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: a logical stable key must keep
9//! owning the same physical allocation slot across upgrades. The crate records
10//! and validates durable ownership as `stable_key -> allocation_slot forever`.
11//!
12//! This crate owns allocation invariants, not framework policy. Namespace
13//! rules, range ownership, controller authorization, endpoint lifecycle, schema
14//! migrations, and application validation belong to the framework or
15//! application.
16//!
17//! Use these primitives before opening stable-memory handles. Integrations
18//! should recover the historical ledger, validate current declarations, commit a
19//! new generation, and only then publish a validated allocation session that can
20//! open slots through a storage substrate.
21//!
22//! The APIs are generic over storage substrates. `ic-stable-structures`
23//! `MemoryManager` IDs are supported as durable slot descriptors, but this crate
24//! is not a replacement for `ic-stable-structures` and is not Canic-specific.
25
26pub mod bootstrap;
27pub mod declaration;
28pub mod diagnostics;
29pub mod generation;
30pub mod key;
31pub mod ledger;
32pub mod physical;
33pub mod policy;
34pub mod schema;
35pub mod session;
36pub mod slot;
37pub mod substrate;
38pub mod validation;
39
40pub use bootstrap::{
41    AllocationBootstrap, BootstrapCommit, BootstrapError, BootstrapReservationError,
42    BootstrapRetirementError,
43};
44pub use declaration::{
45    AllocationDeclaration, DeclarationCollector, DeclarationSnapshot, DeclarationSnapshotError,
46};
47pub use diagnostics::{DiagnosticExport, DiagnosticGeneration, DiagnosticRecord};
48pub use generation::{GenerationCommit, GenerationMutation, StagedGeneration};
49pub use key::{StableKey, StableKeyError};
50pub use ledger::{
51    AllocationHistory, AllocationLedger, AllocationRecord, AllocationReservationError,
52    AllocationRetirement, AllocationRetirementError, AllocationStageError, AllocationState,
53    CURRENT_LEDGER_SCHEMA_VERSION, CURRENT_PHYSICAL_FORMAT_ID, GenerationRecord, LedgerCodec,
54    LedgerCommitError, LedgerCommitStore, LedgerCompatibility, LedgerCompatibilityError,
55    LedgerIntegrityError, SchemaMetadataRecord,
56};
57pub use physical::{
58    AuthoritativeSlot, CommitRecoveryError, CommitSlotDiagnostic, CommitSlotIndex,
59    CommitStoreDiagnostic, CommittedGenerationBytes, DualCommitStore, DualProtectedCommitStore,
60    ProtectedGenerationSlot, select_authoritative_slot,
61};
62pub use policy::{AllocationPolicy, NamespaceAuthority, RangeAuthority};
63pub use schema::{SchemaMetadata, SchemaMetadataError};
64pub use session::{AllocationSession, AllocationSessionError, ValidatedAllocations};
65pub use slot::{
66    AllocationSlot, AllocationSlotDescriptor, IC_MEMORY_AUTHORITY_OWNER,
67    IC_MEMORY_AUTHORITY_PURPOSE, IC_MEMORY_LEDGER_LABEL, IC_MEMORY_LEDGER_STABLE_KEY,
68    IC_MEMORY_STABLE_KEY_PREFIX, MEMORY_MANAGER_DESCRIPTOR_VERSION,
69    MEMORY_MANAGER_GOVERNANCE_MAX_ID, MEMORY_MANAGER_INVALID_ID, MEMORY_MANAGER_LEDGER_ID,
70    MEMORY_MANAGER_MAX_ID, MEMORY_MANAGER_MIN_ID, MEMORY_MANAGER_SUBSTRATE, MemoryManagerIdRange,
71    MemoryManagerRangeError, MemoryManagerSlotError, is_ic_memory_stable_key,
72    memory_manager_governance_range, validate_memory_manager_id,
73};
74pub use substrate::{LedgerAnchor, StorageSubstrate};
75pub use validation::{AllocationValidationError, validate_allocations};
ic_memory/lib.rs

ic_memory/
lib.rs
