ic_memory/
capability.rs

1use crate::{declaration::AllocationDeclaration, key::StableKey, slot::AllocationSlotDescriptor};
2use std::sync::Arc;
3
4///
5/// ValidatedAllocations
6///
7/// Pre-commit allocation declarations accepted by policy and historical ledger
8/// validation.
9///
10/// This value is produced by [`crate::validate_allocations`] and may be staged
11/// into the next ledger generation. It cannot open storage. Only a
12/// [`CommittedAllocations`] capability confirmed after persistence can do that.
13///
14/// This is an in-memory capability, not a serde DTO. It has no public
15/// constructor and should only be produced by validation or bootstrap paths.
16///
17
18#[derive(Clone, Debug, Eq, PartialEq)]
19pub struct ValidatedAllocations {
20    inner: Arc<ValidatedState>,
21    _private: (),
22}
23
24#[derive(Clone, Debug, Eq, PartialEq)]
25struct ValidatedState {
26    /// Recovered generation against which these declarations were validated.
27    base_generation: u64,
28    /// Validated declarations.
29    declarations: Vec<AllocationDeclaration>,
30    /// Optional binary/runtime identity for generation diagnostics.
31    runtime_fingerprint: Option<String>,
32}
33
34impl ValidatedAllocations {
35    pub(crate) fn new(
36        base_generation: u64,
37        declarations: Vec<AllocationDeclaration>,
38        runtime_fingerprint: Option<String>,
39    ) -> Self {
40        Self {
41            inner: Arc::new(ValidatedState {
42                base_generation,
43                declarations,
44                runtime_fingerprint,
45            }),
46            _private: (),
47        }
48    }
49
50    /// Return the recovered generation used as the validation base.
51    #[must_use]
52    pub fn base_generation(&self) -> u64 {
53        self.inner.base_generation
54    }
55
56    /// Borrow the validated declarations.
57    #[must_use]
58    pub fn declarations(&self) -> &[AllocationDeclaration] {
59        &self.inner.declarations
60    }
61
62    /// Borrow the optional runtime fingerprint.
63    #[must_use]
64    pub fn runtime_fingerprint(&self) -> Option<&str> {
65        self.inner.runtime_fingerprint.as_deref()
66    }
67
68    /// Find a validated slot by stable key.
69    #[must_use]
70    pub fn slot_for(&self, key: &StableKey) -> Option<&AllocationSlotDescriptor> {
71        self.declarations()
72            .iter()
73            .find(|declaration| &declaration.stable_key == key)
74            .map(|declaration| &declaration.slot)
75    }
76
77    pub(crate) const fn confirm_persisted(self, generation: u64) -> CommittedAllocations {
78        CommittedAllocations {
79            validated: self,
80            generation,
81            _private: (),
82        }
83    }
84}
85
86///
87/// CommittedAllocations
88///
89/// Allocation-open capability confirmed after the validated ledger generation
90/// was persisted.
91///
92/// This type is not serializable, default-constructible, or publicly
93/// constructible. Generic persistence owners obtain it only by explicitly
94/// confirming a successful [`crate::PendingBootstrapCommit`]. A
95/// [`crate::MemoryRuntime`] stores it only after that runtime's stable-cell write
96/// succeeds.
97///
98
99#[derive(Clone, Debug, Eq, PartialEq)]
100pub struct CommittedAllocations {
101    validated: ValidatedAllocations,
102    generation: u64,
103    _private: (),
104}
105
106impl CommittedAllocations {
107    /// Return the persisted ledger generation that grants this capability.
108    #[must_use]
109    pub const fn generation(&self) -> u64 {
110        self.generation
111    }
112
113    /// Borrow the committed allocation declarations.
114    #[must_use]
115    pub fn declarations(&self) -> &[AllocationDeclaration] {
116        self.validated.declarations()
117    }
118
119    /// Borrow the optional runtime fingerprint.
120    #[must_use]
121    pub fn runtime_fingerprint(&self) -> Option<&str> {
122        self.validated.runtime_fingerprint()
123    }
124
125    /// Find a committed slot by stable key.
126    #[must_use]
127    pub fn slot_for(&self, key: &StableKey) -> Option<&AllocationSlotDescriptor> {
128        self.validated.slot_for(key)
129    }
130
131    pub(crate) fn without_stable_key_prefix(mut self, prefix: &str) -> Self {
132        let mut state = (*self.validated.inner).clone();
133        state
134            .declarations
135            .retain(|declaration| !declaration.stable_key.as_str().starts_with(prefix));
136        self.validated.inner = Arc::new(state);
137        self
138    }
139}
ic_memory/capability.rs

ic_memory/
capability.rs
