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//! `ic-stable-structures` `MemoryManager` IDs are the first-class supported
40//! physical slot substrate. The crate still keeps narrow internal abstractions
41//! for storage adapters and diagnostics, but the native IC path is
42//! `MemoryManager` ID 0 -> `ic-stable-structures::Cell<StableCellLedgerRecord,
43//! _>` -> [`LedgerCommitStore`] -> committed [`AllocationLedger`] payloads.
44//!
45//! `ic-memory` is not a replacement for `ic-stable-structures` collections and
46//! does not wrap typed stores such as `StableBTreeMap`.
47
48pub mod bootstrap;
49pub mod declaration;
50pub mod diagnostics;
51pub mod key;
52pub mod ledger;
53pub mod physical;
54pub mod policy;
55pub mod schema;
56pub mod session;
57pub mod slot;
58pub mod stable_cell;
59pub mod substrate;
60pub mod validation;
61
62pub use ic_stable_structures as stable_structures;
63
64pub use bootstrap::{
65    AllocationBootstrap, BootstrapCommit, BootstrapError, BootstrapReservationError,
66    BootstrapRetirementError,
67};
68pub use declaration::{
69    AllocationDeclaration, DeclarationCollector, DeclarationSnapshot, DeclarationSnapshotError,
70};
71pub use diagnostics::{DiagnosticExport, DiagnosticGeneration, DiagnosticRecord};
72pub use key::{StableKey, StableKeyError};
73pub use ledger::{
74    AllocationHistory, AllocationLedger, AllocationRecord, AllocationReservationError,
75    AllocationRetirement, AllocationRetirementError, AllocationStageError, AllocationState,
76    CURRENT_LEDGER_SCHEMA_VERSION, CURRENT_PHYSICAL_FORMAT_ID, CborLedgerCodec, GenerationRecord,
77    LedgerCodec, LedgerCommitError, LedgerCommitStore, LedgerCompatibility,
78    LedgerCompatibilityError, LedgerIntegrityError, SchemaMetadataRecord,
79};
80pub use physical::{
81    AuthoritativeSlot, CommitRecoveryError, CommitSlotDiagnostic, CommitSlotIndex,
82    CommitStoreDiagnostic, CommittedGenerationBytes, DualCommitStore, DualProtectedCommitStore,
83    ProtectedGenerationSlot, select_authoritative_slot,
84};
85pub use policy::{AllocationPolicy, NamespaceAuthority, RangeAuthority};
86pub use schema::{SchemaMetadata, SchemaMetadataError};
87pub use session::{AllocationSession, AllocationSessionError, ValidatedAllocations};
88pub use slot::{
89    AllocationSlot, AllocationSlotDescriptor, IC_MEMORY_AUTHORITY_OWNER,
90    IC_MEMORY_AUTHORITY_PURPOSE, IC_MEMORY_LEDGER_LABEL, IC_MEMORY_LEDGER_STABLE_KEY,
91    IC_MEMORY_STABLE_KEY_PREFIX, MEMORY_MANAGER_DESCRIPTOR_VERSION,
92    MEMORY_MANAGER_GOVERNANCE_MAX_ID, MEMORY_MANAGER_INVALID_ID, MEMORY_MANAGER_LEDGER_ID,
93    MEMORY_MANAGER_MAX_ID, MEMORY_MANAGER_MIN_ID, MEMORY_MANAGER_SUBSTRATE,
94    MemoryManagerAuthorityRecord, MemoryManagerIdRange, MemoryManagerRangeAuthority,
95    MemoryManagerRangeAuthorityError, MemoryManagerRangeError, MemoryManagerRangeMode,
96    MemoryManagerSlotError, is_ic_memory_stable_key, memory_manager_governance_range,
97    validate_memory_manager_id,
98};
99pub use stable_cell::{
100    STABLE_CELL_HEADER_SIZE, STABLE_CELL_LAYOUT_VERSION, STABLE_CELL_MAGIC,
101    STABLE_CELL_VALUE_OFFSET, StableCellLedgerRecord, StableCellPayloadError,
102    decode_stable_cell_ledger_record, decode_stable_cell_payload,
103};
104pub use substrate::{LedgerAnchor, StorageSubstrate};
105pub use validation::{AllocationValidationError, validate_allocations};
ic_memory/lib.rs

ic_memory/
lib.rs
