Module merge_queue 

Merge queue for tracking parallel loop merges.

The merge queue maintains an append-only log of merge events, tracking loops from completion through successful merge or failure. It uses JSONL format for durability and easy debugging.

Design

• JSONL persistence: Append-only log at .ralph/merge-queue.jsonl
• File locking: Uses flock() for concurrent access safety
• Event sourcing: State is derived from event history

Example

use ralph_core::merge_queue::{MergeQueue, MergeQueueError};

fn main() -> Result<(), MergeQueueError> {
    let queue = MergeQueue::new(".");

    // Queue a completed loop for merge
    queue.enqueue("ralph-20250124-a3f2", "implement auth")?;

    // Get next pending loop
    if let Some(entry) = queue.next_pending()? {
        // Mark as merging
        queue.mark_merging(&entry.loop_id, std::process::id())?;

        // ... perform merge ...

        // Mark result
        queue.mark_merged(&entry.loop_id, "abc123def")?;
    }

    Ok(())
}

Structs

MergeEntry

Summary of a loop’s merge status.

MergeEvent

A merge queue event recorded in the JSONL log.

MergeOption

An option for merge steering.

MergeQueue

Merge queue for tracking parallel loop merges.

SteeringDecision

Decision about whether a merge needs user steering.

Enums

MergeButtonState

State of the merge button for a loop.

MergeEventType

Types of merge events.

MergeQueueError

Errors that can occur during merge queue operations.

MergeState

Current state of a loop in the merge queue.

Functions

merge_button_state

Get the merge button state for a loop.

merge_execution_summary

Generate an execution summary for a completed merge.

merge_needs_steering

Check if a merge needs user steering (e.g., due to conflicts).

smart_merge_summary

Generate a smart merge summary from worktree commits.