# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/in-what-scenarios-must-an-instance-treat-tool-retry-storms-as-evidence-of-a-non-deterministic-replanning-loop-rather-than-transient-infrastructure-fai.md
# Remnant Warrant:    https://corpusfetch.com/c/in-what-scenarios-must-an-instance-treat-tool-retry-storms-as-evidence-of-a-non-deterministic-replanning-loop-rather-than-transient-infrastructure-fai.warrant.json
# Markdown SHA-256:   7d4669b25e26b222eec2ec0a8ef5514f77a7087416b4c086033ab6d8ded595fd
# Code AST SHA-256:   5aecd301308f0a67775d51da934c0f5d41deb84e53ccf85a41f216a08e358f07
# Verified Classes:   ReplanningLoopError, Attempt, LineageTracker
# Defensive Guards:   1 fail-closed invariants (zero external deps)

import hashlib
from dataclasses import dataclass, field
from typing import Sequence


class ReplanningLoopError(RuntimeError):
    """Raised when a plan lineage exhibits non-deterministic replanning under a healthy dependency."""


@dataclass
class Attempt:
    goal_lineage_id: str
    generation: int
    tool_name: str
    arguments: str
    dependency_healthy: bool


@dataclass
class LineageTracker:
    max_distinct_hashes: int = 3
    attempts: list[Attempt] = field(default_factory=list)

    def record(self, attempt: Attempt) -> None:
        self.attempts.append(attempt)

    def _arg_hash(self, a: Attempt) -> str:
        return hashlib.sha256(a.arguments.encode()).hexdigest()

    def classify(self, lineage_id: str) -> str:
        lineage = [a for a in self.attempts if a.goal_lineage_id == lineage_id]
        if not lineage:
            return "unknown"
        distinct = {self._arg_hash(a) for a in lineage}
        healthy = all(a.dependency_healthy for a in lineage)
        generations = len({a.generation for a in lineage})

        if len(distinct) >= self.max_distinct_hashes and healthy and generations >= 3:
            raise ReplanningLoopError(
                f"lineage {lineage_id}: {len(distinct)} distinct argument hashes across "
                f"{generations} generations with healthy dependency — planner instability, "
                f"not transient failure. Freeze replanning and escalate."
            )
        if len(distinct) <= 1:
            return "retry_storm"
        return "ambiguous_retry_storm"


def guard_lineage(tracker: LineageTracker, lineage_id: str) -> str:
    verdict = tracker.classify(lineage_id)
    if verdict == "retry_storm":
        # safe remediation: backoff, do not freeze planner
        return "apply_backoff"
    return "monitor"
