docs(roadmap): Phase M — Network Stack Conformance plan

Adds the Phase M planning entry: replace the happy-path WorldSession
shape with a holtburger-aligned reliable network stack while keeping
acdream's stricter checksum verification + live ACE compatibility.
Lays out M.1–M.x sub-lanes (audit/parity map, layer extraction,
reliability core, etc.).

Detailed spec to land at
docs/superpowers/specs/2026-05-02-network-stack-conformance.md
before implementation starts. Holtburger is the client-behavior
oracle for this phase.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

docs/plans/2026-04-11-roadmap.md

@@ -1,6 +1,6 @@
 # acdream — strategic roadmap
 
-**Status:** Living document. Updated 2026-04-29 for Phase L.2 movement/collision conformance planning.
+**Status:** Living document. Updated 2026-05-02 for Phase M network-stack conformance planning.
 **Purpose:** One source of truth for where the project is and where it's going. Every observed defect or missing feature has a named phase that owns it; when something looks wrong in-game, look here to find the phase that'll address it. Implementation details live in per-phase specs under `docs/superpowers/specs/`, not in this file.
 
 ---
@@ -403,6 +403,101 @@ diagnostic scaffolding, not yet the final collision system.
 
 ---
 
+### Phase M — Network Stack Conformance
+
+**Status:** PLANNED.
+
+**Goal:** replace the current happy-path `WorldSession` networking shape with a
+proper AC client network stack that reaches functional parity with
+`references/holtburger/` while preserving acdream's stricter packet checksum
+verification and live ACE compatibility. This phase owns packet reliability,
+ordered delivery, retransmission, ACK piggybacking, echo/keepalive, typed
+message/action routing, diagnostics, and the migration of low-level network
+responsibilities out of the render tick.
+
+**Why now:** The Phase 4/A.3 stack is good enough for local ACE smoke testing:
+login, ISAAC, checksums, per-packet ACKs, fragments, movement, chat, combat,
+and object updates all work. It is not yet a complete client network runtime.
+Compared with holtburger it lacks ordered S2C delivery, retransmit request
+handling, outbound packet caching/retransmission, ACK piggybacking,
+EchoRequest/EchoResponse handling, runtime ping/timeout policy, and a typed
+protocol/action layer. These gaps will become expensive as movement, dungeons,
+inventory, combat, and plugins depend on stable packet semantics.
+
+**Plan of record:** create
+`docs/superpowers/specs/2026-05-02-network-stack-conformance.md` before
+implementation starts. Treat holtburger as the client-behavior oracle for this
+phase; cross-check wire details against named retail, ACE, Chorizite, and AC2D
+before porting.
+
+**Sub-lanes:**
+- **M.1 — Audit & parity map.** Produce a source-by-source comparison of
+  acdream `AcDream.Core.Net` and holtburger `holtburger-session`,
+  `holtburger-protocol`, and `holtburger-core` networking code. Inventory each
+  packet flag, optional header, session transition, control packet, fragment
+  path, game message, and game action. Mark each as `parity`, `partial`,
+  `missing`, or `intentional divergence`.
+- **M.2 — Layer extraction.** Split the low-level stack under `WorldSession`
+  into testable components: `INetTransport`, `PacketCodec`,
+  `ReliablePacketSession`, `FragmentSession`, `GameMessageSession`, and the
+  high-level `WorldSession` behavior layer. Preserve existing public events and
+  live-client call sites during the migration.
+- **M.3 — Reliability core.** Port holtburger-style sequence tracking:
+  last-delivered server sequence, duplicate/old-packet suppression,
+  out-of-order buffering, missing-sequence detection, throttled
+  `RequestRetransmit`, outbound packet cache, server-requested C2S retransmit,
+  `RejectRetransmit` handling, and retransmission checksum recomputation.
+- **M.4 — ACK and control-packet policy.** Replace standalone-only ACKs with
+  queued ACK state, ACK piggybacking on normal outbound packets, standalone ACK
+  flush when idle, and clean handling for ACK-only packets. Add EchoRequest /
+  EchoResponse and idle ping/timeout behavior matching holtburger unless named
+  retail proves a different cadence.
+- **M.5 — Fragment and payload completeness.** Keep inbound multi-fragment
+  assembly, add TTL/eviction diagnostics for orphaned partials, implement
+  outbound multi-fragment splitting when payloads exceed the current single
+  fragment limit, and verify fragment id/sequence/queue behavior against
+  holtburger, ACE, and retail evidence.
+- **M.6 — Typed protocol surface.** Introduce typed `GameMessage` and
+  `GameAction` routing modeled on holtburger. Migrate current builders and
+  parsers first: login complete, DDD, movement, chat/TurbineChat, combat,
+  spellcast, item/appraise, object/update/motion/position, and teleport.
+  Unknown opcodes must remain observable and non-fatal.
+- **M.7 — Runtime loop and diagnostics.** Move decode/order/reassembly/control
+  handling out of the render tick into a dedicated network runtime that emits
+  clean session events through channels. Add byte counters, packet trace hooks,
+  optional capture/replay fixtures, idle/disconnect state, and dev-panel
+  diagnostics suitable for packet debugging.
+- **M.8 — Conformance tests and live validation.** Add deterministic unit tests
+  for checksum, ISAAC key consumption, optional headers, ordering, retransmit,
+  ACK piggybacking, echo, fragments, typed actions, and login flow. Add
+  replay/capture tests from holtburger-style fixtures where possible. Finish
+  with `dotnet build`, `dotnet test`, local ACE login, chat, movement, combat
+  action smoke test, reconnect test, and user visual sign-off where networking
+  affects the running client.
+
+**Non-goals:**
+- Do not reimplement ACE server behavior.
+- Do not replace acdream's stricter inbound checksum verification unless named
+  retail proves it is wrong.
+- Do not rewrite renderer/gameplay systems as part of this phase; migrate
+  network call sites through compatibility adapters first.
+- Do not remove unknown-message visibility. Plugins and devtools need packet
+  trace surfaces even when parsers are incomplete.
+
+**Acceptance:**
+- acdream has a layered, testable network stack rather than one monolithic
+  `WorldSession`.
+- Every holtburger session capability has an acdream equivalent, an explicit
+  test, or a documented intentional divergence with retail/ACE evidence.
+- Packet ordering, retransmit, outbound cache, ACK piggybacking, echo/keepalive,
+  fragment assembly/splitting, and typed message/action routing are covered by
+  tests.
+- Live ACE loop succeeds: login, enter world, movement, chat, combat action,
+  teleport/reconnect, and clean logout.
+- `dotnet build` and `dotnet test` are green for every implementation slice.
+
+---
+
 ### Phase J — Long-tail (deferred / low-priority)
 
 Not detailed here; each gets its own brainstorm when it becomes relevant.
@@ -486,6 +581,12 @@ port in any phase — no separate listing here.
 | Can't walk past the loaded 3×3 window | **A.1 FIXED** ✓ (5×5 default, `ACDREAM_STREAM_RADIUS` to tune) |
 | Frame hitch crossing landblock boundary | **Phase A.3** (synchronous loader for now; async returns when DatCollection is thread-safe) |
 | Walking around doesn't move me on the server | **Phase B.2/B.3 FIXED** ✓ for coarse server movement; fine retail collision parity is **Phase L.2** |
+| Packet loss / out-of-order UDP causes stale or missing world updates | **Phase M.3** |
+| Server asks for retransmit and client doesn't resend cached packets | **Phase M.3** |
+| ACKs are standalone-only instead of piggybacked like a full client | **Phase M.4** |
+| Echo / idle keepalive / reconnect behavior is incomplete | **Phase M.4 + M.7** |
+| Large outbound game messages exceed the current single-fragment path | **Phase M.5** |
+| Network protocol coverage is spread across ad-hoc builders/parsers | **Phase M.6** |
 | Sliding along buildings / walls feels wrong | **Phase L.2c + L.2d** |
 | Roof edge / cliff / precipice blocks or slides wrong | **Phase L.2c** |
 | Crossing outdoor cell seams reports the wrong cell | **Phase L.2e** |