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

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. 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, which provides immutable facts to the resolver. Below are the TypeScript patterns that produce a completed classification according to the source code:

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

// 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 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 (lines 86-88) for the decision table and 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, 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 at lines 86-88, defining the exact event patterns that constitute completion.

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