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//!
22//! The carrier-event declaration (`AxCode::carrier`) lives together with
23//! `kernel::event` because it names `EventKind`.
24
25mod code;
26mod provider;
27mod refusal;
28mod shape;
29
30pub use code::{AxCode, Carrier};
31pub use provider::ProviderFailureKind;
32pub use refusal::GateRefusal;
33pub use shape::{AxError, ErrorDraft, Retry};