ic-memory 0.0.2

Persistent allocation-governance infrastructure for Internet Computer stable memory
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82

# ic-memory

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

The core invariant is:

```text
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](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

```rust
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.