RealDataStorage

Production-ready SQLite-based implementation of DataStorage interface for Project KARL.

This class provides persistent storage capabilities for the KARL adaptive reasoning system, replacing in-memory storage with durable SQLite database persistence. The implementation manages two primary data domains: container states and user interaction histories.

Architecture & Design:

• Database Engine: SQLite JDBC for lightweight, embedded persistence

• Connection Management: Single connection per instance with proper lifecycle management

• Concurrency: All database operations execute on Dispatchers.IO for non-blocking behavior

• Schema Design: Normalized tables with optimized indexing for query performance

• Error Handling: Comprehensive exception handling with logging for debugging

Database Schema:

-- Container States Table
CREATE TABLE container_states (
    user_id TEXT PRIMARY KEY,        -- Unique user identifier
    state_data BLOB NOT NULL,        -- Serialized KarlContainerState data
    version INTEGER NOT NULL,        -- State version for conflict resolution
    created_at INTEGER DEFAULT NOW,  -- Creation timestamp (Unix epoch)
    updated_at INTEGER DEFAULT NOW   -- Last modification timestamp
);

-- Interaction Data Table
CREATE TABLE interaction_data (
    id INTEGER PRIMARY KEY AUTOINCREMENT,  -- Unique interaction ID
    user_id TEXT NOT NULL,                 -- Associated user identifier
    type TEXT NOT NULL,                    -- Interaction type classification
    details TEXT NOT NULL,                 -- JSON-serialized interaction details
    timestamp INTEGER NOT NULL,            -- Interaction timestamp (Unix epoch)
    created_at INTEGER DEFAULT NOW         -- Database insertion timestamp
);

-- Performance Index
CREATE INDEX idx_interaction_user_timestamp
ON interaction_data(user_id, timestamp DESC);

Data Flow Patterns:

1. State Persistence: Container states are serialized as BLOB data with versioning

2. Interaction Logging: User interactions stored as structured events with timestamps

3. Query Optimization: Indexed queries for efficient historical data retrieval

4. Cleanup Operations: Bulk deletion support for user data management

Threading & Concurrency:

• All database operations use withContext(Dispatchers.IO) for proper coroutine context

• Thread-safe connection management with synchronized access patterns

• Non-blocking I/O operations suitable for reactive application architectures

Error Recovery:

• SQLException handling with detailed error logging

• Graceful degradation for failed operations

• Connection state validation and recovery mechanisms

Parameters

See also