docs(post-A.5): capture holtburger network-stack study + Phase M.0 quick-wins

Holtburger reference fast-forwarded from 88b19bd to 629695a (+237 commits).
Four parallel research agents produced a parity-first-pass between
holtburger's network stack and acdream's src/AcDream.Core.Net/.

Why captured now: study surfaced six small, high-confidence "Tier 1" fixes
that can ship before the bigger M.1-M.8 layer extraction. Most likely fix
for the longstanding "remote retail observer sees us not perfect" bug
(MoveToState wire-format mismatches). Two transport gaps (no EchoResponse
reply, eager port-switch) match recent holtburger fixes (403bc98, 99974cc).
One latent bug worth a 5-min check (ISAAC search-mode for out-of-order
ENCRYPTED_CHECKSUM packets).

Captured as Phase M.0 in the roadmap so the work survives the session and
can be picked up later. Existing M.1-M.8 lift unchanged; M.1 marked as
partially started since the research note is the parity-map deliverable
in draft form.

Files:
- docs/research/2026-05-10-holtburger-network-stack-study.md (new) — full
  study with ranked port candidates, recent commits worth knowing, and
  acdream-vs-holtburger file map.
- docs/plans/2026-04-11-roadmap.md — Phase M Plan-of-record updated with
  2026-05-10 pointer; M.0 sub-lane added before M.1; M.1 status note.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Erik 2026-05-10 17:52:26 +02:00
parent f66522cd6b
commit b8b9845f50
2 changed files with 216 additions and 1 deletions

View file

@ -438,13 +438,51 @@ 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.
**2026-05-10 update:** holtburger pulled to `629695a` (+237 commits since
last audit). First parity-pass written to
[`docs/research/2026-05-10-holtburger-network-stack-study.md`](../research/2026-05-10-holtburger-network-stack-study.md)
— that doc is the M.1 deliverable in draft form. Study identified six
high-ROI "Tier 1" fixes that are individually small and can ship as a
focused pre-pass before the bigger M.1-M.8 lift; tracked as **M.0** below.
Most relevant recent holtburger commits to consult: `99974cc` (session
crate split + retransmit core), `403bc98` (port-switch race), `336cbad`
(turning + locomotion fix), `797aece` (disconnect carries client_id).
**Sub-lanes:**
- **M.0 — Tier 1 quick-win polish pre-pass.** Six small, high-confidence
fixes that don't require the full M.1-M.8 layer extraction and can ship
as one focused PR (~1 day). Sourced from
[`docs/research/2026-05-10-holtburger-network-stack-study.md`](../research/2026-05-10-holtburger-network-stack-study.md)
§1 Tier 1. May ship independently of M.1-M.8.
1. **MoveToState wire-format audit** (study §1.1.a-e). Side-by-side
compare `Messages/MoveToState.cs` against holtburger
`client/movement/common.rs:122-186`. Pin: `current_hold_key` always
set, empty `commands[]` on held WASD, `turn_speed` always with
TURN_COMMAND, gait-aware dedup, no `turning` when locomotion ≠ 0.
Likely candidate for the longstanding "remote retail observer sees
us not perfect" bug.
2. **LoginComplete on every PlayerTeleport** (study §1.2). Currently
only sent on first PlayerCreate.
3. **EchoRequest → EchoResponse reply** (study §1.3). We parse and
ignore; ACE pings periodically — likely contributor to long-session
timeouts.
4. **Port-switch race fix** (study §1.4, holtburger commit `403bc98`).
Track pending vs confirmed `_connectEndpoint`.
5. **Disconnect packet carries client_id** (study §4, holtburger commit
`797aece`). Currently `id = 0`.
6. **Verify `IsaacRandom` has search-and-stash mode for out-of-order
ENCRYPTED_CHECKSUM packets** (study §1.7, holtburger
`crypto.rs:73-93`). 5-minute check; ~20 LOC port if missing —
latent bug under any UDP reorder event.
- **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`.
`missing`, or `intentional divergence`. **Status (2026-05-10): first pass
done at [`docs/research/2026-05-10-holtburger-network-stack-study.md`](../research/2026-05-10-holtburger-network-stack-study.md);
the formal parity table can extend that doc rather than start from
scratch.**
- **M.2 — Layer extraction.** Split the low-level stack under `WorldSession`
into testable components: `INetTransport`, `PacketCodec`,
`ReliablePacketSession`, `FragmentSession`, `GameMessageSession`, and the