fix(graph-node): batchInsert nodes missing from label index

[ruvnet]

Summary

@ruvector/graph-node's batchInsert produced query-invisible nodes: nodes inserted via the fast bulk path were counted in stats() and were traversable by kHopNeighbors, but were not added to the property-graph label index that the only working Cypher pattern (MATCH (n:Label) RETURN n) reads. A user who bulk-loads and then queries by label gets silent empty results — a correctness bug in the fastest ingest path.

Reproduction (before fix)

const { GraphDatabase } = require('@ruvector/graph-node');
const db = new GraphDatabase({ distanceMetric: 'Cosine', dimensions: 4 });
const nodes = [], edges = [];
for (let i = 0; i < 50; i++)
  nodes.push({ id: `p${i}`, embedding: new Float32Array([i,i,i,i]), labels: ['Person'], properties: { name: `n${i}` } });
for (let i = 0; i < 49; i++)
  edges.push({ from: `p${i}`, to: `p${i+1}`, description: 'knows', embedding: new Float32Array([0,0,0,1]) });

await db.batchInsert({ nodes, edges });
console.log((await db.stats()).totalNodes);                 // 50  ✅
console.log((await db.kHopNeighbors('p0', 2)).length);      // 3   ✅
console.log((await db.query('MATCH (n:Person) RETURN n')).nodes.length); // 0  ❌ (expected 50)

stats() and kHopNeighbors see the nodes; the label scan returns 0.

Root cause

In crates/ruvector-graph-node/src/lib.rs:

• create_node inserted into both backing indexes: the hypergraph adjacency/vector index (hg.add_entity, used by kHopNeighbors/stats/searchHyperedges) and the property graph + label index (gdb.create_node, read by the Cypher label scan).
• batch_insert only called hg.add_entity per node — it never called gdb.create_node, and it silently ignored each node's labels/properties.

So the two indexes diverged for bulk-loaded data.

Fix

Extract the shared registration logic into a single register_node helper (single source of truth) that populates the hypergraph index, the property graph + label index, and optional persistent storage. Both create_node and batch_insert now call it, so all read surfaces stay consistent. batch_insert now also honors per-node labels/properties (previously dropped).

Test

Added a Rust regression test (cargo test -p ruvector-graph-node) asserting that nodes registered via the shared path are consistently visible through all three read surfaces — label-scoped scan (get_nodes_by_label), kHop adjacency (k_hop_neighbors), and stats() entity count.

running 3 tests
test transactions::tests::test_transaction_lifecycle ... ok
test transactions::tests::test_transaction_rollback ... ok
test tests::batch_inserted_nodes_are_visible_to_label_scan_khop_and_stats ... ok
test result: ok. 3 passed; 0 failed

Verified end-to-end after rebuilding the NAPI binding (napi build --platform --release): the repro above now returns MATCH (n:Person) = 50, plus a mixed batchInsert + createNode case returns the correct per-label counts, with stats/kHop unchanged.

Out of scope / known issues (filed, not fixed here)

Surfaced by the same benchmarking but deliberately not addressed in this focused fix:

• Inline property filter silently ignored — MATCH (n:Person {name:"Alice"}) returns all Person nodes instead of filtering. The query executor reads only the label, not the inline property map.
• Relationship / path / WHERE / aggregation patterns return empty — e.g. MATCH (a)-[r]->(b) RETURN a,r,b, MATCH (a)-[*1..2]->(b), MATCH (n) WHERE n.name="x", RETURN count(n). The supported Cypher subset is effectively just MATCH (n:Label) RETURN n. This is a larger feature gap, not a one-line correctness fix, and is left as a separate effort.
• Bare MATCH (n) RETURN n (no label) returns 0 — the executor only scans by label.

Provenance

Discovered via agent-harness-generator ruvector benchmarking — see GRAPH-ANALYTICS-PROOF.md §5 (the batchInsert ↔ Cypher consistency bug, proven with a known-answer table). $0 to find and fix (local Rust build + test, no LLM/paid API).

🤖 Generated with claude-flow