# LoopX Turn Journal Runtime: How It Tracks Execution History and Enables Deterministic Replay

> Discover LoopX's Turn Journal Runtime. Learn how it tracks execution history and enables deterministic replay for tamper-proof execution in this Python façade.

- Repository: [huangruiteng/loopx](https://github.com/huangruiteng/loopx)
- Tags: internals
- Published: 2026-09-04

---

**The Turn Journal Runtime is the Python façade that interprets and validates turn journals while delegating persistence logic to the TypeScript Effect Runtime, enabling LoopX to maintain tamper-proof execution history with deterministic replay capabilities.**

The **Turn Journal Runtime** sits at the heart of LoopX's control plane, providing the critical bridge between Python execution logic and the system's immutable execution log. Located in `loopx/control_plane/turn_driver/turn_journal_runtime`, this component tracks every *turn*—the smallest unit of work a goal performs—by validating schema contracts and coordinating with the TypeScript-based Effect Runtime to ensure reliable state recovery across distributed hosts.

## How the Turn Journal Runtime Works

### The Journal Store Layer ([`journal_store.py`](https://github.com/huangruiteng/loopx/blob/main/journal_store.py))

The persistence foundation resides in [`loopx/control_plane/turn_driver/journal_store.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/control_plane/turn_driver/journal_store.py), which manages the physical storage of execution history. For every goal and turn combination, the store creates a unique JSON file path via `turn_journal_path`, persisting entries that conform to the strict schema identified by `LOOPX_TURN_JOURNAL_SCHEMA_VERSION = "loopx_turn_journal_v0"`. Each journal file contains critical fields including `status`, `plan`, `completed_phases`, and optional `tombstone_retained` flags that facilitate host-side cleanup operations.

### Runtime Interface: Interpretation and Writes

The runtime exposes two primary public functions that handle all journal interactions. The `interpret_turn_journal_projection` function requests a read-only inspection of the current journal state, while `write_turn_journal` commits new transitions to the log. When invoked, these functions construct requests containing `goal_id`, `agent_id`, `turn_key`, and optional `session_recovery_check` parameters. Every response undergoes strict validation against `TURN_JOURNAL_INSPECTION_SCHEMA_VERSION = "loopx_turn_journal_inspection_v1"`, ensuring that only schema-compliant projections reach the Python execution layer.

### Effect Runtime Delegation

Rather than implementing journal semantics directly in Python, the Turn Journal Runtime delegates all authoritative logic to the **Effect Runtime** (`effect_runtime_result`). This TypeScript-based layer owns the `turn_journal.inspect` and `turn_journal.write` operations, guaranteeing that semantic rules live in a single, type-safe codebase while Python acts strictly as a validated client. This delegation pattern centralizes business logic ownership in TypeScript while allowing Python to safely query and update execution history without risking journal corruption.

### Executor Integration ([`executor.py`](https://github.com/huangruiteng/loopx/blob/main/executor.py))

High-level inspection flows through [`loopx/control_plane/turn_driver/executor.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/control_plane/turn_driver/executor.py), which provides the `inspect_loopx_turn_journal` function. This executor locks the journal file to prevent race conditions, loads the JSON checkpoint, and invokes `interpret_turn_journal_projection` to obtain a side-effect-free projection. The returned payload includes boolean flags such as `replay_legal` and `journal_consistent`, along with detailed arrays of `completed_phases`, any detected `violations`, and a `recovery_decision` that guides failure handling strategies.

## Tracking Execution History and State Recovery

### Schema-Validated Projections

Every interaction with the turn journal enforces **schema-level correctness** through hardcoded version constants and projection key validation. The runtime explicitly checks that inspection payloads contain required fields like `completed_phases` and `status`, rejecting any journal entries that deviate from the expected structure. This validation guarantees that execution history remains tamper-proof and interpretable across system restarts or host migrations.

### Replay Legality and Recovery Decisions

When a turn fails, the runtime evaluates whether to retry execution using the `retry_failed` parameter and `session_recovery_check` data describing host-session binding outcomes. The `_validate_recovery_decision` and `_validate_recovery_audit` functions scrutinize these requests against the current journal state, ensuring that recovery operations only proceed when the projection indicates `replay_legal` is true. This mechanism prevents unsafe re-execution of turns that have already produced side effects or violated consistency constraints, enabling deterministic recovery workflows.

## Working with the Turn Journal Runtime

The following examples demonstrate read-only inspection and state-changing write operations using the public API:

```python
from pathlib import Path
from loopx.control_plane.turn_driver import (
    inspect_loopx_turn_journal,
    turn_journal_path,
)

# -------------------------------------------------

# 1️⃣ Inspect a turn journal (read-only)

# -------------------------------------------------

runtime_root = Path("/tmp/loopx_runtime")
goal_id = "my_goal"
agent_id = "agent_123"
turn_key = "turn_001"

inspection = inspect_loopx_turn_journal(
    runtime_root,
    goal_id=goal_id,
    agent_id=agent_id,
    turn_key=turn_key,
)

print("Can this turn be replayed?", inspection["replay_legal"])
print("Completed phases:", inspection["completed_phases"])

```

```python
from loopx.control_plane.turn_driver.turn_journal_runtime import write_turn_journal
from loopx.control_plane.turn_driver import turn_journal_path

# -------------------------------------------------

# 2️⃣ Write a new journal entry (commit a transition)

# -------------------------------------------------

journal_path = str(
    turn_journal_path(runtime_root, goal_id=goal_id, turn_key=turn_key)
)
new_journal = {
    "status": "started",
    "plan": {"action": "process_data", "params": {}},
    "completed_phases": [],
    "schema_version": "loopx_turn_journal_v0",
}

result = write_turn_journal(
    journal_path,
    new_journal,
    expected_effect_id=None,  # optional effect tracking

)

print("Append successful?", result["appended"])
print("Operation ID:", result["operation_id"])

```

Both functions ultimately invoke the Turn Journal Runtime, which validates schemas and forwards requests to the Effect Runtime for execution.

## Summary

- The **Turn Journal Runtime** acts as a Python façade that delegates journal semantics to the TypeScript Effect Runtime, ensuring centralized ownership of execution logic.
- **Schema validation** occurs at every entry point, with hardcoded versions like `loopx_turn_journal_v0` preventing incompatible journal formats from corrupting the execution history.
- The runtime provides **deterministic replay capabilities** through the `replay_legal` projection flag, which considers `completed_phases`, `violations`, and `session_recovery_check` data.
- **Recovery decisions** are validated by `_validate_recovery_decision` and `_validate_recovery_audit`, enabling safe retry logic only when journal consistency checks pass.
- Execution history is physically stored in JSON files managed by [`journal_store.py`](https://github.com/huangruiteng/loopx/blob/main/journal_store.py), with each turn receiving isolated persistence via `turn_journal_path` constructions.

## Frequently Asked Questions

### What is the relationship between the Turn Journal Runtime and the Effect Runtime?

The Turn Journal Runtime serves as a Python client that delegates all semantic journal operations to the TypeScript-based Effect Runtime. This architecture ensures that journal ownership and business logic remain centralized in the type-safe TypeScript layer, while Python acts strictly as a validated intermediary that interprets projections and initiates write requests.

### How does LoopX validate the integrity of a turn journal entry?

The runtime enforces integrity through strict schema validation against constants like `LOOPX_TURN_JOURNAL_SCHEMA_VERSION` and `TURN_JOURNAL_INSPECTION_SCHEMA_VERSION`. Additionally, the `interpret_turn_journal_projection` function validates that returned payloads contain required keys such as `journal_consistent`, while recovery functions `_validate_recovery_decision` audit state transitions for compliance with execution invariants.

### What determines whether a turn can be replayed in LoopX?

The `replay_legal` boolean in the journal projection determines replay eligibility, calculated by the Effect Runtime based on the sequence of `completed_phases`, detected `violations`, and the `session_recovery_check` describing host-session binding outcomes. Turns with committed side effects or consistency violations return `replay_legal: false`, preventing unsafe re-execution.

### Where are turn journals physically stored in the LoopX system?

Turn journals are persisted as individual JSON files per goal and turn via the [`journal_store.py`](https://github.com/huangruiteng/loopx/blob/main/journal_store.py) module, with file paths constructed by the `turn_journal_path` utility and stored within the runtime root directory. Each JSON file tracks `status`, `plan` details, `completed_phases`, and retention flags like `tombstone_retained` for distributed cleanup coordination.