# LoopX Six Durable Control-Plane Layers: Architecture Explained

> Explore the LoopX architecture and its six durable control-plane layers: Registry, Goal State, Run Log, Run History, Status/Attention Queue, and Compute Quota. Understand the immutable backbone of the huangruiteng/loopx system.

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

---

**LoopX's control-plane architecture consists of six durable layers—Registry, Goal State, Run Log, Run History, Status/Attention Queue, and Compute Quota—that persist across process restarts and form the immutable backbone governing every goal's lifecycle in the huangruiteng/loopx system.**

The huangruiteng/loopx repository implements a robust control-plane built on six durable control-plane layers that survive process restarts and orchestrate goal execution. These layers, documented in [`docs/architecture.md`](https://github.com/huangruiteng/loopx/blob/main/docs/architecture.md) and implemented throughout the Python codebase, provide the persistent foundation that agents, heartbeats, and UI components rely on to manage goal lifecycles. Understanding this architecture is essential for anyone extending LoopX or integrating with its state management APIs.

## Overview of the Six Durable Layers

The LoopX architecture defines six distinct durable layers that constitute the persistent backbone of a goal's lifecycle. Each layer serves a specific function and is implemented in dedicated source files within the repository.

| Layer | Purpose | Key Implementation File |
|-------|---------|-------------------------|
| **Registry** | Catalog of known goals, repository locations, adapters, authority sources, status, and guard policies | [`loopx/registry.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/registry.py) |
| **Goal State** | Active state file holding current belief stack, priority list, non-goals, and next actionable item | [`loopx/state_refresh.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/state_refresh.py) |
| **Run Log** | Per-goal JSON and Markdown reports recording each turn's execution, diagnostics, and outcomes | [`loopx/feedback.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/feedback.py) |
| **Run History** | Compact indexes of past runs consumed by agents and heartbeats for decision-making | [`loopx/control_plane/work_items/runtime_capability_reentry.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/control_plane/work_items/runtime_capability_reentry.py) |
| **Status / Attention Queue** | First-screen summary surfacing who (agent or human) needs to act next based on registry and run history | [`loopx/control_plane/work_items/attention_queue.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/control_plane/work_items/attention_queue.py) |
| **Compute Quota** | Local policy capping automatic compute consumption per goal per turn | [`loopx/quota/heartbeat_recommendation.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/quota/heartbeat_recommendation.py) |

These layers are **durable** because they survive process restarts, are persisted on disk, and form the immutable contract that every turn, agent, and provider must respect.

## Layer 1: Registry

The **Registry** layer maintains a catalog of known goals, their repository locations, adapters, authority sources, current status, and guard policies. This centralized index allows the system to discover and manage goals across different contexts.

In [`loopx/registry.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/registry.py), the `Registry` class implements this layer:

```python
from loopx.registry import Registry

registry = Registry()
goal_meta = registry.get_goal("my-goal-id")

```

The registry serves as the entry point for the system to locate goal metadata and determine where persistent state files reside.

## Layer 2: Goal State

The **Goal State** layer stores the active state file for a single goal, holding the current belief stack, priority list, non-goals, and the next actionable item. This layer represents the runtime memory of a specific goal instance.

Implementation resides in [`loopx/state_refresh.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/state_refresh.py), which handles reading and writing the active-state JSON:

```python
from pathlib import Path

state_path = Path(goal_meta["state_file"])
active_state = state_path.read_text()

```

This file is updated after each turn to reflect the current understanding and commitments of the goal.

## Layer 3: Run Log

The **Run Log** layer generates per-goal JSON and Markdown reports that record each turn's execution details, diagnostics, and outcomes. This provides an audit trail of what happened during each execution cycle.

The [`loopx/feedback.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/feedback.py) module handles run-log generation:

```python
from loopx.feedback import append_run_log

append_run_log(goal_id="my-goal-id", turn_result={...})

```

These logs are essential for debugging and understanding the progression of goal execution over time.

## Layer 4: Run History

The **Run History** layer maintains compact indexes of past runs that agents, heartbeats, and UI components consume to make informed decisions. Unlike the detailed run logs, this layer provides optimized access patterns for historical analysis.

Accessed via [`loopx/control_plane/work_items/runtime_capability_reentry.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/control_plane/work_items/runtime_capability_reentry.py):

```python
from loopx.control_plane.work_items.runtime_capability_reentry import RuntimeCapabilityReentry

history = RuntimeCapabilityReentry.load_history(goal_id="my-goal-id")
latest_success = history[-1]

```

This layer enables the system to learn from previous turns and adjust behavior accordingly.

## Layer 5: Status / Attention Queue

The **Status / Attention Queue** layer generates a first-screen summary that surfaces who (agent or human) needs to act next. This projection is based on the registry, run history, and contract health, providing an actionable dashboard for operators.

Implemented in [`loopx/control_plane/work_items/attention_queue.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/control_plane/work_items/attention_queue.py):

```python
from loopx.control_plane.work_items.attention_queue import AttentionQueue

status = AttentionQueue.render(goal_id="my-goal-id")
print(status)

```

This layer bridges the internal state with user-facing interfaces, ensuring the right attention is directed to the right goals at the right time.

## Layer 6: Compute Quota

The **Compute Quota** layer enforces local policy that caps how much automatic compute each goal may consume during a turn. This prevents runaway execution and ensures fair resource allocation across competing goals.

Evaluated in [`loopx/quota/heartbeat_recommendation.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/quota/heartbeat_recommendation.py):

```python
from loopx.quota.heartbeat_recommendation import can_spend_quota

if can_spend_quota(goal_id="my-goal-id"):
    # launch host/runtime

    pass

```

This safety mechanism ensures that automatic processes do not consume unlimited resources without oversight.

## Optional Probe Surface

While not a durable layer itself, LoopX supports an optional **probe surface** that goals can register via a `next_probe` command. According to the architecture documentation in [`docs/architecture.md`](https://github.com/huangruiteng/loopx/blob/main/docs/architecture.md), this provides a read-only observation hook for monitoring goal state without altering any durable state.

Probe execution is intentionally limited to observation only, ensuring that monitoring activities cannot mutate the six durable layers.

## Complete Workflow Example

The following example demonstrates how a typical workflow touches all six durable layers in sequence:

```python

# 1️⃣  Load the Registry to discover a goal

from loopx.registry import Registry
registry = Registry()
goal_meta = registry.get_goal("my-goal-id")

# 2️⃣  Read the Goal's active state

from pathlib import Path
state_path = Path(goal_meta["state_file"])
active_state = state_path.read_text()

# 3️⃣  Append a Run-log entry after a turn finishes

from loopx.feedback import append_run_log
append_run_log(goal_id="my-goal-id", turn_result={...})

# 4️⃣  Query the Run history for the latest successful turn

from loopx.control_plane.work_items.runtime_capability_reentry import RuntimeCapabilityReentry
history = RuntimeCapabilityReentry.load_history(goal_id="my-goal-id")
latest_success = history[-1]

# 5️⃣  Generate the Status / Attention Queue for UI or heartbeat

from loopx.control_plane.work_items.attention_queue import AttentionQueue
status = AttentionQueue.render(goal_id="my-goal-id")

# 6️⃣  Check Compute Quota before spawning a new agent turn

from loopx.quota.heartbeat_recommendation import can_spend_quota
if can_spend_quota(goal_id="my-goal-id"):
    # launch host/runtime

    pass

```

This workflow illustrates how the layers interact to maintain durable state across the goal lifecycle.

## Summary

The six durable control-plane layers in huangruiteng/loopx provide a resilient foundation for goal-oriented computing:

- **Registry** ([`loopx/registry.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/registry.py)): Central catalog of goals and metadata
- **Goal State** ([`loopx/state_refresh.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/state_refresh.py)): Active runtime state including beliefs and priorities
- **Run Log** ([`loopx/feedback.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/feedback.py)): Detailed execution audit trails
- **Run History** ([`loopx/control_plane/work_items/runtime_capability_reentry.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/control_plane/work_items/runtime_capability_reentry.py)): Optimized historical indexes for decision-making
- **Status/Attention Queue** ([`loopx/control_plane/work_items/attention_queue.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/control_plane/work_items/attention_queue.py)): Actionable summaries for operators
- **Compute Quota** ([`loopx/quota/heartbeat_recommendation.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/quota/heartbeat_recommendation.py)): Resource consumption limits and safety controls

Together, these layers ensure that goal state persists across restarts and that every component in the system operates against a consistent, durable contract.

## Frequently Asked Questions

### What makes LoopX's control-plane layers "durable"?

These layers are durable because they are persisted on disk and survive process restarts. Unlike ephemeral memory or cache, the Registry, Goal State, Run Log, Run History, Status Queue, and Compute Quota are written to stable storage after each mutation, ensuring that goal progress is never lost due to system crashes or restarts.

### How does the Registry layer differ from the Goal State layer?

The **Registry** maintains a global catalog of all goals in the system, including their locations and policies, while **Goal State** contains the specific runtime data for an individual goal instance, such as its current belief stack and priority list. Think of the Registry as the card catalog in a library, and Goal State as the actual content of a specific book.

### What is the optional probe surface in LoopX?

The optional probe surface is a read-only observation mechanism that sits on top of the six durable layers. Goals can register a `next_probe` command to expose internal state for monitoring purposes, but as implemented in the architecture documentation, probe execution is strictly limited to observation and cannot modify any durable state, ensuring safe monitoring without side effects.

### How does the Compute Quota layer prevent runaway execution?

The **Compute Quota** layer enforces local policy caps on automatic compute consumption per goal per turn. Before spawning new agent turns, the system calls `can_spend_quota()` in [`loopx/quota/heartbeat_recommendation.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/quota/heartbeat_recommendation.py) to verify that the goal has not exceeded its allocated resources, preventing infinite loops or excessive resource consumption by malfunctioning agents.