# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/what-memory-invariants-must-survive-a-silent-storage-backend-upgrade.md
# Remnant Warrant:    https://corpusfetch.com/c/what-memory-invariants-must-survive-a-silent-storage-backend-upgrade.warrant.json
# Markdown SHA-256:   0700edaabeeecbb75c84bc4e4b85609ff3e1042259dbabf480701459d1cc4109
# Code AST SHA-256:   4679333c30ad3f6e4334b7032de5e4f63d3d0b8947fd41dcc282bcb9b929087d
# Verified Classes:   FormatDriftVerdict, StorageWriteRecord, CurrentBackendState, FormatDriftManifest, SilentStorageUpgradeGuard
# Defensive Guards:   0 fail-closed invariants (zero external deps)

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

class FormatDriftVerdict(Enum):
    FORMAT_STABLE = auto()
    SILENT_FORMAT_DRIFT = auto()
    NORMALIZATION_DRIFT = auto()
    BACKEND_VERSION_CHANGED = auto()

@dataclass(frozen=True)
class StorageWriteRecord:
    record_id: str
    backend_version_at_write: str
    serialization_round_trip_hash: str
    normalization_form_signature: str

@dataclass(frozen=True)
class CurrentBackendState:
    current_backend_version: str
    sample_readback_hash: str
    current_normalization_form: str

@dataclass(frozen=True)
class FormatDriftManifest:
    verdict: FormatDriftVerdict
    directive: str
    manifest_digest: str

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

    @classmethod
    def evaluate_record(
        cls, record: StorageWriteRecord, state: CurrentBackendState
    ) -> FormatDriftManifest:
        
        # Gate 1: Backend version change
        if record.backend_version_at_write != state.current_backend_version:
            # Version changed, require readback verification
            if record.serialization_round_trip_hash != state.sample_readback_hash:
                return FormatDriftManifest(
                    verdict=FormatDriftVerdict.SILENT_FORMAT_DRIFT,
                    directive=f"HALT: Backend version {record.backend_version_at_write} -> {state.current_backend_version}. Readback hash mismatch. Silent drift.",
                    manifest_digest=cls._hash(f"DRIFT:{record.record_id}")
                )
            if record.normalization_form_signature != state.current_normalization_form:
                return FormatDriftManifest(
                    verdict=FormatDriftVerdict.NORMALIZATION_DRIFT,
                    directive=f"HALT: Normalization {record.normalization_form_signature} -> {state.current_normalization_form}.",
                    manifest_digest=cls._hash(f"NORM_DRIFT:{record.record_id}")
                )
            return FormatDriftManifest(
                verdict=FormatDriftVerdict.BACKEND_VERSION_CHANGED,
                directive=f"PROCEED: Backend upgraded to {state.current_backend_version} but format verified stable.",
                manifest_digest=cls._hash(f"UPGRADED_SAFE:{record.record_id}")
            )

        # Gate 2: No version change, standard verification
        digest = cls._hash(json.dumps({
            "record": record.record_id,
            "version": record.backend_version_at_write
        }, sort_keys=True))
        
        return FormatDriftManifest(
            verdict=FormatDriftVerdict.FORMAT_STABLE,
            directive="PROCEED: Backend version unchanged. Format stable.",
            manifest_digest=digest
        )