Skip to main content

ftui_web/
session_record.rs

1#![forbid(unsafe_code)]
2
3//! Deterministic session recording and replay for WASM (bd-lff4p.3.7).
4//!
5//! Provides [`SessionRecorder`] for recording input events, time steps, and
6//! resize events during a WASM session, and [`replay`] for replaying them
7//! through a fresh model to verify that frame checksums match exactly.
8//!
9//! # Design
10//!
11//! Follows the golden-trace-v2 schema defined in
12//! `docs/spec/frankenterm-golden-trace-format.md`:
13//!
14//! - **Header**: seed, initial dimensions, capability profile.
15//! - **Input**: timestamped terminal events (key, mouse, paste, etc.).
16//! - **Resize**: terminal resize events.
17//! - **Tick**: explicit time advancement events.
18//! - **Step**: actual initialization/step boundaries, clock and execution outcomes.
19//! - **Frame**: frame checkpoints with FNV-1a checksums and chaining.
20//! - **Summary**: total frames and final checksum chain.
21//!
22//! # Determinism contract
23//!
24//! Given identical recorded inputs and the same model implementation, replay
25//! **must** produce identical frame checksums on the same build. This is
26//! guaranteed by:
27//!
28//! 1. Host-driven clock (no `Instant::now()` — time only advances via explicit
29//!    tick records).
30//! 2. Host-driven events (no polling — events are replayed from the trace).
31//! 3. Deterministic rendering (same model state → same buffer → same checksum).
32//!
33//! # Example
34//!
35//! ```ignore
36//! let mut recorder = SessionRecorder::new(MyModel::default(), 80, 24, /*seed=*/0);
37//! recorder.init().unwrap();
38//!
39//! recorder.push_event(0, key_event('+')).expect("key admission");
40//! recorder.advance_time(16_000_000, Duration::from_millis(16));
41//! recorder.step().unwrap();
42//!
43//! let trace = recorder.finish();
44//! let result = replay(MyModel::default(), &trace).unwrap();
45//! assert!(result.ok());
46//! ```
47
48use core::time::Duration;
49
50use ftui_core::event::{
51    ClipboardEvent, ClipboardSource, Event, ImeEvent, ImePhase, KeyCode, KeyEvent, KeyEventKind,
52    Modifiers, MouseButton, MouseEvent, MouseEventKind, PasteEvent,
53};
54use ftui_runtime::render_trace::checksum_buffer;
55
56use crate::WebBackendError;
57use crate::step_program::{StepProgram, StepResult};
58#[cfg(feature = "tracing")]
59use tracing::{error, info_span};
60
61/// Schema version for session traces.
62pub const SCHEMA_VERSION: &str = "golden-trace-v2";
63
64// FNV-1a constants — identical to ftui-runtime/src/render_trace.rs.
65const FNV_OFFSET_BASIS: u64 = 0xcbf29ce484222325;
66const FNV_PRIME: u64 = 0x100000001b3;
67
68fn fnv1a64_bytes(mut hash: u64, bytes: &[u8]) -> u64 {
69    for &b in bytes {
70        hash ^= b as u64;
71        hash = hash.wrapping_mul(FNV_PRIME);
72    }
73    hash
74}
75
76fn fnv1a64_u64(hash: u64, v: u64) -> u64 {
77    fnv1a64_bytes(hash, &v.to_le_bytes())
78}
79
80fn fnv1a64_pair(prev: u64, next: u64) -> u64 {
81    let hash = FNV_OFFSET_BASIS;
82    let hash = fnv1a64_u64(hash, prev);
83    fnv1a64_u64(hash, next)
84}
85
86/// A single record in a session trace.
87#[derive(Debug, Clone, PartialEq)]
88pub enum TraceRecord {
89    /// Session header (must be first).
90    Header {
91        seed: u64,
92        cols: u16,
93        rows: u16,
94        profile: String,
95    },
96    /// An input event at a specific timestamp.
97    Input { ts_ns: u64, event: Event },
98    /// Terminal resize at a specific timestamp.
99    Resize { ts_ns: u64, cols: u16, rows: u16 },
100    /// Explicit time advancement.
101    Tick { ts_ns: u64 },
102    /// An observed execution boundary, including non-rendering and quit steps.
103    Step {
104        step_idx: u64,
105        ts_ns: u64,
106        init: bool,
107        clock: Duration,
108        result: StepResult,
109    },
110    /// Frame checkpoint with checksum.
111    Frame {
112        frame_idx: u64,
113        ts_ns: u64,
114        checksum: u64,
115        checksum_chain: u64,
116    },
117    /// Trace summary (must be last).
118    Summary {
119        total_frames: u64,
120        final_checksum_chain: u64,
121    },
122}
123
124/// A complete recorded session trace.
125#[derive(Debug, Clone)]
126pub struct SessionTrace {
127    pub records: Vec<TraceRecord>,
128}
129
130impl SessionTrace {
131    /// Number of frame checkpoints in the trace.
132    pub fn frame_count(&self) -> u64 {
133        self.records
134            .iter()
135            .filter(|r| matches!(r, TraceRecord::Frame { .. }))
136            .count() as u64
137    }
138
139    /// Extract the final checksum chain from the summary record.
140    pub fn final_checksum_chain(&self) -> Option<u64> {
141        self.records.iter().rev().find_map(|r| match r {
142            TraceRecord::Summary {
143                final_checksum_chain,
144                ..
145            } => Some(*final_checksum_chain),
146            _ => None,
147        })
148    }
149
150    /// Validate structural invariants for a recorded trace.
151    ///
152    /// This checks:
153    /// - header exists and is the first record
154    /// - summary exists and is the last record
155    /// - frame indices are contiguous and start at zero
156    /// - summary totals/chains match frame records
157    /// - every execution boundary records its outcome and accepted input count
158    /// - frame checkpoints follow exactly those steps that rendered
159    pub fn validate(&self) -> Result<(), TraceValidationError> {
160        if self.records.is_empty() {
161            return Err(TraceValidationError::EmptyTrace);
162        }
163
164        let mut header_count: usize = 0;
165        let mut summary: Option<(usize, u64, u64)> = None;
166        let mut expected_frame_idx: u64 = 0;
167        let mut frame_count: u64 = 0;
168        let mut last_checksum_chain: u64 = 0;
169        let mut last_ts_ns: Option<u64> = None;
170
171        let mut validate_ts =
172            |ts_ns: u64, record_index: usize| -> Result<(), TraceValidationError> {
173                if let Some(previous) = last_ts_ns
174                    && ts_ns < previous
175                {
176                    return Err(TraceValidationError::TimestampRegression {
177                        previous,
178                        current: ts_ns,
179                        record_index,
180                    });
181                }
182                last_ts_ns = Some(ts_ns);
183                Ok(())
184            };
185
186        for (idx, record) in self.records.iter().enumerate() {
187            match record {
188                TraceRecord::Header { .. } => {
189                    if summary.is_some() {
190                        let summary_idx = summary.map(|(i, _, _)| i).unwrap_or_default();
191                        return Err(TraceValidationError::SummaryNotLast {
192                            summary_index: summary_idx,
193                        });
194                    }
195                    header_count += 1;
196                }
197                TraceRecord::Summary {
198                    total_frames,
199                    final_checksum_chain,
200                } => {
201                    if summary.is_some() {
202                        return Err(TraceValidationError::MultipleSummaries);
203                    }
204                    summary = Some((idx, *total_frames, *final_checksum_chain));
205                }
206                TraceRecord::Frame {
207                    frame_idx,
208                    ts_ns,
209                    checksum_chain,
210                    ..
211                } => {
212                    validate_ts(*ts_ns, idx)?;
213                    if summary.is_some() {
214                        let summary_idx = summary.map(|(i, _, _)| i).unwrap_or_default();
215                        return Err(TraceValidationError::SummaryNotLast {
216                            summary_index: summary_idx,
217                        });
218                    }
219                    if *frame_idx != expected_frame_idx {
220                        return Err(TraceValidationError::FrameIndexMismatch {
221                            expected: expected_frame_idx,
222                            actual: *frame_idx,
223                        });
224                    }
225                    expected_frame_idx = expected_frame_idx.saturating_add(1);
226                    frame_count = frame_count.saturating_add(1);
227                    last_checksum_chain = *checksum_chain;
228                }
229                TraceRecord::Input { ts_ns, .. } => {
230                    validate_ts(*ts_ns, idx)?;
231                    if summary.is_some() {
232                        let summary_idx = summary.map(|(i, _, _)| i).unwrap_or_default();
233                        return Err(TraceValidationError::SummaryNotLast {
234                            summary_index: summary_idx,
235                        });
236                    }
237                }
238                TraceRecord::Resize { ts_ns, .. } => {
239                    validate_ts(*ts_ns, idx)?;
240                    if summary.is_some() {
241                        let summary_idx = summary.map(|(i, _, _)| i).unwrap_or_default();
242                        return Err(TraceValidationError::SummaryNotLast {
243                            summary_index: summary_idx,
244                        });
245                    }
246                }
247                TraceRecord::Tick { ts_ns } => {
248                    validate_ts(*ts_ns, idx)?;
249                    if summary.is_some() {
250                        let summary_idx = summary.map(|(i, _, _)| i).unwrap_or_default();
251                        return Err(TraceValidationError::SummaryNotLast {
252                            summary_index: summary_idx,
253                        });
254                    }
255                }
256                TraceRecord::Step { ts_ns, .. } => {
257                    validate_ts(*ts_ns, idx)?;
258                    if let Some((summary_index, _, _)) = summary {
259                        return Err(TraceValidationError::SummaryNotLast { summary_index });
260                    }
261                }
262            }
263        }
264
265        if header_count == 0 {
266            return Err(TraceValidationError::MissingHeader);
267        }
268        if header_count > 1 {
269            return Err(TraceValidationError::MultipleHeaders);
270        }
271        if !matches!(self.records.first(), Some(TraceRecord::Header { .. })) {
272            return Err(TraceValidationError::HeaderNotFirst);
273        }
274
275        let Some((summary_idx, summary_frames, summary_chain)) = summary else {
276            return Err(TraceValidationError::MissingSummary);
277        };
278        if summary_idx != self.records.len().saturating_sub(1) {
279            return Err(TraceValidationError::SummaryNotLast {
280                summary_index: summary_idx,
281            });
282        }
283        if summary_frames != frame_count {
284            return Err(TraceValidationError::SummaryFrameCountMismatch {
285                expected: frame_count,
286                actual: summary_frames,
287            });
288        }
289        if summary_chain != last_checksum_chain {
290            return Err(TraceValidationError::SummaryChecksumChainMismatch {
291                expected: last_checksum_chain,
292                actual: summary_chain,
293            });
294        }
295
296        self.validate_steps()
297    }
298
299    fn validate_steps(&self) -> Result<(), TraceValidationError> {
300        let mut next_step = 0;
301        let mut frames = 0;
302        let mut queued = 0_u64;
303        let mut last_result: Option<StepResult> = None;
304        let mut frame_pending = false;
305        let mut inputs_pending = false;
306        let mut checksum_chain = 0;
307        for (record_index, record) in self.records.iter().enumerate() {
308            let invalid = |reason| TraceValidationError::InvalidExecution {
309                record_index,
310                reason,
311            };
312            if frame_pending && !matches!(record, TraceRecord::Frame { .. }) {
313                return Err(invalid("rendered step is missing its frame checkpoint"));
314            }
315            match record {
316                TraceRecord::Step {
317                    step_idx,
318                    init,
319                    result,
320                    ..
321                } => {
322                    if *step_idx != next_step || *init != (next_step == 0) {
323                        return Err(invalid(
324                            "steps must start with init at zero and be contiguous",
325                        ));
326                    }
327                    if *init && result.events_processed != 0 {
328                        return Err(invalid("initialization cannot process queued input"));
329                    }
330                    if result.events_processed as u64 > queued {
331                        return Err(invalid("step processed more events than were admitted"));
332                    }
333                    queued -= u64::from(result.events_processed);
334                    if queued != u64::from(result.events_pending) {
335                        return Err(invalid(
336                            "step pending count does not account for accepted input",
337                        ));
338                    }
339                    if let Some(previous) = last_result
340                        && !previous.running
341                        && (result.running || result.rendered || result.events_processed != 0)
342                    {
343                        return Err(invalid("a stopped program cannot resume or process input"));
344                    }
345                    if result.rendered && !result.running {
346                        return Err(invalid("a stopped step cannot render"));
347                    }
348                    if result.frame_idx != frames + u64::from(result.rendered) {
349                        return Err(invalid(
350                            "step frame count does not match rendered checkpoints",
351                        ));
352                    }
353                    frame_pending = result.rendered;
354                    inputs_pending = false;
355                    last_result = Some(*result);
356                    next_step += 1;
357                }
358                TraceRecord::Frame {
359                    checksum,
360                    checksum_chain: supplied_chain,
361                    ..
362                } => {
363                    if !frame_pending {
364                        return Err(invalid(
365                            "frame checkpoint has no rendered execution boundary",
366                        ));
367                    }
368                    checksum_chain = fnv1a64_pair(checksum_chain, *checksum);
369                    if *supplied_chain != checksum_chain {
370                        return Err(invalid("frame checksum chain does not match its hashes"));
371                    }
372                    frame_pending = false;
373                    frames += 1;
374                }
375                TraceRecord::Input { .. } | TraceRecord::Resize { .. } => {
376                    if last_result.is_some_and(|result| !result.running) {
377                        return Err(invalid(
378                            "input cannot be admitted after the program stopped",
379                        ));
380                    }
381                    queued += 1;
382                    inputs_pending = true;
383                }
384                TraceRecord::Tick { .. } => inputs_pending = true,
385                TraceRecord::Summary { .. } => {
386                    if last_result.is_none() || inputs_pending {
387                        return Err(invalid("trace ends without an observed execution boundary"));
388                    }
389                }
390                TraceRecord::Header { .. } => {}
391            }
392        }
393        Ok(())
394    }
395}
396
397/// Records a WASM session for deterministic replay.
398///
399/// Wraps a [`StepProgram`] and intercepts all input operations, recording
400/// them as [`TraceRecord`]s. Frame checksums are computed after each render
401/// using the same FNV-1a algorithm as the render trace system.
402pub struct SessionRecorder<M: ftui_runtime::program::Model> {
403    program: StepProgram<M>,
404    records: Vec<TraceRecord>,
405    checksum_chain: u64,
406    current_ts_ns: u64,
407    next_step_idx: u64,
408}
409
410impl<M: ftui_runtime::program::Model> SessionRecorder<M> {
411    /// Create a new recorder with the given model, initial size, and seed.
412    #[must_use]
413    pub fn new(model: M, width: u16, height: u16, seed: u64) -> Self {
414        let program = StepProgram::new(model, width, height);
415        let records = vec![TraceRecord::Header {
416            seed,
417            cols: width,
418            rows: height,
419            profile: "modern".to_string(),
420        }];
421        Self {
422            program,
423            records,
424            checksum_chain: 0,
425            current_ts_ns: 0,
426            next_step_idx: 0,
427        }
428    }
429
430    /// Record initialization and its frame checkpoint, if it renders.
431    pub fn init(&mut self) -> Result<(), WebBackendError> {
432        self.program.init()?;
433        let result = StepResult {
434            running: self.program.is_running(),
435            rendered: self.program.frame_idx() > 0,
436            events_processed: 0,
437            events_pending: self.program.pending_events(),
438            frame_idx: self.program.frame_idx(),
439        };
440        self.record_step(true, result);
441        Ok(())
442    }
443
444    /// Record an input event at the given timestamp (nanoseconds since start).
445    pub fn push_event(&mut self, ts_ns: u64, event: Event) -> Result<(), WebBackendError> {
446        self.program.push_event(event.clone())?;
447        self.current_ts_ns = ts_ns;
448        self.records.push(TraceRecord::Input { ts_ns, event });
449        Ok(())
450    }
451
452    /// Record a resize at the given timestamp.
453    pub fn resize(&mut self, ts_ns: u64, width: u16, height: u16) -> Result<(), WebBackendError> {
454        self.program.resize(width, height)?;
455        self.current_ts_ns = ts_ns;
456        self.records.push(TraceRecord::Resize {
457            ts_ns,
458            cols: width,
459            rows: height,
460        });
461        Ok(())
462    }
463
464    /// Record a time advancement (tick) at the given timestamp.
465    pub fn advance_time(&mut self, ts_ns: u64, dt: Duration) {
466        self.current_ts_ns = ts_ns;
467        self.records.push(TraceRecord::Tick { ts_ns });
468        self.program.advance_time(dt);
469    }
470
471    /// Record an actual step, including non-rendering outcomes and pending input.
472    pub fn step(&mut self) -> Result<StepResult, WebBackendError> {
473        let result = self.program.step()?;
474        self.record_step(false, result);
475        Ok(result)
476    }
477
478    /// Finish recording and return the completed trace.
479    ///
480    /// Does not step or flush pending input. Validation rejects a recording
481    /// whose final admissions or time advance lack an observed step boundary.
482    pub fn finish(mut self) -> SessionTrace {
483        let total_frames = self
484            .records
485            .iter()
486            .filter(|r| matches!(r, TraceRecord::Frame { .. }))
487            .count() as u64;
488        self.records.push(TraceRecord::Summary {
489            total_frames,
490            final_checksum_chain: self.checksum_chain,
491        });
492        SessionTrace {
493            records: self.records,
494        }
495    }
496
497    /// Access the underlying program.
498    pub fn program(&self) -> &StepProgram<M> {
499        &self.program
500    }
501
502    /// Mutably access the underlying program.
503    ///
504    /// Direct input, stepping, or queue recovery bypasses recording. Use the
505    /// recorder methods for operations that must be captured in the trace.
506    pub fn program_mut(&mut self) -> &mut StepProgram<M> {
507        &mut self.program
508    }
509
510    fn record_step(&mut self, init: bool, result: StepResult) {
511        self.records.push(TraceRecord::Step {
512            step_idx: self.next_step_idx,
513            ts_ns: self.current_ts_ns,
514            init,
515            clock: self.program.time(),
516            result,
517        });
518        self.next_step_idx += 1;
519        if result.rendered {
520            self.record_frame();
521        }
522    }
523
524    fn record_frame(&mut self) {
525        let outputs = self.program.outputs();
526        if let Some(buf) = &outputs.last_buffer {
527            let checksum = checksum_buffer(buf, self.program.pool());
528            let chain = fnv1a64_pair(self.checksum_chain, checksum);
529            self.records.push(TraceRecord::Frame {
530                frame_idx: self.program.frame_idx().saturating_sub(1),
531                ts_ns: self.current_ts_ns,
532                checksum,
533                checksum_chain: chain,
534            });
535            self.checksum_chain = chain;
536        }
537    }
538}
539
540/// Result of replaying a session trace.
541#[derive(Debug, Clone, PartialEq, Eq)]
542pub struct ReplayResult {
543    /// Execution boundaries replayed, including initialization.
544    pub total_steps: u64,
545    /// Whether the model was still running at the end of the recording.
546    pub running: bool,
547    /// Exact accepted FIFO tail that quit prevented from being processed.
548    pub unprocessed_events: Vec<Event>,
549    /// Total frames replayed.
550    pub total_frames: u64,
551    /// Final checksum chain from replay.
552    pub final_checksum_chain: u64,
553    /// First frame where a checksum mismatch was detected, if any.
554    pub first_mismatch: Option<ReplayMismatch>,
555}
556
557impl ReplayResult {
558    /// Whether recorded execution outcomes and checksums matched.
559    /// Inspect `unprocessed_events` separately: matching quit may leave a tail.
560    #[must_use]
561    pub fn ok(&self) -> bool {
562        self.first_mismatch.is_none()
563    }
564}
565
566/// Description of a checksum mismatch during replay.
567#[derive(Debug, Clone, PartialEq, Eq)]
568pub struct ReplayMismatch {
569    /// Frame index where the mismatch occurred.
570    pub frame_idx: u64,
571    /// Expected checksum from the trace.
572    pub expected: u64,
573    /// Actual checksum from replay.
574    pub actual: u64,
575}
576
577/// Errors that can occur during replay.
578#[derive(Debug, Clone, PartialEq, Eq)]
579pub enum ReplayError {
580    /// The trace is missing a header record.
581    MissingHeader,
582    /// The trace violates structural invariants.
583    InvalidTrace(TraceValidationError),
584    /// A backend error occurred during replay.
585    Backend(WebBackendError),
586    /// Replay reached a different execution outcome at a recorded boundary.
587    StepMismatch {
588        step_idx: u64,
589        expected: StepResult,
590        actual: StepResult,
591    },
592    /// A frame checkpoint did not have a rendered buffer to compare.
593    MissingFrame { frame_idx: u64 },
594}
595
596impl core::fmt::Display for ReplayError {
597    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
598        match self {
599            Self::MissingHeader => write!(f, "trace missing header record"),
600            Self::InvalidTrace(e) => write!(f, "invalid trace: {e}"),
601            Self::Backend(e) => write!(f, "backend error: {e}"),
602            Self::StepMismatch {
603                step_idx,
604                expected,
605                actual,
606            } => write!(
607                f,
608                "execution mismatch at step {step_idx}: expected {expected:?}, got {actual:?}"
609            ),
610            Self::MissingFrame { frame_idx } => write!(f, "missing rendered frame {frame_idx}"),
611        }
612    }
613}
614
615impl std::error::Error for ReplayError {}
616
617impl From<WebBackendError> for ReplayError {
618    fn from(e: WebBackendError) -> Self {
619        Self::Backend(e)
620    }
621}
622
623/// Replay a recorded session trace through a fresh model.
624///
625/// Feeds all recorded events, resizes, and ticks through a new
626/// [`StepProgram`], executing only recorded initialization and step boundaries.
627/// Checks exact outcomes even when a boundary did not render. Frame records
628/// compare existing rendered buffers; they never trigger an extra step.
629///
630/// Returns [`ReplayResult`] with match/mismatch information.
631pub fn replay<M: ftui_runtime::program::Model>(
632    model: M,
633    trace: &SessionTrace,
634) -> Result<ReplayResult, ReplayError> {
635    // Extract header.
636    let (cols, rows) = trace
637        .records
638        .first()
639        .and_then(|r| match r {
640            TraceRecord::Header { cols, rows, .. } => Some((*cols, *rows)),
641            _ => None,
642        })
643        .ok_or(ReplayError::MissingHeader)?;
644    trace.validate().map_err(ReplayError::InvalidTrace)?;
645
646    let mut program = StepProgram::new(model, cols, rows);
647
648    let mut replay_frame_idx: u64 = 0;
649    let mut total_steps = 0;
650    let mut checksum_chain: u64 = 0;
651    let mut first_mismatch: Option<ReplayMismatch> = None;
652
653    // Admission, actual execution boundaries and rendered checkpoints are
654    // distinct. Never infer a missing step from a frame or from queued input.
655    for record in &trace.records {
656        match record {
657            TraceRecord::Input { event, .. } => {
658                program.push_event(event.clone())?;
659            }
660            TraceRecord::Resize { cols, rows, .. } => {
661                program.resize(*cols, *rows)?;
662            }
663            TraceRecord::Step {
664                step_idx,
665                init,
666                clock,
667                result: expected,
668                ..
669            } => {
670                program.set_time(*clock);
671                let actual = if *init {
672                    program.init()?;
673                    StepResult {
674                        running: program.is_running(),
675                        rendered: program.frame_idx() > 0,
676                        events_processed: 0,
677                        events_pending: program.pending_events(),
678                        frame_idx: program.frame_idx(),
679                    }
680                } else {
681                    program.step()?
682                };
683                if actual != *expected {
684                    return Err(ReplayError::StepMismatch {
685                        step_idx: *step_idx,
686                        expected: *expected,
687                        actual,
688                    });
689                }
690                total_steps += 1;
691            }
692            TraceRecord::Frame {
693                frame_idx: expected_idx,
694                checksum: expected_checksum,
695                ..
696            } => {
697                // Verify checksum.
698                let outputs = program.outputs();
699                if let Some(buf) = &outputs.last_buffer {
700                    let actual = checksum_buffer(buf, program.pool());
701                    checksum_chain = fnv1a64_pair(checksum_chain, actual);
702                    if actual != *expected_checksum && first_mismatch.is_none() {
703                        first_mismatch = Some(ReplayMismatch {
704                            frame_idx: *expected_idx,
705                            expected: *expected_checksum,
706                            actual,
707                        });
708                    }
709                } else {
710                    return Err(ReplayError::MissingFrame {
711                        frame_idx: *expected_idx,
712                    });
713                }
714                replay_frame_idx += 1;
715            }
716            TraceRecord::Header { .. } | TraceRecord::Summary { .. } | TraceRecord::Tick { .. } => {
717            }
718        }
719    }
720
721    Ok(ReplayResult {
722        total_steps,
723        running: program.is_running(),
724        unprocessed_events: program.take_pending_events(),
725        total_frames: replay_frame_idx,
726        final_checksum_chain: checksum_chain,
727        first_mismatch,
728    })
729}
730
731// ---- JSONL serialization / deserialization ----
732
733fn json_escape(input: &str) -> String {
734    let mut out = String::with_capacity(input.len() + 8);
735    for ch in input.chars() {
736        match ch {
737            '"' => out.push_str("\\\""),
738            '\\' => out.push_str("\\\\"),
739            '\n' => out.push_str("\\n"),
740            '\r' => out.push_str("\\r"),
741            '\t' => out.push_str("\\t"),
742            c if c.is_control() => {
743                use core::fmt::Write as _;
744                let _ = write!(out, "\\u{:04x}", c as u32);
745            }
746            c => out.push(c),
747        }
748    }
749    out
750}
751
752fn event_to_json(event: &Event) -> String {
753    match event {
754        Event::Key(k) => {
755            let code = key_code_to_str(k.code);
756            let mods = k.modifiers.bits();
757            let kind = key_event_kind_to_str(k.kind);
758            format!(
759                r#"{{"kind":"key","code":"{}","modifiers":{},"event_kind":"{}"}}"#,
760                json_escape(&code),
761                mods,
762                kind
763            )
764        }
765        Event::Mouse(m) => {
766            let kind = mouse_event_kind_to_str(m.kind);
767            let mods = m.modifiers.bits();
768            format!(
769                r#"{{"kind":"mouse","mouse_kind":"{}","x":{},"y":{},"modifiers":{}}}"#,
770                kind, m.x, m.y, mods
771            )
772        }
773        Event::Resize { width, height } => {
774            format!(
775                r#"{{"kind":"resize","width":{},"height":{}}}"#,
776                width, height
777            )
778        }
779        Event::Paste(p) => {
780            format!(
781                r#"{{"kind":"paste","text":"{}","bracketed":{}}}"#,
782                json_escape(&p.text),
783                p.bracketed
784            )
785        }
786        Event::Ime(ime) => {
787            format!(
788                r#"{{"kind":"ime","phase":"{}","text":"{}"}}"#,
789                ime_phase_to_str(ime.phase),
790                json_escape(&ime.text)
791            )
792        }
793        Event::Focus(gained) => {
794            format!(r#"{{"kind":"focus","gained":{}}}"#, gained)
795        }
796        Event::Clipboard(c) => {
797            let source = clipboard_source_to_str(c.source);
798            format!(
799                r#"{{"kind":"clipboard","content":"{}","source":"{}"}}"#,
800                json_escape(&c.content),
801                source
802            )
803        }
804        Event::Tick => r#"{"kind":"tick"}"#.to_string(),
805    }
806}
807
808fn key_code_to_str(code: KeyCode) -> String {
809    match code {
810        KeyCode::Char(c) => format!("char:{c}"),
811        KeyCode::Enter => "enter".to_string(),
812        KeyCode::Escape => "escape".to_string(),
813        KeyCode::Backspace => "backspace".to_string(),
814        KeyCode::Tab => "tab".to_string(),
815        KeyCode::BackTab => "backtab".to_string(),
816        KeyCode::Delete => "delete".to_string(),
817        KeyCode::Insert => "insert".to_string(),
818        KeyCode::Home => "home".to_string(),
819        KeyCode::End => "end".to_string(),
820        KeyCode::PageUp => "pageup".to_string(),
821        KeyCode::PageDown => "pagedown".to_string(),
822        KeyCode::Up => "up".to_string(),
823        KeyCode::Down => "down".to_string(),
824        KeyCode::Left => "left".to_string(),
825        KeyCode::Right => "right".to_string(),
826        KeyCode::F(n) => format!("f:{n}"),
827        KeyCode::Null => "null".to_string(),
828        KeyCode::MediaPlayPause => "media_play_pause".to_string(),
829        KeyCode::MediaStop => "media_stop".to_string(),
830        KeyCode::MediaNextTrack => "media_next".to_string(),
831        KeyCode::MediaPrevTrack => "media_prev".to_string(),
832    }
833}
834
835fn key_event_kind_to_str(kind: KeyEventKind) -> &'static str {
836    match kind {
837        KeyEventKind::Press => "press",
838        KeyEventKind::Repeat => "repeat",
839        KeyEventKind::Release => "release",
840    }
841}
842
843fn mouse_event_kind_to_str(kind: MouseEventKind) -> &'static str {
844    match kind {
845        MouseEventKind::Down(MouseButton::Left) => "down_left",
846        MouseEventKind::Down(MouseButton::Right) => "down_right",
847        MouseEventKind::Down(MouseButton::Middle) => "down_middle",
848        MouseEventKind::Up(MouseButton::Left) => "up_left",
849        MouseEventKind::Up(MouseButton::Right) => "up_right",
850        MouseEventKind::Up(MouseButton::Middle) => "up_middle",
851        MouseEventKind::Drag(MouseButton::Left) => "drag_left",
852        MouseEventKind::Drag(MouseButton::Right) => "drag_right",
853        MouseEventKind::Drag(MouseButton::Middle) => "drag_middle",
854        MouseEventKind::Moved => "moved",
855        MouseEventKind::ScrollUp => "scroll_up",
856        MouseEventKind::ScrollDown => "scroll_down",
857        MouseEventKind::ScrollLeft => "scroll_left",
858        MouseEventKind::ScrollRight => "scroll_right",
859    }
860}
861
862fn clipboard_source_to_str(source: ClipboardSource) -> &'static str {
863    match source {
864        ClipboardSource::Osc52 => "osc52",
865        ClipboardSource::Unknown => "unknown",
866    }
867}
868
869fn ime_phase_to_str(phase: ImePhase) -> &'static str {
870    match phase {
871        ImePhase::Start => "start",
872        ImePhase::Update => "update",
873        ImePhase::Commit => "commit",
874        ImePhase::Cancel => "cancel",
875    }
876}
877
878impl TraceRecord {
879    /// Serialize this record as a golden-trace-v2 JSONL line.
880    pub fn to_jsonl(&self) -> String {
881        match self {
882            TraceRecord::Header {
883                seed,
884                cols,
885                rows,
886                profile,
887            } => format!(
888                r#"{{"schema_version":"{}","event":"trace_header","seed":{},"cols":{},"rows":{},"env":{{"target":"web"}},"profile":"{}"}}"#,
889                SCHEMA_VERSION,
890                seed,
891                cols,
892                rows,
893                json_escape(profile)
894            ),
895            TraceRecord::Input { ts_ns, event } => format!(
896                r#"{{"schema_version":"{}","event":"input","ts_ns":{},"data":{}}}"#,
897                SCHEMA_VERSION,
898                ts_ns,
899                event_to_json(event)
900            ),
901            TraceRecord::Resize { ts_ns, cols, rows } => format!(
902                r#"{{"schema_version":"{}","event":"resize","ts_ns":{},"cols":{},"rows":{}}}"#,
903                SCHEMA_VERSION, ts_ns, cols, rows
904            ),
905            TraceRecord::Tick { ts_ns } => format!(
906                r#"{{"schema_version":"{}","event":"tick","ts_ns":{}}}"#,
907                SCHEMA_VERSION, ts_ns
908            ),
909            TraceRecord::Step {
910                step_idx,
911                ts_ns,
912                init,
913                clock,
914                result,
915            } => format!(
916                r#"{{"schema_version":"{}","event":"step","step_idx":{},"ts_ns":{},"init":{},"clock_secs":{},"clock_subsec_nanos":{},"running":{},"rendered":{},"events_processed":{},"events_pending":{},"frame_idx":{}}}"#,
917                SCHEMA_VERSION,
918                step_idx,
919                ts_ns,
920                init,
921                clock.as_secs(),
922                clock.subsec_nanos(),
923                result.running,
924                result.rendered,
925                result.events_processed,
926                result.events_pending,
927                result.frame_idx
928            ),
929            TraceRecord::Frame {
930                frame_idx,
931                ts_ns,
932                checksum,
933                checksum_chain,
934            } => format!(
935                r#"{{"schema_version":"{}","event":"frame","frame_idx":{},"ts_ns":{},"hash_algo":"fnv1a64","frame_hash":"{:016x}","checksum_chain":"{:016x}"}}"#,
936                SCHEMA_VERSION, frame_idx, ts_ns, checksum, checksum_chain
937            ),
938            TraceRecord::Summary {
939                total_frames,
940                final_checksum_chain,
941            } => format!(
942                r#"{{"schema_version":"{}","event":"trace_summary","total_frames":{},"final_checksum_chain":"{:016x}"}}"#,
943                SCHEMA_VERSION, total_frames, final_checksum_chain
944            ),
945        }
946    }
947}
948
949impl SessionTrace {
950    /// Serialize the entire trace as a golden-trace-v2 JSONL string.
951    pub fn to_jsonl(&self) -> String {
952        let mut out = String::new();
953        for record in &self.records {
954            out.push_str(&record.to_jsonl());
955            out.push('\n');
956        }
957        out
958    }
959
960    /// Parse a golden-trace-v2 JSONL string into a `SessionTrace`.
961    ///
962    /// Returns a parse error with the line number on failure.
963    pub fn from_jsonl(input: &str) -> Result<Self, TraceParseError> {
964        let mut records = Vec::new();
965        for (line_num, line) in input.lines().enumerate() {
966            let line = line.trim();
967            if line.is_empty() {
968                continue;
969            }
970            let record = parse_trace_line(line, line_num + 1)?;
971            records.push(record);
972        }
973        Ok(SessionTrace { records })
974    }
975
976    /// Parse and validate a golden-trace-v2 JSONL payload.
977    pub fn from_jsonl_validated(input: &str) -> Result<Self, TraceLoadError> {
978        let trace = Self::from_jsonl(input)?;
979        trace.validate()?;
980        Ok(trace)
981    }
982}
983
984/// Error parsing a JSONL trace.
985#[derive(Debug, Clone, PartialEq, Eq)]
986pub struct TraceParseError {
987    pub line: usize,
988    pub message: String,
989}
990
991impl core::fmt::Display for TraceParseError {
992    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
993        write!(f, "line {}: {}", self.line, self.message)
994    }
995}
996
997impl std::error::Error for TraceParseError {}
998
999/// Typed validation failures for `SessionTrace`.
1000#[derive(Debug, Clone, PartialEq, Eq)]
1001pub enum TraceValidationError {
1002    InvalidExecution {
1003        record_index: usize,
1004        reason: &'static str,
1005    },
1006    EmptyTrace,
1007    MissingHeader,
1008    HeaderNotFirst,
1009    MultipleHeaders,
1010    MissingSummary,
1011    MultipleSummaries,
1012    SummaryNotLast {
1013        summary_index: usize,
1014    },
1015    TimestampRegression {
1016        previous: u64,
1017        current: u64,
1018        record_index: usize,
1019    },
1020    FrameIndexMismatch {
1021        expected: u64,
1022        actual: u64,
1023    },
1024    SummaryFrameCountMismatch {
1025        expected: u64,
1026        actual: u64,
1027    },
1028    SummaryChecksumChainMismatch {
1029        expected: u64,
1030        actual: u64,
1031    },
1032}
1033
1034impl core::fmt::Display for TraceValidationError {
1035    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
1036        match self {
1037            Self::InvalidExecution {
1038                record_index,
1039                reason,
1040            } => {
1041                write!(f, "invalid execution at record {record_index}: {reason}")
1042            }
1043            Self::EmptyTrace => write!(f, "trace is empty"),
1044            Self::MissingHeader => write!(f, "trace is missing header"),
1045            Self::HeaderNotFirst => write!(f, "trace header is not the first record"),
1046            Self::MultipleHeaders => write!(f, "trace contains multiple headers"),
1047            Self::MissingSummary => write!(f, "trace is missing summary"),
1048            Self::MultipleSummaries => write!(f, "trace contains multiple summaries"),
1049            Self::SummaryNotLast { summary_index } => write!(
1050                f,
1051                "trace summary at index {} is not the final record",
1052                summary_index
1053            ),
1054            Self::TimestampRegression {
1055                previous,
1056                current,
1057                record_index,
1058            } => write!(
1059                f,
1060                "timestamp regression at record {}: current ts_ns={} is less than previous ts_ns={}",
1061                record_index, current, previous
1062            ),
1063            Self::FrameIndexMismatch { expected, actual } => {
1064                write!(
1065                    f,
1066                    "frame index mismatch: expected {}, got {}",
1067                    expected, actual
1068                )
1069            }
1070            Self::SummaryFrameCountMismatch { expected, actual } => write!(
1071                f,
1072                "summary frame-count mismatch: expected {}, got {}",
1073                expected, actual
1074            ),
1075            Self::SummaryChecksumChainMismatch { expected, actual } => write!(
1076                f,
1077                "summary checksum-chain mismatch: expected {:016x}, got {:016x}",
1078                expected, actual
1079            ),
1080        }
1081    }
1082}
1083
1084impl std::error::Error for TraceValidationError {}
1085
1086/// Combined load error for parse + validation.
1087#[derive(Debug, Clone, PartialEq, Eq)]
1088pub enum TraceLoadError {
1089    Parse(TraceParseError),
1090    Validation(TraceValidationError),
1091}
1092
1093impl core::fmt::Display for TraceLoadError {
1094    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
1095        match self {
1096            Self::Parse(e) => write!(f, "{e}"),
1097            Self::Validation(e) => write!(f, "{e}"),
1098        }
1099    }
1100}
1101
1102impl std::error::Error for TraceLoadError {}
1103
1104impl From<TraceParseError> for TraceLoadError {
1105    fn from(value: TraceParseError) -> Self {
1106        Self::Parse(value)
1107    }
1108}
1109
1110impl From<TraceValidationError> for TraceLoadError {
1111    fn from(value: TraceValidationError) -> Self {
1112        Self::Validation(value)
1113    }
1114}
1115
1116// ---- Minimal JSON field extraction (no serde dependency) ----
1117
1118fn json_string_end(input: &str) -> Option<usize> {
1119    let bytes = input.as_bytes();
1120    if bytes.first() != Some(&b'"') {
1121        return None;
1122    }
1123    let mut i = 1;
1124    while i < bytes.len() {
1125        if bytes[i] == b'\\' {
1126            i += 2;
1127            continue;
1128        }
1129        if bytes[i] == b'"' {
1130            return Some(i + 1);
1131        }
1132        if bytes[i] < 0x20 {
1133            return None;
1134        }
1135        i += 1;
1136    }
1137    None
1138}
1139
1140fn json_value_end(input: &str) -> Option<usize> {
1141    match input.as_bytes().first()? {
1142        b'"' => json_string_end(input),
1143        b'{' | b'[' => {
1144            let mut closing = Vec::new();
1145            let mut index = 0;
1146            while index < input.len() {
1147                match input.as_bytes()[index] {
1148                    b'"' => {
1149                        index += json_string_end(&input[index..])?;
1150                        continue;
1151                    }
1152                    b'{' => closing.push(b'}'),
1153                    b'[' => closing.push(b']'),
1154                    byte @ (b'}' | b']') => {
1155                        if closing.pop()? != byte {
1156                            return None;
1157                        }
1158                        if closing.is_empty() {
1159                            return Some(index + 1);
1160                        }
1161                    }
1162                    _ => {}
1163                }
1164                index += 1;
1165            }
1166            None
1167        }
1168        _ => Some(input.find([',', '}', ']']).unwrap_or(input.len())),
1169    }
1170}
1171
1172// Only inspect complete top-level values. A nested field or quoted payload
1173// must never impersonate execution metadata; duplicate requested keys fail.
1174fn extract_value<'a>(json: &'a str, key: &str) -> Option<&'a str> {
1175    let mut rest = json.trim().strip_prefix('{')?.trim_start();
1176    let mut found = None;
1177    if rest == "}" {
1178        return None;
1179    }
1180    loop {
1181        let key_end = json_string_end(rest)?;
1182        let field_key = &rest[1..key_end - 1];
1183        rest = rest[key_end..].trim_start().strip_prefix(':')?.trim_start();
1184        let value_end = json_value_end(rest)?;
1185        let value = rest[..value_end].trim();
1186        if value.is_empty() {
1187            return None;
1188        }
1189        if field_key == key {
1190            if found.is_some() {
1191                return None;
1192            }
1193            found = Some(value);
1194        }
1195        rest = rest[value_end..].trim_start();
1196        if rest == "}" {
1197            return found;
1198        }
1199        rest = rest.strip_prefix(',')?.trim_start();
1200    }
1201}
1202
1203fn extract_str<'a>(json: &'a str, key: &str) -> Option<&'a str> {
1204    extract_value(json, key)?
1205        .strip_prefix('"')?
1206        .strip_suffix('"')
1207}
1208
1209fn extract_u64(json: &str, key: &str) -> Option<u64> {
1210    let value = extract_value(json, key)?;
1211    if !value.bytes().all(|byte| byte.is_ascii_digit())
1212        || (value.len() > 1 && value.starts_with('0'))
1213    {
1214        return None;
1215    }
1216    value.parse().ok()
1217}
1218
1219fn extract_i64(json: &str, key: &str) -> Option<i64> {
1220    let value = extract_value(json, key)?;
1221    let digits = value.strip_prefix('-').unwrap_or(value);
1222    if !digits.bytes().all(|byte| byte.is_ascii_digit())
1223        || (digits.len() > 1 && digits.starts_with('0'))
1224    {
1225        return None;
1226    }
1227    value.parse().ok()
1228}
1229
1230fn extract_u16(json: &str, key: &str) -> Option<u16> {
1231    extract_u64(json, key).and_then(|v| u16::try_from(v).ok())
1232}
1233
1234fn extract_bool(json: &str, key: &str) -> Option<bool> {
1235    match extract_value(json, key)? {
1236        "true" => Some(true),
1237        "false" => Some(false),
1238        _ => None,
1239    }
1240}
1241
1242fn extract_hex_u64(json: &str, key: &str) -> Option<u64> {
1243    let s = extract_str(json, key)?;
1244    u64::from_str_radix(s, 16).ok()
1245}
1246
1247fn extract_object<'a>(json: &'a str, key: &str) -> Option<&'a str> {
1248    let value = extract_value(json, key)?;
1249    (value.starts_with('{') && value.ends_with('}')).then_some(value)
1250}
1251
1252fn json_unescape(input: &str) -> Result<String, String> {
1253    fn hex_unit(chars: &mut core::str::Chars<'_>) -> Result<u32, String> {
1254        let mut unit = 0;
1255        for _ in 0..4 {
1256            let digit = chars
1257                .next()
1258                .and_then(|ch| ch.to_digit(16))
1259                .ok_or("invalid JSON Unicode escape")?;
1260            unit = unit * 16 + digit;
1261        }
1262        Ok(unit)
1263    }
1264
1265    let mut out = String::with_capacity(input.len());
1266    let mut chars = input.chars();
1267    while let Some(ch) = chars.next() {
1268        if ch == '\\' {
1269            match chars.next() {
1270                Some('"') => out.push('"'),
1271                Some('\\') => out.push('\\'),
1272                Some('/') => out.push('/'),
1273                Some('b') => out.push('\u{0008}'),
1274                Some('f') => out.push('\u{000c}'),
1275                Some('n') => out.push('\n'),
1276                Some('r') => out.push('\r'),
1277                Some('t') => out.push('\t'),
1278                Some('u') => {
1279                    let mut cp = hex_unit(&mut chars)?;
1280                    if (0xd800..=0xdbff).contains(&cp) {
1281                        if chars.next() != Some('\\') || chars.next() != Some('u') {
1282                            return Err("missing JSON low surrogate".to_string());
1283                        }
1284                        let low = hex_unit(&mut chars)?;
1285                        if !(0xdc00..=0xdfff).contains(&low) {
1286                            return Err("invalid JSON low surrogate".to_string());
1287                        }
1288                        cp = 0x10000 + ((cp - 0xd800) << 10) + (low - 0xdc00);
1289                    }
1290                    out.push(char::from_u32(cp).ok_or("invalid JSON Unicode scalar")?);
1291                }
1292                Some(_) => return Err("invalid JSON escape".to_string()),
1293                None => return Err("incomplete JSON escape".to_string()),
1294            }
1295        } else {
1296            out.push(ch);
1297        }
1298    }
1299    Ok(out)
1300}
1301
1302fn check_trace_schema_compat(schema_version: &str, line_num: usize) -> Result<(), TraceParseError> {
1303    let incompatible = schema_version != SCHEMA_VERSION;
1304
1305    #[cfg(feature = "tracing")]
1306    {
1307        let span = info_span!(
1308            "trace.compat_check",
1309            reader_schema_version = SCHEMA_VERSION,
1310            writer_schema_version = schema_version,
1311            line = line_num,
1312            compatible = !incompatible,
1313        );
1314        let _guard = span.enter();
1315
1316        if incompatible {
1317            error!(
1318                reader_schema_version = SCHEMA_VERSION,
1319                writer_schema_version = schema_version,
1320                line = line_num,
1321                "trace schema version incompatible"
1322            );
1323        }
1324    }
1325
1326    if incompatible {
1327        return Err(TraceParseError {
1328            line: line_num,
1329            message: format!(
1330                "unsupported schema_version: {schema_version} (reader={SCHEMA_VERSION}, migration required)"
1331            ),
1332        });
1333    }
1334    Ok(())
1335}
1336
1337fn parse_trace_line(line: &str, line_num: usize) -> Result<TraceRecord, TraceParseError> {
1338    let err = |msg: &str| TraceParseError {
1339        line: line_num,
1340        message: msg.to_string(),
1341    };
1342
1343    let schema_version = extract_str(line, "schema_version")
1344        .ok_or_else(|| err("missing \"schema_version\" field"))?;
1345    check_trace_schema_compat(schema_version, line_num)?;
1346
1347    let event = extract_str(line, "event").ok_or_else(|| err("missing \"event\" field"))?;
1348
1349    match event {
1350        "trace_header" => {
1351            let seed = extract_u64(line, "seed").unwrap_or(0);
1352            let cols = extract_u16(line, "cols").ok_or_else(|| err("missing cols"))?;
1353            let rows = extract_u16(line, "rows").ok_or_else(|| err("missing rows"))?;
1354            let profile = extract_str(line, "profile")
1355                .map(|s| s.to_string())
1356                .unwrap_or_else(|| "modern".to_string());
1357            Ok(TraceRecord::Header {
1358                seed,
1359                cols,
1360                rows,
1361                profile,
1362            })
1363        }
1364        "input" => {
1365            let ts_ns = extract_u64(line, "ts_ns").ok_or_else(|| err("missing ts_ns"))?;
1366            let data = extract_object(line, "data").ok_or_else(|| err("missing data object"))?;
1367            let event = parse_event_json(data).map_err(|e| err(&e))?;
1368            Ok(TraceRecord::Input { ts_ns, event })
1369        }
1370        "resize" => {
1371            let ts_ns = extract_u64(line, "ts_ns").ok_or_else(|| err("missing ts_ns"))?;
1372            let cols = extract_u16(line, "cols").ok_or_else(|| err("missing cols"))?;
1373            let rows = extract_u16(line, "rows").ok_or_else(|| err("missing rows"))?;
1374            Ok(TraceRecord::Resize { ts_ns, cols, rows })
1375        }
1376        "tick" => {
1377            let ts_ns = extract_u64(line, "ts_ns").ok_or_else(|| err("missing ts_ns"))?;
1378            Ok(TraceRecord::Tick { ts_ns })
1379        }
1380        "step" => {
1381            let required_u64 = |key| {
1382                extract_u64(line, key).ok_or_else(|| err(&format!("missing or invalid {key}")))
1383            };
1384            let required_u32 = |key| {
1385                required_u64(key).and_then(|value| {
1386                    u32::try_from(value).map_err(|_| err(&format!("{key} out of range")))
1387                })
1388            };
1389            let required_bool = |key| {
1390                extract_bool(line, key).ok_or_else(|| err(&format!("missing or invalid {key}")))
1391            };
1392            let nanos = required_u32("clock_subsec_nanos")?;
1393            if nanos >= 1_000_000_000 {
1394                return Err(err("clock_subsec_nanos must be less than 1000000000"));
1395            }
1396            Ok(TraceRecord::Step {
1397                step_idx: required_u64("step_idx")?,
1398                ts_ns: required_u64("ts_ns")?,
1399                init: required_bool("init")?,
1400                clock: Duration::new(required_u64("clock_secs")?, nanos),
1401                result: StepResult {
1402                    running: required_bool("running")?,
1403                    rendered: required_bool("rendered")?,
1404                    events_processed: required_u32("events_processed")?,
1405                    events_pending: required_u32("events_pending")?,
1406                    frame_idx: required_u64("frame_idx")?,
1407                },
1408            })
1409        }
1410        "frame" => {
1411            let frame_idx =
1412                extract_u64(line, "frame_idx").ok_or_else(|| err("missing frame_idx"))?;
1413            let ts_ns = extract_u64(line, "ts_ns").ok_or_else(|| err("missing ts_ns"))?;
1414            let checksum =
1415                extract_hex_u64(line, "frame_hash").ok_or_else(|| err("missing frame_hash"))?;
1416            let checksum_chain = extract_hex_u64(line, "checksum_chain")
1417                .ok_or_else(|| err("missing checksum_chain"))?;
1418            Ok(TraceRecord::Frame {
1419                frame_idx,
1420                ts_ns,
1421                checksum,
1422                checksum_chain,
1423            })
1424        }
1425        "trace_summary" => {
1426            let total_frames =
1427                extract_u64(line, "total_frames").ok_or_else(|| err("missing total_frames"))?;
1428            let final_checksum_chain = extract_hex_u64(line, "final_checksum_chain")
1429                .ok_or_else(|| err("missing final_checksum_chain"))?;
1430            Ok(TraceRecord::Summary {
1431                total_frames,
1432                final_checksum_chain,
1433            })
1434        }
1435        other => Err(err(&format!("unknown event type: {other}"))),
1436    }
1437}
1438
1439fn parse_event_json(data: &str) -> Result<Event, String> {
1440    let kind = extract_str(data, "kind").ok_or("missing event kind")?;
1441    match kind {
1442        "key" => {
1443            let code_str = extract_str(data, "code").ok_or("missing key code")?;
1444            let code = parse_key_code(&json_unescape(code_str)?)?;
1445            let mods_bits = extract_u64(data, "modifiers")
1446                .or(extract_u64(data, "mods"))
1447                .unwrap_or(0) as u8;
1448            let modifiers = Modifiers::from_bits(mods_bits).unwrap_or_else(Modifiers::empty);
1449            let event_kind = if let Some(event_kind_str) = extract_str(data, "event_kind") {
1450                match event_kind_str {
1451                    "press" => KeyEventKind::Press,
1452                    "repeat" => KeyEventKind::Repeat,
1453                    "release" => KeyEventKind::Release,
1454                    _ => KeyEventKind::Press,
1455                }
1456            } else {
1457                let phase = extract_str(data, "phase").unwrap_or("down");
1458                let repeat = extract_bool(data, "repeat").unwrap_or(false);
1459                parse_key_event_kind(phase, repeat)
1460            };
1461            Ok(Event::Key(KeyEvent {
1462                code,
1463                modifiers,
1464                kind: event_kind,
1465            }))
1466        }
1467        "mouse" => {
1468            let mouse_kind = if let Some(mouse_kind_str) = extract_str(data, "mouse_kind") {
1469                parse_mouse_event_kind(mouse_kind_str)?
1470            } else {
1471                let phase = extract_str(data, "phase").ok_or("missing phase for mouse event")?;
1472                let button = extract_u64(data, "button")
1473                    .map(|raw| {
1474                        u8::try_from(raw).map_err(|_| "mouse button out of range".to_string())
1475                    })
1476                    .transpose()?;
1477                parse_mouse_phase_and_button(phase, button)?
1478            };
1479            let x = extract_u16(data, "x").unwrap_or(0);
1480            let y = extract_u16(data, "y").unwrap_or(0);
1481            let mods_bits = extract_u64(data, "modifiers")
1482                .or(extract_u64(data, "mods"))
1483                .unwrap_or(0) as u8;
1484            let modifiers = Modifiers::from_bits(mods_bits).unwrap_or_else(Modifiers::empty);
1485            Ok(Event::Mouse(MouseEvent {
1486                kind: mouse_kind,
1487                x,
1488                y,
1489                modifiers,
1490            }))
1491        }
1492        "wheel" => {
1493            let x = extract_u16(data, "x").unwrap_or(0);
1494            let y = extract_u16(data, "y").unwrap_or(0);
1495            let dx = extract_i64(data, "dx")
1496                .and_then(|value| i16::try_from(value).ok())
1497                .unwrap_or(0);
1498            let dy = extract_i64(data, "dy")
1499                .and_then(|value| i16::try_from(value).ok())
1500                .unwrap_or(0);
1501            let kind = if dy < 0 {
1502                MouseEventKind::ScrollUp
1503            } else if dy > 0 {
1504                MouseEventKind::ScrollDown
1505            } else if dx < 0 {
1506                MouseEventKind::ScrollLeft
1507            } else if dx > 0 {
1508                MouseEventKind::ScrollRight
1509            } else {
1510                return Err("wheel event must include non-zero dx or dy".to_string());
1511            };
1512            let mods_bits = extract_u64(data, "modifiers")
1513                .or(extract_u64(data, "mods"))
1514                .unwrap_or(0) as u8;
1515            let modifiers = Modifiers::from_bits(mods_bits).unwrap_or_else(Modifiers::empty);
1516            Ok(Event::Mouse(MouseEvent {
1517                kind,
1518                x,
1519                y,
1520                modifiers,
1521            }))
1522        }
1523        "resize" => {
1524            let width = extract_u16(data, "width").ok_or("missing width")?;
1525            let height = extract_u16(data, "height").ok_or("missing height")?;
1526            Ok(Event::Resize { width, height })
1527        }
1528        "paste" => {
1529            let text = extract_str(data, "text")
1530                .or(extract_str(data, "data"))
1531                .map(json_unescape)
1532                .transpose()?
1533                .unwrap_or_default();
1534            let bracketed = extract_bool(data, "bracketed").unwrap_or(true);
1535            Ok(Event::Paste(PasteEvent::new(text, bracketed)))
1536        }
1537        "ime" | "composition" => {
1538            let phase_raw = extract_str(data, "phase").unwrap_or("update");
1539            let phase = parse_ime_phase(phase_raw)?;
1540            let text = extract_str(data, "text")
1541                .or(extract_str(data, "data"))
1542                .map(json_unescape)
1543                .transpose()?
1544                .unwrap_or_default();
1545            let ime = match phase {
1546                ImePhase::Start => ImeEvent::start(),
1547                ImePhase::Update => ImeEvent::update(text),
1548                ImePhase::Commit => ImeEvent::commit(text),
1549                ImePhase::Cancel => ImeEvent::cancel(),
1550            };
1551            Ok(Event::Ime(ime))
1552        }
1553        "focus" => {
1554            let gained = extract_bool(data, "gained")
1555                .or(extract_bool(data, "focused"))
1556                .unwrap_or(true);
1557            Ok(Event::Focus(gained))
1558        }
1559        "clipboard" => {
1560            let content = extract_str(data, "content")
1561                .map(json_unescape)
1562                .transpose()?
1563                .unwrap_or_default();
1564            let source_str = extract_str(data, "source").unwrap_or("unknown");
1565            let source = match source_str {
1566                "osc52" => ClipboardSource::Osc52,
1567                _ => ClipboardSource::Unknown,
1568            };
1569            Ok(Event::Clipboard(ClipboardEvent::new(content, source)))
1570        }
1571        "tick" => Ok(Event::Tick),
1572        other => Err(format!("unknown event kind: {other}")),
1573    }
1574}
1575
1576fn parse_ime_phase(phase: &str) -> Result<ImePhase, String> {
1577    match phase {
1578        "start" => Ok(ImePhase::Start),
1579        "update" => Ok(ImePhase::Update),
1580        "end" | "commit" => Ok(ImePhase::Commit),
1581        "cancel" => Ok(ImePhase::Cancel),
1582        other => Err(format!("unknown ime/composition phase: {other}")),
1583    }
1584}
1585
1586fn parse_key_code(s: &str) -> Result<KeyCode, String> {
1587    if let Some(rest) = s.strip_prefix("char:") {
1588        let ch = rest.chars().next().ok_or("empty char code")?;
1589        return Ok(KeyCode::Char(ch));
1590    }
1591    if let Some(rest) = s.strip_prefix("f:") {
1592        let n: u8 = rest.parse().map_err(|_| "invalid F-key number")?;
1593        return Ok(KeyCode::F(n));
1594    }
1595    if let Some(n) = parse_function_key_token(s) {
1596        return Ok(KeyCode::F(n));
1597    }
1598
1599    let mut chars = s.chars();
1600    if let Some(ch) = chars.next()
1601        && chars.next().is_none()
1602    {
1603        return Ok(KeyCode::Char(ch));
1604    }
1605
1606    let normalized = s.to_ascii_lowercase();
1607    match normalized.as_str() {
1608        "enter" | "return" => Ok(KeyCode::Enter),
1609        "escape" | "esc" => Ok(KeyCode::Escape),
1610        "backspace" => Ok(KeyCode::Backspace),
1611        "tab" => Ok(KeyCode::Tab),
1612        "backtab" => Ok(KeyCode::BackTab),
1613        "delete" => Ok(KeyCode::Delete),
1614        "insert" => Ok(KeyCode::Insert),
1615        "home" => Ok(KeyCode::Home),
1616        "end" => Ok(KeyCode::End),
1617        "pageup" => Ok(KeyCode::PageUp),
1618        "pagedown" => Ok(KeyCode::PageDown),
1619        "up" | "arrowup" => Ok(KeyCode::Up),
1620        "down" | "arrowdown" => Ok(KeyCode::Down),
1621        "left" | "arrowleft" => Ok(KeyCode::Left),
1622        "right" | "arrowright" => Ok(KeyCode::Right),
1623        "null" | "unidentified" => Ok(KeyCode::Null),
1624        "media_play_pause" => Ok(KeyCode::MediaPlayPause),
1625        "media_stop" => Ok(KeyCode::MediaStop),
1626        "media_next" => Ok(KeyCode::MediaNextTrack),
1627        "media_prev" => Ok(KeyCode::MediaPrevTrack),
1628        other => Err(format!("unknown key code: {other}")),
1629    }
1630}
1631
1632fn parse_function_key_token(s: &str) -> Option<u8> {
1633    let rest = s.strip_prefix('F').or_else(|| s.strip_prefix('f'))?;
1634    if rest.is_empty() || !rest.chars().all(|ch| ch.is_ascii_digit()) {
1635        return None;
1636    }
1637    rest.parse().ok()
1638}
1639
1640fn parse_key_event_kind(phase: &str, repeat: bool) -> KeyEventKind {
1641    if phase.eq_ignore_ascii_case("up") || phase.eq_ignore_ascii_case("release") {
1642        KeyEventKind::Release
1643    } else if repeat {
1644        KeyEventKind::Repeat
1645    } else {
1646        KeyEventKind::Press
1647    }
1648}
1649
1650fn parse_mouse_event_kind(s: &str) -> Result<MouseEventKind, String> {
1651    match s {
1652        "down_left" => Ok(MouseEventKind::Down(MouseButton::Left)),
1653        "down_right" => Ok(MouseEventKind::Down(MouseButton::Right)),
1654        "down_middle" => Ok(MouseEventKind::Down(MouseButton::Middle)),
1655        "up_left" => Ok(MouseEventKind::Up(MouseButton::Left)),
1656        "up_right" => Ok(MouseEventKind::Up(MouseButton::Right)),
1657        "up_middle" => Ok(MouseEventKind::Up(MouseButton::Middle)),
1658        "drag_left" => Ok(MouseEventKind::Drag(MouseButton::Left)),
1659        "drag_right" => Ok(MouseEventKind::Drag(MouseButton::Right)),
1660        "drag_middle" => Ok(MouseEventKind::Drag(MouseButton::Middle)),
1661        "moved" => Ok(MouseEventKind::Moved),
1662        "scroll_up" => Ok(MouseEventKind::ScrollUp),
1663        "scroll_down" => Ok(MouseEventKind::ScrollDown),
1664        "scroll_left" => Ok(MouseEventKind::ScrollLeft),
1665        "scroll_right" => Ok(MouseEventKind::ScrollRight),
1666        other => Err(format!("unknown mouse event kind: {other}")),
1667    }
1668}
1669
1670fn parse_mouse_phase_and_button(phase: &str, button: Option<u8>) -> Result<MouseEventKind, String> {
1671    match phase {
1672        "down" => Ok(MouseEventKind::Down(parse_mouse_button(
1673            button.ok_or("mouse down requires button")?,
1674        )?)),
1675        "up" => Ok(MouseEventKind::Up(parse_mouse_button(
1676            button.ok_or("mouse up requires button")?,
1677        )?)),
1678        "drag" => Ok(MouseEventKind::Drag(parse_mouse_button(
1679            button.ok_or("mouse drag requires button")?,
1680        )?)),
1681        "move" => Ok(MouseEventKind::Moved),
1682        other => Err(format!("unknown mouse phase: {other}")),
1683    }
1684}
1685
1686fn parse_mouse_button(raw: u8) -> Result<MouseButton, String> {
1687    match raw {
1688        0 => Ok(MouseButton::Left),
1689        1 => Ok(MouseButton::Middle),
1690        2 => Ok(MouseButton::Right),
1691        other => Err(format!("unsupported mouse button: {other}")),
1692    }
1693}
1694
1695// ---- Golden Gate API ----
1696
1697/// Validate a trace against a fresh model, returning a detailed report.
1698///
1699/// This is the primary entry point for CI checksum gates. It replays the
1700/// trace and produces a [`GateReport`] with pass/fail status and actionable
1701/// diff information on any mismatch.
1702pub fn gate_trace<M: ftui_runtime::program::Model>(
1703    model: M,
1704    trace: &SessionTrace,
1705) -> Result<GateReport, ReplayError> {
1706    let result = replay(model, trace)?;
1707
1708    let frame_checksums: Vec<(u64, u64)> = trace
1709        .records
1710        .iter()
1711        .filter_map(|r| match r {
1712            TraceRecord::Frame {
1713                frame_idx,
1714                checksum,
1715                ..
1716            } => Some((*frame_idx, *checksum)),
1717            _ => None,
1718        })
1719        .collect();
1720
1721    let diff = result.first_mismatch.as_ref().map(|m| {
1722        // Find the event context: count Input/Resize/Tick records before the failing frame.
1723        let mut event_idx: u64 = 0;
1724        let mut last_event_desc = String::new();
1725        let mut frame_count: u64 = 0;
1726        for record in &trace.records {
1727            match record {
1728                TraceRecord::Frame { .. } => {
1729                    if frame_count == m.frame_idx {
1730                        break;
1731                    }
1732                    frame_count += 1;
1733                }
1734                TraceRecord::Input { event, .. } => {
1735                    last_event_desc = format!("{event:?}");
1736                    event_idx += 1;
1737                }
1738                TraceRecord::Resize { cols, rows, .. } => {
1739                    last_event_desc = format!("Resize({cols}x{rows})");
1740                    event_idx += 1;
1741                }
1742                TraceRecord::Tick { ts_ns } => {
1743                    last_event_desc = format!("Tick(ts_ns={ts_ns})");
1744                    event_idx += 1;
1745                }
1746                _ => {}
1747            }
1748        }
1749
1750        GateDiff {
1751            frame_idx: m.frame_idx,
1752            event_idx,
1753            last_event: last_event_desc,
1754            expected_checksum: m.expected,
1755            actual_checksum: m.actual,
1756        }
1757    });
1758
1759    Ok(GateReport {
1760        passed: result.ok(),
1761        total_steps: result.total_steps,
1762        running: result.running,
1763        unprocessed_events: result.unprocessed_events,
1764        total_frames: result.total_frames,
1765        expected_frames: frame_checksums.len() as u64,
1766        final_checksum_chain: result.final_checksum_chain,
1767        diff,
1768    })
1769}
1770
1771/// Report from a golden trace gate validation.
1772#[derive(Debug, Clone)]
1773pub struct GateReport {
1774    /// Whether all execution outcomes and frame checksums matched.
1775    pub passed: bool,
1776    /// Number of execution boundaries replayed, including initialization.
1777    pub total_steps: u64,
1778    /// Whether the replayed program is still running.
1779    pub running: bool,
1780    /// Accepted input left unprocessed after quit, preserved in FIFO order.
1781    pub unprocessed_events: Vec<Event>,
1782    /// Number of frames replayed.
1783    pub total_frames: u64,
1784    /// Number of frame checkpoints in the trace.
1785    pub expected_frames: u64,
1786    /// Final checksum chain from replay.
1787    pub final_checksum_chain: u64,
1788    /// Detailed diff information if there was a mismatch.
1789    pub diff: Option<GateDiff>,
1790}
1791
1792impl GateReport {
1793    /// Format the report as a human-readable string.
1794    pub fn format(&self) -> String {
1795        if self.passed {
1796            format!(
1797                "PASS: {}/{} frames verified, final_chain={:016x}, steps={}, running={}, unprocessed_events={}",
1798                self.total_frames,
1799                self.expected_frames,
1800                self.final_checksum_chain,
1801                self.total_steps,
1802                self.running,
1803                self.unprocessed_events.len()
1804            )
1805        } else if let Some(d) = &self.diff {
1806            format!(
1807                "FAIL at frame {} (after event #{}: {}): expected {:016x}, got {:016x}",
1808                d.frame_idx, d.event_idx, d.last_event, d.expected_checksum, d.actual_checksum
1809            )
1810        } else {
1811            format!(
1812                "FAIL: {}/{} frames, unknown mismatch",
1813                self.total_frames, self.expected_frames
1814            )
1815        }
1816    }
1817}
1818
1819/// Detailed diff information for a checksum mismatch.
1820#[derive(Debug, Clone)]
1821pub struct GateDiff {
1822    /// Frame index where the mismatch occurred.
1823    pub frame_idx: u64,
1824    /// Number of input events processed before the failing frame.
1825    pub event_idx: u64,
1826    /// Description of the last event before the failing frame.
1827    pub last_event: String,
1828    /// Expected checksum from the trace.
1829    pub expected_checksum: u64,
1830    /// Actual checksum from replay.
1831    pub actual_checksum: u64,
1832}
1833
1834#[cfg(test)]
1835mod tests {
1836    use super::*;
1837    use ftui_core::event::{
1838        KeyCode, KeyEvent, KeyEventKind, Modifiers, MouseButton, MouseEvent, MouseEventKind,
1839        PasteEvent,
1840    };
1841    use ftui_render::cell::Cell;
1842    use ftui_render::frame::Frame;
1843    use ftui_runtime::program::{Cmd, Model};
1844    use pretty_assertions::assert_eq;
1845    #[cfg(feature = "tracing")]
1846    use std::sync::{Arc, Mutex};
1847    #[cfg(feature = "tracing")]
1848    use tracing::Subscriber;
1849    #[cfg(feature = "tracing")]
1850    use tracing::field::{Field, Visit};
1851    #[cfg(feature = "tracing")]
1852    use tracing_subscriber::Layer;
1853    #[cfg(feature = "tracing")]
1854    use tracing_subscriber::filter::LevelFilter;
1855    #[cfg(feature = "tracing")]
1856    use tracing_subscriber::layer::{Context, SubscriberExt};
1857    #[cfg(feature = "tracing")]
1858    use tracing_subscriber::registry::LookupSpan;
1859
1860    #[cfg(feature = "tracing")]
1861    #[derive(Default, Clone)]
1862    struct TraceCaptureLayer {
1863        spans: Arc<Mutex<Vec<String>>>,
1864        events: Arc<Mutex<Vec<String>>>,
1865    }
1866
1867    #[cfg(feature = "tracing")]
1868    #[derive(Default)]
1869    struct EventMessageVisitor {
1870        message: Option<String>,
1871    }
1872
1873    #[cfg(feature = "tracing")]
1874    impl Visit for EventMessageVisitor {
1875        fn record_str(&mut self, field: &Field, value: &str) {
1876            if field.name() == "message" {
1877                self.message = Some(value.to_string());
1878            }
1879        }
1880
1881        fn record_debug(&mut self, field: &Field, value: &dyn std::fmt::Debug) {
1882            if field.name() == "message" {
1883                self.message = Some(format!("{value:?}"));
1884            }
1885        }
1886    }
1887
1888    #[cfg(feature = "tracing")]
1889    impl<S> Layer<S> for TraceCaptureLayer
1890    where
1891        S: Subscriber + for<'lookup> LookupSpan<'lookup>,
1892    {
1893        fn on_new_span(
1894            &self,
1895            attrs: &tracing::span::Attributes<'_>,
1896            _id: &tracing::span::Id,
1897            _ctx: Context<'_, S>,
1898        ) {
1899            self.spans
1900                .lock()
1901                .expect("span capture lock")
1902                .push(attrs.metadata().name().to_string());
1903        }
1904
1905        fn on_event(&self, event: &tracing::Event<'_>, _ctx: Context<'_, S>) {
1906            let mut visitor = EventMessageVisitor::default();
1907            event.record(&mut visitor);
1908            let message = visitor.message.unwrap_or_default();
1909            self.events
1910                .lock()
1911                .expect("event capture lock")
1912                .push(format!("{}:{}", event.metadata().level(), message));
1913        }
1914    }
1915
1916    // ---- Test model (same as step_program tests) ----
1917
1918    struct Counter {
1919        value: i32,
1920    }
1921
1922    #[derive(Debug)]
1923    enum CounterMsg {
1924        Increment,
1925        Decrement,
1926        Reset,
1927        Quit,
1928    }
1929
1930    impl From<Event> for CounterMsg {
1931        fn from(event: Event) -> Self {
1932            match event {
1933                Event::Key(k) if k.code == KeyCode::Char('+') => CounterMsg::Increment,
1934                Event::Key(k) if k.code == KeyCode::Char('-') => CounterMsg::Decrement,
1935                Event::Key(k) if k.code == KeyCode::Char('r') => CounterMsg::Reset,
1936                Event::Key(k) if k.code == KeyCode::Char('q') => CounterMsg::Quit,
1937                Event::Tick => CounterMsg::Increment,
1938                _ => CounterMsg::Increment,
1939            }
1940        }
1941    }
1942
1943    impl Model for Counter {
1944        type Message = CounterMsg;
1945
1946        fn init(&mut self) -> Cmd<Self::Message> {
1947            Cmd::none()
1948        }
1949
1950        fn update(&mut self, msg: Self::Message) -> Cmd<Self::Message> {
1951            match msg {
1952                CounterMsg::Increment => {
1953                    self.value += 1;
1954                    Cmd::none()
1955                }
1956                CounterMsg::Decrement => {
1957                    self.value -= 1;
1958                    Cmd::none()
1959                }
1960                CounterMsg::Reset => {
1961                    self.value = 0;
1962                    Cmd::none()
1963                }
1964                CounterMsg::Quit => Cmd::quit(),
1965            }
1966        }
1967
1968        fn view(&self, frame: &mut Frame) {
1969            let text = format!("Count: {}", self.value);
1970            for (i, c) in text.chars().enumerate() {
1971                if (i as u16) < frame.width() {
1972                    frame.buffer.set_raw(i as u16, 0, Cell::from_char(c));
1973                }
1974            }
1975        }
1976    }
1977
1978    fn key_event(c: char) -> Event {
1979        Event::Key(KeyEvent {
1980            code: KeyCode::Char(c),
1981            modifiers: Modifiers::empty(),
1982            kind: KeyEventKind::Press,
1983        })
1984    }
1985
1986    fn parse_single_input_event(data_json: &str) -> Event {
1987        let line = format!(
1988            r#"{{"schema_version":"{}","event":"input","ts_ns":0,"data":{}}}"#,
1989            SCHEMA_VERSION, data_json
1990        );
1991        let trace = SessionTrace::from_jsonl(&line).expect("input JSON should parse");
1992        trace
1993            .records
1994            .into_iter()
1995            .next()
1996            .and_then(|record| match record {
1997                TraceRecord::Input { event, .. } => Some(event),
1998                _ => None,
1999            })
2000            .expect("expected single input record")
2001    }
2002
2003    fn new_counter(value: i32) -> Counter {
2004        Counter { value }
2005    }
2006
2007    // Observe actual updates even when quit prevents any new frame.
2008    struct ObservedModel {
2009        seen: std::rc::Rc<std::cell::RefCell<Vec<Event>>>,
2010        init_count: std::rc::Rc<std::cell::Cell<u32>>,
2011        quit_on_init: bool,
2012        honor_quit: bool,
2013    }
2014
2015    impl Model for ObservedModel {
2016        type Message = Event;
2017
2018        fn init(&mut self) -> Cmd<Event> {
2019            self.init_count.set(self.init_count.get() + 1);
2020            if self.quit_on_init {
2021                Cmd::quit()
2022            } else {
2023                Cmd::tick(Duration::from_millis(10))
2024            }
2025        }
2026
2027        fn update(&mut self, event: Event) -> Cmd<Event> {
2028            let quit = event == key_event('q') && self.honor_quit;
2029            self.seen.borrow_mut().push(event);
2030            if quit { Cmd::quit() } else { Cmd::none() }
2031        }
2032
2033        fn view(&self, frame: &mut Frame) {
2034            frame.buffer.set_raw(0, 0, Cell::from_char('X'));
2035        }
2036    }
2037
2038    fn observed_model(quit_on_init: bool, honor_quit: bool) -> ObservedModel {
2039        ObservedModel {
2040            seen: Default::default(),
2041            init_count: Default::default(),
2042            quit_on_init,
2043            honor_quit,
2044        }
2045    }
2046
2047    #[test]
2048    fn non_rendering_quit_replays_actual_updates_and_exact_accepted_tail() {
2049        let model = observed_model(false, true);
2050        let recorded_seen = model.seen.clone();
2051        let mut recorder = SessionRecorder::new(model, 20, 2, 7);
2052        recorder.init().unwrap();
2053        let tail = vec![
2054            Event::Paste(PasteEvent::bracketed("尾巴 🦀")),
2055            Event::Resize {
2056                width: 33,
2057                height: 4,
2058            },
2059        ];
2060        for event in [key_event('+'), key_event('q')]
2061            .into_iter()
2062            .chain(tail.clone())
2063        {
2064            recorder.push_event(9, event).unwrap();
2065        }
2066        let outcome = recorder.step().unwrap();
2067        assert_eq!(outcome.events_processed, 2);
2068        assert_eq!(outcome.events_pending, 2);
2069        assert!(!outcome.running && !outcome.rendered);
2070        assert_eq!(
2071            *recorded_seen.borrow(),
2072            vec![key_event('+'), key_event('q')]
2073        );
2074        let trace = SessionTrace::from_jsonl_validated(&recorder.finish().to_jsonl()).unwrap();
2075        let model = observed_model(false, true);
2076        let replayed_seen = model.seen.clone();
2077        let init_count = model.init_count.clone();
2078        let result = replay(model, &trace).unwrap();
2079        assert!(result.ok());
2080        assert_eq!(result.total_steps, 2);
2081        assert_eq!(result.total_frames, 1);
2082        assert!(!result.running);
2083        assert_eq!(result.unprocessed_events, tail);
2084        assert_eq!(*replayed_seen.borrow(), *recorded_seen.borrow());
2085        assert_eq!(init_count.get(), 1);
2086        let gate = gate_trace(observed_model(false, true), &trace).unwrap();
2087        assert!(gate.passed);
2088        assert_eq!(gate.total_steps, 2);
2089        assert!(!gate.running);
2090        assert_eq!(gate.unprocessed_events, tail);
2091        assert!(gate.format().contains("unprocessed_events=2"));
2092        assert!(!gate.format().contains("尾巴"));
2093
2094        // Same initial frame, different quit behavior: checksum-only replay
2095        // previously accepted this without ever executing the quit step.
2096        assert!(matches!(
2097            replay(observed_model(false, false), &trace),
2098            Err(ReplayError::StepMismatch { step_idx: 1, .. })
2099        ));
2100    }
2101
2102    #[test]
2103    fn initialization_quit_has_no_frame_and_recovers_preinit_input() {
2104        let mut recorder = SessionRecorder::new(observed_model(true, true), 20, 2, 7);
2105        recorder.push_event(1, key_event('+')).unwrap();
2106        recorder.resize(2, 40, 4).unwrap();
2107        recorder.init().unwrap();
2108        assert_eq!(recorder.program().size(), (20, 2));
2109        assert!(recorder.program().outputs().last_buffer.is_none());
2110        let stopped = recorder.step().unwrap();
2111        assert_eq!(stopped.events_pending, 2);
2112        assert_eq!(stopped.events_processed, 0);
2113        let trace = SessionTrace::from_jsonl_validated(&recorder.finish().to_jsonl()).unwrap();
2114        let model = observed_model(true, true);
2115        let seen = model.seen.clone();
2116        let init_count = model.init_count.clone();
2117        let result = replay(model, &trace).unwrap();
2118        assert!(result.ok());
2119        assert!(!result.running);
2120        assert_eq!(result.total_frames, 0);
2121        assert_eq!(result.total_steps, 2);
2122        assert_eq!(init_count.get(), 1);
2123        assert!(seen.borrow().is_empty());
2124        assert_eq!(
2125            result.unprocessed_events,
2126            vec![
2127                key_event('+'),
2128                Event::Resize {
2129                    width: 40,
2130                    height: 4
2131                }
2132            ]
2133        );
2134    }
2135
2136    #[test]
2137    fn idle_steps_and_clock_deltas_replay_independently_of_metadata_timestamps() {
2138        let model = observed_model(false, true);
2139        let seen = model.seen.clone();
2140        let mut recorder = SessionRecorder::new(model, 20, 2, 7);
2141        recorder.init().unwrap();
2142        assert!(!recorder.step().unwrap().rendered);
2143        recorder.advance_time(1, Duration::from_millis(9));
2144        assert!(!recorder.step().unwrap().rendered);
2145        recorder.advance_time(2, Duration::from_millis(1));
2146        assert!(recorder.step().unwrap().rendered);
2147        assert!(!recorder.step().unwrap().rendered);
2148        assert_eq!(*seen.borrow(), vec![Event::Tick]);
2149        let trace = SessionTrace::from_jsonl_validated(&recorder.finish().to_jsonl()).unwrap();
2150        let model = observed_model(false, true);
2151        let replayed = model.seen.clone();
2152        let result = replay(model, &trace).unwrap();
2153        assert!(result.ok());
2154        assert_eq!(result.total_steps, 5);
2155        assert_eq!(result.total_frames, 2);
2156        assert_eq!(*replayed.borrow(), vec![Event::Tick]);
2157    }
2158
2159    #[test]
2160    fn trace_requires_observed_boundaries_without_implicit_flush_or_stale_frames() {
2161        let mut recorder = SessionRecorder::new(new_counter(0), 20, 2, 7);
2162        recorder.init().unwrap();
2163        recorder.push_event(1, key_event('q')).unwrap();
2164        recorder.step().unwrap();
2165        let trace = recorder.finish();
2166        trace.validate().unwrap();
2167        let quit_idx = trace.records.len() - 2;
2168        for missing in [1, 2, quit_idx] {
2169            let mut changed = trace.clone();
2170            changed.records.remove(missing);
2171            assert!(changed.validate().is_err(), "missing record {missing}");
2172            assert!(replay(new_counter(0), &changed).is_err());
2173        }
2174        let mut duplicate = trace.clone();
2175        duplicate
2176            .records
2177            .insert(quit_idx, trace.records[quit_idx].clone());
2178        assert!(duplicate.validate().is_err());
2179        let mut reordered = trace.clone();
2180        reordered.records.swap(1, 2);
2181        assert!(reordered.validate().is_err());
2182        let mut bad_count = trace.clone();
2183        if let TraceRecord::Step { result, .. } = &mut bad_count.records[quit_idx] {
2184            result.events_pending = 1;
2185        }
2186        assert!(bad_count.validate().is_err());
2187        let mut after_quit = trace.clone();
2188        after_quit.records.insert(
2189            quit_idx + 1,
2190            TraceRecord::Input {
2191                ts_ns: 1,
2192                event: key_event('+'),
2193            },
2194        );
2195        assert!(after_quit.validate().is_err());
2196
2197        let mut recorder = SessionRecorder::new(new_counter(0), 20, 2, 7);
2198        recorder.init().unwrap();
2199        recorder.push_event(1, key_event('+')).unwrap();
2200        assert!(recorder.finish().validate().is_err());
2201    }
2202
2203    #[test]
2204    fn recorder_rejects_before_changing_trace_or_timestamp_and_replays_recovery() {
2205        let mut recorder = SessionRecorder::new(new_counter(0), 80, 24, 0);
2206        recorder.init().unwrap();
2207        for _ in 0..crate::WebEventSource::MAX_EVENTS {
2208            recorder.push_event(1, key_event('+')).unwrap();
2209        }
2210        let records_before = recorder.records.len();
2211        assert!(matches!(
2212            recorder.push_event(2, key_event('-')),
2213            Err(WebBackendError::InputQueueFull { .. })
2214        ));
2215        assert!(matches!(
2216            recorder.resize(3, 120, 40),
2217            Err(WebBackendError::InputQueueFull { .. })
2218        ));
2219        assert_eq!(recorder.records.len(), records_before);
2220        assert_eq!(recorder.current_ts_ns, 1);
2221        assert_eq!(recorder.program.size(), (80, 24));
2222        assert_eq!(
2223            recorder.step().unwrap().events_processed as usize,
2224            crate::WebEventSource::MAX_EVENTS
2225        );
2226        recorder.push_event(2, key_event('-')).unwrap();
2227        recorder.resize(3, 120, 40).unwrap();
2228        assert_eq!(recorder.step().unwrap().events_processed, 2);
2229        let trace = recorder.finish();
2230        trace.validate().unwrap();
2231        assert!(replay(new_counter(0), &trace).unwrap().ok());
2232    }
2233
2234    #[test]
2235    fn replay_rejects_an_overfull_batch_without_inserting_unrecorded_steps() {
2236        let mut recorder = SessionRecorder::new(new_counter(0), 80, 24, 0);
2237        recorder.init().unwrap();
2238        let mut trace = recorder.finish();
2239        let summary_index = trace.records.len() - 1;
2240        trace.records.splice(
2241            summary_index..summary_index,
2242            (0..=crate::WebEventSource::MAX_EVENTS).map(|_| TraceRecord::Input {
2243                ts_ns: 0,
2244                event: key_event('+'),
2245            }),
2246        );
2247        trace.records.insert(
2248            trace.records.len() - 1,
2249            TraceRecord::Step {
2250                step_idx: 1,
2251                ts_ns: 0,
2252                init: false,
2253                clock: Duration::ZERO,
2254                result: StepResult {
2255                    running: false,
2256                    rendered: false,
2257                    events_processed: 0,
2258                    events_pending: crate::WebEventSource::MAX_EVENTS as u32 + 1,
2259                    frame_idx: 1,
2260                },
2261            },
2262        );
2263        trace.validate().unwrap();
2264        assert!(matches!(
2265            replay(new_counter(0), &trace),
2266            Err(ReplayError::Backend(WebBackendError::InputQueueFull {
2267                limit: crate::WebInputLimit::Events,
2268                ..
2269            }))
2270        ));
2271    }
2272
2273    // ---- FNV-1a hash tests ----
2274
2275    #[test]
2276    fn fnv1a64_pair_is_deterministic() {
2277        let a = fnv1a64_pair(0, 1234);
2278        let b = fnv1a64_pair(0, 1234);
2279        assert_eq!(a, b);
2280    }
2281
2282    #[test]
2283    fn fnv1a64_pair_differs_for_different_input() {
2284        assert_ne!(fnv1a64_pair(0, 1), fnv1a64_pair(0, 2));
2285        assert_ne!(fnv1a64_pair(1, 0), fnv1a64_pair(2, 0));
2286    }
2287
2288    // ---- Recorder basic lifecycle ----
2289
2290    #[test]
2291    fn recorder_produces_header_and_summary() {
2292        let mut rec = SessionRecorder::new(new_counter(0), 80, 24, 42);
2293        rec.init().unwrap();
2294
2295        let trace = rec.finish();
2296        assert_eq!(trace.records.len(), 4); // header + init step + frame + summary
2297
2298        // First record is header.
2299        assert!(matches!(
2300            &trace.records[0],
2301            TraceRecord::Header {
2302                seed: 42,
2303                cols: 80,
2304                rows: 24,
2305                ..
2306            }
2307        ));
2308
2309        // Last record is summary.
2310        assert!(matches!(
2311            trace.records.last().unwrap(),
2312            TraceRecord::Summary {
2313                total_frames: 1,
2314                ..
2315            }
2316        ));
2317    }
2318
2319    #[test]
2320    fn recorder_captures_init_frame() {
2321        let mut rec = SessionRecorder::new(new_counter(0), 20, 1, 0);
2322        rec.init().unwrap();
2323
2324        let trace = rec.finish();
2325        let frames: Vec<_> = trace
2326            .records
2327            .iter()
2328            .filter(|r| matches!(r, TraceRecord::Frame { .. }))
2329            .collect();
2330        assert_eq!(frames.len(), 1);
2331
2332        if let TraceRecord::Frame {
2333            frame_idx,
2334            checksum,
2335            ..
2336        } = &frames[0]
2337        {
2338            assert_eq!(*frame_idx, 0);
2339            assert_ne!(*checksum, 0); // Non-trivial checksum.
2340        }
2341    }
2342
2343    // ---- Record and replay ----
2344
2345    #[test]
2346    fn record_replay_identical_checksums() {
2347        // Record a session.
2348        let mut rec = SessionRecorder::new(new_counter(0), 20, 1, 0);
2349        rec.init().unwrap();
2350
2351        rec.push_event(1_000_000, key_event('+'))
2352            .expect("key admission");
2353        rec.push_event(2_000_000, key_event('+'))
2354            .expect("key admission");
2355        rec.push_event(3_000_000, key_event('-'))
2356            .expect("key admission");
2357        rec.step().unwrap();
2358
2359        rec.push_event(16_000_000, key_event('+'))
2360            .expect("key admission");
2361        rec.step().unwrap();
2362
2363        let trace = rec.finish();
2364        assert_eq!(trace.frame_count(), 3); // init + 2 steps
2365
2366        // Replay with a fresh model.
2367        let result = replay(new_counter(0), &trace).unwrap();
2368        assert!(result.ok(), "replay mismatch: {:?}", result.first_mismatch);
2369        assert_eq!(result.total_frames, 3);
2370        assert_eq!(
2371            result.final_checksum_chain,
2372            trace.final_checksum_chain().unwrap()
2373        );
2374    }
2375
2376    #[test]
2377    fn replay_detects_different_initial_state() {
2378        // Record with counter starting at 0.
2379        let mut rec = SessionRecorder::new(new_counter(0), 20, 1, 0);
2380        rec.init().unwrap();
2381        let trace = rec.finish();
2382
2383        // Replay with counter starting at 5 — different init state → different checksum.
2384        let result = replay(new_counter(5), &trace).unwrap();
2385        assert!(!result.ok());
2386        assert_eq!(result.first_mismatch.as_ref().unwrap().frame_idx, 0);
2387    }
2388
2389    #[test]
2390    fn replay_detects_divergence_after_events() {
2391        // Record with normal counter.
2392        let mut rec = SessionRecorder::new(new_counter(0), 20, 1, 0);
2393        rec.init().unwrap();
2394
2395        rec.push_event(1_000_000, key_event('+'))
2396            .expect("key admission");
2397        rec.push_event(2_000_000, key_event('+'))
2398            .expect("key admission");
2399        rec.step().unwrap();
2400
2401        let trace = rec.finish();
2402
2403        // Replay with a model that starts at 1 instead of 0.
2404        let result = replay(new_counter(1), &trace).unwrap();
2405        assert!(!result.ok());
2406    }
2407
2408    // ---- Resize recording ----
2409
2410    #[test]
2411    fn resize_is_recorded_and_replayed() {
2412        let mut rec = SessionRecorder::new(new_counter(0), 20, 1, 0);
2413        rec.init().unwrap();
2414
2415        rec.resize(5_000_000, 40, 2).expect("resize admission");
2416        rec.step().unwrap();
2417
2418        let trace = rec.finish();
2419
2420        // Verify resize record exists.
2421        assert!(trace.records.iter().any(|r| matches!(
2422            r,
2423            TraceRecord::Resize {
2424                cols: 40,
2425                rows: 2,
2426                ..
2427            }
2428        )));
2429
2430        // Replay should match.
2431        let result = replay(new_counter(0), &trace).unwrap();
2432        assert!(
2433            result.ok(),
2434            "resize replay mismatch: {:?}",
2435            result.first_mismatch
2436        );
2437    }
2438
2439    // ---- Multiple steps ----
2440
2441    #[test]
2442    fn multi_step_record_replay() {
2443        let mut rec = SessionRecorder::new(new_counter(0), 20, 1, 0);
2444        rec.init().unwrap();
2445
2446        for i in 0..5 {
2447            rec.push_event(i * 16_000_000, key_event('+'))
2448                .expect("key admission");
2449            rec.step().unwrap();
2450        }
2451
2452        let trace = rec.finish();
2453        assert_eq!(trace.frame_count(), 6); // init + 5 steps
2454
2455        let result = replay(new_counter(0), &trace).unwrap();
2456        assert!(
2457            result.ok(),
2458            "multi-step mismatch: {:?}",
2459            result.first_mismatch
2460        );
2461        assert_eq!(result.total_frames, 6);
2462    }
2463
2464    // ---- Quit during session ----
2465
2466    #[test]
2467    fn quit_stops_recording() {
2468        let mut rec = SessionRecorder::new(new_counter(0), 20, 1, 0);
2469        rec.init().unwrap();
2470
2471        rec.push_event(1_000_000, key_event('+'))
2472            .expect("key admission");
2473        rec.push_event(2_000_000, key_event('q'))
2474            .expect("quit admission");
2475        let result = rec.step().unwrap();
2476        assert!(!result.running);
2477
2478        let trace = rec.finish();
2479        // init frame + no render after quit (quit stops before render).
2480        assert_eq!(trace.frame_count(), 1);
2481    }
2482
2483    // ---- Empty session ----
2484
2485    #[test]
2486    fn empty_session_replay() {
2487        let mut rec = SessionRecorder::new(new_counter(0), 20, 1, 0);
2488        rec.init().unwrap();
2489        let trace = rec.finish();
2490
2491        let result = replay(new_counter(0), &trace).unwrap();
2492        assert!(result.ok());
2493        assert_eq!(result.total_frames, 1); // Just the init frame.
2494    }
2495
2496    // ---- Trace accessors ----
2497
2498    #[test]
2499    fn session_trace_frame_count() {
2500        let mut rec = SessionRecorder::new(new_counter(0), 20, 1, 0);
2501        rec.init().unwrap();
2502        rec.push_event(1_000_000, key_event('+'))
2503            .expect("key admission");
2504        rec.step().unwrap();
2505        let trace = rec.finish();
2506        assert_eq!(trace.frame_count(), 2);
2507    }
2508
2509    #[test]
2510    fn session_trace_final_checksum_chain() {
2511        let mut rec = SessionRecorder::new(new_counter(0), 20, 1, 0);
2512        rec.init().unwrap();
2513        let trace = rec.finish();
2514        assert!(trace.final_checksum_chain().is_some());
2515        assert_ne!(trace.final_checksum_chain().unwrap(), 0);
2516    }
2517
2518    // ---- Replay error cases ----
2519
2520    #[test]
2521    fn replay_missing_header_returns_error() {
2522        let trace = SessionTrace { records: vec![] };
2523        let result = replay(new_counter(0), &trace);
2524        assert!(matches!(result, Err(ReplayError::MissingHeader)));
2525    }
2526
2527    #[test]
2528    fn replay_non_header_first_returns_error() {
2529        let trace = SessionTrace {
2530            records: vec![TraceRecord::Tick { ts_ns: 0 }],
2531        };
2532        let result = replay(new_counter(0), &trace);
2533        assert!(matches!(result, Err(ReplayError::MissingHeader)));
2534    }
2535
2536    #[test]
2537    fn trace_validate_missing_summary_returns_typed_error() {
2538        let trace = SessionTrace {
2539            records: vec![TraceRecord::Header {
2540                seed: 0,
2541                cols: 80,
2542                rows: 24,
2543                profile: "modern".to_string(),
2544            }],
2545        };
2546        let result = trace.validate();
2547        assert_eq!(result, Err(TraceValidationError::MissingSummary));
2548    }
2549
2550    #[test]
2551    fn trace_validate_summary_frame_count_mismatch_returns_typed_error() {
2552        let trace = SessionTrace {
2553            records: vec![
2554                TraceRecord::Header {
2555                    seed: 0,
2556                    cols: 80,
2557                    rows: 24,
2558                    profile: "modern".to_string(),
2559                },
2560                TraceRecord::Frame {
2561                    frame_idx: 0,
2562                    ts_ns: 0,
2563                    checksum: 0x1,
2564                    checksum_chain: 0x10,
2565                },
2566                TraceRecord::Summary {
2567                    total_frames: 2,
2568                    final_checksum_chain: 0x10,
2569                },
2570            ],
2571        };
2572        let result = trace.validate();
2573        assert_eq!(
2574            result,
2575            Err(TraceValidationError::SummaryFrameCountMismatch {
2576                expected: 1,
2577                actual: 2,
2578            })
2579        );
2580    }
2581
2582    #[test]
2583    fn trace_validate_frame_index_gap_returns_typed_error() {
2584        let trace = SessionTrace {
2585            records: vec![
2586                TraceRecord::Header {
2587                    seed: 0,
2588                    cols: 80,
2589                    rows: 24,
2590                    profile: "modern".to_string(),
2591                },
2592                TraceRecord::Frame {
2593                    frame_idx: 1,
2594                    ts_ns: 0,
2595                    checksum: 0x1,
2596                    checksum_chain: 0x10,
2597                },
2598                TraceRecord::Summary {
2599                    total_frames: 1,
2600                    final_checksum_chain: 0x10,
2601                },
2602            ],
2603        };
2604        let result = trace.validate();
2605        assert_eq!(
2606            result,
2607            Err(TraceValidationError::FrameIndexMismatch {
2608                expected: 0,
2609                actual: 1,
2610            })
2611        );
2612    }
2613
2614    #[test]
2615    fn trace_validate_timestamp_regression_returns_typed_error() {
2616        let trace = SessionTrace {
2617            records: vec![
2618                TraceRecord::Header {
2619                    seed: 0,
2620                    cols: 80,
2621                    rows: 24,
2622                    profile: "modern".to_string(),
2623                },
2624                TraceRecord::Tick { ts_ns: 20 },
2625                TraceRecord::Tick { ts_ns: 10 },
2626                TraceRecord::Summary {
2627                    total_frames: 0,
2628                    final_checksum_chain: 0,
2629                },
2630            ],
2631        };
2632        let result = trace.validate();
2633        assert_eq!(
2634            result,
2635            Err(TraceValidationError::TimestampRegression {
2636                previous: 20,
2637                current: 10,
2638                record_index: 2,
2639            })
2640        );
2641    }
2642
2643    #[test]
2644    fn replay_validates_trace_before_execution() {
2645        let trace = SessionTrace {
2646            records: vec![TraceRecord::Header {
2647                seed: 0,
2648                cols: 80,
2649                rows: 24,
2650                profile: "modern".to_string(),
2651            }],
2652        };
2653        let result = replay(new_counter(0), &trace);
2654        assert_eq!(
2655            result,
2656            Err(ReplayError::InvalidTrace(
2657                TraceValidationError::MissingSummary
2658            ))
2659        );
2660    }
2661
2662    // ---- Determinism: same input → same trace ----
2663
2664    #[test]
2665    fn same_inputs_produce_same_trace_checksums() {
2666        fn record_session() -> SessionTrace {
2667            let mut rec = SessionRecorder::new(new_counter(0), 20, 1, 0);
2668            rec.init().unwrap();
2669
2670            rec.push_event(1_000_000, key_event('+'))
2671                .expect("key admission");
2672            rec.push_event(2_000_000, key_event('+'))
2673                .expect("key admission");
2674            rec.push_event(3_000_000, key_event('-'))
2675                .expect("key admission");
2676            rec.step().unwrap();
2677
2678            rec.push_event(16_000_000, key_event('+'))
2679                .expect("key admission");
2680            rec.step().unwrap();
2681
2682            rec.finish()
2683        }
2684
2685        let t1 = record_session();
2686        let t2 = record_session();
2687        let t3 = record_session();
2688
2689        // All traces should have identical frame checksums.
2690        let checksums = |t: &SessionTrace| -> Vec<u64> {
2691            t.records
2692                .iter()
2693                .filter_map(|r| match r {
2694                    TraceRecord::Frame { checksum, .. } => Some(*checksum),
2695                    _ => None,
2696                })
2697                .collect()
2698        };
2699
2700        assert_eq!(checksums(&t1), checksums(&t2));
2701        assert_eq!(checksums(&t2), checksums(&t3));
2702        assert_eq!(t1.final_checksum_chain(), t2.final_checksum_chain());
2703    }
2704
2705    // ---- Mouse, paste, and focus events ----
2706
2707    #[test]
2708    fn mouse_event_record_replay() {
2709        let mut rec = SessionRecorder::new(new_counter(0), 20, 1, 0);
2710        rec.init().unwrap();
2711
2712        let mouse = Event::Mouse(MouseEvent {
2713            kind: MouseEventKind::Down(MouseButton::Left),
2714            x: 5,
2715            y: 0,
2716            modifiers: Modifiers::empty(),
2717        });
2718        rec.push_event(1_000_000, mouse).expect("mouse admission");
2719        rec.step().unwrap();
2720
2721        let trace = rec.finish();
2722        let result = replay(new_counter(0), &trace).unwrap();
2723        assert!(result.ok());
2724    }
2725
2726    #[test]
2727    fn paste_event_record_replay() {
2728        let mut rec = SessionRecorder::new(new_counter(0), 20, 1, 0);
2729        rec.init().unwrap();
2730
2731        let paste = Event::Paste(PasteEvent::bracketed("hello"));
2732        rec.push_event(1_000_000, paste).expect("paste admission");
2733        rec.step().unwrap();
2734
2735        let trace = rec.finish();
2736        let result = replay(new_counter(0), &trace).unwrap();
2737        assert!(result.ok());
2738    }
2739
2740    #[test]
2741    fn focus_event_record_replay() {
2742        let mut rec = SessionRecorder::new(new_counter(0), 20, 1, 0);
2743        rec.init().unwrap();
2744
2745        rec.push_event(1_000_000, Event::Focus(true))
2746            .expect("focus admission");
2747        rec.push_event(2_000_000, Event::Focus(false))
2748            .expect("focus admission");
2749        rec.step().unwrap();
2750
2751        let trace = rec.finish();
2752        let result = replay(new_counter(0), &trace).unwrap();
2753        assert!(result.ok());
2754    }
2755
2756    #[test]
2757    fn ime_event_record_replay() {
2758        let mut rec = SessionRecorder::new(new_counter(0), 20, 1, 0);
2759        rec.init().unwrap();
2760
2761        rec.push_event(1_000_000, Event::Ime(ImeEvent::start()))
2762            .expect("IME start admission");
2763        rec.push_event(2_000_000, Event::Ime(ImeEvent::update("你")))
2764            .expect("IME update admission");
2765        rec.push_event(3_000_000, Event::Ime(ImeEvent::commit("你好")))
2766            .expect("IME commit admission");
2767        rec.step().unwrap();
2768
2769        let trace = rec.finish();
2770        let result = replay(new_counter(0), &trace).unwrap();
2771        assert!(result.ok());
2772    }
2773
2774    // ---- Checksum chain integrity ----
2775
2776    #[test]
2777    fn checksum_chain_is_cumulative() {
2778        let mut rec = SessionRecorder::new(new_counter(0), 20, 1, 0);
2779        rec.init().unwrap();
2780
2781        rec.push_event(1_000_000, key_event('+'))
2782            .expect("key admission");
2783        rec.step().unwrap();
2784
2785        rec.push_event(2_000_000, key_event('+'))
2786            .expect("key admission");
2787        rec.step().unwrap();
2788
2789        let trace = rec.finish();
2790        let frame_records: Vec<_> = trace
2791            .records
2792            .iter()
2793            .filter_map(|r| match r {
2794                TraceRecord::Frame {
2795                    checksum,
2796                    checksum_chain,
2797                    ..
2798                } => Some((*checksum, *checksum_chain)),
2799                _ => None,
2800            })
2801            .collect();
2802
2803        assert_eq!(frame_records.len(), 3);
2804
2805        // Verify chain: each chain = fnv1a64_pair(prev_chain, checksum).
2806        let (c0, chain0) = frame_records[0];
2807        assert_eq!(chain0, fnv1a64_pair(0, c0));
2808
2809        let (c1, chain1) = frame_records[1];
2810        assert_eq!(chain1, fnv1a64_pair(chain0, c1));
2811
2812        let (c2, chain2) = frame_records[2];
2813        assert_eq!(chain2, fnv1a64_pair(chain1, c2));
2814
2815        // Final chain in summary matches last frame chain.
2816        assert_eq!(trace.final_checksum_chain(), Some(chain2));
2817    }
2818
2819    // ---- Recorder program accessors ----
2820
2821    #[test]
2822    fn recorder_exposes_program() {
2823        let mut rec = SessionRecorder::new(new_counter(42), 20, 1, 0);
2824        rec.init().unwrap();
2825        assert_eq!(rec.program().model().value, 42);
2826    }
2827
2828    // ---- ReplayResult and ReplayError ----
2829
2830    #[test]
2831    fn replay_result_ok_when_no_mismatch() {
2832        let r = ReplayResult {
2833            total_steps: 5,
2834            running: true,
2835            unprocessed_events: Vec::new(),
2836            total_frames: 5,
2837            final_checksum_chain: 123,
2838            first_mismatch: None,
2839        };
2840        assert!(r.ok());
2841    }
2842
2843    #[test]
2844    fn replay_result_not_ok_when_mismatch() {
2845        let r = ReplayResult {
2846            total_steps: 5,
2847            running: true,
2848            unprocessed_events: Vec::new(),
2849            total_frames: 5,
2850            final_checksum_chain: 123,
2851            first_mismatch: Some(ReplayMismatch {
2852                frame_idx: 2,
2853                expected: 100,
2854                actual: 200,
2855            }),
2856        };
2857        assert!(!r.ok());
2858    }
2859
2860    #[test]
2861    fn replay_error_display() {
2862        assert_eq!(
2863            ReplayError::MissingHeader.to_string(),
2864            "trace missing header record"
2865        );
2866        let invalid = ReplayError::InvalidTrace(TraceValidationError::MissingSummary);
2867        assert_eq!(
2868            invalid.to_string(),
2869            "invalid trace: trace is missing summary"
2870        );
2871        let be = ReplayError::Backend(WebBackendError::Unsupported("test"));
2872        assert!(be.to_string().contains("test"));
2873    }
2874
2875    // ---- JSONL serialization ----
2876
2877    #[test]
2878    fn trace_record_header_to_jsonl() {
2879        let r = TraceRecord::Header {
2880            seed: 42,
2881            cols: 80,
2882            rows: 24,
2883            profile: "modern".to_string(),
2884        };
2885        let line = r.to_jsonl();
2886        assert!(line.contains("\"event\":\"trace_header\""));
2887        assert!(line.contains("\"schema_version\":\"golden-trace-v2\""));
2888        assert!(line.contains("\"seed\":42"));
2889        assert!(line.contains("\"cols\":80"));
2890        assert!(line.contains("\"rows\":24"));
2891        assert!(line.contains("\"profile\":\"modern\""));
2892    }
2893
2894    #[test]
2895    fn trace_record_input_key_to_jsonl() {
2896        let r = TraceRecord::Input {
2897            ts_ns: 1_000_000,
2898            event: key_event('+'),
2899        };
2900        let line = r.to_jsonl();
2901        assert!(line.contains("\"event\":\"input\""));
2902        assert!(line.contains("\"ts_ns\":1000000"));
2903        assert!(line.contains("\"kind\":\"key\""));
2904        assert!(line.contains("\"code\":\"char:+\""));
2905    }
2906
2907    #[test]
2908    fn trace_record_resize_to_jsonl() {
2909        let r = TraceRecord::Resize {
2910            ts_ns: 5_000_000,
2911            cols: 120,
2912            rows: 40,
2913        };
2914        let line = r.to_jsonl();
2915        assert!(line.contains("\"event\":\"resize\""));
2916        assert!(line.contains("\"cols\":120"));
2917        assert!(line.contains("\"rows\":40"));
2918    }
2919
2920    #[test]
2921    fn trace_record_frame_to_jsonl() {
2922        let r = TraceRecord::Frame {
2923            frame_idx: 3,
2924            ts_ns: 48_000_000,
2925            checksum: 0xDEADBEEF,
2926            checksum_chain: 0xCAFEBABE,
2927        };
2928        let line = r.to_jsonl();
2929        assert!(line.contains("\"event\":\"frame\""));
2930        assert!(line.contains("\"frame_idx\":3"));
2931        assert!(line.contains("\"frame_hash\":\"00000000deadbeef\""));
2932        assert!(line.contains("\"checksum_chain\":\"00000000cafebabe\""));
2933    }
2934
2935    #[test]
2936    fn trace_record_summary_to_jsonl() {
2937        let r = TraceRecord::Summary {
2938            total_frames: 10,
2939            final_checksum_chain: 0x1234567890ABCDEF,
2940        };
2941        let line = r.to_jsonl();
2942        assert!(line.contains("\"event\":\"trace_summary\""));
2943        assert!(line.contains("\"total_frames\":10"));
2944        assert!(line.contains("\"final_checksum_chain\":\"1234567890abcdef\""));
2945    }
2946
2947    // ---- JSONL round-trip ----
2948
2949    #[test]
2950    fn jsonl_round_trip_full_session() {
2951        // Record a session.
2952        let mut rec = SessionRecorder::new(new_counter(0), 20, 1, 42);
2953        rec.init().unwrap();
2954        rec.push_event(1_000_000, key_event('+'))
2955            .expect("key admission");
2956        rec.push_event(2_000_000, key_event('+'))
2957            .expect("key admission");
2958        rec.step().unwrap();
2959        let trace = rec.finish();
2960
2961        // Serialize to JSONL.
2962        let jsonl = trace.to_jsonl();
2963        assert!(!jsonl.is_empty());
2964
2965        // Deserialize back.
2966        let parsed = SessionTrace::from_jsonl(&jsonl).unwrap();
2967        assert_eq!(parsed.records.len(), trace.records.len());
2968        assert_eq!(parsed.frame_count(), trace.frame_count());
2969        assert_eq!(parsed.final_checksum_chain(), trace.final_checksum_chain());
2970    }
2971
2972    #[test]
2973    fn jsonl_round_trip_preserves_events() {
2974        let events = vec![
2975            key_event('+'),
2976            key_event('-'),
2977            Event::Key(KeyEvent {
2978                code: KeyCode::Enter,
2979                modifiers: Modifiers::CTRL | Modifiers::SHIFT,
2980                kind: KeyEventKind::Press,
2981            }),
2982            Event::Key(KeyEvent {
2983                code: KeyCode::F(12),
2984                modifiers: Modifiers::ALT,
2985                kind: KeyEventKind::Repeat,
2986            }),
2987            Event::Mouse(MouseEvent {
2988                kind: MouseEventKind::Down(MouseButton::Left),
2989                x: 10,
2990                y: 5,
2991                modifiers: Modifiers::empty(),
2992            }),
2993            Event::Mouse(MouseEvent {
2994                kind: MouseEventKind::ScrollDown,
2995                x: 0,
2996                y: 0,
2997                modifiers: Modifiers::CTRL,
2998            }),
2999            Event::Paste(PasteEvent::bracketed("hello world")),
3000            Event::Focus(true),
3001            Event::Focus(false),
3002            Event::Tick,
3003        ];
3004
3005        for (i, event) in events.iter().enumerate() {
3006            let record = TraceRecord::Input {
3007                ts_ns: i as u64 * 1_000_000,
3008                event: event.clone(),
3009            };
3010            let jsonl = record.to_jsonl();
3011            let parsed = SessionTrace::from_jsonl(&jsonl).unwrap();
3012            let parsed_record = &parsed.records[0];
3013            let TraceRecord::Input {
3014                event: parsed_event,
3015                ..
3016            } = parsed_record
3017            else {
3018                unreachable!("expected Input record for event {i}");
3019            };
3020
3021            assert_eq!(parsed_event, event, "event {i} round-trip failed: {jsonl}");
3022        }
3023    }
3024
3025    #[test]
3026    fn jsonl_round_trip_with_resize() {
3027        let mut rec = SessionRecorder::new(new_counter(0), 20, 1, 0);
3028        rec.init().unwrap();
3029        rec.resize(5_000_000, 40, 2).expect("resize admission");
3030        rec.step().unwrap();
3031        let trace = rec.finish();
3032
3033        let jsonl = trace.to_jsonl();
3034        let parsed = SessionTrace::from_jsonl(&jsonl).unwrap();
3035
3036        // Replay parsed trace.
3037        let result = replay(new_counter(0), &parsed).unwrap();
3038        assert!(
3039            result.ok(),
3040            "parsed trace replay failed: {:?}",
3041            result.first_mismatch
3042        );
3043    }
3044
3045    // ---- JSONL parsing errors ----
3046
3047    #[test]
3048    fn step_jsonl_preserves_clock_and_requires_all_outcome_fields() {
3049        let record = TraceRecord::Step {
3050            step_idx: 4,
3051            ts_ns: 9,
3052            init: false,
3053            clock: Duration::new(u64::MAX, 999_999_999),
3054            result: StepResult {
3055                running: false,
3056                rendered: false,
3057                events_processed: 3,
3058                events_pending: 2,
3059                frame_idx: 2,
3060            },
3061        };
3062        let json = record.to_jsonl();
3063        assert_eq!(
3064            SessionTrace::from_jsonl(&json).unwrap().records,
3065            vec![record]
3066        );
3067        for field in [
3068            "step_idx",
3069            "ts_ns",
3070            "init",
3071            "clock_secs",
3072            "clock_subsec_nanos",
3073            "running",
3074            "rendered",
3075            "events_processed",
3076            "events_pending",
3077            "frame_idx",
3078        ] {
3079            let changed = json.replace(&format!("\"{field}\":"), "\"unknown\":");
3080            assert!(
3081                SessionTrace::from_jsonl(&changed).is_err(),
3082                "missing {field}"
3083            );
3084        }
3085        for (old, new) in [
3086            (
3087                "\"clock_subsec_nanos\":999999999",
3088                "\"clock_subsec_nanos\":1000000000",
3089            ),
3090            ("\"events_pending\":2", "\"events_pending\":4294967296"),
3091            ("\"events_processed\":3", "\"events_processed\":-1"),
3092            ("\"running\":false", "\"running\":null"),
3093            ("\"running\":false", "\"running\":falseX"),
3094            ("\"events_pending\":2", "\"events_pending\":2.5"),
3095            ("\"events_pending\":2", "\"events_pending\":2e3"),
3096            ("\"events_pending\":2", "\"nested\":{\"events_pending\":2}"),
3097            (
3098                "\"events_pending\":2",
3099                "\"events_pending\":2,\"events_pending\":2",
3100            ),
3101        ] {
3102            assert!(
3103                SessionTrace::from_jsonl(&json.replace(old, new)).is_err(),
3104                "invalid {new}"
3105            );
3106        }
3107    }
3108
3109    #[test]
3110    fn v1_trace_cannot_invent_missing_execution_boundaries() {
3111        let line = r#"{"schema_version":"golden-trace-v1","event":"tick","ts_ns":0}"#;
3112        let error = SessionTrace::from_jsonl(line).unwrap_err();
3113        assert!(error.message.contains("migration required"));
3114    }
3115
3116    #[test]
3117    fn text_payloads_with_braces_quotes_and_unicode_round_trip_in_quit_tail() {
3118        let text = "} { \\\" 🦀/\n\t\0\u{0008}\u{000c}";
3119        let tail = vec![
3120            Event::Paste(PasteEvent::bracketed(text)),
3121            Event::Ime(ImeEvent::commit(text)),
3122            Event::Clipboard(ftui_core::event::ClipboardEvent {
3123                content: text.to_owned(),
3124                source: ClipboardSource::Osc52,
3125            }),
3126        ];
3127        let mut recorder = SessionRecorder::new(new_counter(0), 20, 2, 7);
3128        recorder.init().unwrap();
3129        recorder.push_event(0, key_event('q')).unwrap();
3130        for event in &tail {
3131            recorder.push_event(0, event.clone()).unwrap();
3132        }
3133        recorder.step().unwrap();
3134        let jsonl = recorder.finish().to_jsonl();
3135        let escaped = jsonl
3136            .replace('🦀', r"\ud83e\udd80")
3137            .replace('/', r"\/")
3138            .replace(r"\u0008", r"\b")
3139            .replace(r"\u000c", r"\f");
3140        for input in [&jsonl, &escaped] {
3141            let trace = SessionTrace::from_jsonl_validated(input).unwrap();
3142            assert_eq!(
3143                replay(new_counter(0), &trace).unwrap().unprocessed_events,
3144                tail
3145            );
3146        }
3147    }
3148
3149    #[test]
3150    fn malformed_text_escapes_are_rejected_without_changing_content() {
3151        for text in [r"\uZZZZ", r"\ud83e", r"\udd80", r"\ud83e\u0061", r"\q"] {
3152            let line = format!(
3153                r#"{{"schema_version":"{}","event":"input","ts_ns":0,"data":{{"kind":"paste","text":"{}"}}}}"#,
3154                SCHEMA_VERSION, text
3155            );
3156            assert!(SessionTrace::from_jsonl(&line).is_err(), "invalid {text}");
3157        }
3158    }
3159
3160    #[test]
3161    fn chain_only_corruption_cannot_pass_replay_or_gate() {
3162        let mut recorder = SessionRecorder::new(new_counter(0), 20, 2, 7);
3163        recorder.init().unwrap();
3164        let mut trace = recorder.finish();
3165        for record in &mut trace.records {
3166            match record {
3167                TraceRecord::Frame { checksum_chain, .. } => *checksum_chain ^= 1,
3168                TraceRecord::Summary {
3169                    final_checksum_chain,
3170                    ..
3171                } => *final_checksum_chain ^= 1,
3172                _ => {}
3173            }
3174        }
3175        assert!(trace.validate().is_err());
3176        assert!(replay(new_counter(0), &trace).is_err());
3177        assert!(gate_trace(new_counter(0), &trace).is_err());
3178    }
3179
3180    #[test]
3181    fn from_jsonl_empty_is_ok() {
3182        let trace = SessionTrace::from_jsonl("").unwrap();
3183        assert!(trace.records.is_empty());
3184    }
3185
3186    #[test]
3187    fn from_jsonl_unknown_event_fails() {
3188        let line = r#"{"schema_version":"golden-trace-v2","event":"unknown_type","ts_ns":0}"#;
3189        let result = SessionTrace::from_jsonl(line);
3190        assert!(result.is_err());
3191        assert!(result.unwrap_err().message.contains("unknown event type"));
3192    }
3193
3194    #[test]
3195    fn from_jsonl_missing_event_field_fails() {
3196        let line = r#"{"schema_version":"golden-trace-v2","ts_ns":0}"#;
3197        let result = SessionTrace::from_jsonl(line);
3198        assert!(result.is_err());
3199    }
3200
3201    #[test]
3202    fn from_jsonl_missing_schema_version_fails() {
3203        let line = r#"{"event":"tick","ts_ns":0}"#;
3204        let result = SessionTrace::from_jsonl(line);
3205        assert!(result.is_err());
3206        assert!(result.unwrap_err().message.contains("schema_version"));
3207    }
3208
3209    #[test]
3210    fn from_jsonl_schema_matrix_current_writer_version_passes() {
3211        let line = format!(
3212            r#"{{"schema_version":"{}","event":"tick","ts_ns":0}}"#,
3213            SCHEMA_VERSION
3214        );
3215        let trace = SessionTrace::from_jsonl(&line).expect("matching schema should parse");
3216        assert_eq!(trace.records, vec![TraceRecord::Tick { ts_ns: 0 }]);
3217    }
3218
3219    #[test]
3220    fn from_jsonl_schema_matrix_newer_writer_version_fails_with_migration_error() {
3221        let line = r#"{"schema_version":"golden-trace-v3","event":"tick","ts_ns":0}"#;
3222        let result = SessionTrace::from_jsonl(line);
3223        assert!(result.is_err());
3224        let message = result.unwrap_err().message;
3225        assert!(message.contains("unsupported schema_version"));
3226        assert!(message.contains("migration required"));
3227    }
3228
3229    #[cfg(feature = "tracing")]
3230    #[test]
3231    fn schema_incompatibility_emits_compat_span_and_error_log() {
3232        let capture = TraceCaptureLayer::default();
3233        let subscriber =
3234            tracing_subscriber::registry().with(capture.clone().with_filter(LevelFilter::TRACE));
3235        let _guard = tracing::subscriber::set_default(subscriber);
3236
3237        let line = r#"{"schema_version":"golden-trace-v3","event":"tick","ts_ns":0}"#;
3238        let err = SessionTrace::from_jsonl(line).expect_err("newer schema should fail");
3239        assert!(err.message.contains("migration required"));
3240
3241        let spans = capture.spans.lock().expect("span capture lock");
3242        assert!(
3243            spans.iter().any(|name| name == "trace.compat_check"),
3244            "expected trace.compat_check span, got {spans:?}"
3245        );
3246        drop(spans);
3247
3248        let events = capture.events.lock().expect("event capture lock");
3249        assert!(
3250            events
3251                .iter()
3252                .any(|event| event.contains("ERROR:trace schema version incompatible")),
3253            "expected incompatible schema ERROR log, got {events:?}"
3254        );
3255    }
3256
3257    #[test]
3258    fn from_jsonl_validated_surfaces_validation_error_type() {
3259        let jsonl = TraceRecord::Header {
3260            seed: 0,
3261            cols: 80,
3262            rows: 24,
3263            profile: "modern".to_string(),
3264        }
3265        .to_jsonl();
3266        let result = SessionTrace::from_jsonl_validated(&jsonl);
3267        assert!(matches!(
3268            result,
3269            Err(TraceLoadError::Validation(
3270                TraceValidationError::MissingSummary
3271            ))
3272        ));
3273    }
3274
3275    // ---- JSON helpers ----
3276
3277    #[test]
3278    fn json_escape_round_trip() {
3279        let cases = [
3280            "hello",
3281            "with\"quotes",
3282            "back\\slash",
3283            "line\nbreak",
3284            "tab\there",
3285        ];
3286        for input in cases {
3287            let escaped = json_escape(input);
3288            let unescaped = json_unescape(&escaped).unwrap();
3289            assert_eq!(unescaped, input, "round-trip failed for: {input:?}");
3290        }
3291    }
3292
3293    #[test]
3294    fn extract_str_basic() {
3295        let json = r#"{"name":"alice","age":30}"#;
3296        assert_eq!(extract_str(json, "name"), Some("alice"));
3297    }
3298
3299    #[test]
3300    fn extract_u64_basic() {
3301        let json = r#"{"count":42,"name":"test"}"#;
3302        assert_eq!(extract_u64(json, "count"), Some(42));
3303    }
3304
3305    #[test]
3306    fn extract_i64_basic() {
3307        let json = r#"{"dx":-12,"dy":7}"#;
3308        assert_eq!(extract_i64(json, "dx"), Some(-12));
3309        assert_eq!(extract_i64(json, "dy"), Some(7));
3310    }
3311
3312    #[test]
3313    fn extract_bool_basic() {
3314        let json = r#"{"enabled":true,"disabled":false}"#;
3315        assert_eq!(extract_bool(json, "enabled"), Some(true));
3316        assert_eq!(extract_bool(json, "disabled"), Some(false));
3317    }
3318
3319    #[test]
3320    fn extract_hex_u64_basic() {
3321        let json = r#"{"hash":"00000000deadbeef"}"#;
3322        assert_eq!(extract_hex_u64(json, "hash"), Some(0xDEADBEEF));
3323    }
3324
3325    #[test]
3326    fn from_jsonl_parses_frankenterm_key_schema() {
3327        let down = parse_single_input_event(
3328            r#"{"kind":"key","phase":"down","code":"F12","mods":5,"repeat":false}"#,
3329        );
3330        assert_eq!(
3331            down,
3332            Event::Key(KeyEvent {
3333                code: KeyCode::F(12),
3334                modifiers: Modifiers::SHIFT | Modifiers::CTRL,
3335                kind: KeyEventKind::Press,
3336            })
3337        );
3338
3339        let repeat = parse_single_input_event(
3340            r#"{"kind":"key","phase":"down","code":"a","mods":0,"repeat":true}"#,
3341        );
3342        assert_eq!(
3343            repeat,
3344            Event::Key(KeyEvent {
3345                code: KeyCode::Char('a'),
3346                modifiers: Modifiers::empty(),
3347                kind: KeyEventKind::Repeat,
3348            })
3349        );
3350
3351        let release = parse_single_input_event(
3352            r#"{"kind":"key","phase":"up","code":"Enter","mods":0,"repeat":false}"#,
3353        );
3354        assert_eq!(
3355            release,
3356            Event::Key(KeyEvent {
3357                code: KeyCode::Enter,
3358                modifiers: Modifiers::empty(),
3359                kind: KeyEventKind::Release,
3360            })
3361        );
3362    }
3363
3364    #[test]
3365    fn key_event_json_round_trip_unescapes_code() {
3366        let quote_key = Event::Key(KeyEvent {
3367            code: KeyCode::Char('"'),
3368            modifiers: Modifiers::empty(),
3369            kind: KeyEventKind::Press,
3370        });
3371        let quote_json = event_to_json(&quote_key);
3372        let parsed_quote = parse_event_json(&quote_json).expect("quote key should parse");
3373        assert_eq!(parsed_quote, quote_key);
3374
3375        let slash_key = Event::Key(KeyEvent {
3376            code: KeyCode::Char('\\'),
3377            modifiers: Modifiers::SHIFT,
3378            kind: KeyEventKind::Press,
3379        });
3380        let slash_json = event_to_json(&slash_key);
3381        let parsed_slash = parse_event_json(&slash_json).expect("slash key should parse");
3382        assert_eq!(parsed_slash, slash_key);
3383    }
3384
3385    #[test]
3386    fn from_jsonl_parses_frankenterm_mouse_and_wheel_schema() {
3387        let mouse = parse_single_input_event(
3388            r#"{"kind":"mouse","phase":"drag","button":2,"x":7,"y":9,"mods":3}"#,
3389        );
3390        assert_eq!(
3391            mouse,
3392            Event::Mouse(MouseEvent {
3393                kind: MouseEventKind::Drag(MouseButton::Right),
3394                x: 7,
3395                y: 9,
3396                modifiers: Modifiers::SHIFT | Modifiers::ALT,
3397            })
3398        );
3399
3400        let wheel =
3401            parse_single_input_event(r#"{"kind":"wheel","x":4,"y":6,"dx":0,"dy":-2,"mods":4}"#);
3402        assert_eq!(
3403            wheel,
3404            Event::Mouse(MouseEvent {
3405                kind: MouseEventKind::ScrollUp,
3406                x: 4,
3407                y: 6,
3408                modifiers: Modifiers::CTRL,
3409            })
3410        );
3411    }
3412
3413    #[test]
3414    fn from_jsonl_parses_frankenterm_paste_focus_and_composition_aliases() {
3415        let paste = parse_single_input_event(r#"{"kind":"paste","data":"hello\nworld"}"#);
3416        assert_eq!(paste, Event::Paste(PasteEvent::new("hello\nworld", true)));
3417
3418        let focus = parse_single_input_event(r#"{"kind":"focus","focused":false}"#);
3419        assert_eq!(focus, Event::Focus(false));
3420
3421        let composition_update =
3422            parse_single_input_event(r#"{"kind":"composition","phase":"update","data":"你"}"#);
3423        assert_eq!(
3424            composition_update,
3425            Event::Ime(ImeEvent::new(ImePhase::Update, "你"))
3426        );
3427
3428        let composition_end =
3429            parse_single_input_event(r#"{"kind":"composition","phase":"end","data":"你好"}"#);
3430        assert_eq!(
3431            composition_end,
3432            Event::Ime(ImeEvent::new(ImePhase::Commit, "你好"))
3433        );
3434    }
3435
3436    // ---- Golden Gate API ----
3437
3438    #[test]
3439    fn gate_trace_passes_on_correct_replay() {
3440        let mut rec = SessionRecorder::new(new_counter(0), 20, 1, 0);
3441        rec.init().unwrap();
3442        rec.push_event(1_000_000, key_event('+'))
3443            .expect("key admission");
3444        rec.step().unwrap();
3445        let trace = rec.finish();
3446
3447        let report = gate_trace(new_counter(0), &trace).unwrap();
3448        assert!(report.passed);
3449        assert_eq!(report.total_frames, 2);
3450        assert!(report.diff.is_none());
3451        assert!(report.format().starts_with("PASS"));
3452    }
3453
3454    #[test]
3455    fn gate_trace_fails_with_actionable_diff() {
3456        let mut rec = SessionRecorder::new(new_counter(0), 20, 1, 0);
3457        rec.init().unwrap();
3458        rec.push_event(1_000_000, key_event('+'))
3459            .expect("key admission");
3460        rec.push_event(2_000_000, key_event('+'))
3461            .expect("key admission");
3462        rec.step().unwrap();
3463        let trace = rec.finish();
3464
3465        // Replay with different initial state.
3466        let report = gate_trace(new_counter(5), &trace).unwrap();
3467        assert!(!report.passed);
3468        assert!(report.diff.is_some());
3469
3470        let diff = report.diff.as_ref().unwrap();
3471        assert_eq!(diff.frame_idx, 0); // First frame mismatch (init).
3472
3473        let formatted = report.format();
3474        assert!(formatted.starts_with("FAIL"));
3475        assert!(formatted.contains("frame 0"));
3476    }
3477
3478    #[test]
3479    fn gate_trace_diff_has_event_context() {
3480        let mut rec = SessionRecorder::new(new_counter(0), 20, 1, 0);
3481        rec.init().unwrap();
3482        rec.push_event(1_000_000, key_event('+'))
3483            .expect("key admission");
3484        rec.push_event(2_000_000, key_event('+'))
3485            .expect("key admission");
3486        rec.step().unwrap();
3487        rec.push_event(3_000_000, key_event('-'))
3488            .expect("key admission");
3489        rec.step().unwrap();
3490        let trace = rec.finish();
3491
3492        // Tamper with the trace: change a frame checksum.
3493        let mut tampered = trace.clone();
3494        let mut chain = 0;
3495        for record in &mut tampered.records {
3496            match record {
3497                TraceRecord::Frame {
3498                    frame_idx,
3499                    checksum,
3500                    checksum_chain,
3501                    ..
3502                } => {
3503                    if *frame_idx == 2 {
3504                        *checksum = 0xBAD;
3505                    }
3506                    chain = fnv1a64_pair(chain, *checksum);
3507                    *checksum_chain = chain;
3508                }
3509                TraceRecord::Summary {
3510                    final_checksum_chain,
3511                    ..
3512                } => *final_checksum_chain = chain,
3513                _ => {}
3514            }
3515        }
3516        // Preserve structural integrity so this still tests an actual model
3517        // checksum mismatch, independently of the malformed-chain rejection.
3518        tampered.validate().unwrap();
3519
3520        let report = gate_trace(new_counter(0), &tampered).unwrap();
3521        assert!(!report.passed);
3522        let diff = report.diff.unwrap();
3523        assert_eq!(diff.frame_idx, 2);
3524        assert!(diff.event_idx > 0); // Events were processed before frame 2.
3525    }
3526
3527    // ---- JSONL → replay integration ----
3528
3529    #[test]
3530    fn jsonl_serialize_parse_replay_round_trip() {
3531        // Full pipeline: record → JSONL → parse → replay → verify.
3532        let mut rec = SessionRecorder::new(new_counter(0), 20, 1, 0);
3533        rec.init().unwrap();
3534
3535        for i in 0..3 {
3536            rec.push_event(i * 16_000_000, key_event('+'))
3537                .expect("key admission");
3538            rec.step().unwrap();
3539        }
3540        let original_trace = rec.finish();
3541
3542        // Serialize.
3543        let jsonl = original_trace.to_jsonl();
3544
3545        // Parse.
3546        let parsed_trace = SessionTrace::from_jsonl(&jsonl).unwrap();
3547
3548        // Replay parsed trace.
3549        let result = replay(new_counter(0), &parsed_trace).unwrap();
3550        assert!(
3551            result.ok(),
3552            "JSONL round-trip replay failed: {:?}",
3553            result.first_mismatch
3554        );
3555        assert_eq!(result.total_frames, original_trace.frame_count());
3556        assert_eq!(
3557            result.final_checksum_chain,
3558            original_trace.final_checksum_chain().unwrap()
3559        );
3560    }
3561
3562    // ---- TraceParseError ----
3563
3564    #[test]
3565    fn trace_parse_error_display() {
3566        let e = TraceParseError {
3567            line: 5,
3568            message: "bad field".to_string(),
3569        };
3570        assert_eq!(e.to_string(), "line 5: bad field");
3571    }
3572}