# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/how-can-an-instance-preserve-verified-sql-query-plans-across-session-restarts.md
# Remnant Warrant:    https://corpusfetch.com/c/how-can-an-instance-preserve-verified-sql-query-plans-across-session-restarts.warrant.json
# Markdown SHA-256:   00095a4f6efdba66de031c62d2782369093b6618068325c55e0caba28c9ef559
# Code AST SHA-256:   90b5957bd468fa39d0f2b8ab24aba1646ca11e9172d2498cc92560470daf2af1
# Verified Classes:   PlanVerdict, VerifiedQueryPlan, CurrentDBState, PlanManifest, SQLPlanGuard
# Defensive Guards:   1 fail-closed invariants (zero external deps)

from dataclasses import dataclass
from enum import Enum, auto
import hashlib
import json


class PlanVerdict(Enum):
    PLAN_STABLE = auto()
    STATS_DRIFT_DETECTED = auto()
    PARAMETER_MISMATCH = auto()
    MISSING_PLAN_BOUNDARY = auto()


@dataclass(frozen=True)
class VerifiedQueryPlan:
    normalized_sql_hash: str
    optimizer_plan_hash: str
    parameter_types: tuple[tuple[str, str], ...]
    table_row_counts: tuple[tuple[str, int], ...]


@dataclass(frozen=True)
class CurrentDBState:
    current_parameter_types: tuple[tuple[str, str], ...]
    current_row_counts: tuple[tuple[str, int], ...]


@dataclass(frozen=True)
class PlanManifest:
    verdict: PlanVerdict
    drift_ratio: float
    action_directive: str
    manifest_digest: str


class SQLPlanGuard:
    """
    Evaluates database state against verified SQL plans to prevent
    Execution Plan Drift across session restarts.
    """

    STATS_DRIFT_THRESHOLD = 0.20  # 20% row count variance

    @staticmethod
    def _hash(data: str) -> str:
        return hashlib.sha256(data.encode("utf-8")).hexdigest()

    @classmethod
    def evaluate_plan_admissibility(
        cls,
        saved_plan: VerifiedQueryPlan,
        current_state: CurrentDBState,
    ) -> PlanManifest:
        
        if not saved_plan.optimizer_plan_hash.strip():
            return PlanManifest(
                verdict=PlanVerdict.MISSING_PLAN_BOUNDARY,
                drift_ratio=0.0,
                action_directive="HALT: Re-run EXPLAIN ANALYZE to generate a verified plan boundary.",
                manifest_digest=cls._hash("MISSING"),
            )

        # Gate 1: Parameter binding shape check
        saved_params = dict(saved_plan.parameter_types)
        current_params = dict(current_state.current_parameter_types)

        for param_name, saved_type in saved_params.items():
            if current_params.get(param_name) != saved_type:
                return PlanManifest(
                    verdict=PlanVerdict.PARAMETER_MISMATCH,
                    drift_ratio=0.0,
                    action_directive=f"HALT: Parameter {param_name} type changed. Re-optimize plan.",
                    manifest_digest=cls._hash(f"PARAM:{param_name}"),
                )

        # Gate 2: Statistics drift check
        saved_counts = dict(saved_plan.table_row_counts)
        current_counts = dict(current_state.current_row_counts)

        max_drift = 0.0
        drifted_tables: list[str] = []

        for table, saved_count in saved_counts.items():
            current_count = current_counts.get(table)
            
            if current_count is None or saved_count == 0:
                continue
                
            drift = abs(current_count - saved_count) / saved_count
            if drift > max_drift:
                max_drift = drift
                
            if drift > cls.STATS_DRIFT_THRESHOLD:
                drifted_tables.append(table)

        if drifted_tables:
            return PlanManifest(
                verdict=PlanVerdict.STATS_DRIFT_DETECTED,
                drift_ratio=max_drift,
                action_directive=(
                    f"HALT: Statistics drift exceeds {cls.STATS_DRIFT_THRESHOLD:.0%} on "
                    f"{drifted_tables}. Regenerate plan before execution."
                ),
                manifest_digest=cls._hash(f"DRIFT:{max_drift:.4f}"),
            )

        # Gate 3: Plan is stable
        return PlanManifest(
            verdict=PlanVerdict.PLAN_STABLE,
            drift_ratio=max_drift,
            action_directive=(
                f"PROCEED: Execute query and optionally pin to plan "
                f"{saved_plan.optimizer_plan_hash}."
            ),
            manifest_digest=cls._hash(f"STABLE:{saved_plan.optimizer_plan_hash}"),
        )

    @classmethod
    def assert_execution_safe(
        cls, manifest: PlanManifest
    ) -> None:
        """
        Fail-closed enforcement: raises if the plan is not stable.
        """
        if manifest.verdict is not PlanVerdict.PLAN_STABLE:
            raise RuntimeError(
                f"QUERY BLOCKED: {manifest.verdict.name}. {manifest.action_directive}"
            )