HeliosDB Nano v3.15.0 Release Notes

Release Date: 2026-04-24 Theme: Code-graph phase 1 — embedded code-graph for AI coding agents (opt-in, FR 2 MVP)

Highlights

New opt-in feature code-graph turns HeliosDB Nano into an embedded code-graph. Phase 1 ships the foundational Rust API with tree-sitter parsers for Rust and Python and four LSP-style queries: lsp_definition, lsp_references, lsp_call_hierarchy, lsp_hover.

Wire-level DDL (CREATE EXTENSION hdb_code, CREATE AST INDEX) and temporal queries land in v3.16+.

cargo build --release --features code-graph

Default builds pull none of the tree-sitter deps; the default release binary stays the same size.

What’s New

Embedded Code-Graph API

use heliosdb_nano::{EmbeddedDatabase, code_graph::CodeIndexOpts};

let db = EmbeddedDatabase::new("./code.helio")?;

// Source table (path TEXT PK, lang TEXT, content TEXT)
db.execute("CREATE TABLE files (path TEXT PRIMARY KEY, lang TEXT, content TEXT)")?;
// … populate from the filesystem …

// Idempotent indexing
db.code_index(CodeIndexOpts::default())?;

// "Where is parse_query defined?"
let defs = db.lsp_definition("parse_query", None)?;

// "Who calls parse_query?"
let refs = db.lsp_references(symbol_id)?;

// BFS over CALLS edges (incoming, depth 3)
let calls = db.lsp_call_hierarchy(symbol_id, "incoming", 3)?;

// Signature lookup
let sig = db.lsp_hover(symbol_id)?;

Auto-Created Tables

On first code_index call:

_hdb_code_files — one row per source file (path, lang, content_hash).
_hdb_code_symbols — extracted definitions (functions, methods, classes).
_hdb_code_symbol_refs — references with resolution (exact, heuristic, unresolved).

Plain user tables — queryable, joinable, branch-aware.

Pluggable Embedders

src/code_graph/embed.rs:

NoopEmbedder (default) — vectors are empty placeholders.
HttpEmbedder — POSTs {"input": "..."} to an external endpoint, expects {"embedding": [...]}.

Nano ships no inference runtime by design; all inference is external.

Storage-Level Filtering

Every lsp_* query pushes its WHERE through the existing FilteredScan path (src/storage/predicate_pushdown.rs), so bloom-filter / zone-map / SIMD selection applies without new code.

Out of Scope (Tracked for Later Phases)

CREATE EXTENSION hdb_code DDL → v3.16
CREATE AST INDEX DDL → future
Real schema namespacing → v3.19 (alias-level)
Temporal / branch variants → v3.19
Incremental reparse → future
Semantic-Merkle subtree hashes → v3.19 (CREATE SEMANTIC HASH INDEX)
WITH CONTEXT SQL clause → future
Native MCP endpoint → v3.18

Regression Coverage

12 module-level unit tests (parser, symbol extraction, in-file resolver, embedder).
6 integration tests (tests/code_graph_mvp.rs):
- rust_lsp_definition_finds_function
- lsp_references_returns_call_sites
- lsp_call_hierarchy_incoming_terminates
- lsp_hover_returns_signature
- code_index_is_idempotent
- unknown_lang_is_skipped_cleanly

Documentation

docs/code_graph/overview.md — track design and feature flag wiring.
See CODE_GRAPH_TUTORIAL for hands-on usage.

Migration

Additive feature. Default builds compile without it — no breaking changes.

# Default (no code-graph)
cargo build --release

# Opt in
cargo build --release --features code-graph

Compatibility Matrix

Component	Version
PostgreSQL wire	14, 15, 16
MySQL wire	5.7, 8.0
MCP protocol	1.0
tree-sitter	0.23
tree-sitter-rust	0.23
tree-sitter-python	0.23