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

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

---

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.

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

// 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	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	Formal specification of the authority model, reservation semantics, and no‑effect capability design
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	WorkspaceHeadRecordV1 structure, revision counters, and accepted head protocol that mutations build upon
packages/runtime/src/types.ts	TypeScript definitions for ToolPreparedFacts, MutationOutcome, and the opaque capability token
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 with design rationale documented in 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.

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