spacedb_store/
lib.rs

1#![forbid(unsafe_code)]
2//! # spacedb-store — SpaceDB Layer 0
3//!
4//! The per-node storage **primitive**: a typed, transactional, order-preserving
5//! key/value store that everything else in SpaceDB rests on. Getting this small
6//! and correct is the whole game — every layer above inherits its guarantees.
7//!
8//! ## What S1 ships
9//!
10//! - [`KvEngine`] — the engine seam, with two implementations that share
11//!   identical transaction semantics: [`RedbEngine`] (durable) and [`MemEngine`]
12//!   (in-memory, for tests).
13//! - [`codec`] — a deterministic `postcard` value codec and an order-preserving
14//!   key codec (`a < b ⟺ encode(a) < encode(b)`), each a verified bijection.
15//! - [`Table`] — the typed `Table<K, V>` primitive that applies both codecs once
16//!   so layers above never touch raw bytes.
17//!
18//! ## Guarantees
19//!
20//! - **Atomic multi-table writes.** One [`WriteTx`] spans many tables and commits
21//!   all-or-nothing; dropping it rolls back.
22//! - **Logical-order range scans**, courtesy of the order-preserving key codec.
23//! - **Single-writer / snapshot reads**, identical across both engines.
24//!
25//! ## Open-core boundary
26//!
27//! `spacedb-store` is MIT and depends on **no** MATA crate. MATA-specific
28//! capabilities (the vault key, identity, mesh replication, settlement) enter
29//! later through *seams this crate defines* — e.g. the `KeyProvider` for the AEAD
30//! boundary in S2 — which MATA implements in its proprietary hosted product. The
31//! dependency arrow is MATA → SpaceDB, never the reverse.
32
33mod error;
34pub use error::{StoreError, StoreResult};
35
36pub mod codec;
37pub use codec::{decode_value, encode_value, KeyDecode, KeyEncode};
38
39pub mod engine;
40pub use engine::{Durability, KvEngine, ReadTx, Readable, WriteTx};
41
42pub mod mem_engine;
43pub use mem_engine::MemEngine;
44
45// Native-only: redb needs real file I/O. Wasm builds use `MemEngine`; the host
46// environment persists snapshots (e.g. IndexedDB in a browser) via its own adapter.
47#[cfg(not(target_arch = "wasm32"))]
48pub mod redb_engine;
49#[cfg(not(target_arch = "wasm32"))]
50pub use redb_engine::RedbEngine;
51
52pub mod table;
53pub use table::Table;
54
55pub mod crypto;
56pub use crypto::{
57    open_row, rewrap_dek, seal_row, unwrap_dek, wrap_fresh_dek, CryptoError, KeyProvider,
58    StaticKeyProvider, WrappedDek, KEY_LEN, NONCE_LEN,
59};
60
61pub mod collection;
62pub use collection::Collection;
63
64pub mod meta;
65pub use meta::{
66    open_meta, open_meta_with, read_store_version, write_store_version, MetaStatus, Migration,
67    STORE_FORMAT_VERSION,
68};
69
70pub mod extern_value;
71pub use extern_value::{classify, content_hash, should_externalize, ExternRef, ValuePlacement};
72
73/// Compiles the README's examples as doctests, so the documented API can never
74/// drift from the real one. Not part of the public API, and not rendered into
75/// the crate docs — it exists only under `cargo test --doc`.
76#[cfg(doctest)]
77#[doc = include_str!("../README.md")]
78pub struct ReadmeDoctests;
spacedb_store/lib.rs

spacedb_store/
lib.rs
