# How Apache Maka's Resume Architecture Creates New Executions from Paused Runs

> Discover Apache Maka's resume architecture. Learn how it safely continues paused agent executions by creating new execution identities with the RuntimeContinuationPlanner.

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

---

**Apache Maka's resume architecture enables safe continuation of paused agent executions by validating workspace safety boundaries and generating fresh execution identities through the `RuntimeContinuationPlanner`.**

Apache Maka implements a sophisticated resume architecture that allows paused agent runs to be safely restarted without state corruption or identity collision. Rather than mutating existing run histories, the system creates entirely new execution identities that maintain lineage to their source runs. The core mechanism resides in [`packages/runtime/src/runtime-resume.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/runtime-resume.ts) and orchestrates safety validation, UUID generation, and admission through the runtime kernel.

## Core Components of the Resume Architecture

### RuntimeContinuationPlanner

The **`RuntimeContinuationPlanner`** class serves as the central orchestration engine for all resume operations in Apache Maka. Located in [`packages/runtime/src/runtime-resume.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/runtime-resume.ts), this component reads source run metadata, validates execution lineage, and constructs continuation plans. It exposes a single **`plan()`** method (lines 91-105) that returns either a valid continuation to execute or a rejection detailing specific safety violations.

### Safety Boundary Validation

Before creating any new execution, the planner executes six critical safety checks (lines 13-88 of [`runtime-resume.ts`](https://github.com/apache/maka/blob/main/runtime-resume.ts)):

- **Ledger readability verification** — Ensures the source run's event log is accessible
- **Terminal state consistency** — Validates the run terminated in an expected state
- **Workspace identity matching** — Confirms the current workspace matches the source
- **Current working directory (cwd) integrity** — Verifies the process cwd hasn't changed
- **Background operations settlement** — Confirms no pending async operations
- **Tool catalog compatibility** — Validates available tools match the source environment

If any check fails, the planner returns a *parked* plan containing `rejectionReasons` rather than a continuation.

### RuntimeContinuation Object

When safety checks pass, the system constructs a **`RuntimeContinuation`** object (lines 5-27) that encapsulates the new execution context:

- Fresh UUIDs for `invocationId`, `runId`, and `turnId`
- Immutable prefix copied from the source run
- Full runtime context including model-visible events
- Safety snapshot reflecting current workspace state
- Optional claim information for durable continuation authority

## How Apache Maka Creates New Executions

The creation of a new execution follows a strict six-phase pipeline orchestrated by the planner and kernel:

1. **Planning Phase** — The `RuntimeContinuationPlanner.plan()` method receives input parameters including `sessionId`, `sourceRunId`, `currentCwd`, and workspace identities.

2. **Safety Validation** — The planner verifies ledger accessibility, terminal consistency, workspace integrity, and background operation settlement. Failed checks immediately park the plan.

3. **Uniqueness Verification** — The system queries storage via **`findExistingContinuation()`** (lines 68-78) using the source run ID and high-water mark (last event sequence). If a continuation already exists, the planner returns a parked plan to prevent duplicates.

4. **ID Generation** — Upon passing all checks, **`buildSafeBoundaryContinuationPlan`** invokes `deps.newId()` to generate fresh identifiers:

```typescript
continuationIdentity: {
  invocationId: this.deps.newId(),
  runId: this.deps.newId(),
  turnId: this.deps.newId(),
},

```

5. **Continuation Assembly** — The new `RuntimeContinuation` aggregates the fresh IDs, source context, immutable prefixes, and safety snapshots (lines 104-124).

6. **Kernel Admission** — The **`RuntimeKernel`** in [`packages/runtime/src/runtime-kernel.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/runtime-kernel.ts) admits the continuation via **`admitContinuation()`**. If the session is stopping, it throws an error at line 399: `"Session ${sessionId} is stopping and cannot admit a new execution"`.

## Triggering Resumes via the GoalResume Tool

Agent-facing resume capabilities are exposed through the **`GoalResume`** tool defined in [`packages/runtime/src/goal-tools.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/goal-tools.ts) (see `GOAL_RESUME_TOOL_NAME` and `buildGoalResumeTool`). This tool triggers the planner and handles the handoff to the kernel:

```typescript
const planner = new RuntimeContinuationPlanner(deps);
const plan = await planner.plan({
  sessionId,
  sourceRunId,
  currentCwd: process.cwd(),
  sourceWorkspaceIdentity: sourceRun.workspaceIdentity,
  currentWorkspaceIdentity: currentWorkspace.identity,
  backgroundOperationsSettled: await ops.allSettled(),
  availableToolNames: await tools.list(),
});

if (plan.disposition === 'continue') {
  // Planner returned a fresh RuntimeContinuation with new execution IDs
  const newExec = plan.continuation!;
  await runtimeKernel.admitContinuation(newExec);
}

```

## Summary

- Apache Maka's resume architecture creates **brand-new execution identities** rather than modifying existing run histories, preventing state corruption
- The **`RuntimeContinuationPlanner`** in [`packages/runtime/src/runtime-resume.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/runtime-resume.ts) orchestrates safety validation and continuation construction
- **Six safety boundary checks** ensure workspace consistency before allowing continuation, covering ledger state, terminal consistency, and tool catalogs
- Fresh UUIDs for `invocationId`, `runId`, and `turnId` guarantee execution uniqueness while maintaining lineage to source runs
- The **`GoalResume`** tool in [`goal-tools.ts`](https://github.com/apache/maka/blob/main/goal-tools.ts) exposes resume functionality to agents and users
- The **`RuntimeKernel`** provides final admission control with session-state guards to prevent admissions during shutdown

## Frequently Asked Questions

### What prevents duplicate continuations in Apache Maka?

The `RuntimeContinuationPlanner` queries the storage layer via **`findExistingContinuation()`** using the source run ID and high-water mark (last event sequence number). If an existing continuation is found at lines 68-78 of [`runtime-resume.ts`](https://github.com/apache/maka/blob/main/runtime-resume.ts), the planner returns a parked plan with rejection reasons rather than creating a duplicate execution, preventing state divergence and redundant work.

### How does Apache Maka ensure workspace safety during resume?

The planner performs six validated safety checks before creating any new execution: ledger readability, terminal state matching, workspace identity verification, cwd consistency, background operation settlement, and tool catalog compatibility. These checks ensure the resumed execution operates in an environment identical to the original run's termination state, as implemented in lines 13-88 of [`runtime-resume.ts`](https://github.com/apache/maka/blob/main/runtime-resume.ts).

### Who generates the new execution IDs during a resume?

The **`RuntimeContinuationPlanner`** generates fresh identifiers by calling `deps.newId()` within **`buildSafeBoundaryContinuationPlan`** (lines 90-94). This creates new UUIDs for `invocationId`, `runId`, and `turnId`, ensuring the continuation receives a distinct execution identity while maintaining immutable lineage to the source run through shared context and prefixes.

### What happens if a session is stopping when a resume is requested?

If the `RuntimeKernel` receives a continuation request while the session is in a stopping state, it throws an error at line 399 of [`runtime-kernel.ts`](https://github.com/apache/maka/blob/main/runtime-kernel.ts): `"Session ${sessionId} is stopping and cannot admit a new execution"`. This guard prevents partial or corrupted continuations during shutdown sequences and ensures clean session termination.