Skip to main content

mnemo_engine/store/
mod.rs

1//! The Mnemo database — ties the storage engine and the memory model together.
2//!
3//! Layout of a populated file:
4//!
5//! ```text
6//!   page 0           : Header (unencrypted)
7//!   pages 1..W       : write-ahead log region
8//!   pages W..        : encrypted record runs + catalog runs + index +
9//!                      snapshot manifest (append-only)
10//! ```
11//!
12//! Durability is provided by a **write-ahead log** ([`crate::wal`]). A `flush`
13//! is one transaction: record data pages are written copy-on-write to fresh
14//! pages, then the new catalog, ANN index, and header are logged to the WAL
15//! and committed with a single fsync. A checkpoint then folds the WAL into the
16//! home pages. A crash before the commit leaves the previous state intact; a
17//! crash after it is repaired by replaying the WAL on open.
18//!
19//! Because pages are only ever appended, every past transaction's runs survive
20//! on disk. Each flush also appends an entry to a **snapshot manifest**, so
21//! [`Mnemo::restore_to`] can reinstate any past state. Stale pages — and the
22//! history along with them — are reclaimed by [`Mnemo::compact_file`].
23
24use std::fs::{File, OpenOptions};
25use std::io::{Read, Seek, SeekFrom, Write};
26use std::path::{Path, PathBuf};
27
28use fs4::fs_std::FileExt;
29use serde::{Deserialize, Serialize};
30use serde_json::{Map, Value};
31use ulid::Ulid;
32
33use crate::crypto::{self, KdfParams};
34use crate::embed::{self, Embedder};
35use crate::error::{MnemoError, Result};
36use crate::format::{
37    Header, RunPtr, FLAG_ENCRYPTED, PAGE_SIZE, PAYLOAD, VERSION, VERSION_V9, WRAPPED_DEK_LEN,
38};
39use crate::freelist::FreeList;
40use crate::index::{IndexConfig, IndexInfo, IndexOp, IvfPqIndex};
41use crate::keyslot::{KeySlot as KeySlotEntry, KeySlotRun};
42use crate::memory::{
43    self, status as essence_status, CommitBatch, CommitReport, EssenceOp, EssenceOpKind,
44    EssenceScope, EssenceSection, ExportedTurn, Filter, FilterTerm, IngestReport, KeyScope, Memory,
45    MemoryPatch, MemoryType, Metric, Scope, ScoreWeights, ThreadTurn, TurnPolicy, WriteOutcome,
46    CONTINUATION_TIMELINE_ENTRIES, ESSENCE_DEFAULT_RENDER_BYTES, ESSENCE_TRANSITIONS,
47    MNEMO_META_CONTINUES, MNEMO_META_INVALID_AT, MNEMO_META_KEY, MNEMO_META_KIND,
48    MNEMO_META_KIND_ESSENCE, MNEMO_META_KIND_THREAD_LINK, MNEMO_META_KIND_TURN, MNEMO_META_LENGTH,
49    MNEMO_META_PART, MNEMO_META_REFS, MNEMO_META_ROLE, MNEMO_META_SECTION, MNEMO_META_SEQ,
50    MNEMO_META_SHA256, MNEMO_META_STATUS, MNEMO_META_STATUS_HISTORY, MNEMO_META_SUPERSEDED_BY,
51    MNEMO_META_SUPERSEDES, MNEMO_META_THREAD, MNEMO_META_TURN_ID, MNEMO_META_UPDATED_AT,
52    THREAD_TOOL_RESULT_TRUNCATE_BYTES, THREAD_TURN_CHUNK_BYTES,
53};
54use crate::pager::{LockedFile, Pager};
55use crate::result_cache::{
56    self, BatchState, CacheBudget, CacheDirectoryEntry, CacheEntry, CacheFlushPolicy, CachePutOpts,
57    CacheStats, CachedValue, CounterState, DirectoryIndex, SemanticCachePutOpts,
58};
59use crate::text;
60use crate::veccol;
61use crate::wal;
62
63mod ann;
64mod cache_api;
65mod continuation;
66mod crud;
67mod essence;
68mod flush;
69#[cfg(test)]
70mod header_graft_tests;
71mod hooks;
72mod keyed;
73mod load;
74mod maintenance;
75mod open;
76mod recall;
77mod records;
78mod snapshots;
79mod threads;
80use crud::*;
81use essence::*;
82use load::*;
83pub(crate) use records::plain_record;
84use records::*;
85
86/// Default initial size of the write-ahead log region, in pages (64 KiB).
87/// The region grows automatically when a transaction's control plane outgrows
88/// it, so this is a *floor* on the fresh-file footprint, not a cap on
89/// transaction size. Was 64 pages (512 KiB) in v0.1.0 — lowered because that
90/// reservation dominated small-file size (~62% of a 31-memory dogfood file).
91const DEFAULT_WAL_PAGES: u64 = 8;
92
93/// Hard floor on the WAL reservation. A single header-page flush already
94/// needs one full DATA frame plus a COMMIT frame; two pages are the bare
95/// minimum that lets the first transaction commit without immediate growth.
96const MIN_WAL_PAGES: u64 = 2;
97
98/// Default cap on retained snapshot manifest entries. Each `flush` appends
99/// one entry; without a cap, long-running processes accumulate entries
100/// forever, growing per-flush manifest-serialize cost as O(total flushes)
101/// and the manifest run size on disk in lockstep. 256 keeps roughly a
102/// week of hourly snapshots while staying tiny (256 × ~82 bytes ≈ 21 KiB
103/// of manifest). Set `MnemoConfig::max_snapshots = 0` to disable the cap.
104pub const DEFAULT_MAX_SNAPSHOTS: usize = 256;
105
106/// PERF-1: the ANN index is derived data, so `flush` persists it only every
107/// this many commits that changed it (or see
108/// [`INDEX_PERSIST_EVERY_CHANGES`], [`Mnemo::flush_index`], [`Mnemo::close`]).
109/// Between persists, only the catalog is rewritten.
110pub const INDEX_PERSIST_EVERY_COMMITS: u32 = 64;
111
112/// PERF-1: …or once this many vectors were added, changed or removed since
113/// the last persist. Records written after the persisted index are
114/// re-assigned when the index is next loaded, so this bounds that work.
115pub const INDEX_PERSIST_EVERY_CHANGES: usize = 1_000;
116
117/// FMT-9d: default weight ε of the normalised BM25 score in hybrid recall
118/// (`relevance = similarity + ε · bm25 / max bm25`).
119pub const DEFAULT_KEYWORD_WEIGHT: f32 = 0.5;
120
121/// FMT-9b: default [`Mnemo::set_vector_cache_budget`]: the fp16 vector
122/// column stays resident while it fits (100K × 384 dims is about 77 MB) and
123/// is read through the page cache above it. PLANNER-A, 2026-11-07.
124pub const DEFAULT_VECTOR_CACHE_BUDGET: usize = 96 * 1024 * 1024;
125
126/// FMT-9b: below this many facts a v9 file has no ANN index: an exact
127/// fp16 scan of 20K × 384 dims is about a millisecond, and the IVF+PQ
128/// codebook alone would cost more disk than it saves time.
129pub const V9_ANN_MIN_FACTS: usize = 20_000;
130
131/// FMT-9f (PLANNER-A, 2026-11-08): on v9 an unpinned recall reranks at
132/// least this many candidates per requested hit (500 for `top_k` 10), or
133/// the index's own auto depth when that's deeper (above 100K). The v9
134/// index is trained on fp16-rounded vectors, and at 20K–50K the auto
135/// depth (×10–×25) lost up to 0.03 recall@10 against v8; ×50 is within
136/// 0.005 at every measured tier. v8 is unchanged.
137pub const V9_RERANK_PER_HIT: usize = 50;
138
139/// FMT-9c: page runs longer than this are written copy-on-write straight
140/// to their home pages (and fsynced) before the commit, instead of through
141/// the WAL, on v9. The WAL then carries only the header and small runs, so
142/// it stays at its 64 KiB default instead of growing to the largest
143/// catalog or index (26 MB at 100K on v8). Safe for the same reason data
144/// pages are: the pages come from the tail or from quarantined free runs,
145/// so nothing committed references them until the header flips.
146const V9_WAL_RUN_MAX_PAGES: u64 = 2;
147
148/// FMT-9c: snapshot retention on v9: the newest 16 snapshots, plus any
149/// from the last 24 hours, with retained snapshots never pinning more than
150/// a quarter of the file (past that, the oldest go first, whatever their
151/// age). `set_max_snapshots` changes the count.
152pub const V9_DEFAULT_MAX_SNAPSHOTS: usize = 16;
153const V9_SNAPSHOT_KEEP_SECS: i64 = 24 * 3600;
154/// FMT-9c: the pin cap never drops below 128 pages (1 MiB).
155const V9_PIN_FLOOR_PAGES: u64 = 128;
156
157/// FMT-9d: the layout byte at the start of a v9 ANN index run (1: the
158/// whole IVF+PQ index, followed by delta runs). A reader treats an unknown
159/// layout as no index, so a later layout (partition-major, PERF-2) ships
160/// without a format bump.
161const V9_INDEX_LAYOUT: u8 = 1;
162
163/// FMT-9b: how many sparse vector pages one commit folds into its new
164/// pages (the vacuum). Bounded so a commit's cost stays bounded.
165const VACUUM_PAGES_PER_COMMIT: usize = 4;
166
167/// FMT-9c.2: and at most this many rows moved by the vacuum per commit (a
168/// moved row is a changed catalog row, so it lands in the commit's delta).
169/// Pages with more live rows than this stay as they are until deletes thin
170/// them out.
171const VACUUM_MAX_ROWS: usize = 64;
172
173/// FMT-9b: header flag: the file also keeps each record's float vector
174/// (`MnemoConfig::store_float_vectors`).
175const FLAG_FLOAT_VECTORS: u32 = 2;
176
177/// PERF-1: when the in-memory ANN index was last persisted, and whether the
178/// next flush must persist it.
179#[derive(Debug, Default, Clone, Copy)]
180struct IndexPersist {
181    /// Persist on the next flush (build, rebuild, drop, `flush_index`,
182    /// `close`, snapshot restore).
183    forced: bool,
184    /// Commits since the last persist that left the index dirty.
185    commits: u32,
186    /// Vectors added, re-assigned or removed since the last persist.
187    changes: usize,
188}
189
190/// Configuration for creating a new database.
191#[derive(Clone, Copy, Debug)]
192pub struct MnemoConfig {
193    /// Embedding dimensionality. Every stored vector must match this.
194    pub dimensions: usize,
195    /// Key-derivation parameters.
196    pub kdf: KdfParams,
197    /// Initial size of the WAL region in 8 KiB pages. Default is
198    /// [`DEFAULT_WAL_PAGES`] (8 pages = 64 KiB), which keeps fresh files
199    /// small; the region auto-grows when a transaction's control plane needs
200    /// more space, so raising this is only a hint for the expected steady-state
201    /// transaction size. Write-heavy databases that routinely flush large
202    /// catalogs or ANN indexes can set this higher (e.g. 64 = 512 KiB) to
203    /// avoid early grow events; tiny embedded uses can leave it at the
204    /// default. Clamped to a minimum of [`MIN_WAL_PAGES`] (2 pages).
205    pub wal_pages_initial: u64,
206    /// Maximum number of snapshot manifest entries to retain. Each `flush`
207    /// appends one entry; once the cap is hit, the *oldest* entry is dropped
208    /// from the in-memory manifest before the new one is added, so the
209    /// retained set is always the most-recent N. Defaults to
210    /// [`DEFAULT_MAX_SNAPSHOTS`] (256). Set to `0` to disable the cap and
211    /// retain every snapshot forever (the pre-v0.3 behavior).
212    ///
213    /// Pages referenced *only* by pruned snapshots stay on disk until the
214    /// next [`Mnemo::compact_file`], which reclaims them. Point-in-time
215    /// recovery via [`Mnemo::restore_to`] into a pruned `txn_id` returns
216    /// [`MnemoError::NotFound`].
217    ///
218    /// Apply to an already-open database with [`Mnemo::set_max_snapshots`].
219    pub max_snapshots: usize,
220    /// The on-disk format a new file is created in. `0` (the default)
221    /// means v9, the current format. `8` creates a v8 file, for tools that
222    /// still need to read it with v0.10 or earlier; it's kept for one
223    /// release (v0.12 makes v8 read-only). **Not a stable API.**
224    #[doc(hidden)]
225    pub format_version: u16,
226    /// FMT-9b (v9 files only; ignored for v8): also keep each memory's
227    /// full-precision vector in its record, so `get()` and `recall()`
228    /// return it exactly. Off by default: a v9 file stores vectors as
229    /// fp16 (about 1e-3 relative error) in the vector column, which recall
230    /// scores from either way. Costs `4 × dimensions` bytes per memory.
231    pub store_float_vectors: bool,
232}
233
234impl Default for MnemoConfig {
235    fn default() -> Self {
236        Self {
237            dimensions: 768,
238            kdf: KdfParams::secure(),
239            wal_pages_initial: DEFAULT_WAL_PAGES,
240            max_snapshots: DEFAULT_MAX_SNAPSHOTS,
241            format_version: 0,
242            store_float_vectors: false,
243        }
244    }
245}
246
247/// FMT-9: resolve [`MnemoConfig::format_version`] for a new file.
248fn resolve_format_version(requested: u16) -> Result<u16> {
249    match requested {
250        // FMT-9f: new files are v9; the `MNEMO_DEV_FORMAT` switch is gone.
251        0 => Ok(crate::format::DEFAULT_NEW_VERSION),
252        VERSION | VERSION_V9 => Ok(requested),
253        v => Err(MnemoError::Invalid(format!(
254            "format_version {v} is not supported for new files (use 8 or 9)"
255        ))),
256    }
257}
258
259/// Catalog entry: maps a memory ID to its page run on disk.
260///
261/// **Schema (v5+):** carries `accessed_at` and `access_count` so `recall`
262/// can update access stats by mutating the catalog entry rather than
263/// rewriting the entire record (Phase 2.1 of the improvement plan). The
264/// values in a memory's serialized record body become a stale snapshot
265/// after the first recall; [`Mnemo::read_memory`] re-populates them from
266/// the catalog so consumers always see the live values.
267#[derive(Serialize, Deserialize, Clone, Debug)]
268struct CatalogEntry {
269    /// ULID as a raw `u128`.
270    id: u128,
271    start_page: u64,
272    page_count: u32,
273    /// Exact serialized byte length of the record.
274    len: u32,
275    deleted: bool,
276    /// Unix seconds of the most recent recall hit (or write, for fresh entries).
277    accessed_at: i64,
278    /// How many times `recall` has surfaced this memory.
279    access_count: u32,
280    /// FMT-9: the generation the record's pages were sealed under (v9 page
281    /// AAD). `0`, and left out of the encoding, on v8 files, so a v8
282    /// catalog is byte-for-byte what v0.10 writes.
283    #[serde(default, skip_serializing_if = "crate::format::is_zero_u64")]
284    gen: u64,
285    /// FMT-9b: the v9 row's tags, scoring inputs and vector location
286    /// (`None`, and left out of the encoding, on v8 files).
287    #[serde(default, skip_serializing_if = "Option::is_none")]
288    v9: Option<RowV9>,
289}
290
291/// FMT-9b: what a v9 catalog row carries beyond the v8 fields, so recall
292/// can filter and score a candidate without decrypting its record, and a
293/// cold handle can select records by kind or thread.
294#[derive(Serialize, Deserialize, Clone, Copy, Debug, Default)]
295struct RowV9 {
296    /// The vector column entry: page (`0` while it's waiting for the next
297    /// flush), slot, and the page's generation.
298    vec_page: u64,
299    vec_slot: u16,
300    vec_gen: u64,
301    /// FMT-9b.2: the record's slot on its packed page (`start_page`), or
302    /// [`REC_SPAN`] when the record owns a run of whole pages.
303    rec_slot: u16,
304    /// `ROW_KIND_*`.
305    kind: u8,
306    /// `ROW_SUPERSEDED | ROW_HAS_TTL | ROW_SHARED`.
307    flags: u8,
308    /// [`memory_type_code`].
309    memory_type: u8,
310    /// FNV-1a of `_mnemo.thread`, of the 12.1 key slot, and of `agent_id`
311    /// (`0` = none). A collision only lets a non-match through to the
312    /// decrypted check.
313    thread_hash: u32,
314    key_hash: u32,
315    agent_hash: u32,
316    created_at: i64,
317    importance: f32,
318    /// `created_at + ttl_secs` when `ROW_HAS_TTL` is set.
319    expires_at: i64,
320    /// FMT-9d: the row's BM25 document id (`0`: not keyword-indexed) and
321    /// its token count. Live rows define which documents are live, and
322    /// N and avgdl, so segments never hold lengths or tombstones.
323    doc: u32,
324    doc_len: u16,
325}
326
327/// FMT-9e: by default a thread turn is written plain and compressed once
328/// it's a week old (by its `created_at`), so a live session's recent turns
329/// read at full speed and archived history is small.
330pub const DEFAULT_TURN_COMPRESS_AFTER_SECS: i64 = 7 * 24 * 3600;
331/// Frozen v4 catalog entry shape, used only by the v4→v5 migration path in
332/// [`Mnemo::open`]. Its layout matches the catalog encoding written by
333/// pre-v5 builds (5 positional fields). Do not change this struct.
334#[derive(Serialize, Deserialize, Clone, Debug)]
335struct CatalogEntryV4 {
336    id: u128,
337    start_page: u64,
338    page_count: u32,
339    len: u32,
340    deleted: bool,
341}
342
343/// Returned by [`Mnemo::prepare_for_flush`] and consumed by [`Mnemo::flush`].
344/// Carries the already-serialized control-plane bytes through the prelude
345/// so we don't re-serialize after the lease has been persisted.
346struct FlushPrelude {
347    cat_bytes: Option<Vec<u8>>,
348    /// FMT-9c.2: `cat_bytes` is a delta run, not a base catalog.
349    cat_delta: bool,
350    /// FMT-9c.3: `idx_bytes` is an index delta run, not a whole index.
351    idx_delta: bool,
352    /// FMT-9d: this commit's BM25 segment, and the segments it replaces.
353    bm25_seg: Option<(Vec<u8>, Option<usize>)>,
354    idx_bytes: Option<Vec<u8>>,
355    /// Serialized result-cache directory bytes when `dirty_cache` is
356    /// set (Phase 10.1). `None` if the cache didn't change since the
357    /// last flush — in that case the header keeps its current
358    /// `cache_start` / `cache_pages` / `cache_len` and no fresh cache
359    /// run is written.
360    cache_bytes: Option<Vec<u8>>,
361}
362
363/// One entry in the append-only snapshot manifest. Because record, catalog,
364/// and index pages are only ever *appended*, the runs a past flush wrote are
365/// still on disk; a `Snapshot` is the set of pointers needed to reconstruct
366/// the database exactly as that flush left it.
367#[derive(Serialize, Deserialize, Clone, Debug)]
368struct Snapshot {
369    txn_id: u64,
370    created_at: i64,
371    catalog_start: u64,
372    catalog_pages: u64,
373    catalog_len: u64,
374    index_start: u64,
375    index_pages: u64,
376    index_len: u64,
377    memory_count: u64,
378    /// FMT-9: generations of the catalog and index runs (v9 only; `None`,
379    /// and left out of the encoding, on v8 files).
380    #[serde(default, skip_serializing_if = "Option::is_none")]
381    gens: Option<SnapshotGens>,
382}
383
384/// FMT-9: the generations a v9 snapshot's runs were sealed under.
385#[derive(Serialize, Deserialize, Clone, Copy, Debug, Default)]
386struct SnapshotGens {
387    catalog: u64,
388    index: u64,
389    /// FMT-9c.2: the catalog's delta-chain head at this snapshot.
390    #[serde(default)]
391    delta: (u64, u64, u64, u64),
392    /// FMT-9c.3: the index's delta-chain head at this snapshot.
393    #[serde(default)]
394    index_delta: (u64, u64, u64, u64),
395    /// FMT-9d: the BM25 manifest at this snapshot.
396    #[serde(default)]
397    bm25: (u64, u64, u64, u64),
398}
399
400impl Snapshot {
401    fn catalog_gen(&self) -> u64 {
402        self.gens.map_or(0, |g| g.catalog)
403    }
404    fn index_gen(&self) -> u64 {
405        self.gens.map_or(0, |g| g.index)
406    }
407    fn delta_head(&self) -> RunPtr {
408        self.gens.map_or(RunPtr::default(), |g| tuple_ptr(g.delta))
409    }
410    fn index_delta_head(&self) -> RunPtr {
411        self.gens
412            .map_or(RunPtr::default(), |g| tuple_ptr(g.index_delta))
413    }
414}
415
416/// A restorable point in a database's history — see [`Mnemo::snapshots`].
417#[derive(Clone, Copy, Debug)]
418pub struct SnapshotInfo {
419    /// Id of the transaction that produced this snapshot (monotonic from 1).
420    pub txn_id: u64,
421    /// When the snapshot was committed (unix seconds).
422    pub created_at: i64,
423    /// Live memory count captured in the snapshot.
424    pub memory_count: u64,
425}
426
427/// A retrieval request for [`Mnemo::recall`].
428#[derive(Clone, Debug)]
429pub struct RecallRequest {
430    /// Query embedding.
431    pub query: Vec<f32>,
432    /// Maximum results to return.
433    pub top_k: usize,
434    /// Restrict to these memory types (`None` = all types).
435    pub memory_types: Option<Vec<MemoryType>>,
436    /// Restrict to a single agent's view: its own memories plus shared ones.
437    pub agent_id: Option<String>,
438    /// Similarity metric.
439    pub metric: Metric,
440    /// Multi-signal score weights.
441    pub weights: ScoreWeights,
442    /// Index override: partitions to probe (`None` = index default). Ignored
443    /// when no ANN index is present.
444    pub n_probe: Option<usize>,
445    /// Index override: candidates to rerank (`None` = index default). Ignored
446    /// when no ANN index is present.
447    pub n_rerank: Option<usize>,
448    /// Whether to update each result's `accessed_at` and `access_count` in
449    /// the catalog. Defaults to `true`, matching pre-v5 behavior.
450    ///
451    /// Set to `false` for **fully read-only recall** — useful for batch
452    /// scoring, dry-run scoring, or recalls run by introspection tooling
453    /// (e.g. `mnemo about` consumers) where you don't want the score's own
454    /// observation to perturb the database. With `false`, recall does not
455    /// dirty the catalog and the next `flush` is a no-op.
456    pub track_access: bool,
457    /// Phase 12.6 pre-scoring filter: `session_id` + AND-ed metadata
458    /// conditions applied before the candidate is scored. Default is
459    /// [`Filter::default`] (no constraints). When the ANN index is on
460    /// and this filter is selective enough to starve the shortlist
461    /// below `top_k`, Phase 12.1's widen-then-exact-scan logic kicks
462    /// in so the result still carries up to `top_k` correct hits.
463    pub filter: Filter,
464    /// Phase 12.8 post-scoring budget: stop adding hits once the UTF-8
465    /// bytes of their `content` fields (not the serialized record
466    /// body) would exceed this many bytes. `None` (default) means no
467    /// budget and every hit through `top_k` is returned. If the top-1
468    /// hit is already over budget it is still returned — callers that
469    /// need an absolute cap should also pre-size `top_k`.
470    ///
471    /// Counts only the UTF-8 `content` bytes so the number is stable
472    /// across the Rust / Python / CLI / MCP surfaces; the JSON or
473    /// MessagePack envelope is excluded. Roughly 4 bytes per BPE
474    /// token for English text — a 4 KB budget comfortably holds ~1K
475    /// tokens.
476    ///
477    /// Observable through [`RecallResponse::truncated`]
478    /// ([`Mnemo::recall_budgeted`]): `true` iff at least one scored
479    /// hit was dropped by this budget, `false` otherwise.
480    pub max_bytes: Option<usize>,
481    /// FMT-9d (Phase 2, v9 files): **identifiers or exact terms to match**
482    /// (a version, a PR number, a function name) for hybrid recall. Don't
483    /// paste the question: the vector covers its meaning, and its common
484    /// words would match the wrong records. BM25 scores, divided by this
485    /// query's best, are added to each candidate's similarity with weight
486    /// [`RecallRequest::keyword_weight`] before the usual scoring. With an
487    /// empty `query` vector ([`RecallRequest::keywords_only`]), recall is
488    /// keyword-only. `None` (the default) is plain vector recall.
489    pub keywords: Option<String>,
490    /// FMT-9d: weight ε of the normalised BM25 score in hybrid recall
491    /// (default [`DEFAULT_KEYWORD_WEIGHT`]).
492    pub keyword_weight: f32,
493    /// FMT-9d: BM25 term-frequency saturation `k1` (default 1.2).
494    pub bm25_k1: f32,
495    /// FMT-9d: BM25 length normalisation `b` (default 0.75).
496    pub bm25_b: f32,
497}
498
499impl RecallRequest {
500    /// A request with sensible defaults for a query embedding.
501    pub fn new(query: Vec<f32>) -> Self {
502        Self {
503            query,
504            top_k: 10,
505            memory_types: None,
506            agent_id: None,
507            metric: Metric::Cosine,
508            weights: ScoreWeights::default(),
509            n_probe: None,
510            n_rerank: None,
511            track_access: true,
512            filter: Filter::default(),
513            max_bytes: None,
514            keywords: None,
515            keyword_weight: DEFAULT_KEYWORD_WEIGHT,
516            bm25_k1: 1.2,
517            bm25_b: 0.75,
518        }
519    }
520
521    /// FMT-9d (v9 files): a keyword-only request: BM25 over `keywords`
522    /// (identifiers or exact terms), no query vector, so it works without
523    /// an embedder.
524    pub fn keywords_only(keywords: impl Into<String>) -> Self {
525        Self::new(Vec::new()).keywords(keywords)
526    }
527
528    /// FMT-9d (v9 files): add identifiers or exact terms to match (hybrid
529    /// recall). Pass identifiers, not the question. See the `keywords`
530    /// field.
531    pub fn keywords(mut self, text: impl Into<String>) -> Self {
532        self.keywords = Some(text.into());
533        self
534    }
535
536    /// FMT-9d: the weight ε of the keyword score in hybrid recall.
537    pub fn keyword_weight(mut self, w: f32) -> Self {
538        self.keyword_weight = w;
539        self
540    }
541
542    /// Phase 12.6: attach a pre-scoring filter. See [`Filter`] and
543    /// [`FilterTerm`] for term shapes.
544    pub fn filter(mut self, filter: Filter) -> Self {
545        self.filter = filter;
546        self
547    }
548
549    /// Phase 12.8: cap the total UTF-8 bytes of returned `content`
550    /// fields. See [`RecallRequest::max_bytes`].
551    pub fn max_bytes(mut self, n: usize) -> Self {
552        self.max_bytes = Some(n);
553        self
554    }
555
556    /// Build a request by embedding `query_text` with the supplied
557    /// embedder (Phase 3). Shorthand for `embedder.embed(&[text])` +
558    /// [`RecallRequest::new`]; same defaults as `new`. Fails if the
559    /// embedder returns an empty vector list or an embedding failure.
560    pub fn from_text(embedder: &dyn Embedder, query_text: &str) -> Result<Self> {
561        let mut vectors = embedder.embed(&[query_text])?;
562        let v = vectors.pop().ok_or_else(|| {
563            MnemoError::Invalid("embedder returned no vector for the query text".into())
564        })?;
565        Ok(Self::new(v))
566    }
567    /// Set the result cap.
568    pub fn top_k(mut self, k: usize) -> Self {
569        self.top_k = k;
570        self
571    }
572    /// Restrict to specific memory types.
573    pub fn types(mut self, t: Vec<MemoryType>) -> Self {
574        self.memory_types = Some(t);
575        self
576    }
577    /// Restrict to one agent's view.
578    pub fn agent(mut self, agent_id: impl Into<String>) -> Self {
579        self.agent_id = Some(agent_id.into());
580        self
581    }
582    /// Set the similarity metric (default: cosine).
583    pub fn metric(mut self, metric: Metric) -> Self {
584        self.metric = metric;
585        self
586    }
587    /// Replace the multi-signal score weights.
588    pub fn weights(mut self, weights: ScoreWeights) -> Self {
589        self.weights = weights;
590        self
591    }
592    /// Override the number of IVF partitions probed (accuracy/speed dial).
593    pub fn n_probe(mut self, n: usize) -> Self {
594        self.n_probe = Some(n);
595        self
596    }
597    /// Override the number of candidates reranked exactly (accuracy dial).
598    pub fn n_rerank(mut self, n: usize) -> Self {
599        self.n_rerank = Some(n);
600        self
601    }
602    /// Toggle whether recall updates `accessed_at` / `access_count` on
603    /// the returned memories' catalog entries (default `true`). Pass
604    /// `false` for a fully read-only recall — see the field doc.
605    pub fn track_access(mut self, track: bool) -> Self {
606        self.track_access = track;
607        self
608    }
609}
610
611/// One scored result from [`Mnemo::recall`].
612#[derive(Clone, Debug)]
613pub struct RecallResult {
614    /// The retrieved memory.
615    pub memory: Memory,
616    /// Combined multi-signal score.
617    pub score: f32,
618    /// The bare similarity component (before other signals).
619    pub similarity: f32,
620}
621
622/// Phase 12.8 budgeted-recall envelope returned by
623/// [`Mnemo::recall_budgeted`]. Wraps the `Vec<RecallResult>` the
624/// legacy [`Mnemo::recall`] returns so callers can tell whether
625/// [`RecallRequest::max_bytes`] cut anything.
626#[derive(Clone, Debug)]
627pub struct RecallResponse {
628    /// Scored hits, best first, truncated to at most `top_k` and then
629    /// to fit the `max_bytes` budget if set.
630    pub hits: Vec<RecallResult>,
631    /// `true` iff the `max_bytes` budget dropped at least one hit
632    /// that would otherwise have been returned (i.e. the result is
633    /// shorter than what `top_k` alone would produce).
634    pub truncated: bool,
635    /// Phase 12.1 + 12.6 observability: `true` iff recall fell
636    /// through to an exact scan (ANN shortlist too narrow after
637    /// filtering, and the widen pass also came up short, so the
638    /// index was skipped for one full-corpus pass). Monitoring on
639    /// this flag is how callers detect selective-filter regressions
640    /// or supersession chains outgrowing the ANN shortlist.
641    pub used_exact_scan: bool,
642}
643
644/// Where a file's bytes and an open handle's heap go (P-0 device budget,
645/// `examples/device_budget.rs`). **Unstable diagnostic**: fields may
646/// change in any release. File figures come from the header and the
647/// catalog. RAM figures are buffer capacities, with hash maps estimated
648/// from their capacity; they cover the engine's main structures, not
649/// every allocation, and not allocator overhead.
650#[doc(hidden)]
651#[derive(Clone, Debug, Default, serde::Serialize)]
652pub struct BudgetReport {
653    pub file_bytes: u64,
654    pub page_size: u64,
655    /// Page 0.
656    pub header_bytes: u64,
657    /// Whole pages holding live records (superseded versions included).
658    pub record_page_bytes: u64,
659    /// Serialized bytes of those records; the rest of their pages is
660    /// slack.
661    pub record_payload_bytes: u64,
662    /// Pages still holding soft-deleted records (reclaimed by compact).
663    pub deleted_record_page_bytes: u64,
664    pub catalog_run_bytes: u64,
665    pub catalog_payload_bytes: u64,
666    pub index_run_bytes: u64,
667    pub index_payload_bytes: u64,
668    /// First page of the persisted index run (0 = none).
669    pub index_start_page: u64,
670    pub wal_bytes: u64,
671    pub snapshot_manifest_bytes: u64,
672    pub cache_dir_run_bytes: u64,
673    /// Everything else: superseded catalog, index and directory runs from
674    /// earlier flushes, and freed pages, until the next compact.
675    pub unreferenced_bytes: u64,
676    pub live_records: u64,
677    pub ram_catalog: u64,
678    pub ram_id_map: u64,
679    pub ram_ann_centroids: u64,
680    pub ram_ann_codebook: u64,
681    pub ram_ann_posting_ids: u64,
682    pub ram_ann_posting_codes: u64,
683    pub ram_ann_assignment: u64,
684    pub ram_cache_dir: u64,
685    pub ram_key_caches: u64,
686    /// FMT-9b: the resident fp16 vector column as allocated (rows not yet
687    /// touched by recall cost no physical memory).
688    pub ram_vector_column: u64,
689    /// Sum of the `ram_*` fields.
690    pub ram_total: u64,
691}
692
693/// Summary statistics for a database.
694#[derive(Clone, Debug)]
695pub struct Stats {
696    /// Live (non-deleted) memory count.
697    pub memories: usize,
698    /// Tombstoned entries awaiting compaction.
699    pub deleted: usize,
700    /// Embedding dimensionality.
701    pub dimensions: usize,
702    /// File size in bytes.
703    pub file_bytes: u64,
704    /// Distinct agent IDs present.
705    pub agents: Vec<String>,
706    /// Whether pages are encrypted (always true in v1).
707    pub encrypted: bool,
708    /// Creation time (unix seconds).
709    pub created_at: i64,
710    /// ANN index shape, if an index has been built.
711    pub index: Option<IndexInfo>,
712    /// Current size of the write-ahead log region, in 8 KiB pages.
713    pub wal_pages: u64,
714    /// Fsyncs issued by the most recent successful [`Mnemo::flush`] on
715    /// this handle. `0` on a fresh handle before any flush, or when
716    /// `flush()` short-circuited (nothing dirty). Phase 6 instrumentation
717    /// for the Phase 11.1 write-latency work — the planner wants this
718    /// before deciding whether cutting fsync count is a viable
719    /// durability-preserving fix.
720    pub fsyncs_last_flush: u32,
721    /// FMT-9f: the file's on-disk format (`8` or `9`). A v8 file still
722    /// opens and writes as v8; `mnemo compact` upgrades it to v9.
723    pub format_version: u16,
724    /// MOBILE-2d: how recall scores vectors on this handle right now.
725    pub recall_mode: RecallMode,
726}
727
728/// [`Mnemo::stats_summary`]: the cheap statistics, read from the catalog and
729/// the header (v0.12.2, RB-002.3).
730#[derive(Clone, Debug, PartialEq, Eq)]
731pub struct StatsSummary {
732    /// Live (non-deleted) memory count.
733    pub memories: usize,
734    /// Tombstoned entries awaiting compaction.
735    pub deleted: usize,
736    /// Embedding dimensionality.
737    pub dimensions: usize,
738    /// File size in bytes.
739    pub file_bytes: u64,
740    /// The on-disk format, `8` or `9`.
741    pub format_version: u16,
742    /// Current size of the write-ahead log region, in 8 KiB pages.
743    pub wal_pages: u64,
744    /// Whether an IVF+PQ index exists (loaded, or persisted in the file).
745    pub has_index: bool,
746    /// How recall scores vectors right now.
747    pub recall_mode: RecallMode,
748    /// The bytes the v9 vector column needs to stay in memory: the live
749    /// facts × (`2 × dimensions + 4`). Recall is `ExactResident` while the
750    /// vector cache budget is at least this; `0` on v8, which has no column.
751    pub vector_column_bytes: u64,
752}
753
754/// MOBILE-2d: how recall scores vectors, from [`Mnemo::stats`].
755#[derive(Clone, Copy, Debug, PartialEq, Eq)]
756pub enum RecallMode {
757    /// An exact scan over the fp16 vector column held in memory: a v9 file
758    /// whose live facts fit [`Mnemo::set_vector_cache_budget`]. The fast
759    /// path.
760    ExactResident,
761    /// An exact scan that reads vectors through the page cache: a v9 file
762    /// whose live facts are over the budget, or a v8 file. Slower, and
763    /// slower still as the file grows; raise the budget or build an index.
764    ExactPaged,
765    /// An IVF+PQ index shortlists the candidates
766    /// ([`Mnemo::build_index`]).
767    Indexed,
768}
769
770impl RecallMode {
771    /// `exact_resident`, `exact_paged` or `indexed`.
772    pub fn as_str(&self) -> &'static str {
773        match self {
774            RecallMode::ExactResident => "exact_resident",
775            RecallMode::ExactPaged => "exact_paged",
776            RecallMode::Indexed => "indexed",
777        }
778    }
779}
780
781/// The error from [`Mnemo::try_close`]: the final flush failed, and the
782/// handle comes back with it, still open and still holding every write that
783/// wasn't flushed.
784pub struct CloseError {
785    pub(super) handle: Box<Mnemo>,
786    pub(super) error: MnemoError,
787}
788
789impl CloseError {
790    /// Why the flush failed.
791    pub fn error(&self) -> &MnemoError {
792        &self.error
793    }
794
795    /// The handle, to retry [`Mnemo::flush`] or [`Mnemo::try_close`].
796    pub fn into_inner(self) -> Mnemo {
797        *self.handle
798    }
799
800    /// The handle and the error.
801    pub fn into_parts(self) -> (Mnemo, MnemoError) {
802        (*self.handle, self.error)
803    }
804}
805
806impl std::fmt::Debug for CloseError {
807    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
808        f.debug_struct("CloseError")
809            .field("error", &self.error)
810            .finish_non_exhaustive()
811    }
812}
813
814impl std::fmt::Display for CloseError {
815    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
816        write!(f, "close failed (the handle is kept): {}", self.error)
817    }
818}
819
820impl std::error::Error for CloseError {
821    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
822        Some(&self.error)
823    }
824}
825
826/// Result of a [`Mnemo::compact_file`] run.
827#[derive(Clone, Copy, Debug, Default)]
828pub struct CompactReport {
829    /// Live memories before compaction.
830    pub before: usize,
831    /// Live memories after compaction (expired ones dropped).
832    pub after: usize,
833    /// Live, non-expired cache entries before compaction. FIX-1
834    /// R-001.1: compaction now preserves the result cache instead of
835    /// silently dropping it.
836    pub cache_before: usize,
837    /// Live, non-expired cache entries after compaction (tombstoned
838    /// and TTL-expired ones dropped).
839    pub cache_after: usize,
840}
841
842/// An encrypted, single-file agent memory database.
843pub struct Mnemo {
844    pager: Pager,
845    header: Header,
846    catalog: Vec<CatalogEntry>,
847    index: IdIndex,
848    #[allow(dead_code)]
849    path: PathBuf,
850    dimensions: usize,
851    kdf: KdfParams,
852    /// Set whenever the catalog changes; drives whether `flush` rewrites it.
853    dirty_catalog: bool,
854    /// Optional IVF+PQ approximate-nearest-neighbour index.
855    ann: Option<IvfPqIndex>,
856    /// Set whenever the in-memory ANN index differs from the persisted one.
857    /// PERF-1: `flush` persists it only per [`IndexPersist`]'s policy.
858    dirty_index: bool,
859    /// PERF-1: index persistence policy state.
860    index_persist: IndexPersist,
861    /// PERF-1 step 3: the header points at a persisted ANN index that
862    /// hasn't been loaded yet. It loads on first use (`ensure_ann`).
863    ann_unloaded: bool,
864    /// Append-only manifest of committed snapshots, oldest first. Capped
865    /// at [`Mnemo::max_snapshots`] entries on every flush — the oldest
866    /// entries are pruned first.
867    manifest: Vec<Snapshot>,
868    /// Maximum manifest entries to retain across flushes. `0` disables
869    /// the cap (retain forever). Defaults to [`DEFAULT_MAX_SNAPSHOTS`].
870    max_snapshots: usize,
871    /// If `true`, this handle was opened via [`Mnemo::open_read_only`] and
872    /// every mutating API returns [`MnemoError::ReadOnly`]. The underlying
873    /// file was opened without write permission and holds an OS shared
874    /// lock; the OS would reject a write() anyway, but gating in Rust
875    /// gives callers a clean, typed error.
876    read_only: bool,
877    /// Result-cache directory (Phase 10.1). See [`crate::result_cache`].
878    /// Loaded from `header.cache_start` on open; persisted on `flush`
879    /// via the same seal_run pipeline as catalog/index/manifest.
880    cache_dir: Vec<CacheDirectoryEntry>,
881    /// In-memory index over `cache_dir` for O(1) `(namespace, key_hash)`
882    /// lookups. Rebuilt on open + kept in sync on `cache_put`/`delete`.
883    cache_idx: DirectoryIndex,
884    /// Set whenever `cache_dir` changes; drives whether `flush` rewrites
885    /// the cache directory run.
886    dirty_cache: bool,
887    /// Per-namespace eviction budgets. Missing entries fall back to
888    /// [`CacheBudget::default`]. Not persisted (per-handle policy).
889    cache_budgets: std::collections::HashMap<String, CacheBudget>,
890    /// Flush policy for cache mutations. Memory writes ignore this and
891    /// always behave as `Strict`.
892    cache_flush_policy: CacheFlushPolicy,
893    /// Bookkeeping for `CacheFlushPolicy::Batched` — pending mutation
894    /// count and first-dirty timestamp.
895    cache_batch: BatchState,
896    /// In-memory hit/miss/eviction counters (reset on reopen).
897    cache_counters: CounterState,
898    /// Optional handle-scoped embedder (Phase 3, PR 10a). Registered
899    /// via [`Mnemo::set_embedder`]; consulted by [`Mnemo::remember_text`]
900    /// and [`RecallRequest::from_text`]. `None` means text-side APIs
901    /// return [`MnemoError::Invalid`] with a "no embedder" message.
902    /// Not persisted — the handle is re-registered after every open.
903    embedder: Option<std::sync::Arc<dyn Embedder>>,
904    /// Fsyncs issued by the most recent `flush()` call. Snapshotted
905    /// from the thread-local fsync counter in `lib.rs::fsync_counter`:
906    /// `flush()` reads it on entry, does its work (each `sync_all` the
907    /// pager / wal / recovery path makes bumps the counter), and
908    /// stores the delta here. `0` on a fresh handle before any flush,
909    /// or on a read-only handle where `flush()` short-circuits.
910    /// Exposed through [`Stats::fsyncs_last_flush`] for diagnostics —
911    /// the Phase 6 planner wants this before deciding whether cutting
912    /// fsync count is a viable write-latency win.
913    fsyncs_last_flush: u32,
914    /// FIX-1 R-001.8 part 2: lazy cache of the distinct agent IDs
915    /// across every live memory, built once on first `stats()` call
916    /// per handle. `remember()` adds to it in O(1); `delete()` can't
917    /// cheaply tell whether the removed memory was the last of its
918    /// agent (the agent lives in the encrypted body, not the catalog
919    /// — pre-v9 format), so it just invalidates the set and the next
920    /// `stats()` call rebuilds. Pre-FIX-1 every `stats()` call
921    /// decrypted every live memory to collect agents, turning an
922    /// otherwise-cheap diagnostic into an O(N) decrypt.
923    agent_set: Option<std::collections::BTreeSet<String>>,
924    /// Phase 12.1 lazy caches, built together on the first keyed op this
925    /// handle sees (`remember_keyed`, `update` that touches `_mnemo.key`,
926    /// or any `history(...)` call). Both are maintained incrementally
927    /// after that. `None` → not built yet; `Some(…)` → authoritative.
928    ///
929    /// * `key_index`: `(scope_owner, key) → ULID bytes` of the **live**
930    ///   record for each keyed slot. `scope_owner` is `Some(agent_id)`
931    ///   for a `Private` scope slot and `None` for a `Shared` one, so a
932    ///   private write never collides with a shared one.
933    /// * `superseded`: the ULID bytes of every record that has been
934    ///   superseded (`_mnemo.superseded_by` set on it). `recall` and
935    ///   `about` skip these before any decrypt.
936    ///
937    /// Building both costs one scan over live records (~1s at 100K with
938    /// hardware AES) and happens at most once per handle. A format bump
939    /// to v9 moves the key into the catalog row so the scan goes away.
940    key_index: Option<std::collections::HashMap<KeySlot, u128>>,
941    superseded: Option<std::collections::HashSet<u128>>,
942    /// R-004.2: thread layers + onboarding ids, built by the same lazy scan.
943    layers: Option<LayerCache>,
944    /// FMT-9e: thread turns are compressed once older than this many
945    /// seconds (`0`: at write). Per handle, not persisted.
946    turn_compress_after: i64,
947    /// FMT-9 (a): the committed free list (v9; always empty on v8). Pages
948    /// allocated from it since the last commit are already removed.
949    free: FreeList,
950    /// FMT-9 (a): runs this transaction stopped referencing (overwritten
951    /// or deleted records, tombstoned cache entries, a relocated WAL
952    /// region). The next commit adds them to the free list, freed at its
953    /// own transaction id.
954    pending_free: Vec<(u64, u64)>,
955    /// FMT-9 (a): the free list changed (an allocation took pages from it)
956    /// and must be rewritten by the next commit.
957    free_dirty: bool,
958    /// FMT-9 (b): the key-slot run (v9; empty until Phase 13.2 adds slots).
959    key_slots: KeySlotRun,
960    /// FMT-9 (b): `key_slots` changed since the last commit.
961    dirty_keys: bool,
962    /// FMT-9: this writable session has burned a transaction id with a
963    /// durable header-only commit (`ensure_gen_lease`), so the generations
964    /// its pages carry can't repeat ones a crashed earlier session used.
965    gen_leased: bool,
966    /// FMT-9b: the fp16 vector column (v9; unused on v8).
967    col: VecColumn,
968    /// FMT-9b.2: packed record pages (v9; unused on v8).
969    recs: RecPages,
970    /// FMT-9d: the BM25 keyword index (v9; unused on v8).
971    bm25: Bm25State,
972    /// FMT-9d: test hook: write this layout byte instead of the current
973    /// one (to exercise the unknown-layout path).
974    index_layout_override: Option<u8>,
975    /// FMT-9d: during one recall, each keyword match's normalised BM25
976    /// score, by id.
977    kw: Option<std::collections::HashMap<u128, f32>>,
978    /// FMT-9c.2: catalog rows changed since the last commit (v9 writes
979    /// them as a delta run instead of the whole catalog).
980    dirty_rows: std::collections::BTreeSet<usize>,
981    /// FMT-9c.2: the delta runs on top of the base catalog, oldest first,
982    /// and how many rows they hold in all.
983    delta_chain: Vec<RunPtr>,
984    delta_rows: usize,
985    /// FMT-9c.3: the ANN index's delta runs on top of its base run, oldest
986    /// first, and how many changes they hold in all.
987    index_chain: Vec<RunPtr>,
988    index_chain_ops: usize,
989    /// FMT-9c.3: the next commit writes the whole index (after a build,
990    /// rebuild or restore).
991    index_rebase: bool,
992    /// FMT-9c.3: this flush's index changes, when it writes them as a
993    /// delta run.
994    index_delta_ops: Option<Vec<IndexOp>>,
995    /// FMT-9c.2: the next commit writes a whole base catalog (after a
996    /// restore, or when the chain has grown too long).
997    catalog_rewrite: bool,
998    /// FMT-9c: the snapshot count was set explicitly (config or
999    /// `set_max_snapshots`), which replaces v9's default retention policy.
1000    snapshot_cap_explicit: bool,
1001    /// FMT-9c: this flush wrote big runs straight to their home pages,
1002    /// which must be fsynced before the commit.
1003    direct_writes: bool,
1004    /// FMT-9b: keep the column resident while it fits this many bytes.
1005    vector_cache_budget: usize,
1006}
1007
1008/// Composite key for the lazy `key_index` on `Mnemo`. A slot is identified
1009/// by `(scope_owner, key)`:
1010/// * `Scope::Private` writes carry the owning agent → `Some(agent_id)`.
1011/// * `Scope::Shared` writes are per-file → `None`.
1012///
1013/// A private write never supersedes a shared one, and the reverse is also
1014/// true. Scope lives on `Memory.scope`, agent on `Memory.agent_id`.
1015#[derive(Debug, Clone, PartialEq, Eq, Hash)]
1016pub(crate) struct KeySlot {
1017    /// `Some(agent_id)` for `Scope::Private`, `None` for `Scope::Shared`.
1018    pub(crate) scope_owner: Option<String>,
1019    /// The caller-supplied key string, exactly as given (no case-fold).
1020    pub(crate) key: String,
1021}
1022
1023/// True if a memory's metadata marks it as the canonical onboarding manifest
1024/// (`metadata.topic == "manifest"`). Used by [`Mnemo::about`] to hoist the
1025/// manifest to the top of the briefing regardless of importance ordering.
1026fn is_manifest(m: &Memory) -> bool {
1027    m.metadata
1028        .get("topic")
1029        .and_then(|v| v.as_str())
1030        .map(|s| s.eq_ignore_ascii_case("manifest"))
1031        .unwrap_or(false)
1032}
1033
1034/// PERF-1 step 4: ULID → catalog row, as an open-addressing table of `u32`
1035/// row numbers: 4 bytes a slot, about 5 bytes an entry, against about 43
1036/// for the `HashMap<u128, usize>` it replaces. A probe compares against the
1037/// catalog's own id at that row, so the ids aren't stored twice. Rows are
1038/// never removed (a delete only tombstones the catalog entry), so there's
1039/// no delete path.
1040#[derive(Debug, Clone, Default)]
1041struct IdIndex {
1042    slots: Vec<u32>,
1043    len: usize,
1044}
1045
1046const NO_ROW: u32 = u32::MAX;
1047
1048impl IdIndex {
1049    fn build(catalog: &[CatalogEntry]) -> IdIndex {
1050        let mut t = IdIndex {
1051            slots: vec![NO_ROW; crate::index::table_capacity_for(catalog.len())],
1052            len: 0,
1053        };
1054        for (row, e) in catalog.iter().enumerate() {
1055            t.insert(e.id, row, catalog);
1056        }
1057        t
1058    }
1059
1060    /// The catalog row holding `id`, if any.
1061    fn get(&self, id: u128, catalog: &[CatalogEntry]) -> Option<usize> {
1062        if self.slots.is_empty() {
1063            return None;
1064        }
1065        let cap = self.slots.len();
1066        let mut i = crate::index::slot_home(id, cap);
1067        loop {
1068            let row = self.slots[i];
1069            if row == NO_ROW {
1070                return None;
1071            }
1072            if catalog[row as usize].id == id {
1073                return Some(row as usize);
1074            }
1075            i = crate::index::next_slot(i, cap);
1076        }
1077    }
1078
1079    /// Map `id` to `row`. `catalog` must hold every row already in the
1080    /// table (the new row may not be pushed yet).
1081    fn insert(&mut self, id: u128, row: usize, catalog: &[CatalogEntry]) {
1082        if (self.len + 1) * 4 > self.slots.len() * 3 {
1083            let cap = (self.slots.len() * 2).max(crate::index::table_capacity_for(self.len + 1));
1084            let old = std::mem::replace(&mut self.slots, vec![NO_ROW; cap]);
1085            self.len = 0;
1086            for r in old.into_iter().filter(|&r| r != NO_ROW) {
1087                self.insert(catalog[r as usize].id, r as usize, catalog);
1088            }
1089        }
1090        let cap = self.slots.len();
1091        let mut i = crate::index::slot_home(id, cap);
1092        loop {
1093            let r = self.slots[i];
1094            if r == NO_ROW {
1095                self.slots[i] = row as u32;
1096                self.len += 1;
1097                return;
1098            }
1099            if catalog[r as usize].id == id {
1100                self.slots[i] = row as u32;
1101                return;
1102            }
1103            i = crate::index::next_slot(i, cap);
1104        }
1105    }
1106
1107    fn heap_bytes(&self) -> usize {
1108        self.slots.capacity() * std::mem::size_of::<u32>()
1109    }
1110}
1111
1112/// Build the ULID → catalog-row lookup.
1113fn build_id_index(catalog: &[CatalogEntry]) -> IdIndex {
1114    IdIndex::build(catalog)
1115}
1116
1117// ---------------------------------------------------------------------------
1118// Phase 12.7a helpers used by `ingest_thread`.
1119// ---------------------------------------------------------------------------
1120
1121/// PERF-1 / FMT-9: was this catalog row written after the persisted index
1122/// run? v8 allocates pages monotonically, so a record past the run's first
1123/// page is newer. v9 reuses pages, so it compares generations instead.
1124fn written_after_index(e: &CatalogEntry, v9: bool, index_start: u64, index_gen: u64) -> bool {
1125    if v9 {
1126        // `start_page` 0: packed at the next flush, so certainly newer.
1127        e.start_page == 0 || e.gen > index_gen
1128    } else {
1129        e.start_page > index_start
1130    }
1131}
1132
1133/// Whether a record belongs in the ANN index: facts only. Thread-archive
1134/// turns, essence items and thread links are read by kind and scope, never
1135/// by similarity, so they stay out (R-004.2).
1136fn is_ann_kind(m: &Memory) -> bool {
1137    !matches!(
1138        m.metadata.get(MNEMO_META_KIND).and_then(|v| v.as_str()),
1139        Some(MNEMO_META_KIND_TURN)
1140            | Some(MNEMO_META_KIND_ESSENCE)
1141            | Some(MNEMO_META_KIND_THREAD_LINK)
1142    )
1143}