spacedb-store

SpaceDB Layer 0 — the per-node storage primitive.

A typed, transactional, order-preserving key/value store that everything else in SpaceDB rests on. Getting this small and correct is the whole game: every layer above inherits its guarantees.

Part of SpaceDB. Dual-licensed MIT OR Apache-2.0.

[dependencies]
spacedb-store = "0.5"

The model

use spacedb_store::{Durability, KvEngine, MemEngine, Table, WriteTx};

let engine = MemEngine::new();
let users: Table<u64, String> = Table::new("users");

// One write transaction spans many tables and commits all-or-nothing.
let mut w = engine.begin_write(Durability::Immediate).unwrap();
users.put(&mut w, &42, &"ada".to_string()).unwrap();
w.commit().unwrap();

let r = engine.begin_read().unwrap();
assert_eq!(users.get(&r, &42).unwrap(), Some("ada".to_string()));

Table<K, V> applies both codecs exactly once, so no layer above ever touches raw bytes.

What's here

Module	What it gives you
`engine`	The `KvEngine` seam — `ReadTx` / `WriteTx` / `Readable`, `Durability`
`redb_engine`	`RedbEngine` — the durable engine (native targets; `redb` 2.x)
`mem_engine`	`MemEngine` — in-memory, identical transaction semantics, for tests
`codec`	Deterministic `postcard` value codec + an order-preserving key codec
`table`	`Table<K, V>` — the typed primitive
`collection`	`Collection` — a schema-versioned namespace over tables
`crypto`	The AEAD row boundary: `seal_row` / `open_row`, DEK wrap / unwrap / rewrap
`meta`	`_meta` store-version gate — refuses to open a store from a newer schema
`extern_value`	Large-value externalization: `classify`, `content_hash`, `ExternRef`

Guarantees

Atomic multi-table writes. One WriteTx spans many tables and commits all-or-nothing; dropping it rolls back.
Order-preserving keys. a < b ⟺ encode(a) < encode(b), so range scans return logical order. The key codec is a verified bijection (proptest).
Single-writer / snapshot reads, identical across both engines — the tests/engines.rs suite runs the same assertions against each.
Encrypted at the value boundary. Rows are sealed with a per-collection DEK (AES-GCM); the DEK itself is wrapped by a key from the KeyProvider seam, so the storage engine never sees plaintext or the master key.
Crash-safe. tests/crash.rs kills the spacedb_crash_helper binary mid-commit and asserts the store reopens with no torn write.

Seams an operator fills

KvEngine — swap the storage engine. Two implementations ship.
KeyProvider — where the wrapping key comes from. MATA binds it to the device vault; a self-hoster can supply a passphrase-derived key.

Open-core boundary

Depends on no MATA crate. MATA-specific capability (vault key, identity, mesh replication, settlement) enters only through seams this crate defines. The dependency arrow is MATA → SpaceDB, never the reverse.

Testing

The workspace defaults to wasm32; this crate is native. Test on your host triple:

cargo test -p spacedb-store --target aarch64-apple-darwin   # or your host triple

Suites: engines.rs (shared semantics), encrypted.rs (AEAD boundary), meta.rs (version gate), crash.rs (kill-mid-commit durability), plus proptest round-trips for both codecs.

License

MIT OR Apache-2.0, at your option. See LICENSE-MIT and LICENSE-APACHE.

spacedb-store 0.5.2