WARP.md

This file provides guidance to WARP (warp.dev) when working with code in this repository.

Project Overview

This is a Rust-based traffic light simulation demonstrating distributed state machine replication. The core concept models a four-way intersection where:

• A "Core" thread generates random actions
• Actions are distributed to replica threads (simulating network transfer via cloning)
• Each replica independently processes its actions and maintains intersection state
• The Core also processes all actions sequentially to show the canonical state progression

Common Commands

Build and Run

cargo build              # Build the project
cargo run                # Run the simulation
cargo run --release      # Run optimized version

Testing

cargo test               # Run all tests
cargo test test_intersection          # Run specific test
cargo test -- --nocapture              # Run tests with output

Development

cargo check              # Fast compilation check without binary
cargo clippy             # Lint with Clippy
cargo fmt                # Format code

Architecture

State Machine Model

The FourWayIntersection is a deterministic state machine with valid states:

1. North/South: Red → Green → Yellow → Red
2. East/West: Red → Green → Yellow → Red
3. Only opposing directions (N/S or E/W) can be Green simultaneously

Invalid states are automatically reset to all-Red to maintain safety.

Action System

Three action types with probabilistic generation:

• Next (70%): Advance intersection to next valid state
• Sleep(u64) (20%): Thread sleep for 0-3 seconds (simulates network delay)
• Glitch(FourWayIntersection) (10%): Force arbitrary state (simulates Byzantine faults)

Replication Flow

1. Core Thread: Generates 30 random actions, distributes to 3 replicas via HashMap
2. Network Transfer: Simulated by cloning the actions HashMap
3. Replica Threads: Run in parallel using thread::scope, each processing only its assigned actions
4. Verification: Core sequentially processes all actions to show expected final states per replica

Key Trade-offs

• Consistency: Replicas may diverge due to Glitch actions (Byzantine fault simulation)
• Parallelism: Uses scoped threads for automatic cleanup, avoiding 'static lifetime constraints
• Determinism: Given same action sequence, a replica produces same state (except for Sleep timing)

Code Organization

• src/main.rs: Single-file implementation containing:
  • TrafficLight enum: Individual light states (Red/Yellow/Green)
  • Action enum: Operations that can be performed
  • FourWayIntersection struct: Main state machine with transition logic
  • main(): Orchestrates Core and Replica simulation
  • tests module: Validates state transitions including invalid state recovery

Diagrams

/scoped/main.rs

graph LR;
    A[Core] --> B{Event};
    B --Sleep--> C(Replica);
    B --Next--> D(Replica);

Loading