Skip to content

Experimental Features in HeliosDB-Lite

Last Updated: November 23, 2025 Version: v2.1.0-dev

Overview

This document describes experimental features in HeliosDB-Lite that are not production-ready but available for testing and development.

⚠️ WARNING: Experimental features may have incomplete implementations, missing tests, breaking API changes, or be removed entirely in future releases. Do NOT use in production.

sync-experimental: Sync/Replication Module

Status: 🧪 EXPERIMENTAL (65-70% Complete) Feature Flag: sync-experimental Target Completion: v2.2.0 (Estimated: Q1 2026)

Description

Multi-node synchronization and replication system for HeliosDB-Lite, enabling: - Offline-first mobile/edge applications - Multi-node eventual consistency - Bidirectional sync with conflict resolution - HTTP/gRPC-based change propagation

Current Implementation Status

Completed Components (65-70%): - ✅ JWT Authentication System (100%) - Production-ready with 15 tests - ✅ Vector Clock Conflict Detection (100%) - Full causality tracking - ✅ Offline Queue (100%) - RocksDB-backed persistent storage - ✅ Delta Compression (100%) - Binary diff/patch framework - ✅ Message Protocol (100%) - Complete message types - ✅ Conflict Resolution (90%) - Last-write-wins, custom resolvers - ✅ Sync Server (75%) - Auth complete, storage hooks missing - ✅ Sync Client (70%) - Logic complete, network layer stubbed

Missing Components (30-35%): - ❌ Storage Engine Integration (CDC hooks) - ❌ HTTP/gRPC Transport Layer - ❌ Change Log Queries - ❌ Delta Application to Database - ❌ End-to-End Integration Tests

Code Statistics: - Total Lines: 2,380 - Tests: 15 passing (auth module only) - TODO Markers: 8

How to Enable

# Cargo.toml
[dependencies]
heliosdb-lite = { version = "2.1", features = ["sync-experimental"] }

# Build with experimental sync
cargo build --features sync-experimental

# Run tests (limited to completed components)
cargo test --features sync-experimental

API Example (Incomplete)

#[cfg(feature = "sync-experimental")]
use heliosdb_lite::sync::{SyncClient, SyncConfig};

#[cfg(feature = "sync-experimental")]
fn example_sync() -> Result<(), Box<dyn std::error::Error>> {
    // Create sync client
    let config = SyncConfig {
        server_url: "https://sync.example.com".to_string(),
        auth_token: "jwt-token-here".to_string(),
        offline_queue_path: "./offline_queue".to_string(),
    };

    let client = SyncClient::new(config)?;

    // Sync database (NOT IMPLEMENTED YET)
    // client.sync()?;

    Ok(())
}

Known Issues

  1. No Network Transport: HTTP/gRPC layer is stubbed
  2. No Storage Integration: CDC hooks not implemented
  3. Incomplete Tests: Only auth module fully tested
  4. API Instability: Module structure may change
  5. Performance Unvalidated: No benchmarks yet

Roadmap to Production

v2.2.0 (Target: Q1 2026): 1. Implement HTTP/gRPC transport (1 week) 2. Add storage engine CDC hooks (1 week) 3. Complete change log queries (3 days) 4. Implement delta application (3 days) 5. Add end-to-end integration tests (1 week) 6. Performance benchmarking (3 days) 7. Security audit (1 week)

Estimated Effort: 4-5 weeks total

Alternatives

If you need sync/replication now, consider: 1. Application-Level Sync: Implement in your application layer 2. PostgreSQL Logical Replication: Use when in PostgreSQL-compatible mode 3. Third-Party Tools: CouchDB, RxDB, WatermelonDB for mobile sync 4. Wait for v2.2.0: Production-ready sync module planned for Q1 2026

Contributing

Contributions to complete this module are welcome! See: - SYNC_MODULE_ANALYSIS_RECOMMENDATION.md - Full analysis - Contributing Guide - How to contribute - GitHub Issues - Tagged with sync-experimental

References

Future Experimental Features

simd: SIMD-Accelerated Operations

Status: 🔬 PLANNED Target: v2.3.0

SIMD-optimized vector operations for 2-5x performance improvement.

gpu-acceleration: GPU-Accelerated Training

Status: 🔬 PLANNED Target: v3.0.0

GPU-based vector quantization training for 10-100x speedup.

Stability Promise

Stable Features (Production-Ready): - Core SQL database - Vector search with HNSW - Encryption (TDE) - PostgreSQL wire protocol - Compression (ALP/FSST) - Time-travel queries - Database branching - Materialized views

Experimental Features (NOT Production-Ready): - Sync/replication module

Deprecated Features (To Be Removed): - None currently

Questions or Feedback?

Last Updated: November 23, 2025 Maintainer: HeliosDB Team License: Apache 2.0