sqlrite 0.1.14__tar.gz → 0.1.15__tar.gz

{sqlrite-0.1.14 → sqlrite-0.1.15}/Cargo.lock

@@ -3736,7 +3736,7 @@ dependencies = [
 
 [[package]]
 name = "sqlrite-desktop"
-version = "0.1.14"
+version = "0.1.15"
 dependencies = [
  "serde",
  "serde_json",
@@ -3748,7 +3748,7 @@ dependencies = [
 
 [[package]]
 name = "sqlrite-engine"
-version = "0.1.14"
+version = "0.1.15"
 dependencies = [
  "clap",
  "env_logger",
@@ -3763,7 +3763,7 @@ dependencies = [
 
 [[package]]
 name = "sqlrite-ffi"
-version = "0.1.14"
+version = "0.1.15"
 dependencies = [
  "cbindgen",
  "sqlrite-engine",
@@ -3771,7 +3771,7 @@ dependencies = [
 
 [[package]]
 name = "sqlrite-nodejs"
-version = "0.1.14"
+version = "0.1.15"
 dependencies = [
  "napi",
  "napi-build",
@@ -3781,7 +3781,7 @@ dependencies = [
 
 [[package]]
 name = "sqlrite-python"
-version = "0.1.14"
+version = "0.1.15"
 dependencies = [
  "pyo3",
  "sqlrite-engine",

{sqlrite-0.1.14 → sqlrite-0.1.15}/Cargo.toml

@@ -27,7 +27,7 @@ resolver = "3"
 # `package =` key so the import name stays `sqlrite` internally:
 #     sqlrite = { package = "sqlrite-engine", path = "…" }
 name = "sqlrite-engine"
-version = "0.1.14"
+version = "0.1.15"
 authors = ["Joao Henrique Machado Silva <joaoh82@gmail.com>"]
 edition = "2024"
 rust-version = "1.85"

{sqlrite-0.1.14 → sqlrite-0.1.15}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlrite
-Version: 0.1.14
+Version: 0.1.15
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License

{sqlrite-0.1.14 → sqlrite-0.1.15}/desktop/package.json

@@ -1,7 +1,7 @@
 {
   "name": "sqlrite-desktop-frontend",
   "private": true,
-  "version": "0.1.14",
+  "version": "0.1.15",
   "type": "module",
   "scripts": {
     "dev": "vite",

{sqlrite-0.1.14 → sqlrite-0.1.15}/docs/phase-7-plan.md

@@ -162,7 +162,7 @@ SELECT id, title FROM docs ORDER BY embedding <-> [0.1, ...] LIMIT 10;
 >
 > - **✅ 7d.1 — Pure HNSW algorithm** *(~700 LOC, shipped in v0.1.13).* `src/sql/hnsw.rs` standalone module: insert + search + layer assignment + beam search per layer + L2/cosine/dot distance dispatch. No SQL integration yet — vectors are passed in via a `get_vec` closure so the algorithm doesn't depend on table types. Tests verify recall@k ≥ 0.95 vs brute-force on randomly-generated vector sets; deterministic via a fixed RNG seed.
 > - **✅ 7d.2 — SQL integration** *(~500 LOC).* `CREATE INDEX … USING hnsw (col)` parser + engine, INSERT wiring (also calls `hnsw.insert()` incrementally), query optimizer hook (recognizes `ORDER BY vec_distance_l2(col, literal) LIMIT k` and probes the HNSW instead of full-scanning). HNSW lives in memory only at this point; the **CREATE INDEX SQL persists in `sqlrite_master` and reopen rebuilds the graph from current rows** — partial persistence ahead of 7d.3. DELETE/UPDATE on HNSW-indexed tables refused with helpful error pointing at 7d.3.
-> - **7d.3 — Persistence** *(~300 LOC).* Wire HNSW into the cell format: new `KIND_HNSW` cell tag, page-tree storage parallel to secondary indexes, save/reopen round-trip without rebuild. Also adds DELETE/UPDATE support since the persisted form gives us a natural rebuild trigger.
+> - **✅ 7d.3 — Persistence** *(~600 LOC).* New `KIND_HNSW` cell tag and `HnswNodeCell` encoding (varint node_id + per-layer neighbor lists). Each HNSW index gets its own page tree parallel to secondary indexes. Open path loads cells directly into `HnswIndex::from_persisted_nodes` — no algorithm runs, exact bit-for-bit reproduction. Also unblocks DELETE / UPDATE on HNSW-indexed tables: those mark the index `needs_rebuild`, save rebuilds from current rows before staging. ~2× the original 300-LOC estimate because the cell encoding + tests + rebuild path together added more than expected.
 >
 > Each 7d.x ships as its own PR + release wave. The user-facing value lands at 7d.2; 7d.3 closes the persistence loop. 7d.1 is foundational but ships a tested algorithmic primitive on its own — useful as documentation of the engine's "from scratch" theme.
 

{sqlrite-0.1.14 → sqlrite-0.1.15}/docs/roadmap.md

@@ -473,7 +473,7 @@ Approved sub-phases (Q1–Q10 resolved):
 - **✅ 7a — `VECTOR(N)` column type** *(v0.1.10)* — dense fixed-dimension f32 storage via the existing cell encoding; format bumped to v4. Bracket-array literal syntax `[0.1, 0.2, …]` (Q7).
 - **✅ 7b — Distance functions** *(v0.1.11)* — `vec_distance_l2/cosine/dot`, plus the ORDER BY-expressions parser change so KNN queries work end-to-end. Operators (`<->` `<=>` `<#>`) deferred to **7b.1** — sqlparser doesn't parse them natively, contradicting Q6's "tiny parser change" assumption.
 - **✅ 7c — Brute-force KNN executor optimization** — bounded `BinaryHeap` of size k for `ORDER BY <expr> LIMIT k`. ~1.8× faster than full-sort at N=10k for cheap keys; bigger gains on expensive keys like `vec_distance_l2`.
-- **7d — HNSW ANN index** — split into 7d.1 (✅ algorithm), 7d.2 (✅ SQL integration), 7d.3 (persistence). `CREATE INDEX … USING hnsw (col)`; fixed defaults `M=16, ef_construction=200, ef_search=50` (Q2).
+- **✅ 7d — HNSW ANN index** — three PRs: 7d.1 (algorithm w/ recall@10 ≥ 0.95), 7d.2 (SQL integration + query optimizer), 7d.3 (persistence + DELETE/UPDATE rebuild). `CREATE INDEX … USING hnsw (col)`; fixed defaults `M=16, ef_construction=200, ef_search=50` (Q2). New `KIND_HNSW` cell tag.
 - **7e — JSON column type + path queries** — `JSON` data type stored as bincoded `serde_json::Value` (Q3); `json_extract` / `json_array_length` / `json_object_keys` / `json_type`.
 - **7f — ~~Full-text search with BM25~~** — **deferred to Phase 8** (Q1).
 - **7g — `ask()` API across the product surface** — natural-language → SQL via Anthropic API (Q4), Anthropic-first then OpenAI + Ollama follow-ups. Foundational 7g.1 introduces a new `sqlrite-ask` crate (Q10 — separate crate, not a feature flag). Thin per-product adapters in 7g.2-7g.8 cover REPL, desktop, Python, Node.js, Go, WASM (JS-callback shape per Q9), and the MCP `ask` tool.

{sqlrite-0.1.14 → sqlrite-0.1.15}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "maturin"
 
 [project]
 name = "sqlrite"
-version = "0.1.14"
+version = "0.1.15"
 description = "Python bindings for SQLRite — a small, embeddable SQLite clone written in Rust."
 authors = [{ name = "Joao Henrique Machado Silva", email = "joaoh82@gmail.com" }]
 license = { text = "MIT" }

{sqlrite-0.1.14 → sqlrite-0.1.15}/sdk/python/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "sqlrite-python"
-version = "0.1.14"
+version = "0.1.15"
 authors = ["Joao Henrique Machado Silva <joaoh82@gmail.com>"]
 edition = "2024"
 rust-version = "1.85"

{sqlrite-0.1.14 → sqlrite-0.1.15}/src/sql/db/table.rs

@@ -143,6 +143,11 @@ pub struct HnswIndexEntry {
     pub column_name: String,
     /// The graph itself.
     pub index: HnswIndex,
+    /// Phase 7d.3 — true iff a DELETE or UPDATE-on-vector-col has
+    /// invalidated the graph since the last rebuild. INSERT maintains
+    /// the graph incrementally and leaves this false. The next save
+    /// rebuilds dirty indexes from current rows before serializing.
+    pub needs_rebuild: bool,
 }
 
 impl Table {

{sqlrite-0.1.14 → sqlrite-0.1.15}/src/sql/executor.rs

@@ -178,26 +178,6 @@ pub fn execute_delete(stmt: &Statement, db: &mut Database) -> Result<usize> {
     };
     let table_name = extract_single_table_name(tables)?;
 
-    // Phase 7d.2 limitation: HNSW lacks an in-place delete-node operation.
-    // True deletion needs either soft-delete + tombstones or a graph rebuild
-    // — both nontrivial. Until 7d.3 lands persistence we don't have a
-    // natural rebuild trigger either. So: refuse DELETE on tables carrying
-    // any HNSW index, with a message that points at the workaround
-    // (DROP the index, DELETE, recreate).
-    {
-        let table = db.get_table(table_name.clone()).map_err(|_| {
-            SQLRiteError::General(format!("DELETE references unknown table '{table_name}'"))
-        })?;
-        if !table.hnsw_indexes.is_empty() {
-            let names: Vec<&str> = table.hnsw_indexes.iter().map(|e| e.name.as_str()).collect();
-            return Err(SQLRiteError::NotImplemented(format!(
-                "DELETE on tables with HNSW indexes is not supported yet \
-                 (Phase 7d.3 follow-up). DROP the index first, then DELETE, then re-CREATE. \
-                 Table '{table_name}' currently has: {names:?}"
-            )));
-        }
-    }
-
     // Compute matching rowids with an immutable borrow, then mutate.
     let matching: Vec<i64> = {
         let table = db
@@ -224,6 +204,15 @@ pub fn execute_delete(stmt: &Statement, db: &mut Database) -> Result<usize> {
     for rowid in &matching {
         table.delete_row(*rowid);
     }
+    // Phase 7d.3 — any DELETE invalidates every HNSW index on this
+    // table (the deleted node could still appear in other nodes'
+    // neighbor lists, breaking subsequent searches). Mark dirty so
+    // the next save rebuilds from current rows before serializing.
+    if !matching.is_empty() {
+        for entry in &mut table.hnsw_indexes {
+            entry.needs_rebuild = true;
+        }
+    }
     Ok(matching.len())
 }
 
@@ -250,25 +239,6 @@ pub fn execute_update(stmt: &Statement, db: &mut Database) -> Result<usize> {
 
     let table_name = extract_table_name(table)?;
 
-    // Phase 7d.2 limitation (same shape as DELETE above): we have no
-    // in-place UPDATE-an-HNSW-node primitive. UPDATE on a column NOT
-    // covered by HNSW is fine in principle, but the simplest MVP is
-    // refuse-everything-when-HNSW-is-present. Re-evaluate in 7d.3 once
-    // persistence + rebuild is in.
-    {
-        let tbl = db.get_table(table_name.clone()).map_err(|_| {
-            SQLRiteError::General(format!("UPDATE references unknown table '{table_name}'"))
-        })?;
-        if !tbl.hnsw_indexes.is_empty() {
-            let names: Vec<&str> = tbl.hnsw_indexes.iter().map(|e| e.name.as_str()).collect();
-            return Err(SQLRiteError::NotImplemented(format!(
-                "UPDATE on tables with HNSW indexes is not supported yet \
-                 (Phase 7d.3 follow-up). DROP the index first if you need to mutate. \
-                 Table '{table_name}' currently has: {names:?}"
-            )));
-        }
-    }
-
     // Resolve assignment targets to plain column names and verify they exist.
     let mut parsed_assignments: Vec<(String, Expr)> = Vec::with_capacity(assignments.len());
     {
@@ -337,6 +307,24 @@ pub fn execute_update(stmt: &Statement, db: &mut Database) -> Result<usize> {
             tbl.set_value(col, *rowid, v.clone())?;
         }
     }
+
+    // Phase 7d.3 — UPDATE may have changed a vector column that an
+    // HNSW index covers. Mark every covering index dirty so save
+    // rebuilds from current rows. (Updates that only touched
+    // non-vector columns also mark dirty, which is over-conservative
+    // but harmless — the rebuild walks rows anyway, and the cost is
+    // only paid on save.)
+    if !work.is_empty() {
+        let updated_columns: std::collections::HashSet<&str> = work
+            .iter()
+            .flat_map(|(_, values)| values.iter().map(|(c, _)| c.as_str()))
+            .collect();
+        for entry in &mut tbl.hnsw_indexes {
+            if updated_columns.contains(entry.column_name.as_str()) {
+                entry.needs_rebuild = true;
+            }
+        }
+    }
     Ok(work.len())
 }
 
@@ -609,6 +597,8 @@ fn create_hnsw_index(
         name: index_name.to_string(),
         column_name: column_name.to_string(),
         index: idx,
+        // Freshly built — no DELETE/UPDATE has invalidated it yet.
+        needs_rebuild: false,
     });
     Ok(index_name.to_string())
 }

{sqlrite-0.1.14 → sqlrite-0.1.15}/src/sql/hnsw.rs

@@ -202,6 +202,50 @@ impl HnswIndex {
         self.nodes.len()
     }
 
+    /// Phase 7d.3 — produces (node_id, layers) pairs in ascending node_id
+    /// order, suitable for serializing the graph to disk via the
+    /// `HnswNodeCell` wire format. The graph's metadata
+    /// (entry_point + top_layer) is recoverable from the nodes alone:
+    /// top_layer = max(max_layer); entry_point = any node at top_layer.
+    /// So we don't ship a separate metadata cell.
+    pub fn serialize_nodes(&self) -> Vec<(i64, Vec<Vec<i64>>)> {
+        let mut out: Vec<(i64, Vec<Vec<i64>>)> = self
+            .nodes
+            .iter()
+            .map(|(id, n)| (*id, n.layers.clone()))
+            .collect();
+        out.sort_by_key(|(id, _)| *id);
+        out
+    }
+
+    /// Phase 7d.3 — rebuilds an HnswIndex from a stream of (node_id, layers)
+    /// pairs as produced by `serialize_nodes` and round-tripped through
+    /// `HnswNodeCell` encode/decode. The rebuilt index has the same nodes,
+    /// same neighbor lists, same entry_point + top_layer as the source.
+    /// `seed` is fresh; the deserialized index is never inserted into via
+    /// the algorithmic `insert` path so the seed only matters if a caller
+    /// later calls `insert` after deserializing (then it controls layer
+    /// assignment for the appended node).
+    pub fn from_persisted_nodes<I>(distance: DistanceMetric, seed: u64, nodes: I) -> Self
+    where
+        I: IntoIterator<Item = (i64, Vec<Vec<i64>>)>,
+    {
+        let mut idx = Self::new(distance, seed);
+        let mut top_layer = 0usize;
+        let mut entry_point: Option<i64> = None;
+        for (id, layers) in nodes {
+            let max_layer = layers.len().saturating_sub(1);
+            if max_layer > top_layer || entry_point.is_none() {
+                top_layer = max_layer;
+                entry_point = Some(id);
+            }
+            idx.nodes.insert(id, Node { layers });
+        }
+        idx.top_layer = top_layer;
+        idx.entry_point = entry_point;
+        idx
+    }
+
     /// Inserts a node into the graph. The node id must be unique;
     /// re-inserting an existing id is a no-op (returns without error).
     /// `vec` is the new node's vector; `get_vec` looks up the vector

{sqlrite-0.1.14 → sqlrite-0.1.15}/src/sql/mod.rs

@@ -1377,28 +1377,39 @@ mod tests {
         assert!(resp.contains("1 row returned"), "got: {resp}");
     }
 
+    // Phase 7d.3 — DELETE / UPDATE on HNSW-indexed tables now works.
+    // The 7d.2 versions of these tests asserted a refusal; replaced
+    // with assertions that the operation succeeds + the index entry's
+    // needs_rebuild flag flipped so the next save will rebuild.
+
     #[test]
-    fn delete_on_hnsw_indexed_table_errors_with_helpful_message() {
+    fn delete_on_hnsw_indexed_table_succeeds_and_marks_dirty() {
         let mut db = seed_hnsw_table();
         process_command("CREATE INDEX ix_e ON docs USING hnsw (e);", &mut db).unwrap();
-        let err = process_command("DELETE FROM docs WHERE id = 1;", &mut db).unwrap_err();
-        let msg = format!("{err}");
+        let resp = process_command("DELETE FROM docs WHERE id = 1;", &mut db).unwrap();
+        assert!(resp.contains("1 row"), "expected 1 row deleted: {resp}");
+
+        let docs = db.get_table("docs".to_string()).unwrap();
+        let entry = docs.hnsw_indexes.iter().find(|e| e.name == "ix_e").unwrap();
         assert!(
-            msg.to_lowercase().contains("hnsw") && msg.contains("ix_e"),
-            "expected error mentioning HNSW + index name; got: {msg}"
+            entry.needs_rebuild,
+            "DELETE should have marked HNSW index dirty for rebuild on next save"
         );
     }
 
     #[test]
-    fn update_on_hnsw_indexed_table_errors_with_helpful_message() {
+    fn update_on_hnsw_indexed_vector_col_succeeds_and_marks_dirty() {
         let mut db = seed_hnsw_table();
         process_command("CREATE INDEX ix_e ON docs USING hnsw (e);", &mut db).unwrap();
-        let err =
-            process_command("UPDATE docs SET e = [9.0, 9.0] WHERE id = 1;", &mut db).unwrap_err();
-        let msg = format!("{err}");
+        let resp =
+            process_command("UPDATE docs SET e = [9.0, 9.0] WHERE id = 1;", &mut db).unwrap();
+        assert!(resp.contains("1 row"), "expected 1 row updated: {resp}");
+
+        let docs = db.get_table("docs".to_string()).unwrap();
+        let entry = docs.hnsw_indexes.iter().find(|e| e.name == "ix_e").unwrap();
         assert!(
-            msg.to_lowercase().contains("hnsw"),
-            "expected error mentioning HNSW; got: {msg}"
+            entry.needs_rebuild,
+            "UPDATE on the vector column should have marked HNSW index dirty"
         );
     }
 

{sqlrite-0.1.14 → sqlrite-0.1.15}/src/sql/pager/cell.rs

@@ -57,6 +57,21 @@ pub const KIND_LOCAL: u8 = 0x01;
 pub const KIND_OVERFLOW: u8 = 0x02;
 pub const KIND_INTERIOR: u8 = 0x03;
 pub const KIND_INDEX: u8 = 0x04;
+/// Phase 7d.3: a single HNSW node's per-layer neighbor lists,
+/// serialized into one cell. Body layout (after the shared
+/// `cell_length | kind_tag` prefix):
+///
+/// ```text
+///   node_id       zigzag varint   the rowid this graph node represents
+///   max_layer     varint          highest layer this node lives in
+///   for each layer 0..=max_layer:
+///     count       varint          number of neighbors at this layer
+///     for each:   zigzag varint   neighbor node_id
+/// ```
+///
+/// `peek_rowid` works uniformly on this kind because it just reads
+/// the first varint after the kind tag — exactly the `node_id` here.
+pub const KIND_HNSW: u8 = 0x05;
 
 /// Value type tag stored in each non-NULL value block.
 pub mod tag {

sqlrite-0.1.15/src/sql/pager/hnsw_cell.rs

@@ -0,0 +1,258 @@
+//! On-disk format for a single HNSW graph node (Phase 7d.3).
+//!
+//! Each cell carries one node's per-layer neighbor lists. The cells live
+//! on `TableLeaf`-style pages identical to a regular table's data tree —
+//! same slot directory, same sibling `next_page` chain, same interior-
+//! page mechanics from Phase 3d. The only thing different is the per-cell
+//! body, signaled by `KIND_HNSW`.
+//!
+//! Reusing the table-tree shape lets `Cell::peek_rowid` work uniformly
+//! across all cell kinds: it skips `cell_length | kind_tag` and reads the
+//! first varint, which is `node_id` here. So slot-directory binary
+//! search by node_id works without HNSW-specific code in the page-level
+//! plumbing.
+//!
+//! ```text
+//!   cell_length   varint          bytes after this field
+//!   kind_tag      u8 = 0x05       (KIND_HNSW)
+//!   node_id       zigzag varint   the rowid this graph node represents
+//!   max_layer     varint          highest layer this node lives in
+//!   for layer in 0..=max_layer:
+//!     count       varint          number of neighbors at this layer
+//!     for each neighbor:
+//!       neighbor  zigzag varint   neighbor's node_id
+//! ```
+//!
+//! No null bitmap — every field is always present. No type tag — every
+//! field has a fixed type (varint or zigzag varint). The encoding is
+//! deliberately minimal because HNSW indexes can have N nodes each with
+//! up to ~M·log(N) total neighbors, and we don't want the per-cell
+//! overhead to dominate disk usage.
+
+use crate::error::{Result, SQLRiteError};
+use crate::sql::pager::cell::KIND_HNSW;
+use crate::sql::pager::varint;
+
+/// One HNSW node's persisted form. `layers[i]` is the list of neighbor
+/// node_ids at layer i; the node lives at every layer 0..=layers.len()-1.
+#[derive(Debug, Clone, PartialEq)]
+pub struct HnswNodeCell {
+    pub node_id: i64,
+    /// `layers[0]` is the densest layer (always present); `layers.len()`
+    /// equals the node's max_layer + 1.
+    pub layers: Vec<Vec<i64>>,
+}
+
+impl HnswNodeCell {
+    pub fn new(node_id: i64, layers: Vec<Vec<i64>>) -> Self {
+        Self { node_id, layers }
+    }
+
+    /// Encodes the cell into a freshly-allocated `Vec<u8>`. The result
+    /// starts with the shared `cell_length | kind_tag` prefix and is
+    /// directly usable as a slot-directory entry on a `TableLeaf`-style
+    /// page.
+    pub fn encode(&self) -> Result<Vec<u8>> {
+        if self.layers.is_empty() {
+            return Err(SQLRiteError::Internal(format!(
+                "HNSW node {} has zero layers — every node lives at layer 0 minimum",
+                self.node_id
+            )));
+        }
+
+        // Body capacity guess: 1 (kind) + 10 (node_id) + 5 (max_layer)
+        // + per-layer overhead. Most nodes are layer-0-only so the
+        // typical body is ~1 + 10 + 1 + 1 + M·10 ≈ 175 bytes for M=16.
+        let layer_bytes = self.layers.iter().map(|l| 5 + l.len() * 10).sum::<usize>();
+        let mut body = Vec::with_capacity(1 + 10 + 5 + layer_bytes);
+
+        body.push(KIND_HNSW);
+        varint::write_i64(&mut body, self.node_id);
+        // max_layer = layers.len() - 1
+        varint::write_u64(&mut body, (self.layers.len() - 1) as u64);
+        for layer in &self.layers {
+            varint::write_u64(&mut body, layer.len() as u64);
+            for n in layer {
+                varint::write_i64(&mut body, *n);
+            }
+        }
+
+        let mut out = Vec::with_capacity(body.len() + varint::MAX_VARINT_BYTES);
+        varint::write_u64(&mut out, body.len() as u64);
+        out.extend_from_slice(&body);
+        Ok(out)
+    }
+
+    /// Decodes one cell starting at `pos`. Returns the cell plus the
+    /// total bytes consumed (including the leading length varint).
+    pub fn decode(buf: &[u8], pos: usize) -> Result<(HnswNodeCell, usize)> {
+        let (body_len, len_bytes) = varint::read_u64(buf, pos)?;
+        let body_start = pos + len_bytes;
+        let body_end = body_start
+            .checked_add(body_len as usize)
+            .ok_or_else(|| SQLRiteError::Internal("HNSW cell length overflow".to_string()))?;
+        if body_end > buf.len() {
+            return Err(SQLRiteError::Internal(format!(
+                "HNSW cell extends past buffer: needs {body_start}..{body_end}, have {}",
+                buf.len()
+            )));
+        }
+        let body = &buf[body_start..body_end];
+        if body.first().copied() != Some(KIND_HNSW) {
+            return Err(SQLRiteError::Internal(format!(
+                "HnswNodeCell::decode called on non-HNSW entry (kind_tag = {:#x})",
+                body.first().copied().unwrap_or(0)
+            )));
+        }
+
+        let mut cur = 1usize;
+        let (node_id, n) = varint::read_i64(body, cur)?;
+        cur += n;
+        let (max_layer_u64, n) = varint::read_u64(body, cur)?;
+        cur += n;
+
+        let layer_count = (max_layer_u64 as usize)
+            .checked_add(1)
+            .ok_or_else(|| SQLRiteError::Internal("HNSW max_layer overflow".to_string()))?;
+        // Sanity: max_layer is in practice ≤ ~10 for N ≤ 1B with
+        // m_l ≈ 0.36. A wildly-large value almost certainly means a
+        // corrupt cell — bail before allocating an enormous Vec.
+        if layer_count > 64 {
+            return Err(SQLRiteError::Internal(format!(
+                "HNSW node {node_id} claims max_layer {} (>= 64) — corrupt cell?",
+                layer_count - 1
+            )));
+        }
+
+        let mut layers = Vec::with_capacity(layer_count);
+        for _ in 0..layer_count {
+            let (count, n) = varint::read_u64(body, cur)?;
+            cur += n;
+            // Same sanity bound — a single layer's neighbor list shouldn't
+            // exceed `2 · M_max0` even after pruning bugs. 256 is a
+            // generous cap.
+            if count > 256 {
+                return Err(SQLRiteError::Internal(format!(
+                    "HNSW node {node_id} layer claims {count} neighbors (>256) — corrupt cell?"
+                )));
+            }
+            let mut neighbors = Vec::with_capacity(count as usize);
+            for _ in 0..count {
+                let (id, n) = varint::read_i64(body, cur)?;
+                cur += n;
+                neighbors.push(id);
+            }
+            layers.push(neighbors);
+        }
+
+        if cur != body.len() {
+            return Err(SQLRiteError::Internal(format!(
+                "HNSW cell had {} trailing bytes",
+                body.len() - cur
+            )));
+        }
+
+        Ok((
+            HnswNodeCell { node_id, layers },
+            len_bytes + body_len as usize,
+        ))
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn round_trip(cell: &HnswNodeCell) {
+        let bytes = cell.encode().expect("encode");
+        let (decoded, consumed) = HnswNodeCell::decode(&bytes, 0).expect("decode");
+        assert_eq!(
+            consumed,
+            bytes.len(),
+            "decode should consume the whole cell"
+        );
+        assert_eq!(&decoded, cell);
+    }
+
+    #[test]
+    fn single_layer_node_round_trips() {
+        // Most common case: a layer-0-only node with a handful of neighbors.
+        let cell = HnswNodeCell::new(42, vec![vec![1, 2, 3, 5, 8]]);
+        round_trip(&cell);
+    }
+
+    #[test]
+    fn multi_layer_node_round_trips() {
+        let cell = HnswNodeCell::new(
+            17,
+            vec![
+                vec![1, 2, 3, 4, 5, 6, 7, 8], // layer 0 (densest)
+                vec![1, 3, 7],                // layer 1
+                vec![3],                      // layer 2 (sparsest)
+            ],
+        );
+        round_trip(&cell);
+    }
+
+    #[test]
+    fn empty_neighbor_layer_round_trips() {
+        // A node can have an empty layer (e.g. if its only neighbor was
+        // pruned away). The encoding must still survive.
+        let cell = HnswNodeCell::new(5, vec![vec![1, 2], vec![]]);
+        round_trip(&cell);
+    }
+
+    #[test]
+    fn node_id_negative_and_large() {
+        // node_id is zigzag-encoded; cover both signs.
+        round_trip(&HnswNodeCell::new(-1, vec![vec![]]));
+        round_trip(&HnswNodeCell::new(i64::MAX, vec![vec![1, 2]]));
+        round_trip(&HnswNodeCell::new(i64::MIN, vec![vec![3, 4]]));
+    }
+
+    #[test]
+    fn zero_layers_is_rejected_at_encode() {
+        let bad = HnswNodeCell::new(1, vec![]);
+        let err = bad.encode().unwrap_err();
+        assert!(format!("{err}").contains("zero layers"));
+    }
+
+    #[test]
+    fn decode_rejects_wrong_kind_tag() {
+        // Build something that looks like a cell with an arbitrary
+        // (non-HNSW) tag byte and confirm decode bails.
+        let mut bad = Vec::new();
+        varint::write_u64(&mut bad, 1); // body_len
+        bad.push(0x01); // KIND_LOCAL, not KIND_HNSW
+        let err = HnswNodeCell::decode(&bad, 0).unwrap_err();
+        assert!(format!("{err}").contains("non-HNSW entry"));
+    }
+
+    #[test]
+    fn decode_rejects_truncated_buffer() {
+        let cell = HnswNodeCell::new(1, vec![vec![10, 20, 30]]);
+        let bytes = cell.encode().expect("encode");
+        for chop in 1..=3 {
+            let truncated = &bytes[..bytes.len() - chop];
+            assert!(
+                HnswNodeCell::decode(truncated, 0).is_err(),
+                "expected error chopping {chop} byte(s) from end of {} byte cell",
+                bytes.len()
+            );
+        }
+    }
+
+    #[test]
+    fn decode_rejects_implausible_max_layer() {
+        // Hand-craft a cell whose max_layer is 100 (above the 64 sanity bound).
+        let mut body = Vec::new();
+        body.push(KIND_HNSW);
+        varint::write_i64(&mut body, 0); // node_id
+        varint::write_u64(&mut body, 100); // max_layer = 100 → 101 layers
+        let mut out = Vec::new();
+        varint::write_u64(&mut out, body.len() as u64);
+        out.extend_from_slice(&body);
+        let err = HnswNodeCell::decode(&out, 0).unwrap_err();
+        assert!(format!("{err}").to_lowercase().contains("corrupt"));
+    }
+}