kernel/error.rs
1// This Source Code Form is subject to the terms of the Mozilla Public
2// License, v. 2.0. If a copy of the MPL was not distributed with this
3// file, You can obtain one at https://mozilla.org/MPL/2.0/.
4// Copyright (c) 2026 2youg1 and the sprawling contributors
5
6//! AxError, the one error shape of the whole city, and
7//! AxCode, the closed set of 35 error codes.
8//! The part `crates/kernel/spec/Error.lean` specifies this module.
9//!
10//! Invariants owned here:
11//! - every wire spelling (`E_…`) has exactly one authority: [`AxCode::as_str`];
12//! serde delegates to it in both directions, so enum and wire cannot drift.
13//! - a gate refusal always carries the three mandatory parts (rule,
14//! violation, alternative): [`AxError::refusal`] is the only path that
15//! sets them and [`AxError::failure`] cannot.
16//! - every constructed error says what to do next: both constructors
17//! return an [`ErrorDraft`], and [`ErrorDraft::with_recovery`] is the
18//! only way to obtain an [`AxError`].
19//! - `retry` defaults to `Retry::No`; a caller must opt in explicitly
20//! (fail-closed).
21//! - `account` is `AccountDisposition::Advance` only beside `Retry::No`
22//! with no wait: [`ErrorDraft::account_unusable`] is the only path that
23//! sets it, and every other retry builder puts it back to `Keep`.
24//!
25//! The carrier-event declaration (`AxCode::carrier`) lives together with
26//! `kernel::event` because it names `EventKind`.
27
28mod code;
29mod provider;
30mod refusal;
31mod shape;
32
33pub use code::{AxCode, Carrier};
34pub use provider::{AccountDisposition, ProviderFailureKind};
35pub use refusal::GateRefusal;
36pub use shape::{AxError, ErrorDraft, Retry};