# How Operational State and Configuration Management Works in Apache Maka

> Learn how Apache Maka manages operational state and configuration using a robust SQLite database with lease-based API, automatic schema versioning, and atomic transactions for reliable data consistency.

- Repository: [The Apache Software Foundation/maka](https://github.com/apache/maka)
- Tags: internals
- Published: 2026-09-08

---

**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`](https://github.com/apache/maka/blob/main/packages/storage/src/operational-state-store.ts). This function returns an `OperationalStateDatabaseLease` that guarantees a single underlying SQLite connection and centralizes transaction boundaries.

```typescript
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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/packages/storage/src/sqlite-session-metadata-store.ts) validates the version before applying changes, preventing lost updates when multiple processes access the same session.

```typescript
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`](https://github.com/apache/maka/blob/main/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.

```typescript
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.