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::TerminalResponse(_) | 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                pixel: None,
1490                modifiers,
1491            }))
1492        }
1493        "wheel" => {
1494            let x = extract_u16(data, "x").unwrap_or(0);
1495            let y = extract_u16(data, "y").unwrap_or(0);
1496            let dx = extract_i64(data, "dx")
1497                .and_then(|value| i16::try_from(value).ok())
1498                .unwrap_or(0);
1499            let dy = extract_i64(data, "dy")
1500                .and_then(|value| i16::try_from(value).ok())
1501                .unwrap_or(0);
1502            let kind = if dy < 0 {
1503                MouseEventKind::ScrollUp
1504            } else if dy > 0 {
1505                MouseEventKind::ScrollDown
1506            } else if dx < 0 {
1507                MouseEventKind::ScrollLeft
1508            } else if dx > 0 {
1509                MouseEventKind::ScrollRight
1510            } else {
1511                return Err("wheel event must include non-zero dx or dy".to_string());
1512            };
1513            let mods_bits = extract_u64(data, "modifiers")
1514                .or(extract_u64(data, "mods"))
1515                .unwrap_or(0) as u8;
1516            let modifiers = Modifiers::from_bits(mods_bits).unwrap_or_else(Modifiers::empty);
1517            Ok(Event::Mouse(MouseEvent {
1518                kind,
1519                x,
1520                y,
1521                pixel: None,
1522                modifiers,
1523            }))
1524        }
1525        "resize" => {
1526            let width = extract_u16(data, "width").ok_or("missing width")?;
1527            let height = extract_u16(data, "height").ok_or("missing height")?;
1528            Ok(Event::Resize { width, height })
1529        }
1530        "paste" => {
1531            let text = extract_str(data, "text")
1532                .or(extract_str(data, "data"))
1533                .map(json_unescape)
1534                .transpose()?
1535                .unwrap_or_default();
1536            let bracketed = extract_bool(data, "bracketed").unwrap_or(true);
1537            Ok(Event::Paste(PasteEvent::new(text, bracketed)))
1538        }
1539        "ime" | "composition" => {
1540            let phase_raw = extract_str(data, "phase").unwrap_or("update");
1541            let phase = parse_ime_phase(phase_raw)?;
1542            let text = extract_str(data, "text")
1543                .or(extract_str(data, "data"))
1544                .map(json_unescape)
1545                .transpose()?
1546                .unwrap_or_default();
1547            let ime = match phase {
1548                ImePhase::Start => ImeEvent::start(),
1549                ImePhase::Update => ImeEvent::update(text),
1550                ImePhase::Commit => ImeEvent::commit(text),
1551                ImePhase::Cancel => ImeEvent::cancel(),
1552            };
1553            Ok(Event::Ime(ime))
1554        }
1555        "focus" => {
1556            let gained = extract_bool(data, "gained")
1557                .or(extract_bool(data, "focused"))
1558                .unwrap_or(true);
1559            Ok(Event::Focus(gained))
1560        }
1561        "clipboard" => {
1562            let content = extract_str(data, "content")
1563                .map(json_unescape)
1564                .transpose()?
1565                .unwrap_or_default();
1566            let source_str = extract_str(data, "source").unwrap_or("unknown");
1567            let source = match source_str {
1568                "osc52" => ClipboardSource::Osc52,
1569                _ => ClipboardSource::Unknown,
1570            };
1571            Ok(Event::Clipboard(ClipboardEvent::new(content, source)))
1572        }
1573        "tick" => Ok(Event::Tick),
1574        other => Err(format!("unknown event kind: {other}")),
1575    }
1576}
1577
1578fn parse_ime_phase(phase: &str) -> Result<ImePhase, String> {
1579    match phase {
1580        "start" => Ok(ImePhase::Start),
1581        "update" => Ok(ImePhase::Update),
1582        "end" | "commit" => Ok(ImePhase::Commit),
1583        "cancel" => Ok(ImePhase::Cancel),
1584        other => Err(format!("unknown ime/composition phase: {other}")),
1585    }
1586}
1587
1588fn parse_key_code(s: &str) -> Result<KeyCode, String> {
1589    if let Some(rest) = s.strip_prefix("char:") {
1590        let ch = rest.chars().next().ok_or("empty char code")?;
1591        return Ok(KeyCode::Char(ch));
1592    }
1593    if let Some(rest) = s.strip_prefix("f:") {
1594        let n: u8 = rest.parse().map_err(|_| "invalid F-key number")?;
1595        return Ok(KeyCode::F(n));
1596    }
1597    if let Some(n) = parse_function_key_token(s) {
1598        return Ok(KeyCode::F(n));
1599    }
1600
1601    let mut chars = s.chars();
1602    if let Some(ch) = chars.next()
1603        && chars.next().is_none()
1604    {
1605        return Ok(KeyCode::Char(ch));
1606    }
1607
1608    let normalized = s.to_ascii_lowercase();
1609    match normalized.as_str() {
1610        "enter" | "return" => Ok(KeyCode::Enter),
1611        "escape" | "esc" => Ok(KeyCode::Escape),
1612        "backspace" => Ok(KeyCode::Backspace),
1613        "tab" => Ok(KeyCode::Tab),
1614        "backtab" => Ok(KeyCode::BackTab),
1615        "delete" => Ok(KeyCode::Delete),
1616        "insert" => Ok(KeyCode::Insert),
1617        "home" => Ok(KeyCode::Home),
1618        "end" => Ok(KeyCode::End),
1619        "pageup" => Ok(KeyCode::PageUp),
1620        "pagedown" => Ok(KeyCode::PageDown),
1621        "up" | "arrowup" => Ok(KeyCode::Up),
1622        "down" | "arrowdown" => Ok(KeyCode::Down),
1623        "left" | "arrowleft" => Ok(KeyCode::Left),
1624        "right" | "arrowright" => Ok(KeyCode::Right),
1625        "null" | "unidentified" => Ok(KeyCode::Null),
1626        "media_play_pause" => Ok(KeyCode::MediaPlayPause),
1627        "media_stop" => Ok(KeyCode::MediaStop),
1628        "media_next" => Ok(KeyCode::MediaNextTrack),
1629        "media_prev" => Ok(KeyCode::MediaPrevTrack),
1630        other => Err(format!("unknown key code: {other}")),
1631    }
1632}
1633
1634fn parse_function_key_token(s: &str) -> Option<u8> {
1635    let rest = s.strip_prefix('F').or_else(|| s.strip_prefix('f'))?;
1636    if rest.is_empty() || !rest.chars().all(|ch| ch.is_ascii_digit()) {
1637        return None;
1638    }
1639    rest.parse().ok()
1640}
1641
1642fn parse_key_event_kind(phase: &str, repeat: bool) -> KeyEventKind {
1643    if phase.eq_ignore_ascii_case("up") || phase.eq_ignore_ascii_case("release") {
1644        KeyEventKind::Release
1645    } else if repeat {
1646        KeyEventKind::Repeat
1647    } else {
1648        KeyEventKind::Press
1649    }
1650}
1651
1652fn parse_mouse_event_kind(s: &str) -> Result<MouseEventKind, String> {
1653    match s {
1654        "down_left" => Ok(MouseEventKind::Down(MouseButton::Left)),
1655        "down_right" => Ok(MouseEventKind::Down(MouseButton::Right)),
1656        "down_middle" => Ok(MouseEventKind::Down(MouseButton::Middle)),
1657        "up_left" => Ok(MouseEventKind::Up(MouseButton::Left)),
1658        "up_right" => Ok(MouseEventKind::Up(MouseButton::Right)),
1659        "up_middle" => Ok(MouseEventKind::Up(MouseButton::Middle)),
1660        "drag_left" => Ok(MouseEventKind::Drag(MouseButton::Left)),
1661        "drag_right" => Ok(MouseEventKind::Drag(MouseButton::Right)),
1662        "drag_middle" => Ok(MouseEventKind::Drag(MouseButton::Middle)),
1663        "moved" => Ok(MouseEventKind::Moved),
1664        "scroll_up" => Ok(MouseEventKind::ScrollUp),
1665        "scroll_down" => Ok(MouseEventKind::ScrollDown),
1666        "scroll_left" => Ok(MouseEventKind::ScrollLeft),
1667        "scroll_right" => Ok(MouseEventKind::ScrollRight),
1668        other => Err(format!("unknown mouse event kind: {other}")),
1669    }
1670}
1671
1672fn parse_mouse_phase_and_button(phase: &str, button: Option<u8>) -> Result<MouseEventKind, String> {
1673    match phase {
1674        "down" => Ok(MouseEventKind::Down(parse_mouse_button(
1675            button.ok_or("mouse down requires button")?,
1676        )?)),
1677        "up" => Ok(MouseEventKind::Up(parse_mouse_button(
1678            button.ok_or("mouse up requires button")?,
1679        )?)),
1680        "drag" => Ok(MouseEventKind::Drag(parse_mouse_button(
1681            button.ok_or("mouse drag requires button")?,
1682        )?)),
1683        "move" => Ok(MouseEventKind::Moved),
1684        other => Err(format!("unknown mouse phase: {other}")),
1685    }
1686}
1687
1688fn parse_mouse_button(raw: u8) -> Result<MouseButton, String> {
1689    match raw {
1690        0 => Ok(MouseButton::Left),
1691        1 => Ok(MouseButton::Middle),
1692        2 => Ok(MouseButton::Right),
1693        other => Err(format!("unsupported mouse button: {other}")),
1694    }
1695}
1696
1697// ---- Golden Gate API ----
1698
1699/// Validate a trace against a fresh model, returning a detailed report.
1700///
1701/// This is the primary entry point for CI checksum gates. It replays the
1702/// trace and produces a [`GateReport`] with pass/fail status and actionable
1703/// diff information on any mismatch.
1704pub fn gate_trace<M: ftui_runtime::program::Model>(
1705    model: M,
1706    trace: &SessionTrace,
1707) -> Result<GateReport, ReplayError> {
1708    let result = replay(model, trace)?;
1709
1710    let frame_checksums: Vec<(u64, u64)> = trace
1711        .records
1712        .iter()
1713        .filter_map(|r| match r {
1714            TraceRecord::Frame {
1715                frame_idx,
1716                checksum,
1717                ..
1718            } => Some((*frame_idx, *checksum)),
1719            _ => None,
1720        })
1721        .collect();
1722
1723    let diff = result.first_mismatch.as_ref().map(|m| {
1724        // Find the event context: count Input/Resize/Tick records before the failing frame.
1725        let mut event_idx: u64 = 0;
1726        let mut last_event_desc = String::new();
1727        let mut frame_count: u64 = 0;
1728        for record in &trace.records {
1729            match record {
1730                TraceRecord::Frame { .. } => {
1731                    if frame_count == m.frame_idx {
1732                        break;
1733                    }
1734                    frame_count += 1;
1735                }
1736                TraceRecord::Input { event, .. } => {
1737                    last_event_desc = format!("{event:?}");
1738                    event_idx += 1;
1739                }
1740                TraceRecord::Resize { cols, rows, .. } => {
1741                    last_event_desc = format!("Resize({cols}x{rows})");
1742                    event_idx += 1;
1743                }
1744                TraceRecord::Tick { ts_ns } => {
1745                    last_event_desc = format!("Tick(ts_ns={ts_ns})");
1746                    event_idx += 1;
1747                }
1748                _ => {}
1749            }
1750        }
1751
1752        GateDiff {
1753            frame_idx: m.frame_idx,
1754            event_idx,
1755            last_event: last_event_desc,
1756            expected_checksum: m.expected,
1757            actual_checksum: m.actual,
1758        }
1759    });
1760
1761    Ok(GateReport {
1762        passed: result.ok(),
1763        total_steps: result.total_steps,
1764        running: result.running,
1765        unprocessed_events: result.unprocessed_events,
1766        total_frames: result.total_frames,
1767        expected_frames: frame_checksums.len() as u64,
1768        final_checksum_chain: result.final_checksum_chain,
1769        diff,
1770    })
1771}
1772
1773/// Report from a golden trace gate validation.
1774#[derive(Debug, Clone)]
1775pub struct GateReport {
1776    /// Whether all execution outcomes and frame checksums matched.
1777    pub passed: bool,
1778    /// Number of execution boundaries replayed, including initialization.
1779    pub total_steps: u64,
1780    /// Whether the replayed program is still running.
1781    pub running: bool,
1782    /// Accepted input left unprocessed after quit, preserved in FIFO order.
1783    pub unprocessed_events: Vec<Event>,
1784    /// Number of frames replayed.
1785    pub total_frames: u64,
1786    /// Number of frame checkpoints in the trace.
1787    pub expected_frames: u64,
1788    /// Final checksum chain from replay.
1789    pub final_checksum_chain: u64,
1790    /// Detailed diff information if there was a mismatch.
1791    pub diff: Option<GateDiff>,
1792}
1793
1794impl GateReport {
1795    /// Format the report as a human-readable string.
1796    pub fn format(&self) -> String {
1797        if self.passed {
1798            format!(
1799                "PASS: {}/{} frames verified, final_chain={:016x}, steps={}, running={}, unprocessed_events={}",
1800                self.total_frames,
1801                self.expected_frames,
1802                self.final_checksum_chain,
1803                self.total_steps,
1804                self.running,
1805                self.unprocessed_events.len()
1806            )
1807        } else if let Some(d) = &self.diff {
1808            format!(
1809                "FAIL at frame {} (after event #{}: {}): expected {:016x}, got {:016x}",
1810                d.frame_idx, d.event_idx, d.last_event, d.expected_checksum, d.actual_checksum
1811            )
1812        } else {
1813            format!(
1814                "FAIL: {}/{} frames, unknown mismatch",
1815                self.total_frames, self.expected_frames
1816            )
1817        }
1818    }
1819}
1820
1821/// Detailed diff information for a checksum mismatch.
1822#[derive(Debug, Clone)]
1823pub struct GateDiff {
1824    /// Frame index where the mismatch occurred.
1825    pub frame_idx: u64,
1826    /// Number of input events processed before the failing frame.
1827    pub event_idx: u64,
1828    /// Description of the last event before the failing frame.
1829    pub last_event: String,
1830    /// Expected checksum from the trace.
1831    pub expected_checksum: u64,
1832    /// Actual checksum from replay.
1833    pub actual_checksum: u64,
1834}
1835
1836#[cfg(test)]
1837mod tests {
1838    use super::*;
1839    use ftui_core::event::{
1840        KeyCode, KeyEvent, KeyEventKind, Modifiers, MouseButton, MouseEvent, MouseEventKind,
1841        PasteEvent,
1842    };
1843    use ftui_render::cell::Cell;
1844    use ftui_render::frame::Frame;
1845    use ftui_runtime::program::{Cmd, Model};
1846    use pretty_assertions::assert_eq;
1847    #[cfg(feature = "tracing")]
1848    use std::sync::{Arc, Mutex};
1849    #[cfg(feature = "tracing")]
1850    use tracing::Subscriber;
1851    #[cfg(feature = "tracing")]
1852    use tracing::field::{Field, Visit};
1853    #[cfg(feature = "tracing")]
1854    use tracing_subscriber::Layer;
1855    #[cfg(feature = "tracing")]
1856    use tracing_subscriber::filter::LevelFilter;
1857    #[cfg(feature = "tracing")]
1858    use tracing_subscriber::layer::{Context, SubscriberExt};
1859    #[cfg(feature = "tracing")]
1860    use tracing_subscriber::registry::LookupSpan;
1861
1862    #[cfg(feature = "tracing")]
1863    #[derive(Default, Clone)]
1864    struct TraceCaptureLayer {
1865        spans: Arc<Mutex<Vec<String>>>,
1866        events: Arc<Mutex<Vec<String>>>,
1867    }
1868
1869    #[cfg(feature = "tracing")]
1870    #[derive(Default)]
1871    struct EventMessageVisitor {
1872        message: Option<String>,
1873    }
1874
1875    #[cfg(feature = "tracing")]
1876    impl Visit for EventMessageVisitor {
1877        fn record_str(&mut self, field: &Field, value: &str) {
1878            if field.name() == "message" {
1879                self.message = Some(value.to_string());
1880            }
1881        }
1882
1883        fn record_debug(&mut self, field: &Field, value: &dyn std::fmt::Debug) {
1884            if field.name() == "message" {
1885                self.message = Some(format!("{value:?}"));
1886            }
1887        }
1888    }
1889
1890    #[cfg(feature = "tracing")]
1891    impl<S> Layer<S> for TraceCaptureLayer
1892    where
1893        S: Subscriber + for<'lookup> LookupSpan<'lookup>,
1894    {
1895        fn on_new_span(
1896            &self,
1897            attrs: &tracing::span::Attributes<'_>,
1898            _id: &tracing::span::Id,
1899            _ctx: Context<'_, S>,
1900        ) {
1901            self.spans
1902                .lock()
1903                .expect("span capture lock")
1904                .push(attrs.metadata().name().to_string());
1905        }
1906
1907        fn on_event(&self, event: &tracing::Event<'_>, _ctx: Context<'_, S>) {
1908            let mut visitor = EventMessageVisitor::default();
1909            event.record(&mut visitor);
1910            let message = visitor.message.unwrap_or_default();
1911            self.events
1912                .lock()
1913                .expect("event capture lock")
1914                .push(format!("{}:{}", event.metadata().level(), message));
1915        }
1916    }
1917
1918    // ---- Test model (same as step_program tests) ----
1919
1920    struct Counter {
1921        value: i32,
1922    }
1923
1924    #[derive(Debug)]
1925    enum CounterMsg {
1926        Increment,
1927        Decrement,
1928        Reset,
1929        Quit,
1930    }
1931
1932    impl From<Event> for CounterMsg {
1933        fn from(event: Event) -> Self {
1934            match event {
1935                Event::Key(k) if k.code == KeyCode::Char('+') => CounterMsg::Increment,
1936                Event::Key(k) if k.code == KeyCode::Char('-') => CounterMsg::Decrement,
1937                Event::Key(k) if k.code == KeyCode::Char('r') => CounterMsg::Reset,
1938                Event::Key(k) if k.code == KeyCode::Char('q') => CounterMsg::Quit,
1939                Event::Tick => CounterMsg::Increment,
1940                _ => CounterMsg::Increment,
1941            }
1942        }
1943    }
1944
1945    impl Model for Counter {
1946        type Message = CounterMsg;
1947
1948        fn init(&mut self) -> Cmd<Self::Message> {
1949            Cmd::none()
1950        }
1951
1952        fn update(&mut self, msg: Self::Message) -> Cmd<Self::Message> {
1953            match msg {
1954                CounterMsg::Increment => {
1955                    self.value += 1;
1956                    Cmd::none()
1957                }
1958                CounterMsg::Decrement => {
1959                    self.value -= 1;
1960                    Cmd::none()
1961                }
1962                CounterMsg::Reset => {
1963                    self.value = 0;
1964                    Cmd::none()
1965                }
1966                CounterMsg::Quit => Cmd::quit(),
1967            }
1968        }
1969
1970        fn view(&self, frame: &mut Frame) {
1971            let text = format!("Count: {}", self.value);
1972            for (i, c) in text.chars().enumerate() {
1973                if (i as u16) < frame.width() {
1974                    frame.buffer.set_raw(i as u16, 0, Cell::from_char(c));
1975                }
1976            }
1977        }
1978    }
1979
1980    fn key_event(c: char) -> Event {
1981        Event::Key(KeyEvent {
1982            code: KeyCode::Char(c),
1983            modifiers: Modifiers::empty(),
1984            kind: KeyEventKind::Press,
1985        })
1986    }
1987
1988    fn parse_single_input_event(data_json: &str) -> Event {
1989        let line = format!(
1990            r#"{{"schema_version":"{}","event":"input","ts_ns":0,"data":{}}}"#,
1991            SCHEMA_VERSION, data_json
1992        );
1993        let trace = SessionTrace::from_jsonl(&line).expect("input JSON should parse");
1994        trace
1995            .records
1996            .into_iter()
1997            .next()
1998            .and_then(|record| match record {
1999                TraceRecord::Input { event, .. } => Some(event),
2000                _ => None,
2001            })
2002            .expect("expected single input record")
2003    }
2004
2005    fn new_counter(value: i32) -> Counter {
2006        Counter { value }
2007    }
2008
2009    // Observe actual updates even when quit prevents any new frame.
2010    struct ObservedModel {
2011        seen: std::rc::Rc<std::cell::RefCell<Vec<Event>>>,
2012        init_count: std::rc::Rc<std::cell::Cell<u32>>,
2013        quit_on_init: bool,
2014        honor_quit: bool,
2015    }
2016
2017    impl Model for ObservedModel {
2018        type Message = Event;
2019
2020        fn init(&mut self) -> Cmd<Event> {
2021            self.init_count.set(self.init_count.get() + 1);
2022            if self.quit_on_init {
2023                Cmd::quit()
2024            } else {
2025                Cmd::tick(Duration::from_millis(10))
2026            }
2027        }
2028
2029        fn update(&mut self, event: Event) -> Cmd<Event> {
2030            let quit = event == key_event('q') && self.honor_quit;
2031            self.seen.borrow_mut().push(event);
2032            if quit { Cmd::quit() } else { Cmd::none() }
2033        }
2034
2035        fn view(&self, frame: &mut Frame) {
2036            frame.buffer.set_raw(0, 0, Cell::from_char('X'));
2037        }
2038    }
2039
2040    fn observed_model(quit_on_init: bool, honor_quit: bool) -> ObservedModel {
2041        ObservedModel {
2042            seen: Default::default(),
2043            init_count: Default::default(),
2044            quit_on_init,
2045            honor_quit,
2046        }
2047    }
2048
2049    #[test]
2050    fn non_rendering_quit_replays_actual_updates_and_exact_accepted_tail() {
2051        let model = observed_model(false, true);
2052        let recorded_seen = model.seen.clone();
2053        let mut recorder = SessionRecorder::new(model, 20, 2, 7);
2054        recorder.init().unwrap();
2055        let tail = vec![
2056            Event::Paste(PasteEvent::bracketed("尾巴 🦀")),
2057            Event::Resize {
2058                width: 33,
2059                height: 4,
2060            },
2061        ];
2062        for event in [key_event('+'), key_event('q')]
2063            .into_iter()
2064            .chain(tail.clone())
2065        {
2066            recorder.push_event(9, event).unwrap();
2067        }
2068        let outcome = recorder.step().unwrap();
2069        assert_eq!(outcome.events_processed, 2);
2070        assert_eq!(outcome.events_pending, 2);
2071        assert!(!outcome.running && !outcome.rendered);
2072        assert_eq!(
2073            *recorded_seen.borrow(),
2074            vec![key_event('+'), key_event('q')]
2075        );
2076        let trace = SessionTrace::from_jsonl_validated(&recorder.finish().to_jsonl()).unwrap();
2077        let model = observed_model(false, true);
2078        let replayed_seen = model.seen.clone();
2079        let init_count = model.init_count.clone();
2080        let result = replay(model, &trace).unwrap();
2081        assert!(result.ok());
2082        assert_eq!(result.total_steps, 2);
2083        assert_eq!(result.total_frames, 1);
2084        assert!(!result.running);
2085        assert_eq!(result.unprocessed_events, tail);
2086        assert_eq!(*replayed_seen.borrow(), *recorded_seen.borrow());
2087        assert_eq!(init_count.get(), 1);
2088        let gate = gate_trace(observed_model(false, true), &trace).unwrap();
2089        assert!(gate.passed);
2090        assert_eq!(gate.total_steps, 2);
2091        assert!(!gate.running);
2092        assert_eq!(gate.unprocessed_events, tail);
2093        assert!(gate.format().contains("unprocessed_events=2"));
2094        assert!(!gate.format().contains("尾巴"));
2095
2096        // Same initial frame, different quit behavior: checksum-only replay
2097        // previously accepted this without ever executing the quit step.
2098        assert!(matches!(
2099            replay(observed_model(false, false), &trace),
2100            Err(ReplayError::StepMismatch { step_idx: 1, .. })
2101        ));
2102    }
2103
2104    #[test]
2105    fn initialization_quit_has_no_frame_and_recovers_preinit_input() {
2106        let mut recorder = SessionRecorder::new(observed_model(true, true), 20, 2, 7);
2107        recorder.push_event(1, key_event('+')).unwrap();
2108        recorder.resize(2, 40, 4).unwrap();
2109        recorder.init().unwrap();
2110        assert_eq!(recorder.program().size(), (20, 2));
2111        assert!(recorder.program().outputs().last_buffer.is_none());
2112        let stopped = recorder.step().unwrap();
2113        assert_eq!(stopped.events_pending, 2);
2114        assert_eq!(stopped.events_processed, 0);
2115        let trace = SessionTrace::from_jsonl_validated(&recorder.finish().to_jsonl()).unwrap();
2116        let model = observed_model(true, true);
2117        let seen = model.seen.clone();
2118        let init_count = model.init_count.clone();
2119        let result = replay(model, &trace).unwrap();
2120        assert!(result.ok());
2121        assert!(!result.running);
2122        assert_eq!(result.total_frames, 0);
2123        assert_eq!(result.total_steps, 2);
2124        assert_eq!(init_count.get(), 1);
2125        assert!(seen.borrow().is_empty());
2126        assert_eq!(
2127            result.unprocessed_events,
2128            vec![
2129                key_event('+'),
2130                Event::Resize {
2131                    width: 40,
2132                    height: 4
2133                }
2134            ]
2135        );
2136    }
2137
2138    #[test]
2139    fn idle_steps_and_clock_deltas_replay_independently_of_metadata_timestamps() {
2140        let model = observed_model(false, true);
2141        let seen = model.seen.clone();
2142        let mut recorder = SessionRecorder::new(model, 20, 2, 7);
2143        recorder.init().unwrap();
2144        assert!(!recorder.step().unwrap().rendered);
2145        recorder.advance_time(1, Duration::from_millis(9));
2146        assert!(!recorder.step().unwrap().rendered);
2147        recorder.advance_time(2, Duration::from_millis(1));
2148        assert!(recorder.step().unwrap().rendered);
2149        assert!(!recorder.step().unwrap().rendered);
2150        assert_eq!(*seen.borrow(), vec![Event::Tick]);
2151        let trace = SessionTrace::from_jsonl_validated(&recorder.finish().to_jsonl()).unwrap();
2152        let model = observed_model(false, true);
2153        let replayed = model.seen.clone();
2154        let result = replay(model, &trace).unwrap();
2155        assert!(result.ok());
2156        assert_eq!(result.total_steps, 5);
2157        assert_eq!(result.total_frames, 2);
2158        assert_eq!(*replayed.borrow(), vec![Event::Tick]);
2159    }
2160
2161    #[test]
2162    fn trace_requires_observed_boundaries_without_implicit_flush_or_stale_frames() {
2163        let mut recorder = SessionRecorder::new(new_counter(0), 20, 2, 7);
2164        recorder.init().unwrap();
2165        recorder.push_event(1, key_event('q')).unwrap();
2166        recorder.step().unwrap();
2167        let trace = recorder.finish();
2168        trace.validate().unwrap();
2169        let quit_idx = trace.records.len() - 2;
2170        for missing in [1, 2, quit_idx] {
2171            let mut changed = trace.clone();
2172            changed.records.remove(missing);
2173            assert!(changed.validate().is_err(), "missing record {missing}");
2174            assert!(replay(new_counter(0), &changed).is_err());
2175        }
2176        let mut duplicate = trace.clone();
2177        duplicate
2178            .records
2179            .insert(quit_idx, trace.records[quit_idx].clone());
2180        assert!(duplicate.validate().is_err());
2181        let mut reordered = trace.clone();
2182        reordered.records.swap(1, 2);
2183        assert!(reordered.validate().is_err());
2184        let mut bad_count = trace.clone();
2185        if let TraceRecord::Step { result, .. } = &mut bad_count.records[quit_idx] {
2186            result.events_pending = 1;
2187        }
2188        assert!(bad_count.validate().is_err());
2189        let mut after_quit = trace.clone();
2190        after_quit.records.insert(
2191            quit_idx + 1,
2192            TraceRecord::Input {
2193                ts_ns: 1,
2194                event: key_event('+'),
2195            },
2196        );
2197        assert!(after_quit.validate().is_err());
2198
2199        let mut recorder = SessionRecorder::new(new_counter(0), 20, 2, 7);
2200        recorder.init().unwrap();
2201        recorder.push_event(1, key_event('+')).unwrap();
2202        assert!(recorder.finish().validate().is_err());
2203    }
2204
2205    #[test]
2206    fn recorder_rejects_before_changing_trace_or_timestamp_and_replays_recovery() {
2207        let mut recorder = SessionRecorder::new(new_counter(0), 80, 24, 0);
2208        recorder.init().unwrap();
2209        for _ in 0..crate::WebEventSource::MAX_EVENTS {
2210            recorder.push_event(1, key_event('+')).unwrap();
2211        }
2212        let records_before = recorder.records.len();
2213        assert!(matches!(
2214            recorder.push_event(2, key_event('-')),
2215            Err(WebBackendError::InputQueueFull { .. })
2216        ));
2217        assert!(matches!(
2218            recorder.resize(3, 120, 40),
2219            Err(WebBackendError::InputQueueFull { .. })
2220        ));
2221        assert_eq!(recorder.records.len(), records_before);
2222        assert_eq!(recorder.current_ts_ns, 1);
2223        assert_eq!(recorder.program.size(), (80, 24));
2224        assert_eq!(
2225            recorder.step().unwrap().events_processed as usize,
2226            crate::WebEventSource::MAX_EVENTS
2227        );
2228        recorder.push_event(2, key_event('-')).unwrap();
2229        recorder.resize(3, 120, 40).unwrap();
2230        assert_eq!(recorder.step().unwrap().events_processed, 2);
2231        let trace = recorder.finish();
2232        trace.validate().unwrap();
2233        assert!(replay(new_counter(0), &trace).unwrap().ok());
2234    }
2235
2236    #[test]
2237    fn replay_rejects_an_overfull_batch_without_inserting_unrecorded_steps() {
2238        let mut recorder = SessionRecorder::new(new_counter(0), 80, 24, 0);
2239        recorder.init().unwrap();
2240        let mut trace = recorder.finish();
2241        let summary_index = trace.records.len() - 1;
2242        trace.records.splice(
2243            summary_index..summary_index,
2244            (0..=crate::WebEventSource::MAX_EVENTS).map(|_| TraceRecord::Input {
2245                ts_ns: 0,
2246                event: key_event('+'),
2247            }),
2248        );
2249        trace.records.insert(
2250            trace.records.len() - 1,
2251            TraceRecord::Step {
2252                step_idx: 1,
2253                ts_ns: 0,
2254                init: false,
2255                clock: Duration::ZERO,
2256                result: StepResult {
2257                    running: false,
2258                    rendered: false,
2259                    events_processed: 0,
2260                    events_pending: crate::WebEventSource::MAX_EVENTS as u32 + 1,
2261                    frame_idx: 1,
2262                },
2263            },
2264        );
2265        trace.validate().unwrap();
2266        assert!(matches!(
2267            replay(new_counter(0), &trace),
2268            Err(ReplayError::Backend(WebBackendError::InputQueueFull {
2269                limit: crate::WebInputLimit::Events,
2270                ..
2271            }))
2272        ));
2273    }
2274
2275    // ---- FNV-1a hash tests ----
2276
2277    #[test]
2278    fn fnv1a64_pair_is_deterministic() {
2279        let a = fnv1a64_pair(0, 1234);
2280        let b = fnv1a64_pair(0, 1234);
2281        assert_eq!(a, b);
2282    }
2283
2284    #[test]
2285    fn fnv1a64_pair_differs_for_different_input() {
2286        assert_ne!(fnv1a64_pair(0, 1), fnv1a64_pair(0, 2));
2287        assert_ne!(fnv1a64_pair(1, 0), fnv1a64_pair(2, 0));
2288    }
2289
2290    // ---- Recorder basic lifecycle ----
2291
2292    #[test]
2293    fn recorder_produces_header_and_summary() {
2294        let mut rec = SessionRecorder::new(new_counter(0), 80, 24, 42);
2295        rec.init().unwrap();
2296
2297        let trace = rec.finish();
2298        assert_eq!(trace.records.len(), 4); // header + init step + frame + summary
2299
2300        // First record is header.
2301        assert!(matches!(
2302            &trace.records[0],
2303            TraceRecord::Header {
2304                seed: 42,
2305                cols: 80,
2306                rows: 24,
2307                ..
2308            }
2309        ));
2310
2311        // Last record is summary.
2312        assert!(matches!(
2313            trace.records.last().unwrap(),
2314            TraceRecord::Summary {
2315                total_frames: 1,
2316                ..
2317            }
2318        ));
2319    }
2320
2321    #[test]
2322    fn recorder_captures_init_frame() {
2323        let mut rec = SessionRecorder::new(new_counter(0), 20, 1, 0);
2324        rec.init().unwrap();
2325
2326        let trace = rec.finish();
2327        let frames: Vec<_> = trace
2328            .records
2329            .iter()
2330            .filter(|r| matches!(r, TraceRecord::Frame { .. }))
2331            .collect();
2332        assert_eq!(frames.len(), 1);
2333
2334        if let TraceRecord::Frame {
2335            frame_idx,
2336            checksum,
2337            ..
2338        } = &frames[0]
2339        {
2340            assert_eq!(*frame_idx, 0);
2341            assert_ne!(*checksum, 0); // Non-trivial checksum.
2342        }
2343    }
2344
2345    // ---- Record and replay ----
2346
2347    #[test]
2348    fn record_replay_identical_checksums() {
2349        // Record a session.
2350        let mut rec = SessionRecorder::new(new_counter(0), 20, 1, 0);
2351        rec.init().unwrap();
2352
2353        rec.push_event(1_000_000, key_event('+'))
2354            .expect("key admission");
2355        rec.push_event(2_000_000, key_event('+'))
2356            .expect("key admission");
2357        rec.push_event(3_000_000, key_event('-'))
2358            .expect("key admission");
2359        rec.step().unwrap();
2360
2361        rec.push_event(16_000_000, key_event('+'))
2362            .expect("key admission");
2363        rec.step().unwrap();
2364
2365        let trace = rec.finish();
2366        assert_eq!(trace.frame_count(), 3); // init + 2 steps
2367
2368        // Replay with a fresh model.
2369        let result = replay(new_counter(0), &trace).unwrap();
2370        assert!(result.ok(), "replay mismatch: {:?}", result.first_mismatch);
2371        assert_eq!(result.total_frames, 3);
2372        assert_eq!(
2373            result.final_checksum_chain,
2374            trace.final_checksum_chain().unwrap()
2375        );
2376    }
2377
2378    #[test]
2379    fn replay_detects_different_initial_state() {
2380        // Record with counter starting at 0.
2381        let mut rec = SessionRecorder::new(new_counter(0), 20, 1, 0);
2382        rec.init().unwrap();
2383        let trace = rec.finish();
2384
2385        // Replay with counter starting at 5 — different init state → different checksum.
2386        let result = replay(new_counter(5), &trace).unwrap();
2387        assert!(!result.ok());
2388        assert_eq!(result.first_mismatch.as_ref().unwrap().frame_idx, 0);
2389    }
2390
2391    #[test]
2392    fn replay_detects_divergence_after_events() {
2393        // Record with normal counter.
2394        let mut rec = SessionRecorder::new(new_counter(0), 20, 1, 0);
2395        rec.init().unwrap();
2396
2397        rec.push_event(1_000_000, key_event('+'))
2398            .expect("key admission");
2399        rec.push_event(2_000_000, key_event('+'))
2400            .expect("key admission");
2401        rec.step().unwrap();
2402
2403        let trace = rec.finish();
2404
2405        // Replay with a model that starts at 1 instead of 0.
2406        let result = replay(new_counter(1), &trace).unwrap();
2407        assert!(!result.ok());
2408    }
2409
2410    // ---- Resize recording ----
2411
2412    #[test]
2413    fn resize_is_recorded_and_replayed() {
2414        let mut rec = SessionRecorder::new(new_counter(0), 20, 1, 0);
2415        rec.init().unwrap();
2416
2417        rec.resize(5_000_000, 40, 2).expect("resize admission");
2418        rec.step().unwrap();
2419
2420        let trace = rec.finish();
2421
2422        // Verify resize record exists.
2423        assert!(trace.records.iter().any(|r| matches!(
2424            r,
2425            TraceRecord::Resize {
2426                cols: 40,
2427                rows: 2,
2428                ..
2429            }
2430        )));
2431
2432        // Replay should match.
2433        let result = replay(new_counter(0), &trace).unwrap();
2434        assert!(
2435            result.ok(),
2436            "resize replay mismatch: {:?}",
2437            result.first_mismatch
2438        );
2439    }
2440
2441    // ---- Multiple steps ----
2442
2443    #[test]
2444    fn multi_step_record_replay() {
2445        let mut rec = SessionRecorder::new(new_counter(0), 20, 1, 0);
2446        rec.init().unwrap();
2447
2448        for i in 0..5 {
2449            rec.push_event(i * 16_000_000, key_event('+'))
2450                .expect("key admission");
2451            rec.step().unwrap();
2452        }
2453
2454        let trace = rec.finish();
2455        assert_eq!(trace.frame_count(), 6); // init + 5 steps
2456
2457        let result = replay(new_counter(0), &trace).unwrap();
2458        assert!(
2459            result.ok(),
2460            "multi-step mismatch: {:?}",
2461            result.first_mismatch
2462        );
2463        assert_eq!(result.total_frames, 6);
2464    }
2465
2466    // ---- Quit during session ----
2467
2468    #[test]
2469    fn quit_stops_recording() {
2470        let mut rec = SessionRecorder::new(new_counter(0), 20, 1, 0);
2471        rec.init().unwrap();
2472
2473        rec.push_event(1_000_000, key_event('+'))
2474            .expect("key admission");
2475        rec.push_event(2_000_000, key_event('q'))
2476            .expect("quit admission");
2477        let result = rec.step().unwrap();
2478        assert!(!result.running);
2479
2480        let trace = rec.finish();
2481        // init frame + no render after quit (quit stops before render).
2482        assert_eq!(trace.frame_count(), 1);
2483    }
2484
2485    // ---- Empty session ----
2486
2487    #[test]
2488    fn empty_session_replay() {
2489        let mut rec = SessionRecorder::new(new_counter(0), 20, 1, 0);
2490        rec.init().unwrap();
2491        let trace = rec.finish();
2492
2493        let result = replay(new_counter(0), &trace).unwrap();
2494        assert!(result.ok());
2495        assert_eq!(result.total_frames, 1); // Just the init frame.
2496    }
2497
2498    // ---- Trace accessors ----
2499
2500    #[test]
2501    fn session_trace_frame_count() {
2502        let mut rec = SessionRecorder::new(new_counter(0), 20, 1, 0);
2503        rec.init().unwrap();
2504        rec.push_event(1_000_000, key_event('+'))
2505            .expect("key admission");
2506        rec.step().unwrap();
2507        let trace = rec.finish();
2508        assert_eq!(trace.frame_count(), 2);
2509    }
2510
2511    #[test]
2512    fn session_trace_final_checksum_chain() {
2513        let mut rec = SessionRecorder::new(new_counter(0), 20, 1, 0);
2514        rec.init().unwrap();
2515        let trace = rec.finish();
2516        assert!(trace.final_checksum_chain().is_some());
2517        assert_ne!(trace.final_checksum_chain().unwrap(), 0);
2518    }
2519
2520    // ---- Replay error cases ----
2521
2522    #[test]
2523    fn replay_missing_header_returns_error() {
2524        let trace = SessionTrace { records: vec![] };
2525        let result = replay(new_counter(0), &trace);
2526        assert!(matches!(result, Err(ReplayError::MissingHeader)));
2527    }
2528
2529    #[test]
2530    fn replay_non_header_first_returns_error() {
2531        let trace = SessionTrace {
2532            records: vec![TraceRecord::Tick { ts_ns: 0 }],
2533        };
2534        let result = replay(new_counter(0), &trace);
2535        assert!(matches!(result, Err(ReplayError::MissingHeader)));
2536    }
2537
2538    #[test]
2539    fn trace_validate_missing_summary_returns_typed_error() {
2540        let trace = SessionTrace {
2541            records: vec![TraceRecord::Header {
2542                seed: 0,
2543                cols: 80,
2544                rows: 24,
2545                profile: "modern".to_string(),
2546            }],
2547        };
2548        let result = trace.validate();
2549        assert_eq!(result, Err(TraceValidationError::MissingSummary));
2550    }
2551
2552    #[test]
2553    fn trace_validate_summary_frame_count_mismatch_returns_typed_error() {
2554        let trace = SessionTrace {
2555            records: vec![
2556                TraceRecord::Header {
2557                    seed: 0,
2558                    cols: 80,
2559                    rows: 24,
2560                    profile: "modern".to_string(),
2561                },
2562                TraceRecord::Frame {
2563                    frame_idx: 0,
2564                    ts_ns: 0,
2565                    checksum: 0x1,
2566                    checksum_chain: 0x10,
2567                },
2568                TraceRecord::Summary {
2569                    total_frames: 2,
2570                    final_checksum_chain: 0x10,
2571                },
2572            ],
2573        };
2574        let result = trace.validate();
2575        assert_eq!(
2576            result,
2577            Err(TraceValidationError::SummaryFrameCountMismatch {
2578                expected: 1,
2579                actual: 2,
2580            })
2581        );
2582    }
2583
2584    #[test]
2585    fn trace_validate_frame_index_gap_returns_typed_error() {
2586        let trace = SessionTrace {
2587            records: vec![
2588                TraceRecord::Header {
2589                    seed: 0,
2590                    cols: 80,
2591                    rows: 24,
2592                    profile: "modern".to_string(),
2593                },
2594                TraceRecord::Frame {
2595                    frame_idx: 1,
2596                    ts_ns: 0,
2597                    checksum: 0x1,
2598                    checksum_chain: 0x10,
2599                },
2600                TraceRecord::Summary {
2601                    total_frames: 1,
2602                    final_checksum_chain: 0x10,
2603                },
2604            ],
2605        };
2606        let result = trace.validate();
2607        assert_eq!(
2608            result,
2609            Err(TraceValidationError::FrameIndexMismatch {
2610                expected: 0,
2611                actual: 1,
2612            })
2613        );
2614    }
2615
2616    #[test]
2617    fn trace_validate_timestamp_regression_returns_typed_error() {
2618        let trace = SessionTrace {
2619            records: vec![
2620                TraceRecord::Header {
2621                    seed: 0,
2622                    cols: 80,
2623                    rows: 24,
2624                    profile: "modern".to_string(),
2625                },
2626                TraceRecord::Tick { ts_ns: 20 },
2627                TraceRecord::Tick { ts_ns: 10 },
2628                TraceRecord::Summary {
2629                    total_frames: 0,
2630                    final_checksum_chain: 0,
2631                },
2632            ],
2633        };
2634        let result = trace.validate();
2635        assert_eq!(
2636            result,
2637            Err(TraceValidationError::TimestampRegression {
2638                previous: 20,
2639                current: 10,
2640                record_index: 2,
2641            })
2642        );
2643    }
2644
2645    #[test]
2646    fn replay_validates_trace_before_execution() {
2647        let trace = SessionTrace {
2648            records: vec![TraceRecord::Header {
2649                seed: 0,
2650                cols: 80,
2651                rows: 24,
2652                profile: "modern".to_string(),
2653            }],
2654        };
2655        let result = replay(new_counter(0), &trace);
2656        assert_eq!(
2657            result,
2658            Err(ReplayError::InvalidTrace(
2659                TraceValidationError::MissingSummary
2660            ))
2661        );
2662    }
2663
2664    // ---- Determinism: same input → same trace ----
2665
2666    #[test]
2667    fn same_inputs_produce_same_trace_checksums() {
2668        fn record_session() -> SessionTrace {
2669            let mut rec = SessionRecorder::new(new_counter(0), 20, 1, 0);
2670            rec.init().unwrap();
2671
2672            rec.push_event(1_000_000, key_event('+'))
2673                .expect("key admission");
2674            rec.push_event(2_000_000, key_event('+'))
2675                .expect("key admission");
2676            rec.push_event(3_000_000, key_event('-'))
2677                .expect("key admission");
2678            rec.step().unwrap();
2679
2680            rec.push_event(16_000_000, key_event('+'))
2681                .expect("key admission");
2682            rec.step().unwrap();
2683
2684            rec.finish()
2685        }
2686
2687        let t1 = record_session();
2688        let t2 = record_session();
2689        let t3 = record_session();
2690
2691        // All traces should have identical frame checksums.
2692        let checksums = |t: &SessionTrace| -> Vec<u64> {
2693            t.records
2694                .iter()
2695                .filter_map(|r| match r {
2696                    TraceRecord::Frame { checksum, .. } => Some(*checksum),
2697                    _ => None,
2698                })
2699                .collect()
2700        };
2701
2702        assert_eq!(checksums(&t1), checksums(&t2));
2703        assert_eq!(checksums(&t2), checksums(&t3));
2704        assert_eq!(t1.final_checksum_chain(), t2.final_checksum_chain());
2705    }
2706
2707    // ---- Mouse, paste, and focus events ----
2708
2709    #[test]
2710    fn mouse_event_record_replay() {
2711        let mut rec = SessionRecorder::new(new_counter(0), 20, 1, 0);
2712        rec.init().unwrap();
2713
2714        let mouse = Event::Mouse(MouseEvent {
2715            kind: MouseEventKind::Down(MouseButton::Left),
2716            x: 5,
2717            y: 0,
2718            pixel: None,
2719            modifiers: Modifiers::empty(),
2720        });
2721        rec.push_event(1_000_000, mouse).expect("mouse admission");
2722        rec.step().unwrap();
2723
2724        let trace = rec.finish();
2725        let result = replay(new_counter(0), &trace).unwrap();
2726        assert!(result.ok());
2727    }
2728
2729    #[test]
2730    fn paste_event_record_replay() {
2731        let mut rec = SessionRecorder::new(new_counter(0), 20, 1, 0);
2732        rec.init().unwrap();
2733
2734        let paste = Event::Paste(PasteEvent::bracketed("hello"));
2735        rec.push_event(1_000_000, paste).expect("paste admission");
2736        rec.step().unwrap();
2737
2738        let trace = rec.finish();
2739        let result = replay(new_counter(0), &trace).unwrap();
2740        assert!(result.ok());
2741    }
2742
2743    #[test]
2744    fn focus_event_record_replay() {
2745        let mut rec = SessionRecorder::new(new_counter(0), 20, 1, 0);
2746        rec.init().unwrap();
2747
2748        rec.push_event(1_000_000, Event::Focus(true))
2749            .expect("focus admission");
2750        rec.push_event(2_000_000, Event::Focus(false))
2751            .expect("focus admission");
2752        rec.step().unwrap();
2753
2754        let trace = rec.finish();
2755        let result = replay(new_counter(0), &trace).unwrap();
2756        assert!(result.ok());
2757    }
2758
2759    #[test]
2760    fn ime_event_record_replay() {
2761        let mut rec = SessionRecorder::new(new_counter(0), 20, 1, 0);
2762        rec.init().unwrap();
2763
2764        rec.push_event(1_000_000, Event::Ime(ImeEvent::start()))
2765            .expect("IME start admission");
2766        rec.push_event(2_000_000, Event::Ime(ImeEvent::update("你")))
2767            .expect("IME update admission");
2768        rec.push_event(3_000_000, Event::Ime(ImeEvent::commit("你好")))
2769            .expect("IME commit admission");
2770        rec.step().unwrap();
2771
2772        let trace = rec.finish();
2773        let result = replay(new_counter(0), &trace).unwrap();
2774        assert!(result.ok());
2775    }
2776
2777    // ---- Checksum chain integrity ----
2778
2779    #[test]
2780    fn checksum_chain_is_cumulative() {
2781        let mut rec = SessionRecorder::new(new_counter(0), 20, 1, 0);
2782        rec.init().unwrap();
2783
2784        rec.push_event(1_000_000, key_event('+'))
2785            .expect("key admission");
2786        rec.step().unwrap();
2787
2788        rec.push_event(2_000_000, key_event('+'))
2789            .expect("key admission");
2790        rec.step().unwrap();
2791
2792        let trace = rec.finish();
2793        let frame_records: Vec<_> = trace
2794            .records
2795            .iter()
2796            .filter_map(|r| match r {
2797                TraceRecord::Frame {
2798                    checksum,
2799                    checksum_chain,
2800                    ..
2801                } => Some((*checksum, *checksum_chain)),
2802                _ => None,
2803            })
2804            .collect();
2805
2806        assert_eq!(frame_records.len(), 3);
2807
2808        // Verify chain: each chain = fnv1a64_pair(prev_chain, checksum).
2809        let (c0, chain0) = frame_records[0];
2810        assert_eq!(chain0, fnv1a64_pair(0, c0));
2811
2812        let (c1, chain1) = frame_records[1];
2813        assert_eq!(chain1, fnv1a64_pair(chain0, c1));
2814
2815        let (c2, chain2) = frame_records[2];
2816        assert_eq!(chain2, fnv1a64_pair(chain1, c2));
2817
2818        // Final chain in summary matches last frame chain.
2819        assert_eq!(trace.final_checksum_chain(), Some(chain2));
2820    }
2821
2822    // ---- Recorder program accessors ----
2823
2824    #[test]
2825    fn recorder_exposes_program() {
2826        let mut rec = SessionRecorder::new(new_counter(42), 20, 1, 0);
2827        rec.init().unwrap();
2828        assert_eq!(rec.program().model().value, 42);
2829    }
2830
2831    // ---- ReplayResult and ReplayError ----
2832
2833    #[test]
2834    fn replay_result_ok_when_no_mismatch() {
2835        let r = ReplayResult {
2836            total_steps: 5,
2837            running: true,
2838            unprocessed_events: Vec::new(),
2839            total_frames: 5,
2840            final_checksum_chain: 123,
2841            first_mismatch: None,
2842        };
2843        assert!(r.ok());
2844    }
2845
2846    #[test]
2847    fn replay_result_not_ok_when_mismatch() {
2848        let r = ReplayResult {
2849            total_steps: 5,
2850            running: true,
2851            unprocessed_events: Vec::new(),
2852            total_frames: 5,
2853            final_checksum_chain: 123,
2854            first_mismatch: Some(ReplayMismatch {
2855                frame_idx: 2,
2856                expected: 100,
2857                actual: 200,
2858            }),
2859        };
2860        assert!(!r.ok());
2861    }
2862
2863    #[test]
2864    fn replay_error_display() {
2865        assert_eq!(
2866            ReplayError::MissingHeader.to_string(),
2867            "trace missing header record"
2868        );
2869        let invalid = ReplayError::InvalidTrace(TraceValidationError::MissingSummary);
2870        assert_eq!(
2871            invalid.to_string(),
2872            "invalid trace: trace is missing summary"
2873        );
2874        let be = ReplayError::Backend(WebBackendError::Unsupported("test"));
2875        assert!(be.to_string().contains("test"));
2876    }
2877
2878    // ---- JSONL serialization ----
2879
2880    #[test]
2881    fn trace_record_header_to_jsonl() {
2882        let r = TraceRecord::Header {
2883            seed: 42,
2884            cols: 80,
2885            rows: 24,
2886            profile: "modern".to_string(),
2887        };
2888        let line = r.to_jsonl();
2889        assert!(line.contains("\"event\":\"trace_header\""));
2890        assert!(line.contains("\"schema_version\":\"golden-trace-v2\""));
2891        assert!(line.contains("\"seed\":42"));
2892        assert!(line.contains("\"cols\":80"));
2893        assert!(line.contains("\"rows\":24"));
2894        assert!(line.contains("\"profile\":\"modern\""));
2895    }
2896
2897    #[test]
2898    fn trace_record_input_key_to_jsonl() {
2899        let r = TraceRecord::Input {
2900            ts_ns: 1_000_000,
2901            event: key_event('+'),
2902        };
2903        let line = r.to_jsonl();
2904        assert!(line.contains("\"event\":\"input\""));
2905        assert!(line.contains("\"ts_ns\":1000000"));
2906        assert!(line.contains("\"kind\":\"key\""));
2907        assert!(line.contains("\"code\":\"char:+\""));
2908    }
2909
2910    #[test]
2911    fn trace_record_resize_to_jsonl() {
2912        let r = TraceRecord::Resize {
2913            ts_ns: 5_000_000,
2914            cols: 120,
2915            rows: 40,
2916        };
2917        let line = r.to_jsonl();
2918        assert!(line.contains("\"event\":\"resize\""));
2919        assert!(line.contains("\"cols\":120"));
2920        assert!(line.contains("\"rows\":40"));
2921    }
2922
2923    #[test]
2924    fn trace_record_frame_to_jsonl() {
2925        let r = TraceRecord::Frame {
2926            frame_idx: 3,
2927            ts_ns: 48_000_000,
2928            checksum: 0xDEADBEEF,
2929            checksum_chain: 0xCAFEBABE,
2930        };
2931        let line = r.to_jsonl();
2932        assert!(line.contains("\"event\":\"frame\""));
2933        assert!(line.contains("\"frame_idx\":3"));
2934        assert!(line.contains("\"frame_hash\":\"00000000deadbeef\""));
2935        assert!(line.contains("\"checksum_chain\":\"00000000cafebabe\""));
2936    }
2937
2938    #[test]
2939    fn trace_record_summary_to_jsonl() {
2940        let r = TraceRecord::Summary {
2941            total_frames: 10,
2942            final_checksum_chain: 0x1234567890ABCDEF,
2943        };
2944        let line = r.to_jsonl();
2945        assert!(line.contains("\"event\":\"trace_summary\""));
2946        assert!(line.contains("\"total_frames\":10"));
2947        assert!(line.contains("\"final_checksum_chain\":\"1234567890abcdef\""));
2948    }
2949
2950    // ---- JSONL round-trip ----
2951
2952    #[test]
2953    fn jsonl_round_trip_full_session() {
2954        // Record a session.
2955        let mut rec = SessionRecorder::new(new_counter(0), 20, 1, 42);
2956        rec.init().unwrap();
2957        rec.push_event(1_000_000, key_event('+'))
2958            .expect("key admission");
2959        rec.push_event(2_000_000, key_event('+'))
2960            .expect("key admission");
2961        rec.step().unwrap();
2962        let trace = rec.finish();
2963
2964        // Serialize to JSONL.
2965        let jsonl = trace.to_jsonl();
2966        assert!(!jsonl.is_empty());
2967
2968        // Deserialize back.
2969        let parsed = SessionTrace::from_jsonl(&jsonl).unwrap();
2970        assert_eq!(parsed.records.len(), trace.records.len());
2971        assert_eq!(parsed.frame_count(), trace.frame_count());
2972        assert_eq!(parsed.final_checksum_chain(), trace.final_checksum_chain());
2973    }
2974
2975    #[test]
2976    fn jsonl_round_trip_preserves_events() {
2977        let events = vec![
2978            key_event('+'),
2979            key_event('-'),
2980            Event::Key(KeyEvent {
2981                code: KeyCode::Enter,
2982                modifiers: Modifiers::CTRL | Modifiers::SHIFT,
2983                kind: KeyEventKind::Press,
2984            }),
2985            Event::Key(KeyEvent {
2986                code: KeyCode::F(12),
2987                modifiers: Modifiers::ALT,
2988                kind: KeyEventKind::Repeat,
2989            }),
2990            Event::Mouse(MouseEvent {
2991                kind: MouseEventKind::Down(MouseButton::Left),
2992                x: 10,
2993                y: 5,
2994                pixel: None,
2995                modifiers: Modifiers::empty(),
2996            }),
2997            Event::Mouse(MouseEvent {
2998                kind: MouseEventKind::ScrollDown,
2999                x: 0,
3000                y: 0,
3001                pixel: None,
3002                modifiers: Modifiers::CTRL,
3003            }),
3004            Event::Paste(PasteEvent::bracketed("hello world")),
3005            Event::Focus(true),
3006            Event::Focus(false),
3007            Event::Tick,
3008        ];
3009
3010        for (i, event) in events.iter().enumerate() {
3011            let record = TraceRecord::Input {
3012                ts_ns: i as u64 * 1_000_000,
3013                event: event.clone(),
3014            };
3015            let jsonl = record.to_jsonl();
3016            let parsed = SessionTrace::from_jsonl(&jsonl).unwrap();
3017            let parsed_record = &parsed.records[0];
3018            let TraceRecord::Input {
3019                event: parsed_event,
3020                ..
3021            } = parsed_record
3022            else {
3023                unreachable!("expected Input record for event {i}");
3024            };
3025
3026            assert_eq!(parsed_event, event, "event {i} round-trip failed: {jsonl}");
3027        }
3028    }
3029
3030    #[test]
3031    fn jsonl_round_trip_with_resize() {
3032        let mut rec = SessionRecorder::new(new_counter(0), 20, 1, 0);
3033        rec.init().unwrap();
3034        rec.resize(5_000_000, 40, 2).expect("resize admission");
3035        rec.step().unwrap();
3036        let trace = rec.finish();
3037
3038        let jsonl = trace.to_jsonl();
3039        let parsed = SessionTrace::from_jsonl(&jsonl).unwrap();
3040
3041        // Replay parsed trace.
3042        let result = replay(new_counter(0), &parsed).unwrap();
3043        assert!(
3044            result.ok(),
3045            "parsed trace replay failed: {:?}",
3046            result.first_mismatch
3047        );
3048    }
3049
3050    // ---- JSONL parsing errors ----
3051
3052    #[test]
3053    fn step_jsonl_preserves_clock_and_requires_all_outcome_fields() {
3054        let record = TraceRecord::Step {
3055            step_idx: 4,
3056            ts_ns: 9,
3057            init: false,
3058            clock: Duration::new(u64::MAX, 999_999_999),
3059            result: StepResult {
3060                running: false,
3061                rendered: false,
3062                events_processed: 3,
3063                events_pending: 2,
3064                frame_idx: 2,
3065            },
3066        };
3067        let json = record.to_jsonl();
3068        assert_eq!(
3069            SessionTrace::from_jsonl(&json).unwrap().records,
3070            vec![record]
3071        );
3072        for field in [
3073            "step_idx",
3074            "ts_ns",
3075            "init",
3076            "clock_secs",
3077            "clock_subsec_nanos",
3078            "running",
3079            "rendered",
3080            "events_processed",
3081            "events_pending",
3082            "frame_idx",
3083        ] {
3084            let changed = json.replace(&format!("\"{field}\":"), "\"unknown\":");
3085            assert!(
3086                SessionTrace::from_jsonl(&changed).is_err(),
3087                "missing {field}"
3088            );
3089        }
3090        for (old, new) in [
3091            (
3092                "\"clock_subsec_nanos\":999999999",
3093                "\"clock_subsec_nanos\":1000000000",
3094            ),
3095            ("\"events_pending\":2", "\"events_pending\":4294967296"),
3096            ("\"events_processed\":3", "\"events_processed\":-1"),
3097            ("\"running\":false", "\"running\":null"),
3098            ("\"running\":false", "\"running\":falseX"),
3099            ("\"events_pending\":2", "\"events_pending\":2.5"),
3100            ("\"events_pending\":2", "\"events_pending\":2e3"),
3101            ("\"events_pending\":2", "\"nested\":{\"events_pending\":2}"),
3102            (
3103                "\"events_pending\":2",
3104                "\"events_pending\":2,\"events_pending\":2",
3105            ),
3106        ] {
3107            assert!(
3108                SessionTrace::from_jsonl(&json.replace(old, new)).is_err(),
3109                "invalid {new}"
3110            );
3111        }
3112    }
3113
3114    #[test]
3115    fn v1_trace_cannot_invent_missing_execution_boundaries() {
3116        let line = r#"{"schema_version":"golden-trace-v1","event":"tick","ts_ns":0}"#;
3117        let error = SessionTrace::from_jsonl(line).unwrap_err();
3118        assert!(error.message.contains("migration required"));
3119    }
3120
3121    #[test]
3122    fn text_payloads_with_braces_quotes_and_unicode_round_trip_in_quit_tail() {
3123        let text = "} { \\\" 🦀/\n\t\0\u{0008}\u{000c}";
3124        let tail = vec![
3125            Event::Paste(PasteEvent::bracketed(text)),
3126            Event::Ime(ImeEvent::commit(text)),
3127            Event::Clipboard(ftui_core::event::ClipboardEvent {
3128                content: text.to_owned(),
3129                source: ClipboardSource::Osc52,
3130            }),
3131        ];
3132        let mut recorder = SessionRecorder::new(new_counter(0), 20, 2, 7);
3133        recorder.init().unwrap();
3134        recorder.push_event(0, key_event('q')).unwrap();
3135        for event in &tail {
3136            recorder.push_event(0, event.clone()).unwrap();
3137        }
3138        recorder.step().unwrap();
3139        let jsonl = recorder.finish().to_jsonl();
3140        let escaped = jsonl
3141            .replace('🦀', r"\ud83e\udd80")
3142            .replace('/', r"\/")
3143            .replace(r"\u0008", r"\b")
3144            .replace(r"\u000c", r"\f");
3145        for input in [&jsonl, &escaped] {
3146            let trace = SessionTrace::from_jsonl_validated(input).unwrap();
3147            assert_eq!(
3148                replay(new_counter(0), &trace).unwrap().unprocessed_events,
3149                tail
3150            );
3151        }
3152    }
3153
3154    #[test]
3155    fn malformed_text_escapes_are_rejected_without_changing_content() {
3156        for text in [r"\uZZZZ", r"\ud83e", r"\udd80", r"\ud83e\u0061", r"\q"] {
3157            let line = format!(
3158                r#"{{"schema_version":"{}","event":"input","ts_ns":0,"data":{{"kind":"paste","text":"{}"}}}}"#,
3159                SCHEMA_VERSION, text
3160            );
3161            assert!(SessionTrace::from_jsonl(&line).is_err(), "invalid {text}");
3162        }
3163    }
3164
3165    #[test]
3166    fn chain_only_corruption_cannot_pass_replay_or_gate() {
3167        let mut recorder = SessionRecorder::new(new_counter(0), 20, 2, 7);
3168        recorder.init().unwrap();
3169        let mut trace = recorder.finish();
3170        for record in &mut trace.records {
3171            match record {
3172                TraceRecord::Frame { checksum_chain, .. } => *checksum_chain ^= 1,
3173                TraceRecord::Summary {
3174                    final_checksum_chain,
3175                    ..
3176                } => *final_checksum_chain ^= 1,
3177                _ => {}
3178            }
3179        }
3180        assert!(trace.validate().is_err());
3181        assert!(replay(new_counter(0), &trace).is_err());
3182        assert!(gate_trace(new_counter(0), &trace).is_err());
3183    }
3184
3185    #[test]
3186    fn from_jsonl_empty_is_ok() {
3187        let trace = SessionTrace::from_jsonl("").unwrap();
3188        assert!(trace.records.is_empty());
3189    }
3190
3191    #[test]
3192    fn from_jsonl_unknown_event_fails() {
3193        let line = r#"{"schema_version":"golden-trace-v2","event":"unknown_type","ts_ns":0}"#;
3194        let result = SessionTrace::from_jsonl(line);
3195        assert!(result.is_err());
3196        assert!(result.unwrap_err().message.contains("unknown event type"));
3197    }
3198
3199    #[test]
3200    fn from_jsonl_missing_event_field_fails() {
3201        let line = r#"{"schema_version":"golden-trace-v2","ts_ns":0}"#;
3202        let result = SessionTrace::from_jsonl(line);
3203        assert!(result.is_err());
3204    }
3205
3206    #[test]
3207    fn from_jsonl_missing_schema_version_fails() {
3208        let line = r#"{"event":"tick","ts_ns":0}"#;
3209        let result = SessionTrace::from_jsonl(line);
3210        assert!(result.is_err());
3211        assert!(result.unwrap_err().message.contains("schema_version"));
3212    }
3213
3214    #[test]
3215    fn from_jsonl_schema_matrix_current_writer_version_passes() {
3216        let line = format!(
3217            r#"{{"schema_version":"{}","event":"tick","ts_ns":0}}"#,
3218            SCHEMA_VERSION
3219        );
3220        let trace = SessionTrace::from_jsonl(&line).expect("matching schema should parse");
3221        assert_eq!(trace.records, vec![TraceRecord::Tick { ts_ns: 0 }]);
3222    }
3223
3224    #[test]
3225    fn from_jsonl_schema_matrix_newer_writer_version_fails_with_migration_error() {
3226        let line = r#"{"schema_version":"golden-trace-v3","event":"tick","ts_ns":0}"#;
3227        let result = SessionTrace::from_jsonl(line);
3228        assert!(result.is_err());
3229        let message = result.unwrap_err().message;
3230        assert!(message.contains("unsupported schema_version"));
3231        assert!(message.contains("migration required"));
3232    }
3233
3234    #[cfg(feature = "tracing")]
3235    #[test]
3236    fn schema_incompatibility_emits_compat_span_and_error_log() {
3237        let capture = TraceCaptureLayer::default();
3238        let subscriber =
3239            tracing_subscriber::registry().with(capture.clone().with_filter(LevelFilter::TRACE));
3240        let _guard = tracing::subscriber::set_default(subscriber);
3241
3242        let line = r#"{"schema_version":"golden-trace-v3","event":"tick","ts_ns":0}"#;
3243        let err = SessionTrace::from_jsonl(line).expect_err("newer schema should fail");
3244        assert!(err.message.contains("migration required"));
3245
3246        let spans = capture.spans.lock().expect("span capture lock");
3247        assert!(
3248            spans.iter().any(|name| name == "trace.compat_check"),
3249            "expected trace.compat_check span, got {spans:?}"
3250        );
3251        drop(spans);
3252
3253        let events = capture.events.lock().expect("event capture lock");
3254        assert!(
3255            events
3256                .iter()
3257                .any(|event| event.contains("ERROR:trace schema version incompatible")),
3258            "expected incompatible schema ERROR log, got {events:?}"
3259        );
3260    }
3261
3262    #[test]
3263    fn from_jsonl_validated_surfaces_validation_error_type() {
3264        let jsonl = TraceRecord::Header {
3265            seed: 0,
3266            cols: 80,
3267            rows: 24,
3268            profile: "modern".to_string(),
3269        }
3270        .to_jsonl();
3271        let result = SessionTrace::from_jsonl_validated(&jsonl);
3272        assert!(matches!(
3273            result,
3274            Err(TraceLoadError::Validation(
3275                TraceValidationError::MissingSummary
3276            ))
3277        ));
3278    }
3279
3280    // ---- JSON helpers ----
3281
3282    #[test]
3283    fn json_escape_round_trip() {
3284        let cases = [
3285            "hello",
3286            "with\"quotes",
3287            "back\\slash",
3288            "line\nbreak",
3289            "tab\there",
3290        ];
3291        for input in cases {
3292            let escaped = json_escape(input);
3293            let unescaped = json_unescape(&escaped).unwrap();
3294            assert_eq!(unescaped, input, "round-trip failed for: {input:?}");
3295        }
3296    }
3297
3298    #[test]
3299    fn extract_str_basic() {
3300        let json = r#"{"name":"alice","age":30}"#;
3301        assert_eq!(extract_str(json, "name"), Some("alice"));
3302    }
3303
3304    #[test]
3305    fn extract_u64_basic() {
3306        let json = r#"{"count":42,"name":"test"}"#;
3307        assert_eq!(extract_u64(json, "count"), Some(42));
3308    }
3309
3310    #[test]
3311    fn extract_i64_basic() {
3312        let json = r#"{"dx":-12,"dy":7}"#;
3313        assert_eq!(extract_i64(json, "dx"), Some(-12));
3314        assert_eq!(extract_i64(json, "dy"), Some(7));
3315    }
3316
3317    #[test]
3318    fn extract_bool_basic() {
3319        let json = r#"{"enabled":true,"disabled":false}"#;
3320        assert_eq!(extract_bool(json, "enabled"), Some(true));
3321        assert_eq!(extract_bool(json, "disabled"), Some(false));
3322    }
3323
3324    #[test]
3325    fn extract_hex_u64_basic() {
3326        let json = r#"{"hash":"00000000deadbeef"}"#;
3327        assert_eq!(extract_hex_u64(json, "hash"), Some(0xDEADBEEF));
3328    }
3329
3330    #[test]
3331    fn from_jsonl_parses_frankenterm_key_schema() {
3332        let down = parse_single_input_event(
3333            r#"{"kind":"key","phase":"down","code":"F12","mods":5,"repeat":false}"#,
3334        );
3335        assert_eq!(
3336            down,
3337            Event::Key(KeyEvent {
3338                code: KeyCode::F(12),
3339                modifiers: Modifiers::SHIFT | Modifiers::CTRL,
3340                kind: KeyEventKind::Press,
3341            })
3342        );
3343
3344        let repeat = parse_single_input_event(
3345            r#"{"kind":"key","phase":"down","code":"a","mods":0,"repeat":true}"#,
3346        );
3347        assert_eq!(
3348            repeat,
3349            Event::Key(KeyEvent {
3350                code: KeyCode::Char('a'),
3351                modifiers: Modifiers::empty(),
3352                kind: KeyEventKind::Repeat,
3353            })
3354        );
3355
3356        let release = parse_single_input_event(
3357            r#"{"kind":"key","phase":"up","code":"Enter","mods":0,"repeat":false}"#,
3358        );
3359        assert_eq!(
3360            release,
3361            Event::Key(KeyEvent {
3362                code: KeyCode::Enter,
3363                modifiers: Modifiers::empty(),
3364                kind: KeyEventKind::Release,
3365            })
3366        );
3367    }
3368
3369    #[test]
3370    fn key_event_json_round_trip_unescapes_code() {
3371        let quote_key = Event::Key(KeyEvent {
3372            code: KeyCode::Char('"'),
3373            modifiers: Modifiers::empty(),
3374            kind: KeyEventKind::Press,
3375        });
3376        let quote_json = event_to_json(&quote_key);
3377        let parsed_quote = parse_event_json(&quote_json).expect("quote key should parse");
3378        assert_eq!(parsed_quote, quote_key);
3379
3380        let slash_key = Event::Key(KeyEvent {
3381            code: KeyCode::Char('\\'),
3382            modifiers: Modifiers::SHIFT,
3383            kind: KeyEventKind::Press,
3384        });
3385        let slash_json = event_to_json(&slash_key);
3386        let parsed_slash = parse_event_json(&slash_json).expect("slash key should parse");
3387        assert_eq!(parsed_slash, slash_key);
3388    }
3389
3390    #[test]
3391    fn from_jsonl_parses_frankenterm_mouse_and_wheel_schema() {
3392        let mouse = parse_single_input_event(
3393            r#"{"kind":"mouse","phase":"drag","button":2,"x":7,"y":9,"mods":3}"#,
3394        );
3395        assert_eq!(
3396            mouse,
3397            Event::Mouse(MouseEvent {
3398                kind: MouseEventKind::Drag(MouseButton::Right),
3399                x: 7,
3400                y: 9,
3401                pixel: None,
3402                modifiers: Modifiers::SHIFT | Modifiers::ALT,
3403            })
3404        );
3405
3406        let wheel =
3407            parse_single_input_event(r#"{"kind":"wheel","x":4,"y":6,"dx":0,"dy":-2,"mods":4}"#);
3408        assert_eq!(
3409            wheel,
3410            Event::Mouse(MouseEvent {
3411                kind: MouseEventKind::ScrollUp,
3412                x: 4,
3413                y: 6,
3414                pixel: None,
3415                modifiers: Modifiers::CTRL,
3416            })
3417        );
3418    }
3419
3420    #[test]
3421    fn from_jsonl_parses_frankenterm_paste_focus_and_composition_aliases() {
3422        let paste = parse_single_input_event(r#"{"kind":"paste","data":"hello\nworld"}"#);
3423        assert_eq!(paste, Event::Paste(PasteEvent::new("hello\nworld", true)));
3424
3425        let focus = parse_single_input_event(r#"{"kind":"focus","focused":false}"#);
3426        assert_eq!(focus, Event::Focus(false));
3427
3428        let composition_update =
3429            parse_single_input_event(r#"{"kind":"composition","phase":"update","data":"你"}"#);
3430        assert_eq!(
3431            composition_update,
3432            Event::Ime(ImeEvent::new(ImePhase::Update, "你"))
3433        );
3434
3435        let composition_end =
3436            parse_single_input_event(r#"{"kind":"composition","phase":"end","data":"你好"}"#);
3437        assert_eq!(
3438            composition_end,
3439            Event::Ime(ImeEvent::new(ImePhase::Commit, "你好"))
3440        );
3441    }
3442
3443    // ---- Golden Gate API ----
3444
3445    #[test]
3446    fn gate_trace_passes_on_correct_replay() {
3447        let mut rec = SessionRecorder::new(new_counter(0), 20, 1, 0);
3448        rec.init().unwrap();
3449        rec.push_event(1_000_000, key_event('+'))
3450            .expect("key admission");
3451        rec.step().unwrap();
3452        let trace = rec.finish();
3453
3454        let report = gate_trace(new_counter(0), &trace).unwrap();
3455        assert!(report.passed);
3456        assert_eq!(report.total_frames, 2);
3457        assert!(report.diff.is_none());
3458        assert!(report.format().starts_with("PASS"));
3459    }
3460
3461    #[test]
3462    fn gate_trace_fails_with_actionable_diff() {
3463        let mut rec = SessionRecorder::new(new_counter(0), 20, 1, 0);
3464        rec.init().unwrap();
3465        rec.push_event(1_000_000, key_event('+'))
3466            .expect("key admission");
3467        rec.push_event(2_000_000, key_event('+'))
3468            .expect("key admission");
3469        rec.step().unwrap();
3470        let trace = rec.finish();
3471
3472        // Replay with different initial state.
3473        let report = gate_trace(new_counter(5), &trace).unwrap();
3474        assert!(!report.passed);
3475        assert!(report.diff.is_some());
3476
3477        let diff = report.diff.as_ref().unwrap();
3478        assert_eq!(diff.frame_idx, 0); // First frame mismatch (init).
3479
3480        let formatted = report.format();
3481        assert!(formatted.starts_with("FAIL"));
3482        assert!(formatted.contains("frame 0"));
3483    }
3484
3485    #[test]
3486    fn gate_trace_diff_has_event_context() {
3487        let mut rec = SessionRecorder::new(new_counter(0), 20, 1, 0);
3488        rec.init().unwrap();
3489        rec.push_event(1_000_000, key_event('+'))
3490            .expect("key admission");
3491        rec.push_event(2_000_000, key_event('+'))
3492            .expect("key admission");
3493        rec.step().unwrap();
3494        rec.push_event(3_000_000, key_event('-'))
3495            .expect("key admission");
3496        rec.step().unwrap();
3497        let trace = rec.finish();
3498
3499        // Tamper with the trace: change a frame checksum.
3500        let mut tampered = trace.clone();
3501        let mut chain = 0;
3502        for record in &mut tampered.records {
3503            match record {
3504                TraceRecord::Frame {
3505                    frame_idx,
3506                    checksum,
3507                    checksum_chain,
3508                    ..
3509                } => {
3510                    if *frame_idx == 2 {
3511                        *checksum = 0xBAD;
3512                    }
3513                    chain = fnv1a64_pair(chain, *checksum);
3514                    *checksum_chain = chain;
3515                }
3516                TraceRecord::Summary {
3517                    final_checksum_chain,
3518                    ..
3519                } => *final_checksum_chain = chain,
3520                _ => {}
3521            }
3522        }
3523        // Preserve structural integrity so this still tests an actual model
3524        // checksum mismatch, independently of the malformed-chain rejection.
3525        tampered.validate().unwrap();
3526
3527        let report = gate_trace(new_counter(0), &tampered).unwrap();
3528        assert!(!report.passed);
3529        let diff = report.diff.unwrap();
3530        assert_eq!(diff.frame_idx, 2);
3531        assert!(diff.event_idx > 0); // Events were processed before frame 2.
3532    }
3533
3534    // ---- JSONL → replay integration ----
3535
3536    #[test]
3537    fn jsonl_serialize_parse_replay_round_trip() {
3538        // Full pipeline: record → JSONL → parse → replay → verify.
3539        let mut rec = SessionRecorder::new(new_counter(0), 20, 1, 0);
3540        rec.init().unwrap();
3541
3542        for i in 0..3 {
3543            rec.push_event(i * 16_000_000, key_event('+'))
3544                .expect("key admission");
3545            rec.step().unwrap();
3546        }
3547        let original_trace = rec.finish();
3548
3549        // Serialize.
3550        let jsonl = original_trace.to_jsonl();
3551
3552        // Parse.
3553        let parsed_trace = SessionTrace::from_jsonl(&jsonl).unwrap();
3554
3555        // Replay parsed trace.
3556        let result = replay(new_counter(0), &parsed_trace).unwrap();
3557        assert!(
3558            result.ok(),
3559            "JSONL round-trip replay failed: {:?}",
3560            result.first_mismatch
3561        );
3562        assert_eq!(result.total_frames, original_trace.frame_count());
3563        assert_eq!(
3564            result.final_checksum_chain,
3565            original_trace.final_checksum_chain().unwrap()
3566        );
3567    }
3568
3569    // ---- TraceParseError ----
3570
3571    #[test]
3572    fn trace_parse_error_display() {
3573        let e = TraceParseError {
3574            line: 5,
3575            message: "bad field".to_string(),
3576        };
3577        assert_eq!(e.to_string(), "line 5: bad field");
3578    }
3579}