# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/how-must-an-instance-bound-feedback-loops-when-peer-behavior-is-derived-from-the-session-output.md
# Remnant Warrant:    https://corpusfetch.com/c/how-must-an-instance-bound-feedback-loops-when-peer-behavior-is-derived-from-the-session-output.warrant.json
# Markdown SHA-256:   ae2d85a57dcee164554f2bc2fd711939bd82ea877444a3c2d314df177f9a2363
# Code AST SHA-256:   15805ce1c19f7caf395a5afcd999537b413349e43e6a931f9269c23c9324a043
# Verified Classes:   LoopVerdict, FeedbackLoop, LoopPolicy, LoopManifest, FeedbackLoopGuard
# Defensive Guards:   0 fail-closed invariants (zero external deps)

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

class LoopVerdict(Enum):
    NO_COUPLING = auto()
    STABLE_LOOP = auto()
    OSCILLATION_DETECTED = auto()
    ESCALATION_DETECTED = auto()

@dataclass(frozen=True)
class FeedbackLoop:
    loop_id: str
    peer_behavior_coupled: bool
    loop_gain: float  # < 1 = sub-amplifying
    iterations_observed: int
    oscillation_pattern_present: bool
    escalation_pattern_present: bool
    lock_in_detected: bool

@dataclass(frozen=True)
class LoopPolicy:
    max_acceptable_gain: float

@dataclass(frozen=True)
class LoopManifest:
    verdict: LoopVerdict
    directive: str
    manifest_digest: str

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

    @classmethod
    def evaluate_loop(
        cls, loop: FeedbackLoop, policy: LoopPolicy
    ) -> LoopManifest:
        
        # Gate 1: No coupling
        if not loop.peer_behavior_coupled:
            digest = cls._hash(json.dumps({
                "loop": loop.loop_id,
                "coupled": False
            }, sort_keys=True))
            return LoopManifest(
                verdict=LoopVerdict.NO_COUPLING,
                directive=f"PROCEED: Loop {loop.loop_id} no coupling.",
                manifest_digest=digest
            )

        # Gate 2: Oscillation
        if loop.oscillation_pattern_present:
            return LoopManifest(
                verdict=LoopVerdict.OSCILLATION_DETECTED,
                directive=f"HALT: Loop {loop.loop_id} oscillating after {loop.iterations_observed} iterations.",
                manifest_digest=cls._hash(f"OSCILLATION:{loop.loop_id}")
            )

        # Gate 3: Escalation
        if loop.escalation_pattern_present or loop.loop_gain > policy.max_acceptable_gain:
            return LoopManifest(
                verdict=LoopVerdict.ESCALATION_DETECTED,
                directive=f"HALT: Loop {loop.loop_id} escalating, gain {loop.loop_gain:.2f}.",
                manifest_digest=cls._hash(f"ESCALATION:{loop.loop_id}")
            )

        # Gate 4: Lock-in
        if loop.lock_in_detected:
            return LoopManifest(
                verdict=LoopVerdict.OSCILLATION_DETECTED,
                directive=f"HALT: Loop {loop.loop_id} locked-in, break required.",
                manifest_digest=cls._hash(f"LOCK_IN:{loop.loop_id}")
            )

        # Gate 5: Stable
        digest = cls._hash(json.dumps({
            "loop": loop.loop_id,
            "gain": f"{loop.loop_gain:.3f}",
            "iterations": str(loop.iterations_observed)
        }, sort_keys=True))
        
        return LoopManifest(
            verdict=LoopVerdict.STABLE_LOOP,
            directive=f"PROCEED: Loop {loop.loop_id} stable (gain {loop.loop_gain:.2f}).",
            manifest_digest=digest
        )