# How Runtime-Managed Workspace Mutation Lifecycle Authority Works in Maka: Architecture Deep‑Dive

> Discover how Maka's runtime manages workspace mutations using a two-phase reservation system, SQLite, and process-wide locking for atomic operations. Learn the architecture.

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

---

**Maka's runtime enforces single‑owner, atomic workspace mutations through a two‑phase reservation system (T1 prepare + T2 commit) backed by SQLite and process‑wide `workspace_instance_id` locking.**

The **Managed Workspace Mutation Lifecycle Authority** is the core mechanism that allows Apache Maka's computer‑use runtime to safely mutate persistent workspace state while guaranteeing that only one durable mutation owns the workspace at any moment. This article explains how the authority works, where it's implemented, and how to interact with it in your own tools.

---

## Why a Managed Mutation Lifecycle Matters

In long‑running agent systems, tools may execute concurrently, fail midway, or produce no‑effect results. Without strict coordination, concurrent mutations risk corrupting the workspace or losing deterministic replay. Maka solves this by treating every mutation as a **reserved, verifiable, atomic transaction** with explicit lifecycle boundaries.

---

## Core Concepts of the Authority

The authority rests on three tightly coupled primitives:

| Concept | Purpose | Source Reference |
|---------|---------|------------------|
| **Baseline workspace head** | Immutable starting point for any mutation; the last accepted version | `WorkspaceHeadRecordV1` 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) |
| **T1 reservation (prepare)** | Acquires exclusive ownership via `workspace_instance_id` and records intent + no‑effect capability | `SqliteRuntimeStore.commitToolPrepared()` in [`packages/runtime/src/storage/runtime-store.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/storage/runtime-store.ts) |
| **T2 commit (accept)** | Atomically validates the reservation, upgrades it to a concrete outcome, and advances the workspace head | `SqliteRuntimeStore.commitToolResult()` in [`packages/runtime/src/storage/runtime-store.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/storage/runtime-store.ts) |

---

## The Two‑Phase Lifecycle Explained

### Phase 1: Prepare (T1)

Before a tool touches the workspace, the runtime calls into the storage layer to create a **prepared reservation**. This happens inside a single SQLite transaction with WAL mode enabled.

- **Lock acquisition**: The store generates a unique `workspace_instance_id` and inserts a reservation row keyed by this ID. SQLite's process‑wide lock guarantees no other process can claim the same ID.
- **Intent recording**: The reservation captures a **fingerprint** of the mutation request (model prompt, tool parameters) and an **opaque no‑effect capability**—a token that only the storage verifier can redeem.
- **Baseline anchoring**: The reservation references the current `acceptedEventId` from `WorkspaceHeadRecordV1`, ensuring the mutation builds on a known‑good state.

```typescript
// Runtime Host calls this before executing the tool
const prep = await runtimeStore.prepareToolMutation({
  toolId: 'computer-use',
  fingerprint: computeFingerprint(request), // hash of intent + context
});

const reservationId = prep.workspace_instance_id; // unique process‑wide
const capability = prep.noEffectCapability;       // opaque token for no‑op path

```

Key parameters in `prepareToolMutation`:

- `toolId`: Identifies the mutating tool for audit trails.
- `fingerprint`: Cryptographic hash preventing replay of stale mutations.
- Returns `workspace_instance_id` and `noEffectCapability` for the subsequent commit.

---

### Phase 2: Commit (T2)

After the tool executes—whether it produced changes, failed, or had no effect—the runtime finalizes the mutation through `commitToolResult`. This again operates inside the same SQLite transaction skeleton, ensuring atomicity.

- **Capability validation**: The store verifies that the provided `noEffectCapability` matches the reservation created in T1.
- **Outcome classification**:
  - **Success**: Tool produced valid workspace mutations; `preparedFacts` (pointer mutations, file writes, etc.) are promoted to durable state.
  - **Failure**: Tool errored; reservation is released without advancing the head.
  - **No‑effect**: Tool explicitly returns the capability unmodified; the verifier treats this as a null operation, preserving baseline exactly.

- **Head advancement**: On success, `WorkspaceHeadRecordV1.acceptedEventId` is updated, the revision counter increments, and the reservation row is deleted.

```typescript
// Called after tool execution completes
await runtimeStore.commitToolResult({
  workspace_instance_id: reservationId,   // from T1
  outcome: toolResult.outcome,            // 'success' | 'failure' | 'no-op'
  preparedFacts: toolResult.preparedFacts, // structured mutation metadata
  noEffectCapability: capability,         // opaque token from T1
});

```

---

## Guarantees Enforced by the Authority

| Guarantee | Mechanism | Failure Mode Prevented |
|-----------|-----------|------------------------|
| **Single durable owner** | `workspace_instance_id` primary key + SQLite lock | Concurrent mutations corrupting same workspace version |
| **Atomic visibility** | Single SQLite transaction spans T1→T2 | Partial writes leaving workspace in inconsistent state |
| **Deterministic replay** | Fingerprint binds request to reservation | Re‑playing old mutations against new baselines |
| **No‑effect safety** | Opaque capability token + verifier logic | Spurious commits when tool makes no changes |
| **Process isolation** | WAL mode + file‑level locks from [`runtime-store.ts`](https://github.com/apache/maka/blob/main/runtime-store.ts) | Cross‑process race conditions on shared SQLite |

---

## Where the Implementation Lives

All paths relative to `https://github.com/apache/maka/blob/main/`:

| File | Responsibility |
|------|--------------|
| [`docs/architecture/runtime-managed-workspace-mutation-lifecycle-authority-v1.zh-CN.md`](https://github.com/apache/maka/blob/main/docs/architecture/runtime-managed-workspace-mutation-lifecycle-authority-v1.zh-CN.md) | Formal specification of the authority model, reservation semantics, and no‑effect capability design |
| [`packages/runtime/src/storage/runtime-store.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/storage/runtime-store.ts) | `SqliteRuntimeStore` class implementing `prepareToolMutation`, `commitToolPrepared`, and `commitToolResult`; manages `workspace_instance_id` tuple and SQLite transaction lifecycle |
| [`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) | `WorkspaceHeadRecordV1` structure, revision counters, and accepted head protocol that mutations build upon |
| [`packages/runtime/src/types.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/types.ts) | TypeScript definitions for `ToolPreparedFacts`, `MutationOutcome`, and the opaque capability token |
| [`packages/runtime/src/api/runtime.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/api/runtime.ts) | Public Runtime Host API surface that tools call to initiate and finalize mutations |

---

## Summary

- **Baseline + reservation + atomic commit** form the three pillars of Maka's mutation authority.
- **`workspace_instance_id`** provides process‑wide exclusive ownership through SQLite locking.
- **Two‑phase commit (T1 prepare, T2 accept)** ensures mutations are either fully durable or fully absent.
- **No‑effect capability** allows tools to explicitly decline mutation without side effects.
- All logic is centralized in **[`packages/runtime/src/storage/runtime-store.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/storage/runtime-store.ts)** with design rationale documented in **[`runtime-managed-workspace-mutation-lifecycle-authority-v1.zh-CN.md`](https://github.com/apache/maka/blob/main/runtime-managed-workspace-mutation-lifecycle-authority-v1.zh-CN.md)**.

---

## Frequently Asked Questions

### What happens if a tool crashes between T1 and T2?

The reservation row remains in SQLite but is marked incomplete. Maka's recovery logic on next startup detects orphaned reservations by their `workspace_instance_id` and either rolls them back (if no capability was redeemed) or queries the tool for status. The baseline head never advances until T2 completes successfully.

### Can multiple tools hold reservations on the same workspace simultaneously?

No. The `workspace_instance_id` is a primary key in the reservation table, and SQLite's lock mechanism prevents concurrent inserts. A second `prepareToolMutation` call will block or fail until the first reservation is committed or released, enforcing strict single‑owner semantics.

### How does the no‑effect capability prevent spurious commits?

The capability is an opaque, unforgeable token generated during T1 and required during T2. If a tool returns it unmodified, the verifier recognizes this as an explicit no‑op and skips all workspace head updates. Without the correct capability, a no‑op outcome cannot be forged by buggy or malicious callers.