Crate ic_memory 

ic-memory

ic-memory is persistent allocation-governance infrastructure for Internet Computer stable memory.

The core invariant is:

stable_key -> allocation_slot forever

The crate is intentionally generic. It owns durable allocation facts, stable-key parsing, allocation-slot descriptors, declaration snapshot sealing, ledger data shapes, policy traits, substrate traits, protected generation commit mechanics, diagnostics, and validated allocation sessions.

Decoded durable ledgers and public DTO structs are untrusted until validated. Recovery and commit paths use strict committed-ledger validation before a ledger can become authoritative. The non-negotiable invariants are recorded in SAFETY.md.

Framework-specific rules belong in adapter crates. Namespace ownership, controller authorization, endpoint dispatch, install/upgrade lifecycle, schema migration, and application policy are not generic ic-memory responsibilities.

Status

0.0.1 is the first standalone split from Canic. The public API is intended to stabilize around persistent allocation ownership, but downstream frameworks should still treat this line as early infrastructure while the extraction finishes.

What It Provides

• Canonical stable-key parsing.
• Allocation slot descriptors.
• Declaration collection and duplicate rejection.
• Allocation policy and substrate traits.
• Durable allocation history records.
• Generation-scoped staging and commit helpers.
• Tombstone and reservation lifecycle primitives.
• Rollback-safe allocation validation.
• Protected dual-slot commit recovery primitives.
• Read-only diagnostic export shapes.

What It Does Not Own

• Framework namespace policy.
• Framework/app range ownership.
• Controller authorization.
• Canister endpoint dispatch.
• Runtime bootstrap orchestration.
• Store-level schema migrations.
• Internet Computer management-canister calls.

Example Shape

use ic_memory::{
    AllocationDeclaration, DeclarationCollector, SchemaMetadata,
};

let mut declarations = DeclarationCollector::default();
let declaration = AllocationDeclaration::new(
    "app.orders.primary.v1",
    ic_memory::AllocationSlotDescriptor::memory_manager(100).expect("usable slot"),
    Some("orders".to_string()),
    SchemaMetadata::default(),
)
.expect("valid allocation declaration");
declarations.push(declaration);

let snapshot = declarations.seal().expect("valid declaration snapshot");

Opening a stable-memory handle is deliberately a separate phase. Frameworks collect declarations, validate them against policy and historical ledger state, publish a validated allocation session, and only then open substrate slots.

The protected physical checksum detects torn writes and accidental corruption. It is not a cryptographic integrity mechanism and must not be treated as adversarial tamper resistance. Persistent allocation-governance primitives for Internet Computer stable memory.

The crate models durable ownership as stable_key -> allocation_slot forever. It intentionally does not own framework namespaces, controller authorization, endpoint lifecycle, schema migrations, or Canic-specific memory ID policy.

Re-exports

pub use bootstrap::AllocationBootstrap;

pub use bootstrap::BootstrapCommit;

pub use bootstrap::BootstrapError;

pub use bootstrap::BootstrapReservationError;

pub use bootstrap::BootstrapRetirementError;

pub use declaration::AllocationDeclaration;

pub use declaration::DeclarationCollector;

pub use declaration::DeclarationSnapshot;

pub use declaration::DeclarationSnapshotError;

pub use diagnostics::DiagnosticExport;

pub use diagnostics::DiagnosticGeneration;

pub use diagnostics::DiagnosticRecord;

pub use generation::GenerationCommit;

pub use generation::GenerationMutation;

pub use generation::StagedGeneration;

pub use key::StableKey;

pub use key::StableKeyError;

pub use ledger::AllocationHistory;

pub use ledger::AllocationLedger;

pub use ledger::AllocationRecord;

pub use ledger::AllocationReservationError;

pub use ledger::AllocationRetirement;

pub use ledger::AllocationRetirementError;

pub use ledger::AllocationStageError;

pub use ledger::AllocationState;

pub use ledger::CURRENT_LEDGER_SCHEMA_VERSION;

pub use ledger::CURRENT_PHYSICAL_FORMAT_ID;

pub use ledger::GenerationRecord;

pub use ledger::LedgerCodec;

pub use ledger::LedgerCommitError;

pub use ledger::LedgerCommitStore;

pub use ledger::LedgerCompatibility;

pub use ledger::LedgerCompatibilityError;

pub use ledger::LedgerIntegrityError;

pub use ledger::SchemaMetadataRecord;

pub use physical::AuthoritativeSlot;

pub use physical::CommitRecoveryError;

pub use physical::CommitSlotDiagnostic;

pub use physical::CommitSlotIndex;

pub use physical::CommitStoreDiagnostic;

pub use physical::CommittedGenerationBytes;

pub use physical::DualCommitStore;

pub use physical::DualProtectedCommitStore;

pub use physical::ProtectedGenerationSlot;

pub use physical::select_authoritative_slot;

pub use policy::AllocationPolicy;

pub use policy::NamespaceAuthority;

pub use policy::RangeAuthority;

pub use schema::SchemaMetadata;

pub use schema::SchemaMetadataError;

pub use session::AllocationSession;

pub use session::AllocationSessionError;

pub use session::ValidatedAllocations;

pub use slot::AllocationSlot;

pub use slot::AllocationSlotDescriptor;

pub use slot::MEMORY_MANAGER_DESCRIPTOR_VERSION;

pub use slot::MEMORY_MANAGER_INVALID_ID;

pub use slot::MEMORY_MANAGER_MAX_ID;

pub use slot::MEMORY_MANAGER_MIN_ID;

pub use slot::MEMORY_MANAGER_SUBSTRATE;

pub use slot::MemoryManagerIdRange;

pub use slot::MemoryManagerRangeError;

pub use slot::MemoryManagerSlotError;

pub use slot::validate_memory_manager_id;

pub use substrate::LedgerAnchor;

pub use substrate::StorageSubstrate;

pub use validation::AllocationValidationError;

pub use validation::validate_allocations;

Modules

bootstrap

declaration

diagnostics

generation

key

ledger

physical

policy

schema

session

slot

substrate

validation