"""Hook Registry — stabile Einhängepunkte (AP1.0 definitions only)."""

from __future__ import annotations

from dataclasses import dataclass

_HOOKS: dict[str, "HookDefinition"] = {}


@dataclass(frozen=True)
class HookDefinition:
    slug: str
    lifecycle_step: str
    description: str
    since_version: str = "0.11.0"


def register_hook(defn: HookDefinition) -> None:
    if defn.slug in _HOOKS:
        raise ValueError(f"Hook already registered: {defn.slug}")
    _HOOKS[defn.slug] = defn


def get_hook(slug: str) -> HookDefinition | None:
    return _HOOKS.get(slug)


def list_hooks() -> tuple[HookDefinition, ...]:
    return tuple(_HOOKS.values())


def clear_hooks_for_tests() -> None:
    _HOOKS.clear()


def register_builtin_hooks() -> None:
    """Slugs aus Target Architecture §7.3 — Handler folgen in AP1.3."""
    builtins = (
        ("on_goal_captured", "intake", "Ziel erfasst"),
        ("on_method_selected", "method_selection", "Methode gewählt"),
        ("on_structure_required", "structure_setup", "Struktur erforderlich"),
        ("on_backlog_required", "structure_setup", "Backlog erforderlich"),
        ("on_next_action_requested", "action_selection", "Nächste Aktion angefragt"),
        ("on_assignment_required", "assignment", "Zuweisung erforderlich"),
        ("on_blocker_open", "waiting", "Blocker gemeldet"),
        ("on_blocker_resolved", "action_selection", "Blocker geschlossen"),
        ("on_wait_started", "waiting", "Warten begonnen"),
        ("on_result_received", "result_intake", "Ergebnis eingegangen"),
        ("on_evidence_required", "validation", "Nachweis erforderlich"),
        ("on_review_due", "review", "Review fällig"),
        ("on_review_completed", "review", "Review abgeschlossen"),
        ("on_replan_required", "adaptation", "Anpassung nötig"),
        ("on_closure_requested", "closure", "Abschluss angefragt"),
    )
    for slug, step, desc in builtins:
        if slug not in _HOOKS:
            register_hook(
                HookDefinition(
                    slug=slug,
                    lifecycle_step=step,
                    description=desc,
                )
            )