muniment 0.2.0

A portable persistence floor: host-supplied byte backends, typed mutable slots, content-addressed immutable blobs, and append-only journals. Format-agnostic and wasm-friendly.
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
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
// Copyright 2026 Mark Alan Boykin
// This Source Code Form is subject to the terms of the Mozilla Public
// License, v. 2.0. If a copy of the MPL was not distributed with this
// file, You can obtain one at https://mozilla.org/MPL/2.0/.
// SPDX-License-Identifier: MPL-2.0

//! The host-supplied storage backend seam, plus an in-memory backend.

use std::collections::HashMap;
use std::sync::{Arc, Mutex};

use async_trait::async_trait;

use crate::error::StoreError;

/// A single write in an [`apply`](Backend::apply) batch.
#[derive(Clone, Debug, PartialEq, Eq)]
pub enum WriteOp {
    /// Write `value` at `key`, overwriting any previous value.
    Put {
        /// The key to write.
        key: String,
        /// The bytes to store.
        value: Vec<u8>,
    },
    /// Remove `key`. Absent keys are not an error.
    Delete {
        /// The key to remove.
        key: String,
    },
}

/// A consistent read view inside a [`transact`](Backend::transact) closure.
///
/// Every `get`/`list` call against this reader observes the same snapshot the
/// closure's returned [`WriteOp`]s will commit against: no other `apply` or
/// `transact` interleaves between the reader's reads and the eventual commit.
/// This is the seam that lets a caller recheck a fact (a reference prefix is
/// empty, an owner key is absent) and act on it atomically, closing the gap a
/// separate `get` then `delete`/`apply` leaves open.
pub trait TransactionReader {
    /// The bytes at `key` in this transaction's snapshot, or `None` if absent.
    fn get(&self, key: &str) -> Result<Option<Vec<u8>>, StoreError>;

    /// Every key beginning with `prefix` in this transaction's snapshot, in
    /// unspecified order. The read a collection recheck needs: "is any
    /// reference under this prefix still live".
    fn list(&self, prefix: &str) -> Result<Vec<String>, StoreError>;
}

/// The caller closure [`transact`](Backend::transact) runs against a
/// [`TransactionReader`], returning the writes to commit.
///
/// Boxed rather than a generic `impl FnOnce`, so [`Backend`] stays object-safe
/// (`Box<dyn Backend>` is a real, exercised shape below) — a generic method
/// parameter is not expressible on a trait object. `FnOnce` because the
/// closure runs exactly once, synchronously, inside the open transaction; it
/// cannot itself `.await` (an async backend that needs its reads to complete
/// first, like IndexedDB, resolves them before calling the closure, not
/// inside it). Native requires `Send` for the same reason `apply`'s futures
/// do; wasm relaxes it since nothing here crosses a thread.
#[cfg(not(target_arch = "wasm32"))]
pub type TransactFn = Box<dyn FnOnce(&dyn TransactionReader) -> Vec<WriteOp> + Send>;
/// See the native [`TransactFn`] doc; wasm drops the `Send` bound.
#[cfg(target_arch = "wasm32")]
pub type TransactFn = Box<dyn FnOnce(&dyn TransactionReader) -> Vec<WriteOp>>;

/// A host-supplied key/value byte store. The host realizes it as the filesystem
/// on desktop, OPFS in the browser, or an embedded store (redb, fjall). muniment
/// defines the contract; it never picks a backend.
///
/// The async bound is platform-split: `Send` on native, `?Send` on wasm. Browser
/// OPFS on the main thread can only await JS promises, whose futures are not
/// `Send`, so the wasm build relaxes the bound. Native backends (filesystem,
/// redb) do their I/O synchronously and return `Send` futures, so native
/// consumers get the stronger bound and can drive a store from a work-stealing
/// task, which the LogSync drain needs. Same source, one `cfg` seam.
///
/// Keys are opaque strings. muniment's stores namespace them (`blob/<hash>`,
/// a consumer's own slot names); a backend treats them as flat byte keys.
#[cfg_attr(not(target_arch = "wasm32"), async_trait)]
#[cfg_attr(target_arch = "wasm32", async_trait(?Send))]
pub trait Backend {
    /// The bytes at `key`, or `None` if absent.
    async fn get(&self, key: &str) -> Result<Option<Vec<u8>>, StoreError>;

    /// Write `bytes` at `key`, overwriting any previous value.
    async fn put(&self, key: &str, bytes: &[u8]) -> Result<(), StoreError>;

    /// Remove `key`. Absent keys are not an error.
    async fn delete(&self, key: &str) -> Result<(), StoreError>;

    /// Every key beginning with `prefix`, in unspecified order.
    async fn list(&self, prefix: &str) -> Result<Vec<String>, StoreError>;

    /// Keys in the half-open lexicographic range `[start, end)`, in **ascending
    /// order**. This is the ordered read a log needs: a per-author log lives at
    /// contiguous fixed-width keys, so `[lo, hi)` returns its entries in `seq`
    /// order. Implementations back this with a native ordered index (redb ranges,
    /// IndexedDB cursors), or filter and sort [`list`](Backend::list) where none
    /// exists.
    ///
    /// Required rather than defaulted: a defaulted async method's future would
    /// borrow `&self` under the native `Send` bound and so demand `Self: Sync`
    /// from every generic caller. Keeping it required frees consumers of that
    /// bound, and both shipped backends have a real ordered read anyway.
    async fn scan(&self, start: &str, end: &str) -> Result<Vec<String>, StoreError>;

    /// Apply a batch of writes **atomically**: every op lands, or none does.
    ///
    /// One store write can touch several keys (an operation's payload blob plus
    /// its log-index entry), and a reader must never see half of it. A
    /// transactional backend (redb, an IndexedDB object-store transaction) commits
    /// the batch in one transaction; a backend without transactions applies the
    /// ops in order, safe when the writes are content-addressed or idempotent (a
    /// crash mid-batch leaves only recoverable orphans). The whole batch arrives
    /// in one call, so a backend issues every write in a single transaction / tick
    /// with no caller-controlled await between ops.
    ///
    /// Required, not defaulted, for the same reason as [`scan`](Backend::scan): a
    /// default body would leak a `Self: Sync` bound to every generic caller.
    async fn apply(&self, ops: &[WriteOp]) -> Result<(), StoreError>;

    /// Run `f` against one consistent snapshot and commit the [`WriteOp`]s it
    /// returns atomically, or apply nothing.
    ///
    /// This is `apply` with the read half restored: `f` can `get` an owner key
    /// and `list` a reference prefix, then decide what to write, all inside the
    /// same transaction — so a competing claim, transfer, or collection that
    /// lands between the read and the write cannot happen, because there is no
    /// gap between them for it to land in. `Backend::apply` alone cannot express
    /// this: a caller that reads first via `get`/`list` and calls `apply` second
    /// has two separate operations with an interval between them another
    /// `transact` or `apply` can act inside.
    ///
    /// No other `apply`/`transact` call interleaves with this one's reads and
    /// writes: single-writer, or serialized under one lock, per backend.
    ///
    /// Defaulted to a typed refusal ([`StoreError::NotTransactional`]) so an
    /// external `Backend` implementor keeps compiling without adding this;
    /// callers that need the guarantee (custody claims, transfers, collection)
    /// must check for the error and refuse rather than fall back to a racy
    /// `apply`.
    async fn transact(&self, f: TransactFn) -> Result<(), StoreError> {
        let _ = f;
        Err(StoreError::NotTransactional)
    }
}

/// A boxed backend is a backend, so a host can **choose** one at runtime.
///
/// Which store a host uses is not always known when its types are named: a
/// desktop app seals to the user's persona when the identity vault opens and
/// writes plain files when it does not, and both are the same store to
/// everything above. Without this, that choice has to be spelled as a
/// hand-written enum per host, delegating all six methods.
///
/// `Sync` is required because the native bound makes the returned futures
/// `Send`, which needs `&B` to cross threads. Every shipped backend is `Sync`.
#[cfg_attr(not(target_arch = "wasm32"), async_trait)]
#[cfg_attr(target_arch = "wasm32", async_trait(?Send))]
impl<B: Backend + Sync + ?Sized> Backend for Box<B> {
    async fn get(&self, key: &str) -> Result<Option<Vec<u8>>, StoreError> {
        (**self).get(key).await
    }

    async fn put(&self, key: &str, bytes: &[u8]) -> Result<(), StoreError> {
        (**self).put(key, bytes).await
    }

    async fn delete(&self, key: &str) -> Result<(), StoreError> {
        (**self).delete(key).await
    }

    async fn list(&self, prefix: &str) -> Result<Vec<String>, StoreError> {
        (**self).list(prefix).await
    }

    async fn scan(&self, start: &str, end: &str) -> Result<Vec<String>, StoreError> {
        (**self).scan(start, end).await
    }

    async fn apply(&self, ops: &[WriteOp]) -> Result<(), StoreError> {
        (**self).apply(ops).await
    }

    async fn transact(&self, f: TransactFn) -> Result<(), StoreError> {
        (**self).transact(f).await
    }
}

/// A **borrowed** backend is a backend, so a consumer that owns one store
/// handle can layer several muniment stores over it without cloning or moving
/// it — a `BlobStore` and a `SlotStore` on the same keyspace, which is how a
/// blob-plus-slot index is written.
///
/// `Sync` for the same reason `Box<B>` needs it: the native bound makes the
/// returned futures `Send`, so `&B` has to cross threads.
#[cfg_attr(not(target_arch = "wasm32"), async_trait)]
#[cfg_attr(target_arch = "wasm32", async_trait(?Send))]
impl<B: Backend + Sync + ?Sized> Backend for &B {
    async fn get(&self, key: &str) -> Result<Option<Vec<u8>>, StoreError> {
        (**self).get(key).await
    }

    async fn put(&self, key: &str, bytes: &[u8]) -> Result<(), StoreError> {
        (**self).put(key, bytes).await
    }

    async fn delete(&self, key: &str) -> Result<(), StoreError> {
        (**self).delete(key).await
    }

    async fn list(&self, prefix: &str) -> Result<Vec<String>, StoreError> {
        (**self).list(prefix).await
    }

    async fn scan(&self, start: &str, end: &str) -> Result<Vec<String>, StoreError> {
        (**self).scan(start, end).await
    }

    async fn apply(&self, ops: &[WriteOp]) -> Result<(), StoreError> {
        (**self).apply(ops).await
    }

    async fn transact(&self, f: TransactFn) -> Result<(), StoreError> {
        (**self).transact(f).await
    }
}

/// An in-memory [`Backend`], the deterministic test and development floor. Not
/// durable: state lives only as long as the handle. Cheap to clone (a shared
/// handle), so one instance can seed both a `SlotStore` and a `BlobStore`, the
/// way a real filesystem or OPFS handle is cheap to clone.
#[derive(Clone, Default)]
pub struct MemoryBackend {
    map: Arc<Mutex<HashMap<String, Vec<u8>>>>,
}

impl MemoryBackend {
    /// A fresh, empty backend.
    pub fn new() -> Self {
        Self::default()
    }

    /// The number of stored keys.
    pub fn len(&self) -> usize {
        self.map.lock().unwrap().len()
    }

    /// Whether the backend holds no keys.
    pub fn is_empty(&self) -> bool {
        self.map.lock().unwrap().is_empty()
    }
}

#[cfg_attr(not(target_arch = "wasm32"), async_trait)]
#[cfg_attr(target_arch = "wasm32", async_trait(?Send))]
impl Backend for MemoryBackend {
    async fn get(&self, key: &str) -> Result<Option<Vec<u8>>, StoreError> {
        Ok(self.map.lock().unwrap().get(key).cloned())
    }

    async fn put(&self, key: &str, bytes: &[u8]) -> Result<(), StoreError> {
        self.map
            .lock()
            .unwrap()
            .insert(key.to_string(), bytes.to_vec());
        Ok(())
    }

    async fn delete(&self, key: &str) -> Result<(), StoreError> {
        self.map.lock().unwrap().remove(key);
        Ok(())
    }

    async fn list(&self, prefix: &str) -> Result<Vec<String>, StoreError> {
        Ok(self
            .map
            .lock()
            .unwrap()
            .keys()
            .filter(|k| k.starts_with(prefix))
            .cloned()
            .collect())
    }

    async fn scan(&self, start: &str, end: &str) -> Result<Vec<String>, StoreError> {
        let mut keys: Vec<String> = self
            .map
            .lock()
            .unwrap()
            .keys()
            .filter(|k| k.as_str() >= start && k.as_str() < end)
            .cloned()
            .collect();
        keys.sort();
        Ok(keys)
    }

    /// Atomic under the single mutex: the whole batch applies while the lock is
    /// held, so no reader observes a partial batch.
    async fn apply(&self, ops: &[WriteOp]) -> Result<(), StoreError> {
        let mut map = self.map.lock().unwrap();
        for op in ops {
            match op {
                WriteOp::Put { key, value } => {
                    map.insert(key.clone(), value.clone());
                },
                WriteOp::Delete { key } => {
                    map.remove(key);
                },
            }
        }
        Ok(())
    }

    /// Honest under the single mutex: it stays locked from the read `f` makes
    /// through the writes it returns, so no other `apply`/`transact` call can
    /// land between them.
    async fn transact(&self, f: TransactFn) -> Result<(), StoreError> {
        struct MapReader<'a>(&'a HashMap<String, Vec<u8>>);
        impl TransactionReader for MapReader<'_> {
            fn get(&self, key: &str) -> Result<Option<Vec<u8>>, StoreError> {
                Ok(self.0.get(key).cloned())
            }

            fn list(&self, prefix: &str) -> Result<Vec<String>, StoreError> {
                Ok(self
                    .0
                    .keys()
                    .filter(|k| k.starts_with(prefix))
                    .cloned()
                    .collect())
            }
        }

        let mut map = self.map.lock().unwrap();
        let ops = f(&MapReader(&map));
        for op in ops {
            match op {
                WriteOp::Put { key, value } => {
                    map.insert(key, value);
                },
                WriteOp::Delete { key } => {
                    map.remove(&key);
                },
            }
        }
        Ok(())
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    /// Native invariant: a backend's method futures are `Send`, so a store built
    /// over one can be driven from a work-stealing task (the LogSync drain needs
    /// this). The wasm build relaxes to `?Send` for OPFS, so this only asserts on
    /// native. Compile-time: the body never has to run.
    #[cfg(not(target_arch = "wasm32"))]
    #[test]
    fn backend_futures_are_send_on_native() {
        fn assert_send<T: Send>(_: T) {}
        let b = MemoryBackend::new();
        assert_send(b.get("k"));
        assert_send(b.put("k", b"v"));
        assert_send(b.apply(&[]));
    }

    /// A borrowed backend reaches the same keyspace as the owned one, so two
    /// stores can share one handle.
    #[test]
    fn a_borrowed_backend_shares_the_keyspace() {
        pollster::block_on(async {
            let owned = MemoryBackend::new();
            let borrowed: &MemoryBackend = &owned;
            borrowed.put("k", b"v").await.unwrap();
            assert_eq!(owned.get("k").await.unwrap(), Some(b"v".to_vec()));
            assert_eq!(borrowed.list("").await.unwrap(), vec!["k".to_string()]);
        });
    }

    /// A backend seeded with two logs, entries inserted out of order.
    fn seed() -> MemoryBackend {
        let b = MemoryBackend::new();
        pollster::block_on(async {
            for (k, v) in [
                ("log/a/0/0000000000000002", "two"),
                ("log/a/0/0000000000000000", "zero"),
                ("log/a/0/0000000000000001", "one"),
                ("log/b/0/0000000000000000", "other-log"),
            ] {
                b.put(k, v.as_bytes()).await.unwrap();
            }
        });
        b
    }

    #[test]
    fn scan_returns_the_range_in_ascending_order() {
        pollster::block_on(async {
            let b = seed();
            // Log a/0, entries 0..3 in seq order despite insertion order; the
            // other log is excluded by the range.
            let keys = b
                .scan("log/a/0/0000000000000000", "log/a/0/0000000000000003")
                .await
                .unwrap();
            assert_eq!(
                keys,
                vec![
                    "log/a/0/0000000000000000".to_string(),
                    "log/a/0/0000000000000001".to_string(),
                    "log/a/0/0000000000000002".to_string(),
                ]
            );
            // Half-open: [1, 2) is exactly entry 1.
            let one = b
                .scan("log/a/0/0000000000000001", "log/a/0/0000000000000002")
                .await
                .unwrap();
            assert_eq!(one, vec!["log/a/0/0000000000000001".to_string()]);
        });
    }

    #[test]
    fn apply_lands_the_whole_batch() {
        pollster::block_on(async {
            let b = MemoryBackend::new();
            b.put("keep", b"v").await.unwrap();
            b.put("drop", b"v").await.unwrap();
            // One batch: an op header + its payload blob + a delete, all together.
            b.apply(&[
                WriteOp::Put {
                    key: "op/h".into(),
                    value: b"header".to_vec(),
                },
                WriteOp::Put {
                    key: "op/h/payload".into(),
                    value: b"body".to_vec(),
                },
                WriteOp::Delete { key: "drop".into() },
            ])
            .await
            .unwrap();
            assert_eq!(b.get("op/h").await.unwrap(), Some(b"header".to_vec()));
            assert_eq!(b.get("op/h/payload").await.unwrap(), Some(b"body".to_vec()));
            assert_eq!(b.get("drop").await.unwrap(), None);
            assert_eq!(b.get("keep").await.unwrap(), Some(b"v".to_vec()));
        });
    }

    #[test]
    fn apply_takes_the_whole_batch_in_one_call() {
        // The seam-level batch-spanning-await guard: `apply` receives every write
        // at once, so a transactional backend commits them in one transaction with
        // no caller-controlled await between ops. Assert the shape: an empty batch
        // is a no-op; a batch is applied wholesale.
        pollster::block_on(async {
            let b = MemoryBackend::new();
            b.apply(&[]).await.unwrap();
            assert!(b.is_empty(), "empty batch writes nothing");
            b.apply(&[WriteOp::Put {
                key: "k".into(),
                value: b"v".to_vec(),
            }])
            .await
            .unwrap();
            assert_eq!(b.len(), 1);
        });
    }

    #[test]
    fn a_backend_chosen_at_runtime_is_still_a_backend() {
        // What the boxed impl is for: the host decides which store it got, and
        // everything above it stays generic over `B: Backend`.
        pollster::block_on(async {
            fn store<B: Backend>(backend: B) -> B {
                backend
            }
            let chosen: Box<dyn Backend + Send + Sync> = Box::new(MemoryBackend::new());
            let backend = store(chosen);
            backend.put("k", b"v").await.unwrap();
            assert_eq!(backend.get("k").await.unwrap(), Some(b"v".to_vec()));
        });
    }
}