# T2 commitToolOutcome in Apache Maka: Significance and Implementation for Durable Workflows

> Discover the significance of T2 commitToolOutcome in Apache Maka. Persist tool results for durable workflows, enable seamless resumes, and create immutable audit records. Learn more.

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

---

**The T2 commitToolOutcome step persists tool execution results to Apache Maka’s Task Ledger, enabling workflows to resume without re-executing tools and creating immutable audit records for compliance and debugging.**

Apache Maka is an open-source runtime designed for reliable AI agent workflows that execute external tools such as web searches, code fetchers, and model endpoints. At the core of its architecture lies a two-phase execution model where **T2 commitToolOutcome** serves as the critical persistence boundary, ensuring that tool effects survive process restarts and network interruptions. This mechanism separates transient tool execution from durable state recording, as defined in the `apache/maka` source repository.

## The Two-Phase Tool Execution Model

Every tool invocation in Apache Maka follows a strict bifurcated lifecycle defined in the runtime architecture documentation and source code.

### Phase T1: Tool Invocation and Raw Capture

During Phase T1, the runtime launches the external tool and captures its raw output. This phase encompasses the actual computation—whether calling an API, executing a shell command, or querying a vector database. At the conclusion of T1, the result exists only in volatile memory and has not yet been written to persistent storage.

### Phase T2: Committing the Tool Outcome

Phase T2, or **T2 commitToolOutcome**, is the durability boundary where the runtime commits the captured result to the **Task Ledger**. According to the code comments in [`packages/runtime/src/tool-runtime.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/tool-runtime.ts) at line 390, hosts that persist **RuntimeEvents** may optionally enforce this T1/T2 boundary. During this phase, the Transaction-Recorder (TR) dispatches a `T2 commitToolOutcome` message to the database, permanently storing the tool’s final output alongside its unique invocation identifier.

## Why T2 commitToolOutcome Matters

The T2 commit provides the foundational guarantees required for production AI agent deployments.

### Durable Resumption Without Re-execution

By persisting outcomes to the Task Ledger, Apache Maka enables **durable resumption** of interrupted sessions. When a workflow resumes, the runtime queries the database for previously committed results rather than re-invoking expensive or stateful tools. The retrieval logic in [`packages/runtime/src/terminal-run-commit.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/terminal-run-commit.ts) illustrates this optimization:

```typescript
// packages/runtime/src/terminal-run-commit.ts
const persisted = await db.getToolOutcome(invocationId);
if (persisted) {
  // Reuse the previously-computed result instead of rerunning the tool
  return persisted;
}

```

This pattern eliminates redundant API calls and prevents side-effect duplication when workflows pause for user input, crash recovery, or scheduled maintenance.

### Consistency and Immutable Auditing

The T2 commit creates an immutable record in the Task Ledger that serves as the canonical source of truth for workflow replay and compliance verification. Unlike transient execution logs, the committed Tool Outcome provides deterministic replay capabilities, allowing developers to reconstruct exact sequences of multi-tool interactions even when external services have changed or become unavailable.

## Source Code Implementation

The T2 commitToolOutcome logic spans the runtime persistence layer and session recovery modules in the Apache Maka codebase.

### The Commit Boundary in tool-runtime.ts

The optional Phase 2 persistence is triggered in [`packages/runtime/src/tool-runtime.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/tool-runtime.ts) when the host configuration enables RuntimeEvent persistence:

```typescript
// packages/runtime/src/tool-runtime.ts
if (this.host?.persistRuntimeEvents) {
  // Optional Phase 2: persist the tool's outcome
  await this.db.commitToolOutcome(toolInvocation.id, toolResult);
}

```

This conditional block represents the precise moment when execution state transitions from volatile memory to durable storage, enforcing the architectural T1/T2 separation.

### Architecture and Recovery Flow

The [`docs/architecture/runtime-resume-architecture.md`](https://github.com/apache/maka/blob/main/docs/architecture/runtime-resume-architecture.md) diagram documents how the Transaction-Recorder coordinates with the database during the T2 phase. This specification confirms that **T2 commitToolOutcome** is not merely a storage convenience but a structural requirement for the resume-capable runtime, ensuring that acknowledged tool results survive process termination.

## Summary

- **T2 commitToolOutcome** is the persistence phase following tool execution (T1) in Apache Maka’s two-phase commit model.
- The operation stores tool results in the **Task Ledger**, located in the database layer, enabling workflows to resume from exact prior states.
- Implementation resides in [`packages/runtime/src/tool-runtime.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/tool-runtime.ts) with retrieval logic in [`packages/runtime/src/terminal-run-commit.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/terminal-run-commit.ts).
- This mechanism delivers **fault tolerance** through durable resumption and **governance** through immutable audit trails.

## Frequently Asked Questions

### What is the difference between T1 and T2 in Apache Maka?

T1 refers to the execution phase where tools run and produce raw results, while T2 (**commitToolOutcome**) is the persistence phase where those results are permanently committed to the Task Ledger. T1 handles computation and capture; T2 guarantees durability and enables recovery.

### How does T2 commitToolOutcome enable session resumption?

When resuming a session, the runtime queries the Task Ledger via `db.getToolOutcome(invocationId)`. If T2 previously committed a result for that invocation, the runtime returns the cached outcome instead of re-executing the tool, allowing the workflow to continue from its exact interruption point without side-effect duplication.

### Where is the tool outcome stored in Apache Maka?

Tool outcomes are stored in the **Task Ledger**, a persistent database accessed through the runtime’s database interface. The `commitToolOutcome()` method in [`packages/runtime/src/tool-runtime.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/tool-runtime.ts) writes to this ledger, while [`packages/runtime/src/terminal-run-commit.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/terminal-run-commit.ts) handles retrieval during session recovery.

### Is the T2 commit step mandatory for all tool executions?

No, the T2 commit is optional and controlled by host configuration. The code in [`tool-runtime.ts`](https://github.com/apache/maka/blob/main/tool-runtime.ts) checks `this.host?.persistRuntimeEvents` before committing, meaning ephemeral or stateless runtimes can skip persistence, while production deployments enable it to support durable resumption and audit requirements.