# How Apache Maka’s Runtime Host Manages the Session Lifecycle

> Discover how Apache Maka's Runtime Host manages the session lifecycle across five key phases: creation, activation, live streaming, draining, and termination. Learn about its coordinators and graceful shutdown.

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

---

**Apache Maka’s Runtime Host orchestrates a deterministic, state-driven session lifecycle through five distinct phases—creation, activation, live streaming, draining, and termination—using dedicated server-side coordinators that enforce single-lease semantics and graceful shutdown guarantees.**

The Apache Maka Runtime Host (RH) provides the server-side foundation for interactive AI sessions, ensuring that every session transitions through well-defined states while maintaining durability and consistency. Unlike simple connection managers, the RH implements a comprehensive lifecycle protocol that governs everything from UUID allocation to graceful host shutdown. This article examines the exact mechanics of how the Runtime Host manages session lifecycles according to the Apache Maka source code.

## The Five Phases of Session Lifecycle Management

The Runtime Host manages every session through a strict progression of phases, each handled by a specialized coordinator component.

### Creation and Catalog Registration

The lifecycle begins in [`packages/runtime-host/src/server/session-catalog-coordinator.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/server/session-catalog-coordinator.ts), where the **SessionCatalogCoordinator** persists a new session record, allocates a durable UUID, and registers the session in the `SessionCatalog` projection. This phase establishes the persistent identity of the session before any client connections are accepted.

### Activation and Admission Control

Before a client can attach, the session must pass through the **SessionAdmissionGate** ([`packages/runtime-host/src/server/session-admission-gate.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/server/session-admission-gate.ts)). This component, utilized by the **SessionContinuityCoordinator**, grants a *lease* that permits client attachment. The gate validates that the host is not currently draining and that the session is not already attached elsewhere, enforcing the critical **single active lease per session** guarantee.

### Live Streaming and Continuity

Once admitted, the **SessionContinuityCoordinator** ([`packages/runtime-host/src/server/session-continuity-coordinator.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/server/session-continuity-coordinator.ts)) manages WebSocket and IPC subscriptions. It buffers **SessionDelta** frames with strict resource limits: a maximum of 16 concurrent connections, 32 queued frames, and 256 KB of queued bytes per session. This coordinator also maintains a replayable transcript overlay using `SessionTranscriptOverlay`, enabling clients to resynchronize to any historical revision by replaying monotonically increasing deltas.

### Effect Application and Durability

During the live phase, the **SessionEffectCoordinator** ([`packages/runtime-host/src/server/session-effect-coordinator.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/server/session-effect-coordinator.ts)) applies side-effects such as tool result previews and transcript pagination to the in-memory projection. It tracks the `terminalPublicationFence` to gate the final commit of a turn, ensuring that transient effects remain durable without blocking the main execution flow.

### Draining and Graceful Shutdown

When the Runtime Host initiates shutdown, the **RuntimeHostControl** sets a `#draining` flag on all coordinators. As implemented in [`session-continuity-coordinator.ts`](https://github.com/apache/maka/blob/main/session-continuity-coordinator.ts) (lines 139-156), this phase rejects all new session admissions with a `host_draining` error code. Existing connections receive the error message *"Runtime Host is draining"*, allowing clients to gracefully terminate or migrate to another host.

### Termination and Catalog Cleanup

The final phase occurs when a session’s Turn graph closes and no live subscriptions remain. The **SessionCatalogCoordinator** marks the catalog entry as closed. According to [`runtime-policy-coordinator.ts`](https://github.com/apache/maka/blob/main/runtime-policy-coordinator.ts) (lines 463-467), if the host attempts to close a composition while any session remains active, it throws an `AggregateError`, ensuring that termination cannot occur while work is in progress.

## Core Lifecycle Guarantees

The Runtime Host enforces four architectural guarantees that prevent race conditions and data loss:

- **Single active lease per session**: The `SessionAdmissionGate` prevents duplicate connections; attempts to attach an already-connected session raise `Duplicate Runtime Host connection` (see [`session-continuity-coordinator.ts`](https://github.com/apache/maka/blob/main/session-continuity-coordinator.ts) line 295).
- **Deterministic replay**: The `SessionContinuityCoordinator` records every delta with a monotonic revision number, enabling disconnected clients to resume from any point via the transcript overlay.
- **Graceful draining**: When shutting down, the host aborts in-flight commands with explicit error messages and rejects new admissions with `host_draining`, preventing abrupt disconnections.
- **Consistent termination**: Sessions cannot close while turns remain live; the `RuntimePolicyCoordinator` validates this constraint before finalizing composition closure.

## Working with the Session Lifecycle in Practice

Client applications interact with these lifecycle phases through the **SessionManager** API ([`packages/runtime/src/session-manager.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/session-manager.ts)), which delegates to the Runtime Host via the `RuntimeMessageAuthority` and `RuntimeInteractionAuthority` layers.

### Creating a New Session

```typescript
import { SessionManager } from '@maka/runtime';

// Creates a session record in the Runtime Host catalog
const session = await SessionManager.createSession({
  name: 'My Research Session',
  // optional: parent session, initial messages, etc.
});
console.log('Session created:', session.sessionId);

```

### Subscribing to Live Events

```typescript
import { SessionClient } from '@maka/runtime';

// Obtains admission lease from SessionAdmissionGate
const client = new SessionClient(session.sessionId);
await client.connect();

client.on('text_delta', (ev) => {
  console.log('Model output:', ev.text);
});

client.on('session_lifecycle_changed', () => {
  console.error('The session was closed or the host is draining');
});

```

### Handling Host Draining Errors

```typescript
try {
  await client.sendToolResult(/* ... */);
} catch (err) {
  if (err.message.includes('Runtime Host is draining')) {
    // Gracefully back-off or retry after host restart
    await client.reconnectToAlternateHost();
  }
}

```

## Summary

- The Apache Maka Runtime Host implements a five-phase lifecycle (creation, activation, streaming, draining, termination) through specialized coordinators.
- **SessionCatalogCoordinator** handles persistence and UUID allocation, while **SessionAdmissionGate** enforces single-lease semantics.
- **SessionContinuityCoordinator** manages live streaming with hard limits on connections, frames, and memory usage.
- The draining phase explicitly signals clients via `host_draining` errors, enabling graceful migration during host shutdown.
- Termination is blocked if active turns exist, preventing data loss through `AggregateError` validation in [`runtime-policy-coordinator.ts`](https://github.com/apache/maka/blob/main/runtime-policy-coordinator.ts).

## Frequently Asked Questions

### How does the Runtime Host prevent multiple clients from connecting to the same session simultaneously?

The **SessionAdmissionGate** component enforces a single active lease per session. When a client attempts to connect, the gate checks the session’s current attachment state; if already leased, it raises a `Duplicate Runtime Host connection` error (as found in [`session-continuity-coordinator.ts`](https://github.com/apache/maka/blob/main/session-continuity-coordinator.ts) line 295). This ensures only one client holds the active connection at any time.

### What happens to active sessions when the Runtime Host shuts down?

When the host initiates shutdown, it sets an internal `#draining` flag on all coordinators. New session admissions are immediately rejected with the `host_draining` error code, while existing connections receive the error *"Runtime Host is draining"* (lines 139-156 in [`session-continuity-coordinator.ts`](https://github.com/apache/maka/blob/main/session-continuity-coordinator.ts)). This allows clients to detect the shutdown and gracefully save state or reconnect to a different host.

### How does the SessionContinuityCoordinator enable clients to resume after disconnection?

The coordinator maintains a `SessionTranscriptOverlay` that records every **SessionDelta** with a monotonically increasing revision number. When a client reconnects, it can request replay from any historical revision, receiving all buffered frames in order. This mechanism supports deterministic recovery without requiring the session to restart or lose context.

### What prevents a session from terminating while work is still in progress?

The **RuntimePolicyCoordinator** validates that no active turns exist before allowing composition closure. As implemented in lines 463-467 of [`runtime-policy-coordinator.ts`](https://github.com/apache/maka/blob/main/runtime-policy-coordinator.ts), attempting to close a composition while sessions remain active throws an `AggregateError`, ensuring that termination only occurs after all pending operations complete and subscriptions disconnect.