# This is error handling — refusal as afterthought
def execute_action(action):
    try:
        result = perform(action)
        return result
    except PolicyViolation as e:
        # Refusal is a CATCH block. An exception. An edge case.
        return {"error": "Action not permitted"}


# This is refusal infrastructure — refusal as designed outcome
def process_action(action, governance_context):
    """
    Refusal and execution are EQUAL outcomes of governance.
    Neither is the 'happy path' — both are valid results
    of a governed system operating correctly.
    """
    decision = governance_layer.evaluate(action, governance_context)

    if decision.outcome == "allow":
        return execution_path(action, decision.constraints)

    if decision.outcome == "deny":
        return refusal_path(action, decision)

    if decision.outcome == "defer":
        return escalation_path(action, decision)

class RefusalResponse:
    """
    Structured refusal that enables upstream systems to
    respond intelligently rather than just displaying errors.

    This response goes BACK to the system that requested
    the action (often your AI/LLM layer).
    """

    def __init__(self, decision):
        # WHAT was refused
        self.refused_action = decision.original_intent

        # WHY it was refused (structured, not free-text)
        self.refusal_reason = RefusalReason(
            category=decision.denial_category,  # e.g., "insufficient_context", 
                                                 # "policy_violation",
                                                 # "scope_exceeded"
            policy_reference=decision.triggering_policy,
            explanation=decision.human_readable_reason
        )

        # WHAT COULD make this action allowable
        # (if anything — some actions are categorically denied)
        self.remediation = self.compute_remediation(decision)

        # WHETHER escalation is available
        self.escalation_available = decision.escalation_path is not None
        self.escalation_context = decision.review_payload


def compute_remediation(self, decision):
    """
    If the action COULD be allowed under different conditions,
    describe what those conditions are.

    This enables the upstream system to either:
    - Modify the action to comply
    - Request additional context/permissions
    - Escalate to a human reviewer

    Not all refusals are remediable. Some actions are
    categorically prohibited regardless of context.
    """
    if decision.is_categorical_denial:
        return Remediation(
            remediable=False,
            reason="This action category is prohibited by policy"
        )

    return Remediation(
        remediable=True,
        missing_conditions=decision.unsatisfied_conditions,
        suggested_modifications=decision.compliant_alternatives
    )

class RefusalAuditRecord:
    """
    Immutable record proving that governance enforcement
    occurred and produced a correct decision.

    This record serves multiple audiences:
    - Compliance teams (proving controls are effective)
    - Security teams (detecting anomalous refusal patterns)
    - Engineering teams (identifying policy tuning needs)
    - Regulators (demonstrating systematic governance)
    """

    # Temporal context
    timestamp: datetime
    trace_id: str

    # What was attempted
    action_intent: ActionIntent
    requesting_entity: str
    session_context: dict

    # Governance decision details
    policies_evaluated: list        # Which policies were checked
    triggering_policy: str          # Which policy caused denial
    policy_version: str             # Exact version for reproducibility
    decision_reasoning: str         # Structured explanation

    # Refusal handling
    refusal_category: str           # Classification of denial type
    remediation_offered: bool       # Was a path forward provided?
    escalation_triggered: bool      # Was human review requested?

    # Integrity
    record_hash: str                # Tamper-evidence
    previous_hash: str              # Chain to previous record


def emit_refusal_audit(intent, decision, context):
    """
    Every refusal produces an audit record.

    Design principle: The absence of a refusal record for
    a sensitive action is itself a compliance finding.
    If you can't prove governance evaluated it, you can't
    prove governance was in effect.
    """
    record = RefusalAuditRecord(
        timestamp=now(),
        trace_id=intent.trace_id,
        action_intent=intent,
        requesting_entity=context.entity_id,
        policies_evaluated=[p.id for p in decision.trace],
        triggering_policy=decision.triggering_policy,
        policy_version=decision.policy_version,
        decision_reasoning=decision.reasoning,
        refusal_category=classify_refusal(decision),
        remediation_offered=decision.remediation is not None,
        escalation_triggered=decision.outcome == "defer"
    )

    # Immutable storage — append only
    audit_store.append(record)

    # Emit event for real-time monitoring
    event_bus.emit("governance.refusal", record)

class RefusalObservability:
    """
    Monitoring and alerting on refusal patterns.

    Refusal metrics are LEADING indicators of system health.
    Execution failures are LAGGING indicators.

    By monitoring refusals, you catch problems before they
    become incidents.
    """

    def track_refusal(self, refusal_record):
        # Metric: Refusal rate by category
        metrics.increment(
            "governance.refusal.count",
            tags={
                "category": refusal_record.refusal_category,
                "policy": refusal_record.triggering_policy,
                "entity": refusal_record.requesting_entity
            }
        )

        # Alert: Sudden spike in refusals (possible misconfiguration)
        if self.detect_spike("refusal_rate", window="5m"):
            alert.fire(
                severity="warning",
                message="Refusal rate spike detected",
                context=self.recent_refusal_summary()
            )

        # Alert: New refusal category appearing (possible new attack vector)
        if self.is_novel_pattern(refusal_record):
            alert.fire(
                severity="info",
                message="Novel refusal pattern detected",
                context=refusal_record
            )

        # Metric: Remediation success rate
        # (how often does a refusal lead to successful retry?)
        self.track_remediation_outcome(refusal_record)

class EscalationManager:
    """
    Manages the flow from governance deferral to human decision.

    Key principle: Deferred actions are QUEUED, not dropped.
    The system remembers what was requested and presents it
    to a human reviewer with full context.
    """

    def escalate(self, intent, decision):
        # Create review request with full context
        review = ReviewRequest(
            action_intent=intent,
            governance_decision=decision,

            # Context for the human reviewer
            why_deferred=decision.reasoning,
            risk_assessment=self.assess_risk(intent),
            similar_past_decisions=self.find_precedents(intent),

            # What happens with the reviewer's decision
            approval_action=self.define_approval_path(intent),
            denial_action=self.define_denial_path(intent),

            # Timeout behavior
            timeout_duration=self.calculate_timeout(intent),
            timeout_action="deny"  # Default to denial on timeout
        )

        # Route to appropriate reviewer
        reviewer = self.resolve_reviewer(intent, decision)
        review_queue.submit(review, reviewer)

        # Notify requesting system that action is pending
        return DeferralResponse(
            status="pending_review",
            review_id=review.id,
            estimated_resolution=review.timeout_duration,
            # System can poll or subscribe for resolution
            resolution_endpoint=f"/reviews/{review.id}/status"
        )

class RefusalCategory:
    """
    Taxonomy of refusal types. Each category implies
    different handling by upstream systems.
    """

    # Action is categorically prohibited — no remediation possible
    CATEGORICAL_PROHIBITION = "categorical"
    # Example: "Delete all patient records" — never allowed

    # Action requires context that isn't present
    INSUFFICIENT_CONTEXT = "insufficient_context"  
    # Example: "Access record" but no patient consent on file
    # Remediation: Obtain consent, then retry

    # Action exceeds the requester's scope
    SCOPE_EXCEEDED = "scope_exceeded"
    # Example: Analyst-level context requesting admin action
    # Remediation: Escalate to appropriate authority

    # Action violates temporal constraints
    TEMPORAL_VIOLATION = "temporal"
    # Example: Write operation during read-only maintenance window
    # Remediation: Retry after window closes

    # Action conflicts with current system state
    STATE_CONFLICT = "state_conflict"
    # Example: Modifying a record currently under review
    # Remediation: Wait for review completion

    # Action requires human approval (deferral, not denial)
    REQUIRES_HUMAN = "requires_human"
    # Example: Action with irreversible consequences above threshold
    # Remediation: Escalation flow