SQLite Storage Schema for Runtime State Persistence in Apache Maka

Apache Maka persists all runtime state—including events, tool journal entries, and workspace versions—in a single SQLite database managed by the runtime schema defined in sqlite-runtime-schema.ts, using Write-Ahead Logging (WAL) mode, foreign-key constraints, and incremental migrations to version 12.

Apache Maka is an open-source framework for building reliable AI-native applications that require durable execution state. To guarantee crash-safe persistence of session data, tool invocations, and workspace history, Maka implements a comprehensive SQLite storage schema for runtime state persistence that enforces strict data integrity through foreign-key constraints, unique indexes, and ACID-compliant transactions configured for maximum durability.

Core Database Architecture

The runtime schema organizes state into specialized tables that separate canonical events from operational metadata. All tables are defined in packages/storage/src/sqlite-runtime-schema.ts and enforced with foreign-key constraints and CHECK clauses to prevent data corruption.

Event and Tool Journal Storage

Three primary tables manage the execution history:

• runtime_events — Stores canonical, ordered events for sessions, runs, and turns. Contains event_id, session_id, invocation_id, run_id, turn_id, event_seq, event_kind, payload_json, and committed_at timestamps. This table serves as the immutable ledger of execution history.
• tool_journal_events — Records every tool call with its state, arguments hash, recovery mode flags, and a foreign key linking to the resulting entry in runtime_events.
• tool_operations — Provides a high-level view of tool operations, linking call and result events while maintaining uniqueness constraints on the combination of invocation_id and provider_tool_call_id.

Workspace Versioning Tables

Maka implements immutable workspace history through three interconnected tables:

• runtime_workspace_epochs — Represents immutable workspace epochs that define points in history.
• runtime_workspace_versions — Stores version objects containing workspace state snapshots.
• runtime_workspace_heads — Maintains the current head pointer for each workspace, referencing the active workspace_version_id.

These tables enable time-travel debugging and deterministic replay by maintaining complete version lineage.

Runtime Capabilities and Continuation

Supporting infrastructure tables enable advanced features:

• runtime_capabilities — Declares enabled capabilities (recovery, continuation, workspace versioning) and their schema versions.
• runtime_continuation_claims — Tracks continuation claims that allow one session to safely resume another’s execution state.
• runtime_storage_root_binding — Binds the database to a unique storage-root identifier (64 hexadecimal characters) to prevent cross-contamination of data roots.
• runtime_partial_snapshots and runtime_partial_segments — Store streamed or partial UI state incrementally, referenced by stream_key for efficient updates.
• runtime_session_event_ordinals — Provides fast lookup of the global ordinal position for each event_id within a session, optimizing event ordering queries.

Note: The legacy headless_task_run_events table was removed in schema version 12 during migration.

Schema Versioning and Migration Strategy

The schema is strictly versioned with SQLITE_RUNTIME_SCHEMA_VERSION = 12. Maka applies changes incrementally through the migrateSqliteRuntimeDatabase() function located in packages/storage/src/sqlite-runtime-store.ts.

The migration system iterates through a versioned map of schema changes and updates the PRAGMA user_version after each successful step. This approach ensures that existing databases upgrade automatically when new application versions start, without manual intervention.

Data Integrity and Durability Configuration

Maka configures SQLite for production-grade reliability through specific pragmas applied in configureSqliteRuntimeDatabase():

Write-Ahead Logging (WAL) Mode — The database opens with WAL journal mode, allowing readers to operate concurrently with writers without blocking.

Synchronous Full — Setting PRAGMA synchronous = FULL ensures that SQLite waits for data to reach physical storage before reporting successful commits, preventing data loss during power failures or crashes.

Foreign Key Enforcement — All relationships between tables enforce referential integrity. For example, tool_journal_events maintains foreign keys to runtime_events, and workspace heads reference valid version IDs.

Constraints and Indexes — UNIQUE indexes prevent duplicate entries for tool operations and storage root bindings, while CHECK clauses validate data invariants at the database level.

Working with the Runtime Schema

Initializing the Database

To open or create the runtime database, use the utilities exported from sqlite-runtime-store.ts:

import { open } from 'node:sqlite';
import { 
  configureSqliteRuntimeDatabase, 
  migrateSqliteRuntimeDatabase 
} from './sqlite-runtime-store';

const db = await open({
  filename: '/home/you/.local/share/maka/maka.db',
  driver: require('sqlite3').Database,
});

configureSqliteRuntimeDatabase(db);
migrateSqliteRuntimeDatabase(db);

Recording Runtime Events

Insert canonical events into the runtime_events table to persist tool results or state changes:

const eventId = crypto.randomUUID();

db.exec(`
  INSERT INTO runtime_events (
    event_id, session_id, invocation_id, run_id, turn_id,
    event_seq, event_kind, payload_json, committed_at
  ) VALUES (
    '${eventId}', 'sess-1', 'inv-1', 'run-1', 'turn-1',
    1, 'tool_result', '{"output":"Hello"}', ${Date.now()}
  );
`);

Querying Workspace Versions

Retrieve the current workspace state by joining the heads table with version metadata:

const row = db.prepare(`
  SELECT wv.*
  FROM runtime_workspace_heads wh
  JOIN runtime_workspace_versions wv
    ON wh.workspace_version_id = wv.workspace_version_id
  WHERE wh.workspace_id = ?
`).get('my-workspace');

console.log('Current version ID:', row.workspace_version_id);

Graceful Shutdown

Always close the database connection to ensure all WAL checkpoints complete:

await db.close();

Summary

• Apache Maka uses a versioned SQLite schema (current version 12) defined in sqlite-runtime-schema.ts to persist runtime state.
• The schema separates concerns into event storage (runtime_events), tool journaling (tool_journal_events), and workspace versioning (runtime_workspace_versions).
• Foreign-key constraints, UNIQUE indexes, and CHECK clauses ensure referential integrity across all tables.
• The database operates in WAL mode with synchronous = FULL for crash-safe durability.
• Migrations are handled automatically by migrateSqliteRuntimeDatabase() in sqlite-runtime-store.ts, incrementally upgrading schemas from older versions.

Frequently Asked Questions

What is the current schema version for Maka's SQLite runtime database?

The current schema version is 12, defined as SQLITE_RUNTIME_SCHEMA_VERSION in sqlite-runtime-schema.ts. This version removed the legacy headless_task_run_events table and represents the latest incremental migration applied by migrateSqliteRuntimeDatabase().

How does Maka ensure data durability across application crashes?

Maka configures SQLite with Write-Ahead Logging (WAL) mode and PRAGMA synchronous = FULL, ensuring commits reach physical storage before acknowledgment. Combined with foreign-key constraints and ACID transactions, this prevents data corruption during unexpected terminations.

What is the difference between runtime_events and tool_journal_events?

The runtime_events table stores the canonical execution history for all sessions and turns, while tool_journal_events specifically tracks tool invocations with additional metadata like arguments hashes and recovery modes. The tool journal references runtime events via foreign keys but focuses on operational details required for deterministic replay and debugging.

How does the workspace versioning system work in the SQLite schema?

Workspace versioning uses three tables: runtime_workspace_epochs define immutable historical points, runtime_workspace_versions store actual state snapshots, and runtime_workspace_heads point to the current active version. This design enables Maka to maintain immutable history while supporting efficient queries for the latest workspace state through indexed joins.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}