ic_memory/policy.rs
1use crate::{key::StableKey, slot::AllocationSlotDescriptor};
2
3///
4/// AllocationPolicy
5///
6/// Framework-supplied rules for whether a key may claim a slot.
7///
8/// Policy is intentionally separate from the durable ledger invariant. The
9/// ledger remembers `stable_key -> allocation_slot`; this trait lets an
10/// integration reject declarations that do not belong to its namespace or
11/// substrate-specific range before staging a generation.
12///
13/// In the default `MemoryManager` runtime, registered range claims are checked
14/// before this policy, and this policy receives external declarations only.
15/// The internal allocation-ledger declaration remains exclusively governed by
16/// ic-memory. Framework adapters should decide whether registered range claims
17/// or their own policy is authoritative for application ID space, then register
18/// ranges accordingly.
19///
20
21pub trait AllocationPolicy {
22 /// Policy error type.
23 type Error;
24
25 /// Validate a stable key against framework naming rules.
26 fn validate_key(&self, key: &StableKey) -> Result<(), Self::Error>;
27
28 /// Validate a stable-key to allocation-slot claim.
29 fn validate_slot(
30 &self,
31 key: &StableKey,
32 slot: &AllocationSlotDescriptor,
33 ) -> Result<(), Self::Error>;
34
35 /// Validate a reserved stable-key to allocation-slot claim.
36 fn validate_reserved_slot(
37 &self,
38 key: &StableKey,
39 slot: &AllocationSlotDescriptor,
40 ) -> Result<(), Self::Error>;
41}
42
43///
44/// RuntimeBootstrapPolicy
45///
46/// Allocation policy with an explicit semantic identity for runtime bootstrap.
47///
48/// [`crate::MemoryRuntime`] binds its successful bootstrap to this identity.
49/// Repeated bootstrap is idempotent only when the caller supplies the same
50/// sealed declaration snapshot and the same policy identity. Implementations
51/// should change the identity whenever policy configuration or semantics
52/// change. The identity must be a non-empty static string, normally a
53/// versioned framework or application constant.
54///
55
56pub trait RuntimeBootstrapPolicy: AllocationPolicy {
57 /// Return the stable semantic identity of this policy configuration.
58 fn runtime_bootstrap_identity(&self) -> &'static str;
59}