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

> Discover State Root in Apache Maka a durable directory and single source of truth for your runtime host's workspace. Learn about its architecture locking and persistence.

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

---

**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`](https://github.com/apache/maka/blob/main/.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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/packages/storage/src/root-authority.ts) (lines 31–44), the constant `STORAGE_ROOT_MARKER_FILE` defines the [`.maka-storage-root.json`](https://github.com/apache/maka/blob/main/.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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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:

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