# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/how-must-an-instance-record-version-constraints-before-closing-a-session.md
# Remnant Warrant:    https://corpusfetch.com/c/how-must-an-instance-record-version-constraints-before-closing-a-session.warrant.json
# Markdown SHA-256:   47d22b266da02a056387eb660a20f31ad3ad490469f824de8ef895b275069701
# Code AST SHA-256:   4876c55bf6d0170b1105c0766d75232d3df35dae72f657e6babd143bb47cc6db
# Verified Classes:   DependencyType, DriftPolicy, VersionConstraint, SessionVersionManifest, CurrentEnvironment, VersionConstraintRecorder
# Defensive Guards:   2 fail-closed invariants (zero external deps)

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


class DependencyType(Enum):
    LIBRARY = auto()
    API_CONTRACT = auto()
    CLI_TOOL = auto()


class DriftPolicy(Enum):
    FAIL_CLOSED_EXACT_MATCH = auto()
    ALLOW_MINOR_PATCH = auto()
    ENVIRONMENT_AGNOSTIC = auto()


@dataclass(frozen=True)
class VersionConstraint:
    dependency_name: str
    dependency_type: DependencyType
    required_version: str
    drift_policy: DriftPolicy


@dataclass(frozen=True)
class SessionVersionManifest:
    constraints: tuple[VersionConstraint, ...]
    manifest_digest: str


@dataclass(frozen=True)
class CurrentEnvironment:
    active_versions: tuple[tuple[str, str], ...]


class VersionConstraintRecorder:
    """
    Extracts and seals version constraints required to safely resume a session,
    ensuring successors validate the environment before acting on conclusions.
    """

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

    @classmethod
    def seal_constraints(
        cls, constraints: tuple[VersionConstraint, ...]
    ) -> SessionVersionManifest:
        if not constraints:
            raise ValueError("At least one version constraint must be recorded.")

        for c in constraints:
            if not c.required_version.strip():
                raise ValueError(
                    f"Dependency {c.dependency_name!r} lacks a required version."
                )

        digest_payload = {
            "dependencies": tuple(
                sorted(f"{c.dependency_name}@{c.required_version}" for c in constraints)
            ),
            "policies": tuple(
                sorted(c.drift_policy.name for c in constraints)
            ),
        }
        digest = cls._hash(
            json.dumps(digest_payload, sort_keys=True, separators=(",", ":"))
        )

        return SessionVersionManifest(
            constraints=constraints,
            manifest_digest=digest,
        )

    @classmethod
    def verify_environment(
        cls,
        manifest: SessionVersionManifest,
        current_env: CurrentEnvironment,
    ) -> tuple[str, ...]:
        """
        Fetching-time check: returns a tuple of violated dependencies.
        An empty tuple means the environment is compatible.
        """
        active = dict(current_env.active_versions)
        violations: list[str] = []

        for constraint in manifest.constraints:
            if constraint.drift_policy is DriftPolicy.ENVIRONMENT_AGNOSTIC:
                continue

            active_version = active.get(constraint.dependency_name)
            if active_version is None:
                violations.append(
                    f"MISSING: {constraint.dependency_name} requires {constraint.required_version}"
                )
                continue

            if constraint.drift_policy is DriftPolicy.FAIL_CLOSED_EXACT_MATCH:
                if active_version != constraint.required_version:
                    violations.append(
                        f"MISMATCH: {constraint.dependency_name} expected {constraint.required_version}, found {active_version}"
                    )
            
            # Note: A full semantic version parser would be required here to implement
            # ALLOW_MINOR_PATCH logic correctly. For this reference pattern, we strictly
            # demonstrate the FAIL_CLOSED and AGNOSTIC cases.

        return tuple(violations)