# What the 'Completed' Decision Means in Apache Maka's RecoveryResolver

> Understand what the 'completed' decision means in Apache Maka's RecoveryResolver. Learn how tool invocations are permanently recorded for recovery.

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

---

**The "completed" decision in Apache Maka's RecoveryResolver signifies that a tool invocation has finished executing and its outcome is permanently recorded in the immutable event log, requiring no further recovery action.**

Apache Maka's RecoveryResolver serves as the single authority that examines immutable `RuntimeEvent` facts to determine the exact state of tool invocations after system crashes or restarts. Understanding the **"completed" decision** is critical for developers building reliable agentic workflows, as it represents the definitive state where a tool's work is finalized and safe to continue. This decision appears in the resolver's classification table alongside outcomes like `definitely_not_dispatched`, `indeterminate`, and `corruption`.

## The Two Scenarios That Trigger a Completed Decision

The RecoveryResolver returns `completed` in exactly two distinct event patterns documented in [`docs/architecture/runtime-recovery-resolver-adr.zh-CN.md`](https://github.com/apache/maka/blob/main/docs/architecture/runtime-recovery-resolver-adr.zh-CN.md). Both patterns confirm the tool produced a result before the system needs to take further action.

### Legacy Pre-Dispatch Completion

In legacy workflows, a tool may finish before crossing any dispatch boundary. The resolver identifies this when it observes:

- A `call` event
- A matching `response` event
- **No** `dispatch` event present

This combination indicates the tool's result was produced entirely within the caller's context without ever entering the dispatched execution phase.

### Standard Dispatched Completion

For modern dispatched operations, the resolver requires three concrete facts:

- A `call` event initiating the operation
- A `dispatch` event containing execution metadata
- A matching `response` event containing the result

This pattern confirms the tool implementation ran successfully within the dispatched context and recorded its output to the immutable log.

## Why the Completed Decision Matters

When the RecoveryResolver classifies an invocation as `completed`, three immediate consequences follow for the Apache Maka runtime:

- **No recovery work required**: The system skips re-dispatching, reconciling, or parking the tool invocation.
- **Safe continuation**: The surrounding Run proceeds immediately because side effects are already reflected in the immutable event log.
- **Fail-closed security**: Only the explicit event combinations above qualify as `completed`; ambiguous patterns default to safer states like `indeterminate` or `corruption` rather than assuming completion.

## Code Implementation and Event Patterns

The decision logic consumes events from [`packages/runtime/src/runtime-event-read-model.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/runtime-event-read-model.ts), which provides immutable facts to the resolver. Below are the TypeScript patterns that produce a `completed` classification according to the source code:

```typescript
// Legacy case: completion before dispatch (no dispatch boundary crossed)
runtimeEventStore.append({
  type: 'tool_call',
  actions: { toolCall: { toolName: 'calculator', params: { x: 1, y: 2 } } },
});
runtimeEventStore.append({
  type: 'tool_response',
  actions: { toolResult: { status: 'completed', result: 3 } },
});
// RecoveryResolver evaluates: call + response → decision = 'completed'

```

```typescript
// Standard case: dispatched tool execution with full audit trail
runtimeEventStore.append({
  type: 'tool_call',
  actions: { toolCall: { toolName: 'databaseQuery', params: { id: 123 } } },
});
runtimeEventStore.append({
  type: 'tool_dispatch',
  actions: { toolDispatch: { dispatchId: 'uuid-456', timestamp: Date.now() } },
});
runtimeEventStore.append({
  type: 'tool_response',
  actions: { toolResult: { status: 'completed', rows: [{ id: 123 }] } },
});
// RecoveryResolver evaluates: call + dispatch + response → decision = 'completed'

```

The test suite in [`packages/runtime/src/__tests__/recovery-resolver.test.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/__tests__/recovery-resolver.test.ts) verifies these exact patterns, ensuring the resolver correctly identifies completed invocations across crash scenarios and prevents duplicate execution.

## Summary

- The **"completed" decision** indicates a tool invocation finished executing and its result is permanently stored in Apache Maka's immutable event log.
- Apache Maka recognizes two valid patterns: legacy pre-dispatch completion (`call` + `response`) and standard dispatched completion (`call` + `dispatch` + `response`).
- Downstream components skip recovery steps entirely when encountering this decision, using the recorded result directly.
- The implementation follows a fail-closed design, routing ambiguous states to `indeterminate` or `corruption` rather than risking incorrect completion assumptions.
- Key source files include [`runtime-recovery-resolver-adr.zh-CN.md`](https://github.com/apache/maka/blob/main/runtime-recovery-resolver-adr.zh-CN.md) (lines 86-88) for the decision table and [`runtime-event-read-model.ts`](https://github.com/apache/maka/blob/main/runtime-event-read-model.ts) for event consumption.

## Frequently Asked Questions

### How does the RecoveryResolver distinguish between completed and definitely_not_dispatched?

The resolver checks for the presence of a `response` event. A `definitely_not_dispatched` decision occurs when only a `call` event exists without any subsequent `dispatch` or `response`, indicating the tool never began execution. The `completed` decision requires both a `call` and a matching `response`, proving the tool finished regardless of whether a `dispatch` event exists in the log.

### What happens if the event log contains a dispatch but no response?

When the RecoveryResolver observes a `call` and `dispatch` but lacks a matching `response`, it cannot assume completion. According to the fail-closed design implemented in Apache Maka's source code, this pattern typically routes to `indeterminate` or requires active reconciliation, as the system cannot verify whether the tool implementation actually executed or crashed mid-flight.

### Can downstream components override a completed decision from the RecoveryResolver?

No. The RecoveryResolver acts as the single authority for invocation state. When it returns `completed`, the Planner, CLI, and UI components must accept the recorded result in `toolResult` and refrain from issuing additional recovery commands. This immutable classification prevents duplicate executions and ensures exactly-once semantics for tool side effects across crashes.

### Where is the completed decision logic tested in the Apache Maka repository?

The verification lives in [`packages/runtime/src/__tests__/recovery-resolver.test.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/__tests__/recovery-resolver.test.ts), which validates that specific RuntimeEvent sequences correctly map to the `completed` outcome. The authoritative decision table specification resides in [`docs/architecture/runtime-recovery-resolver-adr.zh-CN.md`](https://github.com/apache/maka/blob/main/docs/architecture/runtime-recovery-resolver-adr.zh-CN.md) at lines 86-88, defining the exact event patterns that constitute completion.