# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/why-should-session-teardown-preserve-the-exact-commit-hash-of-external-dependencies.md
# Remnant Warrant:    https://corpusfetch.com/c/why-should-session-teardown-preserve-the-exact-commit-hash-of-external-dependencies.warrant.json
# Markdown SHA-256:   d4b6176b6fb7199ba18087a75cbc05d3666fa49b13944baceaf62845775e2501
# Code AST SHA-256:   4b45a9c43a39de20f16189c1a94bc1134820d33b8c4276fcb57991cc3f76e5a8
# Verified Classes:   ReferenceMutability, DependencyState, DependencyManifest, DependencyHashRecorder
# Defensive Guards:   3 fail-closed invariants (zero external deps)

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


class ReferenceMutability(Enum):
    IMMUTABLE_HASH = auto()
    MUTABLE_TAG = auto()
    MUTABLE_BRANCH = auto()
    REGISTRY_ENFORCED_IMMUTABLE = auto()


@dataclass(frozen=True)
class DependencyState:
    identifier: str
    reference: str
    mutability: ReferenceMutability
    immutable_hash: str | None
    lockfile_integrity_hash: str


@dataclass(frozen=True)
class DependencyManifest:
    dependencies: tuple[DependencyState, ...]
    manifest_digest: str


class DependencyHashRecorder:
    """
    Evaluates external dependencies at teardown to ensure exact commit hashes
    are preserved, preventing the Mutable Tag Illusion.
    """

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

    @classmethod
    def seal_manifest(
        cls, dependencies: tuple[DependencyState, ...]
    ) -> DependencyManifest:
        
        if not dependencies:
            raise ValueError("Cannot seal an empty dependency manifest.")

        for dep in dependencies:
            # Fail closed if a mutable reference lacks a commit hash
            if dep.mutability in (ReferenceMutability.MUTABLE_TAG, ReferenceMutability.MUTABLE_BRANCH):
                if not dep.immutable_hash or not dep.immutable_hash.strip():
                    raise ValueError(
                        f"Dependency {dep.identifier!r} uses mutable reference "
                        f"{dep.reference!r} but lacks an immutable commit hash."
                    )
            if not dep.lockfile_integrity_hash.strip():
                raise ValueError(
                    f"Dependency {dep.identifier!r} lacks a lockfile integrity hash; "
                    "transitive drift cannot be prevented."
                )

        digest_payload = {
            "dependencies": tuple(
                sorted(
                    f"{d.identifier}:{d.immutable_hash or d.reference}:{d.lockfile_integrity_hash}"
                    for d in dependencies
                )
            )
        }
        digest = cls._hash(
            json.dumps(digest_payload, sort_keys=True, separators=(",", ":"))
        )

        return DependencyManifest(
            dependencies=dependencies,
            manifest_digest=digest,
        )

    @classmethod
    def verify_dependency_resolution(
        cls,
        manifest: DependencyManifest,
        current_identifier: str,
        resolved_hash: str,
    ) -> tuple[bool, str]:
        """
        Fetching-time check: confirms the newly resolved dependency matches the
        exact hash preserved at session teardown.
        """
        for dep in manifest.dependencies:
            if dep.identifier == current_identifier:
                expected = dep.immutable_hash or dep.reference
                if expected != resolved_hash:
                    return False, f"HASH MISMATCH: {current_identifier} expected {expected}, resolved {resolved_hash}. Possible tag hijack or force-push."
                return True, "MATCHED"
                
        return False, f"UNKNOWN_DEPENDENCY: {current_identifier} is not in the sealed manifest."