mostlyright-data 0.9.0__py3-none-any.whl

mostlyright/data_harness/offline.py

@@ -0,0 +1,2049 @@
+"""Durable local coordinator for the H2 offline vertical slice."""
+
+from __future__ import annotations
+
+import errno
+import os
+import re
+import stat
+import uuid
+from collections.abc import Callable
+from copy import deepcopy
+from dataclasses import dataclass
+from pathlib import Path, PurePosixPath
+from typing import TYPE_CHECKING, Any
+
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
+
+try:
+    import fcntl
+except ImportError:  # pragma: no cover - H2 already fails closed on Windows
+    fcntl = None  # type: ignore[assignment]
+
+from mostlyright.data_harness.canonical import (
+    CanonicalJSONError,
+    canonical_json_bytes,
+    parse_canonical_json,
+    parse_json,
+    sha256_bytes,
+)
+from mostlyright.data_harness.contracts import ContractError, TablePlan, parse_plan
+from mostlyright.data_harness.local_contracts import (
+    GraphTablePlan,
+    LocalQuestion,
+    LocalRequirements,
+    SourceProposal,
+    TableSemantics,
+    parse_question,
+    parse_requirements,
+    parse_source_proposal,
+    parse_table_semantics,
+)
+
+# The underscore-prefixed names below are private to pipeline.py by convention only; this
+# module imports and calls each of them directly, so their signatures have to change
+# together with the call sites here.
+from mostlyright.data_harness.pipeline import (
+    OFFLINE_MANIFEST_VERSION,
+    OFFLINE_SEMANTICS_MANIFEST_VERSION,
+    SOURCE_PROPOSAL_SET_VERSION,
+    BuildError,
+    CandidateInspection,
+    OfflinePackageContext,
+    ResourceLimits,
+    _durability_barrier,
+    _entry_identity,
+    _open_candidate_run_handle,
+    _open_output_parent,
+    _open_source_root,
+    _read_confined_source_from_handle,
+    _remove_tree,
+    _rename_no_replace,
+    _validate_candidate_run_handle,
+    _validate_output_parent_handle,
+    _validate_root_separation,
+    build_candidate,
+    classify_plan_sources_before_persistence,
+    inspect_candidate,
+)
+from mostlyright.data_harness.review import (
+    ReviewResult,
+    _finalize_review,
+    _review_authority_material,
+    _verify_review_decision,
+)
+from mostlyright.data_harness.signing import (
+    TrustedReviewAuthorityProvider,
+    TrustedSigner,
+)
+from mostlyright.data_harness.ux.path_kind import UNKNOWN_KIND, name_of_kind, presence_at
+from mostlyright.data_harness.ux.plain_file import (
+    DANGLING,
+    NOT_PLAIN,
+    TOO_LARGE,
+    PlainFileRefusal,
+    read_plain_file,
+)
+
+if TYPE_CHECKING:
+    from mostlyright.data_harness.visual_run.store import VisualRunStore
+
+_OFFLINE_MANIFEST_VERSIONS = frozenset(
+    {OFFLINE_MANIFEST_VERSION, OFFLINE_SEMANTICS_MANIFEST_VERSION}
+)
+
+RUN_STATE_VERSION = "offline-run-state.v1"
+RUN_RESULT_PATH = "result"
+INPUT_ROOT_PATH = "inputs"
+DEFINITION_PATH = "definitions"
+CONTROL_PATH = ".mr-data"
+WORKSPACE_LOCK_NAME = ".lock"
+# Retain the old private spelling for callers that reached into this module before the workspace
+# control contract had a public lock name. New code must use ``WORKSPACE_LOCK_NAME``.
+_LOCK_NAME = WORKSPACE_LOCK_NAME
+_STATE_NAME = "state.json"
+_DEFINITION_FILES = {
+    "question": "question.json",
+    "requirements": "requirements.json",
+    "source_proposals": "source-proposals.json",
+    "plan": "plan.json",
+}
+_SEMANTICS_DEFINITION = {"semantics": "semantics.json"}
+_TASK_IDS = ("plan", "build", "review")
+_PHASES = frozenset(
+    {
+        "initialized",
+        "planned",
+        "building",
+        "candidate_built",
+        "review_recorded",
+        "failed",
+    }
+)
+_TASK_STATUSES = frozenset({"pending", "running", "completed", "failed"})
+_IDENTIFIER = re.compile(r"^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$")
+_DIGEST = re.compile(r"^[0-9a-f]{64}$")
+_ORPHAN_STAGING = re.compile(r"^\.result\.tmp-[0-9a-f]{32}$")
+_MAX_STATE_BYTES = 8 * 1024 * 1024
+_MAX_DEFINITION_BYTES = 4 * 1024 * 1024
+_H2_PRODUCER_PRINCIPAL = "h2offlinecoordinatorproducer"
+_H2_PRODUCER_ATTEMPT = "h2offlineinitialattempt"
+_PHASE_TASK_STATUSES = {
+    "initialized": ("pending", "pending", "pending"),
+    "planned": ("completed", "pending", "pending"),
+    "building": ("completed", "running", "pending"),
+    "candidate_built": ("completed", "completed", "pending"),
+    "review_recorded": ("completed", "completed", "completed"),
+    "failed": ("completed", "failed", "pending"),
+}
+
+
+def _h2_producer_identity() -> dict[str, str]:
+    return {
+        "principal_id": _H2_PRODUCER_PRINCIPAL,
+        "attempt_id": _H2_PRODUCER_ATTEMPT,
+    }
+
+
+class OfflineRunError(RuntimeError):
+    """A local workspace failed a closed coordinator invariant."""
+
+    def __init__(self, code: str, detail: str) -> None:
+        self.code = code
+        self.detail = detail
+        super().__init__(detail)
+
+
+@dataclass(frozen=True)
+class OfflineInputs:
+    question: LocalQuestion
+    requirements: LocalRequirements
+    source_proposals: tuple[SourceProposal, ...]
+    plan: TablePlan
+    semantics: TableSemantics | None = None
+
+    @property
+    def package_context(self) -> OfflinePackageContext:
+        return OfflinePackageContext(
+            question=self.question,
+            requirements=self.requirements,
+            source_proposals=self.source_proposals,
+            semantics=self.semantics,
+        )
+
+    def definition_values(self) -> dict[str, Any]:
+        values = {
+            "question": self.question.to_dict(),
+            "requirements": self.requirements.to_dict(),
+            "source_proposals": {
+                "schema_version": SOURCE_PROPOSAL_SET_VERSION,
+                "source_proposals": [
+                    item.to_dict()
+                    for item in sorted(self.source_proposals, key=lambda item: item.source_id)
+                ],
+            },
+            "plan": self.plan.to_dict(),
+        }
+        if self.semantics is not None:
+            values["semantics"] = self.semantics.to_dict()
+        return values
+
+
+@dataclass(frozen=True)
+class OfflineExecutionResult:
+    status: str
+    run_id: str
+    candidate: CandidateInspection
+    workspace: Path
+    recovered: bool
+    idempotent: bool
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "status": self.status,
+            "run_id": self.run_id,
+            "workspace": str(self.workspace),
+            "recovered": self.recovered,
+            "idempotent": self.idempotent,
+            "candidate": self.candidate.to_dict(),
+        }
+
+
+@dataclass
+class _Workspace:
+    path: Path
+    run_handle: Any
+    control_fd: int
+    control_identity: tuple[int, int, int]
+    lock_fd: int
+    lock_acquired: bool
+
+    @property
+    def root_fd(self) -> int:
+        return self.run_handle.run_fd
+
+    def validate(self) -> None:
+        _validate_candidate_run_handle(self.run_handle)
+        named = os.stat(CONTROL_PATH, dir_fd=self.root_fd, follow_symlinks=False)
+        opened = os.fstat(self.control_fd)
+        if (
+            not stat.S_ISDIR(named.st_mode)
+            or _entry_identity(named) != self.control_identity
+            or _entry_identity(opened) != self.control_identity
+        ):
+            raise OfflineRunError(
+                "WORKSPACE_RACE",
+                "workspace control directory changed identity",
+            )
+        lock_named = os.stat(WORKSPACE_LOCK_NAME, dir_fd=self.control_fd, follow_symlinks=False)
+        lock_opened = os.fstat(self.lock_fd)
+        if (
+            not stat.S_ISREG(lock_named.st_mode)
+            or lock_named.st_nlink != 1
+            or _stat_signature(lock_named) != _stat_signature(lock_opened)
+        ):
+            raise OfflineRunError("WORKSPACE_RACE", "workspace lock changed identity")
+
+    def close(self) -> None:
+        if self.lock_acquired and fcntl is not None:
+            fcntl.flock(self.lock_fd, fcntl.LOCK_UN)
+        os.close(self.lock_fd)
+        os.close(self.control_fd)
+        self.run_handle.close()
+
+
+def load_offline_inputs(
+    *,
+    question_path: Path,
+    requirements_path: Path,
+    source_proposals_path: Path,
+    plan_path: Path,
+    semantics_path: Path | None = None,
+) -> OfflineInputs:
+    """Load strict JSON definitions and verify their complete H2 relationship."""
+
+    question = parse_question(_read_external_json(question_path, "question"))
+    requirements = parse_requirements(_read_external_json(requirements_path, "requirements"))
+    proposal_set = _read_external_json(source_proposals_path, "source proposals")
+    if not isinstance(proposal_set, dict) or set(proposal_set) != {
+        "schema_version",
+        "source_proposals",
+    }:
+        raise OfflineRunError(
+            "SOURCE_PROPOSAL_SET_INVALID",
+            "source proposal set fields are invalid",
+        )
+    if proposal_set["schema_version"] != SOURCE_PROPOSAL_SET_VERSION:
+        raise OfflineRunError(
+            "SOURCE_PROPOSAL_SET_INVALID",
+            "source proposal set version is unsupported",
+        )
+    proposal_values = proposal_set["source_proposals"]
+    if not isinstance(proposal_values, list):
+        raise OfflineRunError(
+            "SOURCE_PROPOSAL_SET_INVALID",
+            "source_proposals must be an array",
+        )
+    proposals = tuple(parse_source_proposal(item) for item in proposal_values)
+    plan = parse_plan(_read_external_json(plan_path, "plan"))
+    if isinstance(plan, GraphTablePlan):
+        raise OfflineRunError(
+            "GRAPH_OFFLINE_UNSUPPORTED",
+            "local-graph-table-plan.v1 must be executed through an approved Recipe or "
+            "direct plan-check",
+        )
+    semantics = (
+        parse_table_semantics(_read_external_json(semantics_path, "semantics"))
+        if semantics_path is not None
+        else None
+    )
+    inputs = OfflineInputs(
+        question=question,
+        requirements=requirements,
+        source_proposals=proposals,
+        plan=plan,
+        semantics=semantics,
+    )
+    inputs.package_context.validate_for_plan(plan)
+    return inputs
+
+
+def init_workspace(
+    workspace_path: Path,
+    *,
+    run_id: str,
+    input_root: Path,
+    inputs: OfflineInputs,
+    limits: ResourceLimits | None = None,
+) -> dict[str, Any]:
+    """Snapshot two sources and atomically install one resumable local workspace."""
+
+    if isinstance(inputs.plan, GraphTablePlan):
+        raise OfflineRunError(
+            "GRAPH_OFFLINE_UNSUPPORTED",
+            "local-graph-table-plan.v1 must be executed through an approved Recipe or "
+            "direct plan-check",
+        )
+    run_id = _identifier(run_id, "run_id")
+    inputs.package_context.validate_for_plan(inputs.plan)
+    limits = limits or ResourceLimits()
+    workspace = Path(os.path.abspath(os.fspath(workspace_path)))
+    source_handle = _open_source_root(input_root)
+    try:
+        _validate_root_separation(source_handle.path, workspace)
+        source_bytes = {
+            source.source_id: _read_confined_source_from_handle(
+                source_handle,
+                source.path,
+                limits,
+            )
+            for source in inputs.plan.sources
+        }
+    finally:
+        source_handle.close()
+    classify_plan_sources_before_persistence(inputs.plan, source_bytes)
+
+    definition_values = inputs.definition_values()
+    definition_bytes = {
+        name: canonical_json_bytes(value) for name, value in definition_values.items()
+    }
+    definition_sha256s = {name: sha256_bytes(raw) for name, raw in definition_bytes.items()}
+    state = _initial_state(run_id, definition_sha256s)
+    output_parent = _open_output_parent(workspace)
+    staging = workspace.parent / f".{workspace.name}.tmp-{uuid.uuid4().hex}"
+    staging_identity: tuple[int, int, int] | None = None
+    staging_fd = -1
+    installed = False
+    try:
+        _validate_output_parent_handle(output_parent)
+        os.mkdir(staging.name, 0o700, dir_fd=output_parent.parent_fd)
+        staging_named = os.stat(
+            staging.name,
+            dir_fd=output_parent.parent_fd,
+            follow_symlinks=False,
+        )
+        if not stat.S_ISDIR(staging_named.st_mode):
+            raise OfflineRunError("WORKSPACE_INIT_RACE", "workspace staging is not a directory")
+        staging_identity = _entry_identity(staging_named)
+        staging_fd = os.open(
+            staging.name,
+            os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW,
+            dir_fd=output_parent.parent_fd,
+        )
+        if _entry_identity(os.fstat(staging_fd)) != staging_identity:
+            raise OfflineRunError(
+                "WORKSPACE_INIT_RACE",
+                "workspace staging changed identity",
+            )
+        _populate_workspace(
+            staging_fd,
+            definition_bytes=definition_bytes,
+            source_bytes=source_bytes,
+            plan=inputs.plan,
+            state=state,
+        )
+        _validate_output_parent_handle(output_parent)
+        _rename_no_replace(
+            staging,
+            workspace,
+            expected_source_identity=staging_identity,
+            parent_fd=output_parent.parent_fd,
+        )
+        installed = True
+        os.fsync(output_parent.parent_fd)
+        _validate_output_parent_handle(output_parent)
+    except Exception:
+        if staging_identity is not None:
+            _remove_tree(
+                workspace if installed else staging,
+                expected_identity=staging_identity,
+                parent_fd=output_parent.parent_fd,
+            )
+        raise
+    finally:
+        if staging_fd >= 0:
+            os.close(staging_fd)
+        output_parent.close()
+
+    with _open_workspace(workspace) as opened:
+        observed = _read_state(opened)
+        _load_definitions(opened, observed)
+        opened.validate()
+        return _status_payload(observed, workspace)
+
+
+def plan_workspace(workspace_path: Path) -> dict[str, Any]:
+    """Validate the immutable definitions and durably complete the plan task.
+
+    Nothing here authors or edits a plan. The plan JSON is an input that was already sealed
+    into the workspace; this re-verifies it and records the plan task as completed.
+    """
+
+    workspace_path = Path(os.path.abspath(os.fspath(workspace_path)))
+    with _open_workspace(workspace_path) as workspace:
+        state = _read_state(workspace)
+        inputs = _load_definitions(workspace, state)
+        if _task(state, "plan")["status"] != "completed":
+            next_state = deepcopy(state)
+            plan_task = _task(next_state, "plan")
+            plan_task.update(
+                {
+                    "status": "completed",
+                    "attempts": plan_task["attempts"] + 1,
+                    "result_digest": sha256_bytes(canonical_json_bytes(inputs.plan.to_dict())),
+                }
+            )
+            next_state["phase"] = "planned"
+            _append_event(next_state, "plan_validated", "plan")
+            _write_state(workspace, next_state)
+            state = next_state
+        return {
+            "status": "plan_validated",
+            "run_id": state["run_id"],
+            "workspace": str(workspace_path),
+            "question": inputs.question.to_dict(),
+            "requirements": inputs.requirements.to_dict(),
+            "source_proposals": [
+                item.to_dict()
+                for item in sorted(inputs.source_proposals, key=lambda item: item.source_id)
+            ],
+            "plan": inputs.plan.to_dict(),
+            "plan_digest": _task(state, "plan")["result_digest"],
+        }
+
+
+def run_workspace(
+    workspace_path: Path,
+    *,
+    fault_hook: Callable[[str], None] | None = None,
+    visual_store: VisualRunStore | None = None,
+) -> OfflineExecutionResult:
+    """Build using the fixed H2 coordinator-owned producer enrollment."""
+
+    return _execute_workspace_visualized(
+        workspace_path, fault_hook=fault_hook, is_resume=False, visual_store=visual_store
+    )
+
+
+def resume_workspace(
+    workspace_path: Path,
+    *,
+    fault_hook: Callable[[str], None] | None = None,
+    visual_store: VisualRunStore | None = None,
+) -> OfflineExecutionResult:
+    """Resume only with the fixed coordinator-owned H2 producer identity."""
+
+    workspace_path = Path(os.path.abspath(os.fspath(workspace_path)))
+    with _open_workspace(workspace_path) as workspace:
+        state = _read_state(workspace)
+        producer = state["producer"]
+        if producer is None:
+            raise OfflineRunError(
+                "RESUME_NOT_STARTED",
+                "run has no persisted producer identity; invoke run first",
+            )
+    return _execute_workspace_visualized(
+        workspace_path, fault_hook=fault_hook, is_resume=True, visual_store=visual_store
+    )
+
+
+def _execute_workspace_visualized(
+    workspace_path: Path,
+    *,
+    fault_hook: Callable[[str], None] | None,
+    is_resume: bool,
+    visual_store: VisualRunStore | None,
+) -> OfflineExecutionResult:
+    """Include coordinator validation/recovery in one retryable visual attempt."""
+
+    work = None
+    attempt = _H2_PRODUCER_ATTEMPT
+    execution_visual_store = visual_store
+    if visual_store is not None:
+        from mostlyright.data_harness.visual_run.reducer import reduce_events
+        from mostlyright.data_harness.visual_run.sdk import (
+            VisualWork,
+            attempt_event_key,
+            next_attempt_coordinate,
+        )
+
+        work = VisualWork(visual_store, actor="worker")
+        if not visual_store.events():
+            work.start_run(key="offline:run-started")
+        visual_state = reduce_events(visual_store.events())
+        if visual_state.terminal:
+            if visual_state.lifecycle != "completed":
+                raise OfflineRunError(
+                    "VISUAL_RUN_TERMINAL",
+                    "a terminal failed visual run cannot accept a resume",
+                )
+            # The coordinator's existing-result path remains read-only and deterministic.  Its
+            # already-completed visual log is evidence, not a new invocation sink.
+            work = None
+            execution_visual_store = None
+        else:
+            attempt = next_attempt_coordinate(visual_store, "offline", attempt)
+            work.attempt_started(attempt, key=attempt_event_key("offline", attempt, "started"))
+    try:
+        result = _execute_workspace(
+            workspace_path,
+            producer_principal=_H2_PRODUCER_PRINCIPAL,
+            producer_attempt=_H2_PRODUCER_ATTEMPT,
+            fault_hook=fault_hook,
+            is_resume=is_resume,
+            visual_store=execution_visual_store,
+        )
+    except BaseException as exc:
+        if work is not None:
+            from mostlyright.data_harness.visual_run.contracts import TerminalError
+
+            candidate = getattr(exc, "code", "OFFLINE_EXECUTION_FAILED")
+            code = (
+                candidate
+                if isinstance(candidate, str) and re.fullmatch(r"[A-Z][A-Z0-9_]{1,63}", candidate)
+                else "OFFLINE_EXECUTION_FAILED"
+            )
+            work.attempt_failed(
+                attempt,
+                TerminalError(code, f"Offline execution stopped with {code}.", True),
+                key=attempt_event_key("offline", attempt, "failed"),
+            )
+        raise
+    if work is not None:
+        work.attempt_completed(attempt, key=attempt_event_key("offline", attempt, "completed"))
+    return result
+
+
+def status_workspace(
+    workspace_path: Path,
+    *,
+    wait: bool = True,
+) -> dict[str, Any]:
+    """Return coordinator state without accepting caller-asserted review authority.
+
+    ``wait=False`` gives the same reading without queueing behind a build that is holding the
+    folder: it refuses with ``WORKSPACE_BUSY`` instead. That is what a command which only reports
+    wants -- `mr-data preflight` says "check this before you build", and a check that never returns
+    while a build is running is not one. Nothing about the reading is weakened; only the waiting is.
+    """
+
+    return _status_workspace(workspace_path, wait=wait)
+
+
+def _status_enrolled_workspace(
+    workspace_path: Path,
+    *,
+    review_authority_provider: TrustedReviewAuthorityProvider | None,
+) -> dict[str, Any]:
+    """Return reviewed state only through an inherited coordinator session."""
+
+    _authority, assignment, verifier = _review_authority_material(review_authority_provider)
+    return _status_workspace(
+        workspace_path,
+        trusted_verifier_public_key=verifier.public_key(),
+        trusted_assignment_value=assignment,
+    )
+
+
+def _status_workspace(
+    workspace_path: Path,
+    *,
+    trusted_verifier_public_key: Ed25519PublicKey | None = None,
+    trusted_assignment_value: Any | None = None,
+    wait: bool = True,
+) -> dict[str, Any]:
+    """Return the durable coordinator record without overstating review authority."""
+
+    workspace_path = Path(os.path.abspath(os.fspath(workspace_path)))
+    with _open_workspace(workspace_path, wait=wait) as workspace:
+        state = _read_state(workspace)
+        _load_definitions(workspace, state)
+        if state["candidate"] is not None:
+            if not _named_child_exists(workspace.root_fd, RUN_RESULT_PATH):
+                raise OfflineRunError(
+                    "CANDIDATE_MISSING",
+                    "durable state references a missing candidate",
+                )
+            if state["producer"] is None:  # pragma: no cover - state validator enforces this
+                raise OfflineRunError(
+                    "RUN_STATE_INVALID",
+                    "candidate state is missing its producer fence",
+                )
+            _inspect_and_match_state(
+                workspace_path / RUN_RESULT_PATH,
+                state,
+                state["producer"],
+                workspace=workspace,
+            )
+        payload = _status_payload(state, workspace_path)
+        if trusted_verifier_public_key is not None:
+            verified_review = _verify_workspace_review(
+                workspace,
+                state,
+                trusted_verifier_public_key=trusted_verifier_public_key,
+                trusted_assignment_value=trusted_assignment_value,
+            )
+            payload["verified_review"] = {
+                "status": verified_review.status,
+                "candidate_digest": verified_review.candidate_digest,
+                "decision_digest": verified_review.decision_digest,
+            }
+            payload["status"] = verified_review.status
+            payload["review_authority"] = "cryptographically_verified_exact_review"
+        return payload
+
+
+def inspect_workspace(
+    workspace_path: Path,
+) -> dict[str, Any]:
+    """Inspect a candidate without accepting caller-asserted review authority."""
+
+    return _inspect_workspace(workspace_path)
+
+
+def _inspect_enrolled_workspace(
+    workspace_path: Path,
+    *,
+    review_authority_provider: TrustedReviewAuthorityProvider | None,
+) -> dict[str, Any]:
+    """Inspect reviewed state only through an inherited coordinator session."""
+
+    _authority, assignment, verifier = _review_authority_material(review_authority_provider)
+    return _inspect_workspace(
+        workspace_path,
+        trusted_verifier_public_key=verifier.public_key(),
+        trusted_assignment_value=assignment,
+    )
+
+
+def _inspect_workspace(
+    workspace_path: Path,
+    *,
+    trusted_verifier_public_key: Ed25519PublicKey | None = None,
+    trusted_assignment_value: Any | None = None,
+) -> dict[str, Any]:
+    """Return exact replay-verified candidate evidence plus coordinator state."""
+
+    workspace_path = Path(os.path.abspath(os.fspath(workspace_path)))
+    with _open_workspace(workspace_path) as workspace:
+        state = _read_state(workspace)
+        _load_definitions(workspace, state)
+        result_path = workspace_path / state["paths"]["result"]
+        producer = state["producer"]
+        if state["candidate"] is None or producer is None:
+            raise OfflineRunError(
+                "CANDIDATE_NOT_COMMITTED",
+                "workspace has no durably committed candidate to inspect",
+            )
+        inspection, lease = _inspect_and_retain_matched_state(
+            result_path,
+            state,
+            producer,
+            workspace=workspace,
+        )
+        try:
+            payload = {
+                "status": "candidate_inspected",
+                "workspace": str(workspace_path),
+                "run_id": state["run_id"],
+                "state_phase": state["phase"],
+                "candidate": inspection.to_dict(),
+                "review_authority": "not_verified_without_enrolled_verifier_key",
+                "hosted_release": False,
+            }
+            if trusted_verifier_public_key is not None:
+                verified_review = _verify_workspace_review(
+                    workspace,
+                    state,
+                    trusted_verifier_public_key=trusted_verifier_public_key,
+                    trusted_assignment_value=trusted_assignment_value,
+                )
+                if verified_review.candidate_digest != inspection.candidate_digest:
+                    raise OfflineRunError(
+                        "REVIEW_CANDIDATE_MISMATCH",
+                        "verified review does not match the retained candidate snapshot",
+                    )
+                payload["verified_review"] = {
+                    "status": verified_review.status,
+                    "candidate_digest": verified_review.candidate_digest,
+                    "decision_digest": verified_review.decision_digest,
+                }
+                payload["status"] = verified_review.status
+                payload["review_authority"] = "cryptographically_verified_exact_review"
+            lease.validate()
+            _match_candidate_inspection(inspection, state, producer)
+            workspace.validate()
+            lease.validate()
+            return payload
+        finally:
+            lease.close()
+
+
+def workspace_result_path(workspace_path: Path) -> Path:
+    """Resolve the fixed descriptor-validated result child for review/verification."""
+
+    workspace_path = Path(os.path.abspath(os.fspath(workspace_path)))
+    with _open_workspace(workspace_path) as workspace:
+        state = _read_state(workspace)
+        _load_definitions(workspace, state)
+        return workspace_path / state["paths"]["result"]
+
+
+def review_target_path(workspace_path: Path) -> Path:
+    """Resolve the run directory review enrollment acts on: a workspace or a sealed run dir.
+
+    A workspace is marked by its ``.mr-data`` control directory and keeps its run under the
+    recorded result child, resolved through the locked, replayed reader above. Any other path is
+    returned absolutized and unjudged, mirroring the CLI's own run-dir-or-workspace dispatch:
+    every caller hands the result to ``verify_candidate``, which is the gate that decides whether
+    a sealed Build is actually there. Recipe executions seal run directories without any
+    workspace, and review enrollment accepts them exactly the way ``mr-data verify`` and
+    ``mr-data review --local`` already do.
+    """
+
+    absolute = Path(os.path.abspath(os.fspath(workspace_path)))
+    try:
+        control = os.lstat(absolute / CONTROL_PATH)
+    except (FileNotFoundError, NotADirectoryError):
+        return absolute
+    except OSError:
+        return absolute
+    if not stat.S_ISDIR(control.st_mode):
+        return absolute
+    return workspace_result_path(absolute)
+
+
+def recorded_result_path(workspace_path: Path) -> Path:
+    """Where a workspace records its run, for a reading that verifies nothing and must not wait.
+
+    This is not the resolver a command that acts on a run uses. That one is
+    :func:`workspace_result_path`, which takes the durable lock, *waits* for it, and replays the
+    sealed definitions before it answers: exactly right for a command that is about to open,
+    resume, review, or verify the run, and exactly wrong for a listing. A listing walks folders
+    nobody named, says in every row that it verified nothing, and must not stall behind a build
+    that is running in one of them.
+
+    So this one never waits. It takes a shared lock without blocking and refuses with
+    ``WORKSPACE_BUSY`` when a build holds the exclusive one, and it reads the recorded result path
+    out of the run state and nothing else. Nothing is weakened by the shorter reading, because
+    nothing is trusted from it: the value it returns is validated by :func:`_validate_state` to be
+    exactly ``RUN_RESULT_PATH``, and whatever a caller then does with that path goes through the
+    same verified reader every other caller uses.
+    """
+
+    if os.name == "nt" or fcntl is None:
+        raise OfflineRunError(
+            "WORKSPACE_PLATFORM_UNSUPPORTED",
+            "descriptor-relative durable workspaces are unavailable on this platform",
+        )
+    workspace_path = Path(os.path.abspath(os.fspath(workspace_path)))
+    try:
+        control_fd = os.open(
+            workspace_path / CONTROL_PATH,
+            os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW,
+        )
+    except FileNotFoundError as exc:
+        raise OfflineRunError(
+            "WORKSPACE_ABSENT",
+            f"there is {presence_at(workspace_path) or UNKNOWN_KIND} at {workspace_path}, "
+            "and a workbench has to be a folder this harness set up",
+        ) from exc
+    except NotADirectoryError as exc:
+        raise OfflineRunError("WORKSPACE_INVALID", "control path is not a directory") from exc
+    try:
+        state = _read_state_without_waiting(control_fd, workspace_path)
+    finally:
+        os.close(control_fd)
+    return workspace_path / state["paths"]["result"]
+
+
+def _read_state_without_waiting(control_fd: int, workspace_path: Path) -> dict[str, Any]:
+    """The run state, read under a shared lock that is never waited for.
+
+    The shared lock is taken for one reason: a build holds the exclusive one for its whole length,
+    so failing to take this one immediately is how a reader learns a build is running without
+    joining the queue behind it. It is released before anything is parsed, and a build that starts
+    a microsecond later waits on nothing.
+    """
+
+    try:
+        lock_fd = os.open(
+            WORKSPACE_LOCK_NAME,
+            os.O_RDONLY | os.O_NOFOLLOW | getattr(os, "O_CLOEXEC", 0),
+            dir_fd=control_fd,
+        )
+    except FileNotFoundError as exc:
+        raise OfflineRunError(
+            "WORKSPACE_ABSENT",
+            f"there is {presence_at(workspace_path) or UNKNOWN_KIND} at {workspace_path}, "
+            "and a workbench has to be a folder this harness set up",
+        ) from exc
+    try:
+        try:
+            fcntl.flock(lock_fd, fcntl.LOCK_SH | fcntl.LOCK_NB)
+        except OSError as exc:
+            if exc.errno not in (errno.EWOULDBLOCK, errno.EAGAIN, errno.EACCES):
+                raise
+            raise OfflineRunError(
+                "WORKSPACE_BUSY",
+                f"a build is running in {workspace_path}",
+            ) from exc
+        try:
+            raw = _read_regular_file_at(
+                control_fd,
+                _STATE_NAME,
+                maximum=_MAX_STATE_BYTES,
+                required_mode=0o600,
+            )
+        except FileNotFoundError as exc:
+            # The folder was set up but no run was ever recorded in it. That is not a damaged
+            # record; it is the absence of one, and it names a different fix.
+            raise OfflineRunError(
+                "WORKSPACE_ABSENT",
+                f"there is {presence_at(workspace_path) or UNKNOWN_KIND} at {workspace_path}, "
+                "and a workbench has to be a folder this harness set up",
+            ) from exc
+    finally:
+        os.close(lock_fd)
+    try:
+        value = parse_canonical_json(raw)
+    except ValueError as exc:
+        raise OfflineRunError("RUN_STATE_INVALID", "run state is not canonical JSON") from exc
+    return _validate_state(value)
+
+
+def _record_review(
+    workspace_path: Path,
+    *,
+    status: str,
+    candidate_digest: str,
+    decision_digest: str,
+) -> dict[str, Any]:
+    """Record a verified review receipt without making it the verification authority."""
+
+    if status not in {"reviewed_candidate", "fixes_required"}:
+        raise OfflineRunError("REVIEW_STATUS_INVALID", "review status is unsupported in H2")
+    candidate_digest = _digest(candidate_digest, "candidate_digest")
+    decision_digest = _digest(decision_digest, "decision_digest")
+    workspace_path = Path(os.path.abspath(os.fspath(workspace_path)))
+    with _open_workspace(workspace_path) as workspace:
+        state = _read_state(workspace)
+        next_state = _record_review_in_open_workspace(
+            workspace,
+            state,
+            status=status,
+            candidate_digest=candidate_digest,
+            decision_digest=decision_digest,
+        )
+        return _status_payload(next_state, workspace_path)
+
+
+def _finalize_enrolled_workspace_review(
+    workspace_path: Path,
+    *,
+    report_values: list[Any],
+    review_authority_provider: TrustedReviewAuthorityProvider | None,
+) -> ReviewResult:
+    """Finalize workspace review only through an inherited coordinator session."""
+
+    _authority, assignment, verifier = _review_authority_material(review_authority_provider)
+    return _finalize_workspace_review(
+        workspace_path,
+        assignment_value=assignment,
+        report_values=report_values,
+        verifier_private_key=verifier,
+    )
+
+
+def _finalize_workspace_review(
+    workspace_path: Path,
+    *,
+    assignment_value: Any,
+    report_values: list[Any],
+    verifier_private_key: TrustedSigner,
+) -> ReviewResult:
+    """Finalize and record one review against a single retained workspace snapshot."""
+
+    workspace_path = Path(os.path.abspath(os.fspath(workspace_path)))
+    with _open_workspace(workspace_path) as workspace:
+        state = _read_state(workspace)
+        _load_definitions(workspace, state)
+        if state["candidate"] is None:
+            raise OfflineRunError(
+                "CANDIDATE_NOT_COMMITTED",
+                "workspace has no durably committed candidate to review",
+            )
+        result_path = workspace_path / state["paths"]["result"]
+        result = _finalize_review(
+            run_dir=result_path,
+            assignment_value=assignment_value,
+            report_values=report_values,
+            verifier_private_key=verifier_private_key,
+            _run_parent_fd=workspace.root_fd,
+            _transaction_validator=workspace.validate,
+        )
+        if result.candidate_digest != state["candidate"]["candidate_digest"]:
+            raise OfflineRunError(
+                "REVIEW_CANDIDATE_MISMATCH",
+                "review candidate does not match durable run state",
+            )
+        _record_review_in_open_workspace(
+            workspace,
+            state,
+            status=result.status,
+            candidate_digest=result.candidate_digest,
+            decision_digest=result.decision_digest,
+        )
+        workspace.validate()
+        return result
+
+
+def _record_review_in_open_workspace(
+    workspace: _Workspace,
+    state: dict[str, Any],
+    *,
+    status: str,
+    candidate_digest: str,
+    decision_digest: str,
+) -> dict[str, Any]:
+    if status not in {"reviewed_candidate", "fixes_required"}:
+        raise OfflineRunError("REVIEW_STATUS_INVALID", "review status is unsupported in H2")
+    candidate_digest = _digest(candidate_digest, "candidate_digest")
+    decision_digest = _digest(decision_digest, "decision_digest")
+    if state["candidate"] is None or state["candidate"]["candidate_digest"] != candidate_digest:
+        raise OfflineRunError(
+            "REVIEW_CANDIDATE_MISMATCH",
+            "review candidate does not match durable run state",
+        )
+    review_task = _task(state, "review")
+    if (
+        review_task["status"] == "completed"
+        and state["review"] is not None
+        and state["review"]["decision_digest"] == decision_digest
+    ):
+        return state
+    next_state = deepcopy(state)
+    next_review_task = _task(next_state, "review")
+    next_review_task.update(
+        {
+            "status": "completed",
+            "attempts": next_review_task["attempts"] + 1,
+            "result_digest": decision_digest,
+        }
+    )
+    next_state["review"] = {
+        "candidate_digest": candidate_digest,
+        "decision_digest": decision_digest,
+        "verified_status": status,
+    }
+    next_state["phase"] = "review_recorded"
+    _append_event(next_state, "exact_review_recorded", "review")
+    _write_state(workspace, next_state)
+    return next_state
+
+
+def _verify_workspace_review(
+    workspace: _Workspace,
+    state: dict[str, Any],
+    *,
+    trusted_verifier_public_key: Ed25519PublicKey,
+    trusted_assignment_value: Any | None,
+) -> ReviewResult:
+    if state["candidate"] is None:
+        raise OfflineRunError(
+            "CANDIDATE_NOT_COMMITTED",
+            "workspace has no durably committed candidate to verify",
+        )
+    result_path = workspace.path / state["paths"]["result"]
+    result = _verify_review_decision(
+        result_path,
+        trusted_verifier_public_key=trusted_verifier_public_key,
+        trusted_assignment_value=trusted_assignment_value,
+        _run_parent_fd=workspace.root_fd,
+        _ancestor_validator=workspace.validate,
+    )
+    if result.candidate_digest != state["candidate"]["candidate_digest"]:
+        raise OfflineRunError(
+            "REVIEW_CANDIDATE_MISMATCH",
+            "verified review does not match durable run state",
+        )
+    workspace.validate()
+    return result
+
+
+def _execute_workspace(
+    workspace_path: Path,
+    *,
+    producer_principal: str,
+    producer_attempt: str,
+    fault_hook: Callable[[str], None] | None,
+    is_resume: bool,
+    visual_store: VisualRunStore | None = None,
+) -> OfflineExecutionResult:
+    workspace_path = Path(os.path.abspath(os.fspath(workspace_path)))
+    trusted_producer = _h2_producer_identity()
+    if {
+        "principal_id": producer_principal,
+        "attempt_id": producer_attempt,
+    } != trusted_producer:
+        raise OfflineRunError(
+            "PRODUCER_MISMATCH",
+            "offline execution requires the fixed coordinator-owned H2 producer",
+        )
+    with _open_workspace(workspace_path) as workspace:
+        state = _read_state(workspace)
+        inputs = _load_definitions(workspace, state)
+        producer = trusted_producer
+        if state["producer"] is not None and state["producer"] != producer:
+            raise OfflineRunError(
+                "PRODUCER_MISMATCH",
+                "resume/retry must use the persisted producer principal and attempt",
+            )
+        result_path = workspace_path / state["paths"]["result"]
+        if _named_child_exists(workspace.root_fd, RUN_RESULT_PATH):
+            # A process may have died after rename but before the output-parent
+            # barrier. Retry it before adopting or committing an existing result.
+            _durability_barrier(workspace.root_fd, "output-parent")
+            inspection = _inspect_and_match_state(
+                result_path,
+                state,
+                producer,
+                workspace=workspace,
+            )
+            if _task(state, "build")["status"] == "completed":
+                return OfflineExecutionResult(
+                    status="candidate_built",
+                    run_id=state["run_id"],
+                    candidate=inspection,
+                    workspace=workspace_path,
+                    recovered=False,
+                    idempotent=True,
+                )
+            next_state = _candidate_state(
+                state,
+                inspection,
+                producer=producer,
+                event="candidate_recovered",
+            )
+            _write_state(workspace, next_state)
+            return OfflineExecutionResult(
+                status="candidate_built",
+                run_id=next_state["run_id"],
+                candidate=inspection,
+                workspace=workspace_path,
+                recovered=True,
+                idempotent=False,
+            )
+
+        _remove_orphan_staging(workspace)
+        next_state = deepcopy(state)
+        plan_task = _task(next_state, "plan")
+        if plan_task["status"] != "completed":
+            plan_task.update(
+                {
+                    "status": "completed",
+                    "attempts": plan_task["attempts"] + 1,
+                    "result_digest": sha256_bytes(canonical_json_bytes(inputs.plan.to_dict())),
+                }
+            )
+            _append_event(next_state, "plan_validated", "plan")
+        build_task = _task(next_state, "build")
+        build_task.update(
+            {
+                "status": "running",
+                "attempts": build_task["attempts"] + 1,
+                "result_digest": None,
+            }
+        )
+        next_state["phase"] = "building"
+        next_state["producer"] = producer
+        _append_event(next_state, "build_resumed" if is_resume else "build_started", "build")
+        _write_state(workspace, next_state)
+        state = next_state
+        try:
+            build_candidate(
+                inputs.plan,
+                input_root=workspace_path / state["paths"]["input_root"],
+                output_dir=result_path,
+                producer_principal=producer_principal,
+                producer_attempt=producer_attempt,
+                package_context=inputs.package_context,
+                visual_store=visual_store,
+            )
+        except (BuildError, ContractError):
+            failed = deepcopy(state)
+            _task(failed, "build")["status"] = "failed"
+            failed["phase"] = "failed"
+            _append_event(failed, "build_failed", "build")
+            _write_state(workspace, failed)
+            raise
+        if fault_hook is not None:
+            fault_hook("after_candidate_sealed")
+        inspection = _inspect_and_match_state(
+            result_path,
+            state,
+            producer,
+            workspace=workspace,
+        )
+        completed = _candidate_state(
+            state,
+            inspection,
+            producer=producer,
+            event="candidate_built",
+        )
+        _write_state(workspace, completed)
+        return OfflineExecutionResult(
+            status="candidate_built",
+            run_id=completed["run_id"],
+            candidate=inspection,
+            workspace=workspace_path,
+            recovered=False,
+            idempotent=False,
+        )
+
+
+def _candidate_state(
+    state: dict[str, Any],
+    inspection: CandidateInspection,
+    *,
+    producer: dict[str, str],
+    event: str,
+) -> dict[str, Any]:
+    if inspection.manifest_version not in _OFFLINE_MANIFEST_VERSIONS:
+        raise OfflineRunError(
+            "CANDIDATE_VERSION_INVALID",
+            "workspace result is not a complete H2 offline package",
+        )
+    next_state = deepcopy(state)
+    next_state["producer"] = producer
+    next_state["candidate"] = {
+        "candidate_digest": inspection.candidate_digest,
+        "table_sha256": inspection.table_sha256,
+        "manifest_version": inspection.manifest_version,
+        "row_count": inspection.row_count,
+    }
+    next_state["phase"] = "candidate_built"
+    _task(next_state, "build").update(
+        {
+            "status": "completed",
+            "result_digest": inspection.candidate_digest,
+        }
+    )
+    _append_event(next_state, event, "build")
+    return next_state
+
+
+def _inspect_and_match_state(
+    result_path: Path,
+    state: dict[str, Any],
+    producer: dict[str, str],
+    *,
+    workspace: _Workspace | None = None,
+) -> CandidateInspection:
+    inspection, lease = _inspect_and_retain_matched_state(
+        result_path,
+        state,
+        producer,
+        workspace=workspace,
+    )
+    try:
+        return inspection
+    finally:
+        lease.close()
+
+
+def _inspect_and_retain_matched_state(
+    result_path: Path,
+    state: dict[str, Any],
+    producer: dict[str, str],
+    *,
+    workspace: _Workspace | None = None,
+) -> tuple[CandidateInspection, Any]:
+    retained_snapshots: list[Any] = []
+    inspection = inspect_candidate(
+        result_path,
+        _run_parent_fd=workspace.root_fd if workspace is not None else None,
+        _ancestor_validator=workspace.validate if workspace is not None else None,
+        _retained_snapshots=retained_snapshots,
+    )
+    if len(retained_snapshots) != 1:
+        for snapshot in retained_snapshots:
+            snapshot.close()
+        raise OfflineRunError(
+            "CANDIDATE_SNAPSHOT_INVALID",
+            "candidate inspection did not retain its exact bound snapshot",
+        )
+    verified_snapshot = retained_snapshots[0]
+    try:
+        # Deliberate repeat, not a duplicate. The comparison runs once before the workspace
+        # and lease identity checks and once between two rounds of them, so the accepted
+        # comparison is bracketed by identity checks on both sides: a workspace or candidate
+        # root swapped in during either pass fails the surrounding check.
+        _match_candidate_inspection(inspection, state, producer)
+        if workspace is not None:
+            workspace.validate()
+        verified_snapshot.validate()
+        _match_candidate_inspection(inspection, state, producer)
+        if workspace is not None:
+            workspace.validate()
+        verified_snapshot.validate()
+        return inspection, verified_snapshot
+    except Exception:
+        verified_snapshot.close()
+        raise
+
+
+def _match_candidate_inspection(
+    inspection: CandidateInspection,
+    state: dict[str, Any],
+    producer: dict[str, str],
+) -> None:
+    if (
+        inspection.producer_principal != producer["principal_id"]
+        or inspection.producer_attempt != producer["attempt_id"]
+        or inspection.manifest_version not in _OFFLINE_MANIFEST_VERSIONS
+    ):
+        raise OfflineRunError(
+            "CANDIDATE_PRODUCER_MISMATCH",
+            "existing candidate is not the expected H2 producer result",
+        )
+    recorded = state["candidate"]
+    if recorded is not None and (
+        recorded["candidate_digest"] != inspection.candidate_digest
+        or recorded["table_sha256"] != inspection.table_sha256
+        or recorded["row_count"] != inspection.row_count
+    ):
+        raise OfflineRunError(
+            "CANDIDATE_STATE_MISMATCH",
+            "verified candidate does not match durable run state",
+        )
+
+
+def _populate_workspace(
+    staging_fd: int,
+    *,
+    definition_bytes: dict[str, bytes],
+    source_bytes: dict[str, bytes],
+    plan: TablePlan,
+    state: dict[str, Any],
+) -> None:
+    directories: dict[str, int] = {"": staging_fd}
+    opened_fds: list[int] = []
+    try:
+        for path in (CONTROL_PATH, DEFINITION_PATH, INPUT_ROOT_PATH):
+            descriptor = _create_directory_at(staging_fd, path)
+            directories[path] = descriptor
+            opened_fds.append(descriptor)
+        _create_file_at(
+            directories[CONTROL_PATH],
+            WORKSPACE_LOCK_NAME,
+            b"",
+            mode=0o600,
+        )
+        _create_file_at(
+            directories[CONTROL_PATH],
+            _STATE_NAME,
+            canonical_json_bytes(state),
+            mode=0o600,
+        )
+        definition_files = dict(_DEFINITION_FILES)
+        if "semantics" in definition_bytes:
+            definition_files.update(_SEMANTICS_DEFINITION)
+        for logical_name, file_name in definition_files.items():
+            _create_file_at(
+                directories[DEFINITION_PATH],
+                file_name,
+                definition_bytes[logical_name],
+                mode=0o444,
+            )
+        source_by_id = {source.source_id: source for source in plan.sources}
+        for source_id in sorted(source_bytes):
+            source = source_by_id[source_id]
+            parent_fd, newly_opened = _create_relative_parents(
+                directories[INPUT_ROOT_PATH],
+                PurePosixPath(source.path).parts[:-1],
+            )
+            opened_fds.extend(newly_opened)
+            _create_file_at(
+                parent_fd,
+                PurePosixPath(source.path).name,
+                source_bytes[source_id],
+                mode=0o444,
+            )
+        for descriptor in reversed(opened_fds):
+            if descriptor not in {
+                directories[CONTROL_PATH],
+                directories[DEFINITION_PATH],
+                directories[INPUT_ROOT_PATH],
+            }:
+                os.fchmod(descriptor, 0o555)
+                os.fsync(descriptor)
+        os.fchmod(directories[DEFINITION_PATH], 0o555)
+        os.fchmod(directories[INPUT_ROOT_PATH], 0o555)
+        for descriptor in {
+            staging_fd,
+            directories[CONTROL_PATH],
+            directories[DEFINITION_PATH],
+            directories[INPUT_ROOT_PATH],
+        }:
+            os.fsync(descriptor)
+    finally:
+        for descriptor in reversed(opened_fds):
+            os.close(descriptor)
+
+
+def _create_relative_parents(
+    root_fd: int,
+    parts: tuple[str, ...],
+) -> tuple[int, list[int]]:
+    parent_fd = root_fd
+    opened: list[int] = []
+    for part in parts:
+        if part in {"", ".", ".."}:
+            raise OfflineRunError("SOURCE_PATH_INVALID", "source path is not canonical")
+        try:
+            os.mkdir(part, 0o700, dir_fd=parent_fd)
+        except FileExistsError:
+            pass
+        descriptor = os.open(
+            part,
+            os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW,
+            dir_fd=parent_fd,
+        )
+        opened.append(descriptor)
+        parent_fd = descriptor
+    return parent_fd, opened
+
+
+def _create_directory_at(parent_fd: int, name: str) -> int:
+    os.mkdir(name, 0o700, dir_fd=parent_fd)
+    named = os.stat(name, dir_fd=parent_fd, follow_symlinks=False)
+    descriptor = os.open(
+        name,
+        os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW,
+        dir_fd=parent_fd,
+    )
+    opened = os.fstat(descriptor)
+    if not stat.S_ISDIR(named.st_mode) or _entry_identity(named) != _entry_identity(opened):
+        os.close(descriptor)
+        raise OfflineRunError("WORKSPACE_INIT_RACE", f"directory changed identity: {name}")
+    return descriptor
+
+
+def _create_file_at(parent_fd: int, name: str, raw: bytes, *, mode: int) -> None:
+    descriptor = os.open(
+        name,
+        os.O_WRONLY | os.O_CREAT | os.O_EXCL | os.O_NOFOLLOW,
+        0o600,
+        dir_fd=parent_fd,
+    )
+    try:
+        offset = 0
+        while offset < len(raw):
+            written = os.write(descriptor, raw[offset:])
+            if written < 1:
+                raise OfflineRunError("WORKSPACE_WRITE_FAILED", f"write stalled: {name}")
+            offset += written
+        os.fsync(descriptor)
+        os.fchmod(descriptor, mode)
+        os.fsync(descriptor)
+        opened = os.fstat(descriptor)
+        named = os.stat(name, dir_fd=parent_fd, follow_symlinks=False)
+        if (
+            not stat.S_ISREG(opened.st_mode)
+            or opened.st_nlink != 1
+            or _stat_signature(opened) != _stat_signature(named)
+        ):
+            raise OfflineRunError("WORKSPACE_INIT_RACE", f"file changed identity: {name}")
+    finally:
+        os.close(descriptor)
+
+
+class _WorkspaceContext:
+    def __init__(self, workspace: _Workspace) -> None:
+        self.workspace = workspace
+
+    def __enter__(self) -> _Workspace:
+        return self.workspace
+
+    def __exit__(self, _exc_type: Any, _exc: Any, _traceback: Any) -> None:
+        self.workspace.close()
+
+
+def validate_workspace_structure(path: Path) -> None:
+    """Validate a Harness workspace control tree without acquiring its execution lock.
+
+    A successful return proves that the lexical path and its ancestors stayed descriptor-bound,
+    the control directory and single-link ``0600`` lock kept their identities, and one bounded,
+    single-link ``0600`` state file was stable canonical JSON satisfying the current run-state
+    schema. It does not claim the state is current after this function returns, replay immutable
+    definitions, or verify a Build. Callers that need those guarantees must use a locked offline
+    operation instead.
+
+    ``OfflineRunError`` or ``BuildError`` reports a refusal. The function never waits for, takes,
+    or releases the workspace execution lock, so a viewer may use it while a build is running.
+    """
+
+    workspace_path = Path(os.path.abspath(os.fspath(path)))
+    with _open_workspace(workspace_path, acquire_lock=False) as workspace:
+        _read_state(workspace)
+
+
+def _open_workspace(
+    path: Path,
+    *,
+    wait: bool = True,
+    acquire_lock: bool = True,
+) -> _WorkspaceContext:
+    """Open and validate a Workbench folder, optionally under its durable lock.
+
+    ``wait`` is about the lock and nothing else. Every command that acts on a run waits, because
+    joining the queue behind a build is exactly right for a command that is about to change what
+    the build is producing. A command that only *reports* must not wait: a build holds this lock
+    for its whole length, and a reporting command that queues behind one returns no answer at all
+    for as long as the build runs. Nothing else about the reading changes -- the same validation,
+    the same definitions replay, the same candidate match -- so a non-waiting caller is never told
+    less than a waiting one, only told sooner that it could not look.
+
+    ``acquire_lock=False`` is the read-only structural-validation mode used only by
+    :func:`validate_workspace_structure`; in that mode ``wait`` has no effect.
+    """
+
+    if os.name == "nt" or fcntl is None:
+        raise OfflineRunError(
+            "WORKSPACE_PLATFORM_UNSUPPORTED",
+            "descriptor-relative durable workspaces are unavailable on this platform",
+        )
+    run_handle = _open_candidate_run_handle(path)
+    control_fd = -1
+    lock_fd = -1
+    try:
+        try:
+            control_named = os.stat(
+                CONTROL_PATH,
+                dir_fd=run_handle.run_fd,
+                follow_symlinks=False,
+            )
+        except FileNotFoundError as exc:
+            # Pointing a command at a folder that was never initialized is the commonest way to
+            # reach this function, and it is not a fault in the durable record: there is no record.
+            # Letting the raw `FileNotFoundError` out named the control directory -- a path the
+            # caller never typed -- and carried no typed code, so nothing downstream could say what
+            # to do about it.
+            raise OfflineRunError(
+                "WORKSPACE_ABSENT",
+                f"there is {presence_at(path) or UNKNOWN_KIND} at {path}, "
+                "and a workbench has to be a folder this harness set up",
+            ) from exc
+        if not stat.S_ISDIR(control_named.st_mode):
+            raise OfflineRunError("WORKSPACE_INVALID", "control path is not a directory")
+        control_fd = os.open(
+            CONTROL_PATH,
+            os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW | getattr(os, "O_CLOEXEC", 0),
+            dir_fd=run_handle.run_fd,
+        )
+        control_identity = _entry_identity(os.fstat(control_fd))
+        if control_identity != _entry_identity(control_named):
+            raise OfflineRunError("WORKSPACE_RACE", "control path changed identity")
+        lock_fd = os.open(
+            WORKSPACE_LOCK_NAME,
+            os.O_RDWR | os.O_NOFOLLOW | getattr(os, "O_CLOEXEC", 0),
+            dir_fd=control_fd,
+        )
+        lock_info = os.fstat(lock_fd)
+        if (
+            not stat.S_ISREG(lock_info.st_mode)
+            or lock_info.st_nlink != 1
+            or stat.S_IMODE(lock_info.st_mode) != 0o600
+        ):
+            raise OfflineRunError("WORKSPACE_INVALID", "workspace lock is invalid")
+        if acquire_lock:
+            if wait:
+                fcntl.flock(lock_fd, fcntl.LOCK_EX)
+            else:
+                try:
+                    fcntl.flock(lock_fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+                except OSError as exc:
+                    if exc.errno not in (errno.EWOULDBLOCK, errno.EAGAIN, errno.EACCES):
+                        raise
+                    raise OfflineRunError(
+                        "WORKSPACE_BUSY",
+                        f"a build is running in {path}",
+                    ) from exc
+        workspace = _Workspace(
+            path=path,
+            run_handle=run_handle,
+            control_fd=control_fd,
+            control_identity=control_identity,
+            lock_fd=lock_fd,
+            lock_acquired=acquire_lock,
+        )
+        workspace.validate()
+        return _WorkspaceContext(workspace)
+    except Exception:
+        if lock_fd >= 0:
+            os.close(lock_fd)
+        if control_fd >= 0:
+            os.close(control_fd)
+        run_handle.close()
+        raise
+
+
+def _read_state(workspace: _Workspace) -> dict[str, Any]:
+    workspace.validate()
+    raw = _read_regular_file_at(
+        workspace.control_fd,
+        _STATE_NAME,
+        maximum=_MAX_STATE_BYTES,
+        required_mode=0o600,
+    )
+    try:
+        value = parse_canonical_json(raw)
+    except ValueError as exc:
+        raise OfflineRunError("RUN_STATE_INVALID", "run state is not canonical JSON") from exc
+    state = _validate_state(value)
+    workspace.validate()
+    return state
+
+
+def _write_state(workspace: _Workspace, state: dict[str, Any]) -> None:
+    state["revision"] += 1
+    _validate_state(state)
+    raw = canonical_json_bytes(state)
+    temporary = f".state.tmp-{uuid.uuid4().hex}"
+    workspace.validate()
+    try:
+        _create_file_at(workspace.control_fd, temporary, raw, mode=0o600)
+        os.replace(
+            temporary,
+            _STATE_NAME,
+            src_dir_fd=workspace.control_fd,
+            dst_dir_fd=workspace.control_fd,
+        )
+        os.fsync(workspace.control_fd)
+        workspace.validate()
+        observed = _read_state(workspace)
+        if observed != state:
+            raise OfflineRunError(
+                "RUN_STATE_DURABILITY",
+                "atomic run state does not match the committed successor",
+            )
+    except Exception:
+        try:
+            os.unlink(temporary, dir_fd=workspace.control_fd)
+        except FileNotFoundError:
+            pass
+        raise
+
+
+def _load_definitions(workspace: _Workspace, state: dict[str, Any]) -> OfflineInputs:
+    workspace.validate()
+    definitions_fd = os.open(
+        DEFINITION_PATH,
+        os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW,
+        dir_fd=workspace.root_fd,
+    )
+    try:
+        info = os.fstat(definitions_fd)
+        if not stat.S_ISDIR(info.st_mode) or stat.S_IMODE(info.st_mode) != 0o555:
+            raise OfflineRunError("DEFINITIONS_INVALID", "definitions directory is not sealed")
+        definition_files = dict(_DEFINITION_FILES)
+        if "semantics" in state["definition_sha256s"]:
+            definition_files.update(_SEMANTICS_DEFINITION)
+        if set(os.listdir(definitions_fd)) != set(definition_files.values()):
+            raise OfflineRunError("DEFINITIONS_INVALID", "definition member set changed")
+        values: dict[str, Any] = {}
+        for logical_name, file_name in definition_files.items():
+            raw = _read_regular_file_at(
+                definitions_fd,
+                file_name,
+                maximum=_MAX_DEFINITION_BYTES,
+                required_mode=0o444,
+            )
+            if sha256_bytes(raw) != state["definition_sha256s"][logical_name]:
+                raise OfflineRunError(
+                    "DEFINITION_DIGEST_MISMATCH",
+                    f"definition changed: {logical_name}",
+                )
+            try:
+                values[logical_name] = parse_canonical_json(raw)
+            except ValueError as exc:
+                raise OfflineRunError(
+                    "DEFINITIONS_INVALID",
+                    f"definition is not canonical: {logical_name}",
+                ) from exc
+    finally:
+        os.close(definitions_fd)
+    proposal_set = values["source_proposals"]
+    if not isinstance(proposal_set, dict) or set(proposal_set) != {
+        "schema_version",
+        "source_proposals",
+    }:
+        raise OfflineRunError("DEFINITIONS_INVALID", "source proposal set is invalid")
+    if proposal_set["schema_version"] != SOURCE_PROPOSAL_SET_VERSION:
+        raise OfflineRunError("DEFINITIONS_INVALID", "source proposal set version is invalid")
+    inputs = OfflineInputs(
+        question=parse_question(values["question"]),
+        requirements=parse_requirements(values["requirements"]),
+        source_proposals=tuple(
+            parse_source_proposal(item) for item in proposal_set["source_proposals"]
+        ),
+        plan=parse_plan(values["plan"]),
+        semantics=(parse_table_semantics(values["semantics"]) if "semantics" in values else None),
+    )
+    inputs.package_context.validate_for_plan(inputs.plan)
+    workspace.validate()
+    return inputs
+
+
+def _read_regular_file_at(
+    parent_fd: int,
+    name: str,
+    *,
+    maximum: int,
+    required_mode: int,
+) -> bytes:
+    named = os.stat(name, dir_fd=parent_fd, follow_symlinks=False)
+    if (
+        not stat.S_ISREG(named.st_mode)
+        or named.st_nlink != 1
+        or stat.S_IMODE(named.st_mode) != required_mode
+        or named.st_size > maximum
+    ):
+        raise OfflineRunError("WORKSPACE_FILE_INVALID", f"workspace file is invalid: {name}")
+    descriptor = os.open(
+        name,
+        os.O_RDONLY | os.O_NOFOLLOW | getattr(os, "O_CLOEXEC", 0),
+        dir_fd=parent_fd,
+    )
+    try:
+        opened = os.fstat(descriptor)
+        if _stat_signature(opened) != _stat_signature(named):
+            raise OfflineRunError("WORKSPACE_RACE", f"workspace file changed: {name}")
+        raw = bytearray()
+        while True:
+            chunk = os.read(descriptor, min(1024 * 1024, maximum + 1 - len(raw)))
+            if not chunk:
+                break
+            raw.extend(chunk)
+            if len(raw) > maximum:
+                raise OfflineRunError("WORKSPACE_FILE_INVALID", f"workspace file too large: {name}")
+        if len(raw) != opened.st_size or _stat_signature(os.fstat(descriptor)) != _stat_signature(
+            opened
+        ):
+            raise OfflineRunError("WORKSPACE_RACE", f"workspace file changed: {name}")
+    finally:
+        os.close(descriptor)
+    after = os.stat(name, dir_fd=parent_fd, follow_symlinks=False)
+    if _stat_signature(after) != _stat_signature(named):
+        raise OfflineRunError("WORKSPACE_RACE", f"workspace file changed: {name}")
+    return bytes(raw)
+
+
+def _initial_state(run_id: str, definition_sha256s: dict[str, str]) -> dict[str, Any]:
+    state = {
+        "schema_version": RUN_STATE_VERSION,
+        "run_id": run_id,
+        "revision": 0,
+        "phase": "initialized",
+        "paths": {
+            "input_root": INPUT_ROOT_PATH,
+            "result": RUN_RESULT_PATH,
+        },
+        "definition_sha256s": definition_sha256s,
+        "producer": None,
+        "candidate": None,
+        "review": None,
+        "tasks": [
+            {
+                "task_id": task_id,
+                "status": "pending",
+                "attempts": 0,
+                "result_digest": None,
+            }
+            for task_id in _TASK_IDS
+        ],
+        "events": [],
+    }
+    _append_event(state, "run_initialized", None)
+    return _validate_state(state)
+
+
+def _validate_state(value: Any) -> dict[str, Any]:
+    expected = {
+        "schema_version",
+        "run_id",
+        "revision",
+        "phase",
+        "paths",
+        "definition_sha256s",
+        "producer",
+        "candidate",
+        "review",
+        "tasks",
+        "events",
+    }
+    if not isinstance(value, dict) or set(value) != expected:
+        raise OfflineRunError("RUN_STATE_INVALID", "run state fields are invalid")
+    if value["schema_version"] != RUN_STATE_VERSION:
+        raise OfflineRunError("RUN_STATE_INVALID", "run state version is unsupported")
+    _identifier(value["run_id"], "run_id")
+    if type(value["revision"]) is not int or value["revision"] < 0:
+        raise OfflineRunError("RUN_STATE_INVALID", "run revision is invalid")
+    if value["phase"] not in _PHASES:
+        raise OfflineRunError("RUN_STATE_INVALID", "run phase is invalid")
+    if value["paths"] != {"input_root": INPUT_ROOT_PATH, "result": RUN_RESULT_PATH}:
+        raise OfflineRunError("RUN_STATE_INVALID", "run paths are not the closed H2 paths")
+    digests = value["definition_sha256s"]
+    valid_definition_sets = {
+        frozenset(_DEFINITION_FILES),
+        frozenset({*_DEFINITION_FILES, *_SEMANTICS_DEFINITION}),
+    }
+    if not isinstance(digests, dict) or frozenset(digests) not in valid_definition_sets:
+        raise OfflineRunError("RUN_STATE_INVALID", "definition digests are invalid")
+    for name, digest in digests.items():
+        _digest(digest, f"definition_sha256s.{name}")
+    producer = value["producer"]
+    if producer is not None:
+        if not isinstance(producer, dict) or set(producer) != {"principal_id", "attempt_id"}:
+            raise OfflineRunError("RUN_STATE_INVALID", "producer record is invalid")
+        _identifier(producer["principal_id"], "producer.principal_id")
+        _identifier(producer["attempt_id"], "producer.attempt_id")
+        if producer != _h2_producer_identity():
+            raise OfflineRunError(
+                "RUN_STATE_INVALID",
+                "run producer is not the fixed coordinator-owned H2 identity",
+            )
+    candidate = value["candidate"]
+    if candidate is not None:
+        if not isinstance(candidate, dict) or set(candidate) != {
+            "candidate_digest",
+            "table_sha256",
+            "manifest_version",
+            "row_count",
+        }:
+            raise OfflineRunError("RUN_STATE_INVALID", "candidate record is invalid")
+        _digest(candidate["candidate_digest"], "candidate.candidate_digest")
+        _digest(candidate["table_sha256"], "candidate.table_sha256")
+        if candidate["manifest_version"] not in _OFFLINE_MANIFEST_VERSIONS:
+            raise OfflineRunError("RUN_STATE_INVALID", "candidate manifest version is invalid")
+        if type(candidate["row_count"]) is not int or candidate["row_count"] < 1:
+            raise OfflineRunError("RUN_STATE_INVALID", "candidate row count is invalid")
+    review = value["review"]
+    if review is not None:
+        if not isinstance(review, dict) or set(review) != {
+            "candidate_digest",
+            "decision_digest",
+            "verified_status",
+        }:
+            raise OfflineRunError("RUN_STATE_INVALID", "review record is invalid")
+        _digest(review["candidate_digest"], "review.candidate_digest")
+        _digest(review["decision_digest"], "review.decision_digest")
+        if review["verified_status"] not in {"reviewed_candidate", "fixes_required"}:
+            raise OfflineRunError("RUN_STATE_INVALID", "review status is invalid")
+    tasks = value["tasks"]
+    if not isinstance(tasks, list) or len(tasks) != len(_TASK_IDS):
+        raise OfflineRunError("RUN_STATE_INVALID", "run tasks are invalid")
+    for index, task in enumerate(tasks):
+        if not isinstance(task, dict) or set(task) != {
+            "task_id",
+            "status",
+            "attempts",
+            "result_digest",
+        }:
+            raise OfflineRunError("RUN_STATE_INVALID", f"task {index} is invalid")
+        if task["task_id"] != _TASK_IDS[index] or task["status"] not in _TASK_STATUSES:
+            raise OfflineRunError("RUN_STATE_INVALID", f"task {index} identity/status is invalid")
+        if type(task["attempts"]) is not int or task["attempts"] < 0:
+            raise OfflineRunError("RUN_STATE_INVALID", f"task {index} attempts are invalid")
+        if task["result_digest"] is not None:
+            _digest(task["result_digest"], f"tasks[{index}].result_digest")
+        if task["status"] == "pending" and (
+            task["attempts"] != 0 or task["result_digest"] is not None
+        ):
+            raise OfflineRunError(
+                "RUN_STATE_INVALID",
+                f"pending task {index} has execution state",
+            )
+        if task["status"] in {"running", "failed"} and (
+            task["attempts"] < 1 or task["result_digest"] is not None
+        ):
+            raise OfflineRunError(
+                "RUN_STATE_INVALID",
+                f"active task {index} has invalid execution state",
+            )
+        if task["status"] == "completed" and (
+            task["attempts"] < 1 or task["result_digest"] is None
+        ):
+            raise OfflineRunError(
+                "RUN_STATE_INVALID",
+                f"completed task {index} lacks its result",
+            )
+    task_statuses = tuple(task["status"] for task in tasks)
+    if task_statuses != _PHASE_TASK_STATUSES[value["phase"]]:
+        raise OfflineRunError(
+            "RUN_STATE_INVALID",
+            "run phase and task statuses are inconsistent",
+        )
+    events = value["events"]
+    if not isinstance(events, list):
+        raise OfflineRunError("RUN_STATE_INVALID", "events must be an array")
+    for index, event in enumerate(events, start=1):
+        if not isinstance(event, dict) or set(event) != {
+            "sequence",
+            "event",
+            "task_id",
+            "phase",
+        }:
+            raise OfflineRunError("RUN_STATE_INVALID", f"event {index} is invalid")
+        if event["sequence"] != index or event["phase"] not in _PHASES:
+            raise OfflineRunError("RUN_STATE_INVALID", f"event {index} ordering is invalid")
+        _identifier(event["event"], f"events[{index}].event")
+        if event["task_id"] is not None and event["task_id"] not in _TASK_IDS:
+            raise OfflineRunError("RUN_STATE_INVALID", f"event {index} task is invalid")
+    build_task = tasks[_TASK_IDS.index("build")]
+    review_task = tasks[_TASK_IDS.index("review")]
+    producer_required = value["phase"] not in {"initialized", "planned"}
+    if (producer is not None) != producer_required:
+        raise OfflineRunError(
+            "RUN_STATE_INVALID",
+            "run phase and producer enrollment are inconsistent",
+        )
+    candidate_required = value["phase"] in {"candidate_built", "review_recorded"}
+    if (candidate is not None) != candidate_required:
+        raise OfflineRunError(
+            "RUN_STATE_INVALID",
+            "run phase and candidate state are inconsistent",
+        )
+    review_required = value["phase"] == "review_recorded"
+    if (review is not None) != review_required:
+        raise OfflineRunError(
+            "RUN_STATE_INVALID",
+            "run phase and review state are inconsistent",
+        )
+    if candidate is not None and producer is None:
+        raise OfflineRunError(
+            "RUN_STATE_INVALID",
+            "candidate state requires a producer fence",
+        )
+    if build_task["status"] == "completed" and candidate is None:
+        raise OfflineRunError(
+            "RUN_STATE_INVALID",
+            "completed build task requires candidate state",
+        )
+    if value["phase"] in {"candidate_built", "review_recorded"} and candidate is None:
+        raise OfflineRunError(
+            "RUN_STATE_INVALID",
+            "terminal candidate phase requires candidate state",
+        )
+    if candidate is not None and build_task["result_digest"] != candidate["candidate_digest"]:
+        raise OfflineRunError(
+            "RUN_STATE_INVALID",
+            "completed build result does not match candidate state",
+        )
+    if review is not None:
+        if candidate is None or review["candidate_digest"] != candidate["candidate_digest"]:
+            raise OfflineRunError(
+                "RUN_STATE_INVALID",
+                "review record must reference the durable candidate",
+            )
+        if review_task["status"] != "completed":
+            raise OfflineRunError(
+                "RUN_STATE_INVALID",
+                "review record requires a completed review task",
+            )
+    if value["phase"] == "review_recorded" and review is None:
+        raise OfflineRunError(
+            "RUN_STATE_INVALID",
+            "review_recorded phase requires a review record",
+        )
+    if review is not None and review_task["result_digest"] != review["decision_digest"]:
+        raise OfflineRunError(
+            "RUN_STATE_INVALID",
+            "completed review result does not match review state",
+        )
+    return value
+
+
+def _append_event(state: dict[str, Any], event: str, task_id: str | None) -> None:
+    state["events"].append(
+        {
+            "sequence": len(state["events"]) + 1,
+            "event": _identifier(event, "event"),
+            "task_id": task_id,
+            "phase": state["phase"],
+        }
+    )
+
+
+def _task(state: dict[str, Any], task_id: str) -> dict[str, Any]:
+    return state["tasks"][_TASK_IDS.index(task_id)]
+
+
+def _status_payload(state: dict[str, Any], workspace: Path) -> dict[str, Any]:
+    review = state["review"]
+    return {
+        "status": state["phase"],
+        "run_id": state["run_id"],
+        "workspace": str(workspace),
+        "revision": state["revision"],
+        "tasks": deepcopy(state["tasks"]),
+        "events": deepcopy(state["events"]),
+        "candidate": deepcopy(state["candidate"]),
+        "review_record": deepcopy(review),
+        "review_authority": (
+            "record_only_reverify_with_enrolled_public_key"
+            if review is not None
+            else "not_reviewed"
+        ),
+        # The local coordinator cannot authorize hosted release or verify a repaired successor.
+        "hosted_release": False,
+        "successor_repair_closure": False,
+    }
+
+
+def _remove_orphan_staging(workspace: _Workspace) -> None:
+    workspace.validate()
+    for child in os.listdir(workspace.root_fd):
+        if not _ORPHAN_STAGING.fullmatch(child):
+            continue
+        named = os.stat(child, dir_fd=workspace.root_fd, follow_symlinks=False)
+        if stat.S_ISDIR(named.st_mode):
+            _remove_tree(
+                workspace.path / child,
+                expected_identity=_entry_identity(named),
+                parent_fd=workspace.root_fd,
+            )
+    workspace.validate()
+
+
+def _named_child_exists(parent_fd: int, name: str) -> bool:
+    try:
+        os.stat(name, dir_fd=parent_fd, follow_symlinks=False)
+    except FileNotFoundError:
+        return False
+    return True
+
+
+def _read_external_json(path: Path, label: str) -> Any:
+    """One of the four files a job is described in, read strictly.
+
+    Each refusal names the file twice over: by what it is for (`question`, `plan`) and by where it
+    is, because a caller passes four paths on one command line and "one of them is not valid JSON"
+    is not an answer. The strict reader's own detail -- the line and column -- is carried through
+    for the same reason: it is the half that says where to look.
+
+    The read goes through :mod:`ux.plain_file` -- open once, ask the descriptor what it is, read
+    that descriptor under a bound -- because ``path.read_bytes()`` on a path somebody typed is the
+    recurring defect class shared with the authoring, preview, and command-line document readers.
+    Every one of the four paths ``mr-data init`` takes comes through this function, so an unguarded
+    ``--question <a fifo>`` would open the pipe
+    and waited for a writer that never came: no output, no exit, and nothing created. The bound was
+    real but arrived too late -- ``read_bytes`` had already read the whole file before anything
+    measured it -- so a file far past the limit was held in memory to be refused.
+    """
+
+    try:
+        raw = read_plain_file(path, max_bytes=_MAX_DEFINITION_BYTES)
+    except PlainFileRefusal as refusal:
+        if refusal.reason == TOO_LARGE:
+            raise OfflineRunError(
+                "DEFINITION_TOO_LARGE", f"{label} exceeds the byte limit: {path}"
+            ) from None
+        # A pipe, a socket or a device is the one refusal `DEFINITION_UNREADABLE` has no words for:
+        # its remediation says to check the file is there, is a plain file rather than a folder,
+        # and is readable, and all three of those are true of a FIFO nobody is writing to. A folder
+        # and a missing path keep that code, because that is the sentence written for them.
+        if refusal.reason == DANGLING:
+            # A dangling link needs its own refusal: generic readability advice would claim the
+            # named entry is absent or unreadable without identifying the link. The noun comes
+            # from the mode this rule observed.
+            raise OfflineRunError(
+                "DEFINITION_TARGET_DANGLING",
+                f"{label} is at {refusal.path}, which is "
+                f"{name_of_kind(refusal.mode) or UNKNOWN_KIND} "
+                "that leads nowhere",
+            ) from None
+        if refusal.reason == NOT_PLAIN and not stat.S_ISDIR(refusal.mode or 0):
+            raise OfflineRunError(
+                "DEFINITION_TARGET_NOT_A_FILE",
+                f"{label} is not a file: {path}",
+            ) from None
+        raise OfflineRunError("DEFINITION_UNREADABLE", f"{label} cannot be read: {path}") from None
+    except OSError as exc:
+        raise OfflineRunError("DEFINITION_UNREADABLE", f"{label} cannot be read: {path}") from exc
+    try:
+        return parse_json(raw)
+    except CanonicalJSONError as exc:
+        raise OfflineRunError(
+            "DEFINITION_INVALID", f"{label} is not strict JSON ({exc.detail}): {path}"
+        ) from exc
+    except ValueError as exc:
+        raise OfflineRunError("DEFINITION_INVALID", f"{label} is not strict JSON: {path}") from exc
+
+
+def _identifier(value: Any, name: str) -> str:
+    if not isinstance(value, str) or _IDENTIFIER.fullmatch(value) is None:
+        raise OfflineRunError(
+            "IDENTIFIER_INVALID",
+            f"{name} must be a bounded alphanumeric, '-' or '_' identifier",
+        )
+    return value
+
+
+def _digest(value: Any, name: str) -> str:
+    if not isinstance(value, str) or _DIGEST.fullmatch(value) is None:
+        raise OfflineRunError("DIGEST_INVALID", f"{name} must be a lowercase SHA-256")
+    return value
+
+
+def _stat_signature(info: os.stat_result) -> tuple[int, ...]:
+    return (
+        info.st_dev,
+        info.st_ino,
+        info.st_mode,
+        info.st_nlink,
+        info.st_size,
+        info.st_mtime_ns,
+        info.st_ctime_ns,
+    )