Why Maka Uses One Runtime Host per State Root: Architecture Explained

Maka enforces a single Runtime Host per State Root to guarantee exclusive write authority, prevent race conditions, and provide a durable coordination point for all clients accessing the workspace.

In the Apache Maka codebase, persistent workspace data lives inside a State Root—a directory containing the SQLite database, migration files, and ancillary assets. The architecture mandates exactly one Runtime Host per State Root, creating a strict ownership model that serializes all mutations and centralizes session coordination for heterogeneous clients.

Exclusive Write Authority and Lock Management

The Runtime Host is the sole process permitted to hold the OS-level lock for a State Root. This exclusive ownership prevents concurrent write operations that could corrupt the SQLite database or violate session invariants.

In packages/storage/src/root-authority.ts, the tryAcquireInteractiveRootOwner function implements this guarantee. When a host attempts to acquire ownership, the function checks if another process already holds the lease. If the lock is taken, the call fails immediately, ensuring that only one Runtime Host can mutate the State Root at any time【root-authority.ts line 590】.

The Lease Mechanism

The lease mechanism returns a StorageRootLease object that grants write access until explicitly released. This durable lease survives process lifecycles and can be re-acquired after crashes, enabling deterministic recovery. The immutability of the State Root to non-owner processes means that even if the original host terminates unexpectedly, the data remains consistent for the next host that claims the lock.

Centralized Coordination for Diverse Clients

All client types—including Desktop applications, CLI tools, TUI interfaces, bots, and evaluation frameworks—communicate with the same Runtime Host rather than accessing the State Root directly. This design centralizes turn ordering, message queues, and session lifecycle management.

The host owns the coordination session for the WorkHub, as documented in docs/architecture/workhub-coordination-session-adr.md. By funneling all operations through a single authority, Maka ensures that complex distributed operations like turn-based updates and artifact writes maintain strict consistency without requiring distributed consensus protocols.

Recovery Semantics and Remote Deployment

Coupling a State Root to a single Runtime Host simplifies crash recovery and remote deployment scenarios. When a host upgrades or crashes, a fresh process can re-acquire the State Root's lease and continue operations from the exact database state left by the previous owner.

Remote clients identify targets using an immutable rootId that pins to a specific State Root. As implemented in docs/runtime-host-remote-access.md (lines 46-50), uninstalling a service preserves the State Root directory, allowing a new host to mount the workspace without data loss. The new host simply re-opens the same SQLite database and resumes coordination where the previous host stopped.

Architectural Invariants and Separation of Concerns

The docs/architecture/runtime-host-architecture.md file explicitly documents the "one Runtime Host per State Root" invariant (lines 39-43) as a core architectural principle. This separation of concerns isolates execution logic, storage management, and policy enforcement within the host boundary.

Other components delegate persistence operations to the host rather than re-implementing SQLite access or file system locks. This encapsulation keeps the codebase modular—the client packages handle protocol communication while packages/runtime-host/src/server/host-kernel.ts manages the actual state mutations and policy enforcement.

Implementation Examples

The following examples demonstrate how the single-host invariant manifests in the codebase.

Acquiring the Exclusive Host Lease

To become the Runtime Host for a State Root, a process must acquire the interactive root ownership:

import { tryAcquireInteractiveRootOwner } from '@maka/storage/root-authority';

// `capability` describes the State Root we want to own.
const owner = await tryAcquireInteractiveRootOwner(capability);
// `owner` is a `StorageRootLease` that grants write access until released.

The call succeeds only if no other host holds the lock; otherwise it throws an error【root-authority.ts line 590】.

Executing Workloads Under the Lease

Once the lease is acquired, the host executes client requests within the secured context:

import { resolveStorageRoot, runWithStorageRootLease } from '@maka/storage/root-authority';
import { executionComposition } from '@maka/runtime-host/server/execution-composition';

// Resolve (or create) the State Root and obtain its lease.
const root = await resolveStorageRoot({ rootId: 'my-state-root' });
await runWithStorageRootLease(root, async (lease) => {
  // The host kernel executes the client request inside the same lease.
  await executionComposition(lease, { command: 'maka run', args: [] });
});

All mutations performed inside runWithStorageRootLease are serialized through the single host that owns the lease, as implemented in packages/runtime-host/src/server/execution-composition.ts.

Client Connection and State Root Verification

Clients connect to the host and verify the rootId before submitting protocol messages:

import { connectOrSpawn } from '@maka/runtime-host/client/connect-or-spawn';

const client = await connectOrSpawn({
  rootId: 'my-state-root',
  hostEndpoint: 'unix:///run/maka-host.sock',
});
await client.request({ type: 'turn.message.submit', payload: { text: 'Hello' } });

The client validates that the host's rootId matches the expected State Root before transmitting any data, ensuring it talks to the correct authority【packages/runtime-host/src/client/connection.ts】.

Summary

• Exclusive locks prevent corruption: The tryAcquireInteractiveRootOwner function in packages/storage/src/root-authority.ts guarantees only one Runtime Host can write to a State Root at a time.
• Centralized coordination: All clients (Desktop, CLI, TUI, bots) communicate through the single host, which owns the WorkHub coordination session and maintains turn order.
• Deterministic recovery: Because the State Root is immutable to non-owners, crashed hosts can be replaced by new processes that re-acquire the lease and resume from the consistent database state.
• Simplified deployment: Remote clients pin to immutable rootId values, allowing services to be uninstalled and reinstalled without losing workspace data.
• Clean architecture: The invariant documented in runtime-host-architecture.md enforces separation of concerns, isolating persistence logic inside the host boundary.

Frequently Asked Questions

What happens if the Runtime Host crashes?

If the Runtime Host crashes or is terminated, the OS-level lock on the State Root is released. A new host process can then call tryAcquireInteractiveRootOwner to acquire the StorageRootLease and reopen the SQLite database. Because no other process could modify the data during the crash, the new host resumes from a consistent state and continues the WorkHub coordination session exactly where the previous host stopped.

Can multiple clients access the same State Root simultaneously?

Yes, multiple clients can access the same State Root concurrently, but they must all communicate through the single Runtime Host that owns the lease. Clients do not access the SQLite database or file system directly; instead, they send protocol messages to the host via endpoints like UNIX sockets. The host serializes these requests to prevent race conditions while allowing parallel client connections.

How does the single Runtime Host prevent data corruption?

The host prevents data corruption by holding an exclusive OS-level write lock on the State Root directory. The tryAcquireInteractiveRootOwner function in packages/storage/src/root-authority.ts fails if another process already owns the lease, ensuring that only one host can perform mutations such as session creation, turn updates, and artifact writes. This serializes all database transactions through a single authority, eliminating concurrent write conflicts.

What is contained within a State Root directory?

A State Root is a directory that encapsulates all persistent data for a Maka workspace. It contains the SQLite database file storing session state and turn history, database migration files for schema versioning, and ancillary assets such as uploaded artifacts or generated outputs. The Runtime Host exclusively manages this directory, ensuring ACID compliance and consistent backups across the entire workspace lifecycle.

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