mostlyright-data 0.9.0__py3-none-any.whl

mostlyright/data_harness/preparation/contracts.py

@@ -0,0 +1,1017 @@
+"""Closed immutable contracts for deterministic preparation."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from datetime import datetime
+from types import MappingProxyType
+from typing import Any
+
+from mostlyright.data_harness.canonical import canonical_sha256
+from mostlyright.data_harness.local_contracts import LOGICAL_TYPES
+from mostlyright.data_harness.preparation.errors import PreparationError
+
+PREPARATION_CONTRACT_VERSION = "preparation.v1"
+PROFILE_VERSION = "table-profile.v1"
+OPERATION_AUDIT_VERSION = "operation-audit.v1"
+JOIN_AUDIT_VERSION = "join-audit.v1"
+TEMPORAL_REPORT_VERSION = "temporal-report.v1"
+TARGET_RATIONALE_VERSION = "target-rationale.v1"
+QUALITY_REPORT_VERSION = "quality-report.v1"
+
+# Ordered because the quality report serializes checks in this policy-owned order. Repair derives
+# its canonically sorted rerun inventory from the same immutable mapping.
+QUALITY_CHECK_POLICY = MappingProxyType(
+    {
+        "schema": ("blocker", "schema.exact.v1"),
+        "row_bounds": ("critical", "rows.declared-bounds.v1"),
+        "missingness": ("high", "missingness.absolute.v1"),
+        "grain": ("critical", "grain.non-null-unique.v1"),
+        "duplicates": ("high", "rows.no-exact-duplicates.v1"),
+        "join_multiplier": ("critical", "join.maximum-multiplier.v1"),
+        "temporal": ("blocker", "temporal.cutoff-and-revision.v1"),
+        "outliers": ("high", "outlier.tukey-count.v1"),
+        "missing_periods": ("high", "temporal.frequency-gap-count.v1"),
+    }
+)
+
+MAX_FIELDS = 1_024
+MAX_ROWS = 1_000_000
+MAX_OPERATIONS = 256
+MAX_JOINS = 32
+MAX_ALIASES = 10_000
+MAX_TEXT = 4_096
+
+PHYSICAL_TYPES = {
+    "string": "utf8",
+    "int64": "int64",
+    "float64": "double",
+    "boolean": "bool",
+    "date": "date32",
+    "timestamp_utc": "timestamp[us, tz=UTC]",
+}
+SEMANTIC_TYPES = frozenset(
+    {
+        "identifier",
+        "entity",
+        "category",
+        "measure",
+        "dimension",
+        "target",
+        "other",
+    }
+)
+TEMPORAL_ROLES = frozenset(
+    {
+        "none",
+        "event_time",
+        "observed_at",
+        "available_at",
+        "ingested_at",
+        "cutoff",
+        "revision_time",
+    }
+)
+UNITS = frozenset(
+    {
+        "none",
+        "count",
+        "ratio",
+        "percent",
+        "celsius",
+        "fahrenheit",
+        "kelvin",
+        "meter",
+        "kilometer",
+        "mile",
+        "second",
+        "minute",
+        "hour",
+        "hectopascal",
+    }
+)
+OPERATION_KINDS = frozenset(
+    {
+        "trim",
+        "case_normalize",
+        "null_tokens",
+        "strict_cast",
+        "unit_convert",
+        "entity_resolve",
+        "rename",
+        "project",
+        "deduplicate",
+    }
+)
+CARDINALITIES = frozenset({"one_to_one", "one_to_many", "many_to_one", "many_to_many"})
+TEMPORAL_FIDELITIES = frozenset({"exact", "reconstructed", "latest_only", "unknown"})
+# The blocking severities only. Deliberately not the same set as
+# ``repair.contracts.SEVERITIES``, which is all five levels; this is the same subset the
+# repair package spells ``BLOCKING_SEVERITIES``. Nothing in ``src`` reads it today.
+BLOCKING_SEVERITIES = frozenset({"blocker", "critical", "high"})
+_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")
+_UTC = re.compile(r"\A\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,6})?Z\Z")
+
+_OPERATION_PARAMETERS: dict[str, tuple[str, ...]] = {
+    "trim": ("column",),
+    "case_normalize": ("column", "mode"),
+    "null_tokens": ("column", "tokens"),
+    "strict_cast": ("column", "to_type"),
+    "unit_convert": ("column", "from_unit", "to_unit"),
+    "entity_resolve": ("column", "entity_type", "aliases"),
+    "rename": ("mappings",),
+    "project": ("columns",),
+    "deduplicate": ("keys", "authority"),
+}
+
+
+def _text(value: Any, path: str, *, maximum: int = MAX_TEXT) -> str:
+    if not isinstance(value, str) or not value or len(value) > maximum:
+        raise PreparationError("CONTRACT_TEXT", path, f"must be 1..{maximum} characters")
+    if any(0xD800 <= ord(character) <= 0xDFFF for character in value):
+        raise PreparationError("CONTRACT_UNICODE", path, "contains an unpaired surrogate")
+    return value
+
+
+def _identifier(value: Any, path: str) -> str:
+    if not isinstance(value, str) or _IDENT.fullmatch(value) is None:
+        raise PreparationError("CONTRACT_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 PreparationError("CONTRACT_DIGEST", path, "must be a lowercase SHA-256 digest")
+    return value
+
+
+def parse_utc(value: Any, path: str) -> datetime:
+    if not isinstance(value, str) or _UTC.fullmatch(value) is None:
+        raise PreparationError(
+            "CONTRACT_TIMESTAMP",
+            path,
+            "must be a canonical UTC RFC 3339 timestamp",
+        )
+    try:
+        return datetime.fromisoformat(value[:-1] + "+00:00")
+    except ValueError:
+        raise PreparationError(
+            "CONTRACT_TIMESTAMP",
+            path,
+            "timestamp is not a real instant",
+        ) from None
+
+
+def _exact_keys(value: Any, keys: set[str], path: str) -> dict[str, Any]:
+    if not isinstance(value, dict) or set(value) != keys:
+        raise PreparationError(
+            "CONTRACT_FIELDS",
+            path,
+            f"fields must be exactly {sorted(keys)}",
+        )
+    return value
+
+
+def _tuple(
+    value: Any,
+    path: str,
+    *,
+    minimum: int = 0,
+    maximum: int = MAX_FIELDS,
+) -> tuple[Any, ...]:
+    if not isinstance(value, tuple) or not minimum <= len(value) <= maximum:
+        raise PreparationError(
+            "CONTRACT_COLLECTION",
+            path,
+            f"must be an immutable tuple with {minimum}..{maximum} members",
+        )
+    return value
+
+
+def _identifiers(
+    value: Any,
+    path: str,
+    *,
+    minimum: int = 1,
+    maximum: int = MAX_FIELDS,
+) -> tuple[str, ...]:
+    values = _tuple(value, path, minimum=minimum, maximum=maximum)
+    result = tuple(_identifier(item, f"{path}[{index}]") for index, item in enumerate(values))
+    if len(set(result)) != len(result):
+        raise PreparationError("CONTRACT_DUPLICATE", path, "contains duplicate identifiers")
+    return result
+
+
+def _pairs(
+    value: Any,
+    path: str,
+    *,
+    maximum: int,
+    require_sorted: bool = True,
+) -> tuple[tuple[str, str], ...]:
+    pairs = _tuple(value, path, minimum=1, maximum=maximum)
+    result: list[tuple[str, str]] = []
+    for index, pair in enumerate(pairs):
+        if not isinstance(pair, tuple) or len(pair) != 2:
+            raise PreparationError(
+                "CONTRACT_PAIR",
+                f"{path}[{index}]",
+                "must be an immutable two-member tuple",
+            )
+        left = _text(pair[0], f"{path}[{index}][0]", maximum=256)
+        right = _text(pair[1], f"{path}[{index}][1]", maximum=256)
+        result.append((left, right))
+    if len({left for left, _ in result}) != len(result):
+        raise PreparationError("CONTRACT_DUPLICATE", path, "contains duplicate left values")
+    if require_sorted and tuple(result) != tuple(sorted(result)):
+        raise PreparationError("CONTRACT_ORDER", path, "must be sorted canonically")
+    return tuple(result)
+
+
+@dataclass(frozen=True)
+class FieldSpec:
+    """Declared physical, logical, semantic, unit, entity, and temporal field state."""
+
+    name: str
+    logical_type: str
+    physical_type: str
+    semantic_type: str
+    unit: str
+    entity: str | None
+    temporal_role: str
+    nullable: bool
+    source_id: str
+    availability_column: str | None = None
+
+    def __post_init__(self) -> None:
+        _identifier(self.name, "field.name")
+        if self.logical_type not in LOGICAL_TYPES:
+            raise PreparationError("FIELD_LOGICAL_TYPE", "field.logical_type", "is unsupported")
+        if self.physical_type != PHYSICAL_TYPES[self.logical_type]:
+            raise PreparationError(
+                "FIELD_PHYSICAL_TYPE",
+                "field.physical_type",
+                "does not match the logical type",
+            )
+        if self.semantic_type not in SEMANTIC_TYPES:
+            raise PreparationError("FIELD_SEMANTIC_TYPE", "field.semantic_type", "is unsupported")
+        if self.unit not in UNITS:
+            raise PreparationError("FIELD_UNIT", "field.unit", "is unsupported")
+        if self.semantic_type == "measure" and self.unit == "none":
+            raise PreparationError("FIELD_UNIT", "field.unit", "measure fields require a unit")
+        if self.semantic_type != "measure" and self.unit not in {"none", "count"}:
+            raise PreparationError(
+                "FIELD_UNIT",
+                "field.unit",
+                "non-measure fields cannot carry a measurement unit",
+            )
+        if self.entity is not None:
+            _identifier(self.entity, "field.entity")
+        if self.semantic_type == "entity" and self.entity is None:
+            raise PreparationError("FIELD_ENTITY", "field.entity", "entity fields require a type")
+        if self.temporal_role not in TEMPORAL_ROLES:
+            raise PreparationError("FIELD_TEMPORAL_ROLE", "field.temporal_role", "is unsupported")
+        if self.temporal_role != "none" and self.logical_type not in {"date", "timestamp_utc"}:
+            raise PreparationError(
+                "FIELD_TEMPORAL_TYPE",
+                "field.logical_type",
+                "temporal roles require date or UTC timestamp values",
+            )
+        if type(self.nullable) is not bool:
+            raise PreparationError("FIELD_NULLABLE", "field.nullable", "must be Boolean")
+        _identifier(self.source_id, "field.source_id")
+        if self.availability_column is not None:
+            _identifier(self.availability_column, "field.availability_column")
+        if (
+            self.temporal_role == "none"
+            and self.semantic_type != "target"
+            and self.availability_column is None
+        ):
+            raise PreparationError(
+                "FIELD_TEMPORAL_AMBIGUITY",
+                "field.availability_column",
+                "selected non-temporal fields require explicit availability semantics",
+            )
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "name": self.name,
+            "logical_type": self.logical_type,
+            "physical_type": self.physical_type,
+            "semantic_type": self.semantic_type,
+            "unit": self.unit,
+            "entity": self.entity,
+            "temporal_role": self.temporal_role,
+            "nullable": self.nullable,
+            "source_id": self.source_id,
+            "availability_column": self.availability_column,
+        }
+
+
+@dataclass(frozen=True)
+class LineageInput:
+    source_id: str
+    snapshot_digest: str
+    column: str
+
+    def __post_init__(self) -> None:
+        _identifier(self.source_id, "lineage.source_id")
+        _digest(self.snapshot_digest, "lineage.snapshot_digest")
+        _identifier(self.column, "lineage.column")
+
+    def to_dict(self) -> dict[str, str]:
+        return {
+            "source_id": self.source_id,
+            "snapshot_digest": self.snapshot_digest,
+            "column": self.column,
+        }
+
+
+@dataclass(frozen=True)
+class ColumnLineage:
+    output_column: str
+    inputs: tuple[LineageInput, ...]
+    operation_ids: tuple[str, ...]
+
+    def __post_init__(self) -> None:
+        _identifier(self.output_column, "lineage.output_column")
+        _tuple(self.inputs, "lineage.inputs", minimum=1, maximum=MAX_FIELDS)
+        if len(set(self.inputs)) != len(self.inputs):
+            raise PreparationError("CONTRACT_DUPLICATE", "lineage.inputs", "contains duplicates")
+        _identifiers(self.operation_ids, "lineage.operation_ids", minimum=0, maximum=MAX_OPERATIONS)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "output_column": self.output_column,
+            "inputs": [item.to_dict() for item in self.inputs],
+            "operation_ids": list(self.operation_ids),
+        }
+
+
+@dataclass(frozen=True)
+class OperationSpec:
+    """One allowlisted operation with a kind-specific immutable parameter shape."""
+
+    operation_id: str
+    source_id: str
+    kind: str
+    parameters: tuple[tuple[str, Any], ...]
+
+    def __post_init__(self) -> None:
+        _identifier(self.operation_id, "operation.operation_id")
+        _identifier(self.source_id, "operation.source_id")
+        if self.kind not in OPERATION_KINDS:
+            raise PreparationError("OPERATION_KIND", "operation.kind", "is not allowlisted")
+        if not isinstance(self.parameters, tuple):
+            raise PreparationError(
+                "OPERATION_PARAMETERS",
+                "operation.parameters",
+                "must be an immutable tuple",
+            )
+        names = tuple(name for name, _ in self.parameters if isinstance(name, str))
+        if len(names) != len(self.parameters) or names != _OPERATION_PARAMETERS[self.kind]:
+            raise PreparationError(
+                "OPERATION_PARAMETERS",
+                "operation.parameters",
+                f"{self.kind} parameters must be exactly {_OPERATION_PARAMETERS[self.kind]}",
+            )
+        values = dict(self.parameters)
+        if self.kind in {"trim", "case_normalize", "null_tokens", "strict_cast", "unit_convert"}:
+            _identifier(values["column"], "operation.parameters.column")
+        if self.kind == "case_normalize" and values["mode"] not in {"lower", "upper", "casefold"}:
+            raise PreparationError("OPERATION_MODE", "operation.parameters.mode", "is unsupported")
+        if self.kind == "null_tokens":
+            tokens = _tuple(
+                values["tokens"],
+                "operation.parameters.tokens",
+                minimum=1,
+                maximum=128,
+            )
+            checked_values: list[str] = []
+            for index, item in enumerate(tokens):
+                path = f"operation.parameters.tokens[{index}]"
+                if not isinstance(item, str) or len(item) > 256:
+                    raise PreparationError(
+                        "CONTRACT_TEXT",
+                        path,
+                        "must be 0..256 characters",
+                    )
+                if any(0xD800 <= ord(character) <= 0xDFFF for character in item):
+                    raise PreparationError(
+                        "CONTRACT_UNICODE",
+                        path,
+                        "contains an unpaired surrogate",
+                    )
+                checked_values.append(item)
+            checked = tuple(checked_values)
+            if checked != tuple(sorted(set(checked))):
+                raise PreparationError(
+                    "OPERATION_TOKENS",
+                    "operation.parameters.tokens",
+                    "must be unique and canonically sorted",
+                )
+        if self.kind == "strict_cast" and values["to_type"] not in LOGICAL_TYPES:
+            raise PreparationError(
+                "OPERATION_CAST_TYPE",
+                "operation.parameters.to_type",
+                "is unsupported",
+            )
+        if self.kind == "unit_convert":
+            if values["from_unit"] not in UNITS or values["to_unit"] not in UNITS:
+                raise PreparationError(
+                    "OPERATION_UNIT",
+                    "operation.parameters",
+                    "contains an unsupported unit",
+                )
+            if values["from_unit"] == values["to_unit"]:
+                raise PreparationError(
+                    "OPERATION_UNIT",
+                    "operation.parameters",
+                    "source and target units must differ",
+                )
+        if self.kind == "entity_resolve":
+            _identifier(values["column"], "operation.parameters.column")
+            _identifier(values["entity_type"], "operation.parameters.entity_type")
+            aliases = _pairs(
+                values["aliases"],
+                "operation.parameters.aliases",
+                maximum=MAX_ALIASES,
+            )
+            canonical_values = {canonical for _, canonical in aliases}
+            if any(
+                alias in canonical_values and alias != canonical for alias, canonical in aliases
+            ):
+                raise PreparationError(
+                    "ENTITY_AMBIGUOUS",
+                    "operation.parameters.aliases",
+                    "a canonical entity is also mapped to a different entity",
+                )
+        if self.kind == "rename":
+            mappings = _pairs(
+                values["mappings"],
+                "operation.parameters.mappings",
+                maximum=MAX_FIELDS,
+            )
+            for index, (old, new) in enumerate(mappings):
+                _identifier(old, f"operation.parameters.mappings[{index}][0]")
+                _identifier(new, f"operation.parameters.mappings[{index}][1]")
+            if len({new for _, new in mappings}) != len(mappings):
+                raise PreparationError(
+                    "OPERATION_RENAME",
+                    "operation.parameters.mappings",
+                    "target names must be unique",
+                )
+        if self.kind == "project":
+            _identifiers(values["columns"], "operation.parameters.columns")
+        if self.kind == "deduplicate":
+            _identifiers(values["keys"], "operation.parameters.keys")
+            authority = _pairs(
+                values["authority"],
+                "operation.parameters.authority",
+                maximum=MAX_FIELDS,
+                require_sorted=False,
+            )
+            for index, (column, direction) in enumerate(authority):
+                _identifier(column, f"operation.parameters.authority[{index}][0]")
+                if direction not in {"ascending", "descending"}:
+                    raise PreparationError(
+                        "OPERATION_DIRECTION",
+                        f"operation.parameters.authority[{index}][1]",
+                        "must be ascending or descending",
+                    )
+            if len({column for column, _ in authority}) != len(authority):
+                raise PreparationError(
+                    "CONTRACT_DUPLICATE",
+                    "operation.parameters.authority",
+                    "contains duplicate columns",
+                )
+
+    def parameter(self, name: str) -> Any:
+        return dict(self.parameters)[name]
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "operation_id": self.operation_id,
+            "source_id": self.source_id,
+            "kind": self.kind,
+            "parameters": {name: _thaw(value) for name, value in self.parameters},
+        }
+
+    @property
+    def parameters_digest(self) -> str:
+        return canonical_sha256(self.to_dict()["parameters"])
+
+
+@dataclass(frozen=True)
+class EqualityJoinSpec:
+    join_id: str
+    right_source_id: str
+    left_keys: tuple[str, ...]
+    right_keys: tuple[str, ...]
+    cardinality: str
+    suffix: str
+
+    def __post_init__(self) -> None:
+        _identifier(self.join_id, "join.join_id")
+        _identifier(self.right_source_id, "join.right_source_id")
+        left = _identifiers(self.left_keys, "join.left_keys")
+        right = _identifiers(self.right_keys, "join.right_keys")
+        if len(left) != len(right):
+            raise PreparationError("JOIN_KEYS", "join", "left and right key counts differ")
+        if self.cardinality not in CARDINALITIES:
+            raise PreparationError("JOIN_CARDINALITY", "join.cardinality", "is unsupported")
+        _identifier(self.suffix, "join.suffix")
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "kind": "equality_left",
+            "join_id": self.join_id,
+            "right_source_id": self.right_source_id,
+            "left_keys": list(self.left_keys),
+            "right_keys": list(self.right_keys),
+            "cardinality": self.cardinality,
+            "suffix": self.suffix,
+        }
+
+
+@dataclass(frozen=True)
+class AsOfJoinSpec:
+    join_id: str
+    right_source_id: str
+    left_by: tuple[str, ...]
+    right_by: tuple[str, ...]
+    left_time: str
+    left_cutoff: str
+    right_time: str
+    right_available_at: str
+    right_revision_time: str
+    direction: str
+    tolerance_seconds: int
+    revision_policy: str
+    question_cutoff: str
+    cardinality: str
+    suffix: str
+
+    def __post_init__(self) -> None:
+        _identifier(self.join_id, "join.join_id")
+        _identifier(self.right_source_id, "join.right_source_id")
+        left = _identifiers(self.left_by, "join.left_by")
+        right = _identifiers(self.right_by, "join.right_by")
+        if len(left) != len(right):
+            raise PreparationError("JOIN_KEYS", "join", "partition key counts differ")
+        for name in (
+            "left_time",
+            "left_cutoff",
+            "right_time",
+            "right_available_at",
+            "right_revision_time",
+        ):
+            _identifier(getattr(self, name), f"join.{name}")
+        if self.direction != "backward":
+            raise PreparationError("JOIN_DIRECTION", "join.direction", "only backward is allowed")
+        if type(self.tolerance_seconds) is not int or not 0 <= self.tolerance_seconds <= 31_536_000:
+            raise PreparationError(
+                "JOIN_TOLERANCE",
+                "join.tolerance_seconds",
+                "must be an integer between 0 and 31536000",
+            )
+        if self.revision_policy not in {"latest_available", "earliest_available"}:
+            raise PreparationError(
+                "JOIN_REVISION_POLICY",
+                "join.revision_policy",
+                "is unsupported",
+            )
+        parse_utc(self.question_cutoff, "join.question_cutoff")
+        if self.cardinality not in {"one_to_one", "many_to_one"}:
+            raise PreparationError(
+                "JOIN_CARDINALITY",
+                "join.cardinality",
+                "as-of joins require one_to_one or many_to_one",
+            )
+        _identifier(self.suffix, "join.suffix")
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "kind": "asof_left",
+            "join_id": self.join_id,
+            "right_source_id": self.right_source_id,
+            "left_by": list(self.left_by),
+            "right_by": list(self.right_by),
+            "left_time": self.left_time,
+            "left_cutoff": self.left_cutoff,
+            "right_time": self.right_time,
+            "right_available_at": self.right_available_at,
+            "right_revision_time": self.right_revision_time,
+            "direction": self.direction,
+            "tolerance_seconds": self.tolerance_seconds,
+            "revision_policy": self.revision_policy,
+            "question_cutoff": self.question_cutoff,
+            "cardinality": self.cardinality,
+            "suffix": self.suffix,
+        }
+
+
+JoinSpec = EqualityJoinSpec | AsOfJoinSpec
+
+
+@dataclass(frozen=True)
+class SourceTemporalEvidence:
+    source_id: str
+    snapshot_digest: str
+    fidelity: str
+    retrieval_time: str
+    event_time_column: str | None
+    available_at_column: str
+    revision_time_column: str | None
+
+    def __post_init__(self) -> None:
+        _identifier(self.source_id, "temporal.source_id")
+        _digest(self.snapshot_digest, "temporal.snapshot_digest")
+        if self.fidelity not in TEMPORAL_FIDELITIES:
+            raise PreparationError("TEMPORAL_FIDELITY", "temporal.fidelity", "is unsupported")
+        parse_utc(self.retrieval_time, "temporal.retrieval_time")
+        if self.event_time_column is not None:
+            _identifier(self.event_time_column, "temporal.event_time_column")
+        _identifier(self.available_at_column, "temporal.available_at_column")
+        if self.revision_time_column is not None:
+            _identifier(self.revision_time_column, "temporal.revision_time_column")
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "source_id": self.source_id,
+            "snapshot_digest": self.snapshot_digest,
+            "fidelity": self.fidelity,
+            "retrieval_time": self.retrieval_time,
+            "event_time_column": self.event_time_column,
+            "available_at_column": self.available_at_column,
+            "revision_time_column": self.revision_time_column,
+        }
+
+
+@dataclass(frozen=True)
+class TemporalPolicy:
+    analysis_kind: str
+    question_cutoff: str
+    row_cutoff_column: str | None
+
+    def __post_init__(self) -> None:
+        if self.analysis_kind not in {"point_in_time", "current_retrospective"}:
+            raise PreparationError(
+                "TEMPORAL_ANALYSIS_KIND",
+                "temporal.analysis_kind",
+                "is unsupported",
+            )
+        parse_utc(self.question_cutoff, "temporal.question_cutoff")
+        if self.row_cutoff_column is not None:
+            _identifier(self.row_cutoff_column, "temporal.row_cutoff_column")
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "analysis_kind": self.analysis_kind,
+            "question_cutoff": self.question_cutoff,
+            "row_cutoff_column": self.row_cutoff_column,
+        }
+
+
+@dataclass(frozen=True)
+class CategoryMapping:
+    input_value: str
+    output_value: str
+
+    def __post_init__(self) -> None:
+        _text(self.input_value, "target.mapping.input_value", maximum=256)
+        _text(self.output_value, "target.mapping.output_value", maximum=256)
+
+    def to_dict(self) -> dict[str, str]:
+        return {"input_value": self.input_value, "output_value": self.output_value}
+
+
+@dataclass(frozen=True)
+class TargetSpec:
+    operation: str
+    output_column: str
+    source_column: str
+    availability_time_column: str
+    cutoff_column: str
+    source_snapshot_digest: str
+    rationale: str
+    resolution_rule: str
+    horizon_seconds: int
+    mapping: tuple[CategoryMapping, ...] = ()
+    allow_null: bool = False
+
+    def __post_init__(self) -> None:
+        if self.operation not in {"exact_copy", "categorical_map"}:
+            raise PreparationError("TARGET_OPERATION", "target.operation", "is unsupported")
+        for name in (
+            "output_column",
+            "source_column",
+            "availability_time_column",
+            "cutoff_column",
+        ):
+            _identifier(getattr(self, name), f"target.{name}")
+        if self.output_column == self.source_column:
+            raise PreparationError("TARGET_COLUMN", "target.output_column", "must be a new column")
+        _digest(self.source_snapshot_digest, "target.source_snapshot_digest")
+        _text(self.rationale, "target.rationale")
+        _text(self.resolution_rule, "target.resolution_rule")
+        if type(self.horizon_seconds) is not int or not 0 <= self.horizon_seconds <= 315_360_000:
+            raise PreparationError(
+                "TARGET_HORIZON",
+                "target.horizon_seconds",
+                "must be an integer between 0 and 315360000",
+            )
+        _tuple(self.mapping, "target.mapping", maximum=1_024)
+        if self.operation == "exact_copy" and self.mapping:
+            raise PreparationError(
+                "TARGET_MAPPING",
+                "target.mapping",
+                "must be empty for exact_copy",
+            )
+        if self.operation == "categorical_map":
+            if not self.mapping:
+                raise PreparationError(
+                    "TARGET_MAPPING",
+                    "target.mapping",
+                    "must be non-empty for categorical_map",
+                )
+            inputs = tuple(item.input_value for item in self.mapping)
+            if inputs != tuple(sorted(set(inputs))):
+                raise PreparationError(
+                    "TARGET_MAPPING",
+                    "target.mapping",
+                    "must be unique and canonically sorted",
+                )
+        if type(self.allow_null) is not bool:
+            raise PreparationError("TARGET_NULL", "target.allow_null", "must be Boolean")
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "operation": self.operation,
+            "output_column": self.output_column,
+            "source_column": self.source_column,
+            "availability_time_column": self.availability_time_column,
+            "cutoff_column": self.cutoff_column,
+            "source_snapshot_digest": self.source_snapshot_digest,
+            "rationale": self.rationale,
+            "resolution_rule": self.resolution_rule,
+            "horizon_seconds": self.horizon_seconds,
+            "mapping": [item.to_dict() for item in self.mapping],
+            "allow_null": self.allow_null,
+        }
+
+
+@dataclass(frozen=True)
+class MissingnessLimit:
+    column: str
+    maximum_nulls: int
+
+    def __post_init__(self) -> None:
+        _identifier(self.column, "quality.missingness.column")
+        if type(self.maximum_nulls) is not int or not 0 <= self.maximum_nulls <= MAX_ROWS:
+            raise PreparationError(
+                "QUALITY_THRESHOLD",
+                "quality.missingness.maximum_nulls",
+                "is outside the supported range",
+            )
+
+    def to_dict(self) -> dict[str, Any]:
+        return {"column": self.column, "maximum_nulls": self.maximum_nulls}
+
+
+@dataclass(frozen=True)
+class QualitySpec:
+    expected_fields: tuple[FieldSpec, ...]
+    grain: tuple[str, ...]
+    missingness: tuple[MissingnessLimit, ...]
+    maximum_outliers: int
+    temporal_column: str | None
+    expected_frequency: str
+    maximum_missing_periods: int
+    maximum_join_multiplier_numerator: int
+    maximum_join_multiplier_denominator: int
+    minimum_rows: int
+    maximum_rows: int
+
+    def __post_init__(self) -> None:
+        _tuple(self.expected_fields, "quality.expected_fields", minimum=1, maximum=MAX_FIELDS)
+        names = tuple(field.name for field in self.expected_fields)
+        if len(set(names)) != len(names):
+            raise PreparationError(
+                "CONTRACT_DUPLICATE",
+                "quality.expected_fields",
+                "duplicates names",
+            )
+        _identifiers(self.grain, "quality.grain")
+        _tuple(self.missingness, "quality.missingness", maximum=MAX_FIELDS)
+        missing_columns = tuple(item.column for item in self.missingness)
+        if missing_columns != tuple(sorted(set(missing_columns))):
+            raise PreparationError(
+                "CONTRACT_ORDER",
+                "quality.missingness",
+                "must be unique and sorted by column",
+            )
+        if any(column not in names for column in (*self.grain, *missing_columns)):
+            raise PreparationError("QUALITY_REFERENCE", "quality", "references an unknown column")
+        if type(self.maximum_outliers) is not int or not 0 <= self.maximum_outliers <= MAX_ROWS:
+            raise PreparationError("QUALITY_THRESHOLD", "quality.maximum_outliers", "is invalid")
+        if self.temporal_column is not None and self.temporal_column not in names:
+            raise PreparationError("QUALITY_REFERENCE", "quality.temporal_column", "is unknown")
+        if self.expected_frequency not in {"none", "daily", "hourly"}:
+            raise PreparationError(
+                "QUALITY_FREQUENCY",
+                "quality.expected_frequency",
+                "is unsupported",
+            )
+        if (self.temporal_column is None) != (self.expected_frequency == "none"):
+            raise PreparationError(
+                "QUALITY_FREQUENCY",
+                "quality",
+                "temporal column and frequency must be declared together",
+            )
+        for name in (
+            "maximum_missing_periods",
+            "maximum_join_multiplier_numerator",
+            "maximum_join_multiplier_denominator",
+            "minimum_rows",
+            "maximum_rows",
+        ):
+            value = getattr(self, name)
+            minimum = 1 if name == "maximum_join_multiplier_denominator" else 0
+            if type(value) is not int or not minimum <= value <= MAX_ROWS:
+                raise PreparationError("QUALITY_THRESHOLD", f"quality.{name}", "is invalid")
+        if self.minimum_rows > self.maximum_rows:
+            raise PreparationError("QUALITY_THRESHOLD", "quality", "row bounds are reversed")
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "expected_fields": [item.to_dict() for item in self.expected_fields],
+            "grain": list(self.grain),
+            "missingness": [item.to_dict() for item in self.missingness],
+            "maximum_outliers": self.maximum_outliers,
+            "temporal_column": self.temporal_column,
+            "expected_frequency": self.expected_frequency,
+            "maximum_missing_periods": self.maximum_missing_periods,
+            "maximum_join_multiplier_numerator": self.maximum_join_multiplier_numerator,
+            "maximum_join_multiplier_denominator": self.maximum_join_multiplier_denominator,
+            "minimum_rows": self.minimum_rows,
+            "maximum_rows": self.maximum_rows,
+        }
+
+
+@dataclass(frozen=True)
+class PreparationPlan:
+    contract_version: str
+    plan_id: str
+    primary_source_id: str
+    operations: tuple[OperationSpec, ...]
+    joins: tuple[JoinSpec, ...]
+    output_columns: tuple[str, ...]
+    temporal_evidence: tuple[SourceTemporalEvidence, ...]
+    temporal_policy: TemporalPolicy
+    target_policy: str
+    target: TargetSpec | None
+    quality: QualitySpec
+
+    def __post_init__(self) -> None:
+        if self.contract_version != PREPARATION_CONTRACT_VERSION:
+            raise PreparationError("PLAN_VERSION", "plan.contract_version", "is unsupported")
+        _identifier(self.plan_id, "plan.plan_id")
+        _identifier(self.primary_source_id, "plan.primary_source_id")
+        _tuple(self.operations, "plan.operations", maximum=MAX_OPERATIONS)
+        operation_ids = tuple(item.operation_id for item in self.operations)
+        if len(set(operation_ids)) != len(operation_ids):
+            raise PreparationError(
+                "CONTRACT_DUPLICATE",
+                "plan.operations",
+                "duplicates operation IDs",
+            )
+        _tuple(self.joins, "plan.joins", maximum=MAX_JOINS)
+        join_ids = tuple(item.join_id for item in self.joins)
+        if len(set(join_ids)) != len(join_ids):
+            raise PreparationError("CONTRACT_DUPLICATE", "plan.joins", "duplicates join IDs")
+        _identifiers(self.output_columns, "plan.output_columns")
+        _tuple(
+            self.temporal_evidence,
+            "plan.temporal_evidence",
+            minimum=1,
+            maximum=MAX_FIELDS,
+        )
+        source_ids = tuple(item.source_id for item in self.temporal_evidence)
+        if source_ids != tuple(sorted(set(source_ids))):
+            raise PreparationError(
+                "CONTRACT_ORDER",
+                "plan.temporal_evidence",
+                "must be unique and sorted by source ID",
+            )
+        if self.target_policy not in {"none", "justified"}:
+            raise PreparationError("TARGET_POLICY", "plan.target_policy", "is unsupported")
+        if (self.target_policy == "none") != (self.target is None):
+            raise PreparationError(
+                "TARGET_POLICY",
+                "plan.target",
+                "must be absent only when target policy is none",
+            )
+        if self.target is not None:
+            forbidden = set(self.quality.grain)
+            for operation in self.operations:
+                if operation.kind == "deduplicate":
+                    forbidden.update(operation.parameter("keys"))
+                elif operation.kind not in {"project", "rename"}:
+                    forbidden.add(operation.parameter("column"))
+            for join in self.joins:
+                if isinstance(join, EqualityJoinSpec):
+                    forbidden.update(join.left_keys)
+                    forbidden.update(join.right_keys)
+                else:
+                    forbidden.update(join.left_by)
+                    forbidden.update(join.right_by)
+                    forbidden.update(
+                        {
+                            join.left_time,
+                            join.left_cutoff,
+                            join.right_time,
+                            join.right_available_at,
+                            join.right_revision_time,
+                        }
+                    )
+            if self.target.source_column in forbidden:
+                raise PreparationError(
+                    "TARGET_ISOLATION",
+                    "plan.target.source_column",
+                    "cannot be a grain, join, temporal, or cleaning input",
+                )
+
+    @property
+    def digest(self) -> str:
+        """Hash the ``to_dict`` encoding of this plan.
+
+        Distinct from ``repair.adapters.plan_digest``, which hashes the raw dataclass
+        fields instead. ``to_dict`` adds a ``kind`` discriminator to each join and turns
+        each operation's ``parameters`` pair-tuple into a mapping, so the two digests never
+        agree for the same plan. Use this one wherever a stored digest was produced by
+        ``PreparationResult`` or the Studio wire boundary.
+        """
+
+        return canonical_sha256(self.to_dict())
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "contract_version": self.contract_version,
+            "plan_id": self.plan_id,
+            "primary_source_id": self.primary_source_id,
+            "operations": [item.to_dict() for item in self.operations],
+            "joins": [item.to_dict() for item in self.joins],
+            "output_columns": list(self.output_columns),
+            "temporal_evidence": [item.to_dict() for item in self.temporal_evidence],
+            "temporal_policy": self.temporal_policy.to_dict(),
+            "target_policy": self.target_policy,
+            "target": self.target.to_dict() if self.target is not None else None,
+            "quality": self.quality.to_dict(),
+        }
+
+
+def _thaw(value: Any) -> Any:
+    """Convert frozen tuples to lists so a value can be canonically serialized.
+
+    Both branches return the same thing; the pair-tuple test is vestigial.
+    """
+
+    if isinstance(value, tuple):
+        if value and all(isinstance(item, tuple) and len(item) == 2 for item in value):
+            return [_thaw(item) for item in value]
+        return [_thaw(item) for item in value]
+    return value
+
+
+__all__ = [
+    "BLOCKING_SEVERITIES",
+    "CARDINALITIES",
+    "JOIN_AUDIT_VERSION",
+    "MAX_FIELDS",
+    "MAX_ROWS",
+    "OPERATION_AUDIT_VERSION",
+    "PHYSICAL_TYPES",
+    "PREPARATION_CONTRACT_VERSION",
+    "PROFILE_VERSION",
+    "QUALITY_REPORT_VERSION",
+    "TARGET_RATIONALE_VERSION",
+    "TEMPORAL_REPORT_VERSION",
+    "AsOfJoinSpec",
+    "CategoryMapping",
+    "ColumnLineage",
+    "EqualityJoinSpec",
+    "FieldSpec",
+    "JoinSpec",
+    "LineageInput",
+    "MissingnessLimit",
+    "OperationSpec",
+    "PreparationPlan",
+    "QualitySpec",
+    "SourceTemporalEvidence",
+    "TargetSpec",
+    "TemporalPolicy",
+    "parse_utc",
+]