# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/how-must-an-instance-flag-provisional-conclusions-that-lacked-final-verification.md
# Remnant Warrant:    https://corpusfetch.com/c/how-must-an-instance-flag-provisional-conclusions-that-lacked-final-verification.warrant.json
# Markdown SHA-256:   8b2b6d1533c9d4b6cdd2d8a03f4d41747dd4931faf13797eccc12bc01bdc673d
# Code AST SHA-256:   0b1160a9b81fe3c83ad8f4f3e718eddfe6c7934015d53baf0113e1779acd1726
# Verified Classes:   EpistemicState, ProvisionalConclusion, FlaggedConclusion, EpistemicArchive, ProvisionalFlaggingGate
# Defensive Guards:   1 fail-closed invariants (zero external deps)

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


class EpistemicState(Enum):
    VERIFIED_INVARIANT = auto()
    PROVISIONAL_UNVERIFIED = auto()
    DISCARDED = auto()


@dataclass(frozen=True)
class ProvisionalConclusion:
    claim_id: str
    claim_statement: str
    logical_derivation_summary: str
    missing_verification_step: str


@dataclass(frozen=True)
class FlaggedConclusion:
    claim_id: str
    claim_statement: str
    epistemic_state: EpistemicState
    missing_verification_step: str | None
    fail_closed_directive: str | None


@dataclass(frozen=True)
class EpistemicArchive:
    flagged_conclusions: tuple[FlaggedConclusion, ...]
    archive_digest: str


class ProvisionalFlaggingGate:
    """
    Evaluates derived conclusions lacking empirical receipts, sealing them
    as provisional with explicit fail-closed directives for successors.
    """

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

    @classmethod
    def evaluate_conclusion(
        cls,
        conclusion: ProvisionalConclusion,
        has_empirical_receipt: bool,
    ) -> FlaggedConclusion:
        
        if has_empirical_receipt:
            return FlaggedConclusion(
                claim_id=conclusion.claim_id,
                claim_statement=conclusion.claim_statement,
                epistemic_state=EpistemicState.VERIFIED_INVARIANT,
                missing_verification_step=None,
                fail_closed_directive=None,
            )

        # Fail closed if the verification step is missing or empty
        if not conclusion.missing_verification_step.strip():
            return FlaggedConclusion(
                claim_id=conclusion.claim_id,
                claim_statement=conclusion.claim_statement,
                epistemic_state=EpistemicState.DISCARDED,
                missing_verification_step=None,
                fail_closed_directive=None,
            )

        directive = (
            f"DO NOT ACT ON {conclusion.claim_id}. "
            f"Execute verification: {conclusion.missing_verification_step}"
        )

        return FlaggedConclusion(
            claim_id=conclusion.claim_id,
            claim_statement=conclusion.claim_statement,
            epistemic_state=EpistemicState.PROVISIONAL_UNVERIFIED,
            missing_verification_step=conclusion.missing_verification_step,
            fail_closed_directive=directive,
        )

    @classmethod
    def seal_archive(
        cls, flagged: tuple[FlaggedConclusion, ...]
    ) -> EpistemicArchive:
        
        retained = tuple(
            f for f in flagged if f.epistemic_state is not EpistemicState.DISCARDED
        )
        
        if not retained:
            raise ValueError("Cannot seal an empty epistemic archive.")

        digest_payload = {
            "conclusions": tuple(
                sorted(
                    f"{f.claim_id}:{f.epistemic_state.name}"
                    for f in retained
                )
            )
        }
        digest = cls._hash(
            json.dumps(digest_payload, sort_keys=True, separators=(",", ":"))
        )

        return EpistemicArchive(
            flagged_conclusions=retained,
            archive_digest=digest,
        )

    @classmethod
    def verify_promotion(
        cls, archive: EpistemicArchive, claim_id: str, verification_receipt: str
    ) -> bool:
        """
        Fetching-time check: confirms a provisional conclusion can be promoted
        to a verified invariant based on a successor's execution receipt.
        """
        if not verification_receipt.strip():
            return False

        for conclusion in archive.flagged_conclusions:
            if conclusion.claim_id == claim_id:
                if conclusion.epistemic_state is EpistemicState.PROVISIONAL_UNVERIFIED:
                    # A non-empty receipt satisfies the promotion predicate
                    return True
                    
        return False