ic_memory/
lib.rs

1#![forbid(unsafe_code)]
2#![deny(rustdoc::broken_intra_doc_links)]
3#![doc = include_str!("../README.md")]
4
5//! Stable-memory allocation-governance primitives for Internet Computer
6//! canister upgrades.
7//!
8//! `ic-memory` prevents stable-memory slot drift.
9//!
10//! Once a stable key is committed to a physical allocation slot, future binaries
11//! must either reopen that same stable key on that same slot or declare a new
12//! stable key.
13//!
14//! The crate records and validates durable ownership in both directions: an
15//! active stable key cannot move to a different physical slot, and an active
16//! physical slot cannot be reused by a different stable key.
17//!
18//! The intended integration flow is:
19//!
20//! 1. Recover the persisted allocation ledger.
21//! 2. Declare the stable stores expected by the current binary.
22//! 3. Validate those declarations against ledger history and any framework
23//!    policy.
24//! 4. Commit the next generation.
25//! 5. Only then open stable-memory handles through a validated allocation
26//!    session.
27//!
28//! This crate owns allocation invariants, not framework policy. Namespace
29//! rules, range ownership, controller authorization, endpoint lifecycle, schema
30//! migrations, and application validation belong to the framework or
31//! application.
32//!
33//! Use these primitives before opening stable-memory handles. Integrations
34//! should recover the historical ledger, declare the stores expected by the
35//! current binary, validate declarations against history and policy, commit a
36//! new generation, and only then publish a validated allocation session that can
37//! open slots through a storage substrate.
38//!
39//! The APIs are generic over storage substrates. `ic-stable-structures`
40//! `MemoryManager` IDs are supported as durable slot descriptors, but this crate
41//! is not a replacement for `ic-stable-structures` and is not Canic-specific.
42
43pub mod bootstrap;
44pub mod declaration;
45pub mod diagnostics;
46pub mod key;
47pub mod ledger;
48pub mod physical;
49pub mod policy;
50pub mod schema;
51pub mod session;
52pub mod slot;
53pub mod substrate;
54pub mod validation;
55
56pub use bootstrap::{
57    AllocationBootstrap, BootstrapCommit, BootstrapError, BootstrapReservationError,
58    BootstrapRetirementError,
59};
60pub use declaration::{
61    AllocationDeclaration, DeclarationCollector, DeclarationSnapshot, DeclarationSnapshotError,
62};
63pub use diagnostics::{DiagnosticExport, DiagnosticGeneration, DiagnosticRecord};
64pub use key::{StableKey, StableKeyError};
65pub use ledger::{
66    AllocationHistory, AllocationLedger, AllocationRecord, AllocationReservationError,
67    AllocationRetirement, AllocationRetirementError, AllocationStageError, AllocationState,
68    CURRENT_LEDGER_SCHEMA_VERSION, CURRENT_PHYSICAL_FORMAT_ID, GenerationRecord, LedgerCodec,
69    LedgerCommitError, LedgerCommitStore, LedgerCompatibility, LedgerCompatibilityError,
70    LedgerIntegrityError, SchemaMetadataRecord,
71};
72pub use physical::{
73    AuthoritativeSlot, CommitRecoveryError, CommitSlotDiagnostic, CommitSlotIndex,
74    CommitStoreDiagnostic, CommittedGenerationBytes, DualCommitStore, DualProtectedCommitStore,
75    ProtectedGenerationSlot, select_authoritative_slot,
76};
77pub use policy::{AllocationPolicy, NamespaceAuthority, RangeAuthority};
78pub use schema::{SchemaMetadata, SchemaMetadataError};
79pub use session::{AllocationSession, AllocationSessionError, ValidatedAllocations};
80pub use slot::{
81    AllocationSlot, AllocationSlotDescriptor, IC_MEMORY_AUTHORITY_OWNER,
82    IC_MEMORY_AUTHORITY_PURPOSE, IC_MEMORY_LEDGER_LABEL, IC_MEMORY_LEDGER_STABLE_KEY,
83    IC_MEMORY_STABLE_KEY_PREFIX, MEMORY_MANAGER_DESCRIPTOR_VERSION,
84    MEMORY_MANAGER_GOVERNANCE_MAX_ID, MEMORY_MANAGER_INVALID_ID, MEMORY_MANAGER_LEDGER_ID,
85    MEMORY_MANAGER_MAX_ID, MEMORY_MANAGER_MIN_ID, MEMORY_MANAGER_SUBSTRATE,
86    MemoryManagerAuthorityRecord, MemoryManagerIdRange, MemoryManagerRangeAuthority,
87    MemoryManagerRangeAuthorityError, MemoryManagerRangeError, MemoryManagerRangeMode,
88    MemoryManagerSlotError, is_ic_memory_stable_key, memory_manager_governance_range,
89    validate_memory_manager_id,
90};
91pub use substrate::{LedgerAnchor, StorageSubstrate};
92pub use validation::{AllocationValidationError, validate_allocations};
ic_memory/lib.rs

ic_memory/
lib.rs
