graph-node: persisted writes invisible to stats()/query() across handles/processes; MATCH without label unimplemented

[anorlandrtc]

Summary

@ruvector/graph-node writes (createNode/createEdge/batchInsert) commit successfully to the redb-backed storage file (isPersistent() is true, the file grows on disk), but nothing that reads the graph afterwards — stats(), query(), kHopNeighbors(), searchHyperedges() — ever sees that data, even from a second handle in the same process, let alone a new process. This makes persistence effectively non-functional for any real (multi-process, or even multi-handle) usage pattern.

Confirmed on both the currently-installed 2.0.3 and the latest published 2.0.4.

Minimal repro

const { GraphDatabase } = require('@ruvector/graph-node');

const g1 = new GraphDatabase({ distanceMetric: 'Cosine', dimensions: 384, storagePath: './test.db' });
const tx = await g1.begin();
await g1.createNode({ id: 'n1', embedding: new Float32Array(384), labels: ['X'], properties: {} });
await g1.commit(tx);
console.log(await g1.stats()); // { totalNodes: 1, ... } -- correct

// Reopen -- same process, new handle:
const g2 = new GraphDatabase({ distanceMetric: 'Cosine', dimensions: 384, storagePath: './test.db' });
console.log(await g2.stats()); // { totalNodes: 0, ... } -- wrong

// Also wrong via the static factory, and in a brand new process:
const g3 = GraphDatabase.open('./test.db');
console.log(await g3.stats()); // { totalNodes: 0, ... } -- wrong

Root cause -- three stacked bugs in crates/ruvector-graph-node/src/lib.rs

1. Constructor never rehydrated from storage. GraphDatabase::new() and ::open() built graph_db via GraphDB::new() (empty in-memory graph) instead of GraphDB::with_storage(path) (see ruvector-graph/src/graph.rs:58, which correctly calls load_from_storage()).

   • Already fixed on main -- commit 31bb94401 ("fix: integrate latest PRs and issue regressions", 2026-08-12) added a hydrate_from_storage() call to both constructors.
   • Not yet published. Latest npm release is 2.0.4, published 2026-05-06 -- three months before that fix landed. npm/packages/graph-node/package.json on main still reads 2.0.4, so there's no released version with this fix yet.

2. Read paths (stats, query, kHopNeighbors, searchHyperedges) all read from self.hypergraph (a CoreHypergraphIndex), a second in-memory index entirely separate from graph_db/storage. It's populated only as a side effect of create_node/create_edge/batch_insert on that exact struct instance, with no persistence of its own. The hydrate_from_storage() fix above now populates it too, so stats() should be correct once that commit is released.

3. query()'s Cypher MATCH handling is still a stub for the label-less case -- confirmed still broken on main as of this writing, independent of Implement Ruvector high-performance vector database #1/Set up Claude Flow swarm initialization #2. In the Statement::Match arm:

   // If no labels specified, return all nodes (simplified)
   if node_pattern.labels.is_empty() && node_pattern.variable.is_some() {
       // This would need iteration over all nodes - for now just stats
   }

   This branch does nothing. There's also no WHERE-clause evaluation anywhere in query(). Since MATCH (n) WHERE n.id = '...' RETURN n (no label filter) is the standard query shape for point lookups and most real usage, query() will keep returning an empty node list for it even after Implement Ruvector high-performance vector database #1/Set up Claude Flow swarm initialization #2 ship -- stats() would report correct counts, but query() results would not.

Ask

• Cut and publish a new @ruvector/graph-node release once the persistence fix (Implement Ruvector high-performance vector database #1/Set up Claude Flow swarm initialization #2, already on main) and a real implementation of label-less MATCH + WHERE filtering (Reorganize repo structure and update documentation #3) are both in.
• No urgency on main-history hygiene, but flagging: consumers of this crate that pin an older commit (we did, ~2,964 commits behind) won't get Implement Ruvector high-performance vector database #1/Set up Claude Flow swarm initialization #2 either without an explicit update.

[ruvnet]

Reviewed against main (c6bb23c84) — all three claims verified, including the release status. Fix in #938.

Claim 1 — hydrate_from_storage() is called at lib.rs:154 (new) and :179 (open), commit 31bb94401 (2026-08-12). npm latest is still 2.0.4 published 2026-05-06, and package.json on main still reads 2.0.4. Unreleased, exactly as you found.

Claim 2 — stats() (:965), search_hyperedges() (:562), k_hop_neighbors() (:592) read only self.hypergraph; hydrate_from_storage populates both indexes, so the fix does close it.

Claim 3 — the stub is still verbatim on main. One refinement worth recording: you note there is "no WHERE-clause evaluation anywhere in query()", which is true of the executor but undersells what exists. The parser fully handles it — MatchClause.where_clause (cypher/ast.rs:38), populated at parser.rs:142-153, with a passing test_parse_match_with_where. The condition arrives at query() attached to the AST and gets dropped. So this was "write an evaluator over an already-parsed tree", not "add WHERE support" — cheaper than it reads.

Four things beyond what you reported

1. query() could never return edges, for any shape. result_edges was declared and never pushed to — including the labelled queries that otherwise worked.
2. querySync() ignored its argument entirely — it never called parse_cypher, returning a hardcoded empty result for every input including its own doc example. No query shape worked, so a label filter wouldn't have saved you there.
3. The package's own smoke test covered the broken path and passed unconditionally. test.js:74 ran await db.query('MATCH (n) RETURN n') — precisely the stubbed shape — then printed ✓ Query executed without asserting anything. That's the mechanism by which this reached 2.0.4.
4. Three exported stream classes are unreachable — QueryResultStream/HyperedgeStream/NodeStream, whose doc examples call db.queryStream() and db.searchHyperedgesStream(). Neither method exists on GraphDatabase, and QueryResultStream::next() is a stub returning Ok(None).

On the Ask

Your ask was to cut a release once #1/#2 and #3 are in. That was blocked by something not recorded on either issue: #826 is a defect in the fix for #1/#2. The synchronous hydrate_from_storage in the NAPI constructor replays the whole store on the Node main thread — ~15s of blocked event loop on the 154k-node graph from #810. Releasing as-asked would have traded "persistence is invisible" for "constructing a handle freezes your process", which is worse for exactly the large-graph users who need persistence.

#938 therefore fixes both, and closes #826 alongside this. Hydration is now lazy and runs once inside spawn_blocking; construction is O(1) again.

Your verbatim repro, re-run against a release build of the branch:

g1.stats()                             { totalNodes: 1, totalEdges: 0, avgDegree: 0 }
g2.stats() (new handle, same process)  { totalNodes: 1, totalEdges: 0, avgDegree: 0 }
g3.stats() (static factory)            { totalNodes: 1, totalEdges: 0, avgDegree: 0 }
g3.query('MATCH (n) RETURN n')         [{"id":"n1","labels":["X"],...}]
g3.query(WHERE n.id = 'n1')            [{"id":"n1","labels":["X"],...}]
new process, GraphDatabase.open()      { totalNodes: 1, totalEdges: 0, avgDegree: 0 }

2.1.0 will be published once #938 lands. Thanks for the writeup — the two-independent-in-memory-indexes diagnosis was the non-obvious part, and checking whether the fix was actually published rather than assuming it saved a wasted release.

One thing deliberately not fixed in #938, filed as #939: the parser binds NOT tighter than comparison, so NOT n.age = 30 parses as (NOT n.age) = 30. That's in the shared parser and affects every consumer, so it gets its own change.