docs: clarify custom event system rationale over emit

Author: cablehead

docs/adr/0004-custom-event-system.md

@@ -1,49 +1,43 @@
-# Custom Event System Over Tracing
+# Custom Event System
 
 ## Context
 
-http-nu needs structured logging with:
-- Rich request/response data (headers, query params, timing)
-- Multiple output formats (human-readable terminal, JSONL)
+http-nu needs structured logging:
+- Request/response lifecycle (headers, timing, bytes)
+- Two output formats: human-readable terminal, JSONL for tooling
 - High throughput without blocking request handling
-- Works with `cargo install` without special flags
+- Works with `cargo install` (no special flags)
 
-Evaluated options:
+## Options
 
-| | **log** | **tracing** | **emit** | **fastrace** | **custom** |
-|---|---------|-------------|----------|--------------|------------|
-| **Structured data** | ❌ kv unstable since 2019 | ❌ valuable unstable since 2022 | ✅ Native serde | ❌ | ✅ |
-| **Your structs/enums** | ❌ | ❌ | ✅ | ❌ | ✅ |
-| **cargo install works** | ✅ | ❌ needs RUSTFLAGS | ✅ | ✅ | ✅ |
-| **API complexity** | Minimal | High | Medium | Low | Minimal |
-| **Stability** | Stable | Features stuck 3+ years | Stable | API unstable | N/A |
+**tracing**: Rich ecosystem, but `valuable` feature (needed for custom structs) requires `RUSTFLAGS="--cfg tracing_unstable"`. Breaks `cargo install`. Rejected.
 
-tracing's `valuable` feature requires `RUSTFLAGS="--cfg tracing_unstable"` for all downstream users. This broke `cargo install http-nu`.
+**emit**: Viable. Native serde, stable, works with cargo install. Provides emit_term (human) and emit_file (rolling JSONL to files). However:
+- emit_file targets files, not stdout
+- We'd need a custom emitter for stdout JSONL anyway
+- Rate-limiting for human output not built-in
+- Adds dependency for ~300 lines of purpose-built code
+
+**custom**: Typed Event enum, broadcast channel, dedicated handler threads. Simple, fits exact requirements.
 
 ## Decision
 
-Custom event system with broadcast channel and dedicated handler threads:
+Custom event system. Typed events, broadcast to handler threads:
 
 ```rust
 pub enum Event {
-    Request { request_id: Scru128Id, method: String, path: String, ... },
+    Request { request_id: Scru128Id, request: Box<RequestData> },
     Response { request_id: Scru128Id, status: u16, latency_ms: u64, ... },
     Complete { request_id: Scru128Id, bytes: u64, duration_ms: u64 },
     Started { address: String, startup_ms: u64 },
     // ...
 }
 
-// Non-blocking emit via broadcast channel
 fn emit(event: Event) {
     if let Some(tx) = SENDER.get() {
-        let _ = tx.send(event);
+        let _ = tx.send(event); // non-blocking
     }
 }
-
-// Handlers run in dedicated threads
-pub fn run_jsonl_handler(rx: broadcast::Receiver<Event>) {
-    std::thread::spawn(move || { /* blocking_recv + serialize + write */ });
-}
 ```
 
 ## Architecture
@@ -57,22 +51,12 @@ Request Path                    Handler Thread
   continue                     serialize + write
 ```
 
-### JSONL Handler
-- Dedicated thread with `blocking_recv()`
-- BufWriter with idle flush (flush when channel empty)
-- Sustains 24K+ requests/sec without drops
-
-### Human Handler
-- Dedicated thread with `blocking_recv()`
-- Rate limited to ~10 requests/sec (human-readable pace)
-- Skipped requests tracked, periodically prints `... skipped N requests`
-- Once a request is shown, its full lifecycle (Request→Response→Complete) completes
-
-## Rationale
-
-- **Non-blocking emit**: Request path just sends to channel, never waits
-- **Dedicated threads**: Serialization and I/O off the async runtime
-- **Idle flush**: Responsive under low load, efficient under high load
-- **Rate limiting for human**: No point showing 60K req/sec to humans
-- **Complete lifecycle**: Skipping happens at Request level; shown requests always complete
-- **No unstable features**: Works with plain `cargo install`
+**JSONL handler**: Dedicated thread, BufWriter, flushes when channel empty. 24K+ req/sec sustained.
+
+**Human handler**: Dedicated thread, rate-limited to ~10 req/sec. Tracks skipped requests. Once shown, a request's full lifecycle completes.
+
+## Tradeoffs
+
+- Events are cloned at emit (headers→HashMap, IPs→String). Acceptable at current throughput.
+- No file rotation, OTLP, or other emit features. Not needed—stdout only.
+- ~300 lines to maintain vs external dependency.