How the LoopX Dreaming Module Generates Ranked Todo Proposals and Evidence Probes Without Consuming Delivery Quota

The LoopX dreaming module creates advisory dry-run proposals with explicit server-side planning contracts that enable ranking candidate todos and suggesting evidence probes while setting may_spend_delivery_quota to False, ensuring zero quota consumption during the analysis phase.

The dreaming module in the open-source LoopX repository serves as an advisory engine that analyzes goal execution history to suggest improvements without impacting delivery resources. By leveraging a sophisticated three-stage pipeline implemented in loopx/dreaming.py, this subsystem generates ranked todo proposals and evidence probes through a carefully designed dry-run mechanism that guarantees no delivery quota is spent until an operator explicitly approves the recommendation.

The Three-Stage Advisory Pipeline

The dreaming module processes historical run data through a strict pipeline that maintains advisory status throughout, ensuring that ranked todo proposals and evidence probes remain purely analytical until explicitly promoted.

Signal Extraction from Run History

The process begins with _signal_runs (lines 63-78 in loopx/dreaming.py), which filters the most recent non-neutral runs of a specific goal. This function deliberately excludes any classifications belonging to the advisory set DREAMING_ADVISORY_CLASSIFICATIONS to prevent recursive analysis loops. By focusing only on substantive execution history, the module ensures that downstream ranking logic operates on meaningful behavioral signals rather than advisory noise.

Proposal Classification and Identification

Once signal runs are collected, the _proposal_type function (lines 82-106) inspects the gathered metadata to classify the proposal into one of four categories: refactor warning, memory consolidation, archive suggestion, or exploration proposal. A deterministic proposal_id is then generated by hashing the goal identifier, proposal type, evidence window, and a short slice of run metadata. This guarantees that identical historical conditions produce consistent identifiers, enabling idempotent proposal handling across distributed components.

Dry-Run Contract Construction

The core mechanism preventing quota consumption resides in build_dreaming_dry_run_proposal (lines 206-238). This function constructs a server-side planning contract with three critical boolean flags:

• may_spend_delivery_quota: False
• may_rank_candidate_todos: True
• may_suggest_evidence_probes: True

Additionally, the proposal explicitly marks every potential side-effect as disabled: project_files_mutated, active_state_mutated, runtime_history_appended, and quota_spent are all set to False (lines 322-332). The function returns a compact list of up to five recent evidence items (lines 239-247) that downstream consumers use to rank candidate todos or suggest specific investigation probes without triggering resource allocation.

Implementation Architecture and File Structure

The dreaming functionality spans multiple files within the loopx/control_plane/status/ directory, each serving distinct responsibilities in the advisory pipeline:

• loopx/dreaming.py: Contains the core logic for signal extraction, proposal type classification, and the dry-run payload construction. This file implements the build_dreaming_dry_run_proposal and record_dreaming_proposal_decision functions that govern the advisory state.

• loopx/control_plane/status/dreaming_projection.py: Provides helper functions compact_dreaming_proposal and compact_dreaming_lane_badge that project dreaming data into UI-compatible formats for rendering in status dashboards.

• loopx/status.py: Imports the projection helpers (line 1048) and serves as the primary entry point for the control plane to access dreaming proposals, surfacing them to the rest of the system through standardized interfaces.

• loopx/quota.py: Registers the dreaming registry keys (dreaming_proposal, dreaming_lane_badge) with the quota engine, explicitly marking these operations as non-consuming to prevent accidental quota debiting during advisory phases.

• loopx/presentation/renderers/status_markdown.py: Renders the dreaming lane badge in human-readable status markdown, allowing operators to view ranked suggestions without executing them.

Practical Usage Example

The following implementation demonstrates how to generate advisory proposals and verify the quota protection mechanisms:

from pathlib import Path
from loopx.dreaming import (
    build_dreaming_dry_run_proposal,
    record_dreaming_proposal_decision
)

# 1. Prepare registry path and load history payload

registry_path = Path("/path/to/.loopx/registry.json")

# Assume history_payload is collected from the registry

history_payload = {
    "goals": {
        "optimization-task": {
            "runs": [
                {"classification": "success", "generated_at": "2024-01-15T10:00:00"},
                {"classification": "failure", "generated_at": "2024-01-15T09:30:00"}
            ]
        }
    }
}

# 2. Generate dreaming proposal without consuming quota

proposal = build_dreaming_dry_run_proposal(
    history_payload=history_payload,
    goal_id="optimization-task",
    limit=20,  # Examine up to 20 recent runs

)

# 3. Verify the protective contract constraints

contract = proposal["server_planning_contract"]
assert contract["may_spend_delivery_quota"] is False
assert contract["may_rank_candidate_todos"] is True
assert contract["may_suggest_evidence_probes"] is True

# 4. Process evidence for ranking (operator-defined logic)

for evidence in proposal["recent_evidence"]:
    priority = calculate_priority(evidence)  # Custom ranking function

    print(f"Rank {priority}: {evidence['classification']}")

# 5. Upon approval, record decision (still no quota spent)

decision = record_dreaming_proposal_decision(
    registry_path=registry_path,
    runtime_root_override=None,
    goal_id="optimization-task",
    proposal_id=proposal["proposal_id"],
    decision="approve",
    reason_summary="Accepted refactoring recommendation",
    todo_text="Extract utility functions to reduce duplication",
    claimed_by=None,
    dry_run=False,
)

print(decision["side_effects"]["quota_spent"])  # Output: False

Summary

The LoopX dreaming module enables safe, advisory planning through architectural constraints that separate analysis from execution:

• Signal isolation: The _signal_runs function filters advisory classifications to prevent recursive loops, ensuring evidence derives from actual execution history.
• Contractual protection: The server_planning_contract explicitly disables quota spending while enabling ranking and probe suggestion capabilities.
• Deterministic identification: Proposal IDs are cryptographic hashes of goal context, ensuring consistent identification across distributed systems.
• Explicit promotion: Only the record_dreaming_proposal_decision function can transition proposals from advisory to actionable states, and even then, quota consumption only occurs during actual execution, not during the dreaming phase.

Frequently Asked Questions

How does the dreaming module enforce zero quota consumption during proposal generation?

The enforcement occurs at the contract level in build_dreaming_dry_run_proposal (lines 206-238), where the returned payload contains a server_planning_contract with may_spend_delivery_quota explicitly set to False. Additionally, all side-effect indicators—including project_files_mutated, active_state_mutated, runtime_history_appended, and quota_spent—are hardcoded to False (lines 322-332), creating multiple layers of protection against accidental resource debiting.

What distinguishes the different proposal types generated by the dreaming module?

The _proposal_type function (lines 82-106 in loopx/dreaming.py) analyzes the semantic content of signal runs to categorize proposals as refactor warnings (indicating code quality degradation), memory consolidation (suggesting state cleanup), archive recommendations (identifying stale goals), or exploration proposals (for ambiguous failure patterns). Each type triggers different ranking algorithms when may_rank_candidate_todos is processed by downstream planners.

Where does the dreaming module obtain evidence for ranking candidate todos?

Evidence originates from the _signal_runs filter (lines 63-78), which extracts the most recent non-neutral runs from the goal's execution history while excluding any runs classified under DREAMING_ADVISORY_CLASSIFICATIONS. This prevents the system from using previous advisory outputs as input for new proposals, maintaining a clean separation between actual execution behavior and synthetic recommendations.

What occurs when an operator approves a dreaming proposal?

Upon approval via record_dreaming_proposal_decision, the system creates a concrete todo entry in the registry and potentially schedules execution tasks. However, the decision record itself still declares quota_spent: False, as the dreaming advisory phase consumed no resources. Actual quota consumption only begins when the approved todo enters the execution phase and requests delivery resources, ensuring that the ranking and suggestion process remains entirely cost-free.

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