mostlyright-data 0.9.0__py3-none-any.whl

mostlyright/data_harness/repair/coordinator.py

@@ -0,0 +1,1099 @@
+"""Trusted immutable repair execution and independent closure coordination."""
+
+from __future__ import annotations
+
+import base64
+import threading
+from collections.abc import Mapping
+from dataclasses import dataclass, replace
+from typing import Any, Protocol
+
+from cryptography.exceptions import InvalidSignature
+
+from mostlyright.data_harness.canonical import canonical_json_bytes, canonical_sha256
+from mostlyright.data_harness.preparation.contracts import (
+    AsOfJoinSpec,
+    EqualityJoinSpec,
+    OperationSpec,
+    PreparationPlan,
+)
+from mostlyright.data_harness.preparation.engine import (
+    PreparationResult,
+    execute_preparation,
+)
+from mostlyright.data_harness.preparation.table import TableState
+from mostlyright.data_harness.repair.adapters import (
+    append_join,
+    append_operation,
+    candidate_digest,
+    input_set_digest,
+    output_columns_digest,
+    plan_digest,
+    preparation_value,
+    replace_join,
+    replace_operation,
+    validation_policy_digest,
+)
+from mostlyright.data_harness.repair.contracts import (
+    ALL_QUALITY_CHECK_IDS,
+    BLOCKING_SEVERITIES,
+    CLOSURE_DECISION_VERSION,
+    CLOSURE_REPORT_VERSION,
+    CLOSURE_SCOPE_VERSION,
+    CYCLE_ANCHOR_VERSION,
+    MAX_FAILED_CANDIDATES,
+    REPAIR_ASSIGNMENT_VERSION,
+    REPAIR_SUCCESSOR_VERSION,
+    REQUIRED_CLOSURE_LENSES,
+    CandidateReference,
+    ClosureDecision,
+    ClosureReviewReport,
+    ClosureReviewScope,
+    CycleAnchor,
+    FindingInventory,
+    RepairAction,
+    RepairAssignment,
+    RepairFinding,
+    RepairSuccessor,
+    ResolutionEvidence,
+    ReviewerEnrollment,
+    load_public_key,
+    public_key_text,
+)
+from mostlyright.data_harness.repair.errors import RepairError
+from mostlyright.data_harness.signing import TrustedSigner
+
+
+@dataclass(frozen=True)
+class RepairExecution:
+    """The frozen successor plan, deterministic evidence, and lifecycle envelope."""
+
+    plan: PreparationPlan
+    result: PreparationResult
+    successor: RepairSuccessor
+
+
+class TrustedCycleAnchorStore(Protocol):
+    """External linearizable persistence for signed repair-cycle anchors."""
+
+    def load(self, run_id: str) -> CycleAnchor | None:
+        """Return the authoritative current anchor for one run."""
+
+    def compare_and_swap(
+        self,
+        run_id: str,
+        expected_anchor_digest: str | None,
+        successor: CycleAnchor,
+    ) -> None:
+        """Persist only when the external current digest equals ``expected``."""
+
+
+def bind_candidate(
+    plan: PreparationPlan,
+    result: PreparationResult,
+    *,
+    producer_principal: str,
+    producer_attempt: str,
+    status: str,
+    failed_candidate_count: int,
+    inputs: Mapping[str, TableState],
+) -> CandidateReference:
+    """Bind a preparation result to one exact immutable repair candidate."""
+
+    if not isinstance(result, PreparationResult):
+        raise RepairError("REPAIR_RESULT_TYPE", "result", "must be a PreparationResult")
+    if status in {"pending_independent_review", "reviewed_successor"} and not result.analysis_ready:
+        raise RepairError(
+            "REPAIR_STATUS",
+            "status",
+            "a deterministic failure cannot enter review or reviewed state",
+        )
+    if status == "human_direction_required" and failed_candidate_count != 3:
+        raise RepairError(
+            "REPAIR_STATUS",
+            "status",
+            "human direction requires exactly three failed candidates",
+        )
+    if status not in {
+        "fixes_required",
+        "human_direction_required",
+        "pending_independent_review",
+        "reviewed_successor",
+    }:
+        raise RepairError("REPAIR_STATUS", "status", "is unsupported")
+    return CandidateReference(
+        candidate_digest=candidate_digest(plan, result, inputs),
+        plan_digest=plan_digest(plan),
+        validation_policy_digest=validation_policy_digest(plan),
+        input_set_digest=input_set_digest(inputs),
+        evidence_digest=result.evidence_digest,
+        producer_principal=producer_principal,
+        producer_attempt=producer_attempt,
+        status=status,
+        failed_candidate_count=failed_candidate_count,
+    )
+
+
+def make_closure_report(
+    scope: ClosureReviewScope,
+    enrollment: ReviewerEnrollment,
+    signer: TrustedSigner,
+    *,
+    decision: str,
+    verified_resolutions: tuple[tuple[str, str], ...],
+    findings: tuple[RepairFinding, ...] = (),
+) -> ClosureReviewReport:
+    """Sign one exact closure report without exposing reviewer private key bytes."""
+
+    if enrollment not in scope.reviewers:
+        raise RepairError(
+            "REPAIR_REVIEWER_SCOPE",
+            "enrollment",
+            "is not enrolled for the closure scope",
+        )
+    try:
+        signer_public = public_key_text(signer.public_key())
+    except Exception as exc:
+        raise RepairError(
+            "REPAIR_SIGNER",
+            "signer",
+            "did not expose a valid public verification key",
+        ) from exc
+    if signer_public != enrollment.public_key:
+        raise RepairError(
+            "REPAIR_SIGNER",
+            "signer",
+            "does not match the enrolled reviewer key",
+        )
+    unsigned = {
+        "schema_version": CLOSURE_REPORT_VERSION,
+        "scope_digest": scope.digest,
+        "successor_candidate_digest": scope.successor_candidate_digest,
+        "successor_evidence_digest": scope.successor_evidence_digest,
+        "reviewer_principal": enrollment.principal_id,
+        "reviewer_attempt": enrollment.attempt_id,
+        "reviewer_key_id": enrollment.key_id,
+        "lens": enrollment.lens,
+        "decision": decision,
+        "verified_resolutions": [list(item) for item in verified_resolutions],
+        "findings": [item.to_dict() for item in findings],
+    }
+    try:
+        signature = base64.b64encode(signer.sign(canonical_json_bytes(unsigned))).decode("ascii")
+    except Exception as exc:
+        raise RepairError(
+            "REPAIR_SIGNER",
+            "signer",
+            "could not sign the exact closure report",
+        ) from exc
+    return ClosureReviewReport(
+        schema_version=CLOSURE_REPORT_VERSION,
+        scope_digest=scope.digest,
+        successor_candidate_digest=scope.successor_candidate_digest,
+        successor_evidence_digest=scope.successor_evidence_digest,
+        reviewer_principal=enrollment.principal_id,
+        reviewer_attempt=enrollment.attempt_id,
+        reviewer_key_id=enrollment.key_id,
+        lens=enrollment.lens,
+        decision=decision,
+        verified_resolutions=verified_resolutions,
+        findings=findings,
+        signature=signature,
+    )
+
+
+class ImmutableRepairCoordinator:
+    """Linearizes one externally signed, append-only runtime repair chain."""
+
+    def __init__(
+        self,
+        *,
+        run_id: str,
+        predecessor: CandidateReference,
+        inventory: FindingInventory,
+        authority_key_id: str,
+        authority_signer: TrustedSigner,
+        anchor_store: TrustedCycleAnchorStore,
+    ) -> None:
+        if predecessor.status not in {"fixes_required", "human_direction_required"}:
+            raise RepairError(
+                "REPAIR_LIFECYCLE",
+                "predecessor.status",
+                "must be a failed candidate",
+            )
+        if not callable(getattr(authority_signer, "sign", None)) or not callable(
+            getattr(authority_signer, "public_key", None)
+        ):
+            raise RepairError(
+                "REPAIR_SIGNER",
+                "authority_signer",
+                "must be an opaque trusted signer capability",
+            )
+        self._lock = threading.RLock()
+        self._authority_signer = authority_signer
+        if not callable(getattr(anchor_store, "load", None)) or not callable(
+            getattr(anchor_store, "compare_and_swap", None)
+        ):
+            raise RepairError(
+                "REPAIR_ANCHOR_STORE",
+                "anchor_store",
+                "must provide trusted load and compare-and-swap operations",
+            )
+        self._anchor_store = anchor_store
+        self._authority_key_id = authority_key_id
+        try:
+            self._authority_public_key = authority_signer.public_key()
+            self._authority_public_text = public_key_text(self._authority_public_key)
+        except Exception as exc:
+            raise RepairError(
+                "REPAIR_SIGNER",
+                "authority_signer",
+                "did not expose a valid public key",
+            ) from exc
+        self._run_id = run_id
+        existing_anchor = self._load_external_anchor()
+        self._root_candidate_digest = (
+            predecessor.candidate_digest
+            if existing_anchor is None
+            else existing_anchor.root_candidate_digest
+        )
+        self._current = predecessor
+        self._inventory = inventory
+        self._issued_assignments: dict[str, RepairAssignment] = {}
+        self._consumed_assignments: set[str] = set()
+        self._pending_execution: RepairExecution | None = None
+        self._issued_scopes: dict[str, ClosureReviewScope] = {}
+        self._consumed_scopes: set[str] = set()
+        self._closed = False
+        if existing_anchor is None:
+            self._anchor = self._sign_anchor(
+                current=predecessor,
+                inventory_digest=inventory.digest,
+                sequence=0,
+                predecessor_anchor_digest=None,
+            )
+            self._commit_external_anchor(None, self._anchor)
+        else:
+            self._anchor = existing_anchor
+            if self._anchor.inventory_digest != inventory.digest:
+                raise RepairError(
+                    "REPAIR_ANCHOR_STATE",
+                    "inventory",
+                    "does not match externally anchored current findings",
+                )
+        self._verify_current_anchor()
+
+    @property
+    def current_anchor(self) -> CycleAnchor:
+        return self._anchor
+
+    @property
+    def current_candidate(self) -> CandidateReference:
+        return self._current
+
+    def issue_repair_assignment(
+        self,
+        *,
+        assignment_id: str,
+        fixer_principal: str,
+        fixer_attempt: str,
+        actions: tuple[RepairAction, ...],
+        affected_check_ids: tuple[str, ...] = ALL_QUALITY_CHECK_IDS,
+    ) -> RepairAssignment:
+        """Bind one exact fixer and closed repair proposal to current trusted state."""
+
+        with self._lock:
+            self._verify_current_anchor()
+            if self._closed:
+                raise RepairError(
+                    "REPAIR_LIFECYCLE",
+                    "coordinator",
+                    "the successor is already independently reviewed",
+                )
+            if self._pending_execution is not None:
+                raise RepairError(
+                    "REPAIR_LIFECYCLE",
+                    "coordinator",
+                    "a successor awaits independent review",
+                )
+            if self._current.status == "human_direction_required":
+                raise RepairError(
+                    "REPAIR_CYCLE_CAP",
+                    "coordinator",
+                    "three failed candidates require human direction",
+                )
+            if self._current.status != "fixes_required":
+                raise RepairError(
+                    "REPAIR_LIFECYCLE",
+                    "coordinator",
+                    "current candidate does not accept automatic repair",
+                )
+            if fixer_principal in {
+                item.reviewer_principal
+                for item in (*self._inventory.blocking, *self._inventory.backlog)
+            }:
+                raise RepairError(
+                    "REPAIR_IDENTITY",
+                    "fixer_principal",
+                    "fixer must differ from predecessor finding reviewers",
+                )
+            assignment = RepairAssignment(
+                schema_version=REPAIR_ASSIGNMENT_VERSION,
+                assignment_id=assignment_id,
+                run_id=self._run_id,
+                predecessor=self._current,
+                inventory=self._inventory,
+                anchor_digest=self._anchor.digest,
+                anchor_sequence=self._anchor.sequence,
+                fixer_principal=fixer_principal,
+                fixer_attempt=fixer_attempt,
+                actions=actions,
+                affected_check_ids=affected_check_ids,
+            )
+            if assignment.digest in self._issued_assignments:
+                raise RepairError(
+                    "REPAIR_REPLAY",
+                    "assignment",
+                    "this exact assignment was already issued",
+                )
+            self._issued_assignments[assignment.digest] = assignment
+            return assignment
+
+    def execute_repair(
+        self,
+        assignment: RepairAssignment,
+        predecessor_plan: PreparationPlan,
+        inputs: Mapping[str, TableState],
+    ) -> RepairExecution:
+        """Create a distinct successor and rerun the complete deterministic gate set."""
+
+        with self._lock:
+            self._verify_current_anchor()
+            issued = self._issued_assignments.get(assignment.digest)
+            if issued is None or issued != assignment:
+                raise RepairError(
+                    "REPAIR_ASSIGNMENT_TRUST",
+                    "assignment",
+                    "is not the exact coordinator-issued assignment",
+                )
+            if assignment.digest in self._consumed_assignments:
+                raise RepairError(
+                    "REPAIR_REPLAY",
+                    "assignment",
+                    "has already been consumed",
+                )
+            if (
+                assignment.anchor_digest != self._anchor.digest
+                or assignment.anchor_sequence != self._anchor.sequence
+                or assignment.predecessor != self._current
+                or assignment.inventory != self._inventory
+            ):
+                raise RepairError(
+                    "REPAIR_STALE_ASSIGNMENT",
+                    "assignment",
+                    "does not bind the current monotonic coordinator state",
+                )
+            if plan_digest(predecessor_plan) != assignment.predecessor.plan_digest:
+                raise RepairError(
+                    "REPAIR_PREDECESSOR",
+                    "predecessor_plan",
+                    "digest does not match the sealed predecessor",
+                )
+            if (
+                validation_policy_digest(predecessor_plan)
+                != assignment.predecessor.validation_policy_digest
+            ):
+                raise RepairError(
+                    "REPAIR_POLICY",
+                    "predecessor_plan",
+                    "validation policy differs from the sealed predecessor",
+                )
+            if input_set_digest(inputs) != assignment.predecessor.input_set_digest:
+                raise RepairError(
+                    "REPAIR_INPUT_SUBSTITUTION",
+                    "inputs",
+                    "exact input tables differ from the sealed predecessor",
+                )
+            successor_plan = predecessor_plan
+            for action in assignment.actions:
+                successor_plan = self._apply_action(successor_plan, action)
+            if plan_digest(successor_plan) == assignment.predecessor.plan_digest:
+                raise RepairError(
+                    "REPAIR_NO_SUCCESSOR",
+                    "assignment.actions",
+                    "did not create a distinct successor plan",
+                )
+            if (
+                validation_policy_digest(successor_plan)
+                != assignment.predecessor.validation_policy_digest
+            ):
+                raise RepairError(
+                    "REPAIR_POLICY",
+                    "successor_plan",
+                    "repair actions cannot change quality, temporal, or target policy",
+                )
+            result = execute_preparation(successor_plan, inputs)
+            checks = {item.check_id: item for item in result.quality_report.checks}
+            if tuple(sorted(checks)) != ALL_QUALITY_CHECK_IDS:
+                raise RepairError(
+                    "REPAIR_CHECK_COVERAGE",
+                    "result.quality_report",
+                    "does not contain the complete expected check inventory",
+                )
+            check_evidence = tuple(
+                (
+                    check_id,
+                    checks[check_id].status,
+                    canonical_sha256(checks[check_id].to_dict()),
+                )
+                for check_id in ALL_QUALITY_CHECK_IDS
+            )
+            resolutions = self._resolution_evidence(
+                assignment.inventory.blocking,
+                checks,
+            )
+            failed_count = assignment.predecessor.failed_candidate_count
+            if result.analysis_ready:
+                status = "pending_independent_review"
+            else:
+                failed_count += 1
+                status = (
+                    "human_direction_required"
+                    if failed_count >= MAX_FAILED_CANDIDATES
+                    else "fixes_required"
+                )
+            candidate = bind_candidate(
+                successor_plan,
+                result,
+                producer_principal=assignment.fixer_principal,
+                producer_attempt=assignment.fixer_attempt,
+                status=status,
+                failed_candidate_count=failed_count,
+                inputs=inputs,
+            )
+            if candidate.input_set_digest != assignment.predecessor.input_set_digest:
+                raise RepairError(
+                    "REPAIR_INPUT_SUBSTITUTION",
+                    "successor",
+                    "successor is not bound to the predecessor input set",
+                )
+            successor = RepairSuccessor(
+                schema_version=REPAIR_SUCCESSOR_VERSION,
+                assignment_digest=assignment.digest,
+                predecessor_candidate_digest=assignment.predecessor.candidate_digest,
+                candidate=candidate,
+                cycle_number=assignment.predecessor.failed_candidate_count + 1,
+                fixer_principal=assignment.fixer_principal,
+                fixer_attempt=assignment.fixer_attempt,
+                affected_check_ids=assignment.affected_check_ids,
+                check_evidence=check_evidence,
+                resolution_evidence=resolutions,
+                carried_backlog=assignment.inventory.backlog,
+            )
+            execution = RepairExecution(
+                plan=successor_plan,
+                result=result,
+                successor=successor,
+            )
+            self._consumed_assignments.add(assignment.digest)
+            self._current = candidate
+            if result.analysis_ready:
+                self._pending_execution = execution
+                next_inventory = assignment.inventory
+            else:
+                next_inventory = self._failed_inventory(
+                    predecessor_inventory=assignment.inventory,
+                    candidate=candidate,
+                    checks=checks,
+                    cycle_number=successor.cycle_number,
+                )
+                self._inventory = next_inventory
+            self._advance_anchor(candidate, next_inventory.digest)
+            return execution
+
+    def issue_closure_scope(
+        self,
+        execution: RepairExecution,
+        *,
+        scope_id: str,
+        reviewers: tuple[ReviewerEnrollment, ...],
+    ) -> ClosureReviewScope:
+        """Enroll two fresh independent reviewers over the exact successor."""
+
+        with self._lock:
+            self._verify_current_anchor()
+            if self._pending_execution != execution:
+                raise RepairError(
+                    "REPAIR_REVIEW_SCOPE",
+                    "execution",
+                    "is not the exact pending successor",
+                )
+            successor = execution.successor
+            if successor.candidate.status != "pending_independent_review":
+                raise RepairError(
+                    "REPAIR_REVIEW_SCOPE",
+                    "successor",
+                    "did not pass deterministic affected checks",
+                )
+            assignment = self._issued_assignments[successor.assignment_digest]
+            forbidden_principals = {
+                assignment.predecessor.producer_principal,
+                assignment.fixer_principal,
+            }
+            forbidden_attempts = {
+                assignment.predecessor.producer_attempt,
+                assignment.fixer_attempt,
+            }
+            if any(item.principal_id in forbidden_principals for item in reviewers):
+                raise RepairError(
+                    "REPAIR_SELF_REVIEW",
+                    "reviewers",
+                    "producer or fixer cannot review the successor",
+                )
+            if any(item.attempt_id in forbidden_attempts for item in reviewers):
+                raise RepairError(
+                    "REPAIR_SELF_REVIEW",
+                    "reviewers",
+                    "review attempts must be fresh",
+                )
+            blocking_ids = tuple(sorted(item.finding_id for item in assignment.inventory.blocking))
+            resolution_ids = tuple(item.finding_id for item in successor.resolution_evidence)
+            if resolution_ids != blocking_ids:
+                raise RepairError(
+                    "REPAIR_RESOLUTION",
+                    "successor.resolution_evidence",
+                    "does not cover every carried blocking finding",
+                )
+            scope = ClosureReviewScope(
+                schema_version=CLOSURE_SCOPE_VERSION,
+                scope_id=scope_id,
+                run_id=self._run_id,
+                assignment_digest=successor.assignment_digest,
+                predecessor_candidate_digest=successor.predecessor_candidate_digest,
+                successor_candidate_digest=successor.candidate.candidate_digest,
+                successor_evidence_digest=successor.candidate.evidence_digest,
+                resolution_evidence_digest=successor.resolution_evidence_digest,
+                cycle_number=successor.cycle_number,
+                blocking_finding_ids=blocking_ids,
+                backlog_digest=canonical_sha256(
+                    [item.to_dict() for item in successor.carried_backlog]
+                ),
+                reviewers=reviewers,
+            )
+            if scope.digest in self._issued_scopes:
+                raise RepairError(
+                    "REPAIR_REPLAY",
+                    "scope",
+                    "this exact closure scope was already issued",
+                )
+            self._issued_scopes[scope.digest] = scope
+            return scope
+
+    def finalize_closure(
+        self,
+        scope: ClosureReviewScope,
+        reports: tuple[ClosureReviewReport, ...],
+    ) -> ClosureDecision:
+        """Verify both signatures and derive closure or the next bounded failed state."""
+
+        with self._lock:
+            self._verify_current_anchor()
+            issued = self._issued_scopes.get(scope.digest)
+            if issued is None or issued != scope:
+                raise RepairError(
+                    "REPAIR_SCOPE_TRUST",
+                    "scope",
+                    "is not the exact coordinator-issued closure scope",
+                )
+            if scope.digest in self._consumed_scopes:
+                raise RepairError(
+                    "REPAIR_REPLAY",
+                    "scope",
+                    "has already been finalized",
+                )
+            if self._pending_execution is None:
+                raise RepairError(
+                    "REPAIR_LIFECYCLE",
+                    "scope",
+                    "there is no pending successor",
+                )
+            if not isinstance(reports, tuple) or len(reports) != 2:
+                raise RepairError(
+                    "REPAIR_REPORTS",
+                    "reports",
+                    "exactly two signed reports are required",
+                )
+            by_lens = {report.lens: report for report in reports}
+            if len(by_lens) != 2 or tuple(sorted(by_lens)) != REQUIRED_CLOSURE_LENSES:
+                raise RepairError(
+                    "REPAIR_REPORTS",
+                    "reports",
+                    "must cover both required lenses exactly once",
+                )
+            execution = self._pending_execution
+            expected_resolutions = tuple(
+                (item.finding_id, item.digest) for item in execution.successor.resolution_evidence
+            )
+            all_findings: list[RepairFinding] = []
+            for enrollment in scope.reviewers:
+                report = by_lens[enrollment.lens]
+                self._verify_report(
+                    report,
+                    scope=scope,
+                    enrollment=enrollment,
+                    expected_resolutions=expected_resolutions,
+                )
+                all_findings.extend(report.findings)
+            finding_ids = tuple(item.finding_id for item in all_findings)
+            if len(finding_ids) != len(set(finding_ids)):
+                raise RepairError(
+                    "REPAIR_FINDINGS",
+                    "reports.findings",
+                    "finding IDs must be unique across reviewers",
+                )
+            new_blocking = tuple(
+                sorted(
+                    (
+                        finding
+                        for finding in all_findings
+                        if finding.severity in BLOCKING_SEVERITIES
+                    ),
+                    key=lambda item: item.finding_id,
+                )
+            )
+            rejected = any(report.decision == "reject" for report in reports)
+            if rejected and not new_blocking:
+                raise RepairError(
+                    "REPAIR_REVIEW_DECISION",
+                    "reports",
+                    "a rejection requires at least one evidence-bound blocking finding",
+                )
+            if not rejected and new_blocking:
+                raise RepairError(
+                    "REPAIR_REVIEW_DECISION",
+                    "reports",
+                    "an accepting report cannot contain a blocking finding",
+                )
+            new_backlog = tuple(
+                sorted(
+                    (
+                        *execution.successor.carried_backlog,
+                        *(
+                            finding
+                            for finding in all_findings
+                            if finding.severity not in BLOCKING_SEVERITIES
+                        ),
+                    ),
+                    key=lambda item: item.finding_id,
+                )
+            )
+            backlog_ids = tuple(item.finding_id for item in new_backlog)
+            if len(backlog_ids) != len(set(backlog_ids)):
+                raise RepairError(
+                    "REPAIR_BACKLOG",
+                    "reports.findings",
+                    "cannot replace or duplicate a carried backlog item",
+                )
+            report_digests = tuple(
+                canonical_sha256(preparation_value(by_lens[lens]))
+                for lens in REQUIRED_CLOSURE_LENSES
+            )
+            if not new_blocking:
+                candidate = replace(
+                    execution.successor.candidate,
+                    status="reviewed_successor",
+                )
+                status = "reviewed_successor"
+                self._closed = True
+                self._current = candidate
+                inventory_digest = canonical_sha256(
+                    {
+                        "blocking": [],
+                        "backlog": [item.to_dict() for item in new_backlog],
+                    }
+                )
+            else:
+                failed_count = execution.successor.candidate.failed_candidate_count + 1
+                status = (
+                    "human_direction_required"
+                    if failed_count >= MAX_FAILED_CANDIDATES
+                    else "fixes_required"
+                )
+                candidate = replace(
+                    execution.successor.candidate,
+                    status=status,
+                    failed_candidate_count=failed_count,
+                )
+                self._inventory = FindingInventory(
+                    blocking=new_blocking,
+                    backlog=new_backlog,
+                )
+                self._current = candidate
+                inventory_digest = self._inventory.digest
+            decision = ClosureDecision(
+                schema_version=CLOSURE_DECISION_VERSION,
+                scope_digest=scope.digest,
+                candidate=candidate,
+                status=status,
+                report_digests=report_digests,
+                preserved_backlog=new_backlog,
+                remaining_blocking=new_blocking,
+            )
+            self._pending_execution = None
+            self._consumed_scopes.add(scope.digest)
+            self._advance_anchor(candidate, inventory_digest)
+            return decision
+
+    def _apply_action(
+        self,
+        plan: PreparationPlan,
+        action: RepairAction,
+    ) -> PreparationPlan:
+        if action.kind == "append_operation":
+            if not isinstance(action.replacement, OperationSpec):
+                raise RepairError(
+                    "REPAIR_ACTION_SHAPE",
+                    action.action_id,
+                    "append action lost its validated operation replacement",
+                )
+            return append_operation(plan, action.replacement)
+        if action.kind in {"replace_operation", "remove_operation"}:
+            if action.expected_before_digest is None:
+                raise RepairError(
+                    "REPAIR_ACTION_SHAPE",
+                    action.action_id,
+                    "operation edit lost its predecessor digest",
+                )
+            replacement = (
+                action.replacement
+                if action.kind == "replace_operation"
+                and isinstance(action.replacement, OperationSpec)
+                else None
+            )
+            if action.kind == "replace_operation" and replacement is None:
+                raise RepairError(
+                    "REPAIR_ACTION_SHAPE",
+                    action.action_id,
+                    "replacement action lost its validated operation",
+                )
+            return replace_operation(
+                plan,
+                target_id=action.target_id,
+                expected_digest=action.expected_before_digest,
+                replacement=replacement,
+            )
+        if action.kind == "append_join":
+            if not isinstance(action.replacement, (EqualityJoinSpec, AsOfJoinSpec)):
+                raise RepairError(
+                    "REPAIR_ACTION_SHAPE",
+                    action.action_id,
+                    "append action lost its validated join replacement",
+                )
+            return append_join(plan, action.replacement)
+        if action.kind in {"replace_join", "remove_join"}:
+            if action.expected_before_digest is None:
+                raise RepairError(
+                    "REPAIR_ACTION_SHAPE",
+                    action.action_id,
+                    "join edit lost its predecessor digest",
+                )
+            replacement = (
+                action.replacement
+                if action.kind == "replace_join"
+                and isinstance(action.replacement, (EqualityJoinSpec, AsOfJoinSpec))
+                else None
+            )
+            if action.kind == "replace_join" and replacement is None:
+                raise RepairError(
+                    "REPAIR_ACTION_SHAPE",
+                    action.action_id,
+                    "replacement action lost its validated join",
+                )
+            return replace_join(
+                plan,
+                target_id=action.target_id,
+                expected_digest=action.expected_before_digest,
+                replacement=replacement,
+            )
+        if action.kind == "replace_output_columns":
+            if action.expected_before_digest is None or not isinstance(
+                action.replacement,
+                tuple,
+            ):
+                raise RepairError(
+                    "REPAIR_ACTION_SHAPE",
+                    action.action_id,
+                    "output edit lost its validated predecessor or replacement",
+                )
+            if output_columns_digest(plan.output_columns) != action.expected_before_digest:
+                raise RepairError(
+                    "REPAIR_STALE_ACTION",
+                    action.target_id,
+                    "output-column digest differs from the assigned predecessor",
+                )
+            return replace(plan, output_columns=action.replacement)
+        raise RepairError("REPAIR_ACTION_KIND", action.kind, "is not allowlisted")
+
+    def _resolution_evidence(
+        self,
+        findings: tuple[RepairFinding, ...],
+        checks: dict[str, Any],
+    ) -> tuple[ResolutionEvidence, ...]:
+        resolutions: list[ResolutionEvidence] = []
+        for finding in findings:
+            selected = tuple(checks[check_id] for check_id in finding.affected_check_ids)
+            if any(check.status != "passed" for check in selected):
+                continue
+            resolutions.append(
+                ResolutionEvidence(
+                    finding_id=finding.finding_id,
+                    predecessor_evidence_digest=finding.evidence_digest,
+                    acceptance_condition_digest=canonical_sha256(
+                        {"acceptance_condition": finding.acceptance_condition}
+                    ),
+                    check_evidence=tuple(
+                        (
+                            check.check_id,
+                            canonical_sha256(check.to_dict()),
+                        )
+                        for check in selected
+                    ),
+                )
+            )
+        return tuple(sorted(resolutions, key=lambda item: item.finding_id))
+
+    def _failed_inventory(
+        self,
+        *,
+        predecessor_inventory: FindingInventory,
+        candidate: CandidateReference,
+        checks: dict[str, Any],
+        cycle_number: int,
+    ) -> FindingInventory:
+        blockers = list(predecessor_inventory.blocking)
+        covered = {
+            check_id
+            for finding in predecessor_inventory.blocking
+            for check_id in finding.affected_check_ids
+        }
+        for check_id in ALL_QUALITY_CHECK_IDS:
+            check = checks[check_id]
+            if check.status == "passed" or check_id in covered:
+                continue
+            blockers.append(
+                RepairFinding(
+                    finding_id=f"H4.C{cycle_number}.{check_id}",
+                    severity=check.severity,
+                    invariant=f"Quality check {check_id} must pass on the immutable successor.",
+                    evidence_digest=canonical_sha256(check.to_dict()),
+                    affected_artifact_digest=candidate.candidate_digest,
+                    acceptance_condition=(
+                        f"Rerun the policy-owned {check.threshold_id} check and obtain passed "
+                        "evidence on a distinct successor."
+                    ),
+                    affected_check_ids=(check_id,),
+                    reviewer_principal="deterministic_validator",
+                )
+            )
+        return FindingInventory(
+            blocking=tuple(sorted(blockers, key=lambda item: item.finding_id)),
+            backlog=predecessor_inventory.backlog,
+        )
+
+    def _verify_report(
+        self,
+        report: ClosureReviewReport,
+        *,
+        scope: ClosureReviewScope,
+        enrollment: ReviewerEnrollment,
+        expected_resolutions: tuple[tuple[str, str], ...],
+    ) -> None:
+        expected = {
+            "scope_digest": scope.digest,
+            "successor_candidate_digest": scope.successor_candidate_digest,
+            "successor_evidence_digest": scope.successor_evidence_digest,
+            "reviewer_principal": enrollment.principal_id,
+            "reviewer_attempt": enrollment.attempt_id,
+            "reviewer_key_id": enrollment.key_id,
+            "lens": enrollment.lens,
+        }
+        for name, value in expected.items():
+            if getattr(report, name) != value:
+                raise RepairError(
+                    "REPAIR_REPORT_SCOPE",
+                    f"report.{name}",
+                    "does not match the enrolled closure scope",
+                )
+        if report.verified_resolutions != expected_resolutions:
+            raise RepairError(
+                "REPAIR_WAIVER",
+                "report.verified_resolutions",
+                "must verify every exact carried resolution; omission is not a waiver",
+            )
+        if any(item.reviewer_principal != enrollment.principal_id for item in report.findings):
+            raise RepairError(
+                "REPAIR_FINDING_AUTHOR",
+                "report.findings",
+                "finding reviewer must match the signed report reviewer",
+            )
+        if any(
+            item.affected_artifact_digest != scope.successor_candidate_digest
+            for item in report.findings
+        ):
+            raise RepairError(
+                "REPAIR_FINDING_SCOPE",
+                "report.findings",
+                "every finding must bind the exact successor candidate",
+            )
+        report_has_blocking = any(item.severity in BLOCKING_SEVERITIES for item in report.findings)
+        if (report.decision == "reject") != report_has_blocking:
+            raise RepairError(
+                "REPAIR_REVIEW_DECISION",
+                "report.decision",
+                "must reconcile with this reviewer's blocking findings",
+            )
+        try:
+            signature = base64.b64decode(report.signature, validate=True)
+            public_key = next(item for item in scope.reviewers if item.lens == report.lens)
+            load_public_key(public_key.public_key).verify(
+                signature,
+                canonical_json_bytes(report.unsigned_dict()),
+            )
+        except (InvalidSignature, ValueError, TypeError, StopIteration) as exc:
+            raise RepairError(
+                "REPAIR_REPORT_SIGNATURE",
+                "report.signature",
+                "does not verify for the enrolled key and exact payload",
+            ) from exc
+
+    def _advance_anchor(
+        self,
+        current: CandidateReference,
+        inventory_digest: str,
+    ) -> None:
+        predecessor_digest = self._anchor.digest
+        successor = self._sign_anchor(
+            current=current,
+            inventory_digest=inventory_digest,
+            sequence=self._anchor.sequence + 1,
+            predecessor_anchor_digest=predecessor_digest,
+        )
+        self._commit_external_anchor(predecessor_digest, successor)
+        self._anchor = successor
+
+    def _sign_anchor(
+        self,
+        *,
+        current: CandidateReference,
+        inventory_digest: str,
+        sequence: int,
+        predecessor_anchor_digest: str | None,
+    ) -> CycleAnchor:
+        unsigned = {
+            "schema_version": CYCLE_ANCHOR_VERSION,
+            "run_id": self._run_id,
+            "root_candidate_digest": self._root_candidate_digest,
+            "current_candidate_digest": current.candidate_digest,
+            "current_state_digest": canonical_sha256(current.to_dict()),
+            "inventory_digest": inventory_digest,
+            "failed_candidate_count": current.failed_candidate_count,
+            "sequence": sequence,
+            "predecessor_anchor_digest": predecessor_anchor_digest,
+            "authority_key_id": self._authority_key_id,
+            "authority_public_key": self._authority_public_text,
+        }
+        try:
+            signature = base64.b64encode(
+                self._authority_signer.sign(canonical_json_bytes(unsigned))
+            ).decode("ascii")
+        except Exception as exc:
+            raise RepairError(
+                "REPAIR_SIGNER",
+                "authority_signer",
+                "could not sign the monotonic cycle anchor",
+            ) from exc
+        return CycleAnchor(**unsigned, signature=signature)
+
+    def _verify_current_anchor(self) -> None:
+        external = self._load_external_anchor()
+        if external is None or external.digest != self._anchor.digest:
+            raise RepairError(
+                "REPAIR_ANCHOR_STORE",
+                "anchor_store",
+                "external current anchor differs; restart from authoritative state",
+            )
+        if self._anchor.authority_public_key != self._authority_public_text:
+            raise RepairError(
+                "REPAIR_ANCHOR_AUTHORITY",
+                "anchor.authority_public_key",
+                "does not match the coordinator authority",
+            )
+        try:
+            self._authority_public_key.verify(
+                base64.b64decode(self._anchor.signature, validate=True),
+                canonical_json_bytes(self._anchor.unsigned_dict()),
+            )
+        except (InvalidSignature, ValueError, TypeError) as exc:
+            raise RepairError(
+                "REPAIR_ANCHOR_SIGNATURE",
+                "anchor.signature",
+                "does not verify for the trusted coordinator authority",
+            ) from exc
+        if (
+            self._anchor.current_candidate_digest != self._current.candidate_digest
+            or self._anchor.current_state_digest != canonical_sha256(self._current.to_dict())
+            or self._anchor.failed_candidate_count != self._current.failed_candidate_count
+        ):
+            raise RepairError(
+                "REPAIR_ANCHOR_STATE",
+                "anchor",
+                "does not bind the coordinator's current candidate state",
+            )
+
+    def _load_external_anchor(self) -> CycleAnchor | None:
+        try:
+            anchor = self._anchor_store.load(self._run_id)
+        except RepairError:
+            raise
+        except Exception as exc:
+            raise RepairError(
+                "REPAIR_ANCHOR_STORE",
+                "anchor_store",
+                "could not load authoritative cycle state",
+            ) from exc
+        if anchor is not None and not isinstance(anchor, CycleAnchor):
+            raise RepairError(
+                "REPAIR_ANCHOR_STORE",
+                "anchor_store",
+                "returned an invalid cycle anchor",
+            )
+        return anchor
+
+    def _commit_external_anchor(
+        self,
+        expected_anchor_digest: str | None,
+        successor: CycleAnchor,
+    ) -> None:
+        try:
+            self._anchor_store.compare_and_swap(
+                self._run_id,
+                expected_anchor_digest,
+                successor,
+            )
+        except RepairError:
+            raise
+        except Exception as exc:
+            raise RepairError(
+                "REPAIR_ANCHOR_STORE",
+                "anchor_store",
+                "rejected the monotonic compare-and-swap",
+            ) from exc
+
+
+__all__ = [
+    "ImmutableRepairCoordinator",
+    "RepairExecution",
+    "TrustedCycleAnchorStore",
+    "bind_candidate",
+    "make_closure_report",
+]