HelixDB/helix-db

HelixDB is a graph database system that manages structured data through a combination of graph traversal, vector similarity search, and full-text indexing. It provides a robust query engine with a Cascades-based optimizer that generates deterministic execution plans for complex read and write operations. The system supports embedded usage within applications via Python, Node.js, Go, and Rust SDKs, as well as standalone server deployment with HTTP and gRPC interfaces.

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

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

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

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

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

The database now exposes a structured configuration system in \crates/db/src/config\ that allows tuning of embedded storage defaults, cache policies, and index lifecycle throughput. Users can control startup cache warming behavior (blocking, background, or off) and object-store preload levels (L0 or all). The system automatically detects the process's memory ceiling from cgroup limits to size vector build caches and other memory budgets proportionally. Index lifecycle work is now tunable via explicit concurrency limits for secondary, vector, and text tasks, as well as scan prefetch settings. Additionally, durable storage migrations can be configured with batch sizes and worker intervals, and the system now validates dynamic index definitions to detect and report conflicts in fields like vector dimensions, metrics, and text analyzers.

crates/db/src/config · high confidence

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

The server crate now provides a new HTTP and gRPC interface for the HelixDB V3 query service. Users can execute queries via POST /v2/query and check system status through GET /healthz and GET /readyz. The service supports specific request headers like x-helix-warm, x-helix-require-writer, and x-helix-await-durable to control write durability and routing behavior. The implementation includes a build script to generate protocol buffer code from helixdb.proto and is accompanied by a comprehensive test suite covering mutation, read, and error scenarios.

crates/server · high confidence

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.

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

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

The query planner now uses a new Cascades-style optimizer architecture. This change introduces a structured rule registry (\SeedRuleSet\) and a family of optimizer rules for access paths, filtering, ordering, and cardinality estimation. Users benefit from improved query planning capabilities, including more precise cardinality estimates and optimized access strategies, as the planner can now explore multiple physical alternatives for logical operations.

crates/planner/src/rules · high confidence

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

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

The \docker-image\ directory now provides the build, test, and documentation surface for the standalone HelixDB container. Users can build and run the image using \build.sh\ and \test.sh\, which validate the image against a strict contract (entrypoint, environment, labels, and security scans) via \image\_archive.py\. The image supports memory-only storage by default, but introduces a local disk cache feature (requiring v0.0.7+) configurable via \HELIX\_DISK\_CACHE\_DIR\ and \HELIX\_DISK\_CACHE\_BYTES\ to cache SlateDB blocks and full-text splits on NVMe or local disk, improving cold-read performance. The test suite includes smoke tests and a Compose-based S3 compatibility check using SeaweedFS to verify conditional write integrity.

docker-image · high confidence

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

The HelixDB Python SDK is now available, providing both synchronous and asynchronous clients for sending queries to the server or executing them against an embedded database. The new \AsyncClient\ leverages HTTPX for connection pooling and supports custom transports, timeouts, and limits. The SDK includes a query-builder DSL that mirrors the AST of other language SDKs, featuring traversal-scoped text search via \text\_search\ for BM25 ranking within specific node or edge streams. It also exposes structured query errors with static codes, preserves terminal write retry classifications, and handles warm read/write outcomes across transports. The package is licensed under Apache-2.0.

sdks/python · high confidence

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.

sdks/rust · high confidence

This change adds the \bindings/uniffi\ crate, providing the FFI boundary that allows non-Rust languages to interact with HelixDB. It introduces a stable error vocabulary (\HelixError\) that maps internal Rust database failures into specific categories (InvalidConfig, InvalidRequest, Planner, Storage, Transaction, Internal) so foreign callers can handle errors appropriately. The bindings expose a portable \HelixDB\ object with constructors for in-memory, disk, and S3-compatible storage sources, along with configurable cache profiles (\EmbeddedCacheMode\). It also includes a \NativeGraph\ façade for graph algorithms and a dedicated Tokio runtime to ensure database futures run safely across FFI boundaries without stack issues.

bindings/uniffi · high confidence

The \crates/ast\ module now provides the public JSON contract for HelixDB V3 queries, defining the wire format for read and write batches, traversal operations, expressions, projections, and index specifications. This change introduces a stable, machine-readable error code catalog (\QueryErrorCode\) for programmatic error handling and adds support for new query capabilities including bounded equality domains, traversal-scoped text and vector search, and conditional batch entries. Users can now construct queries using the typed builder API in the prelude, which ensures type-safe traversal states and mutation modes, while the underlying AST serializes to a consistent JSON structure for SDKs and the planner.

crates/ast · high confidence

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

The planner now uses a new set of physical types (access, cardinality, pipeline, stream, and alternatives) to represent query execution plans with exact semantics. This includes precise access paths (node/edge exact, point reads, range/index scans, vector/text search), exact cardinality estimation (bitmap operations, verified range scans, authoritative scans), and structured pipeline operators (filters, sorts, limits, projections). The physical alternative model includes stable digests for deterministic tie-breaking during optimization. This change provides the foundation for more accurate query planning and execution by explicitly modeling the physical shape of operations before lowering to executable DAGs.

crates/planner/src/physical · high confidence

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

The planner now defines a comprehensive set of native executable operations (ExecOp) and their supporting structures, replacing or supplementing previous execution models. This includes specific operators for graph access, exact cardinality counting, key-value reads, graph expansion, vector and text search, filtering, index membership, limiting, skipping, range slicing, deduplication, ordering, projection, aggregation, branching control flow (union, choose, coalesce, optional), repetition, shortest path, mutations (add/remove nodes and edges, set/remove properties, drop), index DDL, merging dependency outputs, for-each iteration, barriers, and variable operations. Supporting types define execution steps with conditions, schedules, and costs, as well as specific plans for node index membership and variable injection.

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

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

Added a suite of scripts to enforce and measure code coverage for the database and planner components. The \cov005-coverage.sh\ and \db-production-coverage.sh\ scripts validate workspace and DB production coverage against strict baselines defined in \cov005-coverage-baselines.json\ and \db-production-coverage-baselines.json\, ensuring specific line counts and percentages are met for scopes like the interpreter, index lifecycle, and vector search. The \cardinality-boundary-coverage.sh\ script targets planner and DB files to verify coverage of cardinality-related logic, while \index-lifecycle-production-coverage.sh\ measures V2 index lifecycle coverage. Additionally, \compare-v2-planner-bench.py\ provides a tool to compare V2 planner benchmark results between baseline and candidate binaries, and \cardinality-fuzz-corpus.sh\ manages fuzz testing for planner contexts.

scripts · high confidence

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

The \crates/db/src/index\_lifecycle\ module has been introduced to manage the canonical V2 index lifecycle, establishing storage version 4 as the current format. This change adds a new catalog system that projects durable V2 state into runtime handles for secondary, vector, and text indexes, ensuring physical access is authorized by exact generation and revision. It also implements atomic DDL operation enqueueing, graph mutation routing, and stable crash-injection failpoints for durability transitions, effectively replacing the previous \index\_v2\ runtime with this new lifecycle management layer.

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

The database runtime now uses a lease-based ID allocator that batches sequential node ID generation in memory, reducing storage I/O by only writing to the persistent watermark when a lease is exhausted or proactively refilled. Additionally, a new migration path converts V3 equality index entries into V4 bitmap format, utilizing a merge operator to handle bitmap deltas and ensuring the migration is restart-safe with explicit failpoints for each phase.

crates/db/src · high confidence

The planner now uses a formalized \RuleApplicability\ system to determine which optimizer rules can match specific logical expression shapes, replacing ad-hoc checks with explicit candidate predicates for access paths, filters, windows, and pipelines. This change introduces a closed inventory of production rule IDs (\KnownRuleId\) with stable string names, enabling consistent rule identification and serialization. By defining these contracts, the optimizer can now skip impossible rule applications early in the scheduling process, improving planning efficiency and ensuring that required rewrites (such as access window simplification or filter index exploration) are handled with predictable applicability logic.

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

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

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.

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

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.

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

The \crates/metrics\ crate introduces a privacy-safe, best-effort telemetry system for the Helix CLI, server, and embedded runtime. Users can control data sharing via three levels: \full\ (includes user ID), \basic\ (anonymous, default), or \off\ (disables telemetry). The CLI spools events atomically to \\~/.helix/metrics/spool/\ to survive crashes and prunes old files, while the server and embedded runtimes record query metrics (AST, latency, errors) without blocking execution or exposing sensitive data like rows or parameters. Configuration is managed via \metrics.toml\ and environment variables like \HELIX\_TELEMETRY\_LEVEL\ and \HELIX\_TELEMETRY\_ENDPOINT\.

crates/metrics · high confidence

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

The db-testkit crate now includes new CLI examples and fuzzing targets to validate query planning and launch metrics. The \check\_planner\_corpus\ and \check\_planner\_matrix\ examples allow users to verify SDK query fixtures against the normalized planner domain and check sharded planner case matrices. Additionally, \check\_launch\_metrics\ enables validation of cloud-launch comparison JSON documents against replica lag and performance policies. The crate also introduces a fuzzing suite (\crates/db-testkit/fuzz\) with targets for query JSON round-trips, planner context AST properties, and planner interpreter execution on empty graphs, supported by a new regression corpus.

crates/db-testkit · high confidence

The planner now exposes a comprehensive set of Intermediate Representation (IR) contract types in \crates/planner/src/ir\ to define executable query plans. This includes \PhysicalOp\ as the root operation tree, alongside specific plans for graph access (\NodeAccessPlan\, \EdgeAccessPlan\), mutations (\MutationPlan\), index DDL (\IndexDdlPlan\), and control flow (\BranchPlan\, \RepeatPlan\). The diff also introduces execution contracts for filtering, expansion, ordering, projection, aggregation, and shortest-path traversal, providing the structural foundation for the query execution engine.

crates/planner/src/ir · high confidence

The database execution engine now uses a dedicated access module to handle graph element retrieval, replacing previous ad-hoc implementations. This new layer centralizes dispatch for secondary set lookups, vector and text search (with bounded result limits), range-index scans, and KV reads, while also managing graph expansion (traversing edges between nodes) and runtime equality-domain classification for membership checks. Users benefit from more consistent and performant query execution for graph traversals, indexed property lookups, and restricted search operations within the interpreter.

crates/db/src/execution · high confidence

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

The query planner now uses a structured intermediate representation to define how nodes and edges are accessed. This introduces explicit plan types for point lookups, label scans, equality and range index lookups, vector and text searches, and set operations (union/intersection) for both nodes and edges. It also defines residual-free source wrappers to prevent ambiguous filter layering, establishes iteration direction contracts for range scans, and adds a node membership filter that replaces per-row property predicates with secondary-index set lookups for improved performance.

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

The query planner now includes a comprehensive set of new analysis modules in \crates/planner/src/analysis\ to improve query optimization and correctness. The \index\_atoms\ module (with \equality.rs\, \range.rs\, and \value.rs\) introduces dedicated logic for extracting and analyzing equality and range index atoms, allowing index eligibility rules to evolve independently. The \labels.rs\ module adds label scope analysis, enabling the planner to track and enforce label constraints within predicate trees. Additionally, the \scalar\ module (including \constraints\, \extract\, \truth\, and \values\) provides static predicate evaluation and contradiction detection, allowing the planner to prove that certain predicate branches are statically impossible or tautological, thereby pruning them early in the planning process.

crates/planner/src/analysis · high confidence

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

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

Added a new \scoped\_search\_bench\ example in \crates/db/examples\ that benchmarks global and traversal-scoped vector and BM25 search over a synthetic \Group \<- Item -\> Attribute\ graph. The tool supports local filesystem, S3, and HTTP backends, allows overriding the vector build planning cache size, and reports latency, recall@k, and object-store GET counts to help evaluate search performance and correctness.

crates/db/examples · high confidence

The server crate now provides a standalone runtime that listens on configurable HTTP and gRPC addresses, loading configuration from environment variables. It supports hybrid disk caching via the HELIX\_DISK\_CACHE\_DIR environment variable, including directory locking to prevent concurrent access, file descriptor limit adjustments, and free-space warnings. Both transports expose query execution and health endpoints, with errors mapped to specific HTTP status codes and gRPC statuses, and include static error codes in responses for easier client-side handling.

crates/server/src · high confidence

The CLI now uses a dedicated output module (\crates/cli/src/output\) that enforces a strict stream contract: result data goes to stdout while human-readable chrome (spinners, logs, warnings) goes to stderr. A global \--json\ flag enables machine-readable output, suppressing all chrome and disabling ANSI colors to ensure clean serialization. For human users, the system introduces a custom \HelixTheme\ (using cliclack) for consistent styling of prompts and logs, and adds syntax-highlighted pretty-printing for JSON results on stdout, distinguishing keys, strings, numbers, and literals with ANSI colors while preserving byte-identical layout when colors are disabled. Table rendering and state coloring (green/red/dim) are also standardized for consistent visual feedback.

crates/cli/src/output · high confidence

This change introduces a new storage module for vector data that enforces a strict boundary between logical vector keys and physical SlateDB storage. It adds \VectorRowKeyspace\ to manage tenant-scoped namespaces and index IDs, ensuring that physical key identities are derived correctly and preventing mismatches between logical names and compact namespaces. The module also introduces \MeasuredVectorTransaction\ to track vector write operations (puts and deletes) within a SlateDB transaction, allowing the system to capture and replay deterministic HNSW graph invariants without re-running the graph algorithm. This provides a stable, typed interface for vector row persistence and mutation while maintaining compatibility with existing V2 key encoding and legacy metadata formats.

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

The planner now includes a new contracts module that formally tracks the properties delivered by access and stream operators. For access plans, it infers cardinality bounds (exact counts for point lookups and unique indexes, hard upper bounds for searches, and None for unbounded scans), key locality (Close for indexed scans, Unknown otherwise), and ordering (preserving range index order, but discarding it for intersections). For stream operators, it updates cardinality for limit/skip/range, handles materialization for projections and aggregates, and determines execution scheduling (Barrier vs Pipeline) based on operator type. This allows the planner to make more informed decisions about operator ordering and optimization based on these inferred contracts.

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

Reader nodes now maintain a resident memory cache for vector index upper-layer and SimHash rows, significantly reducing storage fetches for repeated searches. The cache is hydrated in the background with a budget-limited, scope-aware strategy, and reader refreshes are automatically paced and back off when the reader applies state faster than the cache can load, ensuring readers never serve stale data. On the writer side, a new commit-fencing mechanism tracks dirty rows and resolves cache visibility only after storage outcomes are known, preventing stale reads during concurrent writes.

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

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

The planner now builds executable plans directly from the AST without materializing a compatibility physical tree first. This change introduces a new \PlanEnvelope\ that validates read/write batch contracts, return variables, and duplicate names, and records a native handoff trace for diagnostics. Control-flow logic (unions, branches, repeats) and index DDL specifications are now validated in focused modules, ensuring arity invariants, valid repeat stop/emit modes, and correct index identity fields are enforced at the planning boundary.

crates/planner/src/planning · high confidence

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

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.

crates/cli · high confidence

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

The planner now uses rule-fire counts instead of elapsed time to bound optimization, ensuring that the same query and context always produce the same plan regardless of host speed or load. This change introduces \OptimizerLimits\ with configurable caps for memo groups, memo expressions, total rule fires, and alternatives per group, alongside a separate \exploration\_rule\_fires\ limit that stops optional logical exploration while still allowing required rewrites and implementation rules to run for every queued expression. A new \PlannerLimits\ struct adds a \max\_index\_union\_branches\ guardrail (defaulting to 64) to cap Boolean index-union planning, and the \PlannerContext\ now exposes these limits along with runtime feedback and storage cost profiles to the optimizer.

crates/planner/src/optimizer · high confidence

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

The query planner has been rewritten for HelixDB V3, replacing the previous implementation with a modular Cascades-based optimizer. This change introduces deterministic tie-breaking via stable FNV-1a plan digests, ensuring consistent query plans across restarts. It also adds support for immutable runtime feedback snapshots, allowing the planner to incorporate observed row cardinalities from previous executions to improve cost estimation. The new architecture exposes stable contracts for predicate analysis, executable DAG validation, and access source classification, fundamentally changing how queries are optimized and executed.

crates/planner/src · high confidence

The planner now uses a new set of logical root contracts (RootStream, RootPipeline, RootMutation, RootIndexDdl, RootBranch, RootRepeat, RootShortestPath, and various terminals) to preserve executable payloads directly in the logical plan. This allows the planner to select and lower executable operations without consulting the legacy physical tree, supporting features like exact cardinality selection and canonical stream pipeline filters.

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

The database storage format has been updated to the V2 encoding scheme, introducing structured, typed codecs for graph keys (adjacency, edges, properties, indexes) and global metadata. This change replaces the previous V1 key layout with a new binary format that includes explicit prefixes, direction markers, and hash-based indexing for equality and label lookups. To support migration and backward compatibility, the existing V1 encoding paths are retained but marked as deprecated, with all public exports now routing through the new V2 modules. Users will benefit from improved key parsing safety, clearer error reporting for invalid encodings, and a more robust foundation for future index families.

crates/db/src/encoding · high confidence

The planner now uses a new \StorageCostProfile\ to estimate query costs based on granular, tunable metrics such as object read latency, SSTable filter probe costs, range scan steps, and CPU work for residual predicates. This model supports JSON-based experiment overrides, allowing operators to adjust defaults (e.g., \range\_next\, \bitmap\_decode\_per\_id\) without code changes. The cost vector tracks latency, object reads, CPU units, and peak memory, enabling more accurate plan selection by accounting for specific storage engine behaviors like parallel KV reads and bitmap decoding.

crates/planner/src/cost · high confidence

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

The database now migrates tenant-owned keys from the legacy \\[tenant\_id\]\[logical\_key\]\ format to a new typed envelope format prefixed with \0xFD\. This change is implemented via a new \envelope\ migration module that runs before other writer bootstrap steps, ensuring data integrity through a three-phase process: copying legacy keys to the new format, verifying the copies match the originals, and finally cleaning up the old keys. The migration is idempotent and safe to resume if interrupted.

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

The planner now uses a new set of intermediate representation (IR) and logical algebra types to define query plans. The IR layer introduces structured contracts for projections (including binding, general, aggregate, and property selections) and defines a \ProjectionPlan\ enum with a deduplication mode. The logical layer defines a \LogicalExpr\ enum that separates pure, side-effect-free operations from barrier operations (like mutations or DDL) to prevent incorrect reordering during optimization. It also introduces a memo-child extraction system that determines which sub-expressions are independently planned, ensuring stable memo-group lineage for complex root streams, control flow, and mutations.

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

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.

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

The planner now exposes a dedicated intermediate-representation module for index lookups, introducing structured types for secondary equality indexes, range indexes, and text/vector search plans. For equality lookups, the new \SecondaryIndexLiteral\ and \IndexValue\ types enforce that nested arrays and objects are rejected, while explicitly classifying storage behavior for nulls, NaNs, and runtime parameters. Range indexes are now modeled with \IndexBound\, \IndexRange\, and \IndexBetweenRange\ types that support static proof of containment and intersection, allowing the planner to reason about lower, upper, and bounded ranges at query time. Additionally, search plans (\RestrictedTextSearchPlan\, \RestrictedVectorSearchPlan\) now include explicit tenant-scoping logic that rejects literal null tenant values, ensuring that multi-tenant search constraints are handled correctly during planning.

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

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

The database layer now includes new execution primitives for secondary indexes, enabling the planner to perform exact equality point reads and batch lookups, as well as ordered forward and reverse range scans with runtime limits. These changes allow queries to execute verified range counts without materializing all IDs and support bounded reverse ranges with membership-first verification. Additionally, instrumentation for equality read metrics is now isolated per test thread to prevent interference during parallel unit testing, ensuring accurate benchmarking and regression detection for cardinality and range-scan behaviors.

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

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.

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

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

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

The HNSW vector mutation logic in \crates/db/src/search/vector/hnsw/mutation\ has been restructured to introduce an \ActiveVectorMutationRuntime\ that manages transaction-local state for insert, upsert, and delete operations. This change consolidates mutation state into operation-local sessions with explicit cache limits for items, neighbors, and simhashes, and introduces a shared budget system to control memory usage during vector builds. The refactoring also groups runtime modules and ensures that cache invalidation and eviction are handled independently of namespaces, improving performance and memory efficiency for vector index updates.

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

The vector index driver now retains planning sessions (VectorBuildSession) between committed steps of a single build operation, subject to a shared memory budget and a maximum of 16 concurrent retained builds. This allows the system to reuse decoded row data and planning state for subsequent steps within the same build, reducing redundant work. The implementation includes a bounded cache with LRU eviction and max-min fair cap allocation to manage memory usage, and ensures that retained sessions are only kept if they match a durable checkpoint proving no intervening writes occurred.

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

The vector search subsystem introduces strict request-scoped access boundaries and validation layers to improve reliability and performance. New \access\ modules enforce that vector reads and writes are bound to specific database snapshots or transactions, preventing raw storage handle leakage. A new configuration validation layer ensures that persisted vector index definitions are checked for consistency before entering the core, while dimension and metric validation modules prevent silent truncation or invalid magnitude errors during distance calculations. Additionally, feature-gated benchmarking support has been added to measure batch mutation performance and telemetry.

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

The Go SDK now wraps native database errors from embedded operations (such as opening connections and executing queries) into structured errors that preserve specific error codes and messages. This allows users to programmatically inspect the cause of failures, such as invalid query JSON or configuration issues, rather than receiving generic error strings. Additionally, several embedded template files have been moved to an internal directory to clarify their role as generated sources.

sdks/go/internal · high confidence

The planner now uses a dedicated module in \crates/planner/src/rules/access/filter\ to extract index atoms (equality and range) from access-filter predicates, construct typed index plans (conjunctions, disjunctions, and shared-conjunction-with-disjunction), and enforce branch limits via \PlannerLimits\. This structured approach powers stable missing-index diagnostics that report exactly which equality or range indexes are absent for a given predicate, and it enables index membership rewrites for node streams so that filters following expansions can still leverage catalog indexes without becoming access paths.

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

Add Docker image smoke tests and benchmarks; Add Python SDK parity testing and license validation scripts; Add fuzz testing harness for database decoders; Added CLI test support infrastructure; Added V2 planner quality benchmarks and baseline results; Added comprehensive TypeScript SDK test suite; Added comprehensive test coverage for planner diagnostics; Added end-to-end tests for index membership and equality planning; Added production-contract tests for vector index capabilities; Added production-support test harnesses for index lifecycle and graph mutation contracts; Added regression tests for late mutation convergence across all index types; Added regression, DSL, and package smoke tests for the TypeScript SDK; Added test coverage for access rules and Docker image fixtures; Added test coverage for planner execution and lowering logic; Added tests for planner access window, order, and distinct rules; Added tests for planner rule implementation and optimization; Added tests for query planner access path rules; Added tests for query planner access-filter optimization rules; Added tests for root-stream planner rule implementations; 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; Deterministic acceptance contracts for Index V2 lifecycle; Expanded CLI test coverage for cloud, runtime, and installation flows; Expanded unit test coverage for index lifecycle and migration contracts; Introduce structured test inventory and production-linked integration contracts; New benchmark suite for database write, search, and projection performance; New embedded parity test infrastructure for the TypeScript SDK.

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 watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

• CAI 52 → 56 (+4.0)
• Rubric changed (rubric-2026.09.10 → rubric-2026.09.18) — scores are not directly comparable.

• Code Health 60 → 62 (+2.0)
• Architecture 100 → 93 (-6.8)
• Maturity 68 → 67 (-0.3)
• Readiness 68 → 57 (-10.8)
• Security 34 → 46 (+12.7)
• Domain Modelling 100 → 100 (+0.0)
• Performance 85 (new)

• ClassTooLong: HelixDB (crates/db/src/lib.rs)
• ClassTooLong: MutationOpCache (crates/db/src/search/vector/mutation.rs)
• ClassTooLong: VectorIndex (crates/db/src/search/vector/index.rs)
• ClassTooLong: VectorRows (crates/db/src/search/vector/storage.rs)
• Dependency hygiene PARTLY measured — npm pinning read, dependency currency not (no pnpm-resolved versions to grade)
• Documentation: no installation or build instructions (README.md)
• Documentation: no usage examples (README.md)
• Duplicated block (10 lines × 2) (crates/db/src/search/vector/storage.rs)
• Duplicated block (10 lines × 2) (crates/db/src/search/vector/storage.rs)
• Duplicated block (10 lines × 2) (tools/hyperscale-migration-parity/src/main.rs)
• Duplicated block (10 lines × 4) (crates/db/src/migrations/vector_retirement.rs)
• Duplicated block (10 lines × 4) (crates/db/src/search/vector/storage.rs)
• Duplicated block (10–11 lines × 2) (crates/db/src/migrations/vector_properties.rs)
• Duplicated block (10–13 lines × 2) (crates/db/src/search/vector/storage.rs)
• Duplicated block (11 lines × 2) (crates/db/src/execution/interpreter/access/indexes.rs)
• Duplicated block (11 lines × 2) (crates/db/src/execution/interpreter/storage.rs)
• Duplicated block (11 lines × 2) (crates/db/src/migration_parity.rs)
• Duplicated block (11 lines × 2) (crates/db/src/search/vector/mutation.rs)
• Duplicated block (11 lines × 2) (crates/db/src/search/vector/restricted.rs)
• Duplicated block (11 lines × 2) (crates/db/src/search/vector/storage.rs)
• …and 234 more

• Branch::next (cognitive 38) (crates/db/src/execution/interpreter/pull/branch.rs)
• Branch::next (cyclomatic 21) (crates/db/src/execution/interpreter/pull/branch.rs)
• ClassTooLong: MutationOpCache (crates/db/src/search/vector/hnsw/mutation/mod.rs)
• ClassTooLong: VectorIndex (crates/db/src/search/vector/hnsw/index.rs)
• ClassTooLong: VectorRows (crates/db/src/search/vector/storage/mod.rs)
• Cursor::next (cognitive 207) (crates/db/src/execution/interpreter/pull/poll.rs)
• Cursor::next (cyclomatic 92) (crates/db/src/execution/interpreter/pull/poll.rs)
• Documentation: no contributor guidance (README.md)
• Duplicated block (10 lines × 2) (crates/cli/src/local_runtime.rs)
• Duplicated block (10 lines × 2) (crates/db/src/index_lifecycle/text/validation.rs)
• Duplicated block (10 lines × 2) (crates/db/src/search/vector/storage/mod.rs)
• Duplicated block (10 lines × 2) (crates/db/src/search/vector/storage/mod.rs)
• Duplicated block (10 lines × 2) (docker-image/image_archive.py)
• Duplicated block (10 lines × 2) (sdks/go/client.go)
• Duplicated block (10 lines × 2) (sdks/go/dsl.go)
• Duplicated block (10 lines × 2) (sdks/python/scripts/run_embedded_parity.py)
• Duplicated block (10 lines × 2) (sdks/python/scripts/run_embedded_parity.py)
• Duplicated block (10 lines × 3) (crates/db/src/execution/interpreter/mod.rs)
• Duplicated block (10 lines × 4) (crates/db/src/migrations/vector_retirement.rs)
• Duplicated block (10 lines × 4) (crates/db/src/search/vector/storage/mod.rs)
• …and 214 more

• 300 commits — 193 feature/other, 107 fixes

• crates/db — 124 commits
• (repo) — 50 commits
• crates/server — 38 commits
• crates/planner — 18 commits
• crates/cli — 17 commits
• docker-image/tests — 8 commits
• docs/learn — 6 commits
• scripts/server-production-coverage-baselines.json — 6 commits
• docker-image/README.md — 5 commits
• scripts/db-production-coverage-baselines.json — 5 commits
• docs/cli — 4 commits
• sdks/python — 4 commits
• docs/database — 3 commits
• (root) — 2 commits
• docs/VECTOR_IDLE_HYDRATION_VALIDATION.md — 2 commits
• crates/graph-algorithms — 1 commit
• docs/INDEX_DRIVER_FAILURE_VALIDATION.md — 1 commit
• docs/README.md — 1 commit
• docs/llms-full.txt — 1 commit
• docs/scripts — 1 commit

• fix: Distinguish catalog polling from vector-data reads in image regression
• fix: Fix edge-drop stack overflow and test inventory (#1120)
• fix: Fix edge-stream drop silently leaving edges undeleted (#1114)
• fix: Fix permanent index cleanup failures and validation diagnostics (#1078)
• fix: Format edge drop SDK regression test
• fix: Merge main before index lifecycle failure fixes
• fix: Merge remote-tracking branch 'upstream/main' into fix/distinct-numeric-identity-coverage
• fix: Record idle vector hydration regression evidence
• fix: chore(server): record the server coverage fingerprint after the disk cache fixes
• fix: chore(server): record the server coverage fingerprint after the disk cache fixes
• fix: fix(ci): replace withdrawn MinIO images with SeaweedFS in the Compose smoke
• fix: fix(ci,cli): replace withdrawn MinIO images with SeaweedFS (#1136)
• fix: fix(cli): address review of Cloud resolution and --json
• fix: fix(cli): align linked markers and colour states in Cloud tables
• fix: fix(cli): bound the SeaweedFS readiness wait by elapsed time
• fix: fix(cli): harden Cloud resolution and the --json contract after review
• fix: fix(cli): name init projects after the real directory and shorten image digests
• fix: fix(cli): name the command that removes only the legacy MinIO volume
• fix: fix(cli): print query results under --quiet and document RFC 3339 log times
• fix: fix(cli): reach the SeaweedFS sidecar through a fixed network alias
• …and 280 more

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

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.