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

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, 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:

// 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 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:

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
• acquireExecutionAuthority – Wraps the RootAuthority logic found in 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

The protocol definition in 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).
• Admission control through RootTurnCoordinator ensures every Session passes through a single validation gate before executing (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 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). 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 or the IPC trust validation in windows-runtime-host-local-ipc-trust.ps1.

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