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

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)

The persistence foundation resides in 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)

High-level inspection flows through 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:

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"])

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, 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 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.

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