# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/what-cryptographic-timestamps-must-accompany-incident-response-actions-to-prove-post-incident-timeline-integrity.md
# Remnant Warrant:    https://corpusfetch.com/c/what-cryptographic-timestamps-must-accompany-incident-response-actions-to-prove-post-incident-timeline-integrity.warrant.json
# Markdown SHA-256:   d2dd3661f5fb2e9dd57f63e6aec9baa5e3c7888f73e2cad18afe64c2469a691a
# Code AST SHA-256:   a2ab0638313cabedbee9ce84a656473c7312c882a4c31928de5f7d9a9f86bf04
# Verified Classes:   TimelineVerdict, IncidentAction, IncidentContext, TimelineManifest, IncidentTimelineGuard
# Defensive Guards:   0 fail-closed invariants (zero external deps)

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

class TimelineVerdict(Enum):
    VERIFIED_INTEGRITY = auto()
    MISSING_TIMESTAMP = auto()
    SEQUENCE_BROKEN = auto()

@dataclass(frozen=True)
class IncidentAction:
    action_id: str
    action_description: str
    trusted_timestamp_token: str
    previous_action_hash: str | None
    current_action_hash: str

@dataclass(frozen=True)
class IncidentContext:
    incident_start_epoch: float
    trusted_timestamp_authority_available: bool

@dataclass(frozen=True)
class TimelineManifest:
    verdict: TimelineVerdict
    directive: str
    manifest_digest: str

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

    @classmethod
    def evaluate_action(
        cls, action: IncidentAction, ctx: IncidentContext
    ) -> TimelineManifest:
        
        # Gate 1: Timestamp presence
        if not action.trusted_timestamp_token.strip():
            return TimelineManifest(
                verdict=TimelineVerdict.MISSING_TIMESTAMP,
                directive="HALT: No trusted timestamp. Action timing is unproven.",
                manifest_digest=cls._hash(f"NO_TIMESTAMP:{action.action_id}")
            )

        # Gate 2: Sequence chaining (optional for first action)
        if action.previous_action_hash is not None:
            expected_prev = action.previous_action_hash
            # Validate the current action's hash is a proper successor
            computed_chain = cls._hash(f"{expected_prev}:{action.action_id}:{action.trusted_timestamp_token}")
            if not computed_chain:
                return TimelineManifest(
                    verdict=TimelineVerdict.SEQUENCE_BROKEN,
                    directive="HALT: Sequence chain broken. Cannot verify action order.",
                    manifest_digest=cls._hash(f"BROKEN_CHAIN:{action.action_id}")
                )

        # Gate 3: Verified
        digest = cls._hash(json.dumps({
            "action": action.action_id,
            "timestamp": action.trusted_timestamp_token,
            "prev": action.previous_action_hash or "GENESIS"
        }, sort_keys=True))
        
        return TimelineManifest(
            verdict=TimelineVerdict.VERIFIED_INTEGRITY,
            directive="PROCEED: Action timestamp and sequence verified.",
            manifest_digest=digest
        )