# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/how-can-an-instance-preserve-verified-rollback-paths-when-committing-state-changes.md
# Remnant Warrant:    https://corpusfetch.com/c/how-can-an-instance-preserve-verified-rollback-paths-when-committing-state-changes.warrant.json
# Markdown SHA-256:   17629146e0e69103fd1f246c7818fbc8eccdca770bb6fc9b681367c4f06f2cae
# Code AST SHA-256:   d7f822ba733c4d50a5a39ea7f061bc6c88fc46e3d409d72fdb8fd4400bd3d7f4
# Verified Classes:   RollbackVerdict, CompensatingAction, StateMutationRecord, RollbackManifest, RollbackPathGuard
# Defensive Guards:   1 fail-closed invariants (zero external deps)

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


class RollbackVerdict(Enum):
    FULL_ROLLBACK_POSSIBLE = auto()
    PARTIAL_ROLLBACK_REQUIRES_HUMAN = auto()
    BLOCKED_CONCURRENT_MUTATION = auto()


@dataclass(frozen=True)
class CompensatingAction:
    action_type: str
    payload: str
    idempotency_key: str


@dataclass(frozen=True)
class StateMutationRecord:
    mutation_id: str
    pre_commit_state_hash: str
    compensating_action: CompensatingAction
    cascading_side_effects: frozenset[str]
    irreversible_effects: frozenset[str]


@dataclass(frozen=True)
class RollbackManifest:
    record: StateMutationRecord
    verdict: RollbackVerdict
    manifest_digest: str


class RollbackPathGuard:
    """
    Evaluates state mutations to ensure a verified rollback path is preserved
    before the commit is considered final.
    """

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

    @classmethod
    def seal_rollback_manifest(
        cls, record: StateMutationRecord
    ) -> RollbackManifest:
        
        if not record.compensating_action.idempotency_key.strip():
            raise ValueError(
                "Compensating action lacks an idempotency key. Rollback cannot be safely retried."
            )

        # Gate 1: Irreversible effects force a partial rollback state
        if record.irreversible_effects:
            verdict = RollbackVerdict.PARTIAL_ROLLBACK_REQUIRES_HUMAN
        else:
            verdict = RollbackVerdict.FULL_ROLLBACK_POSSIBLE

        digest_payload = {
            "mutation_id": record.mutation_id,
            "pre_commit_hash": record.pre_commit_state_hash,
            "compensating_action": record.compensating_action.action_type,
            "idempotency": record.compensating_action.idempotency_key,
            "irreversible": tuple(sorted(record.irreversible_effects)),
            "verdict": verdict.name,
        }
        
        digest = cls._hash(
            json.dumps(digest_payload, sort_keys=True, separators=(",", ":"))
        )

        return RollbackManifest(
            record=record,
            verdict=verdict,
            manifest_digest=digest,
        )

    @classmethod
    def verify_rollback_admissibility(
        cls,
        manifest: RollbackManifest,
        current_state_hash: str,
    ) -> tuple[bool, str]:
        """
        Fetching-time check: confirms the environment is safe for the
        compensating action by detecting concurrent mutations.
        """
        if manifest.verdict is RollbackVerdict.PARTIAL_ROLLBACK_REQUIRES_HUMAN:
            return False, (
                f"IRREVERSIBLE_SIDE_EFFECTS: {sorted(manifest.record.irreversible_effects)}. "
                "Human reconciliation required."
            )

        if current_state_hash != manifest.record.pre_commit_state_hash:
            return False, (
                "CONCURRENT_MUTATION_DETECTED: Current state hash does not match "
                "the pre-commit hash. Rollback would clobber newer data."
            )

        return True, (
            f"ROLLBACK_ADMISSIBLE: Execute {manifest.record.compensating_action.action_type} "
            f"with idempotency key {manifest.record.compensating_action.idempotency_key}."
        )