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

> Discover Maka's robust workspace versioning and dependency storage. Learn how its crash-resilient SQLite-backed system ensures atomic transactions and deterministic recovery for the Apache Runtime Architecture.

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

---

**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`](https://github.com/apache/maka/blob/main/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.

```ts
// 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`](https://github.com/apache/maka/blob/main/packages/storage/src/sqlite-runtime-store.ts):

```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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/packages/storage/src/managed-dependency-environment.ts) enforces this.

```ts
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`](https://github.com/apache/maka/blob/main/docs/architecture/runtime-workspace-version-authority-v1.zh-CN.md) | Workspace versioning design spec |
| [`docs/architecture/managed-dependency-storage-authority-v1.zh-CN.md`](https://github.com/apache/maka/blob/main/docs/architecture/managed-dependency-storage-authority-v1.zh-CN.md) | Dependency storage design spec |
| [`packages/core/src/workspace-version-authority.ts`](https://github.com/apache/maka/blob/main/packages/core/src/workspace-version-authority.ts) | Version ID types and validation |
| [`packages/storage/src/sqlite-runtime-store.ts`](https://github.com/apache/maka/blob/main/packages/storage/src/sqlite-runtime-store.ts) | SQLite persistence for versions |
| [`packages/storage/src/managed-dependency-environment.ts`](https://github.com/apache/maka/blob/main/packages/storage/src/managed-dependency-environment.ts) | Dependency authority implementation |
| [`packages/storage/src/__tests__/workspace-version-authority-persistence.test.ts`](https://github.com/apache/maka/blob/main/packages/storage/src/__tests__/workspace-version-authority-persistence.test.ts) | Crash-recovery test suite |
| [`packages/storage/src/__tests__/managed-dependency-environment.test.ts`](https://github.com/apache/maka/blob/main/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.