# How Apache Maka's Runtime Host Manages Execution Authority: A Deep Dive into the Single Authority Model

> Discover how Apache Maka's Runtime Host manages execution authority using a single authority model. Learn about RootAuthority, RootTurnCoordinator, and lifecycle tracking.

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

---

**Apache Maka centralizes all execution control in a single Runtime Host that validates ownership through `RootAuthority`, admits work via `RootTurnCoordinator`, and maintains strict lifecycle tracking from startup to graceful shutdown.**

The Apache Maka project implements a unique security architecture where exactly one component—the Runtime Host—holds the **execution authority** for all operations. This design ensures that every desktop client, CLI tool, TUI interface, and automated bot must route requests through a single, auditable gatekeeper. Understanding how this authority is acquired, verified, and drained is essential for developers extending Maka's runtime capabilities.

## The Single Execution Authority Architecture

Apache Maka rejects distributed authority models in favor of a **hosted execution authority** pattern. According to the source code in `apache/maka`, no client or auxiliary service owns independent power to mutate system state. Instead, all components request admission from the Runtime Host, which maintains the sole capability to spawn top-level `Session` objects that own modules, stores, and scheduled tasks.

The architectural foundation rests on three pillars: **ownership verification** (ensuring the control directory belongs to the current user), **admission control** (validating requests before they enter the system), and **lifecycle tracking** (monitoring the authority from creation until resource cleanup). This centralized approach simplifies security auditing and guarantees that all state mutations flow through a single, well-defined path.

## Authority Acquisition and Ownership Verification

Before the Runtime Host can admit any work, it must acquire a **capability object** representing the execution authority. This process begins in [`packages/storage/src/root-authority.ts`](https://github.com/apache/maka/blob/main/packages/storage/src/root-authority.ts), where the `RootAuthority` class enforces strict filesystem requirements.

The `RootAuthority` API performs three critical checks before granting control:

- **`resolveStorageRoot`** – Locates or creates the private control directory under the user's data folder
- **`prepareStorageRootControlDirectory`** – Validates path permissions and privacy settings
- **`tryAcquireInteractiveRootOwner`** – Confirms the directory is owned by the current user and marked private (lines 1350–1388)

If these checks pass, the API returns a capability object that the host uses to establish its authority. The following diagnostic script from the release tooling demonstrates this acquisition pattern:

```typescript
// Example from release-cli-runtime-host-diagnostics.mjs
const authority = await importInstalled(
  'node_modules/@maka/storage/dist/root-authority.js',
);
const cap = await authority.resolveStorageRoot({ path: rootPath, kind: 'interactive' });
const owner = await authority.tryAcquireInteractiveRootOwner(cap);

```

This verification ensures that **only the operating system user who created the control directory** can subsequently claim the execution authority, preventing privilege escalation attacks from other users on the same machine.

## Admission and Lifecycle Management

Once the Runtime Host holds a valid capability, the `RootTurnCoordinator` in [`packages/runtime-host/src/server/root-turn-coordinator.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/server/root-turn-coordinator.ts) assumes responsibility for admission and lifecycle tracking. This coordinator implements a state machine that governs when the authority is active, draining, or terminated.

### Admission Protocol

When a client requests to start work, the coordinator validates the request against the execution authority at lines 630–650. This admission check creates the top-level `Session` that owns all subsequent modules and scheduled tasks. No `Session` can exist without first passing through this validation gate, ensuring that **all work inherits the same authority token**.

### Draining and Cleanup

The coordinator maintains a **drain flag** that signals when the Runtime Host is shutting down. When triggered, the coordinator:

1. Sets the reason string to `'Runtime Host execution authority is draining.'` (lines 2330–2338)
2. Rejects new admissions while allowing in-flight work to complete
3. Waits for all peers to disconnect before releasing resources
4. Cleans up the control directory only after confirming session termination

This graceful shutdown sequence prevents data corruption by ensuring that mutable state operations finish before the authority disappears.

## IPC Trust and Security Boundaries

Beyond filesystem ownership, Apache Maka enforces execution authority boundaries at the inter-process communication layer. On Windows platforms, the `scripts/windows-runtime-host-local-ipc-trust.ps1` script implements an additional security check at lines 21–22: **if a foreign user attempts to connect via local IPC, the script throws an exception and terminates the connection**.

This defense-in-depth strategy ensures that even if a malicious process gains access to the IPC endpoint, it cannot hijack the execution authority without matching the host owner's user credentials.

## Practical Implementation: Acquiring and Using Authority

Developers interact with this authority model through the high-level client API in `@maka/runtime-host`. The typical workflow involves connecting to an existing host or spawning a new process, acquiring the authority capability, and running sessions under that authority.

The following example demonstrates the complete lifecycle:

```typescript
import { RuntimeHost } from '@maka/runtime-host';

// 1️⃣ Launch (or attach to) the Runtime Host
const host = await RuntimeHost.connectOrSpawn({
  // optional: path to an existing host control directory
  controlRoot: '/Users/me/.maka/runtime-host',
});

// 2️⃣ Acquire the execution authority
const authority = await host.acquireExecutionAuthority();

// 3️⃣ Use the authority to run a session (high‑level API)
const session = await authority.runSession({
  name: 'interactive‑demo',
  // the session's composition (stores, scheduled tasks, etc.)
  composition: myComposition,
});

// 4️⃣ Await completion and then release the authority
await session.waitForCompletion();
await authority.release();   // triggers graceful shutdown if last client

```

Key implementation points in the source tree:

- **`RuntimeHost.connectOrSpawn`** – Client entry point located in [`packages/runtime-host/src/client/launcher.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/client/launcher.ts)
- **`acquireExecutionAuthority`** – Wraps the `RootAuthority` logic found in [`packages/runtime-host/src/control/access-credential-delivery.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/control/access-credential-delivery.ts)
- **`runSession`** – Creates new `Session` instances under the existing authority at [`packages/runtime-host/src/client/session-subscription.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/client/session-subscription.ts)

The protocol definition in [`packages/runtime-host/src/protocol/execution-model-authority.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/protocol/execution-model-authority.ts) specifies the authority token format exchanged over IPC and WebSocket connections, ensuring that all clients speak the same authority language when requesting work admission.

## Summary

- **Apache Maka maintains exactly one execution authority** per runtime instance, eliminating distributed state mutation risks.
- **Ownership verification** via `RootAuthority` guarantees that only the creating OS user controls the authority directory ([`packages/storage/src/root-authority.ts`](https://github.com/apache/maka/blob/main/packages/storage/src/root-authority.ts)).
- **Admission control** through `RootTurnCoordinator` ensures every `Session` passes through a single validation gate before executing ([`packages/runtime-host/src/server/root-turn-coordinator.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/server/root-turn-coordinator.ts)).
- **Graceful draining** prevents resource leaks by tracking the authority lifecycle from startup through cleanup, rejecting new work during shutdown while completing pending operations.
- **IPC trust boundaries** enforce user-matching requirements at the platform level, particularly on Windows (`scripts/windows-runtime-host-local-ipc-trust.ps1`).

## Frequently Asked Questions

### What is the Runtime Host execution authority in Apache Maka?

The Runtime Host execution authority is the **single, centralized capability** that owns all mutable state operations in Apache Maka. According to the architecture documentation and source code in `apache/maka`, no client can directly modify stores or schedule tasks; instead, they must request admission from the Runtime Host, which holds the sole authority to create and manage top-level `Session` objects.

### How does Apache Maka verify control directory ownership?

Ownership verification occurs in [`packages/storage/src/root-authority.ts`](https://github.com/apache/maka/blob/main/packages/storage/src/root-authority.ts) through the `tryAcquireInteractiveRootOwner` method (lines 1350–1388). This function checks that the control directory is owned by the current user, marked with private permissions, and located within the correct namespace before returning a capability object. The Windows platform adds an additional layer via `windows-runtime-host-local-ipc-trust.ps1`, which validates that IPC callers match the host's owner.

### What happens when the Runtime Host shuts down?

During shutdown, the `RootTurnCoordinator` sets a drain flag with the message `'Runtime Host execution authority is draining.'` (lines 2330–2338 in [`root-turn-coordinator.ts`](https://github.com/apache/maka/blob/main/root-turn-coordinator.ts)). The coordinator then rejects new admissions, waits for existing sessions to complete, confirms all peers have disconnected, and finally cleans up the control directory. This ensures **all pending work finishes before resources are released**, preventing data corruption.

### Can multiple execution authorities run simultaneously?

No. Apache Maka's architecture explicitly prohibits multiple concurrent execution authorities. The `RootTurnCoordinator` admits only one execution authority per host process, and the `RootAuthority` API enforces exclusive ownership of the control directory. Attempting to spawn a second authority from a different user or process will fail the ownership verification checks in [`root-authority.ts`](https://github.com/apache/maka/blob/main/root-authority.ts) or the IPC trust validation in `windows-runtime-host-local-ipc-trust.ps1`.