Maka Workspace Versioning and Dependency Storage: A Deep Dive into the Apache Runtime Architecture

Maka implements workspace versioning and dependency storage as two independent, crash‑resilient authorities persisted outside the mutable workspace tree, using SQLite-backed transactional systems for guaranteed atomicity and deterministic recovery.

The Apache Maka project separates logical workspace state from physical dependency artifacts through purpose-built authorities. This architecture enables reliable resume, rollback, and multi-agent collaboration by treating workspace versioning and dependency storage as immutable, verifiable systems rather than mutable file operations.

Workspace Versioning in Maka

Maka's workspace versioning authority maintains an immutable history of workspace states through a dedicated SQLite database that survives crashes and power failures.

The Workspace Version Authority Design

Each mutable workspace maintains a canonical head pointing to a workspace version ID in the format version_<64‑hex>. These versions live in runtime.sqlite and are managed by the Workspace Version Authority v1, documented in docs/architecture/runtime-workspace-version-authority-v1.zh-CN.md.

The authority stores immutable facts: epochs, baselines, successors, and heads. This schema enables exact reconstruction of workspace state regardless of interruption point.

Atomic T1/T2 Commit Semantics

Workspace mutations proceed as paired transactions:

• T1 (baseline): The current workspace version ID serving as parent
• T2 (successor): The new version being committed

Both are written together atomically. A version cannot be observed without its predecessor, eliminating partial-state exposure.

// Creating a new workspace version (T1/T2 atomic pair)
import { WorkspaceVersionInput } from '@maka/core';
import { RuntimeStore } from '@maka/storage';

async function commitNewVersion(store: RuntimeStore, baseVersionId: string) {
  const input: WorkspaceVersionInput = {
    baseline: {
      workspaceVersionId: baseVersionId,
    },
    successor: {
      workspaceVersionId: `version_${'a'.repeat(32)}`,
      parentWorkspaceVersionId: baseVersionId,
    },
  };
  const result = await store.commitWorkspaceVersion(input);
  console.log('Committed:', result.committedSuccessor.workspaceVersionId);
}

Crash Recovery Guarantees

The Workspace Version Authority provides exact crash recovery with platform-differentiated durability:

Platform	Guarantee
Linux	Full power-loss durability
macOS/Windows	Process-crash convergence only

If a commit fails mid-write, the database contains no partial version. Post-restart, the authority rebuilds the head from persisted facts.

Query the current head via readWorkspaceHead() in packages/storage/src/sqlite-runtime-store.ts:

import { RuntimeStore } from '@maka/storage';
import { WorkspaceHeadRecordV1 } from '@maka/core';

async function getCurrentHead(store: RuntimeStore): Promise<WorkspaceHeadRecordV1> {
  const head = await store.readWorkspaceHead();
  console.log('Current version:', head.workspaceVersionId);
  return head;
}

Maka Dependency Storage Architecture

Maka isolates dependencies in a managed dependency environment physically separated from workspace files. This system is governed by its own authority with equally strict durability requirements.

Managed Dependency Environment Authority

Dependencies materialize under a canonical storage root with SQLite receipt tracking in managed‑workspaces/dependency‑environment‑authority‑v1.sqlite. The design document at docs/architecture/managed-dependency-storage-authority-v1.zh-CN.md specifies the full protocol.

Atomic Publication Pipeline

Dependency publication follows a six-phase pipeline with failure isolation at each step:

1. Identity validation — verify environment ID format and parentage
2. OS exclusive lock — prevent concurrent mutations
3. Staging — write to temporary directory
4. Content hash & fsync — cryptographic verification of every file
5. Atomic rename — move staging to final location
6. Synchronous SQLite receipt commit — record metadata transactionally

Either the complete dependency tree and its receipt appear together, or neither does. The ManagedDependencyEnvironmentAuthority implementation in packages/storage/src/managed-dependency-environment.ts enforces this.

import { ManagedDependencyEnvironmentAuthority } from '@maka/storage';

async function publishDependencies(authority: ManagedDependencyEnvironmentAuthority) {
  await authority.acquire({ environmentId: 'env_123…' });
  // Staging, hashing, fsync, rename, and receipt commit happen atomically
  console.log('Receipt ID:', authority.receiptId);
}

Orphan Detection and Fail-Closed Behavior

Post-crash, the authority detects three corruption states:

• Artifact only: files exist without receipt
• Receipt only: metadata references missing files
• Hash mismatch: content doesn't match recorded hash

The system fail-closed: it removes orphaned artifacts and forces re-materialization rather than risk corrupted dependencies.

Platform Security Constraints

The authority enforces containment boundaries:

• Symlinks and reparse points cannot escape the dependency root
• Windows read-only files trigger temporary permission elevation during staging, with restoration after commit

Key Implementation Files

Path	Responsibility
docs/architecture/runtime-workspace-version-authority-v1.zh-CN.md	Workspace versioning design spec
docs/architecture/managed-dependency-storage-authority-v1.zh-CN.md	Dependency storage design spec
packages/core/src/workspace-version-authority.ts	Version ID types and validation
packages/storage/src/sqlite-runtime-store.ts	SQLite persistence for versions
packages/storage/src/managed-dependency-environment.ts	Dependency authority implementation
packages/storage/src/__tests__/workspace-version-authority-persistence.test.ts	Crash-recovery test suite
packages/storage/src/__tests__/managed-dependency-environment.test.ts	Dependency lifecycle tests

Summary

• Workspace versioning uses immutable T1/T2 pairs in SQLite with platform-tailored crash recovery
• Dependency storage applies staged, hashed, fsynced, atomically renamed publications with receipt verification
• Both authorities fail-closed on corruption detection, preferring re-materialization over partial states
• Deterministic provenance enables reliable resume, rollback, and multi-agent collaboration across apache/maka runtimes

Frequently Asked Questions

How does Maka recover from power loss during a workspace version commit?

The Workspace Version Authority relies on SQLite's atomic commit guarantees combined with fsync ordering. On Linux, full power-loss durability is guaranteed; on macOS and Windows, the system guarantees only process-crash convergence. In all cases, partial writes are impossible—the database either contains complete T1/T2 pairs or neither, allowing head reconstruction from persisted facts.

Why does Maka separate dependency storage from the workspace tree?

Physical isolation prevents dependency corruption from affecting workspace version integrity. The managed dependency environment uses its own authority, receipt system, and storage root. This separation enables independent garbage collection, sharing across workspaces, and cryptographic verification of dependency graphs without workspace state pollution.

What happens if the dependency staging directory crashes mid-write?

The publication pipeline detects three orphan states post-recovery: artifact without receipt, receipt without artifact, or hash mismatches. The ManagedDependencyEnvironmentAuthority removes orphaned components and forces complete re-materialization. This fail-closed design guarantees that no workspace ever executes against partially-written or unverified dependencies.

Can workspace versions reference dependencies across different storage roots?

No. The dependency environment authority binds environment identity to a canonical storage root and SQLite receipt. Cross-root references would violate the determinism and containment guarantees. Version resolution through readWorkspaceVersion and readWorkspaceHead always validates that referenced dependencies exist within the bound environment's verified receipt set.

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