# LoopX Turn Decision Vocabulary: LoopXTurnRoute and LoopXTurnResultKind Explained

> Understand LoopX turn decision vocabulary: LoopXTurnRoute for routing intent and LoopXTurnResultKind for outcome classification. Declaratively manage adaptive execution paths.

- Repository: [huangruiteng/loopx](https://github.com/huangruiteng/loopx)
- Tags: api-reference
- Published: 2026-08-07

---

**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`](https://github.com/huangruiteng/loopx/blob/main/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`](https://github.com/huangruiteng/loopx/blob/main/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`](https://github.com/huangruiteng/loopx/blob/main/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`](https://github.com/huangruiteng/loopx/blob/main/loopx/control_plane/turn_driver/driver.py) | Implements `_typed_route()` and `LoopXTurnRoute` enum (lines 45, 59-96). |
| [`loopx/control_plane/turn_driver/transaction.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/control_plane/turn_driver/transaction.py) | Defines `LoopXTurnResultKind` and `_result_kind()` mapping (lines 29, 168-170). |
| [`loopx/control_plane/turn_driver/executor.py`](https://github.com/huangruiteng/loopx/blob/main/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`](https://github.com/huangruiteng/loopx/blob/main/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:

```python
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:

```python
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`](https://github.com/huangruiteng/loopx/blob/main/driver.py), handling validation, blocking, and action-specific routing through seven enum members.
- **LoopXTurnResultKind** captures post-execution outcomes via `_result_kind()` in [`transaction.py`](https://github.com/huangruiteng/loopx/blob/main/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`](https://github.com/huangruiteng/loopx/blob/main/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.