"""Kind registry — the four-rule partial-support contract (§2.5 of the design doc).

Rule 1: supported kinds are declared explicitly in a single constant.
Rule 2: unknown kinds are classified as "skipped, unsupported".
Rule 3: vendor-namespace sections (x_<vendor>.*) get the vendor name extracted.
Rule 4: implemented in qvf.py (sha256 verify-before-use guard).
"""

from __future__ import annotations

# ── Rule 1: single explicit registry ──────────────────────────────────────
SUPPORTED_KINDS: frozenset[str] = frozenset(
    {
        "structure",
        "volume.density",
        "volume.orbital",
        "volume.spin",
        "volume.elf",
        "volume.difference",
        "volume.generic",
        "bands",
        "spectra.ir",
        "spectra.uvvis",
        "spectra.raman",
        "spectra.ecd",
        "spectra.vcd",
        "spectra.generic",
        "trajectory",
        "reaction.path",
        "reaction.waypoints",
        "vibrations",
        "atom_properties",
        "wavefunction.gto",
        "citations",
        "scf_history",
        "structure.symmetry",
        "spectra.nmr",
        "dos.total",
        "dos.projected",
    }
)

# Kinds whose binary .dat blob is lazy-loaded (read from zip only on
# first UI activation, not at file-open time).
LAZY_KINDS: frozenset[str] = frozenset(
    {
        "volume.density",
        "volume.orbital",
        "volume.spin",
        "volume.elf",
        "volume.difference",
        "volume.generic",
    }
)


def classify_section(kind: str) -> tuple[str, str | None]:
    """Return ``(status, detail)`` for a section kind.

    status is one of: ``"rendered"``, ``"skipped"``, ``"error"``.
    detail is ``None`` for rendered sections, or a human-readable
    reason string for skipped/error sections.

    ── Rule 2 + 3: unknown kinds and vendor namespaces.
    """
    if kind in SUPPORTED_KINDS:
        return ("rendered", None)
    # Rule 3: vendor-namespace sections
    if kind.startswith("x_"):
        # kind = "x_<vendor>.<rest>" → extract vendor name
        prefix = kind.split(".", 1)[0]  # "x_<vendor>"
        parts = prefix.split("_", 1)
        vendor = parts[1] if len(parts) > 1 else "unknown"
        return ("skipped", f"vendor namespace ({vendor})")
    return ("skipped", "unsupported")


def is_lazy_kind(kind: str) -> bool:
    """Return True if this kind's binary data should be lazy-loaded."""
    return kind in LAZY_KINDS