Struct Store 

pub struct Store {
    pub root: PathBuf,
    /* private fields */
}

Persistent knowledge store for a single mati project.

Wraps two SurrealKV trees:

• knowledge — user-visible records (gotchas, files, decisions, …)
• sessions — analytics, hook events, compliance logs

All public methods are async; callers must be in a tokio context.

Fields

root: PathBuf

Absolute path to ~/.mati/<slug>/

Implementations

impl Store

pub async fn open(repo_root: &Path) -> Result<Self>

Open (or create) both trees for the project rooted at repo_root.

Creates ~/.mati/<slug>/ if it does not exist.

If the search index is corrupt or schema-incompatible, it is wiped and replaced with a fresh empty index. Store::index_needs_rebuild will return true in that case — call Store::rebuild_search_index before issuing any search queries, or use Store::open_and_rebuild which handles this automatically.

pub async fn open_and_rebuild(repo_root: &Path) -> Result<Self>

Open the store and rebuild the search index from SurrealKV if needed.

This is the recommended entry point for the CLI and MCP server. It combines Store::open with an automatic Store::rebuild_search_index call when the index was corrupt or missing (C4). Search queries are safe to issue immediately on the returned store.

Unlike Store::open, this eagerly initializes tantivy so corruption can be detected and recovered from before any queries are issued.

pub fn index_needs_rebuild(&self) -> bool

True when the search index was corrupt or missing on open.

This flag reflects the state detected at open time and is not reset after Store::rebuild_search_index completes. Use it only to decide whether to call rebuild_search_index — not as a post-rebuild status. Store::open_and_rebuild handles this automatically.

pub async fn rebuild_search_index(&self) -> Result<usize>

Rebuild the tantivy search index from scratch by scanning all Record-containing namespaces in SurrealKV (C4).

Must be called on a store whose search index is empty — i.e. immediately after Store::open detected a corrupt/missing index, before any writes. Calling on a non-empty index will produce duplicate entries; use the deduplication in Search::query_keys to tolerate this if it occurs.

Returns the total number of records committed to the index.

pub async fn get(&self, key: &str) -> Result<Option<Record>>

Read a record by key. Returns None if not found.

pub async fn put(&self, key: &str, record: &Record) -> Result<()>

Write a record with the appropriate durability level.

Durability is derived from the key prefix via Durability::for_key.

pub async fn put_batch_kv_only(&self, records: &[(&str, &Record)]) -> Result<()>

Write multiple records to KV only, skipping the tantivy search index.

Use this during bulk init passes where search indexing would block the critical path. Follow with Self::rebuild_search_index to update tantivy from the same in-memory records without a KV round-trip.

Same durability semantics as Self::put_batch: at most 2 fsyncs.

pub fn mark_search_stale(&self)

Mark the search index as stale so the next Self::open_and_rebuild call wipes and rebuilds it from KV.

Written by mati init after a cold init pass to defer the tantivy indexing cost (~400ms on 27k records) to the first MCP server startup. Best-effort: a write failure is silently discarded — the worst outcome is that the search index contains stale data until the next full rebuild.

pub async fn put_batch(&self, records: &[(&str, &Record)]) -> Result<()>

Write multiple records in a single transaction per durability class.

Records are grouped by their key prefix: all Immediate keys share one transaction on knowledge (1 fsync), all Eventual keys share one on sessions (1 fsync). The whole batch costs at most 2 fsyncs regardless of how many records it contains — critical for Layer 0 bulk inserts.

Empty slice is a no-op. Mixed-durability batches are handled correctly.

pub async fn delete(&self, key: &str) -> Result<()>

Delete a record by key. No-op if the key does not exist.

pub async fn scan_prefix(&self, prefix: &str) -> Result<Vec<Record>>

Return all records whose key starts with prefix.

Prefix must use one of the known key namespaces so the correct tree is selected. Unknown prefixes are scanned from knowledge.

Return order is not guaranteed. Callers that need a stable order must sort.

pub async fn scan_prefix_each<F>(&self, prefix: &str, callback: F) -> Result<()>

where F: FnMut(Record),

Scan records whose key starts with prefix, invoking callback for each.

Same tree routing and prefix semantics as Self::scan_prefix, but records are deserialized and passed to callback one at a time rather than collected into a Vec. Callers can begin processing (e.g. printing to stdout) before the full scan completes, giving time-to-first-row latency proportional to a single deserialization rather than the full scan.

Return order is lexicographic (underlying KV order). Callers that need a different order must collect and sort after the fact.

pub async fn search(&self, text: &str, limit: usize) -> Result<Vec<Record>>

Full-text BM25 search over all indexed records.

Calls tantivy for the top limit matching keys, then fetches each full record from SurrealKV. Keys that tantivy returns but are not found in the store (e.g. deleted since last commit) are silently skipped.

Returns results ordered by descending BM25 relevance score. Returns an empty Vec when text is blank or limit is 0.

pub async fn search_scored( &self, text: &str, limit: usize, ) -> Result<Vec<(f32, Record)>>

Full-text BM25 search returning (score, Record) pairs.

Same semantics as Self::search but preserves the raw BM25 relevance score from tantivy. Used by mem_query text mode to include relevance in the agent-facing response.

pub async fn get_raw_bytes(&self, key: &str) -> Result<Option<Vec<u8>>>

Read raw bytes by key. Returns None if the key does not exist.

Counterpart to Self::put_raw. Used for structural metadata, enforcement events, and other non-Record values stored as raw bytes.

pub async fn put_raw(&self, key: &str, value: &[u8]) -> Result<()>

Write raw bytes under key with automatically routed durability.

Same durability routing as Self::put — callers do not need to know which tree a key belongs to. Use this for structural metadata (graph edges, etc.) where the value is not a Record and does not need to be deserialised on reads.

pub async fn put_batch_raw(&self, records: &[(&str, &[u8])]) -> Result<()>

Write multiple raw-byte values in a single transaction per durability class.

Same batch semantics as Self::put_batch (at most 2 fsyncs for the whole batch). Use for bulk structural writes like graph edge inserts.

pub async fn transact_knowledge( &self, ops: &[KnowledgeWriteOp<'_>], ) -> Result<()>

Atomically commit multiple writes to the knowledge tree in a single transaction.

Supports mixed Record + raw byte writes. All keys MUST route to the knowledge tree (Durability::Immediate). Returns an error if any key routes to sessions.

Handles crash-fence + tantivy sync + write-seq after commit. Use this for mutation + audit atomic commit on knowledge-side commands.

pub async fn transact_sessions_raw( &self, entries: &[(&str, &[u8])], ) -> Result<()>

Atomically commit multiple raw byte writes to the sessions tree in a single transaction.

All keys MUST route to the sessions tree (Durability::Eventual). Returns an error if any key routes to knowledge.

Use this for mutation + audit atomic commit on session-side commands.

pub async fn scan_keys(&self, prefix: &str) -> Result<Vec<String>>

Return all keys whose prefix matches, without deserialising values.

Cheaper than Self::scan_prefix when only the key is needed (e.g. graph edge loading, existence checks). Uses the SurrealKV iterator key().user_key() path so value bytes are never read from disk.

pub fn history(&self, key: &str, limit: usize) -> Result<Vec<HistoryEntry>>

Return version history for a single key, newest first.

Includes tombstones (deletions). Uses the tight upper bound key + \0 so adjacent keys never spill into the result set.

limit caps the number of entries returned; 0 means unlimited.

pub fn history_since( &self, key: &str, since_ts: u64, limit: usize, ) -> Result<Vec<HistoryEntry>>

Return version history for a single key since since_ts (seconds), newest first.

Timestamps are converted to nanoseconds for the SurrealKV range filter.

pub async fn records_since( &self, since_ts: u64, limit: usize, ) -> Result<Vec<Record>>

Return all records updated since since_ts (seconds), newest first.

Scans every knowledge namespace (including dep:) and returns records whose updated_at >= since_ts. Results are sorted by updated_at descending with secondary sort by key for deterministic ordering.

pub async fn close(self) -> Result<()>

Flush and close both trees, releasing the LOCK files.

Must be called before dropping Store if another process (or test) will reopen the same database directory. SurrealKV holds an exclusive lock for the lifetime of a Tree; reopening without closing first fails with “already locked by another process”.

pub async fn flush_for_shutdown(&self)

Best-effort durability flush for shutdown paths.

Calls SurrealKV’s flush_wal(sync=true) on both trees so every previously-committed transaction reaches disk. Non-consuming and &self — works through a shared Arc<RwLock<Graph>> read lock on the daemon shutdown path where ownership cannot be reclaimed.

Necessary because SurrealKV’s Tree::Drop only fire-and-forget-spawns core.close() onto the current tokio runtime; if the runtime is shutting down (signal handler, main return) that spawned task may not run before the process exits, losing buffered “Eventual” writes.

Errors are logged via tracing::warn! and not propagated — shutdown paths must be infallible. Search index pending writes are committed per Search::add_record/add_records call, so no separate flush is needed here.

pub async fn ping(&self) -> Result<u64>

Ping the store. Writes a sentinel key and reads it back; returns round-trip latency in microseconds.

Used by mati ping and by hook fast-path availability checks.

pub fn read_write_seq(&self) -> u64

Read the current knowledge write-sequence counter.

Returns 0 if the file does not exist or cannot be parsed — callers treat 0 as “no valid cached snapshot” and recompute.

pub fn sessions_tree(&self) -> &Tree

Direct access to the sessions tree for audit reads in tests.

Production code should use the key-routing methods (get, put_raw, scan_keys) rather than accessing trees directly.

Trait Implementations

impl RepairReader for Store

async fn get(&self, key: &str) -> Result<Option<Record>>

async fn scan_prefix(&self, prefix: &str) -> Result<Vec<Record>>

async fn scan_keys(&self, prefix: &str) -> Result<Vec<String>>