mostlyright-data 0.9.0__py3-none-any.whl

mostlyright/data_harness/preparation/gates.py

@@ -0,0 +1,751 @@
+"""Deterministic temporal, target, and analysis-readiness quality gates."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, replace
+from datetime import date, datetime, timedelta
+from itertools import pairwise
+from typing import Any
+
+from mostlyright.data_harness.canonical import canonical_sha256
+from mostlyright.data_harness.preparation.contracts import (
+    QUALITY_CHECK_POLICY,
+    QUALITY_REPORT_VERSION,
+    TARGET_RATIONALE_VERSION,
+    TEMPORAL_REPORT_VERSION,
+    ColumnLineage,
+    QualitySpec,
+    SourceTemporalEvidence,
+    TargetSpec,
+    TemporalPolicy,
+    parse_utc,
+)
+from mostlyright.data_harness.preparation.errors import PreparationError
+from mostlyright.data_harness.preparation.joins import JoinAudit
+from mostlyright.data_harness.preparation.profile import TableProfile, profile_table
+from mostlyright.data_harness.preparation.table import TableState, validate_columns
+
+_CHECK_POLICY = QUALITY_CHECK_POLICY
+
+
+@dataclass(frozen=True)
+class TemporalFinding:
+    code: str
+    source_id: str
+    column: str | None
+    row_index: int | None
+    detail: str
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.code, str) or not self.code.startswith("TEMPORAL_"):
+            raise PreparationError("TEMPORAL_FINDING", "temporal.finding.code", "is invalid")
+        if not isinstance(self.source_id, str) or not self.source_id:
+            raise PreparationError("TEMPORAL_FINDING", "temporal.finding.source_id", "is invalid")
+        if self.row_index is not None and (type(self.row_index) is not int or self.row_index < 0):
+            raise PreparationError(
+                "TEMPORAL_FINDING",
+                "temporal.finding.row_index",
+                "must be a nonnegative integer",
+            )
+        if not isinstance(self.detail, str) or not self.detail:
+            raise PreparationError("TEMPORAL_FINDING", "temporal.finding.detail", "is invalid")
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "code": self.code,
+            "severity": "blocker",
+            "source_id": self.source_id,
+            "column": self.column,
+            "row_index": self.row_index,
+            "detail": self.detail,
+        }
+
+
+@dataclass(frozen=True)
+class TemporalReport:
+    schema_version: str
+    analysis_kind: str
+    question_cutoff: str
+    checked_sources: tuple[str, ...]
+    checked_cells: int
+    findings: tuple[TemporalFinding, ...]
+    status: str
+
+    def __post_init__(self) -> None:
+        if self.schema_version != TEMPORAL_REPORT_VERSION:
+            raise PreparationError(
+                "TEMPORAL_REPORT_VERSION",
+                "temporal.schema_version",
+                "unsupported",
+            )
+        if self.status not in {"passed", "failed"}:
+            raise PreparationError("TEMPORAL_REPORT_STATUS", "temporal.status", "unsupported")
+        if (self.status == "passed") != (not self.findings):
+            raise PreparationError(
+                "TEMPORAL_REPORT_STATUS",
+                "temporal.status",
+                "does not reconcile",
+            )
+
+    @property
+    def digest(self) -> str:
+        return canonical_sha256(self.to_dict())
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "schema_version": self.schema_version,
+            "analysis_kind": self.analysis_kind,
+            "question_cutoff": self.question_cutoff,
+            "checked_sources": list(self.checked_sources),
+            "checked_cells": self.checked_cells,
+            "findings": [item.to_dict() for item in self.findings],
+            "status": self.status,
+        }
+
+
+@dataclass(frozen=True)
+class TargetRationale:
+    schema_version: str
+    output_column: str
+    operation: str
+    source_column: str
+    source_snapshot_digest: str
+    resolution_rule: str
+    horizon_seconds: int
+    availability_time_column: str
+    cutoff_column: str
+    mapping_digest: str | None
+    rationale: str
+    verified_rows: int
+
+    def __post_init__(self) -> None:
+        if self.schema_version != TARGET_RATIONALE_VERSION:
+            raise PreparationError(
+                "TARGET_RATIONALE_VERSION", "target.schema_version", "unsupported"
+            )
+        if type(self.horizon_seconds) is not int or self.horizon_seconds < 0:
+            raise PreparationError("TARGET_RATIONALE", "target.horizon_seconds", "is invalid")
+        if type(self.verified_rows) is not int or self.verified_rows < 0:
+            raise PreparationError("TARGET_RATIONALE", "target.verified_rows", "is invalid")
+        if not _is_digest(self.source_snapshot_digest):
+            raise PreparationError(
+                "TARGET_RATIONALE",
+                "target.source_snapshot_digest",
+                "is invalid",
+            )
+        if self.mapping_digest is not None and not _is_digest(self.mapping_digest):
+            raise PreparationError("TARGET_RATIONALE", "target.mapping_digest", "is invalid")
+
+    @property
+    def digest(self) -> str:
+        return canonical_sha256(self.to_dict())
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "schema_version": self.schema_version,
+            "output_column": self.output_column,
+            "operation": self.operation,
+            "source_column": self.source_column,
+            "source_snapshot_digest": self.source_snapshot_digest,
+            "resolution_rule": self.resolution_rule,
+            "horizon_seconds": self.horizon_seconds,
+            "availability_time_column": self.availability_time_column,
+            "cutoff_column": self.cutoff_column,
+            "mapping_digest": self.mapping_digest,
+            "rationale": self.rationale,
+            "verified_rows": self.verified_rows,
+        }
+
+
+@dataclass(frozen=True)
+class QualityCheck:
+    check_id: str
+    status: str
+    severity: str
+    threshold_id: str
+    observed: tuple[tuple[str, Any], ...]
+
+    def __post_init__(self) -> None:
+        expected = _CHECK_POLICY.get(self.check_id)
+        if expected != (self.severity, self.threshold_id):
+            raise PreparationError(
+                "QUALITY_POLICY",
+                f"quality.{self.check_id}",
+                "severity or threshold identity is not policy-owned",
+            )
+        if self.status not in {"passed", "failed"}:
+            raise PreparationError("QUALITY_STATUS", f"quality.{self.check_id}", "is unsupported")
+        names = tuple(name for name, _ in self.observed)
+        if names != tuple(sorted(set(names))):
+            raise PreparationError(
+                "QUALITY_EVIDENCE",
+                f"quality.{self.check_id}",
+                "observed evidence must be unique and canonically ordered",
+            )
+        canonical_sha256({name: value for name, value in self.observed})
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "check_id": self.check_id,
+            "status": self.status,
+            "severity": self.severity,
+            "threshold_id": self.threshold_id,
+            "observed": {name: value for name, value in self.observed},
+        }
+
+
+@dataclass(frozen=True)
+class QualityReport:
+    schema_version: str
+    checks: tuple[QualityCheck, ...]
+    status: str
+
+    def __post_init__(self) -> None:
+        if self.schema_version != QUALITY_REPORT_VERSION:
+            raise PreparationError("QUALITY_VERSION", "quality.schema_version", "is unsupported")
+        if tuple(item.check_id for item in self.checks) != tuple(_CHECK_POLICY):
+            raise PreparationError(
+                "QUALITY_CHECK_SET",
+                "quality.checks",
+                "check set/order is not exact",
+            )
+        expected = "failed" if any(item.status == "failed" for item in self.checks) else "passed"
+        if self.status != expected:
+            raise PreparationError("QUALITY_STATUS", "quality.status", "does not reconcile checks")
+
+    @property
+    def digest(self) -> str:
+        return canonical_sha256(self.to_dict())
+
+    @property
+    def findings(self) -> tuple[QualityCheck, ...]:
+        return tuple(item for item in self.checks if item.status == "failed")
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "schema_version": self.schema_version,
+            "checks": [item.to_dict() for item in self.checks],
+            "status": self.status,
+        }
+
+
+def validate_temporal_safety(
+    state: TableState,
+    *,
+    evidence: tuple[SourceTemporalEvidence, ...],
+    policy: TemporalPolicy,
+) -> TemporalReport:
+    """Audit fidelity, availability, revisions, and row/question cutoffs."""
+
+    evidence_by_source = {item.source_id: item for item in evidence}
+    if len(evidence_by_source) != len(evidence):
+        raise PreparationError("TEMPORAL_EVIDENCE", "temporal.evidence", "duplicates source IDs")
+    sources = {item.source_id for lineage in state.lineage for item in lineage.inputs}
+    if set(evidence_by_source) != sources:
+        raise PreparationError(
+            "TEMPORAL_EVIDENCE",
+            "temporal.evidence",
+            "does not exactly cover output lineage sources",
+        )
+    for item in evidence:
+        if item.snapshot_digest not in state.snapshot_digests:
+            raise PreparationError(
+                "TEMPORAL_EVIDENCE",
+                item.source_id,
+                "snapshot digest is not bound to the table",
+            )
+        _validate_temporal_column(
+            state,
+            item.source_id,
+            item.available_at_column,
+            "available_at",
+        )
+        if item.event_time_column is not None:
+            _validate_temporal_column(
+                state,
+                item.source_id,
+                item.event_time_column,
+                "event_time",
+            )
+        if item.revision_time_column is not None:
+            _validate_temporal_column(
+                state,
+                item.source_id,
+                item.revision_time_column,
+                "revision_time",
+            )
+    question_cutoff = parse_utc(policy.question_cutoff, "temporal.question_cutoff")
+    row_cutoff_index = (
+        state.index(policy.row_cutoff_column) if policy.row_cutoff_column is not None else None
+    )
+    findings: list[TemporalFinding] = []
+    checked_cells = 0
+    for source_id in sorted(sources):
+        source = evidence_by_source[source_id]
+        retrieval = parse_utc(source.retrieval_time, f"temporal.{source_id}.retrieval_time")
+        if source.fidelity == "unknown":
+            findings.append(
+                TemporalFinding(
+                    code="TEMPORAL_FIDELITY_UNKNOWN",
+                    source_id=source_id,
+                    column=None,
+                    row_index=None,
+                    detail="unknown fidelity cannot support analysis readiness",
+                )
+            )
+        elif source.fidelity == "latest_only" and policy.analysis_kind == "point_in_time":
+            findings.append(
+                TemporalFinding(
+                    code="TEMPORAL_LATEST_ONLY",
+                    source_id=source_id,
+                    column=None,
+                    row_index=None,
+                    detail="latest-only evidence cannot support point-in-time analysis",
+                )
+            )
+        elif source.fidelity in {"reconstructed", "latest_only"} and (
+            policy.analysis_kind != "current_retrospective" or retrieval > question_cutoff
+        ):
+            findings.append(
+                TemporalFinding(
+                    code="TEMPORAL_RECONSTRUCTED_CUTOFF",
+                    source_id=source_id,
+                    column=None,
+                    row_index=None,
+                    detail="reconstructed/latest evidence is unavailable by the declared cutoff",
+                )
+            )
+    for field_index, (field, lineage) in enumerate(zip(state.fields, state.lineage, strict=True)):
+        if field.semantic_type == "target" or all(
+            item.source_id not in sources for item in lineage.inputs
+        ):
+            continue
+        if field.temporal_role != "none":
+            continue
+        if field.availability_column is None:
+            findings.append(
+                TemporalFinding(
+                    code="TEMPORAL_AVAILABILITY_MISSING",
+                    source_id=field.source_id,
+                    column=field.name,
+                    row_index=None,
+                    detail="selected field has no availability column",
+                )
+            )
+            continue
+        availability_index = state.index(field.availability_column)
+        availability_field = state.fields[availability_index]
+        source_evidence = evidence_by_source[field.source_id]
+        if (
+            availability_field.source_id != field.source_id
+            or availability_field.temporal_role != "available_at"
+            or field.availability_column != source_evidence.available_at_column
+        ):
+            findings.append(
+                TemporalFinding(
+                    code="TEMPORAL_AVAILABILITY_MISMATCH",
+                    source_id=field.source_id,
+                    column=field.name,
+                    row_index=None,
+                    detail="availability semantics are not bound to the same source evidence",
+                )
+            )
+            continue
+        for row_index, row in enumerate(state.rows):
+            if row[field_index] is None:
+                continue
+            checked_cells += 1
+            cutoff = (
+                _instant(row[row_cutoff_index], "temporal.row_cutoff")
+                if row_cutoff_index is not None
+                else question_cutoff
+            )
+            if cutoff > question_cutoff:
+                findings.append(
+                    TemporalFinding(
+                        code="TEMPORAL_ROW_CUTOFF",
+                        source_id=field.source_id,
+                        column=field.name,
+                        row_index=row_index,
+                        detail="row cutoff exceeds the question cutoff",
+                    )
+                )
+                continue
+            available = _instant(row[availability_index], "temporal.available_at")
+            if available > cutoff:
+                findings.append(
+                    TemporalFinding(
+                        code="TEMPORAL_LEAKAGE",
+                        source_id=field.source_id,
+                        column=field.name,
+                        row_index=row_index,
+                        detail="selected value became available after its cutoff",
+                    )
+                )
+    for source in evidence:
+        if source.revision_time_column is None:
+            continue
+        try:
+            revision_index = state.index(source.revision_time_column)
+        except PreparationError:
+            continue
+        for row_index, row in enumerate(state.rows):
+            if row[revision_index] is None:
+                continue
+            cutoff = (
+                _instant(row[row_cutoff_index], "temporal.row_cutoff")
+                if row_cutoff_index is not None
+                else question_cutoff
+            )
+            if _instant(row[revision_index], "temporal.revision_time") > cutoff:
+                findings.append(
+                    TemporalFinding(
+                        code="TEMPORAL_FUTURE_REVISION",
+                        source_id=source.source_id,
+                        column=source.revision_time_column,
+                        row_index=row_index,
+                        detail="selected revision is later than its cutoff",
+                    )
+                )
+    return TemporalReport(
+        schema_version=TEMPORAL_REPORT_VERSION,
+        analysis_kind=policy.analysis_kind,
+        question_cutoff=policy.question_cutoff,
+        checked_sources=tuple(sorted(sources)),
+        checked_cells=checked_cells,
+        findings=tuple(findings),
+        status="failed" if findings else "passed",
+    )
+
+
+def construct_target(
+    state: TableState,
+    spec: TargetSpec | None,
+    *,
+    target_policy: str,
+) -> tuple[TableState, TargetRationale | None]:
+    """Construct only a justified, source-derived, cutoff-safe target."""
+
+    if target_policy == "none":
+        if spec is not None:
+            raise PreparationError("TARGET_POLICY", "target", "target is unjustified")
+        return state, None
+    if target_policy != "justified" or spec is None:
+        raise PreparationError("TARGET_POLICY", "target", "justified target evidence is required")
+    if spec.output_column in state.columns:
+        raise PreparationError("TARGET_COLUMN", "target.output_column", "already exists")
+    source_index = state.index(spec.source_column)
+    availability_index = state.index(spec.availability_time_column)
+    cutoff_index = state.index(spec.cutoff_column)
+    source_field = state.fields[source_index]
+    source_lineage = state.lineage[source_index]
+    if source_field.semantic_type == "target":
+        raise PreparationError(
+            "TARGET_ISOLATION",
+            "target.source_column",
+            "cannot derive from a target",
+        )
+    if spec.source_snapshot_digest not in {item.snapshot_digest for item in source_lineage.inputs}:
+        raise PreparationError(
+            "TARGET_SOURCE",
+            "target.source_snapshot_digest",
+            "does not bind the source column lineage",
+        )
+    mapping = {item.input_value: item.output_value for item in spec.mapping}
+    values: list[Any] = []
+    for row_index, row in enumerate(state.rows):
+        available = _instant(row[availability_index], "target.available_at")
+        cutoff = _instant(row[cutoff_index], "target.cutoff")
+        if available > cutoff:
+            raise PreparationError(
+                "TARGET_LEAKAGE",
+                f"target.row[{row_index}]",
+                "target resolution became available after the cutoff",
+            )
+        source_value = row[source_index]
+        if source_value is None:
+            if not spec.allow_null:
+                raise PreparationError(
+                    "TARGET_NULL",
+                    f"target.row[{row_index}]",
+                    "null target source is forbidden",
+                )
+            values.append(None)
+        elif spec.operation == "exact_copy":
+            values.append(source_value)
+        else:
+            if not isinstance(source_value, str):
+                raise PreparationError(
+                    "TARGET_MAPPING",
+                    f"target.row[{row_index}]",
+                    "categorical mapping requires string inputs",
+                )
+            try:
+                values.append(mapping[source_value])
+            except KeyError:
+                raise PreparationError(
+                    "TARGET_MAPPING",
+                    f"target.row[{row_index}]",
+                    "categorical mapping is not total",
+                ) from None
+    output_field = replace(
+        source_field,
+        name=spec.output_column,
+        semantic_type="target",
+        nullable=spec.allow_null,
+        availability_column=spec.availability_time_column,
+    )
+    rows = tuple((*row, value) for row, value in zip(state.rows, values, strict=True))
+    operation_id = f"target.{spec.output_column}"
+    lineage = (
+        *state.lineage,
+        ColumnLineage(
+            output_column=spec.output_column,
+            inputs=source_lineage.inputs,
+            operation_ids=(*source_lineage.operation_ids, operation_id),
+        ),
+    )
+    output = state.replace(
+        fields=(*state.fields, output_field),
+        rows=rows,
+        lineage=lineage,
+    )
+    rationale = TargetRationale(
+        schema_version=TARGET_RATIONALE_VERSION,
+        output_column=spec.output_column,
+        operation=spec.operation,
+        source_column=spec.source_column,
+        source_snapshot_digest=spec.source_snapshot_digest,
+        resolution_rule=spec.resolution_rule,
+        horizon_seconds=spec.horizon_seconds,
+        availability_time_column=spec.availability_time_column,
+        cutoff_column=spec.cutoff_column,
+        mapping_digest=(
+            canonical_sha256([item.to_dict() for item in spec.mapping]) if spec.mapping else None
+        ),
+        rationale=spec.rationale,
+        verified_rows=len(state.rows),
+    )
+    return output, rationale
+
+
+def validate_quality(
+    state: TableState,
+    *,
+    spec: QualitySpec,
+    joins: tuple[JoinAudit, ...],
+    temporal: TemporalReport,
+) -> tuple[TableProfile, QualityReport]:
+    """Run the complete fixed-severity analysis-readiness gate set."""
+
+    profile = profile_table(state, key_columns=spec.grain)
+    expected_schema = [field.to_dict() for field in spec.expected_fields]
+    actual_schema = [field.to_dict() for field in state.fields]
+    checks: list[QualityCheck] = []
+    checks.append(
+        _check(
+            "schema",
+            expected_schema == actual_schema,
+            (
+                ("actual_schema_digest", canonical_sha256(actual_schema)),
+                ("expected_schema_digest", canonical_sha256(expected_schema)),
+            ),
+        )
+    )
+    row_bounds_pass = spec.minimum_rows <= len(state.rows) <= spec.maximum_rows
+    checks.append(
+        _check(
+            "row_bounds",
+            row_bounds_pass,
+            (
+                ("maximum_rows", spec.maximum_rows),
+                ("minimum_rows", spec.minimum_rows),
+                ("observed_rows", len(state.rows)),
+            ),
+        )
+    )
+    field_profile = {item.name: item for item in profile.fields}
+    missing_failures = tuple(
+        (item.column, field_profile[item.column].null_count, item.maximum_nulls)
+        for item in spec.missingness
+        if field_profile[item.column].null_count > item.maximum_nulls
+    )
+    checks.append(
+        _check(
+            "missingness",
+            not missing_failures,
+            (
+                ("failed_columns", [list(item) for item in missing_failures]),
+                ("threshold_count", len(spec.missingness)),
+            ),
+        )
+    )
+    grain_indexes = validate_columns(state, spec.grain, "quality.grain")
+    null_grain = sum(any(row[index] is None for index in grain_indexes) for row in state.rows)
+    checks.append(
+        _check(
+            "grain",
+            null_grain == 0 and profile.duplicate_key_count == 0,
+            (
+                ("duplicate_grain_rows", profile.duplicate_key_count),
+                ("null_grain_rows", null_grain),
+            ),
+        )
+    )
+    checks.append(
+        _check(
+            "duplicates",
+            profile.duplicate_row_count == 0,
+            (("duplicate_rows", profile.duplicate_row_count),),
+        )
+    )
+    multiplier_failures = tuple(
+        audit.join_id
+        for audit in joins
+        if (
+            audit.row_multiplier_numerator * spec.maximum_join_multiplier_denominator
+            > audit.row_multiplier_denominator * spec.maximum_join_multiplier_numerator
+        )
+    )
+    checks.append(
+        _check(
+            "join_multiplier",
+            not multiplier_failures,
+            (
+                ("failed_join_ids", list(multiplier_failures)),
+                (
+                    "maximum_denominator",
+                    spec.maximum_join_multiplier_denominator,
+                ),
+                ("maximum_numerator", spec.maximum_join_multiplier_numerator),
+            ),
+        )
+    )
+    checks.append(
+        _check(
+            "temporal",
+            temporal.status == "passed",
+            (
+                ("finding_codes", [item.code for item in temporal.findings]),
+                ("temporal_report_digest", temporal.digest),
+            ),
+        )
+    )
+    total_outliers = sum(item.outlier_count for item in profile.fields)
+    checks.append(
+        _check(
+            "outliers",
+            total_outliers <= spec.maximum_outliers,
+            (
+                ("maximum_outliers", spec.maximum_outliers),
+                ("observed_outliers", total_outliers),
+            ),
+        )
+    )
+    missing_periods = _missing_periods(state, spec)
+    checks.append(
+        _check(
+            "missing_periods",
+            missing_periods <= spec.maximum_missing_periods,
+            (
+                ("maximum_missing_periods", spec.maximum_missing_periods),
+                ("observed_missing_periods", missing_periods),
+            ),
+        )
+    )
+    report = QualityReport(
+        schema_version=QUALITY_REPORT_VERSION,
+        checks=tuple(checks),
+        status="failed" if any(item.status == "failed" for item in checks) else "passed",
+    )
+    return profile, report
+
+
+def _check(
+    check_id: str,
+    passed: bool,
+    observed: tuple[tuple[str, Any], ...],
+) -> QualityCheck:
+    severity, threshold = _CHECK_POLICY[check_id]
+    return QualityCheck(
+        check_id=check_id,
+        status="passed" if passed else "failed",
+        severity=severity,
+        threshold_id=threshold,
+        observed=observed,
+    )
+
+
+def _missing_periods(state: TableState, spec: QualitySpec) -> int:
+    if spec.expected_frequency == "none" or spec.temporal_column is None:
+        return 0
+    temporal_index = state.index(spec.temporal_column)
+    partition_columns = tuple(column for column in spec.grain if column != spec.temporal_column)
+    partition_indexes = tuple(state.index(column) for column in partition_columns)
+    groups: dict[tuple[Any, ...], list[datetime | date]] = {}
+    for row in state.rows:
+        value = row[temporal_index]
+        if value is None:
+            continue
+        if state.fields[temporal_index].logical_type == "date":
+            instant: datetime | date = date.fromisoformat(value)
+        else:
+            instant = _instant(value, "quality.temporal_column")
+        partition = tuple(row[index] for index in partition_indexes)
+        groups.setdefault(partition, []).append(instant)
+    step = timedelta(days=1) if spec.expected_frequency == "daily" else timedelta(hours=1)
+    missing = 0
+    for values in groups.values():
+        ordered = sorted(set(values))
+        for previous, current in pairwise(ordered):
+            delta = current - previous
+            missing += max(0, int(delta / step) - 1)
+    return missing
+
+
+def _instant(value: Any, path: str) -> datetime:
+    if not isinstance(value, str):
+        raise PreparationError("TEMPORAL_VALUE", path, "must be a UTC timestamp string")
+    return parse_utc(value, path)
+
+
+def _validate_temporal_column(
+    state: TableState,
+    source_id: str,
+    column: str,
+    role: str,
+) -> None:
+    try:
+        field = state.field(column)
+    except PreparationError:
+        raise PreparationError(
+            "TEMPORAL_EVIDENCE",
+            source_id,
+            f"declared {role} column is absent from the joined table",
+        ) from None
+    if field.source_id != source_id or field.temporal_role != role:
+        raise PreparationError(
+            "TEMPORAL_EVIDENCE",
+            source_id,
+            f"declared {role} column has mismatched source or temporal role",
+        )
+
+
+def _is_digest(value: Any) -> bool:
+    return (
+        isinstance(value, str)
+        and len(value) == 64
+        and all(character in "0123456789abcdef" for character in value)
+    )
+
+
+__all__ = [
+    "QualityCheck",
+    "QualityReport",
+    "TargetRationale",
+    "TemporalFinding",
+    "TemporalReport",
+    "construct_target",
+    "validate_quality",
+    "validate_temporal_safety",
+]