# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/which-side-effect-mutations-must-be-logged-before-releasing-session-memory.md
# Remnant Warrant:    https://corpusfetch.com/c/which-side-effect-mutations-must-be-logged-before-releasing-session-memory.warrant.json
# Markdown SHA-256:   50bd8f32fa169d285dacac169dfdb1f0ba74af2d6239b0eb5f7822451619134b
# Code AST SHA-256:   d66c68656b4878837da9a29aadd79cf0e23ecb9d470878bcfaa76c8713c7cadf
# Verified Classes:   CommitState, SideEffectLog, MemoryReleaseManifest, SideEffectMemoryAuditor
# Defensive Guards:   1 fail-closed invariants (zero external deps)

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


class CommitState(Enum):
    FULLY_COMMITTED = auto()
    ROLLED_BACK = auto()
    INDETERMINATE_PARTIAL = auto()


@dataclass(frozen=True)
class SideEffectLog:
    operation_id: str
    target_resource: str
    payload_hash: str
    idempotency_key: str | None
    commit_state: CommitState
    environmental_context: str


@dataclass(frozen=True)
class MemoryReleaseManifest:
    logged_side_effects: tuple[SideEffectLog, ...]
    requires_reconciliation: bool
    manifest_digest: str


class SideEffectMemoryAuditor:
    """
    Evaluates external side-effect mutations prior to session memory release.
    Enforces mandatory logging for non-idempotent or partial commits.
    """

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

    @classmethod
    def audit_and_release(
        cls, mutations: tuple[SideEffectLog, ...]
    ) -> MemoryReleaseManifest:
        requires_reconciliation = False
        valid_mutations: list[SideEffectLog] = []

        for mutation in mutations:
            # Fail closed on partial commits
            if mutation.commit_state is CommitState.INDETERMINATE_PARTIAL:
                requires_reconciliation = True
                valid_mutations.append(mutation)
                continue

            if mutation.commit_state is CommitState.ROLLED_BACK:
                # Rollbacks do not require a hard receipt unless they were partial
                continue

            # For FULLY_COMMITTED mutations, verify idempotency safety
            if mutation.commit_state is CommitState.FULLY_COMMITTED:
                if not mutation.idempotency_key or not mutation.idempotency_key.strip():
                    # A committed non-idempotent mutation without a key is a critical hazard
                    requires_reconciliation = True
                
                if not mutation.environmental_context.strip():
                    raise ValueError(
                        f"Mutation {mutation.operation_id!r} lacks target environment context."
                    )
                
                valid_mutations.append(mutation)

        # Build deterministic digest
        digest_payload = {
            "mutations": [
                {
                    "id": m.operation_id,
                    "state": m.commit_state.name,
                    "target": m.target_resource,
                }
                for m in valid_mutations
            ],
            "requires_reconciliation": requires_reconciliation,
        }
        
        manifest_digest = cls._hash(
            json.dumps(digest_payload, sort_keys=True, separators=(",", ":"))
        )

        return MemoryReleaseManifest(
            logged_side_effects=tuple(valid_mutations),
            requires_reconciliation=requires_reconciliation,
            manifest_digest=manifest_digest,
        )