codex/docs/tui-stream-chunking-validation.md

TUI Stream Chunking Validation Process

This document records the process used to validate adaptive stream chunking and anti-flap behavior.

Scope

The goal is to verify two properties from runtime traces:

• display lag is reduced when queue pressure rises
• mode transitions remain stable instead of rapidly flapping

Trace targets

Chunking observability is emitted by:

• codex_tui::streaming::commit_tick

Two trace messages are used:

• stream chunking commit tick
• stream chunking mode transition

Runtime command

Run Codex with chunking traces enabled:

RUST_LOG='codex_tui::streaming::commit_tick=trace,codex_tui=info,codex_core=info,codex_rmcp_client=info' \
  just codex --enable=responses_websockets

Log capture process

Tip: for one-off measurements, run with -c log_dir=... to direct logs to a fresh directory and avoid mixing sessions.

1. Record the current size of ~/.codex/log/codex-tui.log as a start offset.
2. Run an interactive prompt that produces sustained streamed output.
3. Stop the run.
4. Parse only log bytes written after the recorded offset.

This avoids mixing earlier sessions with the current measurement window.

Metrics reviewed

For each measured window:

• commit_ticks
• mode_transitions
• smooth_ticks
• catchup_ticks
• drain-plan distribution (Single, Batch(n))
• queue depth (max, p95, p99)
• oldest queued age (max, p95, p99)
• rapid re-entry count:
  • number of Smooth -> CatchUp transitions within 1 second of a CatchUp -> Smooth transition

Interpretation

• Healthy behavior:
  • queue age remains bounded while backlog is drained
  • transition count is low relative to total ticks
  • rapid re-entry events are infrequent and localized to burst boundaries
• Regressed behavior:
  • repeated short-interval mode toggles across an extended window
  • persistent queue-age growth while in smooth mode
  • long catch-up runs without backlog reduction

Experiment history

This section captures the major tuning passes so future work can build on what has already been tried.

• Baseline
  • One-line smooth draining with a 50ms commit tick.
  • This preserved familiar pacing but could feel laggy under sustained backlog.
• Pass 1: instant catch-up, baseline tick unchanged
  • Kept smooth-mode semantics but made catch-up drain the full queued backlog each catch-up tick.
  • Result: queue lag dropped faster, but perceived motion could still feel stepped because smooth-mode cadence remained coarse.
• Pass 2: faster baseline tick (25ms)
  • Improved smooth-mode cadence and reduced visible stepping.
  • Result: better, but still not aligned with draw cadence.
• Pass 3: frame-aligned baseline tick (~16.7ms)
  • Set baseline commit cadence to approximately 60fps.
  • Result: smoother perceived progression while retaining hysteresis and fast backlog convergence.
• Pass 4: higher frame-aligned baseline tick (~8.3ms)
  • Set baseline commit cadence to approximately 120fps.
  • Result: further reduced smooth-mode stepping while preserving the same adaptive catch-up policy shape.

Current state combines:

• instant catch-up draining in CatchUp
• hysteresis for mode-entry/exit stability
• frame-aligned smooth-mode commit cadence (~8.3ms)

Notes

• Validation is source-agnostic and does not rely on naming any specific upstream provider.
• This process intentionally preserves existing baseline smooth behavior and focuses on burst/backlog handling behavior.