How Operational State and Configuration Management Works in Apache Maka

Apache Maka stores all durable runtime data in a single SQLite database called runtime.sqlite at the workspace root, using a lease-based API with automatic schema versioning and atomic transactions to ensure consistency across sessions.

Operational state and configuration management in Maka is centralized around a transactional SQLite ledger that persists workspace data, session metadata, and runtime policies. According to the apache/maka source code, the system employs a deterministic schema migration strategy and lease-based concurrency control to guarantee that every workspace opens with a current, consistent operational schema.

The SQLite-Backed Operational State Architecture

Workspace-Centric Database Design

Maka adopts a workspace-centric model where all durable runtime data lives in a single file named runtime.sqlite located at the root of each workspace. This file contains multiple schema scopes—including runtime, session-metadata, core-execution, workflow, usage, artifact, and others—that partition different aspects of the operational state into logical sections within the same database.

Lease-Based Database Acquisition

Clients interact with the operational state through the OperationalStateDatabaseOwner authority by calling acquireOperationalStateDatabase(workspaceRoot, options?) from packages/storage/src/operational-state-store.ts. This function returns an OperationalStateDatabaseLease that guarantees a single underlying SQLite connection and centralizes transaction boundaries.

import { acquireOperationalStateDatabase } from './operational-state-store.js';

const lease = acquireOperationalStateDatabase('/path/to/workspace');
console.log('DB path:', lease.databasePath);
console.log('Current schema version:', lease.database.user_version);
lease.close(); // releases the lease

The lease pattern ensures that only one logical owner controls the database connection at a time, preventing race conditions during critical operations.

Schema Versioning and Automatic Migration

Multi-Scope Schema Management

Each schema scope within runtime.sqlite maintains its version in the operational_schema_migrations table. When a lease is acquired, Maka runs inspectAndMigrateOperationalState to determine whether any scope requires migration before the workspace becomes operational.

Atomic Migration Process

The migration logic follows a strict four-step sequence implemented in packages/storage/src/operational-state-store.ts:

1. Inspection: Reads current versions via inspectOperationalStateSchema
2. Detection: Determines outdated scopes using needs_migration
3. Execution: Runs scope-specific migrations (migrateSqliteRuntimeDatabase, migrateSqliteSessionMetadataDatabase, etc.) inside a single transaction
4. Registration: Updates version records via registerSchema

This atomic process guarantees that migrations are all-or-nothing—either the entire workspace upgrades to the current schema version, or the transaction rolls back, leaving the database in its previous valid state.

Session Configuration and Metadata Storage

SessionHeader Structure

Per-session configuration resides in the session-metadata store, specifically within the session_metadata table. Each session has a SessionHeader containing fields such as backend, model, permissionMode, labels, llmConnectionId, and orchestrationMode. The SqliteSessionMetadataStore class provides the interface for reading and writing these headers.

Atomic Configuration Updates

Configuration changes use optimistic concurrency control through the expectedVersion parameter. The updateSessionConfiguration method in packages/storage/src/sqlite-session-metadata-store.ts validates the version before applying changes, preventing lost updates when multiple processes access the same session.

import { createSqliteSessionMetadataStore } from './sqlite-session-metadata-store.js';

const store = createSqliteSessionMetadataStore('runtime.sqlite');
const session = await store.readSessionAuthoritySnapshot('my-session');

await store.updateSessionConfiguration('my-session', {
  expectedVersion: session.record.header.version,
  configuration: {
    backend: 'openai',
    llmConnectionId: 'conn-123',
    llmConnectionSlug: 'openai-gpt-4',
    connectionLocked: false,
    model: 'gpt-4',
    thinkingLevel: 'high',
    permissionMode: 'managed',
    collaborationMode: 'single',
    orchestrationMode: 'deterministic',
    labels: ['demo', 'test'],
  },
  lifecycle: { kind: 'preserve' },
});

Runtime Policies and Higher-Level Configuration

Beyond session metadata, Maka stores higher-level policies in dedicated tables under the operational scope, such as runtime_policy. These structures handle complex operational data including onboarding transactions and OAuth receipts, accessed through modules like runtime-policy/credential-vault-document.ts in the storage package.

Backup, Safety, and Concurrency Guarantees

Transaction Boundaries

All writes proceed through the transaction(mode, operation) method, which opens BEGIN IMMEDIATE for write operations and BEGIN for reads. The lease automatically commits on success and rolls back on error, serializing concurrent updates and protecting against partial writes.

Backup Operations

Both the operational store and session-metadata store expose a backup(destinationPath) method that creates a full SQLite copy while preserving the lease reference count. The implementation validates that the backup target differs from the source and does not already exist, preventing accidental data loss.

import { acquireOperationalStateDatabase } from './operational-state-store.js';

const lease = acquireOperationalStateDatabase('/my/workspace');
await lease.backup('/my/backup/runtime-backup.sqlite');
lease.close();

Summary

• Operational state in Maka lives in a single runtime.sqlite file per workspace, managed through acquireOperationalStateDatabase leases.
• Schema versioning tracks multiple scopes in the operational_schema_migrations table, with automatic atomic migrations ensuring consistency across upgrades.
• Session configuration is stored in SessionHeader records within the session_metadata table, supporting atomic updates via version checking.
• Runtime policies utilize separate operational tables for complex configuration data like credentials and OAuth receipts.
• Concurrency and safety are enforced through SQLite transactions (BEGIN IMMEDIATE) and validated backup operations that protect data integrity.

Frequently Asked Questions

Where is operational state stored in Apache Maka?

Operational state is stored in a SQLite database file named runtime.sqlite located at the root of each workspace. This single file contains all durable runtime data across multiple schema scopes including runtime, session-metadata, workflow, and artifact storage.

How does Maka handle database schema migrations?

Maka inspects the operational_schema_migrations table during database acquisition to detect outdated schema scopes. If migrations are needed, it executes scope-specific migration functions inside a single atomic transaction, ensuring the workspace opens with a current schema version or remains in its previous valid state.

How can I update session configuration atomically?

Use the SqliteSessionMetadataStore.updateSessionConfiguration() method with the expectedVersion parameter set to the current header version. This implements optimistic concurrency control—if another process has modified the configuration since you read it, the update will fail rather than overwrite the changes.

What concurrency guarantees does Maka provide for operational state?

All database access occurs through leases that serialize connections, while writes use BEGIN IMMEDIATE transactions to lock the database immediately. The lease pattern combined with explicit transaction boundaries ensures that concurrent processes cannot corrupt the operational state through interleaved writes.

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