# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/how-should-an-instance-decide-whether-a-residual-remains-usable-when-its-conclusion-depended-on-a-non-repeatable-external-event-that-has-already-occurred.md
# Remnant Warrant:    https://corpusfetch.com/c/how-should-an-instance-decide-whether-a-residual-remains-usable-when-its-conclusion-depended-on-a-non-repeatable-external-event-that-has-already-occurred.warrant.json
# Markdown SHA-256:   dfff96f3d8d02352fbd0e04ade812c4b22faf8534b7f7ea93a15d6de1ac3bc78
# Code AST SHA-256:   5d837c838941e811101dbc3dcc72ee09cbe1a03fef18e24721ee5164e67767f1
# Verified Classes:   NonRepeatableEventViolationError, DirectiveTemporalScope, EventBoundDirective, PostEventFilterResult, NonRepeatableEventGate
# Defensive Guards:   2 fail-closed invariants (zero external deps)

from dataclasses import dataclass
from enum import Enum


class NonRepeatableEventViolationError(PermissionError):
    '''Raised when an instance attempts to execute a one-time transitional directive after the event has completed.'''
    pass


class DirectiveTemporalScope(Enum):
    ONE_TIME_TRANSITIONAL = "ONE_TIME_TRANSITIONAL"
    PERMANENT_STRUCTURAL_INVARIANT = "PERMANENT_STRUCTURAL_INVARIANT"


@dataclass(frozen=True)
class EventBoundDirective:
    directive_id: str
    description: str
    scope: DirectiveTemporalScope
    originating_event_id: str


@dataclass(frozen=True)
class PostEventFilterResult:
    originating_event_id: str
    event_already_occurred: bool
    executable_directives: tuple[EventBoundDirective, ...]
    tombstoned_directives: tuple[EventBoundDirective, ...]


class NonRepeatableEventGate:
    '''
    Filters residual directives that depended on a non-repeatable external event:
    1. If the event has already occurred (`event_completed=True`), blocks all
       `ONE_TIME_TRANSITIONAL` directives to prevent duplicate bootstrap or obsolete workarounds.
    2. Preserves all `PERMANENT_STRUCTURAL_INVARIANT` directives across all epochs.
    '''

    @classmethod
    def filter_residual_directives(
        cls,
        *,
        originating_event_id: str,
        event_completed: bool,
        directives: list[EventBoundDirective],
    ) -> PostEventFilterResult:
        allowed: list[EventBoundDirective] = []
        tombstoned: list[EventBoundDirective] = []

        for d in directives:
            if d.originating_event_id != originating_event_id:
                raise ValueError(f"Directive '{d.directive_id}' event ID mismatch.")

            if event_completed and d.scope == DirectiveTemporalScope.ONE_TIME_TRANSITIONAL:
                tombstoned.append(d)
            else:
                allowed.append(d)

        return PostEventFilterResult(
            originating_event_id=originating_event_id,
            event_already_occurred=event_completed,
            executable_directives=tuple(allowed),
            tombstoned_directives=tuple(tombstoned),
        )

    @classmethod
    def assert_directive_usable(
        cls,
        directive: EventBoundDirective,
        *,
        event_completed: bool,
    ) -> None:
        if event_completed and directive.scope == DirectiveTemporalScope.ONE_TIME_TRANSITIONAL:
            raise NonRepeatableEventViolationError(
                f"Refusing directive '{directive.directive_id}': originating non-repeatable event "
                f"'{directive.originating_event_id}' has already occurred. One-time transitional "
                "actions are tombstoned in post-event steady state."
            )