erik/acdream
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs(phase-m): sharpen Phase M into design spec + opcode coverage matrix

Browse source 
Captures Phase M (Network Stack Conformance) as a fully-formed phase
ready to be picked up later. Three deliverables:

1. Design spec at docs/superpowers/specs/2026-05-10-phase-m-network-stack-design.md
   (~700 lines, 8 sections):
   - Bar C completeness target ("wireable on demand"): every wire opcode
     a 2013 EoR retail client receives or sends gets a parser/builder +
     golden-vector test + typed event in the new layered stack.
   - Three-layer architecture: INetTransport / IReliableSession /
     IGameProtocol, with WorldSession as a thin behavior consumer.
     Concrete C# interface signatures, sub-component decomposition.
   - Worktree-branch big-bang migration on claude/phase-m-network-stack;
     weekly rebase cadence; single --no-ff merge ships the phase.
   - Per-sub-phase entry/exit gates, conformance test plan (golden vectors
     + live capture replay + live ACE smoke), 10-row risk register, scope-
     cut order if calendar compresses.
   - Cost: 256 hours / ~6.4 weeks single-developer; 4-6 weeks calendar
     with subagent parallelization on M.1 + M.6.

2. Opcode coverage matrix at docs/research/2026-05-10-phase-m-opcode-matrix.md
   (~284 rows across 5 sections):
   - Section 1: 22 transport flags (14 implemented).
   - Section 2: 12 optional-header fields (10 partial).
   - Section 3: 51 top-level GameMessages (21 implemented).
   - Section 4: 103 GameEvent sub-opcodes inside 0xF7B0 (27 parsed,
     26 wired).
   - Section 5: 96 GameAction sub-opcodes inside 0xF7B1 (24 built,
     8 with live callers).
   - Roll-up: ~34% complete by raw opcode count. Biggest single
     unblocking step is wiring the 16 dead builders in section 5
     (Phase B.4 surface — Use / UseWithTarget / Allegiance / Inventory
     / Social / Cast / Appraise).
   - Sources cited per row: holtburger (629695a), ACE, named retail
     decomp, acdream current state.
   - Produced by 4 parallel research agents (one per class). Spot-check
     pass owed before M.1 closes.

3. Roadmap update: Phase M section trimmed to summary + status + pointer
   to the spec; the previously-tracked M.0 Tier 1 quick-wins are folded
   into M.3 / M.4 / M.6 per the spec; M.1 retained as the matrix
   construction sub-lane with status note.

Why this shape: the user goal is a complete, layered, testable network
stack that can be wired in as gameplay phases need it — independent of
whether each opcode is yet hooked to game state. The matrix is the
source of truth for "done"; the spec is the architecture the matrix
implements against; the roadmap is the index that points at both.

Decisions captured during the design discussion (in case they need
revisiting):
- Bar C ("wireable on demand") chosen over Bar A (holtburger parity)
  or Bar B (named-retail completeness).
- Three layers (INetTransport / IReliableSession / IGameProtocol)
  chosen over holtburger's two-layer split.
- Big-bang on a feature branch (worktree) chosen over strangler
  pattern; preserves live-ACE testing on main throughout the phase.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Erik 2026-05-10 19:22:49 +02:00
parent b8b9845f50
commit c7021d8645
3 changed files with 1360 additions and 48 deletions
Download patch file Download diff file Expand all files Collapse all files

79
docs/plans/2026-04-11-roadmap.md
View file

@ -432,57 +432,40 @@ 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.
**Plan of record:** Detailed design spec at
[`docs/superpowers/specs/2026-05-10-phase-m-network-stack-design.md`](../superpowers/specs/2026-05-10-phase-m-network-stack-design.md)
(supersedes the planned-but-never-written `2026-05-02-network-stack-conformance.md`
the original entry referenced). The spec defines: **Bar C** ("wireable on demand")
as the completeness target; a **three-layer architecture** (`INetTransport` /
`IReliableSession` / `IGameProtocol`) with `WorldSession` as a thin behavior
consumer on top; a **worktree-branch big-bang** migration model on
`claude/phase-m-network-stack` with weekly rebase cadence and single-merge ship;
per-sub-phase entry/exit gates with hour estimates; conformance test plan
(golden vectors + live capture replay + live ACE smoke); risk register; and a
**256-hour / ~6.4-week single-developer cost estimate** (4–6 weeks calendar
with subagent parallelization on M.1 and M.6). Treat holtburger as the
client-behavior oracle, ACE as server-outbound authority, named retail decomp
as wire-format ground truth.
**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).
last audit). First parity-pass at
[`docs/research/2026-05-10-holtburger-network-stack-study.md`](../research/2026-05-10-holtburger-network-stack-study.md);
formal opcode coverage matrix (M.1's main deliverable) under construction
at `docs/research/2026-05-10-phase-m-opcode-matrix.md` via parallel
class-by-class agent dispatch. Most relevant recent holtburger commits:
`99974cc` (session crate split + retransmit core), `403bc98` (port-switch
race), `336cbad` (turning + locomotion fix), `797aece` (disconnect
carries client_id). Six "Tier 1" quick-wins identified by the study
(originally tracked as M.0) are folded into M.3 / M.4 / M.6 per the
spec — they no longer ship as a separate sub-phase.
**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`. **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.**
**Sub-lanes:** *(brief summary; the spec has full entry/exit criteria,
conformance gates, and hour estimates for each.)*
- **M.1 — Audit & opcode matrix.** Build the per-opcode coverage table
citing holtburger / ACE / named retail / acdream-today / Phase M target.
Status: parity-pass done; matrix construction in flight via per-class
agent dispatch (transport flags + optional headers, GameMessages,
GameEvents, GameActions). 16h.
- **M.2 — Layer extraction.** Split the low-level stack under `WorldSession`
into testable components: `INetTransport`, `PacketCodec`,
`ReliablePacketSession`, `FragmentSession`, `GameMessageSession`, and the