# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/how-must-an-instance-reason-about-latent-capabilities-it-has-not-yet-exercised.md
# Remnant Warrant:    https://corpusfetch.com/c/how-must-an-instance-reason-about-latent-capabilities-it-has-not-yet-exercised.warrant.json
# Markdown SHA-256:   4d266624c7d1ca6318a2b6e9ffa2e4ed23ff88b345b0990865fdba7312f624ca
# Code AST SHA-256:   0956f49f5a98a851f27cbb3fe9c2c1b6af4d96e44c0425f2e1753ca0146a8cbf
# Verified Classes:   LatentCapabilityVerdict, CapabilityState, FirstCallProposal, LatentCapabilityPolicy, LatentCapabilityManifest, LatentCapabilityGuard
# Defensive Guards:   0 fail-closed invariants (zero external deps)

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

class LatentCapabilityVerdict(Enum):
    CAPABILITY_DEMONSTRATED = auto()
    SAFE_FIRST_CALL_READY = auto()
    ENVELOPE_UNPREPARED = auto()
    FULL_SCALE_UNVERIFIED = auto()

@dataclass(frozen=True)
class CapabilityState:
    capability_id: str
    declaration: str
    demonstration_context: str | None
    current_context: str
    demonstration_compatible: bool

@dataclass(frozen=True)
class FirstCallProposal:
    proposal_id: str
    is_reversible: bool
    is_isolated: bool
    input_scale_ratio: float  # fraction of typical production input

@dataclass(frozen=True)
class LatentCapabilityPolicy:
    require_demonstration_for_full_scale: bool
    min_reversibility_for_first_call: bool

@dataclass(frozen=True)
class LatentCapabilityManifest:
    verdict: LatentCapabilityVerdict
    directive: str
    manifest_digest: str

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

    @classmethod
    def evaluate_invocation(
        cls, cap: CapabilityState, proposal: FirstCallProposal, policy: LatentCapabilityPolicy
    ) -> LatentCapabilityManifest:
        
        # Gate 1: Demonstration in current context
        if cap.demonstration_context and cap.demonstration_compatible:
            digest = cls._hash(json.dumps({
                "capability": cap.capability_id,
                "demonstration": cap.demonstration_context,
                "compatible": "TRUE"
            }, sort_keys=True))
            return LatentCapabilityManifest(
                verdict=LatentCapabilityVerdict.CAPABILITY_DEMONSTRATED,
                directive=f"PROCEED: Capability {cap.capability_id} demonstrated in compatible context.",
                manifest_digest=digest
            )

        # Gate 2: Full scale requires demonstration
        if proposal.input_scale_ratio >= 0.8:
            if policy.require_demonstration_for_full_scale:
                return LatentCapabilityManifest(
                    verdict=LatentCapabilityVerdict.FULL_SCALE_UNVERIFIED,
                    directive=f"HALT: Full-scale ({proposal.input_scale_ratio:.2f}) requires demonstration.",
                    manifest_digest=cls._hash(f"FULL_SCALE:{cap.capability_id}")
                )

        # Gate 3: First call safety envelope
        is_safe_envelope = (
            proposal.input_scale_ratio <= 0.1
            and (proposal.is_reversible or not policy.min_reversibility_for_first_call)
            and (proposal.is_isolated or proposal.is_reversible)
        )

        if is_safe_envelope:
            digest = cls._hash(json.dumps({
                "capability": cap.capability_id,
                "proposal": proposal.proposal_id,
                "scale": f"{proposal.input_scale_ratio:.3f}",
                "reversible": str(proposal.is_reversible),
                "isolated": str(proposal.is_isolated)
            }, sort_keys=True))
            return LatentCapabilityManifest(
                verdict=LatentCapabilityVerdict.SAFE_FIRST_CALL_READY,
                directive=f"PROCEED: Safe first call for {cap.capability_id} at {proposal.input_scale_ratio:.2f} scale.",
                manifest_digest=digest
            )

        # Gate 4: Envelope unprepared
        return LatentCapabilityManifest(
            verdict=LatentCapabilityVerdict.ENVELOPE_UNPREPARED,
            directive=f"HALT: First call for {cap.capability_id} at scale {proposal.input_scale_ratio:.2f} not safely bounded.",
            manifest_digest=cls._hash(f"UNPREPARED:{cap.capability_id}")
        )