"""The shipped unreachable-engine stance map.

This is the map the surface actually applies. ``pep-stance.yaml`` publishes it,
and ``tests/test_layer_conformance.py`` asserts the two are equal — a published
map that may drift from the code invites reliance it cannot support.

Built to v0.8 obligation 3 per GH-DEC-2026-012: the axis is enumerated rather
than defaulted, ``unknown`` resolves to ``fail_closed``, and an absent scope is
distinguishable in the record from an unknown one.
"""

from __future__ import annotations

from enum import Enum

AXIS = "binding_level"

#: Total by enumeration, not by catch-all. See ``pep-stance.yaml`` for why every
#: stance is ``fail_closed`` here where ops-warden can justify ``fail_open``.
STANCE: dict[str, str] = {
    "acknowledgment": "fail_closed",
    "organizational": "fail_closed",
    "aes": "fail_closed",
    "qes": "fail_closed",
    "unknown": "fail_closed",
    "absent": "fail_closed",
}

#: Values of the axis proper — the two non-value outcomes are not axis values.
AXIS_VALUES: tuple[str, ...] = ("acknowledgment", "organizational", "aes", "qes")


class BindingLevelState(str, Enum):
    """How the axis value was obtained. Recorded; never collapsed.

    ``ABSENT`` and ``UNKNOWN`` resolve to the same stance but must never be
    recorded as the same fact: collapsing them hides a schema-drift incident
    inside a malformed-input statistic.
    """

    PRESENT = "present"
    ABSENT = "absent"
    UNKNOWN = "unknown"


def resolve(binding_level: str | None) -> tuple[str, BindingLevelState]:
    """Return ``(stance, state)`` for a memo's ``binding_level``.

    There is no per-call discretion and no implicit default: an unlisted value
    is resolved explicitly to the ``unknown`` stance, never permissively.
    """
    if binding_level is None or binding_level == "":
        return STANCE["absent"], BindingLevelState.ABSENT
    if binding_level not in AXIS_VALUES:
        return STANCE["unknown"], BindingLevelState.UNKNOWN
    return STANCE[binding_level], BindingLevelState.PRESENT