HeliosDB Nano v2.4.0-beta Known Issues

Last Updated: 2025-11-24 Release: v2.4.0-beta

Overview

This document catalogs all known issues, limitations, and test failures in the v2.4.0-beta release. Issues are categorized by severity and area, with workarounds and resolution timelines where applicable.

Test Failure Summary

Total Tests: 554 Passing: 527 (95.1%) Failing: 27 (4.9%)

Pass Rate by Category

Category	Passed	Failed	Pass Rate	Status
Core Database	230	0	100%	✅ Stable
Storage Engine	145	1	99.3%	✅ Stable
SQL Executor	95	1	99.0%	✅ Stable
Compression	32	15	68.1%	⚠️ Unstable
Vector Search	18	5	78.3%	⚠️ Unstable
Audit Logging	3	2	60.0%	⚠️ Needs Work
Other	4	3	57.1%	⚠️ Needs Work

Critical Issues (Blocker)

Count: 0

No critical blockers. All critical bugs from v2.3.1 have been resolved.

High Priority Issues

HP-1: Compression Test Failures (15 tests)

Severity: High Area: Storage / Compression Impact: Advanced compression features unreliable Status: Under Investigation

Failed Tests

storage::compression::alp::decoder::tests::test_decode_single
storage::compression::alp::decoder::tests::test_decode_range
storage::compression::alp::decoder::tests::test_decode_uncompressed
storage::compression::alp::decoder::tests::test_decode_alp_classic
storage::compression::alp::encoder::tests::test_encode_scientific_data
storage::compression::alp::pattern::tests::test_scientific_pattern_detection
storage::compression::alp::tests::test_alp_codec_decimal
storage::compression::alp::tests::test_single_value_decompression
storage::compression::alp::tests::test_range_decompression
storage::compression::fsst::encoder::tests::test_column_compression_full_flow
storage::compression::fsst::encoder::tests::test_column_compressor_heuristics
storage::compression::fsst::dictionary::tests::test_cache_lru_eviction
storage::compression::fsst::dictionary::tests::test_dictionary_codec_roundtrip
storage::compression::fsst::tests::test_email_compression
storage::compression::simd_ops::tests::test_buffer_pool_max_capacity

Root Cause

ALP decoder: Potential issues with metadata deserialization
ALP encoder: Scientific notation pattern detection edge cases
FSST encoder: Dictionary cache management issues
FSST codec: Roundtrip encoding/decoding inconsistencies
SIMD ops: Buffer pool capacity tracking

Impact Assessment

User Data: No risk - compression failures don’t corrupt data
Performance: Compression may fall back to uncompressed or zstd
Features: Advanced compression (ALP, FSST) unreliable
Core DB: No impact - storage engine works without advanced compression

Workaround

// Option 1: Disable advanced compression
let config = Config {
    compression_enabled: false,
    ..Default::default()
};

// Option 2: Use basic zstd compression only
let config = Config {
    compression_codec: CompressionCodec::Zstd,
    use_alp: false,
    use_fsst: false,
    ..Default::default()
};

Resolution Plan

Target: v2.4.0-rc1
ETA: 2025-12-01
Owner: Storage team
Tasks:
1. Debug ALP decoder metadata handling
2. Fix FSST dictionary cache eviction
3. Resolve SIMD buffer pool tracking
4. Add comprehensive compression integration tests
5. Validate roundtrip encoding/decoding

HP-2: Vector Quantization Failures (5 tests)

Severity: High Area: Vector Search / Quantization Impact: Quantized vector search unreliable Status: Under Investigation

Failed Tests

vector::quantized_hnsw::tests::test_quantized_hnsw_creation
vector::quantized_hnsw::tests::test_quantized_hnsw_insert_search
vector::quantized_hnsw::tests::test_memory_stats
vector::simd::distance::tests::test_dot_product_large
vector::simd::distance::tests::test_simd_correctness_random

Root Cause

Product quantization codebook training issues
HNSW graph construction with quantized vectors
SIMD distance calculation edge cases
Memory statistics tracking for quantized indices

Impact Assessment

User Data: No risk - failures in test code only
Performance: Quantized search may return incorrect results
Features: Product quantization unreliable
Core DB: No impact - standard HNSW works correctly

Workaround

// Use standard HNSW without quantization
db.execute("CREATE INDEX vec_idx ON docs USING hnsw (embedding)")?;

// Instead of:
// db.execute("CREATE INDEX vec_idx ON docs USING hnsw_pq (embedding)")?;

Resolution Plan

Target: v2.4.0-rc1
ETA: 2025-12-05
Owner: Vector team
Tasks:
1. Fix codebook training convergence
2. Debug quantized HNSW graph construction
3. Validate SIMD distance calculations
4. Add memory tracking tests
5. Create comprehensive quantization benchmarks

HP-3: Audit Log Test Failures (2 tests)

Severity: High Area: Audit / Security Impact: Audit logging may miss events Status: Investigating

Failed Tests

audit::logger::tests::test_log_ddl
audit::logger::tests::test_log_dml

Root Cause

Event capture timing issues
Audit log buffer flush synchronization
DDL/DML event classification edge cases

Impact Assessment

User Data: No risk
Security: Audit log may miss some events
Compliance: Potential compliance impact for regulated industries
Core DB: No impact - database functionality not affected

Workaround

// Ensure audit log is flushed before assertions
db.flush_audit_log()?;

// Or use synchronous audit logging (slower)
let config = Config {
    audit_mode: AuditMode::Synchronous,
    ..Default::default()
};

Resolution Plan

Target: v2.4.0-rc1
ETA: 2025-11-28
Owner: Security team
Tasks:
1. Fix event capture timing
2. Add flush synchronization
3. Improve DDL/DML classification
4. Add comprehensive audit tests

Medium Priority Issues

MP-1: System View Test Failure (1 test)

Severity: Medium Area: SQL / System Views Impact: v2.3 system view schema incomplete Status: Known Issue

Failed Test

sql::system_views::tests::test_v2_3_views_schemas

Root Cause

System view schema validation incomplete
Missing columns in some v2.3 system views
Schema evolution from v2.2 to v2.3 not fully tested

Impact Assessment

User Data: No risk
Features: System views mostly work, some columns may be missing
Monitoring: Reduced visibility into some system metrics
Core DB: No impact

Workaround

-- Use individual system views directly
SELECT * FROM pg_database_branches;
SELECT * FROM pg_mv_staleness;
SELECT * FROM pg_vector_index_stats;

-- Instead of relying on pg_v2_3_views_schemas

Resolution Plan

Target: v2.4.0-rc1
ETA: 2025-11-27
Owner: SQL team

MP-2: Transaction Version Parsing (1 test)

Severity: Medium Area: Storage / Transactions Impact: Edge case in MVCC version parsing Status: Known Issue

Failed Test

storage::transaction::tests::test_mvcc_read_at_version_parsing

Root Cause

Version string parsing edge cases
Timestamp format validation incomplete
Transaction ID parsing corner cases

Impact Assessment

User Data: No risk - rarely triggered
Features: AS OF clauses work in normal cases
MVCC: Core MVCC functionality not affected
Core DB: No impact

Workaround

-- Use standard timestamp format
SELECT * FROM table AS OF TIMESTAMP '2025-01-01 12:00:00';

-- Avoid edge cases like:
-- - Fractional seconds beyond microseconds
-- - Timezone offsets with seconds
-- - Very old timestamps (before 1970)

Resolution Plan

Target: v2.4.0-rc1
ETA: 2025-11-29
Owner: Storage team

MP-3: Integration Test Failures (2 tests)

Severity: Medium Area: Compression Integration Impact: Cross-component compression issues Status: Investigating

Failed Tests

storage::compression::integration::tests::test_compress_f64_batch
storage::compression::integration::tests::test_compress_f32_batch

Root Cause

Floating-point batch compression issues
Type conversion between f32/f64 and compression layer
ALP encoder integration with batch processing

Impact Assessment

User Data: No risk
Performance: Batch compression may not optimize f32/f64 columns
Features: Column compression still works with single values
Core DB: No impact

Workaround

Use standard zstd compression for numeric columns:

let config = Config {
    compression_codec: CompressionCodec::Zstd,
    ..Default::default()
};

Resolution Plan

Target: v2.4.0-rc1
ETA: 2025-12-03
Owner: Compression team

MP-4: Branch GC Test Failure (1 test)

Severity: Medium Area: Storage / Branching Impact: Garbage collection with multiple branches Status: Under Investigation

Failed Test

storage::branch::tests::test_gc_multiple_branches

Root Cause

Branch reference counting edge case
GC sweep not handling branch dependencies correctly
Snapshot retention with complex branch graphs

Impact Assessment

User Data: No risk - conservative GC prevents data loss
Storage: May retain more snapshots than necessary
Performance: Slightly higher storage usage
Core DB: No impact - branching works correctly

Workaround

Manual GC after branch operations:

-- Create branches
CREATE BRANCH feature1;
CREATE BRANCH feature2;

-- Merge and cleanup
MERGE BRANCH feature1 INTO main;
DROP BRANCH feature1;

-- Manual GC trigger
SELECT heliosdb_gc();

Resolution Plan

Target: v2.4.0-rc1
ETA: 2025-12-01
Owner: Storage team

Low Priority Issues

LP-1: Clippy Warnings (~150 warnings)

Severity: Low Area: Code Quality Impact: No functional impact Status: Tracked

Warning Categories

Unused Imports (~50 warnings)
- Imports left over from refactoring
- No runtime impact
- Easy to fix
Similar Names (~20 warnings)
```
let sampler = SamplingStrategy::new(...);
let samples = sampler.sample(...);
```
- Clippy flags similar variable names
- Actually good naming in context
- Can be allowed with #[allow(clippy::similar_names)]

Hidden Lifetime Parameters (~12 warnings)

// Warning: hidden lifetime
fn foo(executor: &Executor) { }

// Fixed in most places, some remain
fn foo(executor: &Executor<'_>) { }

Deprecated Usage (~8 warnings)
- Using deprecated DeltaType in tests
- Migration to DeltaOperation in progress
- Test code only, not production
Unused Variables (~40 warnings)
- Mostly in test code
- Some in stub functions
- No runtime impact
Other (~20 warnings)
- Needless continue
- Redundant else
- Private interfaces

Resolution Plan

Target: v2.4.0-rc1
ETA: 2025-12-10
Owner: All teams
Approach: Incremental cleanup during regular development

LP-2: Documentation Gaps

Severity: Low Area: Documentation Impact: Reduced developer experience Status: In Progress

Missing Documentation

System View Schemas
- Column descriptions incomplete
- Example queries needed
- Performance characteristics
Branch Merging
- Conflict resolution strategies undocumented
- Edge cases not covered
- Best practices missing
MV Scheduling
- CPU threshold configuration
- Priority assignment guidelines
- Performance tuning guide
Migration Guides
- v2.3.1 → v2.4.0-beta incomplete
- Breaking changes not fully documented
- Rollback procedures missing

Resolution Plan

Target: v2.4.0-rc1
ETA: 2025-12-08
Owner: Documentation team

Disabled Features

DF-1: Sync/Replication Protocol

Status: Disabled via feature flag Reason: Type incompatibilities with v2.3.0 features Impact: No distributed replication in beta

Details

The sync protocol was disabled because:

Type mismatches between sync messages and storage layer
Incompatible with new MV refresh scheduler
Not production-ready (65-70% complete)

Workaround

Use branching for backup/restore:

-- Create backup branch
CREATE BRANCH backup_2025_11_24;

-- Later, restore from backup
MERGE BRANCH backup_2025_11_24 INTO main;

Resolution Plan

Target: v2.5.0
ETA: 2026-Q1
Scope: Complete rewrite of sync protocol
Features:
- Type-safe sync messages
- MV-aware replication
- Conflict resolution
- Multi-master support

Environment-Specific Issues

Linux-Specific

None known

macOS-Specific

None known

Windows-Specific

None known

Performance Issues

PERF-1: MV Refresh CPU Usage

Severity: Low Area: Materialized Views Impact: High CPU usage during refresh under load Status: Known, By Design

Details

The CPU-aware MV scheduler can consume significant CPU when:

Many MVs need refresh simultaneously
CPU threshold set too high
Complex aggregations in MV queries

Workaround

// Lower CPU threshold
let config = Config {
    mv_scheduler_cpu_threshold: 50.0, // Default: 70.0
    ..Default::default()
};

// Or disable auto-refresh for some MVs
db.execute("ALTER MATERIALIZED VIEW heavy_mv SET (auto_refresh = false)")?;

Resolution Plan

Target: v2.4.0 stable
Approach: Add rate limiting and back-pressure mechanisms

PERF-2: Branch Merge Performance

Severity: Low Area: Branching Impact: Slow for branches with many changes Status: Known, Optimization Opportunity

Details

Branch merging scans all changes sequentially. For branches with thousands of changes, this can take several seconds.

Workaround

Keep branches short-lived
Merge frequently
Use targeted branches for specific changes

Resolution Plan

Target: v2.5.0
Approach: Parallel merge with change bucketing

Upgrade Issues

UG-1: DeltaType Deprecation Warnings

Severity: Low Impact: Compilation warnings during upgrade Status: Expected, Migration Path Available

Details

Code using DeltaType will see deprecation warnings:

warning: use of deprecated enum `storage::mv_delta::DeltaType`: Use DeltaOperation instead

Resolution

Update code to use DeltaOperation:

// Old
use heliosdb_nano::storage::DeltaType;
let delta_type = DeltaType::Insert;

// New
use heliosdb_nano::storage::DeltaOperation;
let operation = DeltaOperation::Insert;

Compatibility Issues

COMPAT-1: PostgreSQL Protocol

Status: 95% compatible Impact: Some PostgreSQL clients may have issues

Known Incompatibilities

Extended Query Protocol
- Some prepared statement edge cases
- Bind parameter type inference incomplete
- Impact: Most queries work, edge cases may fail
System Catalogs
- Not all pg_catalog views implemented
- Some columns missing in implemented views
- Impact: Some introspection queries fail
Data Types
- Custom data types not supported
- Some array operations incomplete
- Impact: Standard types work fine

Workaround

Use simple query protocol (direct SQL execution) instead of extended protocol where issues occur.

Security Issues

None known

All security features (encryption, authentication, SSL/TLS) are stable and passing tests.

Monitoring Recommendations

When using v2.4.0-beta, monitor:

Test Pass Rate

cargo test --lib 2>&1 | grep "test result:"

Compression Failures

SELECT COUNT(*) FROM heliosdb_compression_failures;

MV Refresh Failures

SELECT * FROM pg_mv_staleness WHERE last_error IS NOT NULL;

Audit Log Coverage

SELECT event_type, COUNT(*) FROM heliosdb_audit_log GROUP BY event_type;

Branch Operations

SELECT * FROM pg_database_branches WHERE status != 'active';

Reporting New Issues

When reporting issues:

Check This Document First
- Issue may already be known
- Workaround may be available
Gather Information
- HeliosDB Nano version: 2.4.0-beta
- Rust version: rustc --version
- OS: uname -a (Linux/macOS) or ver (Windows)
- Error message or test output
Create Minimal Reproduction
- Smallest possible code example
- Include schema and data if relevant
- Provide cargo test output if applicable
Submit GitHub Issue
- Use “Bug Report” template
- Tag with v2.4.0-beta
- Include all information from step 2 and 3

Summary

Overall Status

Core Database: ✅ Stable (100% test pass rate)
Phase 3 Features: ✅ Mostly Stable (95%+ pass rate)
Advanced Compression: ⚠️ Unstable (68% pass rate)
Vector Quantization: ⚠️ Unstable (78% pass rate)
Audit Logging: ⚠️ Needs Work (60% pass rate)

Recommendation

v2.4.0-beta is suitable for:

✅ Development and testing
✅ Beta testing programs
✅ Non-critical applications
✅ Feature evaluation

v2.4.0-beta is NOT suitable for:

❌ Production systems
❌ Mission-critical applications
❌ Regulated industries (due to audit log issues)
❌ Applications requiring advanced compression or quantization

Next Milestone

v2.4.0-rc1 (Release Candidate 1)

Target: 2025-12-15
Goal: 98%+ test pass rate
Focus: Fix all high-priority issues
Status: In progress

Last Updated: 2025-11-24 Version: v2.4.0-beta