# Apache Maka Runtime Host Structure: A Deep Dive into the Kernel Architecture

> Explore the Apache Maka Runtime Host structure and kernel architecture. Discover its layered execution environment, handlers, listeners, and residency management for complete workspace lifecycle operations.

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

---

**The Apache Maka Runtime Host is a layered execution environment composed of a central kernel, pluggable composition handlers, transport listeners, and residency management systems that together manage the complete lifecycle of workspace operations from handshake to graceful shutdown.**

The Runtime Host structure in Apache Maka transforms static workspaces into live execution environments through a modular, layered architecture. According to the apache/maka source code, this system separates concerns across nine distinct layers—from transport framing to operation dispatch—enabling both ephemeral desktop sessions and long-running service hosts.

## The Nine Layers of the Runtime Host Architecture

The architecture divides responsibilities into distinct layers, each implemented in specific source files under `packages/runtime-host/src/`:

| Layer | Purpose | Main File |
|-------|---------|-----------|
| **Kernel** | Orchestrates the whole lifecycle (start‑up, hand‑shakes, idle shutdown, graceful termination). Holds the host state, residency tracking, and shutdown logic. | `host‑kernel.ts` |
| **Composition** | Supplies the concrete set of domain operation handlers and optional services (session continuity, client capabilities, host change feed). | `host‑composition.ts` |
| **Listeners** | Accept incoming connections. Two concrete listeners exist: a local IPC listener for the desktop client and a WebSocket listener for remote clients. | `listener‑set.ts` |
| **Transport** | Provides a framed, bi‑directional byte stream abstracted over IPC or WebSocket. Handles protocol framing, error translation, and message encoding/decoding. | `framed‑transport.ts` |
| **Connection Session** | Represents a single client connection. It parses the initial *hello* frame, runs the handshake, and then forwards every request to the kernel’s *operation handlers*. | `connection‑session.ts` |
| **Operation Dispatcher** | Merges the *static* host‑wide handlers (e.g., `host.status`, `access.credential.*`) with the **domain** handlers supplied by the composition, producing a single lookup table. | `operation‑dispatcher.ts` |
| **Residency Registry** | Tracks long‑lived resources (e.g., ongoing operations, background services) so the host can decide when it is idle and safe to shut down. | `host‑residency‑registry.ts` |
| **Access Authority** | Issues, rotates and revokes *access credentials* that authorize client transports. Connections are automatically aborted if a credential is revoked. | `access‑authority.ts` |
| **Control & Registration** | Writes a host registration file that other components (e.g., the client bootstrap) can discover. Handles removal on shutdown. | [`registration.ts`](https://github.com/apache/maka/blob/main/registration.ts) |

## Kernel and Lifecycle Orchestration

The `RuntimeHostKernel` class in `host‑kernel.ts` serves as the central orchestrator. Its `start()` method authenticates the root owner, initializes the listener set via `startLocalRuntimeHostListenerSet` or `startRuntimeHostServiceListenerSet`, and publishes the initial registration.

The kernel maintains internal state machines for **ephemeral mode** (short-lived processes that shut down when idle) and **service mode** (long-running background processes). It exposes `close()` to request a drain, which triggers the graceful shutdown sequence: publishing a *draining* registration, waiting for active operations to finish, aborting transports, and cleaning up the registration file.

## Connection Handling: From Listeners to Sessions

Incoming connections flow through a structured pipeline. The `listener‑set.ts` module creates transport listeners that wrap either IPC channels or WebSocket connections. When a listener accepts a new transport, it delegates to `RuntimeHostKernel.#accept()`, which adds the transport to the hand‑shaking set and invokes `#serveConnection()`.

The `#serveConnection()` method reads the first *hello* frame and validates protocol version, generation, and composition ID through `#admitHandshake()`. Successful handshakes instantiate a `RuntimeHostConnectionSession` from `connection‑session.ts`, which maintains the per‑client state loop. This session reads request frames, acquires operation leases via `#beginOperation()`, and forwards requests to the appropriate handlers.

## Operation Dispatch and Composition

The `operation‑dispatcher.ts` file implements the `composeOperationHandlers` function, which merges static host‑wide handlers with domain‑specific handlers provided by the composition. The composition, defined in `host‑composition.ts`, returns a map of operation strings to handler functions.

When a session processes a request, it calls `#operationHandlers` to resolve the target. The dispatcher combines built‑in handlers like `host.status` and `access.credential.*` with custom domain logic supplied by the composition's `create` method, enabling extensible operation routing without modifying kernel code.

## Residency Tracking and Idle Detection

Long‑lived operations acquire **residency** through `#acquireResidency()` managed by `host‑residency‑registry.ts`. Each residency represents a held resource that prevents the host from shutting down. When operations complete and release their residencies, the kernel checks if all residencies are cleared and the host is in the **ready** state.

In ephemeral mode, this condition arms an idle timer. If no new residencies are acquired before timeout, `#requestDrain()` initiates shutdown. In service mode, the host remains alive indefinitely until an explicit drain request or upgrade preparation triggers termination.

## Access Control and Registration

The `access‑authority.ts` module issues cryptographically secure credentials that authorize client transports. These credentials are validated during the handshake phase, and connections are automatically aborted if credentials are revoked mid‑session.

The [`registration.ts`](https://github.com/apache/maka/blob/main/registration.ts) module handles discovery by writing a host registration file to a well‑known location. Clients use this file to locate the host endpoint. During shutdown, the kernel ensures this registration is removed to prevent connection attempts to a terminating process.

## Practical Implementation Examples

### Starting an Ephemeral Runtime Host

To launch a host in ephemeral mode, invoke `RuntimeHostKernel.start()` with a composition factory and lifecycle configuration:

```typescript
import { RuntimeHostKernel } from '@maka/runtime-host';
import { bindStateRootComposition } from '@maka/storage/state-root-composition';

// Assume `owner` is an InteractiveRootOwner obtained from the storage layer.
const kernel = await RuntimeHostKernel.start({
  owner,
  composition: {
    // A simple composition that only registers a static "noop" domain handler.
    descriptor: { id: 'example', revision: '1' },
    create: async (ctx) => ({
      handlers: new Map(),
    }),
  },
  // Optional: custom listener set, access authority, etc.
  lifecycleMode: 'ephemeral',
});
console.log(`Runtime Host listening at ${kernel.endpoint}`);

```

This pattern, implemented in `host‑kernel.ts`, supports both local IPC listeners for desktop integration and WebSocket listeners for remote access.

### Defining Custom Domain Operations

Compositions inject domain logic by returning a handlers map:

```typescript
// In a composition file:
export const myComposition = {
  descriptor: { id: 'my-app', revision: '42' },
  async create(context) {
    return {
      handlers: new Map<string, any>([
        ['my.operation', async (input) => ({
          ok: true,
          result: `You sent: ${JSON.stringify(input)}`,
        })],
      ]),
    };
  },
};

```

The `handlers` map merges with host‑wide handlers inside `composeOperationHandlers` in `operation‑dispatcher.ts`.

### Client Handshake Protocol

Clients connect by sending a framed hello message:

```typescript
import { WebSocketTransport } from '@maka/runtime-host/transport/websocket-transport';
import { encodeProtocolMessage, decodeClientFrame } from '@maka/runtime-host/protocol';

const transport = new WebSocketTransport(url);
await transport.write(
  encodeProtocolMessage({
    kind: 'hello',
    protocolMin: 1,
    protocolMax: 1,
    compatibilityEpoch: 0,
    clientInstanceId: 'client‑123',
    // other hello fields…
  })
);
const reply = await transport.read(5000);
const helloReply = decodeClientFrame(reply);
console.log('Handshake result:', helloReply);

```

This aligns with the server's `#admitHandshake` validation logic in `host‑kernel.ts`.

### Triggering Graceful Shutdown

For explicit termination or idle timeout handling:

```typescript
// The kernel automatically arms an idle timer (see #scheduleIdleIfNeeded)
// For illustration we can request an explicit drain:
await kernel.close();   // same as calling #requestDrain()
await kernel.closed;    // resolves when shutdown finishes

```

The `#requestDrain` and `#commitShutdown` methods in `host‑kernel.ts` coordinate the orderly release of resources.

## Summary

- The **Runtime Host** architecture separates concerns across nine layers including the kernel, composition, transport, and residency systems.
- **host‑kernel.ts** contains the `RuntimeHostKernel` class that manages the full lifecycle from `start()` through graceful shutdown via `#requestDrain()`.
- Connections flow from **listeners** (`listener‑set.ts`) through **framed transports** (`framed‑transport.ts`) to **connection sessions** (`connection‑session.ts`) that handle the handshake protocol.
- The **operation dispatcher** (`operation‑dispatcher.ts`) merges static host handlers with domain‑specific composition handlers to route requests.
- **Residency tracking** (`host‑residency‑registry.ts`) enables idle detection in ephemeral mode while **access authority** (`access‑authority.ts`) secures transports with revocable credentials.

## Frequently Asked Questions

### What is the difference between ephemeral and service mode in the Maka Runtime Host?

**Ephemeral mode** configures the host to shut down automatically when all operations complete and residencies are released, making it ideal for desktop client sessions. **Service mode** keeps the host running indefinitely as a background process, requiring explicit drain requests to initiate shutdown, which suits long‑running server deployments.

### How does the Runtime Host ensure secure client connections?

According to `access‑authority.ts`, the host issues cryptographically signed access credentials during registration that authorize specific transports. The kernel validates these during the handshake phase in `#admitHandshake()`, and the access authority automatically aborts any connection if its credential is revoked or rotated.

### What happens during the graceful shutdown sequence?

The shutdown sequence, implemented in `#commitShutdown` within `host‑kernel.ts`, first publishes a *draining* registration to signal clients, then waits for active operations to finish or the deadline to expire. It aborts remaining transports, revokes credentials, closes listeners, and removes the registration file. If the deadline expires, a `RuntimeHostProcessTerminationRequiredError` forces immediate process termination.

### How are domain-specific operations integrated into the host?

Domain operations are integrated through the **composition** layer defined in `host‑composition.ts`. Developers provide a `create` function that returns a map of operation names to handler functions. The `composeOperationHandlers` function in `operation‑dispatcher.ts` merges these with built‑in handlers like `host.status`, enabling extensible command routing without kernel modifications.