ic_memory/ledger/
error.rs

1use crate::{
2    key::StableKey, ledger::LedgerPayloadEnvelopeError, physical::CommitRecoveryError,
3    slot::MemoryManagerSlot,
4};
5
6///
7/// LedgerIntegrityError
8///
9/// Decoded ledger violates current ownership invariants.
10///
11
12#[non_exhaustive]
13#[derive(Clone, Debug, Eq, thiserror::Error, PartialEq)]
14pub enum LedgerIntegrityError {
15    /// Current structural recovery ceiling exceeded.
16    #[error("ledger exceeds {resource} limit {limit}")]
17    LimitExceeded {
18        resource: &'static str,
19        limit: usize,
20    },
21    /// Stable key appears in more than one retained allocation record.
22    #[error("stable key '{stable_key}' appears in more than one allocation record")]
23    DuplicateStableKey { stable_key: StableKey },
24    /// Memory ID appears in more than one retained allocation record.
25    #[error("allocation slot '{slot:?}' appears in more than one allocation record")]
26    DuplicateSlot { slot: MemoryManagerSlot },
27    /// Commit counter zero is reserved for empty genesis.
28    #[error("genesis ledger contains allocation records")]
29    NonemptyGenesis,
30}
31
32///
33/// LedgerCommitError
34///
35/// Failure to recover or commit a logical allocation ledger.
36#[non_exhaustive]
37#[derive(Clone, Debug, Eq, thiserror::Error, PartialEq)]
38pub enum LedgerCommitError {
39    /// Protected physical commit recovery failed.
40    #[error(transparent)]
41    Recovery(CommitRecoveryError),
42    /// Logical ledger payload envelope could not be decoded.
43    #[error(transparent)]
44    PayloadEnvelope(LedgerPayloadEnvelopeError),
45    /// Physical slot generation and decoded logical ledger generation disagree.
46    #[error(
47        "physical generation {physical_generation} does not match logical ledger generation {logical_generation}"
48    )]
49    PhysicalLogicalGenerationMismatch {
50        /// Generation encoded in the physical snapshot.
51        physical_generation: u64,
52        /// Generation decoded from the logical allocation ledger.
53        logical_generation: u64,
54    },
55    /// Built-in ledger decoding failed.
56    #[error("allocation ledger codec failed: {0}")]
57    Codec(String),
58    /// Decoded ledger violates current ownership invariants.
59    #[error(transparent)]
60    Integrity(LedgerIntegrityError),
61}
62
63///
64/// AllocationStageError
65///
66/// Failure to stage a validated allocation generation.
67///
68
69#[non_exhaustive]
70#[derive(Clone, Debug, Eq, thiserror::Error, PartialEq)]
71pub enum AllocationStageError {
72    /// The commit counter cannot advance without overflow.
73    #[error("ledger generation {generation} cannot be advanced without overflow")]
74    GenerationOverflow { generation: u64 },
75    #[error(transparent)]
76    Integrity(#[from] LedgerIntegrityError),
77    /// Validated declarations were produced against a different ledger generation.
78    #[error(
79        "validated allocations were produced at generation {validated_generation}, but ledger is at generation {ledger_generation}"
80    )]
81    StaleValidatedAllocations {
82        /// Generation carried by the validated allocation capability.
83        validated_generation: u64,
84        /// Current ledger generation.
85        ledger_generation: u64,
86    },
87    /// Stable key was historically bound to a different slot.
88    #[error("stable key '{stable_key}' was historically bound to a different allocation slot")]
89    StableKeySlotConflict {
90        /// Stable key being declared.
91        stable_key: StableKey,
92        /// Historical slot for the stable key.
93        historical_slot: MemoryManagerSlot,
94        /// Slot claimed by the declaration.
95        declared_slot: MemoryManagerSlot,
96    },
97    /// Slot was historically bound to a different stable key.
98    #[error("allocation slot '{slot:?}' was historically bound to stable key '{historical_key}'")]
99    SlotStableKeyConflict {
100        /// Slot being declared.
101        slot: MemoryManagerSlot,
102        /// Historical stable key for the slot.
103        historical_key: StableKey,
104        /// Stable key claimed by the declaration.
105        declared_key: StableKey,
106    },
107    /// Current declaration attempted to revive a retired allocation.
108    #[error("stable key '{stable_key}' was explicitly retired and cannot be redeclared")]
109    RetiredAllocation {
110        /// Retired stable key.
111        stable_key: StableKey,
112        /// Retired allocation slot.
113        slot: MemoryManagerSlot,
114    },
115}
ic_memory/ledger/error.rs

ic_memory/ledger/
error.rs
