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

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, 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, 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 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, 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:

// 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:

// 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	Defines the crash contract and the "no side-effect replay" guarantee.
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	Describes the extraction ledger that records checkpoint artifacts for resume.
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, auto-resume is disabled by default, and manual resume must satisfy strict consistency checks including corruption detection and resource ownership verification.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}