# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/what-temporal-coupling-invariants-prevent-interference-between-concurrent-sessions.md
# Remnant Warrant:    https://corpusfetch.com/c/what-temporal-coupling-invariants-prevent-interference-between-concurrent-sessions.warrant.json
# Markdown SHA-256:   bbfd5184bc820df0c04ecbb161da6b76b21a0da833ee9dffaf8a9ddef47d347b
# Code AST SHA-256:   e1717bc77cbd9eac1ab166e36539f26d3dc8215cad1bbf304543c3483645a349
# Verified Classes:   InterferenceVerdict, Operation, ConcurrentState, TemporalCouplingPolicy, TemporalCouplingManifest, TemporalCouplingGuard
# Defensive Guards:   0 fail-closed invariants (zero external deps)

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

class InterferenceVerdict(Enum):
    NO_CONCURRENCY = auto()
    NON_INTERFERING = auto()
    INTERFERENCE_DETECTED = auto()
    CAUSAL_REVERSAL_DETECTED = auto()

@dataclass(frozen=True)
class Operation:
    operation_id: str
    session_id: str
    state_key: str
    operation_class: str  # "READ" | "WRITE" | "READ_MODIFY_WRITE"
    temporal_window_start: float
    temporal_window_end: float
    depends_on: tuple[str, ...]

@dataclass(frozen=True)
class ConcurrentState:
    operations: tuple[Operation, ...]

@dataclass(frozen=True)
class TemporalCouplingPolicy:
    require_ordering_for_rmw: bool

@dataclass(frozen=True)
class TemporalCouplingManifest:
    verdict: InterferenceVerdict
    directive: str
    manifest_digest: str

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

    @classmethod
    def evaluate_operations(
        cls, state: ConcurrentState, policy: TemporalCouplingPolicy
    ) -> TemporalCouplingManifest:
        
        # Gate 1: Single session
        sessions = {op.session_id for op in state.operations}
        if len(sessions) <= 1:
            digest = cls._hash(json.dumps({
                "sessions": str(len(sessions)),
                "ops": str(len(state.operations))
            }, sort_keys=True))
            return TemporalCouplingManifest(
                verdict=InterferenceVerdict.NO_CONCURRENCY,
                directive=f"PROCEED: Single session, no concurrency.",
                manifest_digest=digest
            )

        # Gate 2: Temporal overlap check per state key
        by_key: dict[str, list[Operation]] = {}
        for op in state.operations:
            by_key.setdefault(op.state_key, []).append(op)

        for key, ops in by_key.items():
            # Check for overlapping READ_MODIFY_WRITE
            rmw_ops = [o for o in ops if o.operation_class == "READ_MODIFY_WRITE"]
            for i in range(len(rmw_ops)):
                for j in range(i+1, len(rmw_ops)):
                    a, b = rmw_ops[i], rmw_ops[j]
                    if a.session_id == b.session_id:
                        continue
                    # Overlapping windows means RMW interference
                    if a.temporal_window_start < b.temporal_window_end and b.temporal_window_start < a.temporal_window_end:
                        if policy.require_ordering_for_rmw:
                            return TemporalCouplingManifest(
                                verdict=InterferenceVerdict.INTERFERENCE_DETECTED,
                                directive=f"HALT: RMW interference on {key} between {a.operation_id} and {b.operation_id}.",
                                manifest_digest=cls._hash(f"RMW_INTERFERENCE:{key}")
                            )

        # Gate 3: Causal reversal check
        op_map = {op.operation_id: op for op in state.operations}
        for op in state.operations:
            for dep_id in op.depends_on:
                dep = op_map.get(dep_id)
                if dep and op.temporal_window_start < dep.temporal_window_end and op.session_id != dep.session_id:
                    return TemporalCouplingManifest(
                        verdict=InterferenceVerdict.CAUSAL_REVERSAL_DETECTED,
                        directive=f"HALT: Operation {op.operation_id} depends on {dep_id} but starts before dep ends.",
                        manifest_digest=cls._hash(f"CAUSAL_REVERSAL:{op.operation_id}")
                    )

        # Gate 4: Non-interfering
        digest = cls._hash(json.dumps({
            "sessions": tuple(sorted(sessions)),
            "ops": tuple(sorted(op.operation_id for op in state.operations)),
            "state_keys": tuple(sorted(by_key.keys()))
        }, sort_keys=True))
        
        return TemporalCouplingManifest(
            verdict=InterferenceVerdict.NON_INTERFERING,
            directive=f"PROCEED: {len(sessions)} sessions, {len(state.operations)} ops, no interference.",
            manifest_digest=digest
        )