mostlyright-data 0.9.0__py3-none-any.whl

mostlyright/data_harness/review.py

@@ -0,0 +1,2533 @@
+"""Signed, exact-candidate local data-agent review envelopes.
+
+One review envelope is the directory ``<run_dir>/review``. It holds
+assignment.json, backlog.json, decision.json, findings.json, and
+reports/<lens>.json for both required lenses. Every member is a sealed mode-0444
+file under a sealed mode-0555 root.
+
+Finalization is one transaction and runs in this order: bind every absolute
+run-directory ancestor by descriptor, take the exclusive publication lock,
+verify the candidate, stage the envelope in a private temporary directory,
+install it with an atomic rename that refuses to replace an existing envelope,
+then re-verify the installed bytes while the staging descriptors and snapshot
+leases are still held. Each step revalidates the bound chain and the lock, so a
+same-UID actor cannot substitute a pathname midway through.
+
+Entry points, in call order: ``_sign_enrolled_report`` signs one reviewer
+report, ``_finalize_enrolled_review`` writes the verifier-signed decision, and
+``verify_enrolled_review_decision`` re-verifies an installed envelope. Each
+resolves its keys through an inherited coordinator session. The unenrolled forms
+take their trust directly instead: ``_finalize_review`` takes the trusted
+assignment and the verifier signer, and ``_verify_review_decision`` takes the
+trusted verifier public key and, optionally, the trusted assignment.
+"""
+
+from __future__ import annotations
+
+import base64
+import ctypes
+import errno
+import json
+import os
+import select
+import stat
+import struct
+import sys
+import uuid
+from dataclasses import dataclass
+from pathlib import Path, PurePosixPath
+from typing import Any
+
+try:
+    import fcntl
+except ImportError:  # pragma: no cover - unavailable on the already-unsupported Windows path
+    fcntl = None  # type: ignore[assignment]
+
+from cryptography.exceptions import InvalidSignature
+from cryptography.hazmat.primitives import serialization
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
+
+from mostlyright.data_harness.canonical import sha256_bytes
+from mostlyright.data_harness.pipeline import (
+    canonical_json_line_bytes,
+    verify_candidate,
+)
+from mostlyright.data_harness.signing import (
+    SignerProviderError,
+    TrustedReviewAuthority,
+    TrustedReviewAuthorityProvider,
+    TrustedSigner,
+    resolve_review_authority,
+)
+
+REPORT_SCHEMA_VERSION = "agent-review.v2"
+ASSIGNMENT_SCHEMA_VERSION = "review-assignment.v1"
+DECISION_SCHEMA_VERSION = "review-decision.v2"
+VERIFIER_VERSION = "local-review-verifier.v2"
+REQUIRED_LENSES = frozenset({"question_source_fit", "transformation_data_quality"})
+_SEVERITIES = frozenset({"blocker", "critical", "high", "medium", "low"})
+_BLOCKING_SEVERITIES = frozenset({"blocker", "critical", "high"})
+_REVIEW_ROOT_MEMBERS = frozenset(
+    {"assignment.json", "backlog.json", "decision.json", "findings.json", "reports"}
+)
+_REVIEW_REPORT_MEMBERS = frozenset(f"{lens}.json" for lens in REQUIRED_LENSES)
+_REVIEW_FILE_PATHS = frozenset(
+    {
+        "assignment.json",
+        "backlog.json",
+        "decision.json",
+        "findings.json",
+        *(f"reports/{name}" for name in _REVIEW_REPORT_MEMBERS),
+    }
+)
+_REVIEW_PUBLICATION_LOCK = ".review.lock"
+_MAX_REVIEW_MEMBER_BYTES = 10 * 1024 * 1024
+# Linux inotify event bits, spelled here because ctypes gives no header constants. Values
+# are from <sys/inotify.h> and are ABI-stable.
+_IN_ATTRIB = 0x00000004
+_IN_DELETE_SELF = 0x00000400
+_IN_MOVE_SELF = 0x00000800
+_IN_UNMOUNT = 0x00002000
+# The mask retained review ancestors are watched under: any attribute change, self-delete,
+# self-move, or unmount. IN_IGNORED and IN_Q_OVERFLOW arrive whatever the mask is set to,
+# so any readable event at all fails the transaction closed.
+_REVIEW_ANCESTOR_WATCH_MASK = _IN_ATTRIB | _IN_DELETE_SELF | _IN_MOVE_SELF | _IN_UNMOUNT
+_SECURE_REVIEW_STAGING_SUPPORTED = (
+    os.name != "nt"
+    and fcntl is not None
+    and bool(getattr(os, "O_DIRECTORY", 0))
+    and bool(getattr(os, "O_NOFOLLOW", 0))
+    and hasattr(os, "fchmod")
+    and os.open in os.supports_dir_fd
+    and os.stat in os.supports_dir_fd
+    and os.mkdir in os.supports_dir_fd
+    and os.stat in os.supports_follow_symlinks
+    and os.listdir in os.supports_fd
+)
+
+
+class ReviewError(RuntimeError):
+    """A review envelope failed authentication or policy validation.
+
+    ``code`` carries no authority: nothing in the review path reads it, and it exists only so the
+    command line can look up the plain sentences that go with a refusal a person can actually hit.
+    It is what a person quotes and what an agent branches on, so every raise site in this module
+    passes one and ``tests/_typed_errors.py`` fails when one does not. It stays optional in the
+    signature because an exception is rebuilt from its message alone when it crosses a process
+    boundary; what is enforced is the raise site, which is where the code is decided.
+
+    The codes are grouped by the document the refusal is about -- ``ASSIGNMENT_``, ``REPORT_``,
+    ``DECISION_``, ``ENVELOPE_``, ``LOCK_``, ``KEY_`` -- and the path-safety refusals reuse the
+    ``CANDIDATE_ANCESTOR_`` codes the rest of the tree already raises for the same class of
+    failure, so one wording answers for both rather than a second one being invented here.
+    """
+
+    def __init__(self, message: str, *, code: str | None = None) -> None:
+        super().__init__(message)
+        self.code = code
+
+
+def _secure_review_staging_supported() -> bool:
+    """Return whether exact descriptor-relative staging primitives are available."""
+
+    return _SECURE_REVIEW_STAGING_SUPPORTED
+
+
+def _secure_review_verification_supported() -> bool:
+    """Return whether review verification can retain an exact directory snapshot."""
+
+    return _SECURE_REVIEW_STAGING_SUPPORTED
+
+
+# inotify directory watches also receive named (len > 0) events for entries INSIDE the
+# watched directory; only unnamed (len == 0) events — IN_ATTRIB/IN_DELETE_SELF/
+# IN_MOVE_SELF/IN_UNMOUNT/IN_IGNORED and queue overflow — describe the watched inode
+# itself, which is the kqueue EVFILT_VNODE semantic this monitor is defined against.
+_INOTIFY_EVENT_HEADER = struct.Struct("iIII")
+
+
+@dataclass
+class _ReviewAncestorMonitor:
+    """Retain kernel move/delete notifications for every bound run ancestor."""
+
+    kind: str
+    resource: Any
+    event_capacity: int
+
+    def poll(self) -> bool:
+        try:
+            if self.kind == "kqueue":
+                return bool(self.resource.control(None, self.event_capacity, 0))
+            while True:
+                try:
+                    payload = os.read(self.resource, 4096)
+                except BlockingIOError:
+                    return False
+                offset = 0
+                while offset + _INOTIFY_EVENT_HEADER.size <= len(payload):
+                    _wd, _mask, _cookie, name_length = _INOTIFY_EVENT_HEADER.unpack_from(
+                        payload, offset
+                    )
+                    if name_length == 0:
+                        return True
+                    offset += _INOTIFY_EVENT_HEADER.size + name_length
+        except OSError as exc:
+            raise ReviewError(
+                "review run ancestor monitor became unavailable", code="CANDIDATE_ANCESTOR_RACE"
+            ) from exc
+
+    def close(self) -> None:
+        if self.kind == "kqueue":
+            self.resource.close()
+        else:
+            os.close(self.resource)
+
+
+# One retained ancestor of the run directory: descriptor, parent_fd, name, entry identity
+# (st_dev, st_ino, st_nlink), and a human label used in refusal messages. The
+# filesystem-anchor record carries no parent_fd and no name, so revalidation checks it by
+# descriptor only. pipeline.py retains the same shape on its own run handle; the two must
+# change together.
+_RetainedAncestorRecord = tuple[int, int | None, str | None, tuple[int, int, int], str]
+
+
+@dataclass
+class _ReviewRunHandle:
+    """One retained absolute run-directory chain for a complete review transaction."""
+
+    run_dir: Path
+    descriptors: list[int]
+    records: list[_RetainedAncestorRecord]
+    monitor: _ReviewAncestorMonitor
+
+    @property
+    def run_fd(self) -> int:
+        return self.descriptors[-1]
+
+    def close(self) -> None:
+        self.monitor.close()
+        for descriptor in reversed(self.descriptors):
+            os.close(descriptor)
+        self.descriptors.clear()
+
+
+@dataclass
+class _ReviewPublicationLock:
+    """One descriptor-bound exclusive publication lock retained through verification."""
+
+    handle: _ReviewRunHandle
+    descriptor: int
+    lock_stat: os.stat_result
+
+    def validate(self) -> None:
+        _validate_review_run_handle(self.handle)
+        opened = os.fstat(self.descriptor)
+        _require_stable_stat(self.lock_stat, opened, "review publication lock")
+        _require_review_publication_lock(opened)
+        named = os.stat(
+            _REVIEW_PUBLICATION_LOCK,
+            dir_fd=self.handle.run_fd,
+            follow_symlinks=False,
+        )
+        _require_stable_stat(self.lock_stat, named, "review publication lock")
+        _require_review_publication_lock(named)
+
+    def close(self) -> None:
+        if fcntl is not None:
+            fcntl.flock(self.descriptor, fcntl.LOCK_UN)
+        os.close(self.descriptor)
+
+
+@dataclass
+class _ReviewSnapshotLease:
+    """Retain the exact review child root through the result linearization point."""
+
+    handle: _ReviewRunHandle
+    review_fd: int
+    review_stat: os.stat_result
+    owns_review_fd: bool
+
+    def validate(self) -> None:
+        _validate_review_run_handle(self.handle)
+        _require_stable_stat(
+            self.review_stat,
+            os.fstat(self.review_fd),
+            "review root",
+        )
+        named = os.stat(
+            "review",
+            dir_fd=self.handle.run_fd,
+            follow_symlinks=False,
+        )
+        _require_stable_stat(self.review_stat, named, "review root")
+
+    def close(self) -> None:
+        if self.owns_review_fd:
+            os.close(self.review_fd)
+
+
+@dataclass(frozen=True)
+class ReviewResult:
+    """Authenticated outcome of one review envelope.
+
+    status is exactly one of two values. It is "fixes_required" when any finding
+    has severity blocker, critical, or high, and "reviewed_candidate" otherwise.
+    candidate_digest names the exact reviewed candidate. decision_digest is the
+    SHA-256 of the canonical decision payload; the verifier signs that payload
+    with this digest appended. review_dir is the installed envelope directory.
+    """
+
+    status: str
+    candidate_digest: str
+    decision_digest: str
+    review_dir: Path
+    decision_document: dict[str, Any]
+
+
+def public_key_to_base64(public_key: Ed25519PublicKey) -> str:
+    raw = public_key.public_bytes(
+        serialization.Encoding.Raw,
+        serialization.PublicFormat.Raw,
+    )
+    return base64.b64encode(raw).decode("ascii")
+
+
+def load_public_key_base64(value: str) -> Ed25519PublicKey:
+    try:
+        raw = base64.b64decode(value, validate=True)
+        return Ed25519PublicKey.from_public_bytes(raw)
+    except (ValueError, TypeError) as exc:
+        raise ReviewError("invalid Ed25519 public key", code="KEY_INVALID") from exc
+
+
+def _trusted_authority_signer(value: Any, role: str) -> TrustedSigner:
+    if not callable(getattr(value, "sign", None)) or not callable(
+        getattr(value, "public_key", None)
+    ):
+        raise SignerProviderError(f"trusted review authority returned an invalid {role} signer")
+    return value
+
+
+def _review_authority_material(
+    provider: TrustedReviewAuthorityProvider | None,
+) -> tuple[TrustedReviewAuthority, Any, TrustedSigner]:
+    authority = resolve_review_authority(provider)
+    try:
+        assignment = authority.assignment_value()
+        verifier = _trusted_authority_signer(authority.verifier_signer(), "verifier")
+    except (ReviewError, SignerProviderError):
+        raise
+    except Exception as exc:
+        raise SignerProviderError(
+            "trusted review authority could not provide its enrollment"
+        ) from exc
+    return authority, assignment, verifier
+
+
+def _sign_report(payload: Any, private_key: TrustedSigner) -> dict[str, Any]:
+    """Internal primitive: validate and sign one already-authorized report payload."""
+
+    normalized = _parse_report_payload(payload)
+    signature = private_key.sign(canonical_json_line_bytes(normalized))
+    return {**normalized, "signature": base64.b64encode(signature).decode("ascii")}
+
+
+def _sign_assigned_report(
+    payload: Any,
+    *,
+    trusted_assignment_value: Any,
+    reviewer_signer: TrustedSigner,
+) -> dict[str, Any]:
+    """Sign only when a trusted enrollment authorizes this exact report identity."""
+
+    assignment = _parse_assignment(trusted_assignment_value)
+    normalized = _parse_report_payload(payload)
+    reviewer = next(
+        (
+            item
+            for item in assignment["reviewers"]
+            if item["attempt_id"] == normalized["reviewer_attempt"]
+        ),
+        None,
+    )
+    if reviewer is None:
+        raise ReviewError(
+            "report reviewer attempt is not enrolled by the trusted authority",
+            code="ASSIGNMENT_ATTEMPT_NOT_ENROLLED",
+        )
+    expected = {
+        "assignment_digest": _normalized_assignment_digest(assignment),
+        "candidate_digest": assignment["candidate_digest"],
+        "validation_policy_digest": assignment["validation_policy_digest"],
+        "cycle_lineage": assignment["cycle_lineage"],
+        "failed_cycle_count": assignment["failed_cycle_count"],
+        "reviewer_principal": reviewer["principal_id"],
+        "reviewer_attempt": reviewer["attempt_id"],
+        "reviewer_key_id": reviewer["key_id"],
+        "lens": reviewer["lens"],
+    }
+    for field, value in expected.items():
+        if normalized[field] != value:
+            raise ReviewError(
+                f"report {field} is not authorized by the trusted assignment",
+                code="ASSIGNMENT_FIELD_UNAUTHORIZED",
+            )
+    if public_key_to_base64(reviewer_signer.public_key()) != reviewer["public_key"]:
+        raise ReviewError(
+            "reviewer signer does not match the trusted assignment enrollment",
+            code="ASSIGNMENT_SIGNER_MISMATCH",
+        )
+    return _sign_report(normalized, reviewer_signer)
+
+
+def _sign_enrolled_report(
+    payload: Any,
+    *,
+    review_authority_provider: TrustedReviewAuthorityProvider | None,
+) -> dict[str, Any]:
+    """Sign one report only through an inherited coordinator session."""
+
+    authority = resolve_review_authority(review_authority_provider)
+    try:
+        assignment = authority.assignment_value()
+    except (ReviewError, SignerProviderError):
+        raise
+    except Exception as exc:
+        raise SignerProviderError(
+            "trusted review authority could not provide its enrollment"
+        ) from exc
+    normalized = _parse_report_payload(payload)
+    try:
+        signer = _trusted_authority_signer(
+            authority.reviewer_signer_for(normalized["reviewer_attempt"]),
+            "reviewer",
+        )
+    except (ReviewError, SignerProviderError):
+        raise
+    except Exception as exc:
+        raise SignerProviderError(
+            "trusted review authority could not resolve the reviewer enrollment"
+        ) from exc
+    return _sign_assigned_report(
+        normalized,
+        trusted_assignment_value=assignment,
+        reviewer_signer=signer,
+    )
+
+
+def _finalize_enrolled_review(
+    *,
+    run_dir: Path,
+    report_values: list[Any],
+    review_authority_provider: TrustedReviewAuthorityProvider | None,
+) -> ReviewResult:
+    """Finalize one review only through an inherited coordinator session."""
+
+    _authority, assignment, verifier = _review_authority_material(review_authority_provider)
+    return _finalize_review(
+        run_dir=run_dir,
+        assignment_value=assignment,
+        report_values=report_values,
+        verifier_private_key=verifier,
+    )
+
+
+def _finalize_review(
+    *,
+    run_dir: Path,
+    assignment_value: Any,
+    report_values: list[Any],
+    verifier_private_key: TrustedSigner,
+    _run_parent_fd: int | None = None,
+    _transaction_validator: Any | None = None,
+) -> ReviewResult:
+    """Authenticate two reports and write one immutable verifier-signed decision envelope."""
+
+    if not _secure_review_staging_supported():
+        raise ReviewError(
+            "secure descriptor-relative review staging is unavailable on this platform",
+            code="PLATFORM_REVIEW_STAGING_UNSUPPORTED",
+        )
+    handle = (
+        _open_review_run_handle(run_dir)
+        if _run_parent_fd is None
+        else _open_review_run_handle_from_parent(run_dir, _run_parent_fd)
+    )
+    publication_lock: _ReviewPublicationLock | None = None
+    staging_name = f".review.tmp-{uuid.uuid4().hex}"
+    staging_fd = -1
+    renamed = False
+    installed_identity_owned = False
+    installation_durability_confirmed = False
+    staging_identity: tuple[int, int, int] | None = None
+    verification_leases: list[Any] = []
+    try:
+        publication_lock = _acquire_review_publication_lock(handle)
+
+        def validate_transaction() -> None:
+            if publication_lock is None:  # pragma: no cover - developer invariant
+                raise ReviewError("review publication lock is unavailable", code="LOCK_UNAVAILABLE")
+            if _transaction_validator is not None:
+                _transaction_validator()
+            publication_lock.validate()
+
+        verified_candidate = verify_candidate(
+            handle.run_dir,
+            _run_fd=handle.run_fd,
+            _ancestor_validator=validate_transaction,
+        )
+        validate_transaction()
+        assignment = _parse_assignment(assignment_value)
+        _validate_assignment_against_candidate(assignment, verified_candidate)
+        verifier_public = verifier_private_key.public_key()
+        if public_key_to_base64(verifier_public) != assignment["verifier"]["public_key"]:
+            raise ReviewError(
+                "verifier private key does not match the enrolled assignment key",
+                code="ASSIGNMENT_VERIFIER_KEY_MISMATCH",
+            )
+
+        reports = [_parse_signed_report(value) for value in report_values]
+        if len(reports) != 2:
+            raise ReviewError("exactly two signed review reports are required", code="REPORT_COUNT")
+        assignments_by_lens = {item["lens"]: item for item in assignment["reviewers"]}
+        reports_by_lens: dict[str, dict[str, Any]] = {}
+        for report in reports:
+            lens = report["lens"]
+            if lens in reports_by_lens:
+                raise ReviewError(f"duplicate report lens: {lens}", code="REPORT_LENS_DUPLICATE")
+            expected = assignments_by_lens.get(lens)
+            if expected is None:
+                raise ReviewError(
+                    f"report lens is not assigned: {lens}", code="REPORT_LENS_UNASSIGNED"
+                )
+            _verify_report(report, expected, verified_candidate, assignment)
+            reports_by_lens[lens] = report
+        if set(reports_by_lens) != REQUIRED_LENSES:
+            raise ReviewError(
+                "both required review lenses must be present", code="REPORT_LENSES_INCOMPLETE"
+            )
+
+        findings = _normalize_findings(reports_by_lens)
+        backlog = [finding for finding in findings if finding["severity"] in {"medium", "low"}]
+        status = _derive_review_status(findings, assignment["failed_cycle_count"])
+        expected_decision_digest = _expected_review_decision_digest(
+            assignment=assignment,
+            reports_by_lens=reports_by_lens,
+            findings=findings,
+            backlog=backlog,
+            status=status,
+            verified_candidate=verified_candidate,
+        )
+
+        try:
+            os.stat("review", dir_fd=handle.run_fd, follow_symlinks=False)
+        except FileNotFoundError:
+            pass
+        else:
+            _ensure_installed_review_durable(handle)
+            verified = _verify_review_decision(
+                handle.run_dir,
+                trusted_verifier_public_key=verifier_public,
+                trusted_assignment_value=assignment,
+                _run_handle=handle,
+                _transaction_validator=validate_transaction,
+            )
+            if verified.decision_digest != expected_decision_digest or verified.status != status:
+                raise ReviewError(
+                    "existing review envelope does not match this finalization request",
+                    code="ENVELOPE_MISMATCH",
+                )
+            validate_transaction()
+            return verified
+        os.mkdir(staging_name, mode=0o700, dir_fd=handle.run_fd)
+        created_staging = os.stat(
+            staging_name,
+            dir_fd=handle.run_fd,
+            follow_symlinks=False,
+        )
+        if not stat.S_ISDIR(created_staging.st_mode):
+            raise ReviewError(
+                "review staging root is not a directory", code="ENVELOPE_STAGING_ROOT_INVALID"
+            )
+        staging_identity = _entry_identity(created_staging)
+        directory_flags = os.O_RDONLY | getattr(os, "O_DIRECTORY", 0) | getattr(os, "O_NOFOLLOW", 0)
+        staging_fd = os.open(staging_name, directory_flags, dir_fd=handle.run_fd)
+        _require_same_identity(created_staging, os.fstat(staging_fd), "review staging root")
+        decision_digest = _stage_review_envelope(
+            staging_fd,
+            parent_fd=handle.run_fd,
+            staging_name=staging_name,
+            expected_root_identity=staging_identity,
+            assignment=assignment,
+            reports_by_lens=reports_by_lens,
+            findings=findings,
+            backlog=backlog,
+            status=status,
+            verified_candidate=verified_candidate,
+            verifier_private_key=verifier_private_key,
+        )
+        validate_transaction()
+        try:
+            _rename_no_replace(
+                handle.run_dir / staging_name,
+                handle.run_dir / "review",
+                expected_source_identity=staging_identity,
+                installed_mode=0o555,
+                parent_fd=handle.run_fd,
+                source_fd=staging_fd,
+            )
+        except FileExistsError as exc:
+            raise ReviewError(
+                "review envelope already exists and cannot be overwritten", code="ENVELOPE_EXISTS"
+            ) from exc
+        except Exception:
+            installed_identity_owned = _named_entry_has_identity(
+                handle.run_fd,
+                "review",
+                staging_identity,
+            )
+            raise
+        renamed = True
+        installed_identity_owned = True
+        _ensure_installed_review_durable(handle, retained_review_fd=staging_fd)
+        installation_durability_confirmed = True
+        validate_transaction()
+        verified = _verify_review_decision(
+            handle.run_dir,
+            trusted_verifier_public_key=verifier_public,
+            trusted_assignment_value=assignment,
+            _run_handle=handle,
+            _retained_review_fd=staging_fd,
+            _expected_review_identity=staging_identity,
+            _retained_snapshot_leases=verification_leases,
+            _transaction_validator=validate_transaction,
+        )
+        if (
+            decision_digest != expected_decision_digest
+            or verified.decision_digest != expected_decision_digest
+            or verified.status != status
+        ):
+            raise ReviewError(
+                "installed review did not verify as the finalized decision",
+                code="DECISION_NOT_VERIFIED",
+            )
+        for lease in verification_leases:
+            lease.validate()
+        validate_transaction()
+        result = verified
+        for lease in verification_leases:
+            lease.validate()
+        return result
+    except Exception:
+        if staging_identity is not None:
+            _remove_at(
+                handle.run_fd,
+                staging_name,
+                expected_identity=staging_identity,
+            )
+        if (renamed or installed_identity_owned) and installation_durability_confirmed:
+            _remove_at(
+                handle.run_fd,
+                "review",
+                expected_identity=staging_identity,
+            )
+        raise
+    finally:
+        for lease in reversed(verification_leases):
+            lease.close()
+        if staging_fd >= 0:
+            os.close(staging_fd)
+        if publication_lock is not None:
+            publication_lock.close()
+        handle.close()
+
+
+def verify_enrolled_review_decision(
+    run_dir: Path,
+    *,
+    review_authority_provider: TrustedReviewAuthorityProvider | None,
+) -> ReviewResult:
+    """Verify one installed review only through an inherited coordinator session.
+
+    This is the read-only promotion gate for callers such as deployment planning. It deliberately
+    accepts a provider rather than raw keys or assignments, so an ordinary caller cannot downgrade
+    protected review authority into caller-authored trust material.
+    """
+
+    _authority, assignment, verifier = _review_authority_material(review_authority_provider)
+    return _verify_review_decision(
+        run_dir,
+        trusted_verifier_public_key=verifier.public_key(),
+        trusted_assignment_value=assignment,
+    )
+
+
+def _verify_review_decision(
+    run_dir: Path,
+    *,
+    trusted_verifier_public_key: Ed25519PublicKey,
+    trusted_assignment_value: Any | None = None,
+    _run_parent_fd: int | None = None,
+    _ancestor_validator: Any | None = None,
+    _run_handle: _ReviewRunHandle | None = None,
+    _retained_review_fd: int | None = None,
+    _expected_review_identity: tuple[int, int, int] | None = None,
+    _retained_snapshot_leases: list[Any] | None = None,
+    _transaction_validator: Any | None = None,
+) -> ReviewResult:
+    """Return authoritative status/digest evidence at a bound-snapshot linearization.
+
+    The result remains the evidence if a same-UID actor mutates the pathnames after
+    the final no-write observation.
+
+    The two revalidation callbacks are not interchangeable. _transaction_validator
+    revalidates the whole enclosing transaction, including the publication lock a
+    finalizer holds. _ancestor_validator revalidates only the caller's outer
+    ancestors, so it is accepted alone and wrapped with this function's own
+    run-handle check.
+    """
+
+    if not _secure_review_verification_supported():
+        raise ReviewError(
+            "secure descriptor-relative review verification is unavailable on this platform",
+            code="PLATFORM_REVIEW_VERIFY_UNSUPPORTED",
+        )
+    owned_handle = _run_handle is None
+    handle = _run_handle or (
+        _open_review_run_handle(run_dir)
+        if _run_parent_fd is None
+        else _open_review_run_handle_from_parent(run_dir, _run_parent_fd)
+    )
+    transaction_validator = _transaction_validator
+    if transaction_validator is None and _ancestor_validator is not None:
+
+        def transaction_validator() -> None:
+            _ancestor_validator()
+            _validate_review_run_handle(handle)
+
+    try:
+        return _verify_review_decision_with_handle(
+            handle,
+            trusted_verifier_public_key=trusted_verifier_public_key,
+            trusted_assignment_value=trusted_assignment_value,
+            retained_review_fd=_retained_review_fd,
+            expected_review_identity=_expected_review_identity,
+            retained_snapshot_leases=_retained_snapshot_leases,
+            transaction_validator=transaction_validator,
+        )
+    finally:
+        if owned_handle:
+            handle.close()
+
+
+def _verify_review_decision_with_handle(
+    handle: _ReviewRunHandle,
+    *,
+    trusted_verifier_public_key: Ed25519PublicKey,
+    trusted_assignment_value: Any | None,
+    retained_review_fd: int | None,
+    expected_review_identity: tuple[int, int, int] | None,
+    retained_snapshot_leases: list[Any] | None,
+    transaction_validator: Any | None,
+) -> ReviewResult:
+    """Verify one review from an already-bound absolute run-directory chain."""
+
+    validate_transaction = transaction_validator or (lambda: _validate_review_run_handle(handle))
+    validate_transaction()
+    candidate_leases: list[Any] = []
+    verified_candidate = verify_candidate(
+        handle.run_dir,
+        _run_fd=handle.run_fd,
+        _ancestor_validator=validate_transaction,
+        _retained_leases=candidate_leases,
+    )
+    if len(candidate_leases) != 1:
+        for lease in candidate_leases:
+            lease.close()
+        raise ReviewError(
+            "candidate verification did not retain its exact snapshot",
+            code="DECISION_SNAPSHOT_MISSING",
+        )
+    candidate_lease = candidate_leases[0]
+    review_lease: _ReviewSnapshotLease | None = None
+    try:
+        validate_transaction()
+        envelope, review_lease = _read_sealed_review_tree(
+            handle,
+            retained_review_fd=retained_review_fd,
+            expected_review_identity=expected_review_identity,
+        )
+        result = _verify_review_snapshot(
+            handle=handle,
+            verified_candidate=verified_candidate,
+            envelope=envelope,
+            trusted_verifier_public_key=trusted_verifier_public_key,
+            trusted_assignment_value=trusted_assignment_value,
+        )
+        candidate_lease.validate()
+        review_lease.validate()
+        validate_transaction()
+        if retained_snapshot_leases is not None:
+            retained_snapshot_leases.extend([candidate_lease, review_lease])
+            return result
+        review_lease.close()
+        candidate_lease.close()
+        return result
+    except Exception:
+        if review_lease is not None:
+            review_lease.close()
+        candidate_lease.close()
+        raise
+
+
+def _verify_review_snapshot(
+    *,
+    handle: _ReviewRunHandle,
+    verified_candidate: Any,
+    envelope: dict[str, bytes],
+    trusted_verifier_public_key: Ed25519PublicKey,
+    trusted_assignment_value: Any | None,
+) -> ReviewResult:
+    """Authenticate one retained candidate/review byte snapshot."""
+
+    review_dir = handle.run_dir / "review"
+    assignment = _decode_json(envelope["assignment.json"], "assignment")
+    assignment = _parse_assignment(assignment)
+    if trusted_assignment_value is not None:
+        trusted_assignment = _parse_assignment(trusted_assignment_value)
+        if canonical_json_line_bytes(assignment) != canonical_json_line_bytes(trusted_assignment):
+            raise ReviewError(
+                "review assignment is not the trusted coordinator enrollment",
+                code="ASSIGNMENT_NOT_ENROLLED",
+            )
+    if assignment["verifier"]["public_key"] != public_key_to_base64(trusted_verifier_public_key):
+        raise ReviewError(
+            "review verifier is not the trusted enrolled key",
+            code="ASSIGNMENT_VERIFIER_NOT_ENROLLED",
+        )
+    _validate_assignment_against_candidate(assignment, verified_candidate)
+
+    reports_by_lens = {
+        lens: _parse_signed_report(_decode_json(envelope[f"reports/{lens}.json"], f"report {lens}"))
+        for lens in REQUIRED_LENSES
+    }
+    assignments_by_lens = {item["lens"]: item for item in assignment["reviewers"]}
+    for lens, report in reports_by_lens.items():
+        _verify_report(report, assignments_by_lens[lens], verified_candidate, assignment)
+    expected_findings = _normalize_findings(reports_by_lens)
+    findings = _decode_json(envelope["findings.json"], "findings")
+    if findings != expected_findings:
+        raise ReviewError("normalized findings were changed", code="DECISION_FINDINGS_CHANGED")
+    expected_backlog = [
+        finding for finding in expected_findings if finding["severity"] in {"medium", "low"}
+    ]
+    backlog = _decode_json(envelope["backlog.json"], "backlog")
+    if backlog != expected_backlog:
+        raise ReviewError("review backlog was changed", code="DECISION_BACKLOG_CHANGED")
+
+    decision = _decode_json(envelope["decision.json"], "decision")
+    if not isinstance(decision, dict) or set(decision) != {
+        "schema_version",
+        "candidate_digest",
+        "table_sha256",
+        "validation_policy_digest",
+        "assignment_sha256",
+        "report_sha256s",
+        "findings_sha256",
+        "backlog_sha256",
+        "cycle_lineage",
+        "failed_cycle_count",
+        "verifier_version",
+        "verifier_principal",
+        "status",
+        "decision_digest",
+        "signature",
+    }:
+        raise ReviewError("review decision fields are invalid", code="DECISION_FIELDS_INVALID")
+    signed_body = {key: value for key, value in decision.items() if key != "signature"}
+    payload = {key: value for key, value in signed_body.items() if key != "decision_digest"}
+    if decision["decision_digest"] != sha256_bytes(canonical_json_line_bytes(payload)):
+        raise ReviewError("review decision digest is invalid", code="DECISION_DIGEST_INVALID")
+    expected_hashes = {
+        "assignment_sha256": sha256_bytes(envelope["assignment.json"]),
+        "report_sha256s": {
+            lens: sha256_bytes(envelope[f"reports/{lens}.json"]) for lens in sorted(REQUIRED_LENSES)
+        },
+        "findings_sha256": sha256_bytes(envelope["findings.json"]),
+        "backlog_sha256": sha256_bytes(envelope["backlog.json"]),
+    }
+    for field, expected in expected_hashes.items():
+        if decision[field] != expected:
+            raise ReviewError(
+                f"review decision {field} does not match its envelope",
+                code="DECISION_FIELD_MISMATCH",
+            )
+    expected_status = _derive_review_status(findings, assignment["failed_cycle_count"])
+    expected_payload_values = {
+        "schema_version": DECISION_SCHEMA_VERSION,
+        "candidate_digest": verified_candidate.candidate_digest,
+        "table_sha256": verified_candidate.table_sha256,
+        "validation_policy_digest": verified_candidate.validation_policy_digest,
+        "cycle_lineage": assignment["cycle_lineage"],
+        "failed_cycle_count": assignment["failed_cycle_count"],
+        "verifier_version": VERIFIER_VERSION,
+        "verifier_principal": assignment["verifier"]["principal_id"],
+        "status": expected_status,
+    }
+    for field, expected in expected_payload_values.items():
+        if decision[field] != expected:
+            raise ReviewError(f"review decision {field} is invalid", code="DECISION_FIELD_INVALID")
+    try:
+        signature = base64.b64decode(decision["signature"], validate=True)
+        trusted_verifier_public_key.verify(signature, canonical_json_line_bytes(signed_body))
+    except (InvalidSignature, ValueError, TypeError) as exc:
+        raise ReviewError(
+            "review decision signature is invalid", code="DECISION_SIGNATURE_INVALID"
+        ) from exc
+    _validate_review_run_handle(handle)
+    return ReviewResult(
+        status=expected_status,
+        candidate_digest=verified_candidate.candidate_digest,
+        decision_digest=decision["decision_digest"],
+        review_dir=review_dir,
+        decision_document=dict(decision),
+    )
+
+
+def _parse_assignment(value: Any) -> dict[str, Any]:
+    data = _object(value, "assignment")
+    _exact_fields(
+        data,
+        {
+            "schema_version",
+            "candidate_digest",
+            "validation_policy_digest",
+            "cycle_lineage",
+            "failed_cycle_count",
+            "producer",
+            "reviewers",
+            "verifier",
+        },
+        "assignment",
+    )
+    if data["schema_version"] != ASSIGNMENT_SCHEMA_VERSION:
+        raise ReviewError(
+            "assignment schema version is unsupported", code="ASSIGNMENT_VERSION_UNSUPPORTED"
+        )
+    normalized = {
+        "schema_version": ASSIGNMENT_SCHEMA_VERSION,
+        "candidate_digest": _digest(data["candidate_digest"], "candidate_digest"),
+        "validation_policy_digest": _digest(
+            data["validation_policy_digest"], "validation_policy_digest"
+        ),
+        "cycle_lineage": _identifier(data["cycle_lineage"], "cycle_lineage"),
+        "failed_cycle_count": data["failed_cycle_count"],
+        "producer": _parse_principal_attempt(data["producer"], "producer"),
+        "reviewers": _parse_reviewers(data["reviewers"]),
+        "verifier": _parse_verifier(data["verifier"]),
+    }
+    if type(normalized["failed_cycle_count"]) is not int or normalized["failed_cycle_count"] != 0:
+        raise ReviewError(
+            "failed_cycle_count must be 0 for the current initial-candidate review schema",
+            code="ASSIGNMENT_CYCLE_COUNT_INVALID",
+        )
+    reviewers = normalized["reviewers"]
+    principals = [
+        normalized["producer"]["principal_id"],
+        *(item["principal_id"] for item in reviewers),
+        normalized["verifier"]["principal_id"],
+    ]
+    if len(principals) != len(set(principals)):
+        raise ReviewError(
+            "producer, reviewers, and verifier must be distinct principals",
+            code="ASSIGNMENT_PRINCIPALS_NOT_DISTINCT",
+        )
+    attempts = [normalized["producer"]["attempt_id"], *(item["attempt_id"] for item in reviewers)]
+    if len(attempts) != len(set(attempts)):
+        raise ReviewError(
+            "producer and reviewer attempts must be unique", code="ASSIGNMENT_ATTEMPTS_NOT_DISTINCT"
+        )
+    keys = [item["public_key"] for item in reviewers] + [normalized["verifier"]["public_key"]]
+    if len(keys) != len(set(keys)):
+        raise ReviewError(
+            "reviewer and verifier signing keys must be distinct",
+            code="ASSIGNMENT_KEYS_NOT_DISTINCT",
+        )
+    key_ids = [item["key_id"] for item in reviewers]
+    if len(key_ids) != len(set(key_ids)):
+        raise ReviewError(
+            "reviewer signing key IDs must be distinct", code="ASSIGNMENT_KEY_IDS_NOT_DISTINCT"
+        )
+    return normalized
+
+
+def _parse_reviewers(value: Any) -> list[dict[str, str]]:
+    if not isinstance(value, list) or len(value) != 2:
+        raise ReviewError(
+            "assignment must contain exactly two reviewers", code="ASSIGNMENT_REVIEWER_COUNT"
+        )
+    reviewers = []
+    for index, item in enumerate(value):
+        data = _object(item, f"reviewers[{index}]")
+        _exact_fields(
+            data,
+            {"principal_id", "attempt_id", "lens", "key_id", "public_key"},
+            f"reviewers[{index}]",
+        )
+        reviewer = {
+            **_parse_principal_attempt(
+                data,
+                f"reviewers[{index}]",
+                extra={"lens", "key_id", "public_key"},
+            ),
+            "lens": _choice(data["lens"], REQUIRED_LENSES, f"reviewers[{index}].lens"),
+            "key_id": _identifier(data["key_id"], f"reviewers[{index}].key_id"),
+            "public_key": _validated_public_key(data["public_key"]),
+        }
+        reviewers.append(reviewer)
+    if {reviewer["lens"] for reviewer in reviewers} != REQUIRED_LENSES:
+        raise ReviewError(
+            "assignment must cover both required lenses", code="ASSIGNMENT_LENSES_INCOMPLETE"
+        )
+    return sorted(reviewers, key=lambda item: item["lens"])
+
+
+def _parse_verifier(value: Any) -> dict[str, str]:
+    data = _object(value, "verifier")
+    _exact_fields(data, {"principal_id", "public_key"}, "verifier")
+    return {
+        "principal_id": _identifier(data["principal_id"], "verifier.principal_id"),
+        "public_key": _validated_public_key(data["public_key"]),
+    }
+
+
+def _parse_principal_attempt(
+    value: Any, name: str, *, extra: set[str] | None = None
+) -> dict[str, str]:
+    data = _object(value, name)
+    fields = {"principal_id", "attempt_id", *(extra or set())}
+    _exact_fields(data, fields, name)
+    return {
+        "principal_id": _identifier(data["principal_id"], f"{name}.principal_id"),
+        "attempt_id": _identifier(data["attempt_id"], f"{name}.attempt_id"),
+    }
+
+
+def _parse_report_payload(value: Any) -> dict[str, Any]:
+    data = _object(value, "report")
+    _exact_fields(
+        data,
+        {
+            "schema_version",
+            "assignment_digest",
+            "candidate_digest",
+            "validation_policy_digest",
+            "cycle_lineage",
+            "failed_cycle_count",
+            "reviewer_principal",
+            "reviewer_attempt",
+            "reviewer_key_id",
+            "lens",
+            "reviewed_artifact_paths",
+            "summary",
+            "findings",
+        },
+        "report",
+    )
+    if data["schema_version"] != REPORT_SCHEMA_VERSION:
+        raise ReviewError("report schema version is unsupported", code="REPORT_VERSION_UNSUPPORTED")
+    findings = data["findings"]
+    if not isinstance(findings, list):
+        raise ReviewError("report findings must be an array", code="REPORT_FINDINGS_INVALID")
+    failed_cycle_count = data["failed_cycle_count"]
+    if type(failed_cycle_count) is not int or failed_cycle_count != 0:
+        raise ReviewError(
+            "report failed_cycle_count must be 0 for the current initial-candidate review schema",
+            code="REPORT_CYCLE_COUNT_INVALID",
+        )
+    reviewed_artifact_paths = _parse_artifact_paths(data["reviewed_artifact_paths"])
+    normalized_findings = [
+        _parse_finding(item, index, data["reviewer_principal"])
+        for index, item in enumerate(findings)
+    ]
+    ids = [finding["finding_id"] for finding in normalized_findings]
+    if len(ids) != len(set(ids)):
+        raise ReviewError(
+            "finding IDs must be unique within a report", code="REPORT_FINDING_IDS_DUPLICATE"
+        )
+    return {
+        "schema_version": REPORT_SCHEMA_VERSION,
+        "assignment_digest": _digest(data["assignment_digest"], "assignment_digest"),
+        "candidate_digest": _digest(data["candidate_digest"], "candidate_digest"),
+        "validation_policy_digest": _digest(
+            data["validation_policy_digest"], "validation_policy_digest"
+        ),
+        "cycle_lineage": _identifier(data["cycle_lineage"], "cycle_lineage"),
+        "failed_cycle_count": failed_cycle_count,
+        "reviewer_principal": _identifier(data["reviewer_principal"], "reviewer_principal"),
+        "reviewer_attempt": _identifier(data["reviewer_attempt"], "reviewer_attempt"),
+        "reviewer_key_id": _identifier(data["reviewer_key_id"], "reviewer_key_id"),
+        "lens": _choice(data["lens"], REQUIRED_LENSES, "lens"),
+        "reviewed_artifact_paths": reviewed_artifact_paths,
+        "summary": _text(data["summary"], "summary"),
+        "findings": normalized_findings,
+    }
+
+
+def _parse_signed_report(value: Any) -> dict[str, Any]:
+    data = _object(value, "signed report")
+    if "signature" not in data:
+        raise ReviewError("signed report is missing signature", code="REPORT_SIGNATURE_MISSING")
+    payload = _parse_report_payload({key: val for key, val in data.items() if key != "signature"})
+    signature = data["signature"]
+    if not isinstance(signature, str):
+        raise ReviewError("report signature must be base64 text", code="REPORT_SIGNATURE_INVALID")
+    try:
+        base64.b64decode(signature, validate=True)
+    except (ValueError, TypeError) as exc:
+        raise ReviewError(
+            "report signature is invalid base64", code="REPORT_SIGNATURE_INVALID"
+        ) from exc
+    return {**payload, "signature": signature}
+
+
+def _derive_review_status(findings: list[dict[str, Any]], failed_cycle_count: int) -> str:
+    """Derive one canonical review status for finalization and later verification."""
+
+    if type(failed_cycle_count) is not int or failed_cycle_count != 0:
+        raise ReviewError(
+            "failed_cycle_count must be 0 for the current initial-candidate review schema",
+            code="REPORT_CYCLE_COUNT_INVALID",
+        )
+    has_blocking = any(finding["severity"] in _BLOCKING_SEVERITIES for finding in findings)
+    if has_blocking:
+        return "fixes_required"
+    return "reviewed_candidate"
+
+
+def _parse_finding(value: Any, index: int, reviewer_principal: Any) -> dict[str, Any]:
+    name = f"findings[{index}]"
+    data = _object(value, name)
+    _exact_fields(
+        data,
+        {
+            "finding_id",
+            "severity",
+            "invariant",
+            "evidence",
+            "affected_artifact",
+            "reviewer",
+            "repair_owner",
+            "acceptance_condition",
+            "status",
+            "resolution_evidence",
+        },
+        name,
+    )
+    reviewer = _identifier(data["reviewer"], f"{name}.reviewer")
+    if reviewer != reviewer_principal:
+        raise ReviewError(
+            f"{name}.reviewer must match the report reviewer",
+            code="REPORT_FINDING_REVIEWER_MISMATCH",
+        )
+    if data["status"] != "open" or data["resolution_evidence"] is not None:
+        raise ReviewError(
+            f"{name} must be an open finding without resolution evidence",
+            code="REPORT_FINDING_NOT_OPEN",
+        )
+    return {
+        "finding_id": _identifier(data["finding_id"], f"{name}.finding_id"),
+        "severity": _choice(data["severity"], _SEVERITIES, f"{name}.severity"),
+        "invariant": _text(data["invariant"], f"{name}.invariant"),
+        "evidence": _text(data["evidence"], f"{name}.evidence"),
+        "affected_artifact": _text(data["affected_artifact"], f"{name}.affected_artifact"),
+        "reviewer": reviewer,
+        "repair_owner": _identifier(data["repair_owner"], f"{name}.repair_owner"),
+        "acceptance_condition": _text(data["acceptance_condition"], f"{name}.acceptance_condition"),
+        "status": "open",
+        "resolution_evidence": None,
+    }
+
+
+def _verify_report(
+    report: dict[str, Any],
+    reviewer_assignment: dict[str, str],
+    candidate: Any,
+    assignment: dict[str, Any],
+) -> None:
+    expected = {
+        "assignment_digest": _normalized_assignment_digest(assignment),
+        "candidate_digest": candidate.candidate_digest,
+        "validation_policy_digest": candidate.validation_policy_digest,
+        "cycle_lineage": assignment["cycle_lineage"],
+        "failed_cycle_count": assignment["failed_cycle_count"],
+        "reviewer_principal": reviewer_assignment["principal_id"],
+        "reviewer_attempt": reviewer_assignment["attempt_id"],
+        "reviewer_key_id": reviewer_assignment["key_id"],
+        "lens": reviewer_assignment["lens"],
+        "reviewed_artifact_paths": _candidate_artifact_paths(candidate),
+    }
+    for field, value in expected.items():
+        if report[field] != value:
+            raise ReviewError(
+                f"report {field} does not match its assignment/candidate",
+                code="REPORT_FIELD_MISMATCH",
+            )
+    payload = {key: value for key, value in report.items() if key != "signature"}
+    try:
+        signature = base64.b64decode(report["signature"], validate=True)
+        load_public_key_base64(reviewer_assignment["public_key"]).verify(
+            signature, canonical_json_line_bytes(payload)
+        )
+    except (InvalidSignature, ValueError, TypeError) as exc:
+        raise ReviewError(
+            "review report signature is invalid", code="REPORT_SIGNATURE_INVALID"
+        ) from exc
+
+
+def _normalize_findings(reports_by_lens: dict[str, dict[str, Any]]) -> list[dict[str, Any]]:
+    findings = [
+        finding for lens in sorted(reports_by_lens) for finding in reports_by_lens[lens]["findings"]
+    ]
+    ids = [finding["finding_id"] for finding in findings]
+    if len(ids) != len(set(ids)):
+        raise ReviewError(
+            "finding IDs must be unique across reports", code="REPORT_FINDING_IDS_DUPLICATE"
+        )
+    return sorted(findings, key=lambda finding: finding["finding_id"])
+
+
+def _validate_assignment_against_candidate(assignment: dict[str, Any], candidate: Any) -> None:
+    if assignment["candidate_digest"] != candidate.candidate_digest:
+        raise ReviewError(
+            "assignment candidate digest does not match", code="ASSIGNMENT_CANDIDATE_MISMATCH"
+        )
+    if assignment["validation_policy_digest"] != candidate.validation_policy_digest:
+        raise ReviewError(
+            "assignment validation policy digest does not match", code="ASSIGNMENT_POLICY_MISMATCH"
+        )
+    if candidate.producer_principal != assignment["producer"]["principal_id"]:
+        raise ReviewError(
+            "assignment producer principal does not match sealed execution",
+            code="ASSIGNMENT_PRODUCER_MISMATCH",
+        )
+    if candidate.producer_attempt != assignment["producer"]["attempt_id"]:
+        raise ReviewError(
+            "assignment producer attempt does not match sealed execution",
+            code="ASSIGNMENT_PRODUCER_ATTEMPT_MISMATCH",
+        )
+
+
+def _normalized_assignment_digest(assignment: dict[str, Any]) -> str:
+    return sha256_bytes(canonical_json_line_bytes(assignment))
+
+
+def _candidate_artifact_paths(candidate: Any) -> list[str]:
+    members = candidate.manifest.get("members")
+    if not isinstance(members, list):  # verify_candidate should make this unreachable
+        raise ReviewError(
+            "verified candidate does not expose its artifact members",
+            code="CANDIDATE_MEMBER_MISMATCH",
+        )
+    paths = ["candidate/manifest.json"]
+    for member in members:
+        if not isinstance(member, dict) or not isinstance(member.get("path"), str):
+            raise ReviewError(
+                "verified candidate contains an invalid artifact member",
+                code="CANDIDATE_MEMBER_INVALID",
+            )
+        paths.append(f"candidate/{member['path']}")
+    return sorted(paths)
+
+
+def _parse_artifact_paths(value: Any) -> list[str]:
+    if not isinstance(value, list) or not value:
+        raise ReviewError(
+            "reviewed_artifact_paths must be a non-empty array",
+            code="REPORT_ARTIFACT_PATHS_INVALID",
+        )
+    paths: list[str] = []
+    for index, item in enumerate(value):
+        if not isinstance(item, str) or "\\" in item:
+            raise ReviewError(
+                f"reviewed_artifact_paths[{index}] is invalid", code="REPORT_ARTIFACT_PATHS_INVALID"
+            )
+        path = PurePosixPath(item)
+        if (
+            path.is_absolute()
+            or not path.parts
+            or any(part in {"", ".", ".."} for part in path.parts)
+        ):
+            raise ReviewError(
+                f"reviewed_artifact_paths[{index}] is not normalized and relative",
+                code="REPORT_ARTIFACT_PATHS_INVALID",
+            )
+        paths.append(path.as_posix())
+    if paths != sorted(set(paths)):
+        raise ReviewError(
+            "reviewed_artifact_paths must be unique and sorted",
+            code="REPORT_ARTIFACT_PATHS_INVALID",
+        )
+    return paths
+
+
+def _validated_public_key(value: Any) -> str:
+    if not isinstance(value, str):
+        raise ReviewError("public key must be base64 text", code="KEY_ENCODING_INVALID")
+    load_public_key_base64(value)
+    return value
+
+
+def _object(value: Any, name: str) -> dict[str, Any]:
+    if not isinstance(value, dict) or any(not isinstance(key, str) for key in value):
+        raise ReviewError(
+            f"{name} must be an object with string keys", code="ENVELOPE_FIELD_NOT_AN_OBJECT"
+        )
+    return value
+
+
+def _exact_fields(data: dict[str, Any], expected: set[str], name: str) -> None:
+    if set(data) != expected:
+        raise ReviewError(f"{name} fields are invalid", code="ENVELOPE_FIELDS_INVALID")
+
+
+def _identifier(value: Any, name: str) -> str:
+    if not isinstance(value, str) or not value:
+        raise ReviewError(
+            f"{name} must be a non-empty identifier", code="ENVELOPE_FIELD_NOT_AN_IDENTIFIER"
+        )
+    candidate = value.replace("-", "a").replace("_", "a")
+    if not candidate.isalnum():
+        raise ReviewError(
+            f"{name} contains unsupported characters", code="ENVELOPE_FIELD_UNSUPPORTED_CHARACTERS"
+        )
+    return value
+
+
+def _text(value: Any, name: str) -> str:
+    if not isinstance(value, str) or not value.strip():
+        raise ReviewError(f"{name} must be non-empty text", code="ENVELOPE_FIELD_EMPTY")
+    return value
+
+
+def _digest(value: Any, name: str) -> str:
+    if (
+        not isinstance(value, str)
+        or len(value) != 64
+        or any(char not in "0123456789abcdef" for char in value)
+    ):
+        raise ReviewError(
+            f"{name} must be a lowercase SHA-256 digest", code="ENVELOPE_FIELD_NOT_A_DIGEST"
+        )
+    return value
+
+
+def _choice(value: Any, choices: frozenset[str], name: str) -> str:
+    if not isinstance(value, str) or value not in choices:
+        raise ReviewError(
+            f"{name} must be one of {sorted(choices)}", code="ENVELOPE_FIELD_NOT_A_CHOICE"
+        )
+    return value
+
+
+def _decode_json(raw: bytes, name: str) -> Any:
+    try:
+        return json.loads(raw.decode("utf-8"))
+    except (UnicodeDecodeError, json.JSONDecodeError) as exc:
+        raise ReviewError(f"{name} cannot be read", code="ENVELOPE_FILE_UNREADABLE") from exc
+
+
+def _absolute_lexical_path(path: Path) -> Path:
+    """Return an absolute normalized path without resolving filesystem links."""
+
+    return Path(os.path.abspath(os.fspath(path)))
+
+
+def _open_review_run_handle(run_dir: Path) -> _ReviewRunHandle:
+    """Bind every absolute run ancestor and start swap/restore monitoring."""
+
+    if not _secure_review_verification_supported():
+        raise ReviewError(
+            "secure descriptor-relative review verification is unavailable on this platform",
+            code="PLATFORM_REVIEW_VERIFY_UNSUPPORTED",
+        )
+    run_dir = _absolute_lexical_path(run_dir)
+    if run_dir == Path(run_dir.anchor) or not run_dir.name:
+        raise ReviewError(
+            "review run directory must name a non-root directory", code="CANDIDATE_ANCESTOR_INVALID"
+        )
+    directory_flags = os.O_RDONLY | getattr(os, "O_DIRECTORY", 0) | getattr(os, "O_NOFOLLOW", 0)
+    descriptors: list[int] = []
+    records: list[_RetainedAncestorRecord] = []
+    monitor: _ReviewAncestorMonitor | None = None
+    try:
+        anchor_fd = os.open(run_dir.anchor, directory_flags)
+        descriptors.append(anchor_fd)
+        anchor_info = os.fstat(anchor_fd)
+        if not stat.S_ISDIR(anchor_info.st_mode):
+            raise ReviewError(
+                "review run filesystem anchor is not a directory", code="CANDIDATE_ANCESTOR_INVALID"
+            )
+        records.append(
+            (
+                anchor_fd,
+                None,
+                None,
+                _entry_identity(anchor_info),
+                "review run filesystem anchor",
+            )
+        )
+
+        parent_fd = anchor_fd
+        traversed = Path(run_dir.anchor)
+        for part in run_dir.parts[1:]:
+            traversed /= part
+            named = os.stat(part, dir_fd=parent_fd, follow_symlinks=False)
+            if not stat.S_ISDIR(named.st_mode):
+                raise ReviewError(
+                    f"review run ancestor is not a directory: {traversed}",
+                    code="CANDIDATE_ANCESTOR_INVALID",
+                )
+            descriptor = os.open(part, directory_flags, dir_fd=parent_fd)
+            descriptors.append(descriptor)
+            opened = os.fstat(descriptor)
+            _require_same_identity(named, opened, f"review run ancestor {traversed}")
+            records.append(
+                (
+                    descriptor,
+                    parent_fd,
+                    part,
+                    _entry_identity(opened),
+                    f"review run ancestor {traversed}",
+                )
+            )
+            parent_fd = descriptor
+
+        monitor = _create_review_ancestor_monitor(descriptors)
+        handle = _ReviewRunHandle(
+            run_dir=run_dir,
+            descriptors=descriptors,
+            records=records,
+            monitor=monitor,
+        )
+        _validate_review_run_handle(handle)
+        return handle
+    except ReviewError:
+        if monitor is not None:
+            monitor.close()
+        for descriptor in reversed(descriptors):
+            os.close(descriptor)
+        raise
+    except OSError as exc:
+        if monitor is not None:
+            monitor.close()
+        for descriptor in reversed(descriptors):
+            os.close(descriptor)
+        raise ReviewError(
+            "review run ancestor chain cannot be opened safely", code="CANDIDATE_ANCESTOR_INVALID"
+        ) from exc
+
+
+def _open_review_run_handle_from_parent(
+    run_dir: Path,
+    run_parent_fd: int,
+) -> _ReviewRunHandle:
+    """Bind a run child through an already-retained trusted parent descriptor."""
+
+    if not _secure_review_verification_supported():
+        raise ReviewError(
+            "secure descriptor-relative review verification is unavailable on this platform",
+            code="PLATFORM_REVIEW_VERIFY_UNSUPPORTED",
+        )
+    run_dir = _absolute_lexical_path(run_dir)
+    if not run_dir.name:
+        raise ReviewError(
+            "review run directory must name a non-root directory", code="CANDIDATE_ANCESTOR_INVALID"
+        )
+    directory_flags = os.O_RDONLY | getattr(os, "O_DIRECTORY", 0) | getattr(os, "O_NOFOLLOW", 0)
+    run_fd = -1
+    monitor: _ReviewAncestorMonitor | None = None
+    try:
+        named = os.stat(run_dir.name, dir_fd=run_parent_fd, follow_symlinks=False)
+        if not stat.S_ISDIR(named.st_mode):
+            raise ReviewError(
+                "review run child is not a directory", code="CANDIDATE_ANCESTOR_INVALID"
+            )
+        run_fd = os.open(run_dir.name, directory_flags, dir_fd=run_parent_fd)
+        opened = os.fstat(run_fd)
+        _require_same_identity(named, opened, "review run child")
+        monitor = _create_review_ancestor_monitor([run_fd])
+        handle = _ReviewRunHandle(
+            run_dir=run_dir,
+            descriptors=[run_fd],
+            records=[
+                (
+                    run_fd,
+                    run_parent_fd,
+                    run_dir.name,
+                    _entry_identity(opened),
+                    "review run child",
+                )
+            ],
+            monitor=monitor,
+        )
+        _validate_review_run_handle(handle)
+        return handle
+    except ReviewError:
+        if monitor is not None:
+            monitor.close()
+        if run_fd >= 0:
+            os.close(run_fd)
+        raise
+    except OSError as exc:
+        if monitor is not None:
+            monitor.close()
+        if run_fd >= 0:
+            os.close(run_fd)
+        raise ReviewError(
+            "review run child cannot be opened safely", code="CANDIDATE_ANCESTOR_INVALID"
+        ) from exc
+
+
+def _create_review_ancestor_monitor(descriptors: list[int]) -> _ReviewAncestorMonitor:
+    """Watch retained ancestor inodes for move/delete/swap events."""
+
+    if hasattr(select, "kqueue"):
+        queue = select.kqueue()
+        try:
+            flags = select.KQ_NOTE_DELETE | select.KQ_NOTE_RENAME | select.KQ_NOTE_REVOKE
+            if hasattr(select, "KQ_NOTE_ATTRIB"):
+                flags |= select.KQ_NOTE_ATTRIB
+            changes = [
+                select.kevent(
+                    descriptor,
+                    filter=select.KQ_FILTER_VNODE,
+                    flags=select.KQ_EV_ADD | select.KQ_EV_CLEAR,
+                    fflags=flags,
+                )
+                for descriptor in descriptors
+            ]
+            queue.control(changes, 0, 0)
+            return _ReviewAncestorMonitor("kqueue", queue, max(1, len(descriptors)))
+        except Exception:
+            queue.close()
+            raise
+
+    if sys.platform.startswith("linux"):
+        monitor_fd = -1
+        try:
+            libc = ctypes.CDLL(None, use_errno=True)
+            inotify_init1 = libc.inotify_init1
+            inotify_init1.argtypes = [ctypes.c_int]
+            inotify_init1.restype = ctypes.c_int
+            inotify_add_watch = libc.inotify_add_watch
+            inotify_add_watch.argtypes = [ctypes.c_int, ctypes.c_char_p, ctypes.c_uint32]
+            inotify_add_watch.restype = ctypes.c_int
+            monitor_fd = inotify_init1(os.O_CLOEXEC | os.O_NONBLOCK)
+            if monitor_fd < 0:
+                raise OSError(ctypes.get_errno(), "inotify_init1 failed")
+            for descriptor in descriptors:
+                descriptor_path = os.fsencode(f"/proc/self/fd/{descriptor}")
+                if inotify_add_watch(monitor_fd, descriptor_path, _REVIEW_ANCESTOR_WATCH_MASK) < 0:
+                    raise OSError(ctypes.get_errno(), "inotify_add_watch failed")
+            return _ReviewAncestorMonitor("inotify", monitor_fd, 1)
+        except (AttributeError, OSError) as exc:
+            if monitor_fd >= 0:
+                os.close(monitor_fd)
+            raise ReviewError(
+                "secure review ancestor monitoring is unavailable on this platform",
+                code="PLATFORM_REVIEW_MONITOR_UNSUPPORTED",
+            ) from exc
+
+    raise ReviewError(
+        "secure review ancestor monitoring is unavailable on this platform",
+        code="PLATFORM_REVIEW_MONITOR_UNSUPPORTED",
+    )
+
+
+def _validate_review_run_handle(handle: _ReviewRunHandle) -> None:
+    """Reject ancestor substitution, including kernel-observed swap/restore."""
+
+    if handle.monitor.poll():
+        raise ReviewError(
+            "review run ancestor changed during the transaction", code="CANDIDATE_ANCESTOR_RACE"
+        )
+    try:
+        for descriptor, parent_fd, name, expected, label in handle.records:
+            opened = os.fstat(descriptor)
+            if not stat.S_ISDIR(opened.st_mode) or _entry_identity(opened) != expected:
+                raise ReviewError(
+                    f"{label} changed identity during the transaction",
+                    code="CANDIDATE_ANCESTOR_RACE",
+                )
+            if parent_fd is not None and name is not None:
+                named = os.stat(name, dir_fd=parent_fd, follow_symlinks=False)
+                if not stat.S_ISDIR(named.st_mode) or _entry_identity(named) != expected:
+                    raise ReviewError(
+                        f"{label} path changed during the transaction",
+                        code="CANDIDATE_ANCESTOR_RACE",
+                    )
+    except ReviewError:
+        raise
+    except OSError as exc:
+        raise ReviewError(
+            "review run ancestor became unavailable", code="CANDIDATE_ANCESTOR_RACE"
+        ) from exc
+    if handle.monitor.poll():
+        raise ReviewError(
+            "review run ancestor changed during the transaction", code="CANDIDATE_ANCESTOR_RACE"
+        )
+
+
+def _acquire_review_publication_lock(
+    handle: _ReviewRunHandle,
+) -> _ReviewPublicationLock:
+    """Serialize all finalizers for one run before candidate verification or staging."""
+
+    if fcntl is None:  # pragma: no cover - rejected by the platform preflight
+        raise ReviewError(
+            "secure review publication locking is unavailable",
+            code="PLATFORM_REVIEW_LOCK_UNSUPPORTED",
+        )
+    flags = (
+        os.O_RDWR
+        | os.O_CREAT
+        | getattr(os, "O_NOFOLLOW", 0)
+        | getattr(os, "O_CLOEXEC", 0)
+        | getattr(os, "O_NONBLOCK", 0)
+    )
+    descriptor = -1
+    try:
+        descriptor = os.open(
+            _REVIEW_PUBLICATION_LOCK,
+            flags,
+            0o600,
+            dir_fd=handle.run_fd,
+        )
+        opened = os.fstat(descriptor)
+        _require_review_publication_lock(opened)
+        named = os.stat(
+            _REVIEW_PUBLICATION_LOCK,
+            dir_fd=handle.run_fd,
+            follow_symlinks=False,
+        )
+        _require_same_identity(opened, named, "review publication lock")
+
+        fcntl.flock(descriptor, fcntl.LOCK_EX)
+        locked = os.fstat(descriptor)
+        _require_same_identity(opened, locked, "review publication lock")
+        _require_review_publication_lock(locked)
+        os.fchmod(descriptor, 0o600)
+        locked = os.fstat(descriptor)
+        _require_review_publication_lock(locked)
+        named = os.stat(
+            _REVIEW_PUBLICATION_LOCK,
+            dir_fd=handle.run_fd,
+            follow_symlinks=False,
+        )
+        _require_same_identity(locked, named, "review publication lock")
+        _require_review_publication_lock(named)
+        publication_lock = _ReviewPublicationLock(
+            handle=handle,
+            descriptor=descriptor,
+            lock_stat=locked,
+        )
+        publication_lock.validate()
+        return publication_lock
+    except ReviewError:
+        if descriptor >= 0:
+            os.close(descriptor)
+        raise
+    except OSError as exc:
+        if descriptor >= 0:
+            os.close(descriptor)
+        raise ReviewError(
+            "review publication lock cannot be acquired safely", code="LOCK_UNSAFE"
+        ) from exc
+
+
+def _require_review_publication_lock(info: os.stat_result) -> None:
+    expected_uid = os.geteuid() if hasattr(os, "geteuid") else info.st_uid
+    if (
+        not stat.S_ISREG(info.st_mode)
+        or info.st_nlink != 1
+        or info.st_size != 0
+        or info.st_uid != expected_uid
+        or stat.S_IMODE(info.st_mode) != 0o600
+    ):
+        raise ReviewError(
+            "review publication lock is not an owned empty single-link mode-0600 regular file",
+            code="LOCK_INVALID",
+        )
+
+
+def _named_entry_has_identity(
+    parent_fd: int,
+    name: str,
+    expected_identity: tuple[int, int, int] | None,
+) -> bool:
+    if expected_identity is None:
+        return False
+    try:
+        named = os.stat(name, dir_fd=parent_fd, follow_symlinks=False)
+    except OSError:
+        return False
+    return _entry_identity(named) == expected_identity
+
+
+def _review_durability_barrier(descriptor: int, boundary: str) -> None:
+    """Persist one review directory boundary or fail without deleting publication."""
+
+    try:
+        os.fsync(descriptor)
+    except OSError as exc:
+        raise ReviewError(
+            f"review durability barrier failed: {boundary}", code="ENVELOPE_DURABILITY_FAILED"
+        ) from exc
+
+
+def _ensure_installed_review_durable(
+    handle: _ReviewRunHandle,
+    *,
+    retained_review_fd: int | None = None,
+) -> None:
+    """Retryable post-rename durability barriers for an installed review."""
+
+    owned = retained_review_fd is None
+    review_fd = retained_review_fd if retained_review_fd is not None else -1
+    try:
+        review_named = os.stat("review", dir_fd=handle.run_fd, follow_symlinks=False)
+        _require_sealed_directory(review_named, "review root")
+        if review_fd < 0:
+            review_fd = os.open(
+                "review",
+                os.O_RDONLY | getattr(os, "O_DIRECTORY", 0) | getattr(os, "O_NOFOLLOW", 0),
+                dir_fd=handle.run_fd,
+            )
+        review_opened = os.fstat(review_fd)
+        _require_same_identity(review_named, review_opened, "review root")
+        _require_sealed_directory(review_opened, "review root")
+        _review_durability_barrier(review_fd, "review-root")
+        _review_durability_barrier(handle.run_fd, "review-run-parent")
+        review_after = os.stat("review", dir_fd=handle.run_fd, follow_symlinks=False)
+        _require_stable_stat(review_opened, review_after, "review root")
+    except ReviewError:
+        raise
+    except OSError as exc:
+        raise ReviewError(
+            "installed review durability cannot be established safely",
+            code="ENVELOPE_DURABILITY_FAILED",
+        ) from exc
+    finally:
+        if owned and review_fd >= 0:
+            os.close(review_fd)
+
+
+def _stage_review_envelope(
+    root_fd: int,
+    *,
+    parent_fd: int,
+    staging_name: str,
+    expected_root_identity: tuple[int, int, int],
+    assignment: dict[str, Any],
+    reports_by_lens: dict[str, dict[str, Any]],
+    findings: list[dict[str, Any]],
+    backlog: list[dict[str, Any]],
+    status: str,
+    verified_candidate: Any,
+    verifier_private_key: TrustedSigner,
+) -> str:
+    """Write, hash, and seal the exact retained staging descriptors."""
+
+    directory_flags = os.O_RDONLY | getattr(os, "O_DIRECTORY", 0) | getattr(os, "O_NOFOLLOW", 0)
+    reports_fd = -1
+    # Member label -> (parent descriptor, name, open descriptor, sealed stat).
+    retained: dict[str, tuple[int, str, int, os.stat_result]] = {}
+    try:
+        root_opened = os.fstat(root_fd)
+        if _entry_identity(root_opened) != expected_root_identity:
+            raise ReviewError(
+                "review staging root changed identity before writing",
+                code="ENVELOPE_STAGING_ROOT_CHANGED",
+            )
+        if set(os.listdir(root_fd)):
+            raise ReviewError(
+                "review staging root was not empty before writing",
+                code="ENVELOPE_STAGING_ROOT_NOT_EMPTY",
+            )
+
+        os.mkdir("reports", mode=0o700, dir_fd=root_fd)
+        reports_named = os.stat("reports", dir_fd=root_fd, follow_symlinks=False)
+        if not stat.S_ISDIR(reports_named.st_mode):
+            raise ReviewError(
+                "review reports member is not a directory", code="ENVELOPE_REPORTS_MEMBER_INVALID"
+            )
+        reports_fd = os.open("reports", directory_flags, dir_fd=root_fd)
+        reports_opened = os.fstat(reports_fd)
+        _require_same_identity(reports_named, reports_opened, "review reports directory")
+
+        assignment_fd, assignment_stat, assignment_sha256 = _create_hash_and_seal_member(
+            root_fd,
+            "assignment.json",
+            "assignment.json",
+            canonical_json_line_bytes(assignment),
+        )
+        retained["assignment.json"] = (
+            root_fd,
+            "assignment.json",
+            assignment_fd,
+            assignment_stat,
+        )
+        report_sha256s: dict[str, str] = {}
+        for lens in sorted(reports_by_lens):
+            name = f"{lens}.json"
+            descriptor, sealed, digest = _create_hash_and_seal_member(
+                reports_fd,
+                name,
+                f"reports/{name}",
+                canonical_json_line_bytes(reports_by_lens[lens]),
+            )
+            retained[f"reports/{name}"] = (reports_fd, name, descriptor, sealed)
+            report_sha256s[lens] = digest
+
+        findings_fd, findings_stat, findings_sha256 = _create_hash_and_seal_member(
+            root_fd,
+            "findings.json",
+            "findings.json",
+            canonical_json_line_bytes(findings),
+        )
+        retained["findings.json"] = (
+            root_fd,
+            "findings.json",
+            findings_fd,
+            findings_stat,
+        )
+        backlog_fd, backlog_stat, backlog_sha256 = _create_hash_and_seal_member(
+            root_fd,
+            "backlog.json",
+            "backlog.json",
+            canonical_json_line_bytes(backlog),
+        )
+        retained["backlog.json"] = (
+            root_fd,
+            "backlog.json",
+            backlog_fd,
+            backlog_stat,
+        )
+
+        decision, decision_digest = _build_signed_decision(
+            assignment=assignment,
+            status=status,
+            verified_candidate=verified_candidate,
+            verifier_private_key=verifier_private_key,
+            assignment_sha256=assignment_sha256,
+            report_sha256s=report_sha256s,
+            findings_sha256=findings_sha256,
+            backlog_sha256=backlog_sha256,
+        )
+        decision_fd, decision_stat, _ = _create_hash_and_seal_member(
+            root_fd,
+            "decision.json",
+            "decision.json",
+            canonical_json_line_bytes(decision),
+        )
+        retained["decision.json"] = (
+            root_fd,
+            "decision.json",
+            decision_fd,
+            decision_stat,
+        )
+
+        os.fchmod(reports_fd, 0o555)
+        os.fsync(reports_fd)
+        reports_sealed = os.fstat(reports_fd)
+        _require_sealed_directory(reports_sealed, "review reports directory")
+        _validate_staged_quiescence(
+            parent_fd=parent_fd,
+            staging_name=staging_name,
+            expected_root_identity=expected_root_identity,
+            root_fd=root_fd,
+            reports_fd=reports_fd,
+            reports_sealed=reports_sealed,
+            retained=retained,
+        )
+        return decision_digest
+    except ReviewError:
+        raise
+    except OSError as exc:
+        raise ReviewError(
+            "review staging envelope cannot be created safely", code="ENVELOPE_STAGING_UNSAFE"
+        ) from exc
+    finally:
+        for _, _, descriptor, _ in retained.values():
+            os.close(descriptor)
+        if reports_fd >= 0:
+            os.close(reports_fd)
+
+
+def _create_hash_and_seal_member(
+    parent_fd: int,
+    name: str,
+    label: str,
+    raw: bytes,
+) -> tuple[int, os.stat_result, str]:
+    if len(raw) > _MAX_REVIEW_MEMBER_BYTES:
+        raise ReviewError(f"review member is too large: {label}", code="ENVELOPE_MEMBER_TOO_LARGE")
+    flags = (
+        os.O_RDWR
+        | os.O_CREAT
+        | os.O_EXCL
+        | getattr(os, "O_NOFOLLOW", 0)
+        | getattr(os, "O_CLOEXEC", 0)
+        | getattr(os, "O_NONBLOCK", 0)
+    )
+    descriptor = os.open(name, flags, 0o600, dir_fd=parent_fd)
+    try:
+        opened = os.fstat(descriptor)
+        if not stat.S_ISREG(opened.st_mode) or opened.st_nlink != 1:
+            raise ReviewError(
+                f"review staging member is not a single-link regular file: {label}",
+                code="ENVELOPE_STAGING_MEMBER_INVALID",
+            )
+        named = os.stat(name, dir_fd=parent_fd, follow_symlinks=False)
+        _require_same_identity(opened, named, label)
+
+        offset = 0
+        while offset < len(raw):
+            written = os.write(descriptor, raw[offset:])
+            if written <= 0:
+                raise ReviewError(
+                    f"review staging member could not be written: {label}",
+                    code="ENVELOPE_STAGING_MEMBER_UNWRITABLE",
+                )
+            offset += written
+        os.fsync(descriptor)
+        written_stat = os.fstat(descriptor)
+        if written_stat.st_size != len(raw):
+            raise ReviewError(
+                f"review staging member size changed while writing: {label}",
+                code="ENVELOPE_STAGING_MEMBER_CHANGED",
+            )
+        os.lseek(descriptor, 0, os.SEEK_SET)
+        observed = _read_bounded_descriptor(descriptor, label)
+        _require_stable_stat(written_stat, os.fstat(descriptor), label)
+        if observed != raw:
+            raise ReviewError(
+                f"review staging member changed before hashing: {label}",
+                code="ENVELOPE_STAGING_MEMBER_CHANGED",
+            )
+        digest = sha256_bytes(observed)
+
+        os.fchmod(descriptor, 0o444)
+        os.fsync(descriptor)
+        sealed = os.fstat(descriptor)
+        _require_sealed_file(sealed, label)
+        named_after = os.stat(name, dir_fd=parent_fd, follow_symlinks=False)
+        _require_stable_stat(sealed, named_after, label)
+        return descriptor, sealed, digest
+    except Exception:
+        os.close(descriptor)
+        raise
+
+
+def _read_bounded_descriptor(descriptor: int, label: str) -> bytes:
+    raw = bytearray()
+    while True:
+        remaining = _MAX_REVIEW_MEMBER_BYTES + 1 - len(raw)
+        chunk = os.read(descriptor, min(1024 * 1024, remaining))
+        if not chunk:
+            return bytes(raw)
+        raw.extend(chunk)
+        if len(raw) > _MAX_REVIEW_MEMBER_BYTES:
+            raise ReviewError(
+                f"review member is too large: {label}", code="ENVELOPE_MEMBER_TOO_LARGE"
+            )
+
+
+def _build_signed_decision(
+    *,
+    assignment: dict[str, Any],
+    status: str,
+    verified_candidate: Any,
+    verifier_private_key: TrustedSigner,
+    assignment_sha256: str,
+    report_sha256s: dict[str, str],
+    findings_sha256: str,
+    backlog_sha256: str,
+) -> tuple[dict[str, Any], str]:
+    decision_payload = _decision_payload(
+        assignment=assignment,
+        status=status,
+        verified_candidate=verified_candidate,
+        assignment_sha256=assignment_sha256,
+        report_sha256s=report_sha256s,
+        findings_sha256=findings_sha256,
+        backlog_sha256=backlog_sha256,
+    )
+    decision_digest = sha256_bytes(canonical_json_line_bytes(decision_payload))
+    signed_body = {**decision_payload, "decision_digest": decision_digest}
+    signature = verifier_private_key.sign(canonical_json_line_bytes(signed_body))
+    return (
+        {
+            **signed_body,
+            "signature": base64.b64encode(signature).decode("ascii"),
+        },
+        decision_digest,
+    )
+
+
+def _decision_payload(
+    *,
+    assignment: dict[str, Any],
+    status: str,
+    verified_candidate: Any,
+    assignment_sha256: str,
+    report_sha256s: dict[str, str],
+    findings_sha256: str,
+    backlog_sha256: str,
+) -> dict[str, Any]:
+    return {
+        "schema_version": DECISION_SCHEMA_VERSION,
+        "candidate_digest": verified_candidate.candidate_digest,
+        "table_sha256": verified_candidate.table_sha256,
+        "validation_policy_digest": verified_candidate.validation_policy_digest,
+        "assignment_sha256": assignment_sha256,
+        "report_sha256s": report_sha256s,
+        "findings_sha256": findings_sha256,
+        "backlog_sha256": backlog_sha256,
+        "cycle_lineage": assignment["cycle_lineage"],
+        "failed_cycle_count": assignment["failed_cycle_count"],
+        "verifier_version": VERIFIER_VERSION,
+        "verifier_principal": assignment["verifier"]["principal_id"],
+        "status": status,
+    }
+
+
+def _expected_review_decision_digest(
+    *,
+    assignment: dict[str, Any],
+    reports_by_lens: dict[str, dict[str, Any]],
+    findings: list[dict[str, Any]],
+    backlog: list[dict[str, Any]],
+    status: str,
+    verified_candidate: Any,
+) -> str:
+    payload = _decision_payload(
+        assignment=assignment,
+        status=status,
+        verified_candidate=verified_candidate,
+        assignment_sha256=sha256_bytes(canonical_json_line_bytes(assignment)),
+        report_sha256s={
+            lens: sha256_bytes(canonical_json_line_bytes(reports_by_lens[lens]))
+            for lens in sorted(REQUIRED_LENSES)
+        },
+        findings_sha256=sha256_bytes(canonical_json_line_bytes(findings)),
+        backlog_sha256=sha256_bytes(canonical_json_line_bytes(backlog)),
+    )
+    return sha256_bytes(canonical_json_line_bytes(payload))
+
+
+def _validate_staged_quiescence(
+    *,
+    parent_fd: int,
+    staging_name: str,
+    expected_root_identity: tuple[int, int, int],
+    root_fd: int,
+    reports_fd: int,
+    reports_sealed: os.stat_result,
+    retained: dict[str, tuple[int, str, int, os.stat_result]],
+) -> None:
+    root_before = os.fstat(root_fd)
+    if _entry_identity(root_before) != expected_root_identity:
+        raise ReviewError(
+            "review staging root changed identity before install",
+            code="ENVELOPE_STAGING_ROOT_CHANGED",
+        )
+    if not stat.S_ISDIR(root_before.st_mode) or stat.S_IMODE(root_before.st_mode) != 0o700:
+        raise ReviewError(
+            "review staging root is not mode-0700 before install", code="ENVELOPE_STAGING_ROOT_MODE"
+        )
+    if set(os.listdir(root_fd)) != _REVIEW_ROOT_MEMBERS:
+        raise ReviewError(
+            "review staging member set is invalid", code="ENVELOPE_STAGING_MEMBERS_INVALID"
+        )
+    if set(os.listdir(reports_fd)) != _REVIEW_REPORT_MEMBERS:
+        raise ReviewError(
+            "review staging report member set is invalid",
+            code="ENVELOPE_STAGING_REPORT_MEMBERS_INVALID",
+        )
+    reports_named = os.stat("reports", dir_fd=root_fd, follow_symlinks=False)
+    _require_stable_stat(reports_sealed, reports_named, "review reports directory")
+
+    for label in sorted(retained):
+        member_parent_fd, name, retained_fd, sealed = retained[label]
+        retained_now = os.fstat(retained_fd)
+        _require_stable_stat(sealed, retained_now, label)
+        _require_sealed_file(retained_now, label)
+        named = os.stat(name, dir_fd=member_parent_fd, follow_symlinks=False)
+        _require_stable_stat(sealed, named, label)
+        _require_sealed_file(named, label)
+        flags = (
+            os.O_RDONLY
+            | getattr(os, "O_NOFOLLOW", 0)
+            | getattr(os, "O_CLOEXEC", 0)
+            | getattr(os, "O_NONBLOCK", 0)
+        )
+        check_fd = os.open(name, flags, dir_fd=member_parent_fd)
+        try:
+            checked = os.fstat(check_fd)
+            _require_stable_stat(sealed, checked, label)
+            _require_sealed_file(checked, label)
+        finally:
+            os.close(check_fd)
+        named_after = os.stat(name, dir_fd=member_parent_fd, follow_symlinks=False)
+        _require_stable_stat(sealed, named_after, label)
+
+    if set(os.listdir(reports_fd)) != _REVIEW_REPORT_MEMBERS:
+        raise ReviewError(
+            "review staging report member set changed before install",
+            code="ENVELOPE_STAGING_REPORT_MEMBERS_CHANGED",
+        )
+    _require_stable_stat(reports_sealed, os.fstat(reports_fd), "review reports directory")
+    if set(os.listdir(root_fd)) != _REVIEW_ROOT_MEMBERS:
+        raise ReviewError(
+            "review staging member set changed before install",
+            code="ENVELOPE_STAGING_MEMBERS_CHANGED",
+        )
+    _require_stable_stat(root_before, os.fstat(root_fd), "review staging root")
+    root_named = os.stat(
+        staging_name,
+        dir_fd=parent_fd,
+        follow_symlinks=False,
+    )
+    _require_same_identity(root_before, root_named, "review staging root")
+
+
+def _read_sealed_review_tree(
+    handle: _ReviewRunHandle,
+    *,
+    retained_review_fd: int | None,
+    expected_review_identity: tuple[int, int, int] | None,
+) -> tuple[dict[str, bytes], _ReviewSnapshotLease]:
+    """Read one exact review snapshot without following any member path."""
+
+    directory_flags = os.O_RDONLY | getattr(os, "O_DIRECTORY", 0) | getattr(os, "O_NOFOLLOW", 0)
+    review_fd = -1
+    reports_fd = -1
+    owned_review_fd = retained_review_fd is None
+    success = False
+    try:
+        _validate_review_run_handle(handle)
+        review_named = os.stat("review", dir_fd=handle.run_fd, follow_symlinks=False)
+        _require_sealed_directory(review_named, "review root")
+        if expected_review_identity is not None and (
+            _entry_identity(review_named) != expected_review_identity
+        ):
+            raise ReviewError(
+                "installed review root does not match the finalized staging root",
+                code="ENVELOPE_INSTALL_ROOT_MISMATCH",
+            )
+        review_fd = (
+            os.open("review", directory_flags, dir_fd=handle.run_fd)
+            if retained_review_fd is None
+            else retained_review_fd
+        )
+        review_opened = os.fstat(review_fd)
+        _require_same_identity(review_named, review_opened, "review root")
+        _require_sealed_directory(review_opened, "review root")
+        if set(os.listdir(review_fd)) != _REVIEW_ROOT_MEMBERS:
+            raise ReviewError(
+                "review envelope member set has changed", code="ENVELOPE_MEMBERS_CHANGED"
+            )
+
+        reports_named = os.stat("reports", dir_fd=review_fd, follow_symlinks=False)
+        _require_sealed_directory(reports_named, "review reports directory")
+        reports_fd = os.open("reports", directory_flags, dir_fd=review_fd)
+        reports_opened = os.fstat(reports_fd)
+        _require_same_identity(reports_named, reports_opened, "review reports directory")
+        if set(os.listdir(reports_fd)) != _REVIEW_REPORT_MEMBERS:
+            raise ReviewError(
+                "review report member set has changed", code="ENVELOPE_REPORT_MEMBERS_CHANGED"
+            )
+
+        envelope = {
+            name: _read_sealed_member(review_fd, name, name)
+            for name in sorted(_REVIEW_ROOT_MEMBERS - {"reports"})
+        }
+        envelope.update(
+            {
+                f"reports/{name}": _read_sealed_member(
+                    reports_fd,
+                    name,
+                    f"reports/{name}",
+                )
+                for name in sorted(_REVIEW_REPORT_MEMBERS)
+            }
+        )
+        if set(envelope) != _REVIEW_FILE_PATHS:
+            raise ReviewError(
+                "review envelope member set has changed", code="ENVELOPE_MEMBERS_CHANGED"
+            )
+        if set(os.listdir(reports_fd)) != _REVIEW_REPORT_MEMBERS:
+            raise ReviewError(
+                "review report member set changed during verification",
+                code="ENVELOPE_REPORT_MEMBERS_CHANGED",
+            )
+        _require_stable_stat(reports_opened, os.fstat(reports_fd), "review reports directory")
+        reports_after = os.stat("reports", dir_fd=review_fd, follow_symlinks=False)
+        _require_stable_stat(reports_named, reports_after, "review reports directory")
+        if set(os.listdir(review_fd)) != _REVIEW_ROOT_MEMBERS:
+            raise ReviewError(
+                "review envelope member set changed during verification",
+                code="ENVELOPE_MEMBERS_CHANGED",
+            )
+        _require_stable_stat(review_opened, os.fstat(review_fd), "review root")
+        review_after = os.stat("review", dir_fd=handle.run_fd, follow_symlinks=False)
+        _require_stable_stat(review_named, review_after, "review root")
+        _validate_review_run_handle(handle)
+        lease = _ReviewSnapshotLease(
+            handle=handle,
+            review_fd=review_fd,
+            review_stat=review_named,
+            owns_review_fd=owned_review_fd,
+        )
+        lease.validate()
+        success = True
+        return envelope, lease
+    except ReviewError:
+        raise
+    except OSError as exc:
+        raise ReviewError(
+            "sealed review envelope cannot be read safely", code="ENVELOPE_UNREADABLE"
+        ) from exc
+    finally:
+        if reports_fd >= 0:
+            os.close(reports_fd)
+        if not success and owned_review_fd and review_fd >= 0:
+            os.close(review_fd)
+
+
+def _read_sealed_member(parent_fd: int, name: str, label: str) -> bytes:
+    named = os.stat(name, dir_fd=parent_fd, follow_symlinks=False)
+    _require_sealed_file(named, label)
+    flags = (
+        os.O_RDONLY
+        | getattr(os, "O_NOFOLLOW", 0)
+        | getattr(os, "O_CLOEXEC", 0)
+        | getattr(os, "O_NONBLOCK", 0)
+    )
+    descriptor = os.open(name, flags, dir_fd=parent_fd)
+    try:
+        opened = os.fstat(descriptor)
+        _require_sealed_file(opened, label)
+        _require_same_identity(named, opened, label)
+        raw = bytearray()
+        while True:
+            remaining = _MAX_REVIEW_MEMBER_BYTES + 1 - len(raw)
+            chunk = os.read(descriptor, min(1024 * 1024, remaining))
+            if not chunk:
+                break
+            raw.extend(chunk)
+            if len(raw) > _MAX_REVIEW_MEMBER_BYTES:
+                raise ReviewError(
+                    f"review member is too large: {label}", code="ENVELOPE_MEMBER_TOO_LARGE"
+                )
+        _require_stable_stat(opened, os.fstat(descriptor), label)
+    finally:
+        os.close(descriptor)
+    after = os.stat(name, dir_fd=parent_fd, follow_symlinks=False)
+    _require_stable_stat(named, after, label)
+    return bytes(raw)
+
+
+def _require_sealed_directory(info: os.stat_result, label: str) -> None:
+    if not stat.S_ISDIR(info.st_mode) or stat.S_IMODE(info.st_mode) != 0o555:
+        raise ReviewError(
+            f"{label} is not a sealed mode-0555 directory", code="ENVELOPE_MEMBER_NOT_SEALED"
+        )
+
+
+def _require_sealed_file(info: os.stat_result, label: str) -> None:
+    if not stat.S_ISREG(info.st_mode) or info.st_nlink != 1 or stat.S_IMODE(info.st_mode) != 0o444:
+        raise ReviewError(
+            f"{label} is not a sealed single-link mode-0444 regular file",
+            code="ENVELOPE_MEMBER_NOT_SEALED",
+        )
+
+
+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,
+    )
+
+
+def _entry_identity(info: os.stat_result) -> tuple[int, int, int]:
+    return (info.st_dev, info.st_ino, stat.S_IFMT(info.st_mode))
+
+
+def _require_same_identity(before: os.stat_result, after: os.stat_result, label: str) -> None:
+    if _entry_identity(before) != _entry_identity(after):
+        raise ReviewError(
+            f"{label} changed identity during verification", code="ENVELOPE_MEMBER_CHANGED"
+        )
+
+
+def _require_stable_stat(before: os.stat_result, after: os.stat_result, label: str) -> None:
+    if _stat_signature(before) != _stat_signature(after):
+        raise ReviewError(f"{label} changed during verification", code="ENVELOPE_MEMBER_CHANGED")
+
+
+def _rename_no_replace(
+    source: Path,
+    destination: Path,
+    *,
+    expected_source_identity: tuple[int, int, int] | None = None,
+    installed_mode: int | None = None,
+    parent_fd: int | None = None,
+    source_fd: int | None = None,
+) -> None:
+    """Atomically install a directory while refusing to replace any destination."""
+
+    if source.parent != destination.parent:
+        raise OSError(errno.EXDEV, "review install must remain within one directory")
+    if os.name == "nt":
+        raise OSError(
+            errno.ENOSYS,
+            "secure descriptor-relative review install is unavailable on Windows",
+        )
+
+    flags = os.O_RDONLY | getattr(os, "O_DIRECTORY", 0) | getattr(os, "O_NOFOLLOW", 0)
+    active_parent_fd = parent_fd if parent_fd is not None else -1
+    active_source_fd = source_fd if source_fd is not None else -1
+    owned_parent_fd = parent_fd is None
+    owned_source_fd = source_fd is None
+    try:
+        if active_parent_fd < 0:
+            active_parent_fd = os.open(source.parent, flags)
+        source_named = os.stat(
+            source.name,
+            dir_fd=active_parent_fd,
+            follow_symlinks=False,
+        )
+        expected = expected_source_identity or _entry_identity(source_named)
+        if _entry_identity(source_named) != expected or not stat.S_ISDIR(source_named.st_mode):
+            raise OSError(errno.ESTALE, "review install source identity changed", source)
+        if active_source_fd < 0:
+            active_source_fd = os.open(source.name, flags, dir_fd=active_parent_fd)
+        source_opened = os.fstat(active_source_fd)
+        if _entry_identity(source_opened) != expected:
+            raise OSError(errno.ESTALE, "review install source identity changed", source)
+
+        if sys.platform.startswith("linux"):
+            libc = ctypes.CDLL(None, use_errno=True)
+            renameat2 = getattr(libc, "renameat2", None)
+            if renameat2 is None:
+                raise OSError(errno.ENOSYS, "renameat2 is required for atomic no-replace install")
+            renameat2.argtypes = [
+                ctypes.c_int,
+                ctypes.c_char_p,
+                ctypes.c_int,
+                ctypes.c_char_p,
+                ctypes.c_uint,
+            ]
+            renameat2.restype = ctypes.c_int
+            result = renameat2(
+                active_parent_fd,
+                os.fsencode(source.name),
+                active_parent_fd,
+                os.fsencode(destination.name),
+                1,  # RENAME_NOREPLACE: report EEXIST instead of replacing the destination.
+            )
+            if result != 0:
+                error = ctypes.get_errno()
+                if error == errno.EEXIST:
+                    raise FileExistsError(error, os.strerror(error), destination)
+                raise OSError(error, os.strerror(error), destination)
+        elif sys.platform == "darwin":
+            libc = ctypes.CDLL(None, use_errno=True)
+            renameatx_np = libc.renameatx_np
+            renameatx_np.argtypes = [
+                ctypes.c_int,
+                ctypes.c_char_p,
+                ctypes.c_int,
+                ctypes.c_char_p,
+                ctypes.c_uint,
+            ]
+            renameatx_np.restype = ctypes.c_int
+            result = renameatx_np(
+                active_parent_fd,
+                os.fsencode(source.name),
+                active_parent_fd,
+                os.fsencode(destination.name),
+                # RENAME_EXCL | RENAME_NOFOLLOW_ANY: the same no-replace guarantee,
+                # plus a refusal to traverse a symlink in either path.
+                0x00000004 | 0x00000010,
+            )
+            if result != 0:
+                error = ctypes.get_errno()
+                if error == errno.EEXIST:
+                    raise FileExistsError(error, os.strerror(error), destination)
+                raise OSError(error, os.strerror(error), destination)
+        else:
+            raise OSError(errno.ENOSYS, "atomic no-replace directory install is unsupported")
+
+        destination_named = os.stat(
+            destination.name,
+            dir_fd=active_parent_fd,
+            follow_symlinks=False,
+        )
+        if _entry_identity(destination_named) != expected:
+            raise OSError(errno.ESTALE, "installed review identity changed", destination)
+        if installed_mode is not None:
+            os.fchmod(active_source_fd, installed_mode)
+            os.fsync(active_source_fd)
+        installed_opened = os.fstat(active_source_fd)
+        if _entry_identity(installed_opened) != expected:
+            raise OSError(errno.ESTALE, "installed review identity changed", destination)
+        if installed_mode is not None and stat.S_IMODE(installed_opened.st_mode) != installed_mode:
+            raise OSError(errno.EPERM, "installed review mode could not be sealed", destination)
+        destination_after_seal = os.stat(
+            destination.name,
+            dir_fd=active_parent_fd,
+            follow_symlinks=False,
+        )
+        if _entry_identity(destination_after_seal) != expected:
+            raise OSError(errno.ESTALE, "installed review identity changed", destination)
+        if (
+            installed_mode is not None
+            and stat.S_IMODE(destination_after_seal.st_mode) != installed_mode
+        ):
+            raise OSError(errno.EPERM, "installed review mode could not be sealed", destination)
+    finally:
+        if owned_source_fd and active_source_fd >= 0:
+            os.close(active_source_fd)
+        if owned_parent_fd and active_parent_fd >= 0:
+            os.close(active_parent_fd)
+
+
+def _remove_tree(
+    path: Path,
+    *,
+    expected_identity: tuple[int, int, int] | None = None,
+) -> None:
+    """Best-effort removal that never follows or chmods a symlink target."""
+
+    if os.name == "nt":
+        _remove_tree_fallback(path, expected_identity=expected_identity)
+        return
+    parent_fd = -1
+    try:
+        flags = os.O_RDONLY | getattr(os, "O_DIRECTORY", 0) | getattr(os, "O_NOFOLLOW", 0)
+        parent_fd = os.open(path.parent, flags)
+        named = os.stat(path.name, dir_fd=parent_fd, follow_symlinks=False)
+        expected = expected_identity or _entry_identity(named)
+        if _entry_identity(named) != expected:
+            return
+        _remove_at(parent_fd, path.name, expected_identity=expected)
+    except (FileNotFoundError, NotADirectoryError):
+        return
+    except OSError:
+        return
+    finally:
+        if parent_fd >= 0:
+            os.close(parent_fd)
+
+
+def _remove_at(
+    parent_fd: int,
+    name: str,
+    *,
+    expected_identity: tuple[int, int, int] | None = None,
+) -> None:
+    try:
+        info = os.stat(name, dir_fd=parent_fd, follow_symlinks=False)
+    except FileNotFoundError:
+        return
+    expected = expected_identity or _entry_identity(info)
+    if _entry_identity(info) != expected:
+        return
+    if not stat.S_ISDIR(info.st_mode):
+        try:
+            current = os.stat(name, dir_fd=parent_fd, follow_symlinks=False)
+            if _entry_identity(current) != expected:
+                return
+            os.unlink(name, dir_fd=parent_fd)
+        except FileNotFoundError:
+            pass
+        return
+    flags = os.O_RDONLY | getattr(os, "O_DIRECTORY", 0) | getattr(os, "O_NOFOLLOW", 0)
+    try:
+        directory_fd = os.open(name, flags, dir_fd=parent_fd)
+    except FileNotFoundError:
+        return
+    except OSError:
+        return
+    try:
+        opened = os.fstat(directory_fd)
+        if _entry_identity(opened) != expected:
+            return
+        os.fchmod(directory_fd, 0o700)
+        for child in os.listdir(directory_fd):
+            try:
+                child_info = os.stat(child, dir_fd=directory_fd, follow_symlinks=False)
+                _remove_at(
+                    directory_fd,
+                    child,
+                    expected_identity=_entry_identity(child_info),
+                )
+            except OSError:
+                continue
+    finally:
+        os.close(directory_fd)
+    try:
+        current = os.stat(name, dir_fd=parent_fd, follow_symlinks=False)
+        if _entry_identity(current) != expected:
+            return
+        os.rmdir(name, dir_fd=parent_fd)
+    except FileNotFoundError:
+        pass
+
+
+def _remove_tree_fallback(
+    path: Path,
+    *,
+    expected_identity: tuple[int, int, int] | None = None,
+) -> None:
+    try:
+        info = path.lstat()
+    except FileNotFoundError:
+        return
+    expected = expected_identity or _entry_identity(info)
+    if _entry_identity(info) != expected:
+        return
+    if not stat.S_ISDIR(info.st_mode):
+        try:
+            if _entry_identity(path.lstat()) != expected:
+                return
+            path.unlink()
+        except OSError:
+            pass
+        return
+    try:
+        path.chmod(0o700)
+        children = list(path.iterdir())
+    except OSError:
+        return
+    for child in children:
+        try:
+            child_identity = _entry_identity(child.lstat())
+        except FileNotFoundError:
+            continue
+        _remove_tree_fallback(child, expected_identity=child_identity)
+    try:
+        if _entry_identity(path.lstat()) != expected:
+            return
+        path.rmdir()
+    except OSError:
+        pass