perf: sign-signature Hamming prefilter for dense search at scale (#347)

dense_search read EVERY embedded row's full f32 blob per query (~1.5KB
per row at 384 dims) up to the 50k scan ceiling — the last full-table
scan on the recall hot path.

New entities.emb_sig column (schema v6): the embedding's sign bits
packed into dim/8 bytes (48 bytes at 384 dims). Above 2048 embedded
rows, dense_search now scans only id+emb_sig, ranks candidates by
Hamming distance to the query signature (id tie-break — deterministic),
keeps a generously oversampled pool (16x limit, min 512), fetches full
embeddings for the pool alone (chunked IN), and exact-cosine re-ranks
as before. ~30x less I/O on the scan phase at scale.

Guarantees kept:
- Below the cutover the exact full scan runs unchanged — small vaults
  (and every existing test) stay byte-identical.
- Zero new dependencies; results remain deterministic run-to-run.
- Rows with a NULL signature (written by a pre-v6 binary after
  migration) are always included in the pool, never silently dropped.
- Dimension-mismatched signatures score maximally distant.

store_embedding writes both blob+sig; the v6 migration backfills
signatures for existing embeddings in one bounded pass.

Tests: embedding_signature_packs_sign_bits_and_hamming_tracks_distance,
dense_search_signature_prefilter_finds_the_same_top_hits_at_scale
(2200-row vault, engineered near-neighbors, archived exclusion),
migration_backfills_embedding_signatures.
Suite: 167 passed / 0 failed; --no-default-features builds clean.

Co-authored-by: tcconnally <hermes@perseus.observer>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: 3 people

src/db.rs

@@ -586,7 +586,8 @@ impl Database {
         Ok(result)
     }
 
-    /// Store a dense vector embedding for an entity.
+    /// Store a dense vector embedding for an entity (and its sign-bit
+    /// signature — see `embedding_signature` / the dense_search prefilter).
     #[allow(dead_code)]
     pub fn store_embedding(
         &self,
@@ -595,9 +596,10 @@ impl Database {
     ) -> Result<(), Box<dyn std::error::Error>> {
         let conn = self.conn()?;
         let blob: Vec<u8> = embedding.iter().flat_map(|f| f.to_le_bytes()).collect();
+        let sig = embedding_signature(embedding);
         conn.execute(
-            "UPDATE entities SET embedding = ?1 WHERE id = ?2",
-            params![blob, id],
+            "UPDATE entities SET embedding = ?1, emb_sig = ?2 WHERE id = ?3",
+            params![blob, sig, id],
         )?;
         Ok(())
     }
@@ -976,28 +978,114 @@ impl Database {
         let max_scan = 50_000; // safety ceiling — databases beyond this should use HNSW
         let dim = query_vec.len();
 
+        // Signature prefilter cutover point. Below this many embedded rows the
+        // exact full scan is already cheap AND stays byte-identical to the
+        // historical behavior; above it, reading every f32 blob dominates
+        // query time, so we Hamming-prefilter on the dim/8-byte sign
+        // signatures and only read full embeddings for an oversampled pool.
+        const DENSE_SIG_PREFILTER_MIN_ROWS: i64 = 2048;
+        // Exact-rerank pool size: generous oversampling keeps the top-k from
+        // the prefiltered path effectively identical to the exact scan for
+        // normalized text embeddings.
+        let pool_target = |limit: usize| (limit.saturating_mul(16)).clamp(512, 4096);
+
+        let embedded_rows: i64 = conn.query_row(
+            "SELECT COUNT(*) FROM entities WHERE archived = 0 AND embedding IS NOT NULL",
+            [],
+            |r| r.get(0),
+        )?;
+
         // Phase 1 (#209): lightweight scan — read only id + embedding for scoring.
         // The old query hydrated EVERY candidate (decrypt body, parse tags/links)
         // up to max_scan just to score and then keep top-k. Defer full hydration
         // to the surviving top-k in phase 3.
-        let mut stmt = conn.prepare(&format!(
-            "SELECT id, embedding FROM entities \
-             WHERE archived = 0 AND embedding IS NOT NULL LIMIT {}",
-            max_scan
-        ))?;
-        let rows = stmt.query_map([], |row| {
-            let id: String = row.get(0)?;
-            let emb_blob: Vec<u8> = row.get(1)?;
-            let emb: Vec<f32> = emb_blob
-                .chunks_exact(4)
-                .map(|b| f32::from_le_bytes([b[0], b[1], b[2], b[3]]))
-                .collect();
-            Ok((id, emb))
-        })?;
-        let candidates: Vec<(String, Vec<f32>)> = rows
-            .filter_map(|r| r.ok())
-            .filter(|(_, emb)| emb.len() == dim)
-            .collect();
+        let candidates: Vec<(String, Vec<f32>)> = if embedded_rows
+            < DENSE_SIG_PREFILTER_MIN_ROWS
+        {
+            let mut stmt = conn.prepare(&format!(
+                "SELECT id, embedding FROM entities \
+                 WHERE archived = 0 AND embedding IS NOT NULL LIMIT {}",
+                max_scan
+            ))?;
+            let rows = stmt.query_map([], |row| {
+                let id: String = row.get(0)?;
+                let emb_blob: Vec<u8> = row.get(1)?;
+                let emb: Vec<f32> = emb_blob
+                    .chunks_exact(4)
+                    .map(|b| f32::from_le_bytes([b[0], b[1], b[2], b[3]]))
+                    .collect();
+                Ok((id, emb))
+            })?;
+            rows.filter_map(|r| r.ok())
+                .filter(|(_, emb)| emb.len() == dim)
+                .collect()
+        } else {
+            // Phase 0: signature prefilter. Scan only id + emb_sig (~48 bytes
+            // vs ~1.5KB per row for 384-dim), rank by Hamming distance to the
+            // query signature with an id tie-break (deterministic), keep an
+            // oversampled pool, then read full embeddings for the pool only.
+            // Rows with a NULL signature (written by a pre-v6 binary after
+            // migration) are always included so they can't be silently lost.
+            let query_sig = embedding_signature(query_vec);
+            let mut stmt = conn.prepare(&format!(
+                "SELECT id, emb_sig FROM entities \
+                 WHERE archived = 0 AND embedding IS NOT NULL LIMIT {}",
+                max_scan
+            ))?;
+            let rows = stmt.query_map([], |row| {
+                Ok((
+                    row.get::<_, String>(0)?,
+                    row.get::<_, Option<Vec<u8>>>(1)?,
+                ))
+            })?;
+            let mut ranked: Vec<(u32, String)> = Vec::new();
+            let mut unsigned_ids: Vec<String> = Vec::new();
+            for row in rows {
+                let (id, sig) = row?;
+                match sig {
+                    Some(s) => ranked.push((signature_hamming(&query_sig, &s), id)),
+                    None => unsigned_ids.push(id),
+                }
+            }
+            let pool = pool_target(limit);
+            ranked.sort_by(|a, b| a.0.cmp(&b.0).then_with(|| a.1.cmp(&b.1)));
+            ranked.truncate(pool);
+            let mut pool_ids: Vec<String> =
+                ranked.into_iter().map(|(_, id)| id).collect();
+            pool_ids.append(&mut unsigned_ids);
+
+            // Fetch full embeddings for the pool only (chunked IN to bound
+            // SQL variable count).
+            let mut fetched: Vec<(String, Vec<f32>)> = Vec::with_capacity(pool_ids.len());
+            for chunk in pool_ids.chunks(500) {
+                let placeholders = vec!["?"; chunk.len()].join(",");
+                let sql = format!(
+                    "SELECT id, embedding FROM entities WHERE id IN ({})",
+                    placeholders
+                );
+                let mut estmt = conn.prepare(&sql)?;
+                let refs: Vec<&dyn rusqlite::types::ToSql> = chunk
+                    .iter()
+                    .map(|s| s as &dyn rusqlite::types::ToSql)
+                    .collect();
+                let erows = estmt.query_map(refs.as_slice(), |row| {
+                    let id: String = row.get(0)?;
+                    let emb_blob: Vec<u8> = row.get(1)?;
+                    let emb: Vec<f32> = emb_blob
+                        .chunks_exact(4)
+                        .map(|b| f32::from_le_bytes([b[0], b[1], b[2], b[3]]))
+                        .collect();
+                    Ok((id, emb))
+                })?;
+                for r in erows {
+                    let (id, emb) = r?;
+                    if emb.len() == dim {
+                        fetched.push((id, emb));
+                    }
+                }
+            }
+            fetched
+        };
 
         // Phase 2: score by cosine similarity, keep the top `limit` ids.
         let mut scored_ids: Vec<(String, f64)>;
@@ -5632,6 +5720,29 @@ fn is_stopword(word: &str) -> bool {
     STOPWORDS.contains(&lower.as_str())
 }
 
+/// Sign-bit signature of an embedding: bit i set iff v[i] > 0, packed into
+/// dim/8 bytes (dim 384 → 48 bytes vs 1536 for the f32 blob). For normalized
+/// text embeddings, Hamming distance between signatures tracks cosine
+/// distance closely enough to prefilter candidates before an exact re-rank.
+pub(crate) fn embedding_signature(v: &[f32]) -> Vec<u8> {
+    let mut sig = vec![0u8; v.len().div_ceil(8)];
+    for (i, &x) in v.iter().enumerate() {
+        if x > 0.0 {
+            sig[i / 8] |= 1 << (i % 8);
+        }
+    }
+    sig
+}
+
+/// Hamming distance between two signatures. Length mismatch (different
+/// embedding dims) scores maximally distant so it can never win a slot.
+fn signature_hamming(a: &[u8], b: &[u8]) -> u32 {
+    if a.len() != b.len() {
+        return u32::MAX;
+    }
+    a.iter().zip(b).map(|(x, y)| (x ^ y).count_ones()).sum()
+}
+
 fn truncate_str(s: &str, max_len: usize) -> String {
     if s.chars().count() <= max_len {
         s.to_string()
@@ -7692,6 +7803,99 @@ mod tests {
         let _ = fs::remove_file(&path);
     }
 
+    #[test]
+    fn embedding_signature_packs_sign_bits_and_hamming_tracks_distance() {
+        // bit i set iff v[i] > 0; zero and negative both clear.
+        let sig = embedding_signature(&[1.0, -1.0, 0.0, 0.5, -0.2, 2.0, 0.0, -3.0, 0.1]);
+        assert_eq!(sig.len(), 2, "9 dims pack into 2 bytes");
+        assert_eq!(sig[0], 0b0010_1001);
+        assert_eq!(sig[1], 0b0000_0001);
+
+        let a = embedding_signature(&[1.0, 1.0, -1.0, -1.0]);
+        let b = embedding_signature(&[1.0, -1.0, -1.0, 1.0]);
+        assert_eq!(signature_hamming(&a, &a), 0);
+        assert_eq!(signature_hamming(&a, &b), 2);
+        // Dim mismatch can never win a candidate slot.
+        assert_eq!(signature_hamming(&a, &sig), u32::MAX);
+    }
+
+    #[test]
+    fn dense_search_signature_prefilter_finds_the_same_top_hits_at_scale() {
+        // Above DENSE_SIG_PREFILTER_MIN_ROWS dense_search switches to the
+        // Hamming-prefilter + exact-rerank path. Seed 2200 embedded rows with
+        // a deterministic spread plus two engineered near-neighbors of the
+        // query; the prefiltered path must surface both, exactly ranked by
+        // true cosine, and never return an archived row.
+        let (db, path) = temp_db();
+        let conn = db.conn().unwrap();
+        let blob = |v: &[f32]| -> Vec<u8> { v.iter().flat_map(|f| f.to_le_bytes()).collect() };
+        let dim = 16usize;
+        let tx = conn.unchecked_transaction().unwrap();
+        {
+            let mut stmt = tx
+                .prepare(
+                    "INSERT INTO entities (id, category, key, body_json, type, status,
+                        retrieval_count, last_accessed_unix_ms, created_at_unix_ms,
+                        decay_score, layer, embedding, emb_sig, archived)
+                     VALUES (?1, 'insight', ?2, '{}', 'insight', 'active', 0, 0, 0,
+                             1.0, 'working', ?3, ?4, ?5)",
+                )
+                .unwrap();
+            // Deterministic filler vectors: sign pattern derived from the row
+            // index bits, pointing all over the hypercube and away from the
+            // all-positive query region. Starts at 1: i=0 hashes to the
+            // all-positive pattern, which would tie the engineered exact hit
+            // (2654435761 is odd, so no other i < 65536 hashes to it).
+            for i in 1..=2200u32 {
+                let v: Vec<f32> = (0..dim)
+                    .map(|d| {
+                        let bit = (i.wrapping_mul(2654435761) >> (d as u32 % 31)) & 1;
+                        if bit == 1 { -1.0 } else { 0.3 } // mixed signs, never all-positive
+                    })
+                    .collect();
+                stmt.execute(params![
+                    format!("filler-{:05}", i),
+                    format!("filler-key-{:05}", i),
+                    blob(&v),
+                    embedding_signature(&v),
+                    0i64
+                ])
+                .unwrap();
+            }
+            // Engineered hits: the query itself and a slightly-rotated cousin.
+            let query: Vec<f32> = vec![1.0; dim];
+            let mut near = query.clone();
+            near[0] = 0.6;
+            stmt.execute(params![
+                "hit-exact", "hit-exact-key", blob(&query), embedding_signature(&query), 0i64
+            ])
+            .unwrap();
+            stmt.execute(params![
+                "hit-near", "hit-near-key", blob(&near), embedding_signature(&near), 0i64
+            ])
+            .unwrap();
+            // An archived twin of the query must never surface.
+            stmt.execute(params![
+                "hit-archived", "hit-archived-key", blob(&query), embedding_signature(&query), 1i64
+            ])
+            .unwrap();
+        }
+        tx.commit().unwrap();
+
+        let query: Vec<f32> = vec![1.0; dim];
+        let results = db.dense_search(&query, 5).unwrap();
+        let ids: Vec<&str> = results.iter().map(|(e, _)| e.id.as_str()).collect();
+        assert_eq!(ids[0], "hit-exact", "true nearest must rank first: {ids:?}");
+        assert_eq!(ids[1], "hit-near", "second-nearest must rank second: {ids:?}");
+        assert!(!ids.contains(&"hit-archived"), "archived row leaked: {ids:?}");
+        assert!(
+            results[0].1 > results[1].1,
+            "scores must be exact-cosine ordered"
+        );
+
+        let _ = fs::remove_file(&path);
+    }
+
     // #226: dense/hybrid recall must embed the query, not silently fall back to
     // FTS5. With no embedding backend configured, a dense recall over a
     // non-empty query surfaces the backend error instead of returning keyword

src/schema.rs

@@ -26,6 +26,11 @@ CREATE TABLE IF NOT EXISTS entities (
     created_at_unix_ms INTEGER NOT NULL,
     last_accessed_unix_ms INTEGER NOT NULL,
     embedding BLOB,
+    -- Sign-bit signature of `embedding` (v2.13.0, dim/8 bytes): bit i set iff
+    -- embedding[i] > 0. dense_search Hamming-prefilters on this instead of
+    -- reading every full embedding blob once the vault is large enough.
+    -- Written by store_embedding; backfilled by the v6 migration.
+    emb_sig BLOB,
     always_on INTEGER DEFAULT 0,
     certainty REAL DEFAULT 0.5,
     -- Persistent importance floor (v2.13.0). Set by mimir_score; decay_tick and
@@ -145,7 +150,7 @@ CREATE INDEX IF NOT EXISTS idx_entity_history_catkey ON entity_history(category,
 /// the column-add migrations below have been applied. Bump this whenever you add
 /// a new ALTER-probe migration in `initialize_schema`, or existing databases
 /// (already at the previous level) will skip it.
-const SCHEMA_VERSION: i64 = 5;
+const SCHEMA_VERSION: i64 = 6;
 
 /// Initialize the v0.2.0 schema on a fresh database.
 pub fn initialize_schema(conn: &Connection) -> Result<(), Box<dyn std::error::Error>> {
@@ -275,6 +280,35 @@ pub fn initialize_schema(conn: &Connection) -> Result<(), Box<dyn std::error::Er
         conn.execute_batch("ALTER TABLE entities ADD COLUMN importance REAL DEFAULT 0.0;")?;
     }
 
+    // v6: sign-bit embedding signatures for the dense-search prefilter, plus a
+    // backfill for embeddings stored before the column existed. Bounded work:
+    // one pass over embedded rows, ~50 bytes written per row.
+    if conn.prepare("SELECT emb_sig FROM entities LIMIT 1").is_err() {
+        conn.execute_batch("ALTER TABLE entities ADD COLUMN emb_sig BLOB;")?;
+    }
+    {
+        let mut stmt = conn.prepare(
+            "SELECT id, embedding FROM entities \
+             WHERE embedding IS NOT NULL AND emb_sig IS NULL",
+        )?;
+        let rows = stmt.query_map([], |r| {
+            Ok((r.get::<_, String>(0)?, r.get::<_, Vec<u8>>(1)?))
+        })?;
+        let pending: Vec<(String, Vec<u8>)> = rows.filter_map(|r| r.ok()).collect();
+        drop(stmt);
+        for (id, blob) in pending {
+            let emb: Vec<f32> = blob
+                .chunks_exact(4)
+                .map(|b| f32::from_le_bytes([b[0], b[1], b[2], b[3]]))
+                .collect();
+            let sig = crate::db::embedding_signature(&emb);
+            conn.execute(
+                "UPDATE entities SET emb_sig = ?1 WHERE id = ?2",
+                params![sig, id],
+            )?;
+        }
+    }
+
     // v4 (#339): identity becomes (category, key, workspace_hash). A plain
     // (category, key) uniqueness made cross-workspace key collisions
     // unstorable, which is what forced mimir_share's "copy into workspace" to
@@ -690,6 +724,32 @@ mod tests {
         );
     }
 
+    #[test]
+    fn migration_backfills_embedding_signatures() {
+        // v6: embeddings stored before emb_sig existed must get a signature
+        // during the gated migration, matching what store_embedding writes.
+        let (conn, _path) = temp_db();
+        initialize_schema(&conn).expect("fresh init");
+        // Rewind: drop the column's data by simulating a pre-v6 row.
+        let emb: Vec<f32> = vec![1.0, -2.0, 0.5, -0.1];
+        let blob: Vec<u8> = emb.iter().flat_map(|f| f.to_le_bytes()).collect();
+        conn.execute(
+            "INSERT INTO entities (id, category, key, body_json, embedding, emb_sig,
+                                   created_at_unix_ms, last_accessed_unix_ms)
+             VALUES ('sig-1', 'note', 'k', '{}', ?1, NULL, 0, 0)",
+            params![blob],
+        )
+        .unwrap();
+        conn.pragma_update(None, "user_version", 5).unwrap();
+
+        initialize_schema(&conn).expect("v5 -> v6 migration");
+
+        let sig: Vec<u8> = conn
+            .query_row("SELECT emb_sig FROM entities WHERE id = 'sig-1'", [], |r| r.get(0))
+            .expect("emb_sig must be backfilled");
+        assert_eq!(sig, crate::db::embedding_signature(&emb));
+    }
+
     #[test]
     fn adds_bitemporal_columns_and_backfills_recorded_at() {
         // A legacy DB (no bi-temporal columns) with one row predating the migration.