# How Apache Maka Handles the Five Fixed Recovery Phases During Startup

> Discover how Apache Maka manages five fixed recovery phases during startup: state, resources, executions, domains, and schedulers, ensuring a stable system before higher-level logic resumes.

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

---

**During Runtime Host startup, Apache Maka restores system state by executing a deterministic sequence of five recovery phases—state, resources, executions, domains, and schedulers—to guarantee that lower-level infrastructure is available before higher-level logic resumes.**

When the Apache Maka Runtime Host restarts after a crash or controlled shutdown, it must reconstruct its internal state in a strict dependency order. According to the source code in `apache/maka`, the framework defines a fixed pipeline in [`packages/runtime-host/src/server/host-composition.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/server/host-composition.ts) that orchestrates this process, ensuring that core state is loaded before external resources are connected, and business logic domains are initialized before schedulers begin driving periodic tasks.

## The Five Fixed Recovery Phases

The recovery sequence is declared as a constant array of string literals in [`host-composition.ts`](https://github.com/apache/maka/blob/main/host-composition.ts). These phases are processed in the exact order listed, creating an immutable contract for every startup:

```ts
export const HOST_RECOVERY_PHASES = [
  'state',
  'resources',
  'executions',
  'domains',
  'schedulers',
] as const;

```

Each phase represents a distinct layer of the system that must be restored before the next layer can safely initialize.

### State Recovery

The `state` phase recovers core durable data such as persisted Session information. This foundation must be established first because subsequent phases rely on knowing the system’s last known persistent state.

### Resource Recovery

The `resources` phase reconnects to external infrastructure including database connections, file handles, and external caches. These resources must be available before any execution context can be reconstructed, as resumed work will immediately attempt to use these connections.

### Execution Recovery

The `executions` phase restores metadata for ongoing or paused work, such as queued Turns. This phase requires both the persisted `state` and active `resources` to be present so that execution contexts can be accurately reconstructed with valid references to external systems.

### Domain Recovery

The `domains` phase initializes business-logic domains and their module-specific data. Domains depend on the restored `executions` to resume work in the correct logical context, ensuring that business rules operate against a consistent snapshot of pending operations.

### Scheduler Recovery

The `schedulers` phase starts scheduler services that drive periodic background tasks. This phase is intentionally last because scheduled work immediately invokes domain logic; therefore, `domains` must be fully recovered and consistent before timers begin firing.

## Orchestrating the Recovery Pipeline

The `recoverRuntimeHostDomainModules` function in [`packages/runtime-host/src/server/host-composition.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/server/host-composition.ts) implements the orchestration logic. It accepts an array of `RuntimeHostDomainModule` instances and iterates through the phases, invoking each module’s recovery handler in sequence:

```ts
export async function recoverRuntimeHostDomainModules(
  modules: readonly RuntimeHostDomainModule[],
): Promise<void> {
  assertUniqueModules(modules);
  for (const phase of HOST_RECOVERY_PHASES) {
    for (const module of modules) await module.recover(phase);
  }
}

```

This nested loop ensures that **all modules complete a given phase before any module proceeds to the next phase**. The architecture guarantees that when a module is asked to recover `'resources'`, every module has already finished recovering `'state'`, maintaining the dependency invariant across the entire host.

## Implementing Recovery in Domain Modules

Each `RuntimeHostDomainModule` implements a `recover(phase)` function that executes phase-specific work. The following example demonstrates a module that reconnects to its database during the `resources` phase and rebuilds domain caches during the `domains` phase:

```ts
import { RuntimeHostDomainModule, HostRecoveryPhase } from './host-composition';

const myModule: RuntimeHostDomainModule = {
  id: 'example',
  handlers: {},
  async recover(phase: HostRecoveryPhase) {
    if (phase === 'resources') {
      await myDb.connect();           // restore DB connection
    }
    if (phase === 'domains') {
      await loadDomainCache();        // rebuild domain-specific caches
    }
    // omitting state, executions, schedulers if not applicable
  },
  beginDrain() { /* ... */ },
  async close() { /* ... */ }
};

```

Modules can selectively respond to phases; they simply return early for phases that do not require action. This design keeps the orchestration logic generic while allowing specialized handling per phase.

## Architectural Integration

The recovery pipeline is triggered by the host lifecycle manager in [`packages/runtime-host/src/server/host-kernel.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/server/host-kernel.ts), which coordinates the overall startup sequence. During the recovery window, [`packages/runtime-host/src/server/operation-dispatcher.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/server/operation-dispatcher.ts) supplies default "unavailable" handlers to gracefully reject incoming requests until all phases complete. The architectural rationale for the five phases is also documented in [`docs/architecture/runtime-host-architecture.md`](https://github.com/apache/maka/blob/main/docs/architecture/runtime-host-architecture.md), which describes the dependency chain that mandates this specific ordering.

## Summary

- **Five fixed phases**—`state`, `resources`, `executions`, `domains`, `schedulers`—are defined in `HOST_RECOVERY_PHASES` in [`host-composition.ts`](https://github.com/apache/maka/blob/main/host-composition.ts)
- **Strict sequential order** ensures that lower-level infrastructure (state, resources) is ready before higher-level components (domains, schedulers) initialize
- **Double-loop orchestration** in `recoverRuntimeHostDomainModules` processes each phase completely across all modules before advancing
- **Module-level implementation** requires each `RuntimeHostDomainModule` to provide a `recover(phase)` method handling only the relevant lifecycle steps
- **Deterministic pipeline** guarantees consistent system restoration after any crash or shutdown, preventing race conditions between resource initialization and business logic execution

## Frequently Asked Questions

### What are the five fixed recovery phases in Apache Maka?

The five phases are `state` (core durable data), `resources` (external connections), `executions` (queued work metadata), `domains` (business logic modules), and `schedulers` (periodic task timers). They execute in exactly this order during every Runtime Host startup.

### Where is the recovery phase sequence defined in the Apache Maka source code?

The sequence is defined as a constant array in [`packages/runtime-host/src/server/host-composition.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/server/host-composition.ts) under the identifier `HOST_RECOVERY_PHASES`. The `recoverRuntimeHostDomainModules` function in the same file implements the iteration logic that enforces this order.

### How does a Domain Module participate in the startup recovery process?

Each module implements the `RuntimeHostDomainModule` interface and provides a `recover(phase: HostRecoveryPhase)` async method. The host calls this method for each of the five phases in order, allowing the module to execute phase-specific restoration logic such as reconnecting to databases or reloading caches.

### Why must schedulers be the final recovery phase?

Schedulers drive periodic background tasks that immediately invoke domain logic. If schedulers started before domains were fully initialized, scheduled work would execute against incomplete or inconsistent business logic state. By placing `schedulers` last, Apache Maka ensures that all underlying state, resources, executions, and domain contexts are consistent before any timers begin firing.