"""Exception hierarchy for govtool.

Every failure mode in the amendment pipeline maps to a typed exception so
that CI gates and the CLI can distinguish "your proposal is malformed"
from "the ledger has been tampered with" from "the vote did not pass".

All exceptions derive from :class:`GovtoolError`, so callers that just
want a clean exit can catch the base class.
"""

from __future__ import annotations


class GovtoolError(Exception):
    """Base class for all govtool errors."""


# --- serialization / validation -------------------------------------------

class ValidationError(GovtoolError):
    """A document or object failed structural validation."""


class SchemaError(ValidationError):
    """A document failed JSON-schema validation."""


class CanonicalizationError(GovtoolError):
    """An object could not be canonically serialized (e.g. non-JSON type)."""


# --- keys / signatures ------------------------------------------------------

class KeyManagementError(GovtoolError):
    """A key could not be generated, parsed, loaded, or stored."""


class SignatureError(GovtoolError):
    """A digital signature was malformed or failed verification."""


# --- citizens / eligibility -------------------------------------------------

class RegistryError(GovtoolError):
    """The citizen registry is missing, malformed, or inconsistent."""


class EligibilityError(GovtoolError):
    """A voter is not eligible to vote on a proposal."""


# --- proposals / ballots ----------------------------------------------------

class ProposalError(GovtoolError):
    """A proposal is malformed or violates pipeline rules."""


class ProposalStateError(ProposalError):
    """An operation was attempted in an illegal proposal lifecycle state."""


class BallotError(GovtoolError):
    """A ballot is malformed or could not be cast."""


class TallyError(GovtoolError):
    """A tally could not be computed."""


# --- ledger -----------------------------------------------------------------

class LedgerError(GovtoolError):
    """The audit ledger could not be read or written."""


class LedgerIntegrityError(LedgerError):
    """The audit ledger hash chain failed verification: possible tampering."""


# --- classification / gate --------------------------------------------------

class ClassificationError(GovtoolError):
    """A change set could not be classified under governance semver."""


class GateError(GovtoolError):
    """The vote gate could not run or refused to proceed."""


class InvariantViolation(GateError):
    """A proposal touches constitutional invariants without the explicit,
    auditable acknowledgement the kernel requires."""


# --- forks ------------------------------------------------------------------

class ForkError(GovtoolError):
    """Fork creation, upstream tracking, or upstream pull failed."""