Skip to content
CAI
Software that uses CAICheck a score

HelixDB/helix-db

55.0

Adequate · 14 November 2026

452.3k

lines of production code

Rust

primary language

5

measurements over time

CAI band scale
CAI trend line
CAI lens gauges

What this system is

Features

Add Go SDK parity fixture generation tool

The Go SDK now includes a command-line tool (\generate-parity-fixtures\) that generates JSON fixtures for testing SDK parity. This tool creates runtime and JSON-only fixtures by marshaling Helix requests and executing them against embedded clients (in-memory or disk-based) to verify consistency, ensuring the Go SDK behaves identically to other SDKs in the ecosystem.

sdks/go/cmd · high confidence

Added AST benchmark library for request parsing and planning metrics

A new benchmarking library has been added to measure native request parsing, memory usage, and throughput. This library exposes helper functions to bind request parameters and construct a planner context, allowing benchmarks to time the same work performed by a native request between transport and the planner.

crates/ast-bench/src · high confidence

Added Cypher scaling benchmarks and queue acceptance verification examples

New example programs have been added to the database crate to support performance validation and release verification. The \cypher\_scaling\ example provides local correctness-checked scaling measurements for Cypher queries, allowing users to benchmark performance across varying graph sizes (defaulting to 64, 512, and 4096 nodes) and output JSON reports on query admission estimates and storage measurements. The \queue\_acceptance\_verify\ example verifies pre-queue release fixtures by ensuring that existing graph data, physical indexes, and search consistency behave correctly after database restarts and queued index operations, printing a JSON report on any mismatches.

crates/db/examples · high confidence

Added Rust SDK compile-tested examples and parity fixtures

New example files have been added to the Rust SDK to demonstrate and validate the \\#\[query\]\ macro usage. \basic\_query.rs\ provides a full end-to-end client interaction example, while \readme\_sdk\_query.rs\ and \readme\_macros\_query.rs\ serve as compile-tested mirrors of the documentation to ensure the public contract (returning \Result\<QueryRequest, QueryError\>\) remains accurate. Additionally, \generate\_parity\_fixtures.rs\ introduces a tool for generating canonical query fixtures to validate cross-language SDK parity.

sdks/rust/examples · high confidence

Added db-testkit examples for launch metrics and planner validation

The db-testkit crate now includes three new example programs to assist with validation and testing workflows. \check\_launch\_metrics\ validates cloud-launch comparison JSON documents against a default replica lag policy. \check\_planner\_corpus\ verifies that generated SDK query fixtures match the expected count and checks them against the normalized planner properties. \check\_planner\_matrix\ runs a sharded validation of the complete normalized planner case matrix, supporting parallel execution via environment variables.

crates/db-testkit/examples · high confidence

Added profile\_stage example for targeted performance profiling

A new example binary, profile\_stage, has been added to the ast-bench crate to allow users to isolate and profile specific front-end stages (parse, plan, or front\_end) against a fixed corpus shape for a specified duration. This tool facilitates sampling profiling by repeating a single stage repeatedly, helping developers identify performance bottlenecks in parsing, planning, or the combined front-end workflow.

crates/ast-bench/examples · high confidence

Architecture-specific SIMD kernels for vector distance calculations

The database now uses optimized SIMD implementations for Euclidean distance and dot product calculations on x86 (SSE, AVX, AVX-FMA) and ARM (NEON) architectures, significantly improving search performance. These hardware-accelerated kernels are automatically selected at runtime based on CPU capabilities, with a fallback to scalar implementations for compatibility. The change includes a new dispatch layer in \crates/db/src/search/vector/spaces\ that routes vector arithmetic to the best available kernel, ensuring correctness through rigorous agreement tests against scalar references across various vector dimensions.

crates/db/src/search/vector/spaces · high confidence

Arena-backed parsing for native requests with pooled memory management

The AST crate now supports parsing native requests into a growable bump arena (\crates/ast/src/arena\), allowing JSON bodies to be deserialized into a tree of references (\ArenaX\ types) that live in a single allocation. This reduces per-node allocation overhead and simplifies memory freeing. The implementation includes a \Pool\ for reusing arena chunks across requests, configurable allocation limits to prevent unbounded memory growth, and a \Map\ type mirroring \BTreeMap\ for sorted, deduplicated object keys. Tests verify that arena parsing produces identical results to owned parsing for all request variants and mutations.

crates/ast/src/arena · high confidence

Asynchronous index publication with backpressure and admission control

Index vector and text writes are now processed asynchronously through a durable queue, decoupling write acceptance from index publication. This introduces admission accounting that charges operations based on their encoded size plus a fixed overhead, enforcing per-index byte and member limits to prevent unbounded memory growth. The system tracks publication lag, handles blocked builds and planning failures by holding back specific entities, and supports configurable storage layouts (row-per-operation or merge-backed map) for the queue.

_crates/db/src/index\lifecycle/queue · high confidence

Cloud CLI now uses WorkOS session authentication and resolves resources by name

The Helix Cloud CLI has been migrated to use WorkOS session-based authentication instead of API keys, requiring an interactive browser login flow (\helix auth login\) to store and manage session credentials. Additionally, Cloud commands no longer require raw resource IDs; users can now resolve workspaces, projects, clusters, and databases by ID, slug, or display name, with fallbacks to linked \helix.toml\ configurations and interactive pickers.

crates/cli/src/commands · high confidence

Deterministic planner scalability and cost-profile experiment fixtures

The planner now includes a comprehensive, deterministic experiment harness in \crates/planner/src/experiments\ for validating query planning behavior without relying on wall-clock benchmarks. This adds a suite of scalability fixtures covering diverse query shapes—such as wide boolean predicates, deep traversal chains, mutation-heavy batches, and ordered range window pushdowns—each with configurable scales and strict metric thresholds for memo groups, rule fires, and alternatives considered. It also introduces cost-profile comparison fixtures that allow running the same queries under different storage-cost assumptions (e.g., expensive range scans or broad equality fallbacks) to detect planning regressions or shifts in cost-based decisions. These changes provide a stable, CI-safe way to ensure planner performance and correctness remain consistent as the system evolves.

crates/planner/src/experiments · high confidence

Go SDK adds embedded client support for Cypher queries and native graph algorithms

The Go SDK now supports running Cypher queries and native graph algorithms (such as Betweenness Centrality and Shortest Path) in embedded mode. This change introduces templates and implementations for a generated embedded client that wraps native bindings via UNIFFI, enabling users to execute Cypher statements, explain query plans without execution, and perform graph traversals directly within the application process. It also includes a parity harness to verify Cypher execution consistency across different runtime phases.

sdks/go/internal · high confidence

HelixDB V3 introduces graph merge operators, probabilistic degree counting, and SIMD-accelerated vector codecs

This release adds core database capabilities for HelixDB V3, including a merge operator for edge adjacency lists that supports delta operations (add/remove edges) to avoid read-modify-write overhead, and a Morris Counter for probabilistic, low-memory degree approximation. It also introduces new vector search infrastructure with SIMD-optimized (NEON/SSE4.1) binary and binary-quantized codecs for efficient similarity filtering via SimHash, alongside the existing f32 unaligned vector support.

(repo-wide) · high confidence

HelixDB v3 server with Cypher support, hybrid disk cache, and mimalloc allocator

The server has been upgraded to HelixDB v3, introducing a new gRPC and HTTP API that supports both standard queries and Cypher graph queries (including an explain endpoint). A new hybrid disk cache is available for S3 storage backends, configurable via environment variables for directory, memory/disk budgets, and warm-start behavior, with startup validation and file descriptor limits raised to support it. The server now uses mimalloc as the global allocator for improved throughput and memory efficiency. A benchmark mode is also available for measuring index operation backlog, publication lag, and storage metrics.

crates/server/src · high confidence

Implement ordered range scanning with bounded reverse iteration and membership verification

The database now supports serving ordered range scans over secondary indexes, including bounded reverse ranges. This change introduces a new \ordered.rs\ module that handles range scan iteration, enforcing membership constraints via bitmap checks and verifying entries against authoritative data to handle stale candidates. It includes logic to resolve tie groups atomically and limits the number of retained entries during reverse scans to prevent excessive memory usage, ensuring that only the necessary result count is kept in memory rather than scanning the entire physical lane. Also in this area: Optimized index source decoding reads only required fields.

_crates/db/src/index\lifecycle/secondary/exact · high confidence

Initial release of the HelixDB TypeScript SDK

The TypeScript SDK is now available as a new package (\@helix-db/helix-db\), providing a query DSL and client for HelixDB that mirrors the Rust SDK's layout. It supports executing queries over HTTP (server mode) or against an embedded database (embedded mode) and exposes structured error handling via \HelixError\ with fields for status codes, error codes, and retryability. The SDK includes graph traversal capabilities via \GraphSelection\ and \NativeGraph\, parameterized query building, and JSON serialization utilities that preserve large integers as \bigint\.

sdks/typescript · high confidence

Introduce ArenaMirror derive for zero-copy AST parsing

The new \ArenaMirror\ procedural macro generates arena-backed mirror types (e.g., \ArenaX\) for existing owned request types. These mirrors replace heap-allocated strings, boxes, vectors, and maps with borrowed references to a \bumpalo::Bump\, enabling zero-copy deserialization of native requests. The generated mirrors implement \ArenaDeserialize\ to accept the same JSON inputs as the owned types and \IntoOwned\ to convert back, ensuring wire-format compatibility while reducing allocation overhead.

crates/ast-arena-derive · high confidence

Introduce Go SDK for HelixDB

Adds the Go SDK (v0.3.1), providing a client for executing graph queries over HTTP or in embedded mode. The SDK includes a DSL for building read and write queries, supports typed parameters, traversal-scoped text and vector search, row bindings, and graph selection. It also exposes structured query errors and handles warm read responses.

sdks/go · high confidence

Introduce Go SDK with DSL and client implementation

Adds the initial Go SDK, providing a client implementation and a Domain Specific Language (DSL) for constructing queries. The DSL includes support for Cypher-style traversals, typed parameter handling (including DateTime and various numeric types), and search consistency options (strong and eventual). This release establishes the foundational API surface for Go developers to interact with the HelixDB database.

github.com/helixdb/helix-db/sdks/go · high confidence

Introduce Helix CLI v3.4.0 with structured error reporting, instance name validation, and local runtime management

The CLI now ships as version 3.4.0 (Docker image v0.0.7) and introduces a new configuration and error-handling foundation. Users benefit from strict instance name validation that rejects path-traversal characters and enforces a 32-character limit with safe ASCII charset, preventing filesystem and container naming collisions. Error reporting is standardized via a structured \CliError\ type that renders user-friendly, cliclack-styled blocks in interactive mode and serializes to JSON in \--json\ mode, including context, hints, and resource candidates. Local runtime management is enhanced with support for both Docker and Podman, automatic daemon startup with bounded timeouts, and a switch to SeaweedFS for disk-backed local storage. The CLI also adds explicit image version selection with SHA-256 digest support and configurable pull policies, along with global flags for JSON output, quiet mode, and verbose timing.

crates/cli/src · high confidence

Introduce HelixDB Embedded runtime bindings for Python and Node.js

Users can now run HelixDB locally within their applications using the new embedded runtime. This change adds native bindings for Python (via \helix-db-embedded\) and Node.js (via \@helix-db/helix-db-embedded\), allowing developers to initialize a client with \Client.embedded()\ for in-memory or disk-backed storage. The package includes prebuilt native wheels for macOS, Linux, and Windows, and ships with smoke tests to verify functionality across these platforms.

bindings · high confidence

Introduce HelixDB Rust SDK v3.0.0 with graph algorithms and index lifecycle management

The Rust SDK has been updated to version 3.0.0, introducing a new \graph\ module that allows users to load an immutable native graph from a Helix instance and run local graph algorithms (such as betweenness, community detection, and traversal) without further server round-trips. The SDK also exposes a comprehensive \lifecycle\ module for managing index operations, providing structured receipts and status tracking for index builds and drops. Additionally, the query DSL has been refactored to construct a nested AST directly, and the \\#\[query\]\ macro now aligns with a strict \Result\ contract for better error handling. Also in this area: 1 commit (0 fixes) modifying sdks/rust; SDK now recognizes Helix Cloud's lowercase write\_outcome\_unknown error; Cypher error codes now use lower snake case; Updated SDK documentation and tests for Cypher explain behavior; Switch JSON serialization to serde\_json for compact float output; and 1 more.

sdks/rust · medium confidence · unverified

Introduce HelixDB UniFFI bindings for multi-language access

This change adds the initial UniFFI bindings for HelixDB, enabling foreign-language SDKs to interact with the database via a stable FFI interface. The bindings expose a portable \HelixDB\ object with constructors for in-memory, local disk, and S3-compatible object storage sources, along with configurable embedded cache profiles (memory-only, memory, or hybrid with disk-backed SlateDB). A dedicated Tokio runtime ensures database futures run safely without stack conflicts on foreign callback threads. Error handling is standardized through a \HelixError\ enum that maps internal Rust errors (config, request, planner, storage, transaction, internal) to a stable vocabulary for callers, and a \NativeGraph\ API provides FFI-safe access to graph topology, node/edge records, and algorithm options.

bindings/uniffi · high confidence

Introduce OpenCypher TCK conformance harness

Added a new Rust-based test harness in tools/opencypher-tck to run the OpenCypher Test Compatibility Kit against the database. The tool loads a pinned, checksum-verified corpus of 3,897 Gherkin scenarios, executes them via a parallel worker architecture, and produces detailed reports on pass/fail/unsupported status. It includes a strict gate mechanism that enforces a reviewed capability manifest, ensuring that excluded scenarios are properly classified and that no regressions occur in previously passing tests.

tools/opencypher-tck · high confidence

Introduce closed production rule inventory for the query planner

The query planner now uses a closed, stable inventory of production rule IDs (\KnownRuleId\) to manage optimization rules. This change introduces a strongly-typed enum for all known rules (such as \FilterPushdown\, \AccessFilterIndex\, and \SeedStreamCardinality\) along with stable string serialization for persistence and debugging. The rules are organized into families (Core, Access, Root, Stream) and include a test to ensure the family slices partition the complete ordered inventory, providing a more robust and verifiable foundation for planner rule application.

crates/planner/src/rules/contracts/known · high confidence

Introduce dedicated Cypher query engine and API

Adds a new Cypher frontend crate that provides a complete implementation of the Cypher query language, including a lexer, parser, and semantic binder that compiles queries into a shared relational plan. This introduces a new HTTP API contract at \/v2/cypher\ and \/v2/cypher/explain\, standardizing error reporting with lower snake case codes and specific HTTP status mappings (e.g., 400 for invalid queries, 429 for resource limits). The change also includes a request model that supports lossless JSON parameter decoding and allows clients to determine query effects (read vs. write) before execution.

crates/cypher/src · high confidence

Introduce demand-driven pull execution regions

The planner now supports a new execution model where pipelines are divided into 'pull regions' that can suspend early once demand is satisfied, rather than always traversing the entire graph. This change introduces \ExecPullCapability\ to classify operations as incremental, prepared, full-input, or boundary, and \ExecProgram::derive\ to group steps into exclusive producer trees. This allows the system to stop pure traversal pipelines when demand is met, improving performance for queries with limit or range constraints.

crates/planner/src/exec/pull · high confidence

Introduce helix-dsl-macros crate with \#\[query\] attribute for type-safe query building

The new \helix-dsl-macros\ crate provides the \\#\[query\]\ procedural macro, allowing users to define typed query-building functions that automatically transform into callable functions returning \Result\<QueryRequest, QueryError\>\. This macro infers whether a query is a read or write operation based on the presence of \read\_batch()\ or \write\_batch()\ calls, handles parameter coercion for supported types (such as \bool\, \i64\, \String\, \Vec\, and nested structures), and ensures type safety by rejecting unsupported function signatures like async functions, generics, or methods with a \self\ receiver. The implementation is accompanied by documentation and compile-tested examples demonstrating usage for both read and write batch operations.

sdks/rust/helix-dsl-macros · high confidence

Introduce native executable plan contracts and DAG validation

The planner now defines strict contracts for executable plans, including exact cardinality counting, native graph access, and deterministic execution ordering. This change introduces a validated executable DAG structure with stable step IDs, explicit scheduling policies (pipeline, barrier, parallel), and rigorous validation for dependency cycles, reachability, and return shapes, ensuring the runtime receives a fully verified execution plan.

crates/planner/src/exec · high confidence

Introduce new physical planner representation types

The physical planner module now defines a comprehensive set of new types to represent query execution plans, including PhysicalAccess, PhysicalAlternative, PhysicalCardinality, PhysicalExpr, PhysicalPipeline, and PhysicalStreamOp. These types formalize how the planner models access paths (such as KV reads, node/edge exact access, range-index scans, and vector/text search), costed alternatives with stable tie-breaking digests, cardinality estimation programs (like bitmap operations and verified range scans), and pipeline structures. This change establishes the structural foundation for the planner's physical layer, enabling more precise cost modeling and deterministic plan selection.

crates/planner/src/physical · high confidence

Introduce range-index bound contracts and proof helpers

The planner now includes a new module for range-index bounds, defining \IndexBound\ (inclusive or exclusive), \IndexBetweenRange\ (paired bounds), and \IndexRange\ (all, lower, upper, or between). These types provide methods to intersect ranges, prove containment of other ranges or secondary literals, and determine tighter bounds, enabling the planner to reason about static range-index constraints at query planning time.

crates/planner/src/ir/index/range · high confidence

Introduce typed IR contracts for non-empty collections and strings

The planner now enforces structural invariants at the type level through new IR contract types. \AtLeast\<T, MIN\>\ guarantees a collection contains at least a specified number of items, preserving this cardinality through operations like \map\ and \sort\_by\_key\, and rejecting deserialization if the count is too low. \ElementIds\ wraps a non-empty list of unique identifiers, providing safe slicing and rejecting duplicates. \NonEmptyString\ ensures planner identifiers are never empty, supporting static and prefixed generation. These types replace unchecked vectors and strings in the intermediate representation, making invalid states unrepresentable and improving safety during plan construction and serialization.

crates/planner/src/ir/contracts · high confidence

Introduce validated stream and search bound contracts in the planner IR

The planner's intermediate representation now includes a new \bounds\ module that enforces strict contracts for stream windows and search result limits. For search operations, \SearchLimitPlan\ ensures result counts are strictly positive integers, rejecting zero or negative literals and preventing static constants from bypassing validation in runtime expressions. For streaming, \StreamBoundPlan\ validates that bounds are non-negative integers, while \StreamRangePlan\ and \StreamDynamicRange\ manage literal and mixed literal/runtime ranges, ensuring start bounds do not exceed end bounds. These changes provide a robust, type-safe foundation for query planning by guaranteeing that bound parameters meet expected shape and value constraints before execution.

crates/planner/src/ir/bounds · high confidence

Introduces HelixDB V3 migration infrastructure for vector index lifecycle

This change adds the \crates/db/src/migrations\ module, establishing the durable migration framework for HelixDB V3. It introduces specific migration jobs to handle the transition of vector indexes, including the materialization of legacy vector properties into the new graph property codec, the adoption of SimHash directories by active legacy vectors, and the bounded retirement of obsolete HNSW physical namespaces. The module also provides a feature-gated scale contract to benchmark these migration phases under production-like resource constraints.

crates/db/src/migrations · high confidence

Introduces HelixDB V3 runtime configuration and tuning subsystem

The database now exposes a comprehensive, validated configuration subsystem for HelixDB V3, allowing users to tune embedded storage, caching, and indexing behavior at runtime. Users can control startup cache warming (blocking, background, or off) and object-store preload levels (L0 or all). The subsystem introduces tuned memory budgets for the SlateDB hybrid cache (block and metadata tiers) and vector search, with defaults that can adapt to the host's physical memory or cgroup limits. Index lifecycle throughput is now configurable, including source-scan prefetching, worker concurrency for secondary, vector, and text tasks, and admission limits for the asynchronous index operation queue (retained bytes, members, and operand size). Additionally, users can define dynamic index properties (secondary, vector, and text), specify edge storage encoding and update policies, and tune durable migration workers (batch size, intervals, and background mode).

crates/db/src/config · high confidence

Introduces V3-to-V4 managed-index migration for equality bitmaps

The database now includes a new migration module that handles the transition of managed-index storage from version 3 to version 4. This change adds a dedicated \equality\_bitmap\ migration path that rebuilds and verifies active equality generations, ensuring the V3 marker remains authoritative during the process. The migration is designed to be restart-safe, deleting V3 rows only after a final marker write confirms publication, and includes failpoint injection for testing specific migration stages.

crates/db/src/migrations/indexes · high confidence

Introduces a tunable, multi-dimensional storage cost model for the query planner

The planner now uses a new \StorageCostProfile\ to estimate query costs based on granular metrics such as object-store latency, bitmap decode work, and CPU evaluation, replacing the previous implicit assumptions. This profile is fully tunable via JSON overrides, allowing operators to adjust defaults for range scans, equality lookups, and parallel KV reads to better match their specific storage infrastructure and workload characteristics.

crates/planner/src/cost · high confidence

Introduces native executable operation definitions for the query planner

The planner now defines a comprehensive set of native executable operations (ExecOp) and their supporting structures, including control flow (branching, repeating, merging), mutations (adding/removing nodes and edges), and data access (index membership, vector/text search, KV reads). This change establishes the concrete execution plan format that the interpreter will consume, replacing previous abstractions with explicit, serializable step definitions for conditions, variable operations, and DAG scheduling.

crates/planner/src/exec/op · high confidence

Introduction of a supervised background migration worker

A new background migration worker has been added to handle durable, asynchronous database migrations. This component runs as a supervised loop that processes migration batches with configurable active and idle intervals, implementing exponential backoff with a 60-second cap for transient failures. The worker can be enabled or disabled via configuration and ensures clean shutdown by joining the task before storage closes, improving reliability for long-running migration tasks.

crates/db/src/migrations/background · high confidence

Introduction of v2 property index management module

The \crates/db/src/search\ module has been added to manage secondary indexes for property-based queries, including equality, range, vector (ANN), and text (BM25) indexes. This module implements deterministic naming for indexes and their multitenant partitions, and integrates with the v2 encoding layer for persistence, replacing legacy text metadata handling with the new v2 key/value structures.

crates/db/src/search · high confidence

Native executable planning and control-flow validation

The planner now builds executable plans directly from the native AST, bypassing the previous compatibility physical tree. This introduces a new \PlanEnvelope\ that validates read/write batch contracts, return variables, and traces native handoff events. Control-flow operations (union, choose, coalesce, optional, repeat) are now validated for arity and emit/stop invariants before execution. Index DDL (create/drop) for secondary and search indexes is validated with strict separation of create-time attributes and drop-time identity fields, ensuring that invalid configurations are caught early.

crates/planner/src/planning · high confidence

New Cascades memo system for query planning

The planner now includes a new memo system (crates/planner/src/memo) that manages logical expression equivalence groups. This system introduces stable, non-zero IDs for memo groups and expressions, validates child-group arity during insertion, and computes stable identity digests to detect equivalent expressions. It also provides a mutable container with serialization support that validates record integrity and rebuilds lookup indexes on deserialization.

crates/planner/src/memo · high confidence

New Cypher execution interpreter with native access and expansion operators

The database engine now uses a new execution interpreter in \crates/db/src/execution/interpreter/access\ to handle Cypher query execution. This change introduces native modules for graph expansion (\expand.rs\, \edge\_candidates.rs\), index lookups (\indexes.rs\), key-value reads (\kv.rs\), and runtime membership resolution (\membership.rs\, \params.rs\). Users will see these changes as the underlying mechanism for how queries are executed, enabling features like exact count programs, vector and text search integration, and improved memory management through bounded execution and streaming.

crates/db/src/execution · high confidence

New Cypher query support and concurrent batch read performance

The database now supports the Cypher query language, exposing endpoints to execute queries and explain plans, with responses prepared as JSON before write commits. For read performance, batch point reads now run concurrently when a block cache is present, overlapping cold block fetches to reduce latency for random access patterns. Additionally, a new allocation testing module is available to observe memory usage during tests. Also in this area: 2 commits (0 fixes) modifying crates/db, crates/server.

crates/db/src, crates/db/src/cypher/tests · medium confidence

New HNSW vector index implementation with restricted search and adaptive filtering

The vector search subsystem now uses a new HNSW-based index implementation located in \crates/db/src/search/vector/hnsw\. This change introduces a complete rewrite of the vector index façade, graph mutation, and search algorithms, including support for restricted (filtered) vector search with exact-scan and bounded graph-traversal strategies. It adds adaptive SimHash filtering and sampling policies for cosine metrics, deterministic randomness for reproducible searches, and optimized neighbor set management with degree limits. The new index also includes scale-contract tests for recall and throughput validation at 10k and 100k vector sizes, and integrates with the SlateDB block cache for batched vector row reads. Also in this area: Optimized HNSW mutation performance via scratch buffer reuse and allocation-free differencing; Vectorized cosine norm and sum-of-squares kernels with strict bit-identical guarantees.

crates/db/src/search/vector/hnsw · high confidence

New IR access plan contracts for nodes and edges

The planner now defines explicit Intermediate Representation (IR) contracts for node and edge access plans, introducing structured types like \NodeAccessPlan\ and \EdgeAccessPlan\. These types formalize access strategies including point lookups, label scans, equality and range index scans, vector/text search, and set operations (intersection/union). The change introduces \BranchResidualUnion\ to handle index-only set unions with per-branch residual filtering, and \RangeScanIteration\ to manage physical traversal direction independently of index storage order. Additionally, \NodeAccessSourcePlan\ and \EdgeAccessSourcePlan\ enforce contracts that exclude filtered scans from being used as primary sources, ensuring cleaner separation between candidate retrieval and residual filtering.

crates/planner/src/ir/access · high confidence

New IR types for secondary equality and search index planning

The planner now includes new intermediate representation (IR) types to support secondary equality lookups and text/vector search indexing. \SecondaryIndexLiteral\ and \EqualityIndexValueSemantics\ define how literal values are validated and classified for equality indexes, including handling of nulls, NaNs, and size limits. Additionally, \RestrictedTextSearchPlan\ and \RestrictedVectorSearchPlan\ model the execution plans for BM25 text search and vector similarity search, supporting both node and edge indexes with optional tenant scoping.

crates/planner/src/ir/index · high confidence

New Python scripts for index benchmarking and Cargo validation

Added \scripts/async-index-benchmark/replay.py\ to replay fixed HTTP traces for measuring index operation outcomes (writes, strong reads, eventual reads) without retry loops, and \scripts/validate-cargo-target-references.py\ to validate Cargo package and target references in repository automation. These tools support performance testing and build integrity checks.

python · high confidence

New V2 full-text search implementation with split-aware caching and compaction

The full-text search subsystem has been replaced with a new V2 implementation that constructs immutable, content-addressed text splits and manages them through a bounded, split-aware cache. This change introduces a hybrid caching architecture (memory plus local disk) that supports hot directories for fast access and range-cached storage for on-demand retrieval. It also adds a bounded compaction pipeline that merges text splits while enforcing strict limits on fan-in, input size, and temporary disk usage, ensuring that split sizes never exceed the disk tier budget. The new system includes robust lifecycle management for split hydration, including proper cleanup of staging files and lease validation, and supports restricted text search with collector-based prefiltering. Also in this area: Optimized BM25 live state resolution for text search; Search performance and reliability improvements for pending text and vector work.

crates/db/src/search/text · high confidence

The scoped search benchmark now includes a batch-write mode that measures performance under concurrent write and filter workloads. This new capability allows users to run \batch-load\ and \batch-run\ modes to evaluate how the system handles indexed property updates, edge creation, and filtering in bulk, providing insights into write-throughput and index consistency under load.

_crates/db/examples/scoped\_search\bench · high confidence

New core optimizer rules and physical access contracts

The planner now includes a new set of core optimizer rules and physical access contracts. Logical exploration rules (FilterPushdown, FilterMerge, PurePipelineSimplification, StaticPredicateSimplification) rewrite the logical plan before physical implementation. Implementation rules (Barrier, Filter, Order, Pipeline, SimplifiedPredicate, SourceAccess, VariableSource) seed physical alternatives with costs and delivered properties. The physical\_contracts/access module provides detailed contracts for node and edge access paths, including KV reads (point, multi-get, range), set operations (intersection, union), and pipeline operations (filter, order, distinct, window). This enables more accurate cost estimation and physical plan selection for graph traversal queries.

_crates/planner/src/rules/physical\contracts · high confidence

New graph-algorithms crate with deterministic centrality, cycle, layout, and community detection

The \crates/graph-algorithms\ crate introduces a suite of deterministic graph algorithms. Betweenness centrality now supports exact, sampled, and auto modes, and correctly counts parallel edges only once in path calculations. Cycle enumeration includes a \truncated\ flag to indicate when results were cut off by limits. The Louvain and Leiden community detection algorithms are implemented with deterministic seeding and modularity validation. Additionally, a deterministic Fruchterman-Reingold spring layout and configurable graph traversals (BFS/DFS with hub suppression) are provided, accompanied by benchmarks and test fixtures for validation.

crates/graph-algorithms · high confidence

New optimizer result selection API and typed error handling

The planner now exposes a structured API for selecting the best physical plan from optimization results. Users can start a reusable \SelectionSession\ to recursively resolve the cheapest physical alternative for a memo group, optionally filtering by required properties. The system returns typed \SelectionError\ details (such as missing groups, unsatisfied properties, or recursive cycles) and provides a \RootSelectionSummary\ that clearly distinguishes between complete selections and partial failures, ensuring callers can detect when a full executable plan could not be assembled.

crates/planner/src/optimizer/result · high confidence

New planner diagnostics for query performance insights

The planner now exposes structured diagnostics for selected execution plans, providing users with actionable insights and detailed statistics. This includes recommendations for missing secondary indexes (equality or range), warnings about unbounded graph scans, and alerts for deep traversals that may amplify work. Additionally, it reports comprehensive statistics on operator counts, optimization effort, and access methods used, enabling users to understand and optimize query performance.

crates/planner/src/diagnostics · high confidence

New root-level optimizer rules for barriers, control flow, and stream access

The planner now includes a new set of optimizer rules in the \root\ module to handle specific executable contract surfaces. \RootMutationImplementationRule\ and \RootIndexDdlImplementationRule\ translate logical mutation and index DDL operations into physical barrier executions. Control-flow operations like \RootBranch\ and \RootRepeat\ are implemented with barrier effects, and a new \RootControlFlowEmptyRule\ optimizes away branches or repeats that have statically empty inputs. Stream pipelines are handled by \RootPipelineImplementationRule\, while \RootStreamAccessRewriteRule\ pushes access-filter and ordering rewrites through root stream wrappers (such as \StreamProject\, \StreamAggregate\, and \StreamCardinality\) to preserve wrapper payloads during optimization.

crates/planner/src/rules/root · high confidence

New secondary index primitives and metrics for equality and range scans

This change introduces the core execution primitives for secondary index lookups in the database layer. It adds exact equality point and batch reads (including unique and legacy-compatibility handling) and ordered range scans with support for forward/reverse iteration, runtime limits, and stale tie recovery. A new metrics subsystem tracks point reads, multi-get calls, scans, and graph reads with task-local scoping to ensure isolation across parallel tests and spawned workers. Comprehensive tests validate these behaviors, including dynamic equality admission, null/unencodable value handling, and reverse-range ordering.

_crates/db/src/index\lifecycle/secondary · high confidence

New typed catalog model for planner indexes

The planner now uses a new, strongly-typed catalog module to manage index metadata. This introduces distinct types for node and edge equality/range indexes, as well as vector and text search indexes, each with their own keys and metadata structures. The catalog snapshot supports tenant scoping for search indexes and ensures data integrity by rejecting empty identifiers and duplicate keys during deserialization.

crates/planner/src/catalog · high confidence

New vector distance kernels and semantic bindings

The database now supports additional vector distance metrics for similarity search. In addition to the existing Cosine, Euclidean, and Manhattan distances, the system introduces Binary Quantized Cosine, Binary Quantized Euclidean, Binary Quantized Manhattan, and Hamming distance kernels. These new metrics allow for more efficient storage and retrieval of binary-quantized vectors. The Cosine distance implementation has also been updated with a numerically stable, vectorized norm calculation to improve performance and accuracy. All new and existing distance kernels are now bound to stable, durable semantic identities, ensuring consistent behavior across storage and retrieval operations.

crates/db/src/search/vector/distance · high confidence

Python SDK gains Cypher support, asynchronous client, and parity testing infrastructure

The Python SDK now supports the Cypher query language via new \cypher\ and \explain\_cypher\ methods on both the synchronous and asynchronous clients, handling warm 204 responses as successful executions. An asynchronous client (\AsyncClient\) has been added alongside the existing synchronous \Client\, enabling non-blocking database interactions. To ensure consistency across SDKs, a new parity testing harness has been introduced, including scripts to generate and run query fixtures against the server. Additionally, the SDK now exposes structured query errors, validates signed 64-bit integers and RFC3339 timestamps more strictly, and preserves static query error codes for better debugging.

helix-db · high confidence

Python SDK now supports asynchronous queries and structured error codes

The Python SDK introduces an asynchronous client (AsyncClient) built on HTTPX, allowing users to execute concurrent queries and manage connection pools with configurable limits and timeouts. The synchronous API remains unchanged. Additionally, the SDK now exposes structured query errors via HelixError.code, providing static server or embedded error codes separate from human-readable details, and aligns the package license to Apache-2.0.

sdks/python · high confidence

Vector search cache now resident on reader nodes with commit-fenced consistency

Reader nodes now maintain a resident memory cache for vector search rows (SimHash, upper vectors, and upper neighbors), significantly reducing storage fetches for repeated searches. The cache is hydrated from the object store with a configurable memory budget and is kept consistent with writer commits through a commit-fencing mechanism that evicts stale rows when writes occur. Reader cache refreshes are automatically paced and back off when the reader node applies new state faster than the cache can reload, ensuring the cache never serves data older than the reader's current snapshot. Also in this area: Vector memory cache now uses slab-based storage with exact byte accounting.

crates/db/src/search/vector/cache · high confidence

Architecture

Introduce selected executable IR contracts for query planning

The planner now defines a new selected executable intermediate representation (IR) in \crates/planner/src/exec/selected\ to bridge the optimizer and the execution engine. This change introduces strict type-safe contracts for root nodes (including control flow like branches and repeats, exact cardinality counting, and index DDL barriers), batch execution entries, and logical/physical alternative classification. By enforcing these contracts at the selection boundary, the system prevents physically impossible plans from reaching the executable lowering phase, ensuring that only valid, classified logical-physical pairs are converted into executable DAG steps.

crates/planner/src/exec/selected · high confidence

New logical algebra and memoization structure for the query planner

The planner now uses a new core logical expression model that separates pure, side-effect-free operations (such as filters, projections, and aggregations) from barrier operations that enforce execution order or side effects (like mutations and index DDL). This structure defines how logical nodes are grouped into memo children, ensuring that parent-local payloads (like access paths) remain embedded while recursive inputs are selected as independent memo groups for optimization.

_crates/planner/src/logical/core, crates/planner/src/logical/memo\children · high confidence

Planner refactored into a modular, contract-based architecture

The planner has been restructured into a modular, contract-based architecture to improve stability and testability. This change introduces a stable facade for predicate analysis (\analysis.rs\) that exposes pure proof functions for tautology checks and index-atom candidates, and a dedicated context module (\context.rs\) that isolates request parameters, limits, and statistics. It also establishes a strict interpreter-facing contract boundary for executable plans (\exec/plan/\) that validates DAG shapes before exposing them, and introduces a new \digest.rs\ module for deterministic, stable hashing of planner values to ensure consistent optimizer behavior across runs.

crates/planner/src · high confidence

Refactored execution plan lowering into modular sub-components

The planner's execution plan lowering logic has been reorganized into dedicated modules to improve separation of concerns and testability. New files in \crates/planner/src/exec/lowering\ introduce \access\_leaf\ for handling simple node and edge access conversions, \conditions\ for translating batch run conditions, \contracts\ for inferring executable stream properties, \costing\ for storage-profile-based cost accounting, and \secondary\_set\ for pure secondary-index access lowering. This structural change isolates specific lowering responsibilities, allowing the allocation kernel to focus on DAG construction while keeping access shape matching, cost calculation, and property inference independently testable.

crates/planner/src/exec/lowering · high confidence

Structured rule applicability contracts for the query planner

The planner now uses a dedicated applicability module to define and enforce which optimizer rules can apply to specific logical expression shapes. This change introduces canonical kind-set wrappers (for logical expressions, pure operations, stream pipeline operators, and access sources) and a unified matching engine that checks rule metadata against the current plan. By separating candidate predicate helpers from rule implementations, the system ensures that rule applicability is determined consistently during schedule compilation and runtime, preventing rules from firing on incompatible expression types.

crates/planner/src/rules/contracts/applicability · high confidence

Behavioural changes

10 commits (1 fix) modifying crates/db/src/index\_lifecycle\_testing/contracts

A change to existing behaviour in crates/db/src/index\_lifecycle\_testing/contracts — 10 commits (1 fix), 3 files: “Track explicit sustained-write activation with a flag”; “Broaden all-index convergence regressions”; “Prove secondary builds activate under sustained public write batches”; and 7 more.

_crates/db/src/index\_lifecycle\testing/contracts · medium confidence · unverified

142 commits (29 fixes) modifying crates/db/src/index\_lifecycle

A change to existing behaviour in crates/db/src/index\_lifecycle — 142 commits (29 fixs), 20 files: “Keep both owners of a scanned duplicate in the step's read set”; “Apply Cypher property maps in one admitted transition \[skip ci\]”; “fix(db): bind equality reads to transaction catalog”; and 139 more (refs \#1239, \#1297).

_crates/db/src/index\lifecycle · medium confidence · unverified

2 commits (0 fixes) modifying crates/db/src/search/vector/unaligned\_vector, crates/planner/src/trace

A change to existing behaviour in crates/db/src/search/vector/unaligned\_vector, crates/planner/src/trace — 2 commits, 15 files: “test: delete trivial tests of derives, accessors, constants and std”; “HelixDB V3”.

_crates/db/src/search/vector/unaligned\vector, crates/planner/src/trace · medium confidence · unverified

23 commits (2 fixes) modifying crates/db/src/index\_lifecycle\_testing

A change to existing behaviour in crates/db/src/index\_lifecycle\_testing — 23 commits (2 fixs), 2 files: “Expect write-time unique rejection at the activation boundary in the lifecycle contract”; “Fix merged lifecycle fixtures and tied calibration comparisons”; “test(db): run lifecycle, queue, secondary, and text contracts as unit tests”; and 20 more (refs \#1297).

_crates/db/src/index\_lifecycle\testing · medium confidence · unverified

30 commits (3 fixes) modifying crates/db/src/search/vector

A change to existing behaviour in crates/db/src/search/vector — 30 commits (3 fixs), 11 files: “perf(db): overlap the cold block fetches of every batch point read”; “perf(db): abandon and back off reader vector refreshes the reader outruns”; “Score vector publication's beam distances beside the planner”; and 27 more.

crates/db/src/search/vector · medium confidence · unverified

38 commits (3 fixes) modifying crates/db/src/search/vector/hnsw/mutation

A change to existing behaviour in crates/db/src/search/vector/hnsw/mutation — 38 commits (3 fixs), 6 files: “Describe the cosine golden digests against main's vectorised norm”; “Score vector publication's beam distances beside the planner”; “perf(db): batch HNSW mutation item loads and target cache invalidation”; and 35 more.

crates/db/src/search/vector/hnsw/mutation · medium confidence · unverified

4 commits (0 fixes) modifying crates/db/src/index\_lifecycle/graph\_mutation

A change to existing behaviour in crates/db/src/index\_lifecycle/graph\_mutation — 4 commits, 3 files: “Apply Cypher property maps in one admitted transition \[skip ci\]”; “Batch Cypher CREATE and SET across rows and keys”; “Admit property rewrites and pending Cypher write buffers \[skip ci\]”; and 1 more.

_crates/db/src/index\_lifecycle/graph\mutation · medium confidence · unverified

4 commits (0 fixes) modifying crates/db/src/search/vector/simhash

A change to existing behaviour in crates/db/src/search/vector/simhash — 4 commits, 2 files: “Stage membership merges without reading the stored row (\#1239)”; “test(db): run vector search contracts as unit tests”; “refactor(vector): group cache and support modules”; and 1 more (refs \#1239).

crates/db/src/search/vector/simhash · medium confidence · unverified

5 commits (1 fix) modifying crates/metrics

A change to existing behaviour in crates/metrics — 5 commits (1 fix), 9 files: “Attribute OSS telemetry and count every query”; “Fix the transport test's RequestContext path”; “Report the caller's user agent and honour DO\_NOT\_TRACK”; and 2 more.

crates/metrics · medium confidence · unverified

6 commits (0 fixes) modifying crates/db/src/search/vector/benchmarks

A change to existing behaviour in crates/db/src/search/vector/benchmarks — 6 commits, 3 files: “test(db): run vector search contracts as unit tests”; “feat(db): index vector and text writes asynchronously through the queue”; “refactor(vector): group HNSW runtime modules”; and 3 more.

crates/db/src/search/vector/benchmarks · medium confidence · unverified

6 commits (1 fix) modifying crates/server

A change to existing behaviour in crates/server — 6 commits (1 fix), 2 files: “docs(errors): publish query error code reference”; “feat: add helix doctor and GET /v2/diagnostics (\#1183)”; “ci: remove the line-fingerprint coverage gates”; and 3 more (refs \#1183).

crates/server · medium confidence · unverified

60 commits (21 fixes) modifying docker-image

A change to existing behaviour in docker-image — 60 commits (21 fixs), 4 files: “docs: document the always-on S3 disk cache”; “fix(server): cache only SSTs read back when data lives in HELIX\_DATA\_DIR”; “Verify idle vector refresh against MinIO and preserve coverage references”; and 44 more (refs \#1183, \#1254).

docker-image · medium confidence · unverified

7 commits (2 fixes) modifying scripts

A change to existing behaviour in scripts — 7 commits (2 fixs), 5 files: “docs(bench): distinguish costed planner io”; “bench(planner): compare v2 plan quality”; “test: add queue image contracts, acceptance verifier, and benchmark harness”; and 4 more.

scripts · medium confidence · unverified

8 commits (2 fixes) modifying crates/db-testkit/src

A change to existing behaviour in crates/db-testkit/src — 8 commits (2 fixs), 13 files: “perf(planner): share request parameters instead of copying them per expression”; “test: delete dead and never-compiled test code”; “fix(planner): replace the wall-clock exploration budget with a rule-fire budget”; and 5 more.

crates/db-testkit/src · medium confidence · unverified

Benchmark support now reports SIMD paths and uses a scoped bump allocator for planning benchmarks

The benchmark support module now prints the runtime SIMD algorithm detected by simd-json (removing the previous compile-time sonic-rs path reporting) and hardcodes the allocator as mimalloc. Additionally, a new scoped bump allocator is introduced for planning benchmarks, allowing allocations within a scope to be served from a thread-local bump region for faster, zero-cost freeing, while falling back to mimalloc for allocations outside the scope or those that do not fit.

crates/ast-bench/benches/support · high confidence

CLI v3.4.0 release with image selection, disk storage migration, and installer improvements

The Helix CLI (v3.4.0) introduces explicit image version selection and pull policies via \--image-version\ and \--pull\ flags, allowing users to pin specific tags or digests and control caching behavior. Local disk mode now uses SeaweedFS instead of the withdrawn MinIO images, with automatic cleanup of legacy MinIO sidecars during start, stop, and prune operations. The CLI also adds a \chef\ command for interactive AI-assisted project bootstrapping, supports WorkOS session-based Cloud authentication, and includes improved idempotency in the PowerShell installer to prevent duplicate PATH entries. Also in this area: 3 commits (0 fixes) modifying crates/cli; 1 commit (0 fixes) modifying crates/cli; CLI adds a 'doctor' command for read-only setup diagnostics; Default local server image updated to v0.0.12; New \helix explorer\ command and updated local instance image.

crates/cli · medium confidence · unverified

Consolidated startup migration pipeline for managed writer initialization

The database startup process now uses a unified migration pipeline to handle managed writer initialization and tenant key migrations. This change introduces a structured bootstrap flow that validates storage versions, migrates legacy tenant keys, and ensures index storage metadata is consistent before the writer runtime is constructed. Users benefit from more robust handling of partial bootstraps and legacy data, reducing the risk of startup failures due to inconsistent storage states.

crates/db/src/migrations/startup · high confidence

Exact numeric value semantics moved to shared crate and exposed publicly

The exact numeric value semantics previously located in the database encoding layer have been moved to a new shared crate, \crates/value-semantics\. This change makes the \CanonicalNumber\ type and its \CanonicalFinite\ representation public, allowing the planner and database to share a common, exact mathematical normalization for numeric property values. The module no longer depends on the database's internal \PropertyValue\ enum, instead accepting primitive numeric types (\i64\, \f32\, \f64\) directly, which decouples the value semantics from specific storage or AST representations.

crates/value-semantics · high confidence

Executable plan validation and execution ordering

The planner now validates executable plans before execution by checking for duplicate step IDs, dependency cycles, unreachable steps, and specific contract violations (such as invalid access orderings, count program dependencies, and parallel step requirements). It also derives a deterministic execution order using a non-recursive, stack-based graph traversal to handle long dependency chains without stack overflow, ensuring that steps are executed in valid stages while respecting parallelism and barrier constraints.

crates/planner/src/exec/validation · high confidence

HelixDB V3 introduces a new executable IR contract

HelixDB V3 replaces the previous planner intermediate representation with a new, explicitly typed executable IR located in \crates/planner/src/ir\. This new contract defines the specific data structures for physical operations, including node and edge access, graph expansion, filtering, ordering, and mutations. It introduces dedicated plan types for control flow (branching and repeating), batch execution (with variable conditions and output binding), and index DDL (handling creation, dropping, and operation status). The new IR also formalizes constraints for property assignments, projection items, and shortest-path traversals, ensuring that the planner's output is strictly validated before execution.

crates/planner/src/ir · high confidence

Introduce HelixDB V3 query AST with native request parsing and stable error codes

The \crates/ast\ crate has been replaced with a new V3 query AST that defines the public JSON contract for SDKs and the planner. This change introduces a new wire format for read and write batches (including \for\_each\ loops and conditional entries), a comprehensive set of stable machine-readable \QueryErrorCode\ values for error handling, and native request parsing that uses a growable bump arena to reduce memory allocations. Additionally, the new AST includes iterative nesting bounds to prevent stack overflows during planning and execution, and supports new index specifications for vector and text search.

crates/ast/src · high confidence

Introduce bounded aggregation and memory-aware planning infrastructure

The planner now enforces strict memory budgets during query execution by introducing an \Accumulator\ for aggregation state that validates and admits memory usage before mutation, preventing unbounded growth. A new \Average\ implementation preserves exact integer totals using i128 arithmetic to avoid floating-point rounding errors during averaging, while a shared \allocation\ module provides precise byte-counting models for B-trees and hash tables to support these budget checks. Additionally, the planner now derives and validates physical operator contracts—including row schemas, correlation, and multiplicity—and prepares batch consumers with cursor proofs to ensure that streaming pipelines respect proven window boundaries and do not over-fetch data.

crates/planner/src/relational · high confidence

Introduce logical root contracts for query planning

The planner now uses a new set of logical root contracts (RootStream, RootPipeline, RootMutation, RootBranch, RootRepeat, RootShortestPath, and various terminals) to represent query roots and their executable payloads. This replaces the previous reliance on compatibility physical subtrees for these root-level operations, allowing the logical planner to preserve and lower mutation, DDL, and control-flow payloads directly. Additionally, the new StreamCardinality terminal shares request parameter bindings across expressions rather than copying them, which reduces memory overhead during planning for parameter-heavy requests.

crates/planner/src/logical/root · high confidence

Introduces V2 storage encoding with deprecated V1 compatibility layer

The database now uses a new V2 encoding format for all graph data keys, values, and indexes, replacing the previous V1 scheme. This change introduces a comprehensive set of typed key structures (for nodes, edges, properties, and various index types) and a new error handling module for encoding operations. To ensure backward compatibility and support migration, the old V1 encoding paths are retained but marked as deprecated, automatically re-exporting their functionality from the new V2 modules. Users will benefit from a more robust and structured internal storage format, while existing data remains accessible through the compatibility layer.

crates/db/src/encoding · high confidence

Introduces precise execution plans for node and edge access with bounded limits

The planner now defines explicit executable access plans for nodes and edges, supporting exact equality lookups (bitmap, unique-owner with verification, authoritative scan), dynamic runtime equality, range-index scans, and secondary-ID sets. It also introduces a typed read-limit mechanism that applies literal or dynamic bounds to access streams, automatically flattening nested limits to the tightest bound and eliding static limits when a tighter hard upper bound exists.

crates/planner/src/exec/access · high confidence

Introduces structured contracts for optimizer rule applicability and metadata

The query planner now uses a new set of rule contracts in \crates/planner/src/rules/contracts\ to define how optimizer rules are identified, matched, and described. This change adds \RuleId\ for stable rule identification (distinguishing known production rules from custom ones), \RuleMetadata\ to bundle rule phase, applicability, and property requirements, and \RuleApplicability\ to specify exactly which logical expression kinds or candidates a rule can match. It also defines \RuleKind\ (Exploration vs. Implementation) and \RuleOutcome\ to standardize rule execution results. This provides a stricter, more explicit interface for the optimizer scheduler to determine rule eligibility and behavior.

crates/planner/src/rules/contracts · high confidence

Migration to new tenant key envelope format

The database now performs a blocking migration that rewrites tenant-owned keys from the legacy \\[tenant\_id\]\[logical\_key\]\ format to the new \\[0xFD\]\[tenant\_id\]\[logical\_key\]\ format. This process runs before other writer bootstrap operations, ensuring data integrity by copying, verifying, and then cleaning up legacy keys in idempotent batches. The system will not proceed with normal operations until every legacy key has been successfully migrated and removed.

crates/db/src/migrations/tenant · high confidence

New Cascades-based query optimizer with rule-based access and cardinality planning

The planner now uses a Cascades-style optimizer driven by a static registry of seed rules, replacing the previous planning approach. This change introduces a new rule family for access patterns (handling filters, ordering, distinct, windows, and paths) and a comprehensive cardinality estimation system that generates physical count plans for various stream types. The optimizer is initialized once per process for performance, and the new rules handle index membership, range intersections, and equality domains, fundamentally changing how query execution plans are constructed and costed.

crates/planner/src/rules · high confidence

New canonical stream-pipeline operator model with filter flattening

The planner now uses a new \StreamPipelineOp\ enum and a canonicalization pass in the access pipeline to flatten nested filter predicates into a single conjunction, ensuring consistent query execution. This change introduces validation rules that reject identity or adjacent windows and correctly classifies operator effects (such as \VariableWrite\ as a state barrier), providing a more robust foundation for pipeline simplification and scheduling. Also in this area: Planner performance optimizations for memory and CPU efficiency.

crates/planner/src/logical/access/pipeline · high confidence

New index-based access filter planning and membership rules

The planner now uses a dedicated access-filter rule set to convert node and edge predicates into index lookups, range scans, and index membership checks. This includes collecting equality and range atoms, planning disjunctions with bounded union branches, caching index rewrites per optimization run, and deriving row-preserving membership sets for filters inside node streams to avoid redundant per-row filtering.

crates/planner/src/rules/access · high confidence

New intermediate representation for query projection plans

The planner now uses a new set of internal data structures in \crates/planner/src/ir/projection\ to define how query results are projected. This change introduces specific plan types for aggregates, property selections, and row-binding projections, along with validation logic to prevent duplicate output aliases or property names. For users, this represents an internal restructuring of the query planning layer that supports more precise control over result shapes and deduplication modes without changing the external query syntax.

crates/planner/src/ir/projection · medium confidence

New logical access contracts for query planning

The planner now introduces a structured logical access layer that explicitly models residual-free node and edge access paths, unary operations (filters, windows, ordering, distinct), and composed stream pipelines. This change enforces canonicalization of adjacent filters and static window composition, ensuring that the optimizer can safely simplify and reorder access-backed stream operations before physical execution.

crates/planner/src/logical/access · high confidence

New node access analysis and membership planning in the query planner

The planner now includes a dedicated analysis module for node access sources, providing derived properties such as hard cardinality upper bounds, common labels, and set canonicalization/subsumption detection. It introduces a node index membership plan that replaces per-row predicate evaluation with set-based lookups from secondary indexes or $label bitmaps, allowing nodes in the set to evaluate only residual conjuncts. Additionally, a new branch structure supports partly indexed OR predicates by splitting them into per-branch index sets with associated residuals, ensuring that only index-only sources are used for these branches.

crates/planner/src/ir/access/node · high confidence

New source-kind classification for query planning

The planner now uses a dedicated \AccessSourceKind\ enum to classify access paths into distinct families (such as Scan, PointIds, Range, Equality, Search, Runtime, etc.). This provides a stable, coarse-grained contract between the optimizer and the scheduler, allowing rule applicability checks to rely on a closed set of source types rather than the full, detailed executable access IR.

crates/planner/src/logical/access/path · high confidence

New text-index lifecycle management for Active mutations

The \crates/db/src/index\_lifecycle/text\ module now owns the complete lifecycle for Active text-index mutations, replacing the previous implementation. It introduces transaction-epoch batching to coalesce graph changes into single text updates, resource-admission preflight checks to enforce configurable limits on entities and bytes, and direct publication of immutable content-addressed split blobs to object storage. The module also handles state-only retirements for deleted or moved documents, restart-safe compaction of immutable splits, and bounded metadata cleanup for dropped or aborted builds, ensuring that text-index operations are atomic, bounded, and consistent with the underlying graph state. Also in this area: Optimized index source decoding reads only required fields; Optimized BM25 live state validation for search candidates; Backpressure and admission accounting for strong vector and text searches.

_crates/db/src/index\lifecycle/text · high confidence

New validated expression and predicate IR contracts in the planner

The planner now introduces a new IR layer for expressions and predicates located in \crates/planner/src/ir/expr\. This change adds validation logic (\validation.rs\, \error.rs\) that ensures parameter and property names are non-empty and that logical predicate sets (AND/OR) are not empty, returning specific \ExprPlanError\ types when these constraints are violated. It provides \ExprPlan\ and \PredicatePlan\ structures that wrap the existing AST nodes, maintaining a compatibility view for serialization while exposing a validated, shared scalar representation (\native.rs\) for execution. This allows the planner to borrow and validate pruned predicates without immediately building full plans, improving performance and error reporting for invalid query structures.

crates/planner/src/ir/expr · high confidence

Planner access contracts now infer cardinality, ordering, and locality

The planner's access-lowering layer now formally tracks execution properties for node and edge access plans. It infers hard upper bounds and exact cardinalities for operations like point lookups, equality/range index scans, and vector/text searches, and correctly propagates these through intersections and unions. It also determines key locality (marking index scans as 'Close' and scans/point-ids as 'Unknown') and preserves the sort order of range-index drivers while ensuring that intersected results are treated as unordered. These contracts allow downstream planner stages to make more accurate cost and ordering decisions.

crates/planner/src/exec/lowering/contracts/access · high confidence

Planner adds scheduler candidate predicates for unary access optimizations

The query planner now includes a new set of conservative scheduler predicates in \crates/planner/src/logical/access/unary/candidates\ to determine when specific rewrite rules can be applied to unary access operations. This enables the optimizer to skip impossible rule probes for \AccessDistinct\ (identifying noop candidates), \AccessOrder\ (detecting order elision and range direction mismatches), and \AccessWindow\ (identifying windows that can be folded or tightened). These changes allow the planner to more efficiently handle distinct operations, ordering on range indexes, and windowing on point IDs or search results.

crates/planner/src/logical/access/unary · high confidence

Planner analysis refactored for efficient predicate pruning and index selection

The planner's analysis module has been restructured to improve query performance through better memory management and static optimization. New modules in \crates/planner/src/analysis\ introduce \literal\_set\ for stable, low-allocation construction of equality domains and \membership\ for efficient set lookups. The \prune\ module now performs static pruning of impossible or tautological predicates using borrowed references to avoid unnecessary copying, while \labels\ and \index\_atoms\ provide specialized analysis for label scoping and index eligibility. These changes allow the planner to resolve membership constraints and filter predicates more efficiently before execution.

crates/planner/src/analysis · high confidence

Planner context refactored with shared parameters and rule-fire limits

The planner's context handling has been restructured to improve performance and determinism. Request parameters are now wrapped in \SharedParamBindings\ (using \Arc\) to avoid copying large parameter sets across expressions, while the optimizer's exploration budget has shifted from a wall-clock time limit to a rule-fire count (\OptimizerLimits\), ensuring reproducible plans regardless of host speed. Additionally, new guardrails (\PlannerLimits\) cap Boolean index-union branches, and the context now supports immutable runtime feedback to overlay statistics for more accurate cost modeling.

crates/planner/src/context · high confidence

Planner error handling and diagnostics expanded

The query planner now exposes a comprehensive set of specific error types to provide clearer diagnostics when planning fails. This includes detailed errors for search index issues (such as missing indexes, invalid tenant values, or unsupported result counts), validation failures for batch operations and property assignments (like duplicate properties or invalid batch conditions), and constraints on traversal operations (such as unsupported operations within sub-traversals or after row bindings). These changes help users quickly identify and correct malformed queries or unsupported planning scenarios.

crates/planner/src/error · high confidence

Planner introduces bounded equality and range index atom extraction

The query planner now includes dedicated analysis modules for extracting indexable atoms from equality and range predicates. This change adds logic to identify when properties can be resolved via secondary indexes for equality checks (including \IN\ lists and single values) and range comparisons (\\<\, \\>\, \BETWEEN\), validating that operands are literals or parameters rather than complex expressions. By defining specific domains for these index lookups, the planner can now generate more efficient execution plans that leverage native indexes for these common query patterns.

_crates/planner/src/analysis/index\atoms · high confidence

Planner now detects statically impossible scalar predicate conjunctions

The query planner has added logic to identify when a set of combined scalar conditions (such as equality, inequality, range bounds, nullability, and value sets) on a single property are mutually contradictory. By accumulating these constraints and checking for conflicts—like a value being required to be both equal to X and not equal to X, or falling within disjoint ranges—the planner can now recognize predicates that are statically impossible to satisfy. This allows the system to short-circuit execution for queries containing such contradictions, avoiding unnecessary processing.

crates/planner/src/analysis/scalar/constraints · high confidence

Planner optimizer now uses a compiled, pre-indexed rule schedule

The query planner's optimizer driver has been refactored to replace dynamic rule discovery with a pre-compiled schedule. The \RuleSchedule\ component now converts the ordered rule registry into dense, closed-enum candidate tables at initialization time. During query planning, the scheduler routes expressions to specific rule candidates by reading these pre-built tables (e.g., \candidates\_by\_kind\, \access\_filter\_index\_candidates\) rather than scanning the full registry or performing map lookups. This change introduces a strict registry-order iteration mechanism via \RuleCandidates\ and \CandidateSlice\ to ensure deterministic and efficient rule application for logical expressions, access pipelines, and root control flow.

crates/planner/src/optimizer/driver/schedule · high confidence

Query memory budgeting for adjacency, bitmaps, and properties

The query execution layer now enforces strict memory budgets for structural query resources. Adjacency buffers, bitmap indices, and property sets are decoded or constructed only after reserving memory from a query budget, ensuring that large graph traversals or index scans cannot exceed allocated limits. This change introduces new resource-tracking types in the query\_resources module to manage these allocations and prevent unbounded memory growth during query execution.

_crates/db/src/query\resources · high confidence

Query optimizer switches exploration budget from wall-clock time to rule-fire count

The query optimizer's exploration phase now limits its search depth based on the number of optimization rules applied (rule fires) rather than elapsed wall-clock time. This change, implemented in the new \state.rs\ module within the exploration driver, introduces a \rule\_fires\ metric and corresponding guardrails (\ExplorationBudget\, \RuleFires\) to stop exploration once a configured threshold is reached. Users may see more consistent optimization performance across different hardware loads, as the budget is no longer affected by system timing variations, though the specific timing of when optimization stops is now determined by rule application counts instead of time.

crates/planner/src/optimizer/driver/exploration · high confidence

Refactor scalar predicate analysis into modular proof components

The scalar predicate analysis logic in the planner has been restructured into distinct modules (\extract\, \truth\, \values\, \constraints\) to separate concerns for constant evaluation, literal extraction, and contradiction detection. This change introduces \CanonicalNumber\ for numeric equality checks to align with storage semantics, ensuring consistent behavior for planner proofs and \GROUP BY\ operations. It also adds static evaluation for string predicates (\StartsWith\, \EndsWith\, \Contains\) and refines range bound handling to treat unorderable domains (like nulls or mixed types) as empty, improving the accuracy of scalar contradiction proofs.

crates/planner/src/analysis/scalar · high confidence

Refactored memoizer to track expression identities separately from the memo

The query planner's memoization logic has been restructured so that the memoizer no longer stores its own copies of expression data. Instead, it now maintains a request-local identity index (MemoExpressionMemoizer) that maps expression digests to their locations within the central memo. This change introduces new contract types (QueuedMemoExpr, MemoizedExpr) and a session-based index to track which expressions have been queued for exploration, ensuring that the memoizer only holds references to where expressions are stored rather than duplicating the expression content itself.

crates/planner/src/optimizer/memoize · high confidence

Refactored optimizer configuration to borrow catalog and statistics

The optimizer configuration now borrows the index catalog and statistics from the planner context instead of copying them, which reduces memory overhead during planning sessions that may involve thousands of indexes. This change introduces a new \OptimizerConfig\ struct in \config.rs\ that holds references to the catalog, stats, and request parameters, ensuring that expensive data structures are not duplicated per expression. The \OptimizerConfig\ also provides an \into\_owned\ method for cases where the configuration must outlive the planner context, and the \RuleInput\ struct in \rule.rs\ now exposes these borrowed references to optimizer rules.

crates/planner/src/optimizer · high confidence

Vector index lifecycle moves to asynchronous queue-based planning and publication

The vector index driver now processes writes asynchronously through an operation queue, separating the planning of HNSW writes from their physical application. This change introduces a bounded outbox driver that retains build sessions and publication checkpoints to reuse cached rows and planning state across commits, improving throughput and reducing redundant reads. Publication of vector changes is now handled by collapsing queued operations into deterministic physical effects, ensuring that updates are applied in order and only after the build generation is activated.

_crates/db/src/index\lifecycle/vector · high confidence

Vector storage refactored into typed physical namespace with budget-aware warm passes

The vector storage layer has been reorganized into a dedicated \storage\ module that enforces a typed physical namespace boundary between logical vector keys and tenant-scoped SlateDB bytes. This change introduces \VectorRowKeyspace\ to bind physical names and index IDs, preventing namespace mismatches, and implements budget-controlled warm passes (\PartWarm\) that charge object-store parts against a byte limit to keep the storage tier warm without exceeding capacity. Additionally, the module now supports deterministic transaction-local write measurement (\MeasuredVectorTransaction\) that captures final vector writes for atomic HNSW graph validation before committing to SlateDB.

crates/db/src/search/vector/storage · high confidence

Fixes

1 commit (1 fix) fixing scripts

A fix in scripts — 1 commit (1 fix), 1 file: “Label Helix-internal OSS telemetry with fixed deployment IDs”. Also in this area: New async index queue benchmark harness for comparing map and rows layouts.

scripts/async-index-benchmark · low confidence · unverified

Deterministic Cascades optimizer with rule-fire budgeting

The planner's optimization driver now uses a deterministic, FIFO-based exploration loop that is bounded by a rule-fire budget rather than wall-clock time. This ensures that the same input always produces the same plan, regardless of system load or execution speed. The driver guarantees that required rewrites and implementation rules continue to run even after the optional exploration budget is exhausted, preventing plannable requests from failing due to missing physical alternatives. Additionally, index rewrites are cached and derived only once per filter for the entire optimization run, improving efficiency.

crates/planner/src/optimizer/driver · high confidence

Test coverage

11 commits adding/updating tests in scripts/tests; 178 commits adding/updating tests in crates/db/tests; 2 commits adding/updating tests in crates/db/tests/unit/vector; 3 commits adding/updating tests in crates/ast/src/testing; 3 commits adding/updating tests in crates/db-testkit; 36 commits adding/updating tests in crates/db/tests/unit; 6 commits adding/updating tests in crates/db/tests/production\_contracts; Add Docker image smoke tests and benchmarks; Add fuzz testing harness for database decoders; Added CLI test support infrastructure; Added Cypher parity validation harness; Added V2 planner quality benchmarks and baseline results; Added comprehensive TypeScript SDK test suite; Added comprehensive contract tests for Cypher query execution; Added comprehensive test coverage for planner diagnostics; Added contract tests for the Cascades query optimizer; Added end-to-end tests for index membership and query service behavior; Added integration tests for Cypher query compilation and execution; Added regression, DSL, and package smoke tests for the TypeScript SDK; Added test coverage for planner execution logic; Added test coverage for planner predicate analysis; Added test for arena parsing equivalence; Added tests for mutation route catalog target selection; Added tests for planner access window, order, and distinct rules; Added tests for planner allocation bounds; Added tests for planner rule implementation and optimization; Added tests for query planner access path and filter rules; Added tests for query planner executable subplan lowering; Added tests for query planner implementation rules; Added tests for root-stream planner rule implementations; Added tests for scalar predicate analysis and literal set handling; Added tests for the access-filter index optimizer rule; Added tests for typed Cypher relationship scanning and relationship count query plans; Added tests for vector build cache equivalence and throughput; Added unit tests for the logical planner's access windows, expression effects, and memoization; Comprehensive test coverage for Python SDK client, DSL, and graph modules; Expanded CLI test coverage for cloud, runtime, and installation flows; Expanded integration test coverage for the query planner; New AST and planner benchmarks for memory, throughput, and allocation profiling; New Python SDK parity and validation scripts; New benchmark suite for database write, search, and projection performance; New embedded parity test infrastructure for the TypeScript SDK; New fuzz testing targets for query parsing, planner, and interpreter; OpenCypher TCK integration and worker testing infrastructure; Updated openCypher TCK test scenarios for CALL and CREATE clauses.

Dependencies

HelixDB CLI updated to version 3.4.0

The HelixDB command-line interface has been updated to version 3.4.0. This release includes updated dependencies and configuration changes reflected in the Cargo.toml and Cargo.lock files for the CLI crate.

(dependencies) · high confidence

Written by cca.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

How this codebase got here

Score

  • CAI 55 → 55 (+0.3)
  • Rubric changed (rubric-2026.10.5 → rubric-2026.11.4) — scores are not directly comparable.

Lenses

  • Code Health 67 → 63 (-3.8)
  • Architecture 94 → 95 (+0.3)
  • Maturity 73 → 76 (+3.1)
  • Readiness 57 → 59 (+2.3)
  • Security 41 → 40 (-0.9)
  • Domain Modelling 100 → 100 (+0.0)
  • Performance 87 → 100 (+13.4)

Resolved (294)

  • Catalog.add_metadata (cognitive 16) (scripts/validate-cargo-target-references.py)
  • ClassTooLong: MutationOpCache (crates/db/src/search/vector/hnsw/mutation/mod.rs)
  • ClassTooLong: Runner (crates/db-testkit/src/lifecycle_workload.rs)
  • Client.postCypher (cognitive 33) (sdks/go/cypher.go)
  • Client.postCypher (cyclomatic 19) (sdks/go/cypher.go)
  • Duplicated block (10 lines × 2) (crates/cli/src/local_runtime.rs)
  • Duplicated block (10 lines × 2) (crates/db/src/encoding/v2/keys/indexes/equality/edge.rs)
  • Duplicated block (10 lines × 2) (crates/db/src/encoding/v2/values/adjacency/mod.rs)
  • Duplicated block (10 lines × 2) (crates/db/src/index_lifecycle/text/driver.rs)
  • Duplicated block (10 lines × 2) (crates/db/src/index_lifecycle/text/validation.rs)
  • Duplicated block (10 lines × 2) (crates/db/src/merge_operator.rs)
  • Duplicated block (10 lines × 2) (crates/db/src/migrations/mod.rs)
  • Duplicated block (10 lines × 2) (crates/db/src/search/mod.rs)
  • Duplicated block (10 lines × 3) (crates/db/src/encoding/v2/values/property/canonical_number.rs)
  • Duplicated block (10 lines × 4) (crates/db/src/migrations/vector_retirement.rs)
  • Duplicated block (10 lines × 5) (crates/db/src/migrations/mod.rs)
  • Duplicated block (10–11 lines × 2) (crates/db/src/migrations/vector_properties.rs)
  • Duplicated block (11 lines × 2) (crates/db/src/config/definition_differences.rs)
  • Duplicated block (11 lines × 2) (crates/db/src/execution/interpreter/rows/matches.rs)
  • Duplicated block (11 lines × 2) (crates/db/src/execution/interpreter/rows/matches.rs)
  • …and 274 more

New (587)

  • Clause::fmt (cognitive 18) (crates/cypher/src/print.rs)
  • Client.postStatement (cognitive 39) (sdks/go/cypher.go)
  • Client.postStatement (cyclomatic 23) (sdks/go/cypher.go)
  • Duplicated block (10 lines × 2) (crates/cli/src/local_runtime.rs)
  • Duplicated block (10 lines × 2) (crates/db/src/encoding/v2/keys/indexes/equality/edge.rs)
  • Duplicated block (10 lines × 2) (crates/db/src/encoding/v2/values/adjacency/mod.rs)
  • Duplicated block (10 lines × 2) (crates/db/src/execution/interpreter/control/foreach.rs)
  • Duplicated block (10 lines × 2) (crates/db/src/index_lifecycle/queue/publication.rs)
  • Duplicated block (10 lines × 2) (crates/db/src/index_lifecycle/text/driver.rs)
  • Duplicated block (10 lines × 2) (crates/db/src/index_lifecycle/text/validation.rs)
  • Duplicated block (10 lines × 2) (crates/db/src/search/mod.rs)
  • Duplicated block (10 lines × 2) (crates/db/src/search/vector/hnsw/search.rs)
  • Duplicated block (10 lines × 2) (crates/server/src/diagnostics/mod.rs)
  • Duplicated block (10 lines × 3) (crates/db/src/encoding/v2/values/property/canonical_number.rs)
  • Duplicated block (10 lines × 4) (crates/db/src/migrations/vector_retirement.rs)
  • Duplicated block (10–11 lines × 2) (crates/db/src/index_lifecycle/outbox.rs)
  • Duplicated block (10–11 lines × 2) (crates/db/src/migrations/vector_properties.rs)
  • Duplicated block (11 lines × 2) (crates/cli/src/commands/cloud/project.rs)
  • Duplicated block (11 lines × 2) (crates/db/src/config/definition_differences.rs)
  • Duplicated block (11 lines × 2) (crates/db/src/execution/interpreter/count.rs)
  • …and 567 more

Changes since last survey

  • 245 commits — 232 feature/other, 13 fixes

By area

  • crates/db — 114 commits
  • (repo) — 51 commits
  • .github/workflows — 16 commits
  • (root) — 14 commits
  • docs/database — 8 commits
  • crates/cli — 7 commits
  • crates/metrics — 5 commits
  • crates/planner — 5 commits
  • crates/server — 5 commits
  • scripts/db-production-coverage-baselines.json — 3 commits
  • crates/db-testkit — 2 commits
  • docker-image/tests — 2 commits
  • docs/cli — 2 commits
  • scripts/tests — 2 commits
  • sdks/go — 2 commits
  • crates/cypher — 1 commit
  • docs/databuddy.js — 1 commit
  • docs/foundry — 1 commit
  • docs/package-lock.json — 1 commit
  • scripts/server-production-coverage-baselines.json — 1 commit

Notable commits

  • fix: Fix MCP first-read example and document index operation tracking
  • fix: Fix MCP first-read example and document index operation tracking (#1241)
  • fix: Fix the durable wait limit contracts after commits moved to their own thread (#1287)
  • fix: Fix the nightly fuzz job: pin the nightly, key the cache, allow 40 minutes (#1279)
  • fix: Fix the transport test's RequestContext path
  • fix: Label Helix-internal OSS telemetry with fixed deployment IDs
  • fix: Pin the SlateDB fork with its v0.17 fixes and cleanups
  • fix: Pin the SlateDB fork with the multi-get request fix
  • fix: Pin the SlateDB fork with the reader poll and multi-get fixes
  • fix: ci: fix the nightly fuzz toolchain and workload timeout
  • fix: fix(python): accept every value type in typed datetime parameters
  • fix: fix(python): accept every value type in typed datetime parameters (#1238)
  • fix: fix: fsync every write to local disk storage (#1228)
  • change: Account for a warm planning cache at writer open
  • change: Activate secondary index builds under sustained writes (#1215)
  • change: Add .crucible.toml for Crucible (#1245)
  • change: Add Crucible test instructions and MCP config for agents
  • change: Add SQL explain, gRPC, embedded and SDK support (#1250)
  • change: Add a concurrent request throughput bench
  • change: Add a paired benchmark for unique-key claims
  • …and 225 more

Architecture

  • Unchanged — 0 containers · 3 contexts · 0 edges

Written by cca.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

Survey your own repository

HelixDB/helix-db was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.

About this page

  • The score is its most recent published measurement, taken on 14 November 2026 at a pinned commit. It is not a live figure and does not change until the project is measured again.
  • Measured at commit 4b0982fdf0e0e8606ca5fee3bb6214ea09973bb1 — the exact code this score is about.
  • Scored under rubric-2026.11.4 — the same rubric and the same method as every other entry in this index.
  • Measured by Canine Code Analyzer (cca.canine.dev) using cca measure-2026.11.65+preprod-e1a3b69fc8ee.