Add ADR-014: Event journal (recording and replay)

[diego3]

Summary

Proposes docs/adr/ADR_014_event_journal.md: options and tradeoffs for a recording/replay
capability, prompted by comparing frame's event bus architecture to a classic id Software
(Quake III Arena-style) engine diagram — Input -> Event Queue -> {Server, Client}, with an
Event Journal hanging off the queue for demo recording/replay.

Why this is worth writing down now, even though nothing needs it yet

This ADR is explicit about being speculative — no games/metalslug_demo/ideas.md TODO is
blocked on it. It exists because the architecture comparison exposed a real gap (frame has zero
recording/replay capability today), the same way ADR-010 opened from "we want visibility" rather
than a blocking bug. The point of writing it now is so a future concrete trigger (a
hard-to-reproduce bug, wanting a highlight-clip feature, or actually starting ADR-004's
peer-to-peer networking) picks from an already-considered set of options instead of re-litigating
from scratch under time pressure.

What's inside

Four approaches, each with a pros/cons table, following the same format ADR-010 uses:

1. Record only intents, replay by re-simulating (the actual Quake demo-file mechanism) —
   smallest recordings, doubles as ADR-004's peer-to-peer networking foundation, but requires the
   simulation to be bit-for-bit deterministic — which isn't currently true:
   frameengine/view/camera/shake.go calls rand.Float64() from Go's default, unseeded global
   source. Cosmetic today, but it's live proof nothing here guarantees reproducible randomness.
2. Record every bus event, replay by direct playback — bigger recordings, but correct
   immediately with no determinism dependency; good for bug-repro, useless for netcode.
3. Periodic full-state snapshots — the only option enabling scrub/seek, but needs Box2D
   world-state save/restore that doesn't exist yet; heaviest by far.
4. Defer — build nothing now.

Recommendation: defer (Approach 4) for now, since there's no concrete trigger and Approach
1 — the option actually worth building deliberately — is gated on a determinism audit that isn't
even scoped yet. Fall back to Approach 2 as the pragmatic first cut if a real need shows up
before that audit happens; revisit Approach 1 specifically once ADR-004's networking work is
actually pursued, since the audit becomes a hard requirement there anyway.

Also includes a comparison table, Open Questions (hook point, always-on ring buffer vs.
explicit start/stop, serialization format, WASM support), Consequences, and References back to
ADR-002 (event bus), ADR-004 (networking), ADR-006 (constraints), ADR-007 (precedent for
deferring speculative infrastructure), and ADR-010 (sibling options/tradeoffs ADR this follows
the format of).

Scope

Docs-only (one new file); no code changes. Branches from main, no dependency on any other open
PR.

---

Generated by Claude Code

[cursor]

Bugbot is not enabled for your account, so this pull request was not reviewed.

Enable Bugbot in the Cursor dashboard to get automatic reviews on future PRs.