"""Fail-closed compatibility shim for the uncommissioned NFC reader.

No AINA deployment profile currently binds an NFC reader identity, USB path,
payload schema, or Supraworx receipt.  The legacy helper therefore remains
importable but cannot open arbitrary USB NFC hardware or forward tag dumps.
"""

from __future__ import annotations

from typing import Any, Optional

LEGACY_NFC_READER_DISABLED_MESSAGE = (
    "NFC access is unavailable: no commissioned AINA reader and identity "
    "contract is configured"
)


class LegacyNFCReaderDisabledError(RuntimeError):
    """Raised for all uncommissioned NFC hardware entry points."""


def _format_identifier(identifier: Any) -> Optional[str]:
    """Retain the pure identifier formatter for import compatibility."""

    if identifier is None:
        return None
    if isinstance(identifier, (bytes, bytearray)):
        return identifier.hex()
    return str(identifier)


def _disabled(*_args, **_kwargs):
    raise LegacyNFCReaderDisabledError(LEGACY_NFC_READER_DISABLED_MESSAGE)


def read_nfc_tag(*args, **kwargs):
    _disabled(*args, **kwargs)


def read_and_forward_nfc(*args, **kwargs):
    _disabled(*args, **kwargs)
