mostlyright-data 0.9.0__py3-none-any.whl

mostlyright/data_harness/repair/__init__.py

@@ -0,0 +1,78 @@
+"""Immutable, bounded repair-successor coordination.
+
+A repair never edits a sealed candidate. It builds a successor: a new plan derived from the
+predecessor by a bounded set of actions, re-executed through
+``preparation.execute_preparation``, and closed out by independent review.
+"""
+
+from mostlyright.data_harness.repair.adapters import (
+    candidate_digest,
+    input_set_digest,
+    join_digest,
+    operation_digest,
+    output_columns_digest,
+    plan_digest,
+    validation_policy_digest,
+)
+from mostlyright.data_harness.repair.contracts import (
+    ALL_QUALITY_CHECK_IDS,
+    BLOCKING_SEVERITIES,
+    MAX_FAILED_CANDIDATES,
+    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.coordinator import (
+    ImmutableRepairCoordinator,
+    RepairExecution,
+    TrustedCycleAnchorStore,
+    bind_candidate,
+    make_closure_report,
+)
+from mostlyright.data_harness.repair.errors import RepairError
+
+__all__ = [
+    "ALL_QUALITY_CHECK_IDS",
+    "BLOCKING_SEVERITIES",
+    "MAX_FAILED_CANDIDATES",
+    "REQUIRED_CLOSURE_LENSES",
+    "CandidateReference",
+    "ClosureDecision",
+    "ClosureReviewReport",
+    "ClosureReviewScope",
+    "CycleAnchor",
+    "FindingInventory",
+    "ImmutableRepairCoordinator",
+    "RepairAction",
+    "RepairAssignment",
+    "RepairError",
+    "RepairExecution",
+    "RepairFinding",
+    "RepairSuccessor",
+    "ResolutionEvidence",
+    "ReviewerEnrollment",
+    "TrustedCycleAnchorStore",
+    "bind_candidate",
+    "candidate_digest",
+    "input_set_digest",
+    "join_digest",
+    "load_public_key",
+    "make_closure_report",
+    "operation_digest",
+    "output_columns_digest",
+    "plan_digest",
+    "public_key_text",
+    "validation_policy_digest",
+]

mostlyright/data_harness/repair/adapters.py

@@ -0,0 +1,274 @@
+"""Narrow immutable adapters over the preparation engine."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import fields, is_dataclass, replace
+from typing import Any
+
+from mostlyright.data_harness.canonical import canonical_sha256
+from mostlyright.data_harness.preparation.contracts import (
+    AsOfJoinSpec,
+    EqualityJoinSpec,
+    OperationSpec,
+    PreparationPlan,
+)
+from mostlyright.data_harness.preparation.engine import PreparationResult
+from mostlyright.data_harness.preparation.table import TableState
+from mostlyright.data_harness.repair.errors import RepairError
+
+# Re-declared locally rather than imported; ``preparation.contracts`` exports an identical
+# ``JoinSpec`` alias.
+JoinSpec = EqualityJoinSpec | AsOfJoinSpec
+
+
+def preparation_value(value: Any) -> Any:
+    """Convert frozen preparation objects to their complete canonical value."""
+
+    if is_dataclass(value) and not isinstance(value, type):
+        return {
+            field.name: preparation_value(getattr(value, field.name)) for field in fields(value)
+        }
+    if isinstance(value, tuple):
+        return [preparation_value(item) for item in value]
+    if isinstance(value, list):
+        return [preparation_value(item) for item in value]
+    if isinstance(value, dict):
+        return {key: preparation_value(item) for key, item in value.items()}
+    return value
+
+
+def plan_digest(plan: PreparationPlan) -> str:
+    """Hash a plan's raw dataclass fields, as encoded by ``preparation_value``.
+
+    This is not ``PreparationPlan.digest``. The two hash different encodings of the same
+    object and are deliberately distinct values: ``PreparationPlan.digest`` hashes
+    ``plan.to_dict()``, which adds a ``kind`` discriminator to each join and turns each
+    operation's ``parameters`` pair-tuple into a mapping, while this function hashes the
+    fields as declared. Repair digests recorded by this module must always be compared
+    against this function; comparing one against ``PreparationPlan.digest`` mismatches
+    even for an identical plan.
+    """
+
+    if not isinstance(plan, PreparationPlan):
+        raise RepairError("REPAIR_PLAN_TYPE", "plan", "must be a PreparationPlan")
+    return canonical_sha256(preparation_value(plan))
+
+
+def validation_policy_digest(plan: PreparationPlan) -> str:
+    if not isinstance(plan, PreparationPlan):
+        raise RepairError("REPAIR_PLAN_TYPE", "plan", "must be a PreparationPlan")
+    return canonical_sha256(
+        {
+            "quality": preparation_value(plan.quality),
+            "temporal_policy": preparation_value(plan.temporal_policy),
+            "target_policy": plan.target_policy,
+            "target": preparation_value(plan.target),
+        }
+    )
+
+
+def operation_digest(operation: OperationSpec) -> str:
+    if not isinstance(operation, OperationSpec):
+        raise RepairError("REPAIR_OPERATION_TYPE", "operation", "must be an OperationSpec")
+    return canonical_sha256(preparation_value(operation))
+
+
+def join_digest(join: JoinSpec) -> str:
+    if not isinstance(join, (EqualityJoinSpec, AsOfJoinSpec)):
+        raise RepairError("REPAIR_JOIN_TYPE", "join", "must be a supported join")
+    return canonical_sha256(preparation_value(join))
+
+
+def output_columns_digest(columns: tuple[str, ...]) -> str:
+    return canonical_sha256(list(columns))
+
+
+def table_value(state: TableState) -> dict[str, Any]:
+    """Encode every cell without depending on locale or JSON floating numbers."""
+
+    if not isinstance(state, TableState):
+        raise RepairError("REPAIR_TABLE_TYPE", "state", "must be a TableState")
+    encoded_rows: list[list[dict[str, Any]]] = []
+    for row in state.rows:
+        encoded_row: list[dict[str, Any]] = []
+        for field, value in zip(state.fields, row, strict=True):
+            if value is None:
+                encoded = {"type": field.logical_type, "value": None}
+            elif field.logical_type == "float64":
+                encoded = {"type": "float64", "value": float(value).hex()}
+            elif field.logical_type == "boolean":
+                encoded = {"type": "boolean", "value": value}
+            elif field.logical_type == "int64":
+                encoded = {"type": "int64", "value": value}
+            else:
+                encoded = {"type": field.logical_type, "value": value}
+            encoded_row.append(encoded)
+        encoded_rows.append(encoded_row)
+    return {
+        "table_id": state.table_id,
+        "snapshot_digests": list(state.snapshot_digests),
+        "fields": [preparation_value(field) for field in state.fields],
+        "rows": encoded_rows,
+        "lineage": [preparation_value(item) for item in state.lineage],
+    }
+
+
+def input_set_digest(inputs: Mapping[str, TableState]) -> str:
+    """Bind every exact pre-preparation input table and cell."""
+
+    if not isinstance(inputs, Mapping) or not inputs:
+        raise RepairError(
+            "REPAIR_INPUT_SET",
+            "inputs",
+            "must be a non-empty source mapping",
+        )
+    if any(
+        not isinstance(key, str) or not isinstance(value, TableState)
+        for key, value in inputs.items()
+    ):
+        raise RepairError(
+            "REPAIR_INPUT_SET",
+            "inputs",
+            "must map source identifiers to TableState values",
+        )
+    if any(key != value.table_id for key, value in inputs.items()):
+        raise RepairError(
+            "REPAIR_INPUT_SET",
+            "inputs",
+            "mapping keys must equal table IDs",
+        )
+    return canonical_sha256(
+        [
+            {"source_id": source_id, "table": table_value(inputs[source_id])}
+            for source_id in sorted(inputs)
+        ]
+    )
+
+
+def candidate_digest(
+    plan: PreparationPlan,
+    result: PreparationResult,
+    inputs: Mapping[str, TableState],
+) -> str:
+    if not isinstance(result, PreparationResult):
+        raise RepairError("REPAIR_RESULT_TYPE", "result", "must be a PreparationResult")
+    return canonical_sha256(
+        {
+            "plan_digest": plan_digest(plan),
+            "validation_policy_digest": validation_policy_digest(plan),
+            "input_set_digest": input_set_digest(inputs),
+            "evidence_digest": result.evidence_digest,
+            "output": table_value(result.output),
+        }
+    )
+
+
+def replace_operation(
+    plan: PreparationPlan,
+    *,
+    target_id: str,
+    expected_digest: str,
+    replacement: OperationSpec | None,
+) -> PreparationPlan:
+    indexes = [
+        index
+        for index, operation in enumerate(plan.operations)
+        if operation.operation_id == target_id
+    ]
+    if len(indexes) != 1:
+        raise RepairError(
+            "REPAIR_TARGET",
+            target_id,
+            "operation target must exist exactly once",
+        )
+    index = indexes[0]
+    current = plan.operations[index]
+    if operation_digest(current) != expected_digest:
+        raise RepairError(
+            "REPAIR_STALE_ACTION",
+            target_id,
+            "operation digest differs from the assigned predecessor",
+        )
+    updated = list(plan.operations)
+    if replacement is None:
+        del updated[index]
+    else:
+        if replacement.operation_id != target_id:
+            raise RepairError(
+                "REPAIR_TARGET",
+                target_id,
+                "replacement operation ID must remain stable",
+            )
+        updated[index] = replacement
+    return replace(plan, operations=tuple(updated))
+
+
+def append_operation(plan: PreparationPlan, replacement: OperationSpec) -> PreparationPlan:
+    if any(item.operation_id == replacement.operation_id for item in plan.operations):
+        raise RepairError(
+            "REPAIR_TARGET",
+            replacement.operation_id,
+            "appended operation ID already exists",
+        )
+    return replace(plan, operations=(*plan.operations, replacement))
+
+
+def replace_join(
+    plan: PreparationPlan,
+    *,
+    target_id: str,
+    expected_digest: str,
+    replacement: JoinSpec | None,
+) -> PreparationPlan:
+    indexes = [index for index, join in enumerate(plan.joins) if join.join_id == target_id]
+    if len(indexes) != 1:
+        raise RepairError("REPAIR_TARGET", target_id, "join target must exist exactly once")
+    index = indexes[0]
+    current = plan.joins[index]
+    if join_digest(current) != expected_digest:
+        raise RepairError(
+            "REPAIR_STALE_ACTION",
+            target_id,
+            "join digest differs from the assigned predecessor",
+        )
+    updated = list(plan.joins)
+    if replacement is None:
+        del updated[index]
+    else:
+        if replacement.join_id != target_id:
+            raise RepairError(
+                "REPAIR_TARGET",
+                target_id,
+                "replacement join ID must remain stable",
+            )
+        updated[index] = replacement
+    return replace(plan, joins=tuple(updated))
+
+
+def append_join(plan: PreparationPlan, replacement: JoinSpec) -> PreparationPlan:
+    if any(item.join_id == replacement.join_id for item in plan.joins):
+        raise RepairError(
+            "REPAIR_TARGET",
+            replacement.join_id,
+            "appended join ID already exists",
+        )
+    return replace(plan, joins=(*plan.joins, replacement))
+
+
+__all__ = [
+    "JoinSpec",
+    "append_join",
+    "append_operation",
+    "candidate_digest",
+    "input_set_digest",
+    "join_digest",
+    "operation_digest",
+    "output_columns_digest",
+    "plan_digest",
+    "preparation_value",
+    "replace_join",
+    "replace_operation",
+    "table_value",
+    "validation_policy_digest",
+]