# The Four Phases of Maka's Resume System and Their Safety Guarantees

> Explore Maka's resume system four phases Crash Contract Safe-Boundary Contract Extraction-Ledger Design and Workspace-Bound Continuation. Learn their safety guarantees against replay data corruption and inconsistent state.

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

---

**Maka's resume system implements four progressive phases—Crash Contract, Safe-Boundary Contract, Extraction-Ledger Design, and Workspace-Bound Continuation—that provide staged safety guarantees against side-effect replay, data corruption, and inconsistent runtime state.**

The apache/maka repository employs a sophisticated staged architecture for resuming interrupted operations. This four-phase system creates a progressive safety envelope, ensuring that resuming a halted turn never compromises workspace integrity or replays dangerous side-effects. Each phase adds concrete guarantees that build upon the previous stage to prevent accidental data mutation.

## Phase 0 – Crash Contract: The Non-Replay Baseline

Phase 0 establishes the foundational contract for any resume operation within Maka. According to [`docs/architecture/runtime-resume-phase0-crash-contract.md`](https://github.com/apache/maka/blob/main/docs/architecture/runtime-resume-phase0-crash-contract.md), this phase defines that a **resume operation does not attempt to replay tool side-effects**, nor does it re-execute code that has already run.

The core safety guarantees at this stage include:

- **Clean logical start**: A resumed turn begins from a pristine logical point without assuming any prior side-effects have occurred.
- **Historic state immutability**: The system guarantees it will never mutate historic state when a crash occurs, preserving the integrity of past operations.

## Phase 1 – Safe-Boundary Contract: Explicit User Control

Phase 1 introduces an explicit safe-resume boundary controlled via the environment variable `MAKA_RUNTIME_SAFE_BOUNDARY_RESUME=1`. As documented 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), this phase exposes resume functionality through UI surfaces including the Desktop banner, CLI `/resume` command, and TUI interface.

This phase provides a **Best-effort** resume capability that cannot change underlying behavior. The safety guarantees include:

- **Explicit confirmation**: User-triggered resume occurs only after explicit confirmation, preventing accidental activation.
- **Safe data boundary**: The runtime will not silently modify workspace data during resume operations.
- **Contract preservation**: The resume operation remains best-effort and cannot violate the Phase 0 crash contract.

## Phase 2 – Extraction-Ledger Design: Durable Checkpoint Integrity

Phase 2 implements a durable ledger that records **extraction points**—checkpoints, artifacts, and provenance data—enabling precise state reconstruction during resume. The architecture in [`docs/architecture/runtime-resume-phase2-extraction-ledger.md`](https://github.com/apache/maka/blob/main/docs/architecture/runtime-resume-phase2-extraction-ledger.md) ensures that only verifiable evidence is used for continuation.

The safety guarantees at this stage focus on data integrity:

- **Integrity-checked reads**: Only the minimal evidence required for resume is fetched, with verification preventing corrupted artifact usage.
- **Faithful state capture**: The ledger guarantees accurate recording of state at checkpoint boundaries, preventing mismatched or missing data during resume operations.

## Phase 3 – Workspace-Bound Continuation: Strict Consistency Enforcement

Phase 3 implements the actual continuation logic with strict workspace validation before any auto-resume occurs. According to [`docs/architecture/runtime-resume-phase3-workspace-checkpoint-design.md`](https://github.com/apache/maka/blob/main/docs/architecture/runtime-resume-phase3-workspace-checkpoint-design.md), this phase enforces hard gates including workspace corruption checks and resource ownership verification.

The final phase provides the strongest safety guarantees:

- **Corruption-free requirement**: Resume proceeds only when the workspace is free of corruption, specifically when `parked` status and `recovery.hasCorruption` indicators are cleared.
- **Exclusive ownership**: The system guarantees exclusive ownership of the SQLite database, filesystem workers, and contract registry to prevent concurrent resume interference.
- **Default-disallow auto-resume**: Auto-resume is disabled by default; manual resume must satisfy the hard gates defined in this phase.

## Implementation Examples

Below are minimal snippets illustrating how to trigger safe resume at each stage using the public CLI entry point. All examples assume the repository has been built (`npm run build`).

Enable the Phase 1 safe-boundary resume by setting the environment variable before starting Maka:

```typescript
// Phase 1 – Enable safe-boundary resume (desktop or CLI)
process.env.MAKA_RUNTIME_SAFE_BOUNDARY_RESUME = '1';

```

Execute a manual Phase 3 resume from a halted Turn using the CLI:

```typescript
// Phase 3 – Manual resume from a halted Turn (CLI)
// The `/resume` command resumes the most recent interrupted turn.
import { execSync } from 'child_process';
execSync('npm run cli:dev -- /resume', { stdio: 'inherit' });

```

## Key Architecture Documentation

The complete technical specifications for each phase are maintained in the following architecture documents:

| File | Role |
|------|------|
| [`docs/architecture/runtime-resume-phase0-crash-contract.md`](https://github.com/apache/maka/blob/main/docs/architecture/runtime-resume-phase0-crash-contract.md) | Defines the crash contract and the "no side-effect replay" guarantee. |
| [`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) | Introduces the safe-boundary flag and UI-driven resume actions. |
| [`docs/architecture/runtime-resume-phase2-extraction-ledger.md`](https://github.com/apache/maka/blob/main/docs/architecture/runtime-resume-phase2-extraction-ledger.md) | Describes the extraction ledger that records checkpoint artifacts for resume. |
| [`docs/architecture/runtime-resume-phase3-workspace-checkpoint-design.md`](https://github.com/apache/maka/blob/main/docs/architecture/runtime-resume-phase3-workspace-checkpoint-design.md) | Details the workspace-bound continuation, ownership checks, and corruption gates. |

## Summary

Maka's four-phase resume architecture provides a progressive safety envelope that prevents data corruption and side-effect replay:

- **Phase 0** establishes a non-replaying baseline that protects historic state from mutation during crashes.
- **Phase 1** adds explicit user-controlled boundaries via the `MAKA_RUNTIME_SAFE_BOUNDARY_RESUME` environment variable and confirmation-driven UI.
- **Phase 2** ensures trustworthy checkpoint extraction through a durable ledger that verifies artifact integrity before use.
- **Phase 3** enforces strict workspace consistency, requiring cleared corruption flags (`recovery.hasCorruption`) and exclusive resource ownership before allowing any continuation.

## Frequently Asked Questions

### What is the primary purpose of Phase 0 in Maka's resume system?

Phase 0 establishes the fundamental crash contract that guarantees a resumed turn starts from a clean logical point without assuming prior side-effects have occurred, and ensures the system never mutates historic state during a crash.

### How does Phase 1 prevent silent data modification during resume?

Phase 1 requires explicit user confirmation through UI surfaces (Desktop banner, CLI `/resume`, or TUI) and activates only when `MAKA_RUNTIME_SAFE_BOUNDARY_RESUME=1` is set, creating a "safe boundary" where the runtime cannot silently modify workspace data.

### What corruption checks are enforced in Phase 3 before allowing continuation?

Phase 3 enforces hard gates that verify the workspace `parked` status is cleared and `recovery.hasCorruption` is false, while also ensuring exclusive ownership of SQLite databases, filesystem workers, and the contract registry before permitting any resume operation.

### Is auto-resume enabled by default in Maka's architecture?

No, according to the Phase 3 implementation in [`runtime-resume-phase3-workspace-checkpoint-design.md`](https://github.com/apache/maka/blob/main/runtime-resume-phase3-workspace-checkpoint-design.md), auto-resume is disabled by default, and manual resume must satisfy strict consistency checks including corruption detection and resource ownership verification.