# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/what-provenance-must-accompany-human-in-the-loop-approval-decisions-in-autonomous-agent-workflows.md
# Remnant Warrant:    https://corpusfetch.com/c/what-provenance-must-accompany-human-in-the-loop-approval-decisions-in-autonomous-agent-workflows.warrant.json
# Markdown SHA-256:   0d4262a6afec9e1e41989b2d8727350cfc6129993bbc93237baaba8b26a67450
# Code AST SHA-256:   e9c8e3df711788c92a5ff337e2f861248ed5e1a61e899b550f47ba6a6bb05006
# Verified Classes:   ApprovalVerdict, HumanApproval, ApprovalPolicy, ApprovalManifest, HumanApprovalGuard
# Defensive Guards:   0 fail-closed invariants (zero external deps)

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

class ApprovalVerdict(Enum):
    AUTHENTIC_APPROVAL = auto()
    SHARED_ACCOUNT_REJECTED = auto()
    ACTION_SUBSTITUTED = auto()
    APPROVAL_EXPIRED = auto()

@dataclass(frozen=True)
class HumanApproval:
    approval_id: str
    approver_identity_signature: str
    approver_is_shared_account: bool
    approved_action_hash: str
    action_about_to_execute_hash: str
    approval_epoch: float
    expiration_epoch: float

@dataclass(frozen=True)
class ApprovalPolicy:
    current_epoch: float

@dataclass(frozen=True)
class ApprovalManifest:
    verdict: ApprovalVerdict
    directive: str
    manifest_digest: str

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

    @classmethod
    def evaluate_approval(
        cls, approval: HumanApproval, policy: ApprovalPolicy
    ) -> ApprovalManifest:
        
        # Gate 1: Identity signature
        if not approval.approver_identity_signature:
            return ApprovalManifest(
                verdict=ApprovalVerdict.SHARED_ACCOUNT_REJECTED,
                directive=f"HALT: No approver signature for {approval.approval_id}.",
                manifest_digest=cls._hash(f"NO_SIG:{approval.approval_id}")
            )

        # Gate 2: Shared account rejection
        if approval.approver_is_shared_account:
            return ApprovalManifest(
                verdict=ApprovalVerdict.SHARED_ACCOUNT_REJECTED,
                directive=f"HALT: Shared account approval {approval.approval_id} not attributable.",
                manifest_digest=cls._hash(f"SHARED:{approval.approval_id}")
            )

        # Gate 3: Action match
        if approval.approved_action_hash != approval.action_about_to_execute_hash:
            return ApprovalManifest(
                verdict=ApprovalVerdict.ACTION_SUBSTITUTED,
                directive=f"HALT: Approved action {approval.approved_action_hash} != current {approval.action_about_to_execute_hash}.",
                manifest_digest=cls._hash(f"SUBSTITUTED:{approval.approval_id}")
            )

        # Gate 4: Expiration
        if policy.current_epoch > approval.expiration_epoch:
            return ApprovalManifest(
                verdict=ApprovalVerdict.APPROVAL_EXPIRED,
                directive=f"HALT: Approval expired at {approval.expiration_epoch:.0f}.",
                manifest_digest=cls._hash(f"EXPIRED:{approval.approval_id}")
            )

        # Gate 5: Authentic
        digest = cls._hash(json.dumps({
            "approval": approval.approval_id,
            "approver": approval.approver_identity_signature,
            "action": approval.approved_action_hash,
            "epoch": f"{approval.approval_epoch:.0f}"
        }, sort_keys=True))
        
        return ApprovalManifest(
            verdict=ApprovalVerdict.AUTHENTIC_APPROVAL,
            directive=f"PROCEED: Approval {approval.approval_id} authentic and bound to action.",
            manifest_digest=digest
        )