# Phase 4: Server Rebuild (MVP) - Discussion Log

> **Audit trail only.** Do not use as input to planning, research, or execution agents.
> Decisions are captured in `04-CONTEXT.md` — this log preserves the alternatives considered.

**Date:** 2026-05-05
**Phase:** 04-server-rebuild-mvp
**Areas discussed:** Wire/state model split, Auth + Colyseus integration, Room layout wire format (SRV-13), Persistence write cadence

---

## Gray Area Selection

| Option | Description | Selected |
|--------|-------------|----------|
| Wire/state model split | Where does @colyseus/schema (state-diff sync: positions, platforms) end and msgpackr (intent messages: input vectors, chat-send, room-join, login) begin? Locks packages/protocol API shape — Phase 6 client cannot revisit. | (delegated) |
| Auth + Colyseus integration | Better-Auth uses HTTP/cookie sessions; Colyseus uses WS handshake. Token-via-query-param + Colyseus onAuth fetches Better-Auth session? Or full HTTP login then upgrade to WS with session cookie? Affects login flow forever. | (delegated) |
| Room layout wire format (SRV-13) | Extracted GM5 rooms → server-side canonical format → wire frame on room-entry. Build-time JSON committed to apps/server/rooms/, or runtime-loaded from extracted/? Integrity: signed manifest hash vs per-frame checksum? Phase 7 PAR-03 drops into this contract with no protocol changes. | (delegated) |
| Persistence write cadence | When does the server flush to SQLite? On-tick (50ms — too hot), checkpoint interval (every N seconds), event-driven (state-change), SIGTERM-only? Determines RPO surface for SRV-08 crash recovery and Litestream replication frequency. | (delegated) |

**User's choice:** Free-text — "agent decides all using best judgment. push for modern best practices and setting up for frictionless UX. for server-side rooms, ensure they can be safely edited and reloaded during runtime without fully restarting the server."

**Notes:** All four areas delegated to Claude's discretion. Two explicit steers:
1. **Modern best practices + frictionless UX** — applied across all four areas.
2. **Server-side rooms must support edit-and-reload at runtime without restarting the server** — a NEW requirement beyond SRV-13's wire-format spec; locked as D-09..D-13 (fs.watch + atomic-rename writes from `tools/room-converter` + Ed25519-verified hot-broadcast + ADR 0004 to make it un-regressable).

---

## Claude's Discretion

All four discussed areas plus the broader monorepo + tooling surface (D-18..D-25) were resolved on Claude's discretion grounded in:
- `.planning/research/STACK.md` (version pins)
- `.planning/research/PITFALLS.md` §B1 (server-authoritative discipline)
- ADR 0001 / 0002 / 0003 (locked Phase 2/3 decisions)
- Phase 1 D-15 / D-17 / D-19 (deterministic output, standalone tools, thin wrappers)
- Phase 2 D-04 / D-09 / D-11 / D-13 (mvp tagging, subsystem MDs, AUTOGEN, lint forcing functions)
- Phase 3 D-04 (staging-table read-once-then-purge), D-05 / D-06 (protocol artifacts), D-09 (save-format artifacts), D-13 (Drizzle baseline), D-18 (parity checklist mvp scope), D-20 (admin-anti-port modernized surface), D-22 (lint forcing functions)
- CLAUDE.md hard rules #1 (server-authoritative), #2 (no plaintext password port), #3 (no Ctrl+E admin port), #6 (extract → document → rewrite)
- OWASP 2026 Argon2id #1 recommendation

## Deferred Ideas

- Full chat surface (whispers, channels, ignore/block, profanity, history) → Phase 7 PAR-04
- `.bnu` per-user transactional character migration → Phase 7 PAR-05
- Modernized admin web UI → Phase 7 PAR-07
- Multi-region Fly / sharding / Postgres → v2 (OPS-01..03)
- Asset pipeline (BMP→PNG, MIDI→OGG, fonts→WOFF2) → Phase 6 / 7
- `apps/client` scaffold + Vite + Phaser → Phase 6
- Fly.io Dockerfile hardening + fly.toml + Litestream sidecar + RESTORE.md + GitHub Actions → Phase 5
- Wireshark validation of derived protocol → optional, Phase 6 dogfood
- Postgres migration / LiteFS replicas → v2
- Public username changes / OAuth / passkeys → Phase 7 PAR-06 + v2
- Fixed-point math (rejected — float math deterministic per-platform on V8; revisit only if Phase 6 cross-browser breaks it)