# LoopX Quota Spend Sources and Settlement Validation Rules: Complete Implementation Guide

> Understand LoopX quota spend sources (runtime_events, visible-goal, heartbeat) and settlement validation rules for accurate budget accounting. Master implementation with this guide.

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

---

**LoopX implements three distinct quota spend sources—`runtime_events`, `visible-goal`, and `heartbeat`—and enforces strict settlement validation rules including identity consistency, step ordering, and idempotent replay to ensure accurate budget accounting.**

The LoopX agent execution framework (available at `huangruiteng/loopx`) provides a sophisticated **quota system** that controls resource consumption across agent turns. Understanding the **quota spend sources and settlement validation rules in LoopX** is essential for control plane integrators, as these mechanisms ensure that quota is spent only after durable writeback and within defined budget limits.

## Quota Spend Sources in LoopX

LoopX categorizes quota consumption into three distinct spend sources defined in [`loopx/control_plane/quota/spend_sources.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/control_plane/quota/spend_sources.py). Each source corresponds to a specific execution context and is stored in the `spend_source` field of the quota-spend payload.

### Runtime Events (Default)

The `runtime_events` source represents the standard agent execution path. Defined as **`DEFAULT_SLOT_SPEND_SOURCE`** in [`loopx/control_plane/quota/spend_sources.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/control_plane/quota/spend_sources.py), this source is selected when the quota spend triggers from the normal runtime event loop, as implemented in [`loopx/quota.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/quota.py) (line 407).

### Visible-Goal Scheduler Context

When execution originates from the visible-goal scheduler, LoopX uses the **`visible-goal`** source. The constant **`VISIBLE_GOAL_SLOT_SPEND_SOURCE`** identifies this path, selected when a goal is explicitly marked as visible in [`loopx/control_plane/quota/spend_sources.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/control_plane/quota/spend_sources.py) (line 29). This distinguishes scheduler-driven work from standard runtime events.

### Heartbeat-Driven Execution

The **`heartbeat`** source applies to periodic maintenance turns rather than direct commands. The heartbeat subsystem emits this source in [`loopx/control_plane/quota/effect_program.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/control_plane/quota/effect_program.py) (line 85) when driving turns via scheduled heartbeats, ensuring that background maintenance tasks are accounted for separately.

### Determining the Source Programmatically

The helper function **`quota_spend_source_for_execution_context()`** examines the scheduler’s execution context and returns the appropriate string identifier. This function bridges the control plane logic with the quota runtime, ensuring that the correct source is attached to the payload before submission to the quota system.

## Settlement Validation Rules in LoopX

Settlement validation ensures that quota spends are recorded only after successful turn completion and within budget constraints. The validation logic spans [`loopx/control_plane/turn_driver/settlement.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/control_plane/turn_driver/settlement.py) and [`loopx/control_plane/quota/settlement.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/control_plane/quota/settlement.py), performing checks that prevent over-consumption and ensure consistency.

### Identity Consistency Requirements

All effects within a single turn must share identical settlement identity fields including `goal_id`, `agent_id`, `todo_id`, and `effect_id`. The test suite in [`tests/test_turn_loop_disposition.py`](https://github.com/huangruiteng/loopx/blob/main/tests/test_turn_loop_disposition.py) (lines 128-129) verifies that mismatched identities trigger validation failures, ensuring that all effects are tied to the same logical turn.

### Step Ordering Constraints

Settlement plans must follow the exact sequence: **`host_execute → typed_result → validation → durable_writeback → quota_spend`**. This ordering, validated in [`tests/test_turn_loop_disposition.py`](https://github.com/huangruiteng/loopx/blob/main/tests/test_turn_loop_disposition.py) (lines 123-124), guarantees that quota is only spent after the state has been durably written, preventing budget loss for failed operations.

### Budget Enforcement and Presence Checks

The settlement driver rejects plans that would exceed available budget, raising **`budget_rejected`** errors as demonstrated in [`tests/test_loopx_turn_executor.py`](https://github.com/huangruiteng/loopx/blob/main/tests/test_loopx_turn_executor.py) (lines 2245-2247). Additionally, quota-spend effects appear only when the quota-should-run check succeeds, verified in [`tests/test_loopx_turn_transaction.py`](https://github.com/huangruiteng/loopx/blob/main/tests/test_loopx_turn_transaction.py) (lines 63-81), blocking quota spending for throttled turns.

### Idempotent Replay Guarantees

For crash recovery safety, replaying a settled turn must not generate duplicate quota spends. The **`idempotent_replay`** flag in [`tests/test_goal_mode_mcp_settlement.py`](https://github.com/huangruiteng/loopx/blob/main/tests/test_goal_mode_mcp_settlement.py) (lines 379-380) ensures that re-executing a turn with an existing settlement skips quota expenditure. The settlement-binding matching rule in [`tests/test_loopx_turn_driver.py`](https://github.com/huangruiteng/loopx/blob/main/tests/test_loopx_turn_driver.py) (lines 2246-2248) further detects mismatches between a turn’s journal and its settlement plan.

### Failure Propagation and No-Spend Scenarios

If any phase before quota spend fails (validation, write-back, etc.), the settlement result must report the failure without recording quota consumption, as tested in [`tests/test_loopx_turn_executor.py`](https://github.com/huangruiteng/loopx/blob/main/tests/test_loopx_turn_executor.py) (lines 2242-2244). Diagnostic commands explicitly set `spend_source` to empty strings (`""`) to avoid affecting budgets, demonstrated in [`tests/test_quota_settlement_cli.py`](https://github.com/huangruiteng/loopx/blob/main/tests/test_quota_settlement_cli.py) (line 2585), allowing quota-should-run queries without expenditure.

## Implementation Examples

The following examples demonstrate how to determine spend sources and execute settlement validation in LoopX applications.

```python
from loopx.control_plane.quota.spend_sources import quota_spend_source_for_execution_context

def build_quota_spend_payload(scheduler_ctx):
    """Construct a quota payload with the correct spend source."""
    source = quota_spend_source_for_execution_context(scheduler_ctx)
    
    payload = {
        "spend_source": source,               # "runtime_events", "visible-goal", or "heartbeat"

        "quota_spend_command": "record_turn", 
        "amount": 1
    }
    return payload

```

```python
from loopx.control_plane.turn_driver.settlement import execute_turn_driver_settlement

def run_turn(transaction):
    """Execute a turn and validate settlement before quota spend."""
    result = execute_turn_driver_settlement(transaction)
    
    if not result.ok:
        # Errors include budget_rejected, writeback_rejected, 

        # or quota_spend_before_writeback

        raise RuntimeError(f"Settlement failed: {result.failure}")
    
    # On success, result.settlement_plan includes ordered steps ending with quota_spend

    return result.settlement_plan

```

## Summary

- LoopX defines **three spend sources**: `runtime_events` (default agent execution), `visible-goal` (scheduler-driven goals), and `heartbeat` (periodic maintenance turns).
- The **`quota_spend_source_for_execution_context()`** function selects the appropriate source based on scheduler context in [`loopx/control_plane/quota/spend_sources.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/control_plane/quota/spend_sources.py).
- **Settlement validation** enforces strict step ordering (`host_execute` through `quota_spend`), ensuring quota is only spent after durable writeback.
- **Budget enforcement** rejects settlements that would exceed available quota, raising `budget_rejected` errors before recording spends.
- **Idempotent replay** prevents duplicate quota charges during crash recovery, verified by settlement-binding matching.
- **Failure propagation** ensures that failed turns (validation errors, writeback failures) do not consume quota, maintaining accurate budget tracking.

## Frequently Asked Questions

### What are the three quota spend sources in LoopX?

LoopX recognizes three quota spend sources defined in [`loopx/control_plane/quota/spend_sources.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/control_plane/quota/spend_sources.py): **`runtime_events`** for standard agent execution paths, **`visible-goal`** for scheduler-driven visible goals, and **`heartbeat`** for periodic maintenance turns. The helper function `quota_spend_source_for_execution_context()` returns the appropriate source string based on the current execution context.

### How does LoopX prevent duplicate quota spending during replay?

LoopX implements **idempotent replay** guards in the settlement driver ([`loopx/control_plane/turn_driver/settlement.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/control_plane/turn_driver/settlement.py)). When replaying a settled turn, the system checks the `idempotent_replay` flag and validates settlement-binding matching (verified in [`tests/test_goal_mode_mcp_settlement.py`](https://github.com/huangruiteng/loopx/blob/main/tests/test_goal_mode_mcp_settlement.py) lines 379-380). If a settlement already exists for the turn identity, the quota spend step is skipped, preventing double-charging during crash recovery.

### What happens if a turn fails before the quota spend phase?

If any phase before quota spend fails—such as validation or durable writeback—the settlement result reports the specific failure (e.g., **`writeback_rejected`** or validation errors) and **no quota is consumed**. This failure propagation mechanism, tested in [`tests/test_loopx_turn_executor.py`](https://github.com/huangruiteng/loopx/blob/main/tests/test_loopx_turn_executor.py) (lines 2242-2244), ensures that the quota budget remains accurate when turns abort early, maintaining the invariant that quota is only spent for successfully completed turns.

### Where are the spend source constants defined in the LoopX codebase?

The spend source constants **`DEFAULT_SLOT_SPEND_SOURCE`** and **`VISIBLE_GOAL_SLOT_SPEND_SOURCE`** are defined in [`loopx/control_plane/quota/spend_sources.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/control_plane/quota/spend_sources.py). The `heartbeat` source is referenced in [`loopx/control_plane/quota/effect_program.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/control_plane/quota/effect_program.py) (line 85), while the top-level quota API in [`loopx/quota.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/quota.py) (line 407) attaches these sources to the quota-spend payload sent to the runtime.