# Understanding Phase 1 in Apache Maka's Resume Architecture: The Safe-Boundary Contract

> Discover Apache Maka's Phase 1 Safe-Boundary Contract. Learn how it ensures session safety with a fail-closed continuation path, resuming only when explicit conditions are met.

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

---

**Phase 1 (the Safe‑Boundary Contract) extends Apache Maka’s basic crash‑recovery logic by implementing a fail‑closed continuation path that only resumes interrupted sessions when explicit safety conditions are satisfied.**

Apache Maka’s resume architecture employs a phased approach to session recovery, with Phase 1 serving as the critical bridge between simple replay mechanisms and safe production continuations. While Phase 0 handles pure crash recovery through deterministic replay, Phase 1 introduces the **Safe‑Boundary Contract** to ensure that resumed executions never proceed with stale or unsafe state. This phase is defined in [`docs/architecture/runtime-resume-phase1-safe-boundary-contract.md`](https://github.com/apache/maka/blob/main/docs/architecture/runtime-resume-phase1-safe-boundary-contract.md) and builds upon the foundational guarantees established in [`docs/architecture/runtime-resume-phase0-crash-contract.md`](https://github.com/apache/maka/blob/main/docs/architecture/runtime-resume-phase0-crash-contract.md).

## The Purpose of Phase 1: Controlled Continuation

Phase 1 transforms Apache Maka’s recovery model from passive replay into active, safety‑checked resumption. According to the source architecture documentation, the primary purpose is to create a **controlled boundary** around session resumption that validates external safety facts before allowing a new Run to begin.

Unlike Phase 0’s pure replay model, Phase 1 requires the runtime to obtain a **committed source boundary** and validated host‑supplied facts before creating fresh execution identities. This ensures that no provider receives duplicate calls and no source ledger mutations occur without explicit validation.

## Core Responsibilities of the Safe‑Boundary Contract

### Explicit Continuation with Safety Gates

The contract allows the runtime to create a **new Run and Invocation** after crashes or interruptions, but only when the committed source boundary is complete and the host supplies all required external safety facts. As specified in [`runtime-resume-phase1-safe-boundary-contract.md`](https://github.com/apache/maka/blob/main/runtime-resume-phase1-safe-boundary-contract.md) (lines 22‑26), the system verifies workspace identity, current working directory, and tool catalog validity before permitting continuation.

### Separation of Planning and Execution

Phase 1 enforces a strict separation between planning and execution through the `RuntimeContinuationPlanner`. Planning is performed first, and execution only begins after the plan is re‑validated immediately before the new Run starts. This architecture prevents “run‑away” continuations by ensuring the planner gates documented in lines 56‑73 of the contract file are satisfied before any provider code executes.

### Fail‑Closed Guarantee

If any required safety fact is missing or contradictory, the planner **parks** the continuation rather than retrying. This fail‑closed behavior (lines 76‑84) guarantees that the system never proceeds with an unsafe state, providing deterministic failure outcomes rather than speculative execution risks.

### Fresh Execution Identity Isolation

Every Phase 1 continuation generates fresh `Invocation`, `Run`, and `Turn` IDs. The system records a `continuation‑start` event that must be durably persisted before the provider is called (lines 34‑45). This isolation mechanism ensures that resumed runs are cleanly separated from their original execution contexts, preventing state contamination.

### Host‑Supplied Safety Snapshots

The host must provide authoritative facts including workspace identity, current working directory, tool catalog, and optional checkpoint restoration data. The runtime validates these facts both during the planning phase and immediately before execution begins (lines 32‑38), creating a double‑validation pattern that catches environment drifts.

## How to Trigger Phase 1 Resumption

Users can initiate safe‑boundary resumption through multiple entry points defined in the architecture (lines 45‑52):

- **Desktop Interface**: Click the “Safe resume” button on the Interrupted‑Turn banner
- **CLI/TUI**: Execute the `/resume` command in the interactive shell
- **Environment Variable**: Set `MAKA_RUNTIME_SAFE_BOUNDARY_RESUME=1` to enable auto‑continuation

```bash

# Enable safe-boundary resume (required for Phase I)

export MAKA_RUNTIME_SAFE_BOUNDARY_RESUME=1

# CLI/TUI – request a safe resume

/maka> /resume

```

For programmatic control in Node.js environments, the `RuntimeClient` exposes the resumption interface:

```javascript
const { RuntimeClient } = require('@apache/maka/runtime');

async function safeResume(sessionId) {
  // RuntimeClient checks the safe-boundary flag and invokes the planner
  const result = await RuntimeClient.resumeLatest(sessionId);
  console.log('Resume result:', result);
}

```

## Technical Implementation Reference

The Phase 1 implementation spans several key files in the Apache Maka repository:

- [`docs/architecture/runtime-resume-phase1-safe-boundary-contract.md`](https://github.com/apache/maka/blob/main/docs/architecture/runtime-resume-phase1-safe-boundary-contract.md) — Complete specification of the Safe‑Boundary Contract, safety conditions, and failure behaviors
- [`docs/architecture/runtime-resume-phase0-crash-contract.md`](https://github.com/apache/maka/blob/main/docs/architecture/runtime-resume-phase0-crash-contract.md) — Baseline crash‑recovery contract that Phase 1 extends
- [`ARCHITECTURE.md`](https://github.com/apache/maka/blob/main/ARCHITECTURE.md) — High‑level overview of the resume architecture phases
- [`README.md`](https://github.com/apache/maka/blob/main/README.md) — General repository information and quick start guides

The `RuntimeContinuationPlanner` serves as the primary orchestration component, implementing the planning gates that prevent execution until safety validation completes.

## Summary

- Phase 1 introduces the **Safe‑Boundary Contract** to extend Phase 0’s replay logic with active safety validation.
- The **fail‑closed guarantee** ensures continuations park rather than proceed when safety facts are missing.
- **Fresh execution identities** (new Run, Invocation, and Turn IDs) isolate resumed sessions from original contexts.
- **Host-supplied snapshots** require explicit validation of workspace state, directory context, and tool catalogs.
- Entry points include the desktop banner, CLI `/resume` command, and the `MAKA_RUNTIME_SAFE_BOUNDARY_RESUME` environment variable.

## Frequently Asked Questions

### How does Phase 1 differ from Phase 0 in Apache Maka’s resume architecture?

Phase 0 implements a pure crash‑recovery contract based on deterministic replay of completed actions, while Phase 1 adds the Safe‑Boundary Contract that requires explicit safety validation before creating new execution contexts. Phase 0 focuses on ledger integrity through replay, whereas Phase 1 ensures runtime safety through validated continuation planning.

### What happens if safety conditions aren't met during Phase 1 resumption?

The `RuntimeContinuationPlanner` implements a fail‑closed policy: if any required safety fact is missing, contradictory, or fails re‑validation, the system **parks** the continuation rather than executing. This prevents run‑away continuations and ensures the system never calls providers with unsafe or stale state.

### How does RuntimeContinuationPlanner prevent run‑away continuations?

The planner enforces a strict separation between planning and execution phases, as documented in [`runtime-resume-phase1-safe-boundary-contract.md`](https://github.com/apache/maka/blob/main/runtime-resume-phase1-safe-boundary-contract.md) (lines 56‑73). Planning occurs first, followed by immediate re‑validation immediately before the new Run begins. This dual‑gate pattern ensures that environmental changes between planning and execution trigger immediate parking.

### What safety facts must the host provide for Phase 1 resumption?

According to the contract specification, the host must supply authoritative facts including workspace identity, current working directory, available tool catalog, and optional checkpoint restoration data. These facts are validated twice: once during planning and again immediately before execution starts, ensuring consistency between the planning snapshot and execution environment.