From 77b59d89e22d464d7285a2b0cb823caf110f3da6 Mon Sep 17 00:00:00 2001 From: Erik Date: Sat, 2 May 2026 16:14:05 +0200 Subject: [PATCH] =?UTF-8?q?docs(roadmap):=20Phase=20M=20=E2=80=94=20Networ?= =?UTF-8?q?k=20Stack=20Conformance=20plan?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- docs/plans/2026-04-11-roadmap.md | 103 ++++++++++++++++++++++++++++++- 1 file changed, 102 insertions(+), 1 deletion(-) diff --git a/docs/plans/2026-04-11-roadmap.md b/docs/plans/2026-04-11-roadmap.md index a75fd3f..91f7100 100644 --- a/docs/plans/2026-04-11-roadmap.md +++ b/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** |