Interactive Trace Visualizer (chaossql ui)

Architecture of the Local Web Visualizer (chaossql ui)

The ChaosSQL Interactive Trace Visualizer is a self-contained, editorial web application served directly by Go's native HTTP server (net/http). Designed following the official Studio Bregalda Design System, it features an immersive, restful color palette (Deep Ink #120E1F, Bregalda Purple #4B2E83, Warm Cream #FCFBF8, Signal Yellow #F5C400, and Ship Green #22C55E), crisp typography (JetBrains Mono), and strictly zero external dependencies (no CDNs, no Node.js runtime, and no analytics trackers).

How to Launch the Visualizer

Option 1: Immediate Post-Execution Inspection

chaossql run specs/banking_lost_update.yaml --ui

Upon completing the fuzzing run, ChaosSQL starts the local web server and automatically opens your system default browser (invoking wslview on WSL2, open on macOS, or rundll32 on Windows).

Option 2: Inspecting Saved Traces from Disk

chaossql ui trace_banking_run_42.json --port=8090

The 4 Visual Inspection Modules

1. Concurrency Gantt Swimlane (Microsecond Timeline)

The Gantt Swimlane maps each concurrent worker goroutine (W₀, W₁, W₂, W₃, …) onto an independent horizontal time axis:

• Monotonic Microsecond Scale: Nanosecond-precision timestamps formatted as elapsed microseconds (μs) from the start of the session, exposing overlapping transactions with pinpoint accuracy.
• Color-Coded Operation Blocks:
  • ● Purple / Blue: BEGIN and transaction snapshot acquisition.
  • ● Gray: SELECT queries and intermediate read evaluation.
  • ● Orange: UPDATE, INSERT, and mutation writes.
  • ● Green: COMMIT successfully applied.
  • ● Red: ROLLBACK or concurrency conflict abort.
• Critical Race Window Diagnostic: Highlights the exact moment Worker W₁ read before Worker W₀ committed its write, visually pinning the lost update or dirty read.

2. Adya Directed Dependency Graph (Interactive SVG DSG)

Renders the Direct Serialization Graph (SG(S)) where vertices represent committed transactions and directed edges represent conflicting data access pairs:

• Anti-Dependency Edge (rw): Transaction T₁ read a prior version of entity x before transaction T₂ overwrote it with a newer version.
• Overwrite Dependency Edge (ww): Transaction T₁ wrote a version of record x that was subsequently overwritten by transaction T₂.
• Read Dependency Edge (wr): Transaction T₂ read the specific value written and committed by transaction T₁.
• Anomalous Cycle Highlighting: Edges forming directed cycles (T₁  —^rw→  T₂  —^ww→  T₁) are illuminated in pulsing Bregalda Gold (#F5C400), providing mathematical visual proof of Conflict Serializability violation (CSR Theorem).

3. Delta-Debugging (ddmin) Panel: Raw Trace vs Minimal Trace

ChaosSQL's shrinker module purges noise from extensive fuzzing runs to deliver a minimal reproducible trace. The ddmin card compares the raw execution against the irreducible counterexample:

4. Tabular Query & Resolved Parameters Inspector

An interactive, sortable statement ledger detailing every SQL instruction submitted to the database engine in strict chronological order:

• Resolved Parameter Inspection: Statements are rendered with dynamic expression variables evaluated (e.g., UPDATE accounts SET balance = 900 WHERE id = 1 instead of raw template placeholders).
• Statement Latency: Engine execution duration recorded at microsecond resolution for every roundtrip.
• Goroutine Worker Affinity: Immediate identification of the originating worker, thread state, and database error codes.

Standalone HTML Report Export

Generate self-contained static audit artifacts suitable for attaching to Pull Requests or sharing in architecture reviews:

chaossql run specs/banking_lost_update.yaml --export-html=audit_report.html

The resulting HTML artifact is approximately 60KB, bundles all styling, interactivity, and SVG vector assets inline, and opens offline in any modern browser without network access.