HeliosDB Nano v3.19.0 Release Notes

Release Date: 2026-04-25 Theme: Backlog sweep #181-#193 + 9 code-graph / graph-rag / MCP follow-ups

See v3.19.1 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.

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