HeliosDB Nano v3.22 — The Daily-RAG Correctness Wave

Three releases in three weeks closed the silent-fail matrix that the field-bench bug report opened in late April. v3.22.1 fixed a phantom FK violation, v3.22.2 fixed cross-process ON CONFLICT, and v3.22.3 shipped the agentic-ops skill catalogue. This post covers v3.22.1 and v3.22.2 in detail — both are correctness fixes that anyone running HeliosDB Nano in a daily-RAG ingestion pipeline should care about.

v3.22.1 — FK validator now reads-its-own-writes

Every code_index call against a populated KB raised fk__hdb_code_symbol_refs_from_symbol___hdb_code_symbols on the second of a DELETE child WHERE …; DELETE parent WHERE …; sequence inside a single transaction. The first DELETE removed every offending child, but the FK validator on the parent DELETE didn't see those tombstones — it called storage.scan_table directly, which reads RocksDB committed state.

Fix: thread the active storage::Transaction through to check_referencing_rows_exist, which now calls txn.merge_with_write_set(table_name, base) on the scan result so in-txn DELETEs and INSERTs are reflected. This matches PostgreSQL's read-your-own-writes semantics for FK validation.

Three new acceptance tests reproduce the field-bench scenarios: ingest_twice_against_populated_kb (SHA gate short-circuits), ingest_twice_with_one_changed_file_against_populated_kb (per-file delete-stale on the changed file — the original failing case), and force_reparse_against_populated_kb. All pass.

v3.22.2 — cross-process INSERT … ON CONFLICT no longer duplicates rows

A second process attaching to a KB written by a prior process and issuing INSERT … ON CONFLICT(col) DO UPDATE silently inserted duplicate rows. Two divergences caused this:

1. EmbeddedDatabase::insert_tuple_versioned_with_schema — the storage primitive used on the main branch and by execute_plan_with_params_inner's INSERT arm — did not call check_unique_constraints. Its SQL fast-path sibling insert_tuple_fast did.
2. execute_plan_with_params_inner's LogicalPlan::Insert arm discarded on_conflict entirely (on_conflict: _).

Fix: add the constraint check to the storage primitive (matching the fast-path twin) and wire on_conflict through the parameterised INSERT path — pre-check uniqueness, route DoNothing to a silent skip and DoUpdate to a UNIQUE-column scan / PK lookup → read existing tuple → resolve EXCLUDED refs and apply assignments via a parameter-aware Evaluator → write back via update_tuple_fast.

v3.22.2 — MCP result_cache stats in helios/info

The MCP discovery payload now includes a cache sub-object covering the engine's MCP result_cache (server-side LRU for read-only tools/call results, 256-entry, 5-minute TTL):

{
  "cache": {
    "size": 42, "capacity": 256, "generation": 7,
    "hits": 1284, "misses": 201, "evictions": 0, "hit_rate": 0.864
  }
}

generation increments on every mutating tool call (which invalidates the cache). hit_rate is 0.0 until the first request, avoiding div-by-zero. Both transports — JSON-RPC helios/info and HTTP GET /mcp/info — surface the same field.

What this means for the daily workflow

Every silent-fail mode the pilot reported is now a green test. ingest_twice short-circuits via the SHA gate, ingest_twice_with_one_changed_file properly deletes stale child rows, force_reparse_against_populated_kb rebuilds without phantom violations, and cross-process UPSERT stops duplicating. If you've been running cargo install heliosdb-nano and seeing intermittent FK errors, this is your upgrade.

HeliosDB Nano is open source under Apache 2.0. Repository: github.com/dimensigon/HDB-HeliosDB-Nano.

← Back to Blog