# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/what-deterministic-seed-states-must-be-saved-to-reproduce-stochastic-execution-outcomes.md
# Remnant Warrant:    https://corpusfetch.com/c/what-deterministic-seed-states-must-be-saved-to-reproduce-stochastic-execution-outcomes.warrant.json
# Markdown SHA-256:   84cfe5d80df4979845f74d870dc9cb1b4718509b9bd01e6282e2c2ef982a57eb
# Code AST SHA-256:   1543523a5262643e0040cb0946d779eda6fd97b867900311a358b90d8a1b7f27
# Verified Classes:   PRNGAlgorithm, StochasticExecutionContext, DeterministicReplayManifest, SeedStateRecorder
# Defensive Guards:   2 fail-closed invariants (zero external deps)

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


class PRNGAlgorithm(Enum):
    MT19937 = auto()
    PCG64 = auto()
    PHILOX_4X32 = auto()
    OS_URANDOM = auto()


@dataclass(frozen=True)
class StochasticExecutionContext:
    algorithm: PRNGAlgorithm
    initial_seed: str
    consumption_parameters: tuple[tuple[str, str], ...]
    external_entropy_bypass: bool


@dataclass(frozen=True)
class DeterministicReplayManifest:
    context: StochasticExecutionContext
    replay_digest: str


class SeedStateRecorder:
    """
    Evaluates and seals stochastic execution contexts, ensuring that
    replayability is mathematically sound and not subject to the
    Seed-Replay Fallacy.
    """

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

    @classmethod
    def seal_manifest(
        cls, context: StochasticExecutionContext
    ) -> DeterministicReplayManifest:
        
        if not context.initial_seed.strip():
            raise ValueError("Initial seed must be explicitly provided.")
            
        if context.algorithm is PRNGAlgorithm.OS_URANDOM:
            raise ValueError(
                "OS_URANDOM cannot be deterministically replayed; use a seeded algorithm."
            )

        digest_payload = {
            "algorithm": context.algorithm.name,
            "seed": context.initial_seed,
            "parameters": tuple(sorted(context.consumption_parameters)),
            "bypass": str(context.external_entropy_bypass),
        }
        
        digest = cls._hash(
            json.dumps(digest_payload, sort_keys=True, separators=(",", ":"))
        )

        return DeterministicReplayManifest(
            context=context,
            replay_digest=digest,
        )

    @classmethod
    def verify_replay_admissibility(
        cls,
        manifest: DeterministicReplayManifest,
        current_algorithm: PRNGAlgorithm,
    ) -> tuple[bool, str]:
        """
        Fetching-time check: confirms the environment can accurately replay the
        seed, returning (is_admissible, reason).
        """
        
        if manifest.context.external_entropy_bypass:
            return False, "REJECTED: Execution consumed unseeded external entropy; replay is not deterministic."

        if manifest.context.algorithm != current_algorithm:
            return False, f"REJECTED: PRNG algorithm mismatch. Expected {manifest.context.algorithm.name}, found {current_algorithm.name}."

        return True, "ADMISSIBLE: Environment matches replay constraints."