Skip to main content

eidetic/
lib.rs

1// Copyright 2026 Mark AB (markik)
2// SPDX-License-Identifier: MIT OR Apache-2.0
3
4//! # Eidetic
5//!
6//! Private local-memory lane for the [`mere`](https://crates.io/crates/mere)
7//! browser. Eidetic owns the vocabulary for owner-scoped local blobs, caches,
8//! and accumulated browsing memory — the lane that "keeps the impressions
9//! over time" in Mere's printing-press metaphor (engines → inker → platen →
10//! eidetic).
11//!
12//! Eidetic defines typed [`Request`] / [`Response`] enums, an async [`Store`]
13//! trait that storage backends implement (fjall, redb, OPFS, …), and a
14//! [`dispatch`] helper that routes requests to a store. Eidetic does not pick
15//! a storage backend, mount filesystems, or know about graphs — it is the
16//! pure boundary between reducer-emitted memory requests and concrete blob
17//! storage.
18//!
19//! ## Why async
20//!
21//! Browser-side stores (OPFS via `FileSystemSyncAccessHandle` in workers,
22//! or other wasm-bindgen-backed implementations) cannot expose a synchronous
23//! I/O surface from Rust — there is no `block_on` in wasm32-unknown-unknown.
24//! The trait is therefore async, with native fjall/redb implementations
25//! returning ready futures (no actual async work) and browser implementations
26//! actually awaiting JS Promises. The trait uses `?Send` so it works on both
27//! single-threaded wasm and multi-threaded native; consumers `.await`
28//! eidetic calls in their existing context rather than spawning them.
29//!
30//! Eidetic is distinct from:
31//!
32//! - [`transport`](https://crates.io/crates/transport) (peer
33//!   transport state — networked, not local-private),
34//! - [`gemot`](https://crates.io/crates/gemot) (community/federation
35//!   flora — shared, not private),
36//! - host UI state (transient, not durable).
37//!
38//! ## Temporal-integrity contract (R0 invariant)
39//!
40//! Adopted from the donor `graphshell` history/memory subsystem (per the
41//! [adoption roadmap](../../../../design_docs/mere_docs/implementation_strategy/2026-05-27_adoption_roadmap.md)
42//! R0; the same contract binds the navigation side in
43//! [`node-lineage`](https://docs.rs/node-lineage)). Three invariants, already
44//! embodied by [`engram::Engram`] and the [`Store`] trait, named here so they
45//! hold as backends and tiers are added:
46//!
47//! 1. **Temporal-integrity** — an [`engram::Engram`] is immutable and
48//!    content-hashed; edits do not exist. A refresh produces a *new* engram
49//!    with a fresh hash; a stored blob is never mutated in place.
50//! 2. **Replay-isolation** — reading or replaying stored memory does not mutate
51//!    the store. A [`Store`] read leaves history untouched, so re-deriving a
52//!    past state is side-effect-free.
53//! 3. **Shared-projection** — derived views ("recent", caches, indices) are
54//!    projections over the single engram store, never a second authoritative
55//!    store.
56
57#![doc(html_root_url = "https://docs.rs/eidetic/0.0.1")]
58
59use serde::{Deserialize, Serialize};
60
61pub mod browsing;
62pub mod bundle;
63pub mod deleted;
64pub mod engram;
65pub mod manifest;
66pub mod models;
67pub mod pack;
68pub mod schema;
69pub mod schema_def;
70pub mod seal;
71pub mod typed;
72
73pub use browsing::{
74    BROWSING_TRACE_SCHEMA_REF, BrowsingMemory, BrowsingTrace, PageRef, TraceEvent, TraceTransition,
75    bootstrap_browsing_schema, save_trace,
76};
77pub use bundle::{
78    BUNDLE_SCHEMA_REF, Bundle, BundleMember, bundle_schema_ref, load_bundle, save_bundle,
79    verify_required_members,
80};
81pub use deleted::{DeletedNode, clear_deleted, list_deleted, purge_deleted, record_deleted};
82pub use engram::{Engram, TimeBounds};
83pub use manifest::{BlobFetcher, BlobManifest, BlobSource, NoFetcher, delete_manifest};
84pub use models::{ModelComponents, ModelLibrary, ModelManifest};
85pub use schema::{
86    Hash, ManifestId, ModerationState, PrivacyClass, ProvenanceOrigin, ProvenanceRecord, SchemaRef,
87    SignatureRef, Timestamp, TrustEnvelope, TrustLevel,
88};
89pub use schema_def::{
90    JsonLdValidator, JsonSchemaValidator, META_SCHEMA_REF, MereNativeFieldSpec,
91    MereNativeSchemaBody, MereNativeSchemaBuilder, MereNativeValidator, SchemaDefinition,
92    SchemaFormat, SchemaValidator, bootstrap_meta_schema, find_schema_by_id, load_schema,
93    meta_schema_engram, meta_schema_ref, save_schema, validate_against_schema, validate_payload,
94};
95pub use seal::{
96    PayloadSealer, SealEpochId, SealedBlobRef, is_private_lane, resolve_sealed_blob, seal_marker,
97    seal_payload_for_store,
98};
99pub use typed::{
100    TypedPayload, list_typed, load_typed, load_typed_sealed, save_typed, save_typed_sealed,
101};
102
103/// Request emitted by reducers and routed to a [`Store`].
104#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
105pub enum Request {
106    /// Load a blob by key. The store returns `None` if the key is unknown.
107    LoadBlob { key: String },
108    /// Save a blob under the given key. Overwrites any previous value.
109    SaveBlob { key: String, value: Vec<u8> },
110}
111
112/// Response returned by [`dispatch`] after a [`Request`] resolves.
113#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
114pub enum Response {
115    BlobLoaded { key: String, value: Option<Vec<u8>> },
116    BlobSaved { key: String },
117}
118
119/// Error type returned by [`Store`] implementations and [`dispatch`].
120///
121/// Eidetic uses a small, owned error vocabulary so downstream crates can
122/// `From`-convert into their own error types without taking a dependency on
123/// any particular error library.
124#[derive(Clone, Debug, PartialEq, Eq)]
125pub struct Error {
126    pub message: String,
127}
128
129impl Error {
130    pub fn new(message: impl Into<String>) -> Self {
131        Self {
132            message: message.into(),
133        }
134    }
135}
136
137impl std::fmt::Display for Error {
138    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
139        formatter.write_str(&self.message)
140    }
141}
142
143impl std::error::Error for Error {}
144
145/// Crate-level result alias.
146pub type Result<T> = std::result::Result<T, Error>;
147
148/// The storage seam, **muniment's** (2026-07-12).
149///
150/// Eidetic used to declare its own `Store` trait — get/put/delete/list over
151/// `&str -> Vec<u8>`, async, one method per operation. That was
152/// [`muniment::Backend`] written twice: eidetic poured its own floor before
153/// muniment existed. It now consumes the real one, and `Store` remains as an
154/// alias so every layer above (manifests, schemas, sealing, engrams) reads
155/// unchanged.
156///
157/// What the swap buys beyond deleting a duplicate: backends take `&self`,
158/// `delete`/`list` are required rather than `Err`-by-default, muniment's
159/// `scan` (ordered range) and `apply` (atomic batch) come along, and every
160/// muniment backend (memory, redb) is now an eidetic store — while
161/// eidetic-fjall becomes a backend the whole family can reuse.
162pub use muniment::{Backend, Backend as Store, MemoryBackend, WriteOp};
163
164/// muniment's store errors flow into eidetic's owned error vocabulary, so the
165/// layers above keep returning [`Result`] and `?` still works at every call.
166impl From<muniment::error::StoreError> for Error {
167    fn from(err: muniment::error::StoreError) -> Self {
168        Error::new(err.to_string())
169    }
170}
171
172/// Idempotent first-init seeding for any [`Store`].
173///
174/// Currently equivalent to [`bootstrap_meta_schema`]; in the future will
175/// also seed any other well-known schemas eidetic itself ships with
176/// (e.g. the `OpaqueBlob` schema). Higher-layer consumers that ship their
177/// own schemas (model storage, vector indices, browsing memory) should
178/// follow this pattern with their own `bootstrap_*` helpers.
179pub async fn bootstrap(store: &mut dyn Store) -> Result<()> {
180    bootstrap_meta_schema(store).await
181}
182
183/// Route a [`Request`] to a [`Store`] and produce the matching [`Response`].
184pub async fn dispatch(store: &mut dyn Store, request: &Request) -> Result<Response> {
185    match request {
186        Request::LoadBlob { key } => Ok(Response::BlobLoaded {
187            key: key.clone(),
188            value: store.get(key).await?,
189        }),
190        Request::SaveBlob { key, value } => {
191            store.put(key, value).await?;
192            Ok(Response::BlobSaved { key: key.clone() })
193        }
194    }
195}
196
197#[cfg(test)]
198mod tests {
199    use super::*;
200    use async_trait::async_trait;
201    use muniment::error::StoreError;
202
203    // The in-memory test store is muniment's (2026-07-12): eidetic's
204    // hand-rolled one was the same map behind the same seam.
205    use muniment::MemoryBackend as InMemoryStore;
206
207    #[test]
208    fn dispatch_round_trips_save_then_load() {
209        pollster::block_on(async {
210            let mut store = InMemoryStore::default();
211            let saved = dispatch(
212                &mut store,
213                &Request::SaveBlob {
214                    key: "k".into(),
215                    value: b"hello".to_vec(),
216                },
217            )
218            .await
219            .unwrap();
220            assert_eq!(
221                saved,
222                Response::BlobSaved {
223                    key: "k".to_string()
224                }
225            );
226
227            let loaded = dispatch(&mut store, &Request::LoadBlob { key: "k".into() })
228                .await
229                .unwrap();
230            assert_eq!(
231                loaded,
232                Response::BlobLoaded {
233                    key: "k".to_string(),
234                    value: Some(b"hello".to_vec()),
235                }
236            );
237        });
238    }
239
240    #[test]
241    fn dispatch_load_returns_none_for_unknown_key() {
242        pollster::block_on(async {
243            let mut store = InMemoryStore::default();
244            let loaded = dispatch(
245                &mut store,
246                &Request::LoadBlob {
247                    key: "missing".into(),
248                },
249            )
250            .await
251            .unwrap();
252            assert_eq!(
253                loaded,
254                Response::BlobLoaded {
255                    key: "missing".to_string(),
256                    value: None,
257                }
258            );
259        });
260    }
261
262    #[test]
263    fn dispatch_propagates_store_errors() {
264        // A backend whose disk is on fire, in muniment's vocabulary.
265        struct FailingStore;
266        type R<T> = std::result::Result<T, StoreError>;
267        #[cfg_attr(not(target_arch = "wasm32"), async_trait)]
268        #[cfg_attr(target_arch = "wasm32", async_trait(?Send))]
269        impl Backend for FailingStore {
270            async fn get(&self, _key: &str) -> R<Option<Vec<u8>>> {
271                Err(StoreError::Backend("disk on fire".into()))
272            }
273            async fn put(&self, _key: &str, _bytes: &[u8]) -> R<()> {
274                Err(StoreError::Backend("disk on fire".into()))
275            }
276            async fn delete(&self, _key: &str) -> R<()> {
277                Err(StoreError::Backend("disk on fire".into()))
278            }
279            async fn list(&self, _prefix: &str) -> R<Vec<String>> {
280                Err(StoreError::Backend("disk on fire".into()))
281            }
282            async fn scan(&self, _start: &str, _end: &str) -> R<Vec<String>> {
283                Err(StoreError::Backend("disk on fire".into()))
284            }
285            async fn apply(&self, _ops: &[WriteOp]) -> R<()> {
286                Err(StoreError::Backend("disk on fire".into()))
287            }
288        }
289
290        pollster::block_on(async {
291            let err = dispatch(&mut FailingStore, &Request::LoadBlob { key: "k".into() })
292                .await
293                .unwrap_err();
294            // muniment's StoreError Display prefixes its variant ("backend: …"),
295            // and eidetic's From carries that through — the error vocabulary is
296            // now the seam's, which is the point of the swap.
297            assert_eq!(err.message, "backend: disk on fire");
298        });
299    }
300}