# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/what-invariants-prevent-semantic-versioning-from-masking-behavioral-incompatibility.md
# Remnant Warrant:    https://corpusfetch.com/c/what-invariants-prevent-semantic-versioning-from-masking-behavioral-incompatibility.warrant.json
# Markdown SHA-256:   e5a5819646ffb1b15e58e046a58c4d379f812763059b78853fce7644fef804c9
# Code AST SHA-256:   258caf47b661d9b6020bdc92b035aafaf41ea5c1bbd786b52a659f6fe21c4fcc
# Verified Classes:   SemverVerdict, VersionDependency, SemverPolicy, SemverManifest, SemanticVersioningGuard
# Defensive Guards:   0 fail-closed invariants (zero external deps)

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

class SemverVerdict(Enum):
    NO_VERSION_DEPENDENCY = auto()
    DECLARED_SEMANTICS_HOLD = auto()
    BEHAVIORAL_COMPATIBILITY_VERIFIED = auto()
    SEMVER_VIOLATION_DETECTED = auto()

@dataclass(frozen=True)
class VersionDependency:
    artifact_id: str
    old_version: str  # semver
    new_version: str  # semver
    declares_backward_compatible: bool
    has_behavioral_testing: bool
    breaking_change_observed: bool
    past_semver_violations: int

@dataclass(frozen=True)
class SemverPolicy:
    require_behavioral_testing: bool
    max_acceptable_violation_history: int

@dataclass(frozen=True)
class SemverManifest:
    verdict: SemverVerdict
    directive: str
    manifest_digest: str

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

    @classmethod
    def evaluate_upgrade(
        cls, dep: VersionDependency, policy: SemverPolicy
    ) -> SemverManifest:
        
        # Gate 1: No dependency
        if not dep.old_version or not dep.new_version:
            digest = cls._hash(json.dumps({
                "artifact": dep.artifact_id,
                "type": "NO_VERSION"
            }, sort_keys=True))
            return SemverManifest(
                verdict=SemverVerdict.NO_VERSION_DEPENDENCY,
                directive=f"PROCEED: No version dependency for {dep.artifact_id}.",
                manifest_digest=digest
            )

        # Gate 2: Violation history
        if dep.past_semver_violations > policy.max_acceptable_violation_history:
            return SemverManifest(
                verdict=SemverVerdict.SEMVER_VIOLATION_DETECTED,
                directive=f"HALT: {dep.artifact_id} has {dep.past_semver_violations} past semver violations.",
                manifest_digest=cls._hash(f"HISTORY:{dep.artifact_id}")
            )

        # Gate 3: Observed breaking change
        if dep.declares_backward_compatible and dep.breaking_change_observed:
            return SemverManifest(
                verdict=SemverVerdict.SEMVER_VIOLATION_DETECTED,
                directive=f"HALT: {dep.artifact_id} claims backward-compatible but breaks behavior.",
                manifest_digest=cls._hash(f"BREAKING:{dep.artifact_id}")
            )

        # Gate 4: Behavioral testing
        if policy.require_behavioral_testing:
            if not dep.has_behavioral_testing:
                return SemverManifest(
                    verdict=SemverVerdict.DECLARED_SEMANTICS_HOLD,
                    directive=f"CAUTION: {dep.artifact_id} semver declared but untested behaviorally.",
                    manifest_digest=cls._hash(f"UNTESTED:{dep.artifact_id}")
                )
            return SemverManifest(
                verdict=SemverVerdict.BEHAVIORAL_COMPATIBILITY_VERIFIED,
                directive=f"PROCEED: {dep.artifact_id} verified behaviorally compatible.",
                manifest_digest=cls._hash(f"VERIFIED:{dep.artifact_id}")
            )

        # Gate 5: Declared semantics hold
        digest = cls._hash(json.dumps({
            "artifact": dep.artifact_id,
            "from": dep.old_version,
            "to": dep.new_version,
            "compatible": dep.declares_backward_compatible
        }, sort_keys=True))
        
        return SemverManifest(
            verdict=SemverVerdict.DECLARED_SEMANTICS_HOLD,
            directive=f"PROCEED: {dep.artifact_id} semver assumed valid from {dep.old_version} to {dep.new_version}.",
            manifest_digest=digest
        )