Struct Memory 

pub struct Memory<'a> { /* private fields */ }

The memory engine. See the module docs for staging.

The lifetime 'a is the provenance of the engine’s byte pools. Every owned constructor (new/open/from_bytes) yields a Memory<'static> that owns its bytes; the read-only Memory::from_bytes_borrowed path borrows them from an mmap’d snapshot instead of copying.

Implementations

impl Memory<'_>

pub fn maintain<S: Storage>( &mut self, store: &mut S, now: u64, ) -> Result<MaintainReport, Error>

Physically purges tombstoned facts and compacts every satellite structure. Ids of living facts are preserved; purged ids are burned (never reissued); observable state is unchanged; only bytes shrink. Journaled as a Maintain marker so replay reproduces the compaction exactly.

Errors

Error::CapacityExceeded if a rebuilt pool hits its ceiling (it cannot, being a subset of the live data, but the path is honest), or an Error::Storage from the journal append — in either case nothing is swapped in and the engine is unchanged.

pub fn snapshot_disk_first<T: Scratch, V: Scratch, Sk: SnapshotSink>( &self, created_at: u64, text_scratch: &mut T, vec_scratch: &mut V, sink: Sk, ) -> Result<usize, Error>

Disk-first compaction (milestone H): rebuilds the compacted image and writes it to sink, streaming the two big pools (text, vectors) through text_scratch/vec_scratch so peak RAM stays ∝ the record count (metadata + graph), never ∝ the content size. Byte-identical to a snapshot taken after an in-RAM Memory::maintain — it drives the same walk (rebuild_parts) and the same emit (write_snapshot_with), the pools merely borrowing the frozen scratch instead of RAM. Returns the purge count.

Errors

Error::Corrupt for a malformed source, Error::Storage from a scratch or the sink, or a pool ceiling error (a subset never exceeds it).

impl<'a> Memory<'a>

pub fn write_snapshot_to( &self, created_at: u64, sink: impl SnapshotSink, ) -> Result<(), Error>

Streams the whole engine into snapshot-container bytes through sink, never materializing the full image: a first pass computes each section’s length and checksum, the header+table prefix is written, then a second pass streams the section bodies (the dominant vector pool straight from its borrowed pieces) while a running hash accumulates the file checksum, patched into the header at the end. Deterministic and canonical — byte-identical to Memory::snapshot_bytes.

Errors

Propagates whatever sink reports (e.g. an I/O error from a file sink).

pub fn snapshot_bytes(&self, created_at: u64) -> Vec<u8>

Serializes the whole engine into snapshot-container bytes. Deterministic and canonical: save → load → save is byte-identical. A thin wrapper over Memory::write_snapshot_to into a Vec; large databases should prefer streaming into a file sink.

pub fn snapshot<S: Storage>( &mut self, store: &mut S, now: u64, ) -> Result<(), Error>

Writes a full snapshot and clears the journal.

pub fn verify(&self) -> Result<(), Error>

Runs the integrity checks that open defers for speed and memory — the on-demand equivalent of SQLite’s integrity_check.

A load (owned, overlay or read-only) validates only the metadata, so the large byte pools stay non-resident on an mmap’d base — an overlay open of a multi-gigabyte database faults in only what it must. This method sweeps the deferred pools and confirms the whole image is well-formed: every stored text is valid UTF-8, the vector pool is self-consistent, and facts flagged with a vector map one-to-one onto pool slots that name them back. It reads the text and vector pools in full, so it costs one linear pass over them (and residents them).

Skipping it is safe: the accessors that read these pools tolerate bad bytes on their own (invalid text hides the fact, vector reads are bounds-checked), so a corrupt image never panics — verify only turns that latent corruption into an explicit Error::Corrupt.

Errors

Error::Corrupt for the first inconsistency found.

pub fn faulty_facts(&self) -> Vec<(FactId, FactFault)>

Attributes Memory::verify’s content checks to individual facts — the salvage predicate for recover. Walks every live (non-tombstone) fact and returns those whose stored text is not valid UTF-8, that are flagged with a vector whose slot is out of range or does not name the fact back, or whose metadata blob does not decode to a well-formed key→value map. It reads the text, vector and metadata pools (like verify), so it residents them; the accessors it uses are panic-free on any bytes. Unlike verify, it does not fail on the first problem — it reports each faulty fact so the caller can forget it and rebuild a clean image from the survivors.

impl Memory<'_>

pub fn recall(&self, q: RecallQuery<'_>) -> Result<RecallResult, Error>

Runs a recall, allocating a fresh RecallScratch and RecallResult. Convenience over Memory::recall_into for one-shot callers; a hot loop should own a RecallScratch and call recall_into to stay zero-alloc.

pub fn recall_into( &self, q: RecallQuery<'_>, s: &mut RecallScratch, out: &mut RecallResult, ) -> Result<(), Error>

Runs a recall into a reused result and caller-owned scratch (the zero-alloc path: after warm-up neither s nor out allocate).

Takes &self — recall never mutates engine data; every mutable buffer it needs lives in s. This is what lets many readers recall one engine concurrently, each with its own RecallScratch.

impl<'a> Memory<'a>

pub fn new(cfg: Config) -> Result<Self, Error>

Creates an empty database.

Errors

Error::ConfigMismatch for an invalid config (see Config::validate).

pub fn open<S: Storage>( store: &mut S, cfg: Config, ) -> Result<(Self, OpenReport), Error>

Opens a database from a storage: journal replay over an empty state (the snapshot fast-path lands with the section composition; a non-empty snapshot is rejected rather than half-read).

pub fn from_bytes( snapshot: Option<&[u8]>, journal: &[u8], cfg: Config, ) -> Result<(Self, OpenReport), Error>

Opens from raw bytes (the wasm path: the host already read them).

pub fn from_bytes_borrowed( snapshot: &'a [u8], journal: &[u8], cfg: Config, ) -> Result<Self, Error>

Opens a database read-only over a borrowed snapshot: the engine’s byte pools borrow snapshot (typically an mmap’d file) instead of copying it, so a large database residents only the pages actually read. The returned engine is tied to snapshot’s lifetime.

A non-empty journal is rejected: the read-only handle exposes no write verbs, so a snapshot with un-checkpointed journal tail would open stale. Checkpoint the database read-write once first — or use Memory::from_bytes_overlay, which replays the journal into the overlay. The caller (the host) owns the map and the exclusive lock.

pub fn from_bytes_overlay( snapshot: &'a [u8], journal: &[u8], cfg: Config, ) -> Result<(Self, OpenReport), Error>

Opens a database read-write over a borrowed snapshot (the overlay write path): like Memory::from_bytes_borrowed the byte pools borrow snapshot instead of copying it, but the journal is replayed and the engine stays fully mutable. Mutations do not clone the borrowed base: the flat structures land appends in an owned tail and copy only the pages they rewrite (per-page copy-on-write), so a multi-gigabyte mapped database is opened and written to while resident only in the pages it actually touches.

This is the write sibling of Memory::from_bytes (which owns its bytes) — the same snapshot + journal replay, over a borrowed base, and it returns the same OpenReport describing the replay. The returned engine is tied to snapshot’s lifetime; the caller (the host) owns the map and the exclusive lock.

pub fn remember<S: Storage>( &mut self, store: &mut S, input: RememberInput<'_>, ) -> Result<RememberOutcome, Error>

Remembers a new fact.

pub fn remember_batch<S: Storage>( &mut self, store: &mut S, inputs: &[RememberInput<'_>], skip_similar: bool, ) -> Result<Vec<RememberOutcome>, Error>

Batch import: a sequence of remembers in one call, journaled individually. skip_similar turns off the similar-detection pass — imports don’t need hints, and skipping them makes a bulk load cheaper.

Stops at the first error; already-applied inputs stay applied and journaled (replay reproduces exactly the applied prefix).

pub fn revise<S: Storage>( &mut self, store: &mut S, target: FactId, input: RememberInput<'_>, ) -> Result<RememberOutcome, Error>

Revises target: closes its validity at the new fact’s valid_from and records the new fact with revises = target (rule 2).

pub fn forget<S: Storage>( &mut self, store: &mut S, now: u64, id: FactId, ) -> Result<bool, Error>

Tombstones a fact: it disappears from every query immediately, the bytes go with the next maintain (rule 3). Ok(false) when it was already tombstoned.

pub fn link<S: Storage>( &mut self, store: &mut S, input: LinkInput<'_>, ) -> Result<(), Error>

Upserts a typed edge between two entities (created lazily); re-linking an existing (src, rel, dst) updates its provenance.

pub fn get(&self, id: FactId) -> Option<FactView<'_>>

Returns a fact unless it is tombstoned (closed facts are returned — their interval says so).

pub fn tags_of(&self, id: FactId, out: &mut Vec<TermId>)

Appends the tag terms of a fact to out. A tombstoned or unknown fact contributes nothing.

pub fn metadata_of<'s>( &'s self, id: FactId, out: &mut Vec<(&'s str, &'s str)>, ) -> bool

Fills out with the fact’s metadata as key→value pairs in canonical (ascending-key) order — the same order the blob was written and the same order a host BTreeMap yields, so no layer sorts twice. Returns true when the fact carries metadata (even an empty map is false, since an empty map is stored as no blob).

A tombstoned or unknown fact, a fact with no metadata blob, or a blob that fails to decode (deferred validation, — verify reports it) all leave out empty and return false; this accessor never panics on bad bytes.

pub fn entity(&mut self, name: &str) -> Option<EntityId>

Resolves an entity by name (normalized), without creating it.

pub fn term(&self, id: TermId) -> &str

Resolves the string behind a term id (tags, relations).

pub fn entity_name(&self, id: EntityId) -> Option<&str>

The canonical (verbatim) name of an entity, or None for an unknown id. The read-side inverse of Memory::entity: it lets a host export a fact with its subject name instead of the internal EntityId carried by FactRecord.

pub fn facts_len(&self) -> usize

Number of fact records currently stored (tombstoned facts count until maintain removes them). Purged ids stay burned, so this can be below Stats::next_fact.

pub fn entities_len(&self) -> usize

Number of entities.

pub fn cfg(&self) -> &Config

The engine configuration.

pub fn stats(&self) -> Stats

Size counters of the engine. O(1).

Trait Implementations

impl Debug for Memory<'_>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Summary only — the contents are the user’s memory, not ours to print.