---
title: "HeliosDB Nano v3.22 — The Daily-RAG Correctness Wave"
description: "FK validator now reads-its-own-writes inside a transaction (PG-compatible). Cross-process `INSERT … ON CONFLICT` no longer duplicates. MCP `result_cache` stats published in `helios/info` and `GET /mcp/info`. Three fixes that close the daily-workflow silent-fail matrix."
date: 2026-05-12
updated: 2026-05-12
tag: "Release"
canonical: https://www.heliosdb.com/blog/nano-3-22-daily-rag-correctness.html
---

# 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](https://github.com/dimensigon/HDB-HeliosDB-Nano).