ic_memory/runtime/
admission.rs

1use crate::{
2    AllocationLedger, AllocationState, MemoryManagerSlot, MemoryRequest, SchemaMetadata,
3    SealedDeclarationSnapshot, StableKey,
4};
5
6///
7/// RecoveredAllocationMetadata
8///
9/// Validated allocation evidence borrowed during bootstrap preparation. This
10/// metadata grants no memory access and contains no application payload or
11/// historical authority identity. Host grants supply current authorization.
12///
13
14#[derive(Clone, Copy, Debug)]
15pub struct RecoveredAllocationMetadata<'a> {
16    /// Durable allocation identity.
17    pub stable_key: &'a StableKey,
18    /// Persisted assignment, not permission to open it.
19    pub slot: &'a MemoryManagerSlot,
20    /// Current generic allocation lifecycle state.
21    pub state: AllocationState,
22    /// Latest diagnostic schema metadata, not application schema validation.
23    pub schema: &'a SchemaMetadata,
24}
25
26///
27/// BootstrapAdmissionError
28///
29/// Historical declaration completion rejected before staging or persistence.
30///
31
32#[non_exhaustive]
33#[derive(Clone, Debug, Eq, PartialEq, thiserror::Error)]
34pub enum BootstrapAdmissionError {
35    #[error("historical key {0} is unknown")]
36    Unknown(StableKey),
37    #[error("historical key {0} is retired")]
38    Retired(StableKey),
39    #[error("key {0} is already declared or selected")]
40    Duplicate(StableKey),
41    #[error("completed declarations exceed 254 external allocations")]
42    TooManyDeclarations,
43    #[error("historical selection {stable_key} by {authority} lacks a current grant: {source}")]
44    Range {
45        stable_key: StableKey,
46        authority: String,
47        source: crate::MemoryManagerRangeAuthorityError,
48    },
49    #[error(transparent)]
50    Registry(#[from] crate::StaticMemoryDeclarationError),
51}
52
53///
54/// BootstrapAdmission
55///
56/// Bounded preparation context supplied only after validated ledger recovery.
57/// Consumers may reject identity transitions or explicitly include known
58/// historical allocations before the existing resolve/validate/commit boundary.
59/// No memory handles or mutable recovered state are exposed. Failed selections
60/// poison this attempt even if a consumer ignores their returned errors.
61///
62
63pub struct BootstrapAdmission<'a> {
64    ledger: &'a AllocationLedger,
65    declarations: &'a SealedDeclarationSnapshot,
66    selected: Vec<MemoryRequest>,
67    failure: Option<BootstrapAdmissionError>,
68}
69
70impl<'a> BootstrapAdmission<'a> {
71    pub(super) const fn new(
72        ledger: &'a AllocationLedger,
73        declarations: &'a SealedDeclarationSnapshot,
74    ) -> Self {
75        Self {
76            ledger,
77            declarations,
78            selected: Vec::new(),
79            failure: None,
80        }
81    }
82
83    /// Original sealed input; preparation cannot remove declarations or add grants.
84    #[must_use]
85    pub const fn declarations(&self) -> &SealedDeclarationSnapshot {
86        self.declarations
87    }
88
89    /// At most 255 validated allocation summaries, including governance records.
90    ///
91    /// # Panics
92    ///
93    /// Panics only if an internal validated-ledger invariant is broken.
94    #[must_use = "recovered allocation metadata is inspected only when the iterator is consumed"]
95    pub fn recovered_allocations(
96        &self,
97    ) -> impl ExactSizeIterator<Item = RecoveredAllocationMetadata<'_>> {
98        self.ledger
99            .records()
100            .iter()
101            .map(|record| RecoveredAllocationMetadata {
102                stable_key: record.stable_key(),
103                slot: record.slot(),
104                state: record.state(),
105                schema: record.schema(),
106            })
107    }
108
109    /// Whether the original input or an earlier selection already names this key.
110    #[must_use]
111    pub fn is_declared(&self, key: &StableKey) -> bool {
112        // Sealing owns canonical fixed/request keys. Selections retain callback
113        // order, so only that unsealed tail needs a scan.
114        key.as_str() == crate::IC_MEMORY_LEDGER_STABLE_KEY
115            || self.declarations.registered_declaration(key).is_some()
116            || self
117                .declarations
118                .requests()
119                .binary_search_by(|request| request.stable_key().cmp(key))
120                .is_ok()
121            || self
122                .selected
123                .iter()
124                .any(|request| request.stable_key() == key)
125    }
126
127    /// Include a known, nonretired key under an explicit current host grant.
128    /// Retains its slot and latest schema metadata. Final current policy and all
129    /// ordinary collision/retirement checks still run after preparation.
130    pub fn include_historical(
131        &mut self,
132        authority: &str,
133        stable_key: &str,
134    ) -> Result<(), BootstrapAdmissionError> {
135        if let Some(error) = &self.failure {
136            return Err(error.clone());
137        }
138        let result = self.select(authority, stable_key);
139        if let Err(error) = &result {
140            self.failure = Some(error.clone());
141        }
142        result
143    }
144
145    fn select(&mut self, authority: &str, stable_key: &str) -> Result<(), BootstrapAdmissionError> {
146        // Constructor bounds names before they can enter selection diagnostics.
147        let request = MemoryRequest::new(authority, stable_key, SchemaMetadata::default())?;
148        let key = request.stable_key();
149        if self.is_declared(key) {
150            return Err(BootstrapAdmissionError::Duplicate(key.clone()));
151        }
152        if self.declarations.registered_declarations().len()
153            + self.declarations.requests().len()
154            + self.selected.len()
155            >= 254
156        {
157            return Err(BootstrapAdmissionError::TooManyDeclarations);
158        }
159        let record = self
160            .ledger
161            .records()
162            .iter()
163            .find(|r| r.stable_key() == key)
164            .ok_or_else(|| BootstrapAdmissionError::Unknown(key.clone()))?;
165        if matches!(record.state(), AllocationState::Retired) {
166            return Err(BootstrapAdmissionError::Retired(key.clone()));
167        }
168        self.declarations
169            .range_authority()
170            .validate_slot_authority(record.slot(), authority)
171            .map_err(|source| BootstrapAdmissionError::Range {
172                stable_key: key.clone(),
173                authority: authority.to_string(),
174                source,
175            })?;
176        self.selected
177            .push(request.with_schema(record.schema().clone()));
178        Ok(())
179    }
180
181    pub(super) fn complete(self) -> Result<Vec<MemoryRequest>, BootstrapAdmissionError> {
182        if let Some(error) = self.failure {
183            return Err(error);
184        }
185        Ok(self.selected)
186    }
187}
ic_memory/runtime/admission.rs

ic_memory/runtime/
admission.rs
