mostlyright-data 0.9.0__py3-none-any.whl

mostlyright/data_harness/repair/contracts.py

@@ -0,0 +1,872 @@
+"""Closed contracts for immutable, bounded repair and closure review."""
+
+from __future__ import annotations
+
+import base64
+import re
+from dataclasses import dataclass
+from typing import Any
+
+from cryptography.hazmat.primitives import serialization
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
+
+from mostlyright.data_harness.canonical import canonical_sha256
+from mostlyright.data_harness.preparation.contracts import (
+    QUALITY_CHECK_POLICY,
+    AsOfJoinSpec,
+    EqualityJoinSpec,
+    OperationSpec,
+)
+from mostlyright.data_harness.repair.adapters import (
+    JoinSpec,
+    preparation_value,
+)
+from mostlyright.data_harness.repair.errors import RepairError
+
+REPAIR_CONTRACT_VERSION = "repair.v1"
+REPAIR_ASSIGNMENT_VERSION = "repair-assignment.v1"
+REPAIR_SUCCESSOR_VERSION = "repair-successor.v1"
+CYCLE_ANCHOR_VERSION = "repair-cycle-anchor.v1"
+CLOSURE_SCOPE_VERSION = "repair-closure-scope.v1"
+CLOSURE_REPORT_VERSION = "repair-closure-report.v1"
+CLOSURE_DECISION_VERSION = "repair-closure-decision.v1"
+MAX_FAILED_CANDIDATES = 3
+MAX_REPAIR_ACTIONS = 32
+MAX_FINDINGS = 256
+
+BLOCKING_SEVERITIES = frozenset({"blocker", "critical", "high"})
+SEVERITIES = frozenset({*BLOCKING_SEVERITIES, "medium", "low"})
+REPAIR_ACTION_KINDS = frozenset(
+    {
+        "append_operation",
+        "replace_operation",
+        "remove_operation",
+        "append_join",
+        "replace_join",
+        "remove_join",
+        "replace_output_columns",
+    }
+)
+# Repair contracts require canonical identifier order, while quality reports retain the
+# policy-owned presentation order.
+ALL_QUALITY_CHECK_IDS = tuple(sorted(QUALITY_CHECK_POLICY))
+REQUIRED_CLOSURE_LENSES = ("data_quality_temporal", "repair_correctness")
+
+_IDENT = re.compile(r"\A[A-Za-z][A-Za-z0-9_.-]{0,127}\Z")
+_DIGEST = re.compile(r"\A[0-9a-f]{64}\Z")
+
+
+def _identifier(value: Any, path: str) -> str:
+    if not isinstance(value, str) or _IDENT.fullmatch(value) is None:
+        raise RepairError("REPAIR_IDENTIFIER", path, "must be a canonical identifier")
+    return value
+
+
+def _digest(value: Any, path: str) -> str:
+    if not isinstance(value, str) or _DIGEST.fullmatch(value) is None:
+        raise RepairError("REPAIR_DIGEST", path, "must be a lowercase SHA-256 digest")
+    return value
+
+
+def _text(value: Any, path: str, *, maximum: int = 4_096) -> str:
+    if not isinstance(value, str) or not value or len(value) > maximum:
+        raise RepairError("REPAIR_TEXT", path, f"must be 1..{maximum} characters")
+    if any(0xD800 <= ord(character) <= 0xDFFF for character in value):
+        raise RepairError("REPAIR_UNICODE", path, "contains an unpaired surrogate")
+    return value
+
+
+def _identifiers(
+    value: Any,
+    path: str,
+    *,
+    minimum: int = 1,
+    allowed: frozenset[str] | None = None,
+) -> tuple[str, ...]:
+    if not isinstance(value, tuple) or not minimum <= len(value) <= 256:
+        raise RepairError(
+            "REPAIR_COLLECTION",
+            path,
+            f"must be an immutable tuple with {minimum}..256 members",
+        )
+    result = tuple(_identifier(item, f"{path}[{index}]") for index, item in enumerate(value))
+    if result != tuple(sorted(set(result))):
+        raise RepairError("REPAIR_ORDER", path, "must be unique and canonically sorted")
+    if allowed is not None and any(item not in allowed for item in result):
+        raise RepairError("REPAIR_VALUE", path, "contains an unsupported identifier")
+    return result
+
+
+def _public_key(value: Any, path: str) -> Ed25519PublicKey:
+    if not isinstance(value, str):
+        raise RepairError("REPAIR_PUBLIC_KEY", path, "must be base64 text")
+    try:
+        raw = base64.b64decode(value, validate=True)
+        return Ed25519PublicKey.from_public_bytes(raw)
+    except (ValueError, TypeError) as exc:
+        raise RepairError("REPAIR_PUBLIC_KEY", path, "is not an Ed25519 public key") from exc
+
+
+def public_key_text(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(value: str) -> Ed25519PublicKey:
+    """Load one enrolled public key without exposing private material."""
+
+    return _public_key(value, "public_key")
+
+
+@dataclass(frozen=True)
+class CandidateReference:
+    """Exact immutable candidate state known to the trusted coordinator."""
+
+    candidate_digest: str
+    plan_digest: str
+    validation_policy_digest: str
+    input_set_digest: str
+    evidence_digest: str
+    producer_principal: str
+    producer_attempt: str
+    status: str
+    failed_candidate_count: int
+
+    def __post_init__(self) -> None:
+        for name in (
+            "candidate_digest",
+            "plan_digest",
+            "validation_policy_digest",
+            "input_set_digest",
+            "evidence_digest",
+        ):
+            _digest(getattr(self, name), f"candidate.{name}")
+        _identifier(self.producer_principal, "candidate.producer_principal")
+        _identifier(self.producer_attempt, "candidate.producer_attempt")
+        if self.status not in {
+            "fixes_required",
+            "human_direction_required",
+            "pending_independent_review",
+            "reviewed_successor",
+        }:
+            raise RepairError("REPAIR_STATUS", "candidate.status", "is unsupported")
+        if (
+            type(self.failed_candidate_count) is not int
+            or not 0 <= self.failed_candidate_count <= MAX_FAILED_CANDIDATES
+        ):
+            raise RepairError(
+                "REPAIR_COUNTER",
+                "candidate.failed_candidate_count",
+                "must be between zero and three",
+            )
+        if self.status == "fixes_required" and self.failed_candidate_count not in {1, 2}:
+            raise RepairError(
+                "REPAIR_COUNTER",
+                "candidate.failed_candidate_count",
+                "fixes_required candidates must have failed count one or two",
+            )
+        if (
+            self.status == "human_direction_required"
+            and self.failed_candidate_count != MAX_FAILED_CANDIDATES
+        ):
+            raise RepairError(
+                "REPAIR_COUNTER",
+                "candidate.failed_candidate_count",
+                "human direction requires exactly three failed candidates",
+            )
+
+    def to_dict(self) -> dict[str, Any]:
+        return preparation_value(self)
+
+
+@dataclass(frozen=True)
+class RepairFinding:
+    """One stable finding; closure is evidence-derived, never a caller Boolean."""
+
+    finding_id: str
+    severity: str
+    invariant: str
+    evidence_digest: str
+    affected_artifact_digest: str
+    acceptance_condition: str
+    affected_check_ids: tuple[str, ...]
+    reviewer_principal: str
+
+    def __post_init__(self) -> None:
+        _identifier(self.finding_id, "finding.finding_id")
+        if self.severity not in SEVERITIES:
+            raise RepairError("REPAIR_SEVERITY", "finding.severity", "is unsupported")
+        _text(self.invariant, "finding.invariant")
+        _digest(self.evidence_digest, "finding.evidence_digest")
+        _digest(self.affected_artifact_digest, "finding.affected_artifact_digest")
+        _text(self.acceptance_condition, "finding.acceptance_condition")
+        _identifiers(
+            self.affected_check_ids,
+            "finding.affected_check_ids",
+            allowed=frozenset(ALL_QUALITY_CHECK_IDS),
+        )
+        _identifier(self.reviewer_principal, "finding.reviewer_principal")
+
+    def to_dict(self) -> dict[str, Any]:
+        return preparation_value(self)
+
+
+@dataclass(frozen=True)
+class FindingInventory:
+    blocking: tuple[RepairFinding, ...]
+    backlog: tuple[RepairFinding, ...]
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.blocking, tuple) or not 1 <= len(self.blocking) <= MAX_FINDINGS:
+            raise RepairError(
+                "REPAIR_FINDINGS",
+                "inventory.blocking",
+                "must contain 1..256 findings",
+            )
+        if not isinstance(self.backlog, tuple) or len(self.backlog) > MAX_FINDINGS:
+            raise RepairError(
+                "REPAIR_FINDINGS",
+                "inventory.backlog",
+                "must contain at most 256 findings",
+            )
+        if any(item.severity not in BLOCKING_SEVERITIES for item in self.blocking):
+            raise RepairError(
+                "REPAIR_FINDINGS",
+                "inventory.blocking",
+                "contains a non-blocking severity",
+            )
+        if any(item.severity in BLOCKING_SEVERITIES for item in self.backlog):
+            raise RepairError(
+                "REPAIR_FINDINGS",
+                "inventory.backlog",
+                "contains a blocking severity",
+            )
+        blocking_ids = tuple(item.finding_id for item in self.blocking)
+        backlog_ids = tuple(item.finding_id for item in self.backlog)
+        if blocking_ids != tuple(sorted(set(blocking_ids))) or backlog_ids != tuple(
+            sorted(set(backlog_ids))
+        ):
+            raise RepairError(
+                "REPAIR_ORDER",
+                "inventory",
+                "finding partitions must be canonically sorted",
+            )
+        if set(blocking_ids) & set(backlog_ids):
+            raise RepairError(
+                "REPAIR_FINDINGS",
+                "inventory",
+                "finding IDs must be globally unique",
+            )
+
+    @property
+    def digest(self) -> str:
+        return canonical_sha256(self.to_dict())
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "blocking": [item.to_dict() for item in self.blocking],
+            "backlog": [item.to_dict() for item in self.backlog],
+        }
+
+
+@dataclass(frozen=True)
+class RepairAction:
+    """One operation from the closed repair-plan edit registry."""
+
+    action_id: str
+    kind: str
+    target_id: str
+    expected_before_digest: str | None
+    replacement: OperationSpec | JoinSpec | tuple[str, ...] | None
+
+    def __post_init__(self) -> None:
+        _identifier(self.action_id, "action.action_id")
+        if self.kind not in REPAIR_ACTION_KINDS:
+            raise RepairError("REPAIR_ACTION_KIND", "action.kind", "is not allowlisted")
+        _identifier(self.target_id, "action.target_id")
+        append = self.kind in {"append_operation", "append_join"}
+        if append != (self.expected_before_digest is None):
+            raise RepairError(
+                "REPAIR_ACTION_SHAPE",
+                "action.expected_before_digest",
+                "must be absent only for append actions",
+            )
+        if self.expected_before_digest is not None:
+            _digest(self.expected_before_digest, "action.expected_before_digest")
+        if self.kind in {"append_operation", "replace_operation"}:
+            if not isinstance(self.replacement, OperationSpec):
+                raise RepairError(
+                    "REPAIR_ACTION_SHAPE",
+                    "action.replacement",
+                    "must be an OperationSpec",
+                )
+            if self.replacement.operation_id != self.target_id:
+                raise RepairError(
+                    "REPAIR_ACTION_SHAPE",
+                    "action.target_id",
+                    "must equal the replacement operation ID",
+                )
+        elif self.kind == "remove_operation":
+            if self.replacement is not None:
+                raise RepairError(
+                    "REPAIR_ACTION_SHAPE",
+                    "action.replacement",
+                    "must be absent for removal",
+                )
+        elif self.kind in {"append_join", "replace_join"}:
+            if not isinstance(self.replacement, (EqualityJoinSpec, AsOfJoinSpec)):
+                raise RepairError(
+                    "REPAIR_ACTION_SHAPE",
+                    "action.replacement",
+                    "must be a supported join",
+                )
+            if self.replacement.join_id != self.target_id:
+                raise RepairError(
+                    "REPAIR_ACTION_SHAPE",
+                    "action.target_id",
+                    "must equal the replacement join ID",
+                )
+        elif self.kind == "remove_join":
+            if self.replacement is not None:
+                raise RepairError(
+                    "REPAIR_ACTION_SHAPE",
+                    "action.replacement",
+                    "must be absent for removal",
+                )
+        elif self.kind == "replace_output_columns":
+            if not isinstance(self.replacement, tuple):
+                raise RepairError(
+                    "REPAIR_ACTION_SHAPE",
+                    "action.replacement",
+                    "must be an immutable tuple",
+                )
+            values = tuple(
+                _identifier(item, f"action.replacement[{index}]")
+                for index, item in enumerate(self.replacement)
+            )
+            if not values or len(values) != len(set(values)):
+                raise RepairError(
+                    "REPAIR_ACTION_SHAPE",
+                    "action.replacement",
+                    "must contain unique ordered output columns",
+                )
+            if self.target_id != "output_columns":
+                raise RepairError(
+                    "REPAIR_ACTION_SHAPE",
+                    "action.target_id",
+                    "must be output_columns for an output replacement",
+                )
+
+    def to_dict(self) -> dict[str, Any]:
+        return preparation_value(self)
+
+
+@dataclass(frozen=True)
+class CycleAnchor:
+    """Externally signed monotonic coordinator state."""
+
+    schema_version: str
+    run_id: str
+    root_candidate_digest: str
+    current_candidate_digest: str
+    current_state_digest: str
+    inventory_digest: str
+    failed_candidate_count: int
+    sequence: int
+    predecessor_anchor_digest: str | None
+    authority_key_id: str
+    authority_public_key: str
+    signature: str
+
+    def __post_init__(self) -> None:
+        if self.schema_version != CYCLE_ANCHOR_VERSION:
+            raise RepairError("REPAIR_ANCHOR_VERSION", "anchor.schema_version", "is unsupported")
+        _identifier(self.run_id, "anchor.run_id")
+        for name in (
+            "root_candidate_digest",
+            "current_candidate_digest",
+            "current_state_digest",
+            "inventory_digest",
+        ):
+            _digest(getattr(self, name), f"anchor.{name}")
+        if (
+            type(self.failed_candidate_count) is not int
+            or not 0 <= self.failed_candidate_count <= MAX_FAILED_CANDIDATES
+        ):
+            raise RepairError("REPAIR_COUNTER", "anchor.failed_candidate_count", "is invalid")
+        if type(self.sequence) is not int or self.sequence < 0:
+            raise RepairError("REPAIR_COUNTER", "anchor.sequence", "is invalid")
+        if self.predecessor_anchor_digest is not None:
+            _digest(self.predecessor_anchor_digest, "anchor.predecessor_anchor_digest")
+        if (self.sequence == 0) != (self.predecessor_anchor_digest is None):
+            raise RepairError(
+                "REPAIR_ANCHOR_CHAIN",
+                "anchor.predecessor_anchor_digest",
+                "must be absent only for sequence zero",
+            )
+        _identifier(self.authority_key_id, "anchor.authority_key_id")
+        _public_key(self.authority_public_key, "anchor.authority_public_key")
+        if not isinstance(self.signature, str):
+            raise RepairError("REPAIR_SIGNATURE", "anchor.signature", "must be base64 text")
+        try:
+            base64.b64decode(self.signature, validate=True)
+        except (ValueError, TypeError) as exc:
+            raise RepairError(
+                "REPAIR_SIGNATURE",
+                "anchor.signature",
+                "is not canonical base64",
+            ) from exc
+
+    def unsigned_dict(self) -> dict[str, Any]:
+        value = preparation_value(self)
+        del value["signature"]
+        return value
+
+    @property
+    def digest(self) -> str:
+        return canonical_sha256(preparation_value(self))
+
+
+@dataclass(frozen=True)
+class RepairAssignment:
+    schema_version: str
+    assignment_id: str
+    run_id: str
+    predecessor: CandidateReference
+    inventory: FindingInventory
+    anchor_digest: str
+    anchor_sequence: int
+    fixer_principal: str
+    fixer_attempt: str
+    actions: tuple[RepairAction, ...]
+    affected_check_ids: tuple[str, ...]
+
+    def __post_init__(self) -> None:
+        if self.schema_version != REPAIR_ASSIGNMENT_VERSION:
+            raise RepairError(
+                "REPAIR_ASSIGNMENT_VERSION",
+                "assignment.schema_version",
+                "is unsupported",
+            )
+        _identifier(self.assignment_id, "assignment.assignment_id")
+        _identifier(self.run_id, "assignment.run_id")
+        if self.predecessor.status != "fixes_required":
+            raise RepairError(
+                "REPAIR_LIFECYCLE",
+                "assignment.predecessor",
+                "must be a fixes_required candidate",
+            )
+        _digest(self.anchor_digest, "assignment.anchor_digest")
+        if type(self.anchor_sequence) is not int or self.anchor_sequence < 0:
+            raise RepairError("REPAIR_COUNTER", "assignment.anchor_sequence", "is invalid")
+        _identifier(self.fixer_principal, "assignment.fixer_principal")
+        _identifier(self.fixer_attempt, "assignment.fixer_attempt")
+        if self.fixer_principal == self.predecessor.producer_principal:
+            raise RepairError(
+                "REPAIR_IDENTITY",
+                "assignment.fixer_principal",
+                "fixer must differ from the predecessor producer",
+            )
+        if self.fixer_attempt == self.predecessor.producer_attempt:
+            raise RepairError(
+                "REPAIR_IDENTITY",
+                "assignment.fixer_attempt",
+                "fixer attempt must differ from the predecessor producer attempt",
+            )
+        if not isinstance(self.actions, tuple) or not 1 <= len(self.actions) <= MAX_REPAIR_ACTIONS:
+            raise RepairError(
+                "REPAIR_ACTIONS",
+                "assignment.actions",
+                "must contain 1..32 actions",
+            )
+        action_ids = tuple(item.action_id for item in self.actions)
+        if len(set(action_ids)) != len(action_ids):
+            raise RepairError(
+                "REPAIR_ACTIONS",
+                "assignment.actions",
+                "contains duplicate action IDs",
+            )
+        # An assignment must claim the entire check inventory, not the subset a repair
+        # believes it touches: a fixer that under-declares would narrow the re-validation
+        # that closes the repair. A genuine subset is therefore rejected here, so
+        # ``affected_check_ids`` on an assignment is in practice always
+        # ``ALL_QUALITY_CHECK_IDS``. Per-finding subsets do exist and are validated on
+        # ``RepairFinding.affected_check_ids`` instead.
+        checked = _identifiers(
+            self.affected_check_ids,
+            "assignment.affected_check_ids",
+            allowed=frozenset(ALL_QUALITY_CHECK_IDS),
+        )
+        if checked != ALL_QUALITY_CHECK_IDS:
+            raise RepairError(
+                "REPAIR_CHECK_COVERAGE",
+                "assignment.affected_check_ids",
+                "must include every directly or transitively affected quality check",
+            )
+
+    @property
+    def digest(self) -> str:
+        return canonical_sha256(self.to_dict())
+
+    def to_dict(self) -> dict[str, Any]:
+        return preparation_value(self)
+
+
+@dataclass(frozen=True)
+class ResolutionEvidence:
+    finding_id: str
+    predecessor_evidence_digest: str
+    acceptance_condition_digest: str
+    check_evidence: tuple[tuple[str, str], ...]
+
+    def __post_init__(self) -> None:
+        _identifier(self.finding_id, "resolution.finding_id")
+        _digest(self.predecessor_evidence_digest, "resolution.predecessor_evidence_digest")
+        _digest(self.acceptance_condition_digest, "resolution.acceptance_condition_digest")
+        if not isinstance(self.check_evidence, tuple) or not self.check_evidence:
+            raise RepairError(
+                "REPAIR_RESOLUTION",
+                "resolution.check_evidence",
+                "must contain deterministic check evidence",
+            )
+        check_ids = tuple(item[0] for item in self.check_evidence)
+        if check_ids != tuple(sorted(set(check_ids))):
+            raise RepairError(
+                "REPAIR_ORDER",
+                "resolution.check_evidence",
+                "must be unique and sorted",
+            )
+        for check_id, evidence_digest in self.check_evidence:
+            _identifier(check_id, "resolution.check_evidence.check_id")
+            _digest(evidence_digest, "resolution.check_evidence.digest")
+
+    @property
+    def digest(self) -> str:
+        return canonical_sha256(preparation_value(self))
+
+
+@dataclass(frozen=True)
+class RepairSuccessor:
+    schema_version: str
+    assignment_digest: str
+    predecessor_candidate_digest: str
+    candidate: CandidateReference
+    cycle_number: int
+    fixer_principal: str
+    fixer_attempt: str
+    affected_check_ids: tuple[str, ...]
+    check_evidence: tuple[tuple[str, str, str], ...]
+    resolution_evidence: tuple[ResolutionEvidence, ...]
+    carried_backlog: tuple[RepairFinding, ...]
+
+    def __post_init__(self) -> None:
+        if self.schema_version != REPAIR_SUCCESSOR_VERSION:
+            raise RepairError(
+                "REPAIR_SUCCESSOR_VERSION",
+                "successor.schema_version",
+                "is unsupported",
+            )
+        _digest(self.assignment_digest, "successor.assignment_digest")
+        _digest(self.predecessor_candidate_digest, "successor.predecessor_candidate_digest")
+        if self.candidate.candidate_digest == self.predecessor_candidate_digest:
+            raise RepairError(
+                "REPAIR_IMMUTABILITY",
+                "successor.candidate",
+                "must have a distinct candidate identity",
+            )
+        if type(self.cycle_number) is not int or not 1 <= self.cycle_number <= 3:
+            raise RepairError("REPAIR_COUNTER", "successor.cycle_number", "is invalid")
+        _identifier(self.fixer_principal, "successor.fixer_principal")
+        _identifier(self.fixer_attempt, "successor.fixer_attempt")
+        _identifiers(
+            self.affected_check_ids,
+            "successor.affected_check_ids",
+            allowed=frozenset(ALL_QUALITY_CHECK_IDS),
+        )
+        check_ids = tuple(item[0] for item in self.check_evidence)
+        if check_ids != ALL_QUALITY_CHECK_IDS:
+            raise RepairError(
+                "REPAIR_CHECK_COVERAGE",
+                "successor.check_evidence",
+                "must contain the complete rerun check inventory",
+            )
+        for check_id, status, evidence_digest in self.check_evidence:
+            _identifier(check_id, "successor.check_evidence.check_id")
+            if status not in {"passed", "failed"}:
+                raise RepairError(
+                    "REPAIR_STATUS",
+                    "successor.check_evidence.status",
+                    "is unsupported",
+                )
+            _digest(evidence_digest, "successor.check_evidence.digest")
+        resolution_ids = tuple(item.finding_id for item in self.resolution_evidence)
+        if resolution_ids != tuple(sorted(set(resolution_ids))):
+            raise RepairError(
+                "REPAIR_ORDER",
+                "successor.resolution_evidence",
+                "must be unique and sorted",
+            )
+        backlog_ids = tuple(item.finding_id for item in self.carried_backlog)
+        if backlog_ids != tuple(sorted(set(backlog_ids))):
+            raise RepairError(
+                "REPAIR_ORDER",
+                "successor.carried_backlog",
+                "must be unique and sorted",
+            )
+        if any(item.severity in BLOCKING_SEVERITIES for item in self.carried_backlog):
+            raise RepairError(
+                "REPAIR_BACKLOG",
+                "successor.carried_backlog",
+                "cannot contain a blocking finding",
+            )
+
+    @property
+    def resolution_evidence_digest(self) -> str:
+        return canonical_sha256([preparation_value(item) for item in self.resolution_evidence])
+
+
+@dataclass(frozen=True)
+class ReviewerEnrollment:
+    lens: str
+    principal_id: str
+    attempt_id: str
+    key_id: str
+    public_key: str
+
+    def __post_init__(self) -> None:
+        if self.lens not in REQUIRED_CLOSURE_LENSES:
+            raise RepairError("REPAIR_REVIEW_LENS", "reviewer.lens", "is unsupported")
+        _identifier(self.principal_id, "reviewer.principal_id")
+        _identifier(self.attempt_id, "reviewer.attempt_id")
+        _identifier(self.key_id, "reviewer.key_id")
+        _public_key(self.public_key, "reviewer.public_key")
+
+
+@dataclass(frozen=True)
+class ClosureReviewScope:
+    schema_version: str
+    scope_id: str
+    run_id: str
+    assignment_digest: str
+    predecessor_candidate_digest: str
+    successor_candidate_digest: str
+    successor_evidence_digest: str
+    resolution_evidence_digest: str
+    cycle_number: int
+    blocking_finding_ids: tuple[str, ...]
+    backlog_digest: str
+    reviewers: tuple[ReviewerEnrollment, ...]
+
+    def __post_init__(self) -> None:
+        if self.schema_version != CLOSURE_SCOPE_VERSION:
+            raise RepairError("REPAIR_SCOPE_VERSION", "scope.schema_version", "is unsupported")
+        _identifier(self.scope_id, "scope.scope_id")
+        _identifier(self.run_id, "scope.run_id")
+        for name in (
+            "assignment_digest",
+            "predecessor_candidate_digest",
+            "successor_candidate_digest",
+            "successor_evidence_digest",
+            "resolution_evidence_digest",
+            "backlog_digest",
+        ):
+            _digest(getattr(self, name), f"scope.{name}")
+        if self.predecessor_candidate_digest == self.successor_candidate_digest:
+            raise RepairError(
+                "REPAIR_IMMUTABILITY",
+                "scope.successor_candidate_digest",
+                "must differ from the predecessor",
+            )
+        if type(self.cycle_number) is not int or not 1 <= self.cycle_number <= 3:
+            raise RepairError("REPAIR_COUNTER", "scope.cycle_number", "is invalid")
+        _identifiers(self.blocking_finding_ids, "scope.blocking_finding_ids")
+        if not isinstance(self.reviewers, tuple) or len(self.reviewers) != 2:
+            raise RepairError(
+                "REPAIR_REVIEWERS",
+                "scope.reviewers",
+                "must contain exactly two reviewers",
+            )
+        if tuple(item.lens for item in self.reviewers) != REQUIRED_CLOSURE_LENSES:
+            raise RepairError(
+                "REPAIR_REVIEWERS",
+                "scope.reviewers",
+                "must cover both required lenses in canonical order",
+            )
+        for attribute in ("principal_id", "attempt_id", "key_id", "public_key"):
+            values = tuple(getattr(item, attribute) for item in self.reviewers)
+            if len(set(values)) != len(values):
+                raise RepairError(
+                    "REPAIR_REVIEWERS",
+                    f"scope.reviewers.{attribute}",
+                    "must be distinct",
+                )
+
+    @property
+    def digest(self) -> str:
+        return canonical_sha256(preparation_value(self))
+
+
+@dataclass(frozen=True)
+class ClosureReviewReport:
+    schema_version: str
+    scope_digest: str
+    successor_candidate_digest: str
+    successor_evidence_digest: str
+    reviewer_principal: str
+    reviewer_attempt: str
+    reviewer_key_id: str
+    lens: str
+    decision: str
+    verified_resolutions: tuple[tuple[str, str], ...]
+    findings: tuple[RepairFinding, ...]
+    signature: str
+
+    def __post_init__(self) -> None:
+        if self.schema_version != CLOSURE_REPORT_VERSION:
+            raise RepairError("REPAIR_REPORT_VERSION", "report.schema_version", "is unsupported")
+        _digest(self.scope_digest, "report.scope_digest")
+        _digest(self.successor_candidate_digest, "report.successor_candidate_digest")
+        _digest(self.successor_evidence_digest, "report.successor_evidence_digest")
+        _identifier(self.reviewer_principal, "report.reviewer_principal")
+        _identifier(self.reviewer_attempt, "report.reviewer_attempt")
+        _identifier(self.reviewer_key_id, "report.reviewer_key_id")
+        if self.lens not in REQUIRED_CLOSURE_LENSES:
+            raise RepairError("REPAIR_REVIEW_LENS", "report.lens", "is unsupported")
+        if self.decision not in {"accept", "reject"}:
+            raise RepairError("REPAIR_REVIEW_DECISION", "report.decision", "is unsupported")
+        ids = tuple(item[0] for item in self.verified_resolutions)
+        if ids != tuple(sorted(set(ids))):
+            raise RepairError(
+                "REPAIR_ORDER",
+                "report.verified_resolutions",
+                "must be unique and sorted",
+            )
+        for finding_id, resolution_digest in self.verified_resolutions:
+            _identifier(finding_id, "report.verified_resolutions.finding_id")
+            _digest(resolution_digest, "report.verified_resolutions.digest")
+        finding_ids = tuple(item.finding_id for item in self.findings)
+        if finding_ids != tuple(sorted(set(finding_ids))):
+            raise RepairError(
+                "REPAIR_ORDER",
+                "report.findings",
+                "must be unique and sorted",
+            )
+        if not isinstance(self.signature, str):
+            raise RepairError("REPAIR_SIGNATURE", "report.signature", "must be base64 text")
+        try:
+            base64.b64decode(self.signature, validate=True)
+        except (ValueError, TypeError) as exc:
+            raise RepairError(
+                "REPAIR_SIGNATURE",
+                "report.signature",
+                "is not canonical base64",
+            ) from exc
+
+    def unsigned_dict(self) -> dict[str, Any]:
+        value = preparation_value(self)
+        del value["signature"]
+        return value
+
+
+@dataclass(frozen=True)
+class ClosureDecision:
+    schema_version: str
+    scope_digest: str
+    candidate: CandidateReference
+    status: str
+    report_digests: tuple[str, ...]
+    preserved_backlog: tuple[RepairFinding, ...]
+    remaining_blocking: tuple[RepairFinding, ...]
+
+    def __post_init__(self) -> None:
+        if self.schema_version != CLOSURE_DECISION_VERSION:
+            raise RepairError(
+                "REPAIR_DECISION_VERSION",
+                "decision.schema_version",
+                "is unsupported",
+            )
+        _digest(self.scope_digest, "decision.scope_digest")
+        if self.status not in {
+            "reviewed_successor",
+            "fixes_required",
+            "human_direction_required",
+        }:
+            raise RepairError("REPAIR_STATUS", "decision.status", "is unsupported")
+        if not isinstance(self.report_digests, tuple) or len(self.report_digests) != 2:
+            raise RepairError(
+                "REPAIR_REPORTS",
+                "decision.report_digests",
+                "must contain two report digests",
+            )
+        for digest in self.report_digests:
+            _digest(digest, "decision.report_digests")
+        if self.status == "reviewed_successor" and self.remaining_blocking:
+            raise RepairError(
+                "REPAIR_CLOSURE",
+                "decision.remaining_blocking",
+                "a reviewed successor cannot retain blocking findings",
+            )
+        if self.status != self.candidate.status:
+            raise RepairError(
+                "REPAIR_STATUS",
+                "decision.candidate.status",
+                "must match the derived decision status",
+            )
+        backlog_ids = tuple(item.finding_id for item in self.preserved_backlog)
+        blocking_ids = tuple(item.finding_id for item in self.remaining_blocking)
+        if backlog_ids != tuple(sorted(set(backlog_ids))) or blocking_ids != tuple(
+            sorted(set(blocking_ids))
+        ):
+            raise RepairError(
+                "REPAIR_ORDER",
+                "decision",
+                "finding partitions must be unique and sorted",
+            )
+        if any(item.severity in BLOCKING_SEVERITIES for item in self.preserved_backlog):
+            raise RepairError(
+                "REPAIR_BACKLOG",
+                "decision.preserved_backlog",
+                "cannot contain a blocking finding",
+            )
+        if any(item.severity not in BLOCKING_SEVERITIES for item in self.remaining_blocking):
+            raise RepairError(
+                "REPAIR_FINDINGS",
+                "decision.remaining_blocking",
+                "cannot contain a non-blocking finding",
+            )
+
+    @property
+    def digest(self) -> str:
+        return canonical_sha256(preparation_value(self))
+
+
+__all__ = [
+    "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_CONTRACT_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",
+]