HeliosDB-Lite Knowledge Adaptation for HeliosDB Full

Purpose: Extract design patterns and conceptual knowledge from HeliosDB-Lite and adapt them to HeliosDB Full’s distributed, enterprise-grade architecture.

Date: 2025-11-30 Status: Specification Complete

Architectural Context

HeliosDB Full Architecture Summary

Component	Description
Storage Layer	LSM-tree + SSTables, page-based storage with COW
Branching	Page-level COW via `heliosdb-branching` with LSN tracking
Temporal	Oracle-compatible flashback with SCN tracking
Compute	Distributed compute endpoints, multi-tenant
Protocols	PostgreSQL, Oracle, Cassandra, MongoDB, etc.
MV System	ML-based candidate generation and optimization
CLI	Basic REPL with backslash commands

Key Architectural Principles for Adaptation

Distributed-First: All designs must work across multiple nodes
Protocol Agnostic: Features exposed through multiple wire protocols
Enterprise-Grade: Multi-tenant, RBAC, audit logging
LSN-Based: Use Log Sequence Numbers for ordering, not timestamps
Page-Level: Operations at page granularity, not row-level

Feature 1: Branch SQL Syntax

Knowledge from HeliosDB-Lite

Design Pattern: Declarative SQL syntax for branch lifecycle management

-- HeliosDB-Lite syntax
CREATE DATABASE BRANCH <name> FROM <parent> AS OF <point>;
USE BRANCH <name>;
MERGE DATABASE BRANCH <source> INTO <target>;
DROP DATABASE BRANCH <name>;

Key Concepts:

Creation Points: NOW, TIMESTAMP, TRANSACTION (tri-modal)
Branch Context: Session-level branch binding
Merge Operations: Three-way merge with conflict detection

Adaptation for HeliosDB Full

1.1 Extended SQL Syntax for Distributed Environment

-- Adapted for HeliosDB Full's distributed architecture
CREATE DATABASE BRANCH <name>
    FROM <parent>
    AS OF { LSN <lsn> | TIMESTAMP <ts> | SCN <scn> | NOW }
    [ ON STORAGE NODE <node_id> ]
    [ WITH COMPUTE ENDPOINT <endpoint_id> ]
    [ OPTIONS (
        read_only = { true | false },
        retention_period = <interval>,
        gc_policy = { aggressive | balanced | conservative }
    ) ];

-- Multi-protocol branch switching
USE BRANCH <name> [ FOR SESSION | FOR TRANSACTION ];

-- Distributed merge with conflict resolution
MERGE DATABASE BRANCH <source> INTO <target>
    [ USING STRATEGY { OURS | THEIRS | MANUAL } ]
    [ WITH CONFLICT RESOLUTION <rule_name> ]
    [ DRY RUN ];

-- Branch lifecycle
ALTER DATABASE BRANCH <name> SET { READ_ONLY | WRITABLE };
DROP DATABASE BRANCH <name> [ IF EXISTS ] [ CASCADE ];

1.2 Integration Points

Integration	Target	Design
Parser	`heliosdb-compute/src/parser/`	Add AST nodes for branch statements
Planner	`heliosdb-compute/src/planner/`	Plan branch operations as DDL
Executor	`heliosdb-branching/src/operations.rs`	Connect to `BranchManager`
Protocols	Each protocol crate	Map to native syntax where applicable

1.3 Session Context Design

┌─────────────────────────────────────────────────────────────┐
│                    Session Context                          │
├─────────────────────────────────────────────────────────────┤
│  current_branch: Option<BranchId>                          │
│  branch_lsn: Lsn           // Read horizon for branch      │
│  compute_endpoint: ComputeEndpointId                       │
│  protocol: ProtocolType    // PostgreSQL, Oracle, etc.     │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                Storage Node Resolution                      │
├─────────────────────────────────────────────────────────────┤
│  1. Resolve branch_id → storage_nodes[]                    │
│  2. Select optimal node (latency, load)                    │
│  3. Route read/write to appropriate node                   │
└─────────────────────────────────────────────────────────────┘

1.4 Protocol Mapping

Protocol	Native Equivalent	Mapping
PostgreSQL	N/A	Direct SQL syntax
Oracle	Flashback + Edition-Based	`CREATE EDITION` semantics
Snowflake	`USE DATABASE`	Map branch to virtual schema
Databricks	Delta Lake branches	Direct mapping

Feature 2: Time-Travel SQL Syntax

Knowledge from HeliosDB-Lite

Design Pattern: Tri-modal temporal query specification

-- HeliosDB-Lite tri-modal syntax
SELECT * FROM table AS OF TIMESTAMP '2025-11-23 10:00:00';
SELECT * FROM table AS OF TRANSACTION 12345;
SELECT * FROM table AS OF SCN 9876543;

Key Concepts:

Resolution Modes: Timestamp, Transaction ID, SCN
Snapshot Isolation: Read from consistent point-in-time
Version Chain: Navigate through historical versions

Adaptation for HeliosDB Full

2.1 Extended AS OF Syntax

-- Full temporal query syntax for distributed environment
SELECT <columns>
FROM <table>
    AS OF {
        TIMESTAMP <timestamp>
      | LSN <lsn>
      | SCN <scn>
      | BRANCH <branch_name> [ AT <point> ]
      | SYSTEM_TIME <timestamp>  -- SQL:2011 standard
    }
[ WHERE <conditions> ];

-- Oracle-compatible VERSIONS BETWEEN (already in Full)
SELECT <columns>,
       VERSIONS_STARTSCN,
       VERSIONS_ENDSCN,
       VERSIONS_OPERATION
FROM <table>
    VERSIONS BETWEEN {
        TIMESTAMP <start> AND <end>
      | SCN <start_scn> AND <end_scn>
    }
[ WHERE <conditions> ];

-- Cross-branch temporal join
SELECT a.*, b.*
FROM orders AS OF BRANCH 'prod' AT LSN 1000 a
JOIN inventory AS OF BRANCH 'staging' b ON a.product_id = b.id;

2.2 Integration with Existing Temporal Engine

The existing heliosdb-storage/src/temporal/ module has:

FlashbackEngine with SCN tracking
VersionControl for version management
HistoryStorage for historical data

Enhancement Strategy:

┌────────────────────────────────────────────────────────────────┐
│                    Query Parser                                │
│  Parse AS OF clause → TemporalSpec                            │
└────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌────────────────────────────────────────────────────────────────┐
│                 Temporal Spec Resolver                         │
├────────────────────────────────────────────────────────────────┤
│  resolve(spec: TemporalSpec) → (BranchId, Lsn, Scn)          │
│                                                                │
│  - TIMESTAMP → find_scn_at_timestamp() → Scn → Lsn           │
│  - LSN → direct use                                           │
│  - SCN → map_scn_to_lsn() → Lsn                              │
│  - BRANCH → resolve_branch() → (BranchId, Lsn)               │
└────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌────────────────────────────────────────────────────────────────┐
│              Page Request with Temporal Context                │
│  GetPageRequest { branch_id, lsn, page_id }                   │
└────────────────────────────────────────────────────────────────┘

2.3 Unified Resolution Interface

// Conceptual interface for HeliosDB Full
pub enum TemporalSpec {
    Timestamp(DateTime<Utc>),
    Lsn(Lsn),
    Scn(Scn),
    Branch { name: String, point: Option<Box<TemporalSpec>> },
    SystemTime(DateTime<Utc>),  // SQL:2011
}

pub trait TemporalResolver {
    /// Resolve any temporal spec to canonical (BranchId, Lsn)
    fn resolve(&self, spec: TemporalSpec) -> Result<(BranchId, Lsn)>;

    /// Resolve to SCN for Oracle compatibility
    fn resolve_to_scn(&self, spec: TemporalSpec) -> Result<Scn>;

    /// Validate temporal spec is within retention window
    fn validate_retention(&self, spec: &TemporalSpec) -> Result<()>;
}

2.4 Protocol Compatibility

Protocol	Native Syntax	Mapping
PostgreSQL	N/A (extension)	`AS OF` clause
Oracle	`AS OF TIMESTAMP/SCN`	Direct compatibility
Snowflake	`AT (TIMESTAMP => ts)`	Syntax transformation
Databricks	`VERSION AS OF`	Map to LSN

Feature 3: MV Auto-Refresh Logic

Knowledge from HeliosDB-Lite

Design Pattern: CPU-aware, staleness-based intelligent refresh

Key Components:

CPU Monitor: Track system CPU usage
Staleness Threshold: Refresh when data freshness drops below threshold
Priority Queue: Prioritize critical views
Delta Tracking: Incremental refresh via change capture

// HeliosDB-Lite approach
pub struct SchedulerConfig {
    pub max_cpu_percent: f32,      // Don't exceed this CPU
    pub check_interval_secs: u64,  // How often to check
    pub default_priority: Priority,
}

pub struct RefreshTask {
    pub view_name: String,
    pub priority: Priority,       // Critical, High, Medium, Low
    pub staleness: f64,           // 0.0 = fresh, 1.0 = completely stale
}

Adaptation for HeliosDB Full

3.1 Distributed CPU-Aware Scheduling

HeliosDB Full’s heliosdb-materialized-views already has ML-based optimization. Enhancement: Add resource-aware scheduling.

┌─────────────────────────────────────────────────────────────────┐
│                 Distributed MV Scheduler                        │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐        │
│  │ Node 1      │    │ Node 2      │    │ Node 3      │        │
│  │ CPU: 45%    │    │ CPU: 78%    │    │ CPU: 23%    │        │
│  │ MV: view_a  │    │ MV: view_b  │    │ MV: view_c  │        │
│  └─────────────┘    └─────────────┘    └─────────────┘        │
│         │                 │                   │                │
│         └─────────────────┴───────────────────┘                │
│                           │                                    │
│                           ▼                                    │
│  ┌─────────────────────────────────────────────────────────┐  │
│  │            Resource-Aware Task Distributor              │  │
│  │  - Route refresh to least-loaded node                   │  │
│  │  - Respect per-node CPU limits                          │  │
│  │  - Coordinate cross-node dependencies                   │  │
│  └─────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────┘

3.2 Enhanced Configuration Model

-- Extended CREATE MATERIALIZED VIEW syntax
CREATE MATERIALIZED VIEW <name> AS <query>
WITH (
    -- Refresh strategy
    maintenance_strategy = { incremental | deferred | on_demand | immediate },

    -- Resource limits (from HeliosDB-Lite)
    max_cpu_percent = <0-100>,           -- Per-node CPU limit
    max_cluster_cpu_percent = <0-100>,   -- Cluster-wide limit

    -- Staleness control (from HeliosDB-Lite)
    staleness_threshold = <0.0-1.0>,     -- Trigger refresh at this staleness
    max_staleness_seconds = <seconds>,   -- Time-based staleness

    -- Priority (from HeliosDB-Lite)
    priority = { critical | high | medium | low },

    -- Existing Full features
    enable_genetic_algorithm = { true | false },

    -- Distributed options
    preferred_nodes = '<node_list>',
    refresh_parallelism = <degree>
);

3.3 Staleness Calculation Model

Adapt HeliosDB-Lite’s staleness model for distributed environment:

Staleness(view, t) = f(
    time_since_refresh,      // Time-based component
    delta_count,             // Change-based component
    query_frequency,         // Usage-based component
    dependency_staleness     // Cascading staleness
)

// Distributed enhancement
Distributed_Staleness(view, t) = max(
    Staleness(view, node_1),
    Staleness(view, node_2),
    ...
)

3.4 Integration with Existing ML Pipeline

┌─────────────────────────────────────────────────────────────────┐
│          Enhanced MV Management Pipeline                        │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  [Existing]                    [From HeliosDB-Lite]            │
│  WorkloadAnalyzer              ┌────────────────────┐          │
│       │                        │ Resource Monitor   │          │
│       ▼                        │ - CPU per node     │          │
│  CandidateGenerator ◄──────────│ - Memory usage     │          │
│       │                        │ - I/O bandwidth    │          │
│       ▼                        └────────────────────┘          │
│  CostBenefitAnalyzer ◄─────────┬────────────────────┐          │
│       │                        │ Staleness Tracker  │          │
│       ▼                        │ - Per-view metrics │          │
│  [Genetic/Greedy]              │ - Delta counters   │          │
│  Optimizer                     └────────────────────┘          │
│       │                                                        │
│       ▼                                                        │
│  RefreshScheduler ◄────────────┬────────────────────┐          │
│       │                        │ Priority Queue     │          │
│       ▼                        │ - CPU-aware        │          │
│  IncrementalRefreshEngine      │ - Node-aware       │          │
│                                └────────────────────┘          │
└─────────────────────────────────────────────────────────────────┘

Feature 4: REPL Meta Commands

Knowledge from HeliosDB-Lite

Design Pattern: PostgreSQL-style backslash commands for database exploration

Key Commands from Lite:

\branches         - List database branches
\use <branch>     - Switch to branch
\snapshots        - List time-travel snapshots
\dmv              - List materialized views
\dmv <view>       - Describe MV with staleness info
\compression      - Show compression statistics
\lsn              - Toggle LSN display

Adaptation for HeliosDB Full

4.1 Extended Command Set

The existing CLI at heliosdb-cli/src/commands.rs should be extended:

┌─────────────────────────────────────────────────────────────────┐
│              HeliosDB Full Extended Meta Commands               │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  BRANCH MANAGEMENT                                              │
│  ─────────────────                                              │
│  \branches              List all branches with status           │
│  \branches <pattern>    Filter branches by pattern              │
│  \use <branch>          Switch session to branch                │
│  \branch info <name>    Show branch details (LSN, nodes, etc)   │
│  \branch tree           Show branch hierarchy as tree           │
│  \branch diff <a> <b>   Compare two branches                    │
│                                                                 │
│  TIME-TRAVEL                                                    │
│  ───────────                                                    │
│  \snapshots             List available snapshots                │
│  \snapshots <table>     List snapshots for specific table       │
│  \retention             Show retention policies                 │
│  \scn                   Show current SCN                        │
│  \lsn                   Show current LSN                        │
│  \timeline              Show LSN/SCN timeline                   │
│                                                                 │
│  MATERIALIZED VIEWS                                             │
│  ──────────────────                                             │
│  \dmv                   List MVs with staleness                 │
│  \dmv <view>            Describe MV schema and stats            │
│  \dmv staleness         Show staleness for all MVs              │
│  \dmv refresh <view>    Trigger manual refresh                  │
│  \dmv deps <view>       Show MV dependencies                    │
│                                                                 │
│  DISTRIBUTED STATUS                                             │
│  ──────────────────                                             │
│  \nodes                 List storage/compute nodes              │
│  \shards <table>        Show shard distribution                 │
│  \replication           Show replication status                 │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

4.2 Implementation Structure

// Extend existing BackslashCommand enum
pub enum BackslashCommand {
    // Existing commands...
    Quit,
    Help,
    Timing(bool),
    // ...

    // Branch commands (from HeliosDB-Lite knowledge)
    ListBranches { pattern: Option<String> },
    UseBranch(String),
    BranchInfo(String),
    BranchTree,
    BranchDiff { branch_a: String, branch_b: String },

    // Time-travel commands (from HeliosDB-Lite knowledge)
    ListSnapshots { table: Option<String> },
    ShowRetention,
    ShowScn,
    ShowLsn,
    ShowTimeline { limit: Option<usize> },

    // MV commands (from HeliosDB-Lite knowledge)
    ListMaterializedViews,
    DescribeMaterializedView(String),
    MvStaleness,
    MvRefresh(String),
    MvDependencies(String),
}

4.3 Output Formatting for Distributed Context

heliosdb=> \branches
┌──────────────────┬────────────┬─────────────┬──────────────┬────────────┐
│ Name             │ State      │ Current LSN │ Storage Node │ Created    │
├──────────────────┼────────────┼─────────────┼──────────────┼────────────┤
│ main             │ Active     │ 0/00001A3F  │ node-1       │ 2025-11-01 │
│ feature-auth     │ Active     │ 0/00001B2E  │ node-2       │ 2025-11-28 │
│ staging          │ ReadOnly   │ 0/00001900  │ node-1       │ 2025-11-15 │
└──────────────────┴────────────┴─────────────┴──────────────┴────────────┘
(3 branches)

heliosdb=> \use feature-auth
Switched to branch: feature-auth (LSN: 0/00001B2E, Node: node-2)

heliosdb[feature-auth]=> \dmv staleness
┌──────────────────┬───────────┬──────────────┬──────────┬────────────────┐
│ View             │ Staleness │ Last Refresh │ Priority │ Next Scheduled │
├──────────────────┼───────────┼──────────────┼──────────┼────────────────┤
│ user_summary     │ 0.12      │ 5 min ago    │ High     │ 10 min         │
│ order_analytics  │ 0.78      │ 2 hours ago  │ Medium   │ Pending        │
│ inventory_cache  │ 0.02      │ 30 sec ago   │ Critical │ On-demand      │
└──────────────────┴───────────┴──────────────┴──────────┴────────────────┘

Feature 5: REPL Shell Design

Knowledge from HeliosDB-Lite

Design Patterns:

Branch-Aware Prompt: Show current branch in prompt
Multi-line SQL: Buffer incomplete statements
Context Persistence: Remember branch across commands
Completion: Auto-complete table, branch, view names

// HeliosDB-Lite prompt pattern
let prompt = format!(
    "{} {} ",
    "heliosdb".green().bold(),
    format!("[{}]", &self.current_branch).cyan()
) + ">";

Adaptation for HeliosDB Full

5.1 Enhanced Prompt Design

┌─────────────────────────────────────────────────────────────────┐
│                    Prompt State Machine                         │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Normal Mode:                                                   │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │ heliosdb[main]@node-1=> _                               │   │
│  │    │      │      │                                      │   │
│  │    │      │      └── Connected storage node             │   │
│  │    │      └── Current branch                            │   │
│  │    └── Database name                                    │   │
│  └─────────────────────────────────────────────────────────┘   │
│                                                                 │
│  Time-Travel Mode (after AS OF):                               │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │ heliosdb[main@LSN:0/1A3F]=> _                           │   │
│  │                │                                        │   │
│  │                └── Temporal context indicator           │   │
│  └─────────────────────────────────────────────────────────┘   │
│                                                                 │
│  Transaction Mode:                                              │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │ heliosdb[main]*=> _                                     │   │
│  │               │                                         │   │
│  │               └── Active transaction indicator          │   │
│  └─────────────────────────────────────────────────────────┘   │
│                                                                 │
│  Multi-line Continuation:                                       │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │ heliosdb[main]=> SELECT                                 │   │
│  │ heliosdb[main]->   *                                    │   │
│  │ heliosdb[main]->   FROM users                           │   │
│  │ heliosdb[main]->   WHERE active;                        │   │
│  └─────────────────────────────────────────────────────────┘   │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

5.2 Session State Model

// Enhanced session state for HeliosDB Full
pub struct ReplSession {
    // Connection
    connection: ConnectionManager,

    // Branch context (from HeliosDB-Lite)
    current_branch: Option<BranchId>,
    branch_name: String,

    // Temporal context (from HeliosDB-Lite)
    temporal_context: Option<TemporalContext>,

    // Distributed context
    preferred_node: Option<StorageNodeId>,
    compute_endpoint: ComputeEndpointId,

    // Display preferences
    show_lsn: bool,
    show_scn: bool,
    show_timing: bool,
    output_format: OutputFormat,

    // Multi-line handling (from HeliosDB-Lite)
    statement_buffer: String,

    // Completion state
    completer: HeliosCompleter,
}

pub struct TemporalContext {
    pub spec: TemporalSpec,
    pub resolved_lsn: Lsn,
    pub resolved_scn: Option<Scn>,
}

5.3 Auto-Completion Enhancement

// Enhanced completer with branch/temporal awareness
pub struct HeliosCompleter {
    // Existing
    tables: Vec<String>,
    columns: HashMap<String, Vec<String>>,

    // From HeliosDB-Lite patterns
    branches: Vec<String>,
    snapshots: Vec<String>,
    materialized_views: Vec<String>,

    // SQL keywords with temporal extensions
    keywords: Vec<&'static str>,
}

impl HeliosCompleter {
    fn complete_after_as_of(&self, partial: &str) -> Vec<String> {
        // Suggest: TIMESTAMP, LSN, SCN, BRANCH, SYSTEM_TIME
        vec!["TIMESTAMP", "LSN", "SCN", "BRANCH", "SYSTEM_TIME"]
            .into_iter()
            .filter(|k| k.starts_with(&partial.to_uppercase()))
            .map(String::from)
            .collect()
    }

    fn complete_branch_name(&self, partial: &str) -> Vec<String> {
        self.branches.iter()
            .filter(|b| b.starts_with(partial))
            .cloned()
            .collect()
    }
}

Feature 6: Branch Merge Strategies

Knowledge from HeliosDB-Lite

Design Pattern: Git-like three-way merge with configurable strategies

// HeliosDB-Lite merge model
pub enum MergeStrategy {
    Ours,      // Keep target branch on conflict
    Theirs,    // Keep source branch on conflict
    Abort,     // Stop on any conflict
}

pub struct MergeResult {
    pub success: bool,
    pub merged_pages: u64,
    pub conflicts: Vec<MergeConflict>,
    pub new_lsn: Lsn,
}

pub struct MergeConflict {
    pub page_id: PageId,
    pub source_value: Bytes,
    pub target_value: Bytes,
    pub base_value: Option<Bytes>,  // From common ancestor
}

Adaptation for HeliosDB Full

6.1 Enterprise Merge Strategy Model

// Enhanced for distributed, enterprise environment
pub enum MergeStrategy {
    // Basic strategies (from HeliosDB-Lite)
    Ours,
    Theirs,
    Abort,

    // Enterprise additions
    Manual {
        conflict_table: String,  // Store conflicts for manual resolution
    },

    // Automatic resolution rules
    RuleBased {
        rules: Vec<ConflictResolutionRule>,
    },

    // Timestamp-based (newer wins)
    LastWriteWins,

    // Custom function
    Custom {
        resolver_function: String,  // UDF name
    },
}

pub struct ConflictResolutionRule {
    pub table_pattern: String,      // Regex for table names
    pub column_pattern: String,     // Regex for column names
    pub strategy: SimpleStrategy,   // How to resolve
}

pub enum SimpleStrategy {
    PreferSource,
    PreferTarget,
    PreferNewer,
    PreferOlder,
    Concatenate,     // For arrays/lists
    Sum,             // For numeric counters
    Max,             // For version numbers
    Min,
}

6.2 Distributed Merge Coordination

┌─────────────────────────────────────────────────────────────────┐
│                 Distributed Merge Coordinator                   │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  MERGE BRANCH 'feature' INTO 'main' USING STRATEGY OURS        │
│                                                                 │
│  Phase 1: Analyze                                               │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │ 1. Find common ancestor (LCA in branch tree)            │   │
│  │ 2. Identify changed pages on both branches              │   │
│  │ 3. Classify: no-conflict, auto-resolvable, conflict     │   │
│  │ 4. Generate merge plan                                  │   │
│  └─────────────────────────────────────────────────────────┘   │
│                                                                 │
│  Phase 2: Validate (DRY RUN)                                   │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │ 1. Check schema compatibility                           │   │
│  │ 2. Verify constraint satisfaction                       │   │
│  │ 3. Estimate resource requirements                       │   │
│  │ 4. Return preview without applying                      │   │
│  └─────────────────────────────────────────────────────────┘   │
│                                                                 │
│  Phase 3: Execute (Distributed)                                │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │ Node 1          Node 2          Node 3                  │   │
│  │ ├─ Pages 1-100  ├─ Pages 101-200 ├─ Pages 201-300      │   │
│  │ ├─ Apply merge  ├─ Apply merge   ├─ Apply merge        │   │
│  │ └─ Report       └─ Report        └─ Report             │   │
│  │                      │                                  │   │
│  │                      ▼                                  │   │
│  │              Coordinator commits                        │   │
│  └─────────────────────────────────────────────────────────┘   │
│                                                                 │
│  Phase 4: Finalize                                             │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │ 1. Update target branch LSN                             │   │
│  │ 2. Record merge metadata                                │   │
│  │ 3. Optionally delete source branch                      │   │
│  │ 4. Trigger dependent MV refreshes                       │   │
│  └─────────────────────────────────────────────────────────┘   │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

6.3 Merge Preview (Dry Run)

-- Dry run to preview merge
MERGE DATABASE BRANCH feature INTO main
    USING STRATEGY rule_based
    DRY RUN;

-- Output:
┌────────────────────────────────────────────────────────────────┐
│                      Merge Preview                              │
├────────────────────────────────────────────────────────────────┤
│ Source: feature (LSN: 0/00001B2E)                              │
│ Target: main (LSN: 0/00001A3F)                                 │
│ Common Ancestor: LSN 0/00001800                                │
├────────────────────────────────────────────────────────────────┤
│ Changes:                                                        │
│   - Tables modified: 5                                          │
│   - Pages to merge: 1,234                                       │
│   - Auto-resolvable: 1,230                                      │
│   - Conflicts: 4                                                │
├────────────────────────────────────────────────────────────────┤
│ Conflicts (showing first 4):                                    │
│   1. users.row_42 - concurrent update                          │
│   2. orders.row_1001 - delete vs update                        │
│   3. inventory.row_55 - constraint violation                   │
│   4. settings.row_1 - concurrent update                        │
├────────────────────────────────────────────────────────────────┤
│ Estimated time: 2.3 seconds                                    │
│ Estimated storage impact: +45 MB                               │
└────────────────────────────────────────────────────────────────┘

6.4 Conflict Resolution Table

For Manual strategy, store conflicts for later resolution:

-- Auto-created table for manual conflict resolution
CREATE TABLE _merge_conflicts_<merge_id> (
    conflict_id SERIAL PRIMARY KEY,
    table_name TEXT,
    page_id BIGINT,
    row_key BYTEA,
    source_value JSONB,
    target_value JSONB,
    base_value JSONB,
    resolution TEXT,  -- NULL until resolved
    resolved_by TEXT,
    resolved_at TIMESTAMP
);

-- User resolves conflicts
UPDATE _merge_conflicts_abc123
SET resolution = 'source', resolved_by = current_user
WHERE conflict_id = 1;

-- Complete merge after all conflicts resolved
COMPLETE MERGE <merge_id>;

Summary: Integration Roadmap

Phase 1: SQL Parser Extensions (Week 1-2)

Task	Target Module	Complexity
Branch SQL statements	`heliosdb-compute/parser`	Medium
Extended AS OF syntax	`heliosdb-compute/parser`	Low
MV WITH options	`heliosdb-compute/parser`	Low
MERGE DRY RUN	`heliosdb-compute/parser`	Medium

Phase 2: CLI Enhancement (Week 3-4)

Task	Target Module	Complexity
Branch meta commands	`heliosdb-cli/commands`	Low
Time-travel commands	`heliosdb-cli/commands`	Low
MV staleness commands	`heliosdb-cli/commands`	Low
Branch-aware prompt	`heliosdb-cli/repl`	Medium

Phase 3: MV Scheduler (Week 5-6)

Task	Target Module	Complexity
Resource monitor	`heliosdb-materialized-views`	Medium
Staleness tracker	`heliosdb-materialized-views`	Medium
CPU-aware scheduler	`heliosdb-materialized-views`	High
Distributed coordination	`heliosdb-materialized-views`	High

Phase 4: Merge Strategies (Week 7-8)

Task	Target Module	Complexity
Strategy enum extension	`heliosdb-branching`	Low
Rule-based resolver	`heliosdb-branching`	Medium
Distributed merge coordinator	`heliosdb-branching`	High
Conflict table management	`heliosdb-branching`	Medium

Appendix: Design Decision Matrix

Decision	HeliosDB-Lite Approach	HeliosDB Full Adaptation	Rationale
Branch granularity	Row-level COW	Keep page-level	Already implemented, better for distributed
Temporal resolution	Timestamp primary	LSN primary, timestamp secondary	LSN ordering essential for distributed
MV refresh	Single-node CPU check	Cluster-wide resource monitoring	Distributed workload balancing
Merge coordinator	Single-threaded	Distributed phases	Scale to large merges
Prompt context	Branch only	Branch + node + temporal	More visibility for operators

References

HeliosDB-Lite source: /home/claude/HeliosDB-Lite/
HeliosDB Full roadmap: docs/roadmap/V7_0_COMPLETE_ROADMAP.md
Branching crate: heliosdb-branching/src/
MV crate: heliosdb-materialized-views/src/
CLI crate: heliosdb-cli/src/
Temporal module: heliosdb-storage/src/temporal/