What Is a State Root in Apache Maka? Architecture, Locking, and Persistence Explained

A State Root in Apache Maka is a durable directory that serves as the single source of truth for a runtime host's persisted workspace, identified by a unique rootId and protected by OS-level locking to enforce single-writer semantics.

In the Apache Maka ecosystem, persistent state management relies on a foundational abstraction that guarantees data integrity across process lifecycles. The State Root provides runtime hosts with a verified, exclusive workspace that survives restarts, service upgrades, and even runtime uninstallation. Understanding how Maka implements State Root identity verification, exclusive locking, and filesystem binding is essential for building resilient applications on this platform.

Defining the State Root Concept

At its core, a State Root is a filesystem directory that stores all persisted data for a Maka runtime host. Each State Root is identified by a unique, immutable rootId written to a hidden marker file named .maka-storage-root.json. This directory acts as the host's workspace, ensuring that all durable state remains consistent and recoverable.

The implementation distinguishes between the physical storage location and the logical identity of the root. According to the source code in packages/storage/src/root-authority.ts, the system binds the State Root to specific filesystem properties to prevent accidental data corruption or misplacement.

Internal Architecture and Identity Verification

The Marker File and rootId Persistence

The identity of a State Root begins with its marker file. In packages/storage/src/root-authority.ts (lines 31–44), the constant STORAGE_ROOT_MARKER_FILE defines the .maka-storage-root.json filename, and the ensureRootMarker function creates or validates this file.

This marker stores the unique rootId alongside filesystem metadata, creating a permanent record that survives directory moves or renames. When a host initializes, it reads this marker to confirm it is operating on the intended State Root.

Filesystem-Level Identity Binding

Maka strengthens State Root security by binding the directory's identity to its physical location on disk. The system records the device (dev) and inode (ino) numbers from the marker file and compares them against the current filesystem state.

If the underlying storage is remounted or the directory is copied to a new location (resulting in different inode numbers), Maka detects the mismatch. This binding ensures that a State Root cannot be inadvertently aliased or duplicated without explicit repair workflows.

Single-Writer Locking and Ownership

Maka enforces strict single-writer semantics to prevent concurrent host access. Only one runtime host can hold a write lease on a given State Root at any time.

The locking mechanism uses a private ownership namespace called state-root-owners. As implemented in packages/storage/src/root-authority.ts (lines 98–106), the acquireStateRootLock function creates a durable lock file within this namespace to guarantee exclusive access. The host must acquire this OS-level lock before performing reads, writes, or migrations on the directory.

A separate control directory holds auxiliary metadata for the active host, ensuring clear ownership semantics even when multiple hosts have visibility to the same filesystem paths.

Persistence Across Host Lifecycles

State Roots are designed for durability beyond the runtime process lifecycle. The persisted data survives host restarts, service upgrades, and even complete uninstallation of the runtime-host service.

The write lock persists only as long as the host process remains active. If the host crashes or shuts down gracefully, the lock is released, allowing another process to acquire ownership. However, the data remains intact in the State Root directory, enabling seamless recovery and restart scenarios.

Composition ID Integration

Hosts can bind a composition ID to a State Root, ensuring that the same runtime composition (e.g., the same version of the host binary) is used whenever the root is reopened. This mechanism, handled in packages/storage/src/state-root-composition.ts, prevents version mismatches that could corrupt the persisted state format.

When a host attempts to open a State Root with a mismatched composition ID, Maka can trigger appropriate migration or repair workflows to maintain compatibility.

Repair and Recovery Workflows

When filesystem events change the underlying storage characteristics—such as remounting a volume or restoring from backup—the dev and ino values may no longer match the marker file. Maka detects these mismatches during initialization and offers a repair flow.

The repair mechanism updates the marker file's filesystem metadata while preserving the original rootId, ensuring continuity of identity despite physical storage changes. This allows administrators to move State Roots between volumes or recover from snapshot backups without losing the logical workspace identity.

Practical Implementation: Acquiring and Using a State Root

The following TypeScript example demonstrates how to resolve a State Root path, acquire an exclusive write lock, and perform durable operations:

import { resolveStorageRoot, tryAcquireInteractiveRootOwner } from '@maka/storage';

// 1️⃣ Resolve (or create) a State Root at a given path.
//    This writes the marker file if it does not exist.
const capability = await resolveStorageRoot({
  path: '/home/user/.maka/state-root',
  kind: 'interactive',
});

// 2️⃣ Acquire an exclusive owner lease (write access).
const owner = await tryAcquireInteractiveRootOwner(capability);
if (!owner) {
  throw new Error('Another host already holds the write lock');
}

// 3️⃣ Use the lease to perform work inside the root.
await owner.lease.beginOperation()();   // start an operation
await runWithStorageRootLease(
  owner.lease,
  'interactive',
  'write',
  async (canonicalPath) => {
    // `canonicalPath` is the absolute path of the State Root.
    // Perform any persistent work here, e.g. write a file.
    await Deno.writeTextFile(`${canonicalPath}/example.txt`, 'hello');
  },
);
await owner.close();   // releases the lock

Key points illustrated:

• resolveStorageRoot creates or validates the marker file containing the rootId and inode data.
• tryAcquireInteractiveRootOwner obtains the exclusive lock ensuring only one writer can access the directory.
• runWithStorageRootLease executes async operations while verifying the root's identity remains unchanged.

Summary

• A State Root is a durable directory identified by a unique rootId stored in .maka-storage-root.json.
• Filesystem identity binding via device (dev) and inode (ino) numbers prevents accidental root relocation.
• Single-writer semantics are enforced through OS-level locks in the state-root-owners namespace.
• State Roots persist across host restarts, upgrades, and service uninstalls until explicitly released.
• Composition IDs bind specific runtime versions to State Roots, ensuring format compatibility.
• Repair workflows detect storage mismatches and update markers while preserving the original rootId.

Frequently Asked Questions

What file identifies a Maka State Root?

The hidden marker file .maka-storage-root.json identifies a State Root. This file contains the immutable rootId and filesystem metadata (dev and ino) that bind the directory to its physical storage location, as defined by STORAGE_ROOT_MARKER_FILE in packages/storage/src/root-authority.ts.

How does Maka enforce single-writer access to a State Root?

Maka uses an operating-system lock acquired via acquireStateRootLock in packages/storage/src/root-authority.ts (lines 98–106). This creates a lock file in the private state-root-owners namespace, ensuring only one host process can hold the write lease at any time.

What happens to a State Root when the host restarts?

The State Root persists indefinitely on disk. When the host process exits—whether through shutdown or crash—the OS releases the write lock, allowing a new host instance to acquire ownership. The data remains intact, enabling seamless recovery and restart without data loss.

How does Maka handle filesystem remounts or inode changes?

Maka detects mismatches between the stored dev/ino values and the current filesystem state during initialization. The system offers a repair flow that updates the marker file with new filesystem metadata while preserving the original rootId, allowing the State Root to remain functional after storage migrations or remounts.

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