"""C10 cache-provisioning error family.

Rooted at :class:`C10ProvisioningError`; today the family contains
:class:`ManifestWriteError` (AZ-323) covering signing-key load failure,
fingerprint-allowlist rejection, and any I/O failure path during
``ManifestBuilder.build_manifest``. AZ-324 / AZ-325 add additional
subtypes (``ManifestVerifierError``, ``ManifestCoverageError``,
``ContentHashMismatchError``) under the same root as they land.
"""

from __future__ import annotations

__all__ = [
    "C10ProvisioningError",
    "DescriptorBatchError",
    "ManifestWriteError",
]


class C10ProvisioningError(Exception):
    """Base class for the C10 cache-provisioning error family."""


class DescriptorBatchError(C10ProvisioningError):
    """``DescriptorBatcher.populate_descriptors`` could not finish (AZ-322).

    Surfaces three failure modes:

    1. ``"CUDA OOM"`` raised by the injected
       :class:`gps_denied_onboard.components.c10_provisioning.interface.BackboneEmbedder`;
       the batcher catches the OOM-flavoured instance and triggers the
       halve-and-retry loop (AC-2). Persistent OOM after retries are
       exhausted re-raises with the final batch size + tile-id
       context (AC-3).
    2. ``descriptor_dim`` mismatch — the impl returned a column count
       that does not equal :meth:`BackboneEmbedder.descriptor_dim`
       (AC-9); raised BEFORE the FAISS rebuild call so an existing
       valid index is not corrupted.
    3. Underlying FAISS rebuild failure (rewrapped from the AZ-306
       :class:`IndexBuildError` envelope).
    """


class ManifestWriteError(C10ProvisioningError):
    """``ManifestBuilder.build_manifest`` could not produce a signed Manifest.

    Surfaces three failure modes:

    1. Operator-mode signing key fingerprint not in the configured
       allowlist (C10-ST-01).
    2. Signing key file unreadable or malformed PEM (the underlying
       ``cryptography`` exception is chained via ``__cause__``).
    3. Any underlying atomic-write / sidecar failure during Manifest
       or signature emission.

    Callers catch this single envelope; the structured `kind=
    "c10.manifest.build.error"` log payload (set by ``ManifestBuilder``)
    carries the discriminator field.
    """