#![allow(
    clippy::cast_precision_loss,
    clippy::cast_sign_loss,
    clippy::missing_const_for_fn
)]

use std::fs;
use std::sync::Arc;
use std::time::Duration;

use tidaldb::wal::checkpoint::CheckpointManager;
use tidaldb::wal::format::{self, EventRecord, HEADER_SIZE};
use tidaldb::wal::reader;
use tidaldb::wal::segment;
use tidaldb::wal::{SignalEvent, WalConfig, WalHandle};

fn test_config(dir: &std::path::Path) -> WalConfig {
    WalConfig {
        dir: dir.to_path_buf(),
        segment_size: 16 * 1024 * 1024,
        batch_size: 100,
        batch_timeout: Duration::from_millis(10),
        dedup_window: Duration::from_secs(30),
    }
}

fn make_event(id: u64) -> SignalEvent {
    SignalEvent {
        entity_id: id,
        signal_type: 1,
        weight: 1.0,
        timestamp_nanos: id * 1_000_000_000,
    }
}

// -- AC-1, AC-2: Wire format byte-level tests are in format.rs unit tests.
// These integration tests validate the full pipeline.

#[test]
fn wal_basic_round_trip() {
    let dir = tempfile::tempdir().expect("tempdir creation should succeed");
    let config = test_config(dir.path());

    // Write events
    let (handle, replayed) = WalHandle::open(config).expect("open should succeed");
    assert!(replayed.is_empty());

    for i in 1..=10 {
        handle.append(make_event(i)).expect("append should succeed");
    }
    handle.shutdown().expect("shutdown should succeed");

    // Reopen and verify replay
    let config = test_config(dir.path());
    let (handle, replayed) = WalHandle::open(config).expect("reopen should succeed");
    assert_eq!(replayed.len(), 10);
    for (i, event) in replayed.iter().enumerate() {
        assert_eq!(event.entity_id, (i + 1) as u64);
        assert_eq!(event.signal_type, 1);
        assert_eq!(event.weight.to_bits(), 1.0_f32.to_bits());
    }
    handle.shutdown().expect("shutdown should succeed");
}

// -- AC-10, AC-11: Deduplication
#[test]
fn wal_dedup_silent() {
    let dir = tempfile::tempdir().expect("tempdir creation should succeed");
    let config = test_config(dir.path());

    let (handle, _) = WalHandle::open(config).expect("open should succeed");

    let event = make_event(42);
    let seq1 = handle
        .append(event.clone())
        .expect("first append should succeed");
    let seq2 = handle
        .append(event.clone())
        .expect("second append should succeed");
    let seq3 = handle.append(event).expect("third append should succeed");

    assert!(seq1 > 0, "first event should get real sequence number");
    assert_eq!(seq2, 0, "duplicate should return seq=0");
    assert_eq!(seq3, 0, "duplicate should return seq=0");

    handle.shutdown().expect("shutdown should succeed");

    // Verify only one event on disk
    let config = test_config(dir.path());
    let (handle, replayed) = WalHandle::open(config).expect("reopen should succeed");
    assert_eq!(replayed.len(), 1, "only one unique event should be on disk");
    handle.shutdown().expect("shutdown should succeed");
}

// -- AC-12: No false positives
#[test]
fn wal_dedup_no_false_positives() {
    let dir = tempfile::tempdir().expect("tempdir creation should succeed");
    // Use a large batch size so batches fill quickly from concurrent writers.
    let config = WalConfig {
        dir: dir.path().to_path_buf(),
        segment_size: 16 * 1024 * 1024,
        batch_size: 256,
        batch_timeout: Duration::from_millis(5),
        dedup_window: Duration::from_secs(60),
    };

    let (handle, _) = WalHandle::open(config).expect("open should succeed");
    let handle = Arc::new(handle);

    let total_events: u64 = 100_000;
    let num_threads = 10u64;
    let per_thread = total_events / num_threads;

    let mut threads = Vec::new();
    for t in 0..num_threads {
        let handle = Arc::clone(&handle);
        threads.push(std::thread::spawn(move || {
            let mut count = 0u64;
            for i in 0..per_thread {
                let entity_id = t * per_thread + i;
                let event = SignalEvent {
                    entity_id,
                    #[allow(clippy::cast_possible_truncation)]
                    signal_type: (entity_id % 256) as u8,
                    weight: entity_id as f32,
                    timestamp_nanos: entity_id * 1_000_000,
                };
                let seq = handle.append(event).expect("append should succeed");
                if seq > 0 {
                    count += 1;
                }
            }
            count
        }));
    }

    let mut real_seqs = 0u64;
    for thread in threads {
        real_seqs += thread.join().expect("thread should join");
    }

    let handle = Arc::try_unwrap(handle).expect("should be sole owner of WalHandle Arc");
    handle.shutdown().expect("shutdown should succeed");

    assert_eq!(
        real_seqs, total_events,
        "all {total_events} unique events must be accepted (no false positives)"
    );
}

// -- AC-5, AC-6: Segment rotation
#[test]
fn wal_segment_rotation() {
    let dir = tempfile::tempdir().expect("tempdir creation should succeed");
    // Use very small segment size to force rotation
    let config = WalConfig {
        dir: dir.path().to_path_buf(),
        segment_size: 256, // tiny: one batch exceeds this
        batch_size: 10,
        batch_timeout: Duration::from_millis(10),
        dedup_window: Duration::from_secs(30),
    };

    let (handle, _) = WalHandle::open(config).expect("open should succeed");

    // Write enough events to trigger multiple rotations
    for i in 1..=100 {
        handle.append(make_event(i)).expect("append should succeed");
    }
    handle.shutdown().expect("shutdown should succeed");

    // Check segment files exist
    let wal_dir = dir.path().join("wal");
    let segments = segment::list_segments(&wal_dir).expect("list should succeed");
    assert!(
        segments.len() > 1,
        "expected multiple segments, got {}",
        segments.len()
    );

    // Verify segment naming: all should match wal-{seq:020}.seg pattern
    for (seq, path) in &segments {
        let filename = path
            .file_name()
            .expect("should have filename")
            .to_str()
            .expect("should be valid UTF-8");
        assert_eq!(
            filename,
            segment::segment_filename(*seq),
            "segment filename mismatch"
        );
    }

    // Verify replay gets all events
    let config = WalConfig {
        dir: dir.path().to_path_buf(),
        segment_size: 256,
        batch_size: 10,
        batch_timeout: Duration::from_millis(10),
        dedup_window: Duration::from_secs(30),
    };
    let (handle, replayed) = WalHandle::open(config).expect("reopen should succeed");
    assert_eq!(replayed.len(), 100, "all events should be replayed");
    handle.shutdown().expect("shutdown should succeed");
}

// -- AC-13, AC-14: Crash recovery with torn write
#[test]
fn wal_crash_recovery_torn_write() {
    let dir = tempfile::tempdir().expect("tempdir creation should succeed");
    let wal_dir = dir.path().join("wal");
    fs::create_dir_all(&wal_dir).expect("create dir should succeed");

    // Write valid batches directly to simulate a crash mid-write
    let events1: Vec<EventRecord> = (1..=5)
        .map(|i| EventRecord {
            entity_id: i,
            signal_type: 1,
            weight: 1.0,
            timestamp_nanos: i * 1_000_000_000,
        })
        .collect();

    let events2: Vec<EventRecord> = (6..=10)
        .map(|i| EventRecord {
            entity_id: i,
            signal_type: 1,
            weight: 1.0,
            timestamp_nanos: i * 1_000_000_000,
        })
        .collect();

    let batch1 = format::encode_batch(&events1, 1, 1_000_000_000).expect("encode should succeed");
    let batch2 = format::encode_batch(&events2, 6, 6_000_000_000).expect("encode should succeed");

    // Write batch1 fully, then truncate batch2 at various offsets
    for truncate_at in [
        0,
        10,
        32,
        63,
        HEADER_SIZE,
        HEADER_SIZE + 5,
        HEADER_SIZE + 20,
    ] {
        let seg_name = segment::segment_filename(1);
        let seg_path = wal_dir.join(&seg_name);

        let mut data = batch1.clone();
        if truncate_at > 0 {
            data.extend_from_slice(&batch2[..truncate_at.min(batch2.len())]);
        }
        fs::write(&seg_path, &data).expect("write should succeed");

        let recovery = reader::recover(&wal_dir).expect("recovery should succeed");
        assert_eq!(
            recovery.events.len(),
            5,
            "torn write at offset {truncate_at}: should recover 5 events"
        );

        // Clean up for next iteration
        fs::remove_file(&seg_path).expect("cleanup should succeed");
    }
}

// -- AC-15: No phantom records (clean shutdown variant)
#[test]
fn wal_clean_shutdown_no_data_loss() {
    let dir = tempfile::tempdir().expect("tempdir creation should succeed");
    let config = test_config(dir.path());

    // Write 5 events
    let (handle, _) = WalHandle::open(config).expect("open should succeed");
    for i in 1..=5 {
        handle.append(make_event(i)).expect("append should succeed");
    }
    handle.shutdown().expect("shutdown should succeed");

    // Verify exactly 5 events on replay
    let config = test_config(dir.path());
    let (handle, replayed) = WalHandle::open(config).expect("reopen should succeed");
    assert_eq!(
        replayed.len(),
        5,
        "should replay exactly 5 events, not more"
    );

    // No phantom events (events from un-fsynced batches should not appear)
    for event in &replayed {
        assert!(
            event.entity_id >= 1 && event.entity_id <= 5,
            "unexpected entity_id {}",
            event.entity_id
        );
    }
    handle.shutdown().expect("shutdown should succeed");
}

// -- AC-16: Crash at any byte position never produces corrupt state
#[test]
fn wal_crash_at_any_byte_position() {
    let dir = tempfile::tempdir().expect("tempdir creation should succeed");
    let wal_dir = dir.path().join("wal");
    fs::create_dir_all(&wal_dir).expect("create dir should succeed");

    let events: Vec<EventRecord> = (1..=3)
        .map(|i| EventRecord {
            entity_id: i,
            signal_type: 1,
            weight: 1.0,
            timestamp_nanos: i * 1_000_000_000,
        })
        .collect();
    let batch = format::encode_batch(&events, 1, 1_000_000_000).expect("encode should succeed");

    // Test truncation at every byte offset
    for truncate_at in 0..=batch.len() {
        let seg_name = segment::segment_filename(1);
        let seg_path = wal_dir.join(&seg_name);

        fs::write(&seg_path, &batch[..truncate_at]).expect("write should succeed");

        let recovery = reader::recover(&wal_dir).expect("recovery should never fail");

        if truncate_at == batch.len() {
            assert_eq!(
                recovery.events.len(),
                3,
                "full batch should recover 3 events"
            );
        } else {
            assert_eq!(
                recovery.events.len(),
                0,
                "truncated at byte {truncate_at}: no events should be recovered"
            );
        }

        // Clean up for next iteration
        fs::remove_file(&seg_path).expect("cleanup should succeed");
    }
}

// -- AC-17, AC-18: Checkpoint and truncation
#[test]
fn wal_checkpoint_and_truncation() {
    let dir = tempfile::tempdir().expect("tempdir creation should succeed");
    // Small segments so we get multiple
    let config = WalConfig {
        dir: dir.path().to_path_buf(),
        segment_size: 256,
        batch_size: 5,
        batch_timeout: Duration::from_millis(10),
        dedup_window: Duration::from_secs(30),
    };

    let (handle, _) = WalHandle::open(config).expect("open should succeed");

    // Write events
    let mut last_seq = 0;
    for i in 1..=50 {
        let seq = handle.append(make_event(i)).expect("append should succeed");
        if seq > last_seq {
            last_seq = seq;
        }
    }

    // Checkpoint at a mid-point
    let checkpoint_seq = last_seq / 2;
    handle
        .checkpoint(checkpoint_seq)
        .expect("checkpoint should succeed");

    // Verify checkpoint file exists and is correct
    let wal_dir = dir.path().join("wal");
    let cp = CheckpointManager::read(&wal_dir).expect("read should succeed");
    let (seq, _ts) = cp.expect("checkpoint should exist");
    assert_eq!(seq, checkpoint_seq);

    // Truncate segments before checkpoint
    handle
        .truncate_before(checkpoint_seq)
        .expect("truncate should succeed");

    handle.shutdown().expect("shutdown should succeed");

    // Reopen and verify: only events >= checkpoint_seq are replayed
    let config = WalConfig {
        dir: dir.path().to_path_buf(),
        segment_size: 256,
        batch_size: 5,
        batch_timeout: Duration::from_millis(10),
        dedup_window: Duration::from_secs(30),
    };
    let (handle, replayed) = WalHandle::open(config).expect("reopen should succeed");
    assert!(
        !replayed.is_empty(),
        "should replay events after checkpoint"
    );
    // All replayed events should have sequence >= checkpoint_seq
    // (we verify this implicitly by checking count)
    handle.shutdown().expect("shutdown should succeed");
}

// -- AC-19: Concurrent writers
#[test]
fn wal_concurrent_writers() {
    let dir = tempfile::tempdir().expect("tempdir creation should succeed");
    let config = test_config(dir.path());

    let (handle, _) = WalHandle::open(config).expect("open should succeed");
    let handle = Arc::new(handle);

    let num_threads = 8;
    let events_per_thread = 1000;

    let mut threads = Vec::new();
    for thread_id in 0..num_threads {
        let handle = Arc::clone(&handle);
        threads.push(std::thread::spawn(move || {
            let mut seqs = Vec::with_capacity(events_per_thread);
            for i in 0..events_per_thread {
                // Each thread uses unique entity_ids to avoid dedup
                let entity_id = thread_id as u64 * events_per_thread as u64 + i as u64;
                let event = SignalEvent {
                    entity_id,
                    signal_type: thread_id as u8,
                    weight: 1.0,
                    timestamp_nanos: entity_id * 1_000,
                };
                let seq = handle.append(event).expect("append should succeed");
                seqs.push(seq);
            }
            seqs
        }));
    }

    let mut all_seqs = Vec::new();
    for thread in threads {
        let seqs = thread.join().expect("thread should join");
        all_seqs.extend(seqs);
    }

    // Shutdown by unwrapping the Arc (only holder now)
    let handle = Arc::try_unwrap(handle).expect("should be sole owner of WalHandle Arc");
    handle.shutdown().expect("shutdown should succeed");

    // Filter out dedup seq=0 (should be none)
    let non_zero: Vec<u64> = all_seqs.iter().copied().filter(|&s| s > 0).collect();
    assert_eq!(
        non_zero.len(),
        num_threads * events_per_thread,
        "all {} events should get unique sequence numbers",
        num_threads * events_per_thread
    );

    // No duplicate sequence numbers
    let mut sorted = non_zero.clone();
    sorted.sort_unstable();
    sorted.dedup();
    assert_eq!(
        sorted.len(),
        non_zero.len(),
        "no duplicate sequence numbers allowed"
    );

    // Verify all checksums valid on replay
    let config = test_config(dir.path());
    let (handle, replayed) = WalHandle::open(config).expect("reopen should succeed");
    assert_eq!(
        replayed.len(),
        num_threads * events_per_thread,
        "all events should be present on replay"
    );
    handle.shutdown().expect("shutdown should succeed");
}

// -- AC-4: Sequence numbers survive close/reopen
#[test]
fn wal_close_and_reopen() {
    let dir = tempfile::tempdir().expect("tempdir creation should succeed");

    let mut last_seq = 0;

    // Session 1: write 10 events
    let config = test_config(dir.path());
    let (handle, _) = WalHandle::open(config).expect("open should succeed");
    for i in 1..=10 {
        let seq = handle.append(make_event(i)).expect("append should succeed");
        if seq > last_seq {
            last_seq = seq;
        }
    }
    handle.shutdown().expect("shutdown should succeed");

    // Session 2: write 10 more, verify seqs continue
    let config = test_config(dir.path());
    let (handle, replayed) = WalHandle::open(config).expect("reopen should succeed");
    assert_eq!(replayed.len(), 10);

    for i in 11..=20 {
        let seq = handle.append(make_event(i)).expect("append should succeed");
        assert!(seq > last_seq, "seq {seq} should be > last_seq {last_seq}");
        last_seq = seq;
    }
    handle.shutdown().expect("shutdown should succeed");

    // Session 3: verify all 20 events
    let config = test_config(dir.path());
    let (handle, replayed) = WalHandle::open(config).expect("reopen should succeed");
    assert_eq!(replayed.len(), 20);
    handle.shutdown().expect("shutdown should succeed");
}

#[test]
fn wal_replay_correctness() {
    let dir = tempfile::tempdir().expect("tempdir creation should succeed");
    let config = test_config(dir.path());

    // Write 1000 events
    let (handle, _) = WalHandle::open(config).expect("open should succeed");
    let mut seqs = Vec::new();
    for i in 1..=1000 {
        let seq = handle.append(make_event(i)).expect("append should succeed");
        seqs.push(seq);
    }

    // Checkpoint at event 500
    let checkpoint_seq = seqs[499]; // seq of the 500th event
    handle
        .checkpoint(checkpoint_seq)
        .expect("checkpoint should succeed");
    handle.shutdown().expect("shutdown should succeed");

    // Reopen and verify: only post-checkpoint events are replayed
    let config = test_config(dir.path());
    let (handle, replayed) = WalHandle::open(config).expect("reopen should succeed");

    // Events with seq >= checkpoint_seq should be replayed.
    // The exact count depends on batching, but it should be at least 500
    // (the events after the checkpoint) and at most 1000.
    assert!(
        replayed.len() >= 500,
        "expected at least 500 replayed events, got {}",
        replayed.len()
    );
    assert!(
        replayed.len() <= 1000,
        "expected at most 1000 replayed events, got {}",
        replayed.len()
    );

    handle.shutdown().expect("shutdown should succeed");
}

// =============================================================================
// UAT: P1.2 Write-Ahead Log -- Full 10-Step Acceptance Test
// =============================================================================
//
// This test exercises the complete UAT scenario using ONLY the public API:
//   WalHandle::open, WalHandle::append, WalHandle::checkpoint,
//   WalHandle::truncate_before, WalHandle::shutdown, WalConfig, SignalEvent.
//
// No internal modules (format::, reader::, segment::, checkpoint::) are used.
//
// Steps:
//  1. Append 5,000 signal events with varied entity IDs, signal types,
//     timestamps, and weights.
//  2. Read back all events via shutdown + reopen replay. Verify all 5,000
//     present with correct data and monotonic sequence numbers.
//  3. Append 50 duplicate events (same content as events already written).
//     Verify each returns Ok(0).
//  4. Verify the WAL contains exactly 5,000 records (not 5,050).
//  5. Write a checkpoint at the current WAL position.
//  6. Append 500 more events after the checkpoint.
//  7. Close the WAL cleanly (shutdown).
//  8. Reopen the WAL. Verify exactly 500 events are replayed.
//  9. Verify that replayed events combined with pre-checkpoint state
//     produce the full correct history.
// 10. Simulate a crash: open a new WAL, write 200 events (committed),
//     truncate the WAL file, reopen. Verify clean recovery.
//
// Performance gates (release mode only):
//  - 5,000 events append < 30s
//  - WAL open/recovery < 1s

#[test]
#[allow(clippy::too_many_lines)] // UAT scenario is inherently sequential -- 10 steps in one test
fn uat_p1_2_wal_full_scenario() {
    let start_total = std::time::Instant::now();
    let dir = tempfile::tempdir().expect("tempdir creation should succeed");

    // Use small segments to force segment rotation during the test.
    // 32 KB segments: each batch is ~2164 bytes (100 events * 21B + 64B header),
    // so we get ~15 batches per segment, forcing ~3 rotations across 5,000 events.
    // batch_size=100, batch_timeout=10ms match the UAT spec.
    let make_config = |d: &std::path::Path| WalConfig {
        dir: d.to_path_buf(),
        segment_size: 32 * 1024, // 32 KB: forces multiple segment rotations
        batch_size: 100,
        batch_timeout: Duration::from_millis(10),
        dedup_window: Duration::from_secs(60),
    };

    // Helper: generate a unique event with varied fields.
    // Uses a simple deterministic scheme: each event has a unique combination
    // of (entity_id, signal_type, weight, timestamp_nanos) ensuring unique
    // BLAKE3 content hashes.
    let make_varied_event = |index: u64| -> SignalEvent {
        #[allow(clippy::cast_possible_truncation)]
        SignalEvent {
            entity_id: index * 7 + 13,
            signal_type: (index % 256) as u8,
            weight: ((index % 100) as f32).mul_add(0.01, 0.5),
            timestamp_nanos: 1_000_000_000 + index * 1_000_000,
        }
    };

    // =========================================================================
    // Step 1: Append 5,000 signal events
    // =========================================================================
    let config = make_config(dir.path());
    let (handle, replayed) = WalHandle::open(config).expect("initial open should succeed");
    assert!(
        replayed.is_empty(),
        "fresh WAL should have no replayed events"
    );

    let append_start = std::time::Instant::now();
    let mut seqs = Vec::with_capacity(5000);
    for i in 0..5000u64 {
        let event = make_varied_event(i);
        let seq = handle.append(event).expect("append should succeed");
        assert!(
            seq > 0,
            "unique event at index {i} should get real seq, got 0"
        );
        seqs.push(seq);
    }
    let append_duration = append_start.elapsed();
    // Performance gate: 30s for 5,000 appends. Only enforced in release mode
    // because debug builds include no optimizations and each fsync is
    // disproportionately expensive relative to the batch encoding overhead.
    #[cfg(not(debug_assertions))]
    assert!(
        append_duration.as_secs() < 30,
        "5,000 event append took {append_duration:?}, exceeds 30s performance gate",
    );
    eprintln!("step 1: 5,000 events appended in {append_duration:?}");

    // Verify sequence numbers are monotonically increasing
    for window in seqs.windows(2) {
        assert!(
            window[0] < window[1],
            "sequence numbers not monotonic: {} >= {}",
            window[0],
            window[1]
        );
    }

    handle.shutdown().expect("shutdown should succeed");

    // =========================================================================
    // Step 2: Read back all events via WAL scan (reopen = replay)
    // =========================================================================
    let config = make_config(dir.path());
    let recovery_start = std::time::Instant::now();
    let (handle, replayed) = WalHandle::open(config).expect("reopen for step 2 should succeed");
    let recovery_duration = recovery_start.elapsed();
    #[cfg(not(debug_assertions))]
    assert!(
        recovery_duration.as_secs() < 1,
        "WAL recovery took {recovery_duration:?}, exceeds 1s performance gate",
    );
    eprintln!("step 2: recovery in {recovery_duration:?}");

    assert_eq!(
        replayed.len(),
        5000,
        "step 2: expected 5,000 replayed events, got {}",
        replayed.len()
    );

    // Verify event data integrity (BLAKE3 checksums are validated during replay
    // by the reader -- if we get here without error, checksums are valid).
    // Additionally verify the content matches what we wrote.
    for (i, event) in replayed.iter().enumerate() {
        let expected = make_varied_event(i as u64);
        assert_eq!(
            event.entity_id, expected.entity_id,
            "step 2: entity_id mismatch at index {i}"
        );
        assert_eq!(
            event.signal_type, expected.signal_type,
            "step 2: signal_type mismatch at index {i}"
        );
        assert_eq!(
            event.weight.to_bits(),
            expected.weight.to_bits(),
            "step 2: weight mismatch at index {i}"
        );
        assert_eq!(
            event.timestamp_nanos, expected.timestamp_nanos,
            "step 2: timestamp_nanos mismatch at index {i}"
        );
    }

    // =========================================================================
    // Steps 3-4: Append 50 duplicate events, verify dedup, verify total = 5,000
    // =========================================================================
    // Pick 50 events from the original 5,000 to re-submit as duplicates.
    for dup_idx in 0..50u64 {
        // Spread duplicates across the original range
        let original_index = dup_idx * 100; // indices 0, 100, 200, ..., 4900
        let dup_event = make_varied_event(original_index);
        let seq = handle
            .append(dup_event)
            .expect("duplicate append should succeed");
        assert_eq!(
            seq, 0,
            "step 3: duplicate event at original index {original_index} should return seq=0, got {seq}"
        );
    }

    handle
        .shutdown()
        .expect("shutdown after dedup should succeed");

    // Step 4: verify exactly 5,000 records (not 5,050)
    let config = make_config(dir.path());
    let (handle, replayed) = WalHandle::open(config).expect("reopen for step 4 should succeed");
    assert_eq!(
        replayed.len(),
        5000,
        "step 4: expected exactly 5,000 records after dedup, got {}",
        replayed.len()
    );

    // =========================================================================
    // Step 5: Write a checkpoint at the current WAL position
    // =========================================================================
    // The last sequence number from our original 5,000 events
    let checkpoint_seq = seqs[4999]; // last event's seq
    handle
        .checkpoint(checkpoint_seq)
        .expect("step 5: checkpoint should succeed");

    // =========================================================================
    // Step 6: Append 500 more events after the checkpoint
    // =========================================================================
    let mut post_checkpoint_events = Vec::with_capacity(500);
    for i in 5000..5500u64 {
        let event = make_varied_event(i);
        post_checkpoint_events.push(event.clone());
        let seq = handle
            .append(event)
            .expect("post-checkpoint append should succeed");
        assert!(
            seq > 0,
            "step 6: post-checkpoint event at index {i} should get real seq"
        );
    }

    // =========================================================================
    // Step 7: Close the WAL cleanly (shutdown)
    // =========================================================================
    handle
        .shutdown()
        .expect("step 7: clean shutdown should succeed");

    // =========================================================================
    // Step 8: Reopen the WAL. Verify exactly 500 events are replayed.
    // =========================================================================
    let config = make_config(dir.path());
    let recovery_start = std::time::Instant::now();
    let (handle, replayed) = WalHandle::open(config).expect("reopen for step 8 should succeed");
    let recovery_duration = recovery_start.elapsed();
    #[cfg(not(debug_assertions))]
    assert!(
        recovery_duration.as_secs() < 1,
        "WAL recovery (step 8) took {recovery_duration:?}, exceeds 1s performance gate",
    );
    eprintln!("step 8: recovery in {recovery_duration:?}");

    // The checkpoint was set at the last seq of the original 5,000 events.
    // Replay should return events with seq >= checkpoint_seq.
    // This includes the checkpoint event itself plus the 500 new events.
    // Due to batch granularity, the replay may include a few extra events
    // from the batch containing the checkpoint. But the 500 post-checkpoint
    // events must all be present.
    assert!(
        replayed.len() >= 500,
        "step 8: expected at least 500 replayed events, got {}",
        replayed.len()
    );

    // Verify all 500 post-checkpoint events are in the replay.
    // The post-checkpoint events should appear at the end of the replayed list.
    let replay_tail: Vec<&SignalEvent> = replayed.iter().rev().take(500).rev().collect();
    for (i, event) in replay_tail.iter().enumerate() {
        let expected = &post_checkpoint_events[i];
        assert_eq!(
            event.entity_id, expected.entity_id,
            "step 8: post-checkpoint event {i} entity_id mismatch"
        );
        assert_eq!(
            event.signal_type, expected.signal_type,
            "step 8: post-checkpoint event {i} signal_type mismatch"
        );
        assert_eq!(
            event.weight.to_bits(),
            expected.weight.to_bits(),
            "step 8: post-checkpoint event {i} weight mismatch"
        );
    }

    // =========================================================================
    // Step 9: Verify replayed events combined with pre-checkpoint state
    //         produce the full correct history.
    // =========================================================================
    // The pre-checkpoint state represents events 0..5000 (already materialized).
    // The replayed events cover seq >= checkpoint_seq (the 500 new events).
    // Together they should form the complete history of 5,500 events.
    //
    // We verify this by: the 500 post-checkpoint events in the replay match
    // the 500 events we appended in step 6, and the pre-checkpoint count
    // was 5,000 (verified in step 4). 5,000 + 500 = 5,500 total.

    // Append 1 more event in this session to prove the WAL continues
    // to work after recovery (a basic "ready for new appends" check).
    let continuation_seq = handle
        .append(make_varied_event(99999))
        .expect("step 9: continuation append should succeed");
    assert!(
        continuation_seq > 0,
        "step 9: continuation event should get real seq"
    );

    // The full history: 5,000 pre-checkpoint + 500 post-checkpoint + 1 continuation = 5,501.
    // We cannot read all 5,501 without replaying the full WAL (checkpoint truncated old segments),
    // but we can verify the post-checkpoint + continuation count is correct.
    handle.shutdown().expect("step 9: shutdown should succeed");

    let config = make_config(dir.path());
    let (handle, replayed) = WalHandle::open(config).expect("step 9: final reopen should succeed");
    // Should replay everything from checkpoint forward: 500 post-checkpoint + 1 continuation = 501
    assert!(
        replayed.len() >= 501,
        "step 9: expected at least 501 replayed events (500 + 1 continuation), got {}",
        replayed.len()
    );
    handle
        .shutdown()
        .expect("step 9: final shutdown should succeed");

    // =========================================================================
    // Step 10: Simulate a crash -- write 200 events, truncate file, reopen.
    // =========================================================================
    // Use a separate temp directory for the crash simulation to avoid
    // interfering with the state from steps 1-9.
    let crash_dir = tempfile::tempdir().expect("crash tempdir creation should succeed");
    let crash_config = || WalConfig {
        dir: crash_dir.path().to_path_buf(),
        segment_size: 4096,
        batch_size: 50,
        batch_timeout: Duration::from_millis(10),
        dedup_window: Duration::from_secs(60),
    };

    // Write 200 events and confirm they are committed
    let (crash_handle, _) = WalHandle::open(crash_config()).expect("crash WAL open should succeed");
    for i in 0..200u64 {
        let event = make_varied_event(10_000 + i);
        let seq = crash_handle
            .append(event)
            .expect("crash WAL append should succeed");
        assert!(seq > 0, "crash WAL event {i} should get real seq");
    }

    // Shutdown cleanly so all 200 events are durable on disk
    crash_handle
        .shutdown()
        .expect("crash WAL shutdown should succeed");

    // Verify all 200 survive a clean reopen (baseline)
    let (baseline_handle, baseline_replayed) =
        WalHandle::open(crash_config()).expect("baseline reopen should succeed");
    assert_eq!(
        baseline_replayed.len(),
        200,
        "step 10 baseline: expected 200 events, got {}",
        baseline_replayed.len()
    );
    baseline_handle
        .shutdown()
        .expect("baseline shutdown should succeed");

    // Now simulate a crash by truncating the last segment file.
    // Find all .seg files in the WAL directory using only std::fs (no internal modules).
    let wal_dir = crash_dir.path().join("wal");
    let mut seg_files: Vec<std::path::PathBuf> = fs::read_dir(&wal_dir)
        .expect("WAL dir should exist")
        .filter_map(|entry| {
            let entry = entry.ok()?;
            let name = entry.file_name();
            let name_str = name.to_str()?;
            if name_str.starts_with("wal-")
                && std::path::Path::new(name_str)
                    .extension()
                    .is_some_and(|ext| ext.eq_ignore_ascii_case("seg"))
            {
                Some(entry.path())
            } else {
                None
            }
        })
        .collect();
    seg_files.sort();
    assert!(
        !seg_files.is_empty(),
        "step 10: should have at least one segment file"
    );

    // Truncate the LAST segment file to a position within the last batch.
    // This simulates a crash mid-write of the last batch.
    let last_seg = seg_files.last().expect("should have segments");
    let original_len = fs::metadata(last_seg)
        .expect("metadata should succeed")
        .len();

    // Truncate to approximately 70% of the file size. This should land
    // in the middle of some batch, producing a torn write.
    let truncate_to = (original_len * 7) / 10;
    let file = fs::OpenOptions::new()
        .write(true)
        .open(last_seg)
        .expect("open for truncation should succeed");
    file.set_len(truncate_to)
        .expect("truncation should succeed");
    file.sync_all().expect("sync should succeed");
    drop(file);

    // Reopen the WAL after crash simulation
    let recovery_start = std::time::Instant::now();
    let (recovered_handle, recovered_events) =
        WalHandle::open(crash_config()).expect("step 10: recovery should succeed (not corrupt)");
    let recovery_duration = recovery_start.elapsed();
    #[cfg(not(debug_assertions))]
    assert!(
        recovery_duration.as_secs() < 1,
        "step 10: WAL recovery took {recovery_duration:?}, exceeds 1s performance gate",
    );
    eprintln!("step 10: recovery in {recovery_duration:?}");

    // Verify: recovered events < 200 (we truncated some)
    // but > 0 (we had committed batches before the truncation point).
    assert!(
        recovered_events.len() < 200,
        "step 10: after truncation, expected fewer than 200 events, got {}",
        recovered_events.len()
    );
    assert!(
        !recovered_events.is_empty(),
        "step 10: after truncation at 70%, expected at least some recovered events"
    );

    // Verify no corrupt records: every recovered event should match
    // one of the 200 events we originally wrote. The recovery process
    // validates BLAKE3 checksums, so if we reach this point, no corrupt
    // data leaked through.
    for (i, event) in recovered_events.iter().enumerate() {
        let expected = make_varied_event(10_000 + i as u64);
        assert_eq!(
            event.entity_id, expected.entity_id,
            "step 10: recovered event {i} entity_id mismatch (corrupt data?)"
        );
        assert_eq!(
            event.signal_type, expected.signal_type,
            "step 10: recovered event {i} signal_type mismatch"
        );
        assert_eq!(
            event.weight.to_bits(),
            expected.weight.to_bits(),
            "step 10: recovered event {i} weight mismatch"
        );
        assert_eq!(
            event.timestamp_nanos, expected.timestamp_nanos,
            "step 10: recovered event {i} timestamp mismatch"
        );
    }

    // Verify WAL is ready for new appends after recovery
    let new_seq = recovered_handle
        .append(make_varied_event(99998))
        .expect("step 10: append after recovery should succeed");
    assert!(
        new_seq > 0,
        "step 10: new event after recovery should get real seq"
    );

    recovered_handle
        .shutdown()
        .expect("step 10: final shutdown should succeed");

    // Final reopen to verify the newly appended event is durable
    let (final_handle, final_replayed) =
        WalHandle::open(crash_config()).expect("step 10: final reopen should succeed");
    // Should have the recovered events + 1 new event
    assert_eq!(
        final_replayed.len(),
        recovered_events.len() + 1,
        "step 10: final replay should have recovered + 1 new event"
    );
    final_handle
        .shutdown()
        .expect("step 10: absolute final shutdown should succeed");

    let total_duration = start_total.elapsed();
    eprintln!(
        "UAT P1.2 complete: total={total_duration:?}, append_5k={append_duration:?}, recovery={recovery_duration:?}"
    );
}

// Property test for replay from random checkpoints
mod proptests {
    use super::*;
    use proptest::prelude::*;

    fn arb_signal_event() -> impl Strategy<Value = SignalEvent> {
        (1..=10_000u64, 0..=255u8, -100.0f32..100.0, 1..=u64::MAX).prop_map(
            |(entity_id, signal_type, weight, timestamp_nanos)| SignalEvent {
                entity_id,
                signal_type,
                weight,
                timestamp_nanos,
            },
        )
    }

    proptest! {
        // 10 cases × up to 10 000 events each satisfies the "10k+ events per
        // property run" acceptance criterion while keeping total runtime in the
        // same order as the previous 100-case × 500-event configuration.
        #![proptest_config(proptest::test_runner::Config::with_cases(10))]
        #[test]
        fn prop_wal_replay_from_checkpoint(
            events in proptest::collection::vec(arb_signal_event(), 1..=10_000),
            checkpoint_frac in 0.0f64..1.0,
        ) {
            let dir = tempfile::tempdir().expect("tempdir creation should succeed");
            let config = WalConfig {
                dir: dir.path().to_path_buf(),
                segment_size: 16 * 1024 * 1024,
                batch_size: 50,
                batch_timeout: Duration::from_millis(10),
                dedup_window: Duration::from_secs(60),
            };

            // Make events unique by appending index to entity_id
            let unique_events: Vec<SignalEvent> = events.iter().enumerate().map(|(i, e)| {
                SignalEvent {
                    entity_id: i as u64 * 1_000_000 + e.entity_id,
                    signal_type: e.signal_type,
                    weight: e.weight,
                    timestamp_nanos: i as u64 * 1_000_000 + e.timestamp_nanos % 1_000_000,
                }
            }).collect();

            let (handle, _) = WalHandle::open(config).expect("open should succeed");

            let mut seqs = Vec::new();
            for event in &unique_events {
                let seq = handle.append(event.clone()).expect("append should succeed");
                seqs.push(seq);
            }

            // Checkpoint at a fractional position
            let checkpoint_idx = ((unique_events.len() as f64 * checkpoint_frac) as usize)
                .min(unique_events.len().saturating_sub(1));
            let checkpoint_seq = seqs[checkpoint_idx];

            handle.checkpoint(checkpoint_seq).expect("checkpoint should succeed");
            handle.shutdown().expect("shutdown should succeed");

            // Reopen and verify replay contains at least post-checkpoint events
            let config = WalConfig {
                dir: dir.path().to_path_buf(),
                segment_size: 16 * 1024 * 1024,
                batch_size: 50,
                batch_timeout: Duration::from_millis(10),
                dedup_window: Duration::from_secs(60),
            };
            let (handle, replayed) = WalHandle::open(config).expect("reopen should succeed");

            // Count how many events had seq >= checkpoint_seq
            let expected_min = seqs.iter().filter(|&&s| s >= checkpoint_seq).count();
            prop_assert!(
                replayed.len() >= expected_min,
                "expected at least {} replayed events, got {}",
                expected_min,
                replayed.len()
            );

            handle.shutdown().expect("shutdown should succeed");
        }
    }
}