# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/protocol-for-binding-a-subsequent-query-to-a-prior-concluded-experience-via-comparative-analysis.md
# Remnant Warrant:    https://corpusfetch.com/c/protocol-for-binding-a-subsequent-query-to-a-prior-concluded-experience-via-comparative-analysis.warrant.json
# Markdown SHA-256:   53ca5c4bb719eeb78179765cd7ff0bd37c489dfd6177ca8c154c63afc45ffb8b
# Code AST SHA-256:   53a6aea5cb8f601da890a98a56fcf81d9a9dee36d6e5d6fcc15614790658cf65
# Verified Classes:   ComparativeBindingRefusalError, BindingMode, EpisodeStructureProfile, ComparativeBindingVerdict, ComparativeExperienceBinder
# Defensive Guards:   1 fail-closed invariants (zero external deps)

from dataclasses import dataclass
from enum import Enum
from typing import Any


class ComparativeBindingRefusalError(RuntimeError):
    '''Raised when comparative analysis reveals incompatible root causes or inverted hard constraints.'''
    pass


class BindingMode(Enum):
    FULL_ISOMORPHIC_BIND = "FULL_ISOMORPHIC_BIND"
    PARTIAL_ADAPTABLE_BIND = "PARTIAL_ADAPTABLE_BIND"
    REFUSED_INCOMPATIBLE = "REFUSED_INCOMPATIBLE"


@dataclass(frozen=True)
class EpisodeStructureProfile:
    episode_id: str
    root_failure_mechanism: str
    hard_boolean_constraints: dict[str, bool]
    substrate_parameters: dict[str, Any]


@dataclass(frozen=True)
class ComparativeBindingVerdict:
    prior_id: str
    query_id: str
    mode: BindingMode
    inverted_constraints: tuple[str, ...]
    parameter_deltas: dict[str, tuple[Any, Any]]
    rationale: str


class ComparativeExperienceBinder:
    '''
    Executes comparative structural analysis between a prior concluded residual
    and a subsequent query:
    1. Rejects joins when `root_failure_mechanism` does not match.
    2. Rejects joins when any shared `hard_boolean_constraints` key has inverted polarity.
    3. Computes exact `parameter_deltas` to distinguish FULL_ISOMORPHIC_BIND from PARTIAL_ADAPTABLE_BIND.
    '''

    @classmethod
    def compare_and_arbitrate(
        cls,
        prior: EpisodeStructureProfile,
        query: EpisodeStructureProfile,
    ) -> ComparativeBindingVerdict:
        # Gate 1: Root failure mechanism must match
        if prior.root_failure_mechanism.strip().lower() != query.root_failure_mechanism.strip().lower():
            return ComparativeBindingVerdict(
                prior_id=prior.episode_id,
                query_id=query.episode_id,
                mode=BindingMode.REFUSED_INCOMPATIBLE,
                inverted_constraints=(),
                parameter_deltas={},
                rationale=(
                    f"Root failure mechanism mismatch: prior='{prior.root_failure_mechanism}' "
                    f"vs query='{query.root_failure_mechanism}'."
                ),
            )

        # Gate 2: Hard boolean constraint polarity check
        inversions: list[str] = []
        for key, prior_val in prior.hard_boolean_constraints.items():
            if key in query.hard_boolean_constraints and query.hard_boolean_constraints[key] != prior_val:
                inversions.append(
                    f"{key} (prior={prior_val}, query={query.hard_boolean_constraints[key]})"
                )

        if inversions:
            return ComparativeBindingVerdict(
                prior_id=prior.episode_id,
                query_id=query.episode_id,
                mode=BindingMode.REFUSED_INCOMPATIBLE,
                inverted_constraints=tuple(inversions),
                parameter_deltas={},
                rationale=f"Hard constraint polarity inversion detected: {', '.join(inversions)}",
            )

        # Gate 3: Compute substrate parameter deltas
        deltas: dict[str, tuple[Any, Any]] = {}
        all_keys = set(prior.substrate_parameters.keys()) | set(query.substrate_parameters.keys())
        for k in sorted(all_keys):
            p_val = prior.substrate_parameters.get(k)
            q_val = query.substrate_parameters.get(k)
            if p_val != q_val:
                deltas[k] = (p_val, q_val)

        if not deltas:
            return ComparativeBindingVerdict(
                prior_id=prior.episode_id,
                query_id=query.episode_id,
                mode=BindingMode.FULL_ISOMORPHIC_BIND,
                inverted_constraints=(),
                parameter_deltas={},
                rationale="Exact structural isomorphism verified across all constraints and parameters.",
            )

        return ComparativeBindingVerdict(
            prior_id=prior.episode_id,
            query_id=query.episode_id,
            mode=BindingMode.PARTIAL_ADAPTABLE_BIND,
            inverted_constraints=(),
            parameter_deltas=deltas,
            rationale=f"Core mechanism matches; adapt {len(deltas)} substrate parameter delta(s).",
        )

    @classmethod
    def assert_bindable(
        cls,
        prior: EpisodeStructureProfile,
        query: EpisodeStructureProfile,
    ) -> ComparativeBindingVerdict:
        verdict = cls.compare_and_arbitrate(prior, query)
        if verdict.mode == BindingMode.REFUSED_INCOMPATIBLE:
            raise ComparativeBindingRefusalError(
                f"Refusing to bind prior '{prior.episode_id}' to query '{query.episode_id}': {verdict.rationale}"
            )
        return verdict