---
title: "HeliosDB Nano v3.19.0 Release Notes"
---

# HeliosDB Nano v3.19.0 Release Notes

**Theme:** Backlog sweep #181-#193 + 9 code-graph / graph-rag / MCP follow-ups

> See [v3.19.1](https://www.heliosdb.com/docs/nano/releases/release_notes_v3191/) for the immediate UUID literal coercion fix.

---

## Highlights

v3.19 closes nine of the gaps a downstream client raised against the v3.18 merge plus the residual FR backlog tasks #181-#193. Every change is additive; no public API breakage.

Headline additions:

- **9 new MCP tools** — `helios_lsp_document_symbols`, `helios_lsp_rename_preview`, `helios_lsp_rename_apply`, `helios_graphrag_search`, `helios_lsp_references_diff`, `helios_lsp_body_diff`, `helios_ast_diff`.
- **`ON BRANCH '<name>'`** override on every `lsp_*` table function (combines with `AS OF`).
- **`CREATE SEMANTIC HASH INDEX`** DDL — Merkle-tree subtree invalidation.
- **Centrality-biased + prefilter-aware HNSW** — post-rerank with `(1 - α) × distance - α × centrality`.
- **Streaming `notifications/progress`** for MCP tools (WebSocket + stdio).
- **Docling content-conversion ingestion** — `graph_rag_ingest_pdf / _office / _audio / _image`.
- **`body_vec VECTOR(n)` lazy column** on `_hdb_code_symbols` + new `code-embed` feature using fastembed-rs (BGESmallENV15, 384-dim).
- **`_hdb_code.*` / `_hdb_graph.*` dotted namespacing aliases** at the planner level.

```bash
cargo build --release --features mcp-endpoint,code-graph,graph-rag,code-embed
```

---

## What's New

### Code-Graph / Graph-RAG / MCP Follow-Ups (#1-#9)

| # | Item | Notes |
|---|------|-------|
| 1 | `helios_lsp_document_symbols` | File outline ordered by line, optional kind filter. |
| 2 | `helios_lsp_rename_preview` | Preview-only edit list (definition + every reference site); never writes back. |
| 3 | `helios_graphrag_search` | Wraps `graph_rag::graph_rag_search` as an MCP tool — flagship cross-modal query reachable over JSON-RPC. |
| 4 | `helios_lsp_references_diff` / `_body_diff` / `helios_ast_diff` | Wraps `diff::*` Rust API. Accepts AS OF refs as `{"now": true}`, `{"commit": "sha"}`, `{"timestamp": "iso"}`. |
| 5 | `ON BRANCH '<name>'` per-call override | RAII branch guard restores prior branch on every early-return. Combines with `AS OF` in either order. |
| 6 | `CREATE SEMANTIC HASH INDEX` DDL | Surfaces existing `code_graph::merkle_refresh` Rust primitive at the SQL layer. |
| 7 | `graph_rag_link_vector` | Vector-similar entity-linker stage. Caller-supplied `(node_id, vector)` pairs on both sides; cosine top-k with threshold gating; emits MENTIONS edges with `weight = similarity`. |
| 8 | `tools/list?verbose=true` + `helios/info` JSON-RPC + `GET /mcp/info` HTTP | Single-shot discovery payload (serverInfo + capabilities + verbose tool catalogue + resource list). |
| 9 | Streaming `notifications/progress` events | Tools that call `mcp::progress::emit` produce JSON-RPC notifications when client opted in via `_meta.progressToken`. WebSocket and stdio transports; HTTP POST stays single-shot (paired SSE channel covers it). |

### Backlog Sweep (#181-#193)

| # | Item | Notes |
|---|------|-------|
| 181 | `hdb_code_languages` system view | Exposes `SupportedLanguage::all()` + `parse::registered_grammars()` as a queryable SQL view. Runtime grammars shadowing a static tag report `source = 'runtime'`. |
| 182 | `body_vec VECTOR(n)` column | Materialised on `_hdb_code_symbols` lazily on first non-null embedding. Dimension negotiated at insert time. New `code_index_with_embedder(Box<dyn Embedder>)` entry point. |
| 183 | SymbolExtractor pluggability | Runtime-registered grammars can ship paired extractors via `EmbeddedDatabase::register_extractor`. |
| 184 | HTTP POST + SSE progress pairing | Process-static session table keyed by `Mcp-Session-Id`. POSTs that pair with an open SSE channel get their `notifications/progress` events forwarded to the SSE stream while the POST returns the final `tools/call` response. |
| 185 | `helios_lsp_rename_apply` | Write-back side of the preview tool; identifier-boundary aware, sha256 conflict check, optional `dry_run`. |
| 186 | Docling content-conversion ingestion | `graph_rag_ingest_pdf / _office / _audio / _image` POSTs to docling-serve, parses the DoclingDocument JSON, and projects sections + chunks + tables under `_hdb_graph_nodes` with CONTAINS edges. Idempotent via source_ref keys. |
| 187 | `code-embed` feature | fastembed-rs as the in-process embedder. Default model BGESmallENV15 (384-dim, ~30 MB cache on first run). No on-disk impact on the binary itself. |
| 188 | `_hdb_code.*` / `_hdb_graph.*` namespacing aliases | Planner-level rewrite at `normalize_object_name`; `pg_tables.schemaname` reports the schema split. Catalog keys remain flat (full refactor tracked separately). |
| 189 | Scope-chain resolver via IMPORTS | Unresolved CALLS / REFERENCES refs upgrade to `Exact` when an unambiguous IMPORTS edge in the same file ends in the bare name. Handles Rust `use foo::bar`, Python `from foo import bar`, TypeScript `import { bar } from './foo'`, Go imports. |
| 190 | Centrality-biased + prefilter-aware HNSW | Over-fetches `k * over_fetch_multiplier` candidates, applies row-level prefilter, re-scores with `(1 - α) × distance - α × centrality`. |
| 191 | Acceptance benchmarks | `with_context_bench` (10k-node fixture, 100-query mean ≤ 500 ms) and `linker_precision` (≥ 80 % on a hand-labelled fixture). Current run: mean 62 ms, precision 100 %. |
| 192 | FR-6 pilot deployment | `scripts/install-nano-pilot.sh` + `docs/code_graph/{pilot,troubleshooting}.md`. |
| 193 | Build report | `docs/followups/build-report.md` — all-features release binary metadata (35.0 MiB, sha256 `41176528…`, rustc 1.92.0). |

---

## Ratified Deviations from FR Text

These design choices in v3.15-v3.18 were reviewed by a downstream client; we ratify them as the intended end-state rather than TODOs:

- **Flat-prefix tables (`_hdb_code_*` / `_hdb_graph_*`) instead of dotted schemas (`_hdb_code.*`).** Simpler bootstrap; no catalog refactor required. Promotion to real schema namespacing is a separate engine-wide refactor that benefits `pg_catalog` too — not part of the code-graph track.
- **Cargo features (`code-graph` / `graph-rag` / `mcp-endpoint`) instead of runtime `CREATE EXTENSION`.** Build-time opt-in; no per-process activation step. The static grammar set is fixed at build time, but the runtime grammar registry covers the dynamic plug-in case (caller supplies the loader — wasm runtime, dynamically-linked grammar, etc.).
- **Centrality is a post-rerank weighting, not an HNSW navigation bias** (`src/graph_rag/centrality.rs:10`). Smaller relevance lift, but avoids forking `hnsw_rs`. Descent-bias is a separate phase-3.1 follow-up if the relevance gap turns out to matter in the pilot.

---

## Regression Coverage

- `tests/mcp_followups.rs` — 9 integration tests.
- `tests/mcp_introspection.rs` — 4 introspection tests.
- `tests/code_graph_on_branch.rs` — 2 ON BRANCH integration tests.
- `tests/code_graph_semantic_hash_ddl.rs` — 2 semantic-hash DDL tests.
- `tests/graph_rag_linker_vector.rs` — 4 vector-similar linker tests.
- `tests/mcp_progress.rs` — 4 progress-streaming integration tests (WS round-trip with token, no token, numeric token, scalar-token contract) + 3 lib unit tests.
- `sql_rewrite` — 6 unit tests for `ON BRANCH` parsing + 3 for `detect_create_semantic_hash_index`.

---

## Known Follow-Ups

- **HTTP POST progress** — `POST /mcp` is request/response so streaming requires the paired SSE channel; not yet wired. WebSocket and stdio cover the streaming case today.
- **In-descent HNSW navigation bias** — pending; v3.19 ships post-rerank only.
- **Schema namespacing** — flat prefixes ship; dotted schemas tracked as separate engine-wide refactor.

---

## Migration

No breaking changes. All additions are opt-in via feature flags or new SQL syntax.

---

## Compatibility Matrix

| Component | Version |
|-----------|---------|
| PostgreSQL wire | 14, 15, 16 |
| MySQL wire | 5.7, 8.0 |
| MCP protocol | 1.0 |
| JSON-RPC | 2.0 |
| tree-sitter | 0.23 |
| fastembed-rs (`code-embed`) | latest |