# Where Is Interactive Runtime State Stored in Apache Maka?

> Discover where Apache Maka stores interactive runtime state. Learn about its user-private storage, cache directory, and the `@maka/storage` package for efficient state management.

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

---

**Apache Maka stores interactive runtime state in a dedicated user-private storage root under the system cache directory, managed by the `@maka/storage` package through marker files, unique root IDs, and file-based locking.**

The interactive runtime state in Apache Maka persists data like command history, tool outputs, and invocation traces across sessions. Unlike transient memory, this state survives process restarts and is scoped to specific workspaces. The storage system in `apache/maka` implements a robust, platform-aware directory structure with guaranteed exclusive access during writes.

## How the Storage Root System Works

Apache Maka uses a **storage-root abstraction** to organize runtime data. Every storage root has a kind, a canonical path, and a durable identifier. For interactive sessions, this kind is explicitly set to `'interactive'`.

### Root Kind Identification

The `StorageRootKind` type distinguishes between different storage purposes. Interactive state uses the literal value `'interactive'` as defined in [`packages/storage/src/root-authority.ts`](https://github.com/apache/maka/blob/main/packages/storage/src/root-authority.ts):

```typescript
// lines 36-38
export type StorageRootKind = 'interactive' | 'workspace' | 'global';

const INTERACTIVE_KIND: StorageRootKind = 'interactive';

```

This kind value determines where files are placed and which locking semantics apply.

### Resolving a Storage Root

The entry point for accessing interactive state is `resolveStorageRoot()` in [`packages/storage/src/root-authority.ts`](https://github.com/apache/maka/blob/main/packages/storage/src/root-authority.ts) (lines 10-16). This function:

1. Verifies or creates a storage-root directory at the specified path
2. Writes a marker file [`.maka-storage-root.json`](https://github.com/apache/maka/blob/main/.maka-storage-root.json) containing metadata
3. Returns a `StorageRootCapability` with the canonical path and `rootId`

```typescript
import { resolveStorageRoot } from '@maka/storage';

const capability = await resolveStorageRoot({
  path: '/absolute/path/to/my-workspace',
  kind: 'interactive',
});
// capability.rootId: durable UUID for this root
// capability.path: verified absolute path

```

The `rootId` is a stable identifier that survives directory moves and renames because it's stored in the marker file, not derived from the path.

## Control Namespace: The Actual Storage Location

While the storage root has a logical path, the **interactive runtime state files** live in a separate **control namespace** directory. This separation keeps user data clean while allowing Maka to manage its own metadata.

### Platform-Specific Cache Directories

The function `resolveRootControlNamespace()` (lines 39-52 in [`root-authority.ts`](https://github.com/apache/maka/blob/main/root-authority.ts)) returns the base control directory:

```typescript
export function resolveRootControlNamespace(): string {
  // Linux  → $HOME/.cache/maka/runtime-hosts
  // macOS  → $HOME/Library/Caches/Maka/runtime-hosts
  // Windows → $HOME/AppData/Local/Maka/runtime-hosts
}

```

Each interactive root receives a private subdirectory named by its `rootId`:

```

$CONTROL_ROOT/
  <rootId>/
    usage.db          # SQLite database for interaction traces

    events.jsonl      # Append-only runtime event log

    snapshots/        # Periodic state snapshots

  <rootId>.lock       # Exclusive access lock file

```

### Persisted Data Types

The control directory contains multiple store types. The **usage-stores** implementation in [`packages/storage/src/usage-stores.ts`](https://github.com/apache/maka/blob/main/packages/storage/src/usage-stores.ts) (lines 146-156) creates SQLite databases and JSON files under this root for:

- Command invocation history
- Tool input/output streams
- Performance metrics
- Error traces

## Locking and Exclusive Access

Interactive state requires **exclusive write access** to prevent corruption from concurrent processes. The storage system implements advisory locking through three mechanisms in [`packages/storage/src/root-authority.ts`](https://github.com/apache/maka/blob/main/packages/storage/src/root-authority.ts):

| Function | Lines | Purpose |
|----------|-------|---------|
| `tryAcquireInteractiveRootOwner` | 90-94 | Attempt to become exclusive owner |
| `runWithStorageRootLease` | 127-136 | Execute operation with guaranteed lease |
| `acquireStateRootLock` | 804-810 | Low-level lock file implementation |

### Complete Workflow Example

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

// 1. Resolve the interactive storage root
const capability = await resolveStorageRoot({
  path: '/home/user/projects/my-app',
  kind: 'interactive',
});

// 2. Acquire exclusive ownership
const owner = await tryAcquireInteractiveRootOwner(capability);
if (!owner) {
  throw new Error('Another Maka process holds the interactive lock');
}

// 3. Perform stateful operations with automatic cleanup
await runWithStorageRootLease(
  owner.lease,
  'interactive',
  'write',
  async (rootPath) => {
    // rootPath resolves to:
    //   $HOME/.cache/maka/runtime-hosts/<rootId>
    
    const usageDbPath = `${rootPath}/usage.db`;
    // Open database, append interaction record, etc.
  }
);

```

The lease automatically releases the lock when the operation completes or throws, preventing deadlocks.

## On-Disk Layout Summary

For a workspace at `/home/user/projects/my-app` with `rootId = 'abc-123-def'`:

| Location | Contents |
|----------|----------|
| [`/home/user/projects/my-app/.maka-storage-root.json`](https://github.com/apache/maka/blob/main//home/user/projects/my-app/.maka-storage-root.json) | Marker file with `rootId` and metadata |
| `$HOME/.cache/maka/runtime-hosts/abc-123-def/` | **Interactive runtime state directory** |
| `$HOME/.cache/maka/runtime-hosts/abc-123-def.lock` | Active lock file (present when owned) |

This two-level structure (marker in workspace, data in cache) enables workspace portability while keeping runtime data centralized and cleanable.

## Key Source Files

The implementation spans these files in the `apache/maka` repository:

- **[`packages/storage/src/root-authority.ts`](https://github.com/apache/maka/blob/main/packages/storage/src/root-authority.ts)** — Core API for storage root lifecycle, marker management, and locking
- **[`packages/storage/src/usage-stores.ts`](https://github.com/apache/maka/blob/main/packages/storage/src/usage-stores.ts)** — Concrete store implementations that persist interaction data
- **[`packages/core/src/runtime-event.ts`](https://github.com/apache/maka/blob/main/packages/core/src/runtime-event.ts)** — Event definitions written into interactive storage

## Summary

- **Interactive runtime state** is stored in a **platform-specific cache directory** returned by `resolveRootControlNamespace()`
- Each workspace gets a **unique `rootId`** stored in a local marker file ([`.maka-storage-root.json`](https://github.com/apache/maka/blob/main/.maka-storage-root.json))
- Actual data files reside under `<control-root>/<rootId>/` including SQLite databases and JSON logs
- **Exclusive access** is enforced through file-based locks acquired via `tryAcquireInteractiveRootOwner()`
- The `@maka/storage` package provides `resolveStorageRoot()`, `runWithStorageRootLease()`, and related functions for safe, concurrent access

## Frequently Asked Questions

### What happens if multiple Maka processes access the same workspace?

Only one process can hold the interactive lock at a time. Subsequent calls to `tryAcquireInteractiveRootOwner()` return `null` until the lock is released. Processes should either wait with exponential backoff or operate in read-only mode using `runWithStorageRootLease` with `'read'` access.

### Can I relocate or delete the interactive state manually?

Yes. Deleting the control directory (`$HOME/.cache/maka/runtime-hosts/<rootId>`) removes all runtime history for that workspace. The next `resolveStorageRoot()` call will create fresh state. Deleting the marker file ([`.maka-storage-root.json`](https://github.com/apache/maka/blob/main/.maka-storage-root.json)) causes Maka to generate a new `rootId`, effectively orphaning the old control directory.

### How does Maka handle platform differences for the cache directory?

The `resolveRootControlNamespace()` function follows XDG Base Directory specifications on Linux, `Library/Caches/` conventions on macOS, and `AppData/Local/` on Windows. This ensures state persists appropriately across platform standards while remaining user-accessible for debugging or cleanup.

### Is the interactive state encrypted or protected from other users?

The control directory inherits standard filesystem permissions from the parent cache directory (typically `0700` on Unix systems). Maka does not currently implement application-level encryption for interactive runtime state; protection relies on operating system file permissions.