crates/
  chaoscontrol-protocol/   # Wire format (no_std, zero deps)
  chaoscontrol-sdk/         # Guest SDK (no_std default, std feature)
  chaoscontrol-fault/       # Fault engine + property oracle
  chaoscontrol-vmm/         # VM, CPU, devices, controller, snapshots
  chaoscontrol-trace/       # eBPF tracing + determinism verification
  chaoscontrol-explore/     # Coverage-guided exploration engine
  chaoscontrol-replay/      # Recording, replay, time-travel debugger, triage
  chaoscontrol-guest/       # Minimal SDK-instrumented guest binary
  chaoscontrol-raft-guest/  # 3-node Raft consensus guest (dogfood target)
guest/                      # Pre-built initrd images
scripts/                    # Guest build + trace test scripts
tools/tracing/              # bpftrace scripts for KVM debugging
docs/                       # Design documents

protocol (no_std)
  ├── sdk (guest-side, no_std + std)
  ├── fault (host-side engine)
  │     └── vmm (VM + devices + controller)
  │           ├── explore (coverage-guided search)
  │           └── replay (recording + triage)
  └── trace (eBPF, independent)

# Enter devshell (required for clang, musl, libbpf)
nix develop

# Or run a single command without entering the shell
nix develop --command bash -c "cargo build --release"

# Build everything
cargo build --release

# Run all tests (616+ tests, no /dev/kvm needed for unit tests)
cargo test

# Run tests for a specific crate
cargo test -p chaoscontrol-vmm
cargo test -p chaoscontrol-raft-guest --lib

# Clippy (deny warnings — matches CI)
cargo clippy --all-targets -- -D warnings

# Format
cargo fmt --all

# Nix checks (build + clippy + fmt + tests, no /dev/kvm in sandbox)
nix flake check

# Boot a kernel (needs vmlinux ELF, NOT bzImage)
cargo run --bin boot -- result-dev/vmlinux guest/initrd.gz

# Snapshot demo
cargo run --release --bin snapshot_demo -- result-dev/vmlinux guest/initrd.gz

# Run SDK guest tests (requires /dev/kvm)
cargo run --release --bin sdk_guest_test -- result-dev/vmlinux guest/initrd-sdk.gz

# Integration tests (requires /dev/kvm)
cargo run --release --bin integration_test -- result-dev/vmlinux guest/initrd-sdk.gz

# Build SDK guest → guest/initrd-sdk.gz
nix develop --command bash -c "scripts/build-guest.sh"

# Build Raft guest → guest/initrd-raft.gz
nix develop --command bash -c "scripts/build-raft-guest.sh"

# Coverage-guided exploration
cargo run --release --bin chaoscontrol-explore -- run \
  --kernel result-dev/vmlinux \
  --initrd guest/initrd-raft.gz \
  --vms 3 --rounds 200 --branches 16 \
  --ticks 1000 --quantum 100 \
  --seed 42 --output results/

# Exploration with persistent disk image
cargo run --release --bin chaoscontrol-explore -- run \
  --kernel result-dev/vmlinux \
  --initrd guest/initrd-raft.gz \
  --disk-image data/ext4.img \
  --vms 3 --rounds 200 --branches 16

# Resume from checkpoint
cargo run --release --bin chaoscontrol-explore -- resume \
  --corpus results/ --rounds 500 \
  [--kernel path] [--initrd path]

# Replay a recording
cargo run --release --bin chaoscontrol-replay -- replay \
  --recording session.json [--checkpoint <id>] [--ticks <n>]

# Triage a bug (markdown or JSON report)
cargo run --release --bin chaoscontrol-replay -- triage \
  --recording session.json --bug-id 1 --format markdown

# Show recording metadata
cargo run --release --bin chaoscontrol-replay -- info \
  --recording session.json

# List events with optional filter
cargo run --release --bin chaoscontrol-replay -- events \
  --recording session.json [--filter faults|assertions|bugs] \
  [--from <tick>] [--to <tick>]

# Debug at specific tick
cargo run --release --bin chaoscontrol-replay -- debug \
  --recording session.json --tick <n>

# Live eBPF trace (requires sudo)
sudo chaoscontrol-trace live --pid <VMM_PID> --output trace.json

# Verify determinism between two traces
chaoscontrol-trace verify --trace-a run1.json --trace-b run2.json

# Summarize a trace
chaoscontrol-trace summary --trace run1.json

use chaoscontrol_sdk::{assert, coverage, lifecycle, random};

// Signal ready — gates fault injection
lifecycle::setup_complete(&[("role", "leader"), ("nodes", "3")]);

// Safety properties (immediate failure if violated)
assert::always(leader_count <= 1, "election safety", &[("term", &format!("{}", term))]);

// Liveness properties (fail if never true across ALL runs)
assert::sometimes(committed > 0, "value committed", &[]);

// Reachability
assert::reachable("leader elected", &[]);
assert::unreachable("split brain", &[]);

// Deterministic randomness (seeded by VMM)
let choice = random::random_choice(4);  // 0..3
let val = random::get_random();         // u64

// Coverage (AFL-style edge tracking)
coverage::init();
coverage::record_edge(location_id);

// Structured events
lifecycle::send_event("commit", &[("index", "42"), ("value", "x")]);

cc_assert_always!(cond, "message");
cc_assert_sometimes!(cond, "message");
cc_assert_reachable!("message");
cc_assert_unreachable!("message");

use chaoscontrol_vmm::{DeterministicVm, VmConfig, CpuConfig};

// Create and boot a VM
let config = VmConfig::default();  // 256MB, 3GHz TSC, deterministic cmdline
let mut vm = DeterministicVm::new(config)?;
vm.load_kernel("result-dev/vmlinux", Some("guest/initrd.gz"))?;

// Run modes
vm.run()?;                              // Run until exit
let output = vm.run_until("pattern")?;  // Run until serial matches
let (exits, idle) = vm.run_bounded(100_000)?;  // Bounded by exit count

// State access
let tsc = vm.virtual_tsc();
let exits = vm.exit_count();
let serial = vm.take_serial_output();

// Snapshots
let snap = vm.snapshot()?;
vm.restore(&snap)?;

// Coverage
vm.clear_coverage_bitmap();
let bitmap = vm.read_coverage_bitmap();

// Fault engine
vm.fault_engine_mut().force_setup_complete();
vm.fault_engine_mut().set_schedule(schedule);
let faults = vm.fault_engine_mut().poll_faults(virtual_ns);

use chaoscontrol_vmm::{SimulationController, SimulationConfig};

let config = SimulationConfig {
    num_vms: 3,
    vm_config: VmConfig::default(),
    kernel_path: "result-dev/vmlinux".into(),
    initrd_path: Some("guest/initrd-raft.gz".into()),
    seed: 42,
};
let mut ctrl = SimulationController::new(config)?;

// Run N ticks (relative, not absolute)
ctrl.run(1000)?;

// Round-robin step
let result = ctrl.step_round()?;

// Snapshot/restore all VMs
let snap = ctrl.snapshot_all()?;
ctrl.restore_all(&snap)?;

// Network faults
// Network faults (via fault schedule — preferred)
// Or direct fabric access:
ctrl.network_mut().send(0, 1, vec![42], ctrl.tick());
let can_reach = ctrl.network().can_reach(0, 1);

// Fault schedule
ctrl.set_schedule(schedule);
ctrl.force_setup_complete();  // For tests without SDK

use chaoscontrol_fault::{FaultScheduleBuilder, Fault};

let schedule = FaultScheduleBuilder::new()
    .at_ns(1_000_000, Fault::NetworkPartition {
        side_a: vec![0], side_b: vec![1, 2],
    })
    .at_ns(2_000_000, Fault::NetworkJitter {
        target: 0, jitter_ns: 50_000_000,       // ±50ms
    })
    .at_ns(2_000_000, Fault::NetworkBandwidth {
        target: 1, bytes_per_sec: 1_000_000,     // 1 MB/s
    })
    .at_ns(3_000_000, Fault::PacketDuplicate {
        target: 0, rate_ppm: 100_000,            // 10%
    })
    .at_ns(5_000_000, Fault::ProcessKill { target: 1 })
    .at_ns(8_000_000, Fault::NetworkHeal)
    .at_ns(10_000_000, Fault::ClockSkew {
        target: 0, offset_ns: 500_000,
    })
    .build();

use chaoscontrol_explore::{Explorer, ExplorerConfig};

let config = ExplorerConfig {
    num_vms: 3,
    kernel_path: "result-dev/vmlinux".into(),
    initrd_path: Some("guest/initrd-raft.gz".into()),
    seed: 42,
    branch_factor: 8,
    ticks_per_branch: 1000,
    max_rounds: 200,
    max_frontier: 50,
    quantum: 100,
    ..Default::default()
};
let mut explorer = Explorer::new(config)?;
let report = explorer.run()?;

// Resume from checkpoint
let checkpoint = load_checkpoint("results/checkpoint.json")?;
let mut explorer = Explorer::from_checkpoint(checkpoint, None, None, 500)?;

use chaoscontrol_replay::{Debugger, EventFilter, TriageEngine, load_recording};

let recording = load_recording("session.json")?;

// Time-travel debugger
let mut dbg = Debugger::new(&recording);
dbg.goto_bug(1);
dbg.rewind(100);
dbg.step_forward(10);
dbg.next_event(EventFilter::FailedAssertion);

// Triage
let report = TriageEngine::triage(&recording, 1);

clocksource=tsc tsc=reliable lpj=6000000 nokaslr noapic nosmp
randomize_kstack_offset=off norandmaps kfence.sample_interval=0
no_hash_pointers

// crates/chaoscontrol-my-guest/src/main.rs
use chaoscontrol_sdk::{assert, coverage, lifecycle, random};

fn main() {
    // Mount devtmpfs for SDK std transport (/dev/mem, /dev/port)
    unsafe {
        libc::mount(
            b"devtmpfs\0".as_ptr().cast(),
            b"/dev\0".as_ptr().cast(),
            b"devtmpfs\0".as_ptr().cast(),
            0, std::ptr::null(),
        );
    }

    coverage::init();
    lifecycle::setup_complete(&[("app", "my-guest")]);

    // Main workload — must loop forever (VMM controls horizon)
    loop {
        let choice = random::random_choice(4);
        coverage::record_edge(choice);

        // Do work based on choice...

        // Assert invariants
        assert::always(invariant_holds(), "my invariant", &[]);
        assert::sometimes(progress_made(), "liveness", &[]);
    }
}

cargo test                                    # All unit tests
cargo test -p chaoscontrol-fault              # Single crate
cargo test -p chaoscontrol-raft-guest --lib   # Lib tests only
cargo test -p chaoscontrol-vmm -- virtio      # Filter by name

cargo run --release --bin integration_test -- result-dev/vmlinux guest/initrd-sdk.gz
cargo run --release --bin sdk_guest_test -- result-dev/vmlinux guest/initrd-sdk.gz

nix develop --command bash -c "scripts/test-trace.sh"

cargo test -p chaoscontrol-raft-guest --lib