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}