LoopX Turn Decision Vocabulary: LoopXTurnRoute and LoopXTurnResultKind Explained

LoopX uses two tightly-coupled typed contracts—LoopXTurnRoute for routing intent and LoopXTurnResultKind for outcome classification—to declaratively manage adaptive execution paths across its control plane.

The huangruiteng/loopx repository implements a deterministic turn-processing pipeline where every envelope transition is governed by explicit enum contracts. These LoopX turn decision vocabulary types eliminate ambiguity between the driver's routing logic and the host's execution results, ensuring type-safe communication from validation through completion.

LoopXTurnRoute: The Intent Routing Contract

LoopXTurnRoute is an enum defined in loopx/control_plane/turn_driver/driver.py that classifies the intended next step for a turn after envelope validation. Created by the _typed_route() helper, it bridges the gap between incoming scheduler requests and the actual execution strategy.

Route Determination Logic

The _typed_route() function (lines 59-96 in driver.py) applies a strict decision tree:

1. Envelope Sanity Checks – Validates schema version, signature match, and budget compliance. Failures immediately yield CONTRACT_ERROR.
2. Execution Intent Verification – Checks if should_run is True. When false, the logic evaluates user-action requirements or quiet-noop conditions, returning USER_ACTION_REQUIRED, WAIT, or BLOCKED.
3. Action Classification – Compares the effective action against predefined sets:
   • REPLAN_ACTIONS → REPLAN_REQUIRED
   • REPAIR_ACTIONS (or any action ending with _repair / _repair_required) → REPAIR_REQUIRED
4. Default Routing – When the envelope is runnable and requires no special handling, the route becomes READY_FOR_HOST.

Core Route Values

The enum defines seven distinct routing states:

• READY_FOR_HOST – Standard execution path; hand off to the host implementation.
• REPAIR_REQUIRED – Trigger repair logic due to action classification or error recovery.
• REPLAN_REQUIRED – Invoke replanning strategies for adjusted execution.
• USER_ACTION_REQUIRED – Block execution pending external user intervention.
• WAIT – Defer processing until conditions change.
• BLOCKED – Prevent execution due to policy or dependency constraints.
• CONTRACT_ERROR – Terminal state for validation failures (schema, signature, or budget).

LoopXTurnResultKind: The Outcome Classification Contract

LoopXTurnResultKind (defined in loopx/control_plane/turn_driver/transaction.py, line 29) describes the terminal outcome once the host, repair, or replan logic finishes execution. The _result_kind() helper (lines 168-170) maps raw execution results to these typed values.

Success and Failure States

The enum captures granular completion states:

Success States:

• VALIDATED_PROGRESS – Turn executed successfully but workflow continues.
• VALIDATED_COMPLETION – Turn finished and marked complete.

Failure States:

• HOST_FAILURE – Unhandled exception during host execution.
• VALIDATION_FAILED – Post-execution validation rejected the results.
• WRITEBACK_FAILED – State persistence error after successful execution.
• QUOTA_SPEND_FAILED – Budget or resource quota exceeded.
• REPAIR_REQUIRED, REPLAN_REQUIRED, USER_ACTION_REQUIRED, WAIT – Mirrored from routing when the host determines these actions are needed post-execution.

Source Code Implementation

According to the LoopX source code, these contracts reside in specific control-plane modules:

File	Key Component
loopx/control_plane/turn_driver/driver.py	Implements _typed_route() and LoopXTurnRoute enum (lines 45, 59-96).
loopx/control_plane/turn_driver/transaction.py	Defines LoopXTurnResultKind and _result_kind() mapping (lines 29, 168-170).
loopx/control_plane/turn_driver/executor.py	Consumes both enums to drive host execution, error recovery, and result reporting.
tests/test_loopx_turn_driver.py	Unit tests validating routing logic and result-kind mappings.

Practical Usage Examples

Import the contracts and implement decision logic in your turn-processing loop:

from loopx.control_plane.turn_driver.driver import LoopXTurnRoute, _typed_route
from loopx.control_plane.turn_driver.transaction import LoopXTurnResultKind

def process_incoming_turn(envelope: dict) -> None:
    # Determine routing intent based on envelope state

    route = _typed_route(envelope)
    
    if route is LoopXTurnRoute.CONTRACT_ERROR:
        raise ValueError("Envelope failed contract validation")
    
    if route is LoopXTurnRoute.READY_FOR_HOST:
        result = execute_host_operation(envelope)
        
        # Interpret the terminal result kind

        result_kind = LoopXTurnResultKind(result.get("result_kind"))
        
        if result_kind is LoopXTurnResultKind.VALIDATED_COMPLETION:
            commit_state(envelope)
        elif result_kind is LoopXTurnResultKind.REPAIR_REQUIRED:
            trigger_repair_flow(envelope)
        elif result_kind in (LoopXTurnResultKind.HOST_FAILURE, 
                           LoopXTurnResultKind.VALIDATION_FAILED):
            escalate_error(result_kind, envelope)

For testing route determination directly:

def test_repair_classification():
    envelope = {
        "action": "database_repair_required",
        "should_run": True,
        "schema_version": "v2"
    }
    route = _typed_route(envelope)
    assert route is LoopXTurnRoute.REPAIR_REQUIRED

Summary

• LoopXTurnRoute classifies pre-execution intent via _typed_route() in driver.py, handling validation, blocking, and action-specific routing through seven enum members.
• LoopXTurnResultKind captures post-execution outcomes via _result_kind() in transaction.py, distinguishing between progress, completion, and specific failure modes.
• Both enums provide type-safe contracts that decouple the turn driver's routing logic from host implementation details.
• The executor.py module consumes these values to orchestrate host launches, repairs, replans, and error handling.

Frequently Asked Questions

What triggers the REPLAN_REQUIRED route in LoopX?

The REPLAN_REQUIRED route activates when _typed_route() detects an action present in the REPLAN_ACTIONS set during the action classification phase. This typically occurs when the incoming envelope specifies an execution strategy that requires workflow restructuring before the host can process the turn.

How does LoopXTurnResultKind differ from LoopXTurnRoute?

LoopXTurnRoute determines what should happen next before execution begins, while LoopXTurnResultKind describes what actually happened after the host, repair, or replan logic completes. The route drives control-flow decisions, whereas the result kind captures terminal states for logging, metrics, and error handling.

Can a turn result in REPAIR_REQUIRED after successfully reaching the host?

Yes. Even when the initial route is READY_FOR_HOST, the LoopXTurnResultKind.REPAIR_REQUIRED value can emerge from _result_kind() if the host execution detects recoverable errors requiring intervention, or if post-execution validation fails in a way that suggests repair rather than replanning.

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