How Apache Maka Handles Crash Recovery: Safe-Boundary Transactions and Resumption

Apache Maka handles crash recovery through a three-layer architecture of crash-boundary transactions, safe-boundary continuations, and quarantine recovery bundles that ensure durable state validation before and after mutations.

Apache Maka's crash recovery strategy centers on detecting incomplete operations after process termination and safely resuming from the last known good state. The repository implements this through durable commit records, continuation validation, and workspace isolation mechanisms that prevent data loss during unexpected failures.

Crash-Boundary Transactions

Critical state-changing actions in Maka are wrapped in crash-boundary sections that enforce durability guarantees. Each boundary writes a durable "commit" record before any actual mutation occurs and validates it immediately after the mutation completes.

In packages/storage/src/plan-store.ts, this mechanism detects incomplete transactions when a process crashes between the pre-mutation commit and post-mutation validation. According to lines 377-388 of the source, if the system discovers an unvalidated commit record during recovery, it can roll back or retry the operation to maintain consistency. The resumeExecution method in this file enforces these crash-boundary checks during plan persistence operations.

Safe-Boundary Continuations

The runtime kernel exposes a resumeContinuation method that enables safe replay of operations after a crash. This functionality only activates when the continuation was captured at a safe-boundary—specifically, after all required durable writes have succeeded.

The session-manager validates resume eligibility before allowing continuation replay. According to lines 2270-2290 of packages/runtime/src/session-manager.ts, the system verifies that the runtime kernel supports the resume feature and that the continuation passes resumeTrust checks. This prevents resumption from corrupted or unsafe states that could propagate errors into subsequent operations.

Quarantine and Recovery Bundles

When crashes occur during workspace staging, Maka employs quarantine logic to preserve staging inodes without corrupting active workspaces. The system later re-hydrates the workspace from a recovery bundle rather than touching decoy files directly.

In packages/storage/src/git-workspace-service.ts (lines 1472-1507), this mechanism ensures that a crash leaves no orphaned state. The next execution can reclaim the staging area cleanly by validating the recovery bundle integrity before resuming operations. This approach isolates partial or corrupted staging data from the main workspace until explicit recovery confirmation occurs.

Resuming Execution After a Crash

When resuming a prior session, Maka reads the persisted session header—specifically the first line of the log—to locate the appropriate resume point. The session-store.ts file implements this logic around lines 759-760, parsing the session header to identify valid resume candidates.

If the required resume candidate is missing or the model does not support the requested resume boundary, Maka reports a clear error instead of crashing. The runtime-resume-copy.ts file (lines 54-58) contains the UI strings and error handling logic for these validation failures, ensuring users receive actionable feedback rather than silent failures.

Practical Implementation Examples

To resume a previously interrupted plan execution programmatically:

await runtime.sessionManager.resumePlanExecution({
  sessionId: 'my-session-id',
  executionId: 'exec-123',
  operationId: 'op-456',
});

For command-line resumption with a legacy run identifier:

maka --resume <legacy-run-id>

For low-level manual invocation of safe-boundary continuations:

if (runtimeKernel.resumeContinuation) {
  const continuation = await loadContinuationFromStore(...);
  for await (const chunk of runtimeKernel.resumeContinuation.call(
    runtimeKernel,
    continuation,
    { abortSignal: new AbortController().signal }
  )) {
    // Process resumed output
  }
}

Summary

Apache Maka's crash recovery architecture provides multiple safeguards against data loss and state corruption:

• Crash-boundary transactions in plan-store.ts validate commit records before and after state mutations, enabling rollback of incomplete operations detected between lines 377-388
• Safe-boundary continuations managed by session-manager.ts ensure resumption only occurs from trusted, fully persisted states verified by resumeTrust checks
• Quarantine and recovery bundles in git-workspace-service.ts isolate crashed staging operations and enable clean workspace re-hydration without touching decoy files
• Session header validation in session-store.ts locates precise resume points while runtime-resume-copy.ts provides clear error handling for unsupported resumption requests

Frequently Asked Questions

What constitutes a crash-boundary transaction in Apache Maka?

A crash-boundary transaction is a critical state-changing operation wrapped in durability checks that write a commit record before mutation and validate it immediately after. According to the source code in packages/storage/src/plan-store.ts (lines 377-388), these boundaries detect incomplete transactions when a process terminates unexpectedly between the pre-commit and post-validation phases, allowing the system to either roll back partial changes or retry the operation safely.

How does Maka determine if a continuation is safe to resume?

Maka validates resume safety through the resumeTrust checks implemented in packages/runtime/src/session-manager.ts (lines 2270-2290). The system confirms that the runtime kernel supports continuation resumption and that the specific continuation was captured at a safe-boundary after all durable writes completed. If these conditions are not met, Maka refuses resumption and reports an error via the handlers defined in packages/ui/src/runtime-resume-copy.ts.

What happens if a crash occurs during workspace staging?

If a crash interrupts workspace staging, the quarantine logic in packages/storage/src/git-workspace-service.ts (lines 1472-1507) preserves the staging inode without committing partial changes to the active workspace. Upon restart, Maka re-hydrates the workspace from a recovery bundle rather than attempting to salvage potentially corrupted decoy files directly. This ensures the staging area can be reclaimed cleanly without orphaning state or contaminating the production workspace.

Can Maka resume any interrupted operation, or are there limitations?

Maka cannot resume arbitrary interrupted operations. Resumption requires that the operation reached a safe-boundary with a valid session header, as verified by packages/storage/src/session-store.ts (lines 759-760). Additionally, the runtime kernel must explicitly support the resumeContinuation method, and the operation must pass resumeTrust validation. Operations that crash before establishing a safe-boundary or those involving unsupported model configurations cannot be resumed and will trigger clear error messages instead.

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