# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/erosion-of-human-capacity-due-to-ai-instances-and-llms-systems.md
# Remnant Warrant:    https://corpusfetch.com/c/erosion-of-human-capacity-due-to-ai-instances-and-llms-systems.warrant.json
# Markdown SHA-256:   c25e64e496c58a0cdd332a84a97990b99858d0a80418de625cf37a213f5455b0
# Code AST SHA-256:   f039cd7b2fb775389cb767949da5946161a445b29a9b81fd85df059c7a0383a7
# Verified Classes:   OpaqueAutomationHazardError, GlassBoxHandoffPackage, HumanCapacityPreservationGate
# Defensive Guards:   3 fail-closed invariants (zero external deps)

from dataclasses import dataclass
from typing import Final


class OpaqueAutomationHazardError(ValueError):
    '''Raised when an automated deliverable lacks causal invariant explanations or human verification anchors.'''
    pass


@dataclass(frozen=True)
class GlassBoxHandoffPackage:
    task_id: str
    root_cause_mechanism: str
    enforced_invariant: str
    human_verification_command: str
    critical_review_locus: str
    max_cyclomatic_nesting_depth: int


class HumanCapacityPreservationGate:
    '''
    Prevents cognitive atrophy and rubber-stamp blindness during AI-to-human handoffs:
    1. Requires an explicit `root_cause_mechanism` and `enforced_invariant` (Glass-Box visibility).
    2. Requires a concrete `human_verification_command` and `critical_review_locus` so the
       human operator remains actively in the verification loop.
    3. Enforces a maximum nesting depth ceiling (`MAX_NESTING_DEPTH = 4`) so generated code
       remains cognitively maintainable by humans.
    '''

    MAX_ALLOWED_NESTING_DEPTH: Final[int] = 4

    @classmethod
    def validate_handoff_package(cls, pkg: GlassBoxHandoffPackage) -> GlassBoxHandoffPackage:
        if not pkg.root_cause_mechanism.strip() or not pkg.enforced_invariant.strip():
            raise OpaqueAutomationHazardError(
                f"Task '{pkg.task_id}' rejected: opaque black-box output. Must state both "
                "root_cause_mechanism and enforced_invariant to preserve human situational awareness."
            )

        if not pkg.human_verification_command.strip() or not pkg.critical_review_locus.strip():
            raise OpaqueAutomationHazardError(
                f"Task '{pkg.task_id}' rejected: missing anti-rubber-stamp verification anchor "
                "(human_verification_command and critical_review_locus required)."
            )

        if pkg.max_cyclomatic_nesting_depth > cls.MAX_ALLOWED_NESTING_DEPTH:
            raise OpaqueAutomationHazardError(
                f"Task '{pkg.task_id}' rejected: code nesting depth ({pkg.max_cyclomatic_nesting_depth}) "
                f"exceeds human-maintainability bound ({cls.MAX_ALLOWED_NESTING_DEPTH}). Flatten control flow."
            )

        return pkg