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

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

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

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:

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

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:

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

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