# acdream — project instructions for Claude

## Goal

Build **acdream**, a modern open-source C# .NET 10 Asheron's Call client.
A faithful port of the retail AC client's behavior to modern C# + Silk.NET,
with a plugin API the original never had.

**The code is modern. The behavior is retail.**

Every AC-specific algorithm is ported from the **named retail decomp**
at `docs/research/named-retail/` — Sept 2013 EoR build PDB (18,366
named functions, 5,371 named struct/class types) + Binary Ninja
pseudo-C with 99.6% function-name recovery + verbatim retail header
struct definitions. The older Ghidra `FUN_xxx` chunks under
`docs/research/decompiled/` (22,225 functions, 688K lines) remain a
fallback for chunk-by-chunk address-range navigation. **Grep
`named-retail/acclient_2013_pseudo_c.txt` by `class::method` BEFORE
decompiling fresh.** The code around those algorithms is modern C#
with clean architecture. The plugin API exposes game state through
well-defined interfaces.

**Architecture:** `docs/architecture/acdream-architecture.md` is the
single source of truth for how the client is structured. All work must
align with this document. When the architecture doc and reality diverge,
update one or the other — never leave them out of sync.

**WorldBuilder code lives in our tree.** Phase O extracted ~33 WB files
(~7.7K LOC) into our own namespaces and dropped the two external project
references. `DatCollection` is the **only** dat reader in process —
`DefaultDatReaderWriter` is gone. `references/WorldBuilder/` remains
in-tree as a read-reference (MIT-licensed; grep it freely), but nothing
in `src/AcDream.*` references it as a project dependency.

**Where the extracted code lives (post-Phase O):**
- `src/AcDream.Core/Rendering/Wb/` — pure dat/mesh helpers (5 files,
  ~782 LOC): `TerrainUtils`, `TerrainEntry`, `RegionInfo`,
  `SceneryHelpers`, `TextureHelpers`. No GL dependency; safe to use
  from Core.
- `src/AcDream.App/Rendering/Wb/` — GL infrastructure + mesh pipeline
  (~27 files, ~7K LOC): `ObjectMeshManager`, `WbMeshAdapter`,
  `WbDrawDispatcher`, `LandblockSpawnAdapter`, `EntitySpawnAdapter`,
  `TextureCache`, `GlobalMeshBuffer`, shader infrastructure, and the
  EnvCell/portal/scenery/terrain-blending pipeline classes.

**Modern rendering path is MANDATORY.** The N.5 ship amendment deleted
`WbFoundationFlag`, `InstancedMeshRenderer`, and `StaticMeshRenderer`;
Campaign V (`docs/plans/2026-07-27-vulkan-campaign.md`, closed
2026-07-29) then ported the renderer to Vulkan behind the RHI contract
and deleted the OpenGL backend outright — `AcDream.App` references only
`Silk.NET.Vulkan`. There is no legacy fallback. Engineering cribs
(WbMeshAdapter seams, N.5 SSBO layout, translucency model, gotchas)
live in `memory/reference_modern_rendering_pipeline.md`.

Before re-implementing any AC-specific rendering or dat-handling
algorithm, **read `docs/architecture/worldbuilder-inventory.md` FIRST**.
The inventory describes what we extracted (now in our tree) and what we
still write ourselves. Re-porting from retail decomp when we already
have a tested port is how subtle bugs (the scenery edge-vertex bug, the
triangle-Z bug) keep slipping in. Retail decomp remains the oracle for
network, physics, animation, movement, UI, plugin, audio, chat — see
the inventory doc's 🔴 list.

**Execution model:** the active source of truth is the **milestones doc**
(`docs/plans/2026-05-12-milestones.md`) for "what are we building right
now" and the **strategic roadmap** (`docs/plans/2026-04-11-roadmap.md`)
for the per-phase ledger of what's shipped, what's in flight, and what
comes next. **Ignore the old "R1→R8" sequence** — it was an early refactor
sketch that no longer matches reality (see the "Roadmap Model" section in
`docs/architecture/acdream-architecture.md`). Per-phase detailed specs
live under `docs/superpowers/specs/`.

The codebase is organized by layer (see architecture doc + the **Code
Structure Rules** section below). Plans live in `docs/plans/`,
research in `docs/research/`, persistent project memory in `memory/`
and `~/.claude/projects/.../memory/` (the latter is browsable in
Obsidian via the `claude-memory/` junction in the repo root; see
`memory/reference_obsidian_vault.md`).

**UI strategy:** one presentation stack — the retained retail
`UiHost`/`UiRoot` tree in `AcDream.App/UI`, imported from LayoutDesc/DAT
assets and bound by focused controllers over shared state, ViewModels,
events, and commands (the ViewModels/commands seam from the earlier
two-stack era remains the stable boundary between state and
presentation). The ImGui.NET developer-tools frontend
(`AcDream.UI.ImGui`) and the OpenGL backend it required were deleted at
Campaign V slice V11 (`docs/plans/2026-07-27-vulkan-campaign.md`);
`ACDREAM_DEVTOOLS=1` now only selects the optional Vulkan
validation/debug-utils extensions (see the flag's log line in
`Program.cs`). `TextRenderer` + `BitmapFont` serve D.6 world-space HUD
elements in the 3D scene. Plugin gameplay UI uses the BCL-only
`AcDream.Plugin.Abstractions.IUiRegistry.AddMarkupPanel` contract; plugins
never import App namespaces. Full design:
[`docs/plans/2026-04-24-ui-framework.md`](docs/plans/2026-04-24-ui-framework.md).
Memory cribs: `claude-memory/project_chat_pipeline.md` (chat pipeline as of
Phase I), `claude-memory/project_input_pipeline.md` (input pipeline as of
Phase K).

**Input pipeline:** `src/AcDream.UI.Abstractions/Input/` (action enum,
`KeyChord`, `KeyBindings`, multicast `InputDispatcher` with scope
stack + modal capture for rebind UX) + `src/AcDream.App/Input/`
(Silk.NET adapters). Retail-default keymap loaded from
`%LOCALAPPDATA%\acdream\keybinds.json` at startup (falls back to
`KeyBindings.RetailDefaults()` matching
`docs/research/named-retail/retail-default.keymap.txt`). The Settings
panel (F11 / View → Settings) lets users remap any action via
click-to-rebind. As of Phase K, ALL keyboard / mouse input flows
through the dispatcher — no IsKeyPressed polling outside the per-frame
movement queries.

## Current state

**M3 — Cast a spell LANDED 2026-07-21. M4 — Live in the world ACTIVE.** Retail
casting, spellbook/component-book UI, active effects, recall/portal-space
presentation, the R6 locomotion/collision/projectile/teleport/radar rebaseline,
and the final two-client portal-out/materialization observer flow are
user-gated. Deterministic world-lifecycle automation protects fresh login,
outdoor/world-edge/dungeon travel, same-location revisit, exact graceful
disconnect, and uncapped fresh-process reconnect with JSON/PNG artifacts.
Release builds; the current performance-program checkpoint passes
3,763 App tests / 3 skips and 8,826 complete-solution tests / 5 skips.

**M4 feature work order (active after the Modern Runtime closeout and Slice L
deferral):** the six-slice pre-M4 world-interaction completion
program in `docs/plans/2026-07-23-world-interaction-completion.md`: favorite
spell-bar overflow, status Use/Assess, assessment information,
equipped-child picking, vendor browsing, and authoritative vendor
transactions. Slices 1–3 plus the adjacent shared-cooldown presentation are
user-accepted, including exact response flags, independent examination
window, inscription transaction, complete creature/item/spell reports,
favorite-spell press/right-click behavior, modern scarab/prismatic formula,
DAT component icons, foreground stacking, and authored 310 x 400 extent.
Slice 4 equipped-child world picking passed its two-client Coldeve gate and
was user-accepted 2026-07-29. **Slices 5 and 6 (the complete vendor
experience — browse, staged buying, selling, walk-to-use, the authored
panel) closed user-accepted 2026-08-08; the six-slice program is COMPLETE
(see the plan's PROGRAM CLOSEOUT). The vendor arc also exposed and fixed
two latent client-wide crashers (#348 cursor-handle exhaustion, #350
render-ledger overflow).** **Campaign P — physics retail-feel parity
(`docs/plans/2026-07-29-physics-parity-campaign.md`) is CLOSED 2026-07-31
— final user matrix accepted.** Every physics-scope gap from the
2026-07-29 audit landed and user-gated: #266 run speed (retail's ==800
sentinel — ACE's >=800 is a misread; never re-import), the #265/#166
landing-momentum + bounce family
(`docs/research/2026-07-30-landing-bounce-family.md`), the #267 vitae
panel, #268 (panel colors + augmentation bonuses), #269 (slope-stop slide
— the live-trace contact-plane-restore fix), and TS-8 (0x02C2 StatMod
parse). See the plan doc for the retired-row ledger. **Campaign A — audio
retail parity (`docs/plans/2026-08-08-audio-parity-campaign.md`) is
CODE-COMPLETE 2026-08-08** with slices A1–A6 landed and listening-gate
rounds user-driven; open tail: #358 (Ctrl+M mute chord never fires) and
the formal plan-status flip. **Campaign CH — chat & interface-text retail
parity (`docs/plans/2026-08-09-chat-parity-campaign.md`) is CLOSED
USER-ACCEPTED 2026-08-10** after five connected gate rounds: retail
colors, the SpewBox with retail's two-plane glyph outlines, working side
channels, the 152-verb command registry, the CH6 window shell (floating
windows, all-corner resize, opacity), and verbatim /help. Carried tail:
#360/#361, #366, #369, AP-177/190/191, and the round-5 review S1–S3
polish items. **Campaign OP — the retail four-tab Options panel
(`docs/plans/2026-08-10-options-panel-campaign.md`) is CODE-COMPLETE
2026-08-11.** Retail's Options panel (Gameplay Options / Character / Chat /
Config, LayoutDesc `0x2100002B`) plus the Configure Keyboard screen are
acdream's ONE in-client settings surface (design D1): F11/toolbar open the
authored tab host; `RuntimeCharacterOptionsState` + the 53-id
`CharacterOptionTable` own option storage; retail's wire split ships exactly
(21 auto-save ids → `0x0005` immediate, the rest ride the real `0x01A1`
PlayerModule blob with Apply/logout/480 s flushes, header always `0x460`);
headless bots declare options by name (OP7's live bot-vs-ACE gate PASSED);
OP9 retired the dead F11 `SettingsPanel`/`SettingsVM` surface and the
`GameplaySettings` record outright. OP1/OP2/OP7/OP9 CLOSED through dual/
combined Opus review. **2026-08-14 re-gate round:** the whole gate-4 fix
batch (#372 both halves, #374, #375, #378–#382, #385) is USER-PASSED; the
OP8 first look filed + same-day-fixed #394/#395/#396 (authored 18px-serif
row-caption font; the retail `GetNameFromKey` key-name pipeline — DAT
tables `0x2300000A`/`0x2300000B`/`0x23000007` via GetDIDByEnum category 4,
OS-localized fallback, register AD-96; the `InitiateBinding` capture-
instruction WAIT dialog) plus the WaitDialog-type-0x19 crash (`2a81e813`,
live-verified no-crash). **STILL OWED: the full §OP3–§OP6 script sections
and §OP8's visual re-check** — script
`docs/research/2026-08-11-campaign-op-test-script.md`, launch with
`ACDREAM_RETAIL_UI=1`. Tail:
#371, #373, AP-198/199/201/202/203. START at
`claude-memory/project_settings_options_digest.md`.

**Campaign FA — the retail social panel (Fellowship & Allegiance)
(`docs/plans/2026-08-11-fellowship-allegiance-campaign.md`) is
CODE-COMPLETE 2026-08-12.** Retail authors ONE four-tab `gmPanelUI` social
panel (Friends / Allegiance / Fellowship / Squelch, host slot
`0x1000018F`, id 12; F3 = Allegiance, F4 = Fellowship, keyboard-only —
Allegiance is the authored DEFAULT tab), mounted with the OP3 Options-panel
recipe. The Fellowship and Allegiance pages are LIVE end-to-end: real wire
(FA1 repaired the never-called H.2 builders + parsers — retail's FOUR
tree-rejection rules, ELEVEN version gates, the byte-decoded `>=9` size and
the truncated XP-share table), two session-scoped Runtime owners
(`RuntimeFellowshipState`/`RuntimeAllegianceState`, both clear at
generation reset — D2 corrected), and the authored panels through
`LayoutImporter`. Friends/Squelch bind read-only to J4.1's owners.
**The fellowship two-session flow is PROVEN over the live wire** — FA6's
automated bot-vs-ACE gate (`testaccount`/`+Acdream` + `testaccount2`/
`+Horan`) passed: the recruited bot's OWN `RuntimeFellowshipState` flips
`IsInFellowship`. Six FA slices, each dual-lens Opus reviewed → fix round →
narrow re-review; the reviews caught what tests can't (retail's 4th tree
rule, the D2 reset-lifetime inversion, the D6 server-side invite filter,
a seam-map entry that would have re-introduced a fixed bug). OWED: the
user's connected gates (§FA3-§FA6 of
`docs/research/2026-08-12-campaign-fa-test-script.md`, several
`[TWO-CLIENT]`), and **#384** — the allegiance-swear bot gate is
deferred/disabled because ACE returns NOTHING to the `0x001D` swear at
0.005 m (no confirmation, no tree update, no error; needs ACE-console
disambiguation — the swear CODE is done+reviewed, only its automated
two-session proof is unverified; register AD-87). Tail: #383 (installed-
DAT vs committed-fixture drift, found at FA3). START at
`claude-memory/project_fellowship_allegiance_campaign.md`.

**2026-08-13/14 gate block — SOCIAL GATES + SECURE TRADE all
USER-PASSED.** The social panel's connected gate rounds closed (border-only
move cursor, amber row selection, wrapped empty-state text, composed
confirmation sentences via the new `DatStringResolver.ResolveTemplate`
StringTable-interleave port, the refused-drop SpewBox notice via the
`InventoryTransactionState.RequestFailed` seam, live friends
Online/Offline through the authored row state machine + the new UiText
per-state string swap). Same block: powerbar mode captions
(jump 'Height' right-aligned per-STATE justify / 'Power'↔'Accuracy' by
combat mode), release-edge airborne jump refusal (supersedes CH round-1's
press-edge report), and **SECURE TRADE SHIPPED + two-client user gate
PASSED 2026-08-14** — gmSecureTradeUI window (LayoutDesc `0x2100000D`),
full `0x1F6`–`0x208` wire, `RuntimeTradeState` as the third sibling
J-owner, both retail open paths, staged-item trading marker
(`ClientObject.TradeState` now live), cancel text. START at
`claude-memory/project_secure_trade.md`; the deferred-Func lesson is
`claude-memory/feedback_resolve_deferred_funcs_per_call.md`. Register:
AD-93/AD-94 filed, AD-85 narrowed, AD-81 amended, AD-89/AD-95 retired.
Filed: #393 (texture-detail options, post-M4).

**Campaign LA — the alpha launcher (ACTIVE 2026-08-14):** Avalonia
launcher/installer/updater (Windows+Linux) + the retail character-
management screen, driven autonomously under a user-set goal: Fable
plans, Sonnet implements, Opus dual-lens reviews (architectural +
retail-faithful). Spec:
`docs/superpowers/specs/2026-08-14-launcher-campaign-design.md`; plan +
ledger: `docs/plans/2026-08-14-launcher-campaign.md`; START at
`claude-memory/project_launcher_direction.md`. Key recon corrections
already binding: retail's select screen (`gmCharacterManagementUI`) has
NO 3D preview (chargen-only machinery); UI Studio no longer exists
(deleted at Campaign V — ignore stale memory/docs claims otherwise);
App `Program.cs` has no subcommand dispatch (the `--session-config` flag
is additive).
LA0 through LA11's automated scope are review-closed. The launcher composer is now
compiled into both host test suites, and Launcher.Core runs in the portable
Windows/Ubuntu CI closure. The self-contained Avalonia launcher,
transactional two-host plugin lifetime, shared login-command route,
Runtime-owned retail selection state, authored DAT character screen, and
crash-safe verified installer plus atomic cross-platform updater/self-updater
are integrated. Windows group-isolated Headless stop, isolated update fixtures,
strict status/redaction evidence, and the exact Windows/Ubuntu operator script
are landed; the integrated preflight passes 32/32 commands and 14,012 tests /
5 skips. Only the connected/visual/real-DAT user gate remains before shipment.

**Campaign CC — retail character creation (CODE-COMPLETE 2026-08-16, all
seven slices REVIEW-CLOSED; the user's connected gate is the sole
outstanding acceptance step).** The full retail creation flow: Create
button (retail's exact `UpdateButtons` roster<slots ghost gate) →
`gmCharGenMainUI`'s six-page flow (Heritage / Profession / Skills /
Appearance with live 3D preview / Town / Summary with its own zoomed-out
viewport) → byte-exact 0xF656 with the 55-slot invariant → complete
0xF643 handling (roster append + retail log-straight-in; every rejection
dialog, incl. the corrected ground truth that retail shows NameDBDown
for Pending/Undef — the plan's original "retail swallows it" was
DISPROVEN at CC5's review) → the §LA1 `characterCreated`/`creationFailed`
launcher status cycle. `RandomizeCharacter` + sub-primitives are ported
(retail's ctor-time open-roll incl. the gender-flip quirk; humans-only
random heritage ids 1-4 — a real retail quirk). Plan + ledger:
`docs/plans/2026-08-15-character-creation-campaign.md`; connected gate
script: `docs/research/2026-08-16-campaign-cc-test-script.md` (launch:
launcher flow, or `ACDREAM_RETAIL_UI=1` + `ACDREAM_OPEN_CHARGEN=1`);
START at `claude-memory/project_character_creation_campaign_handoff.md`.
Register churn: AP-214/AP-225/TS-82/AD-101 retired; AP-211 updated;
AP-212 narrowed; AP-215–AP-229 filed (AP-221 one-shot preview binding,
AP-222 spin-highlight no-op, AP-229 stacked-screens-vs-retail-teardown
are the ones a gate tester will meet). Known-flake set now also names
`RuntimeCollisionReportingStateTests.WarmedSteadyContactRefreshDoesNotAllocate`
(full-solution parallel load only). Suites at `2176ba76`: full solution
14,426 / 4 skips, App 5257/3, Runtime 1735/0, Launcher.Core 324/0.

**Placement cutover — C4 COMPLETE 2026-08-05, merged to main.** Every
placement route now runs through the canonical residence + continuation-
executor owner. Routes landed this session: 4b-3 remote teleport/cell-less
(`6dc7ba51`), 6 drops (`1b484937`, zero production lines), 5 projectile
(`36255af0`), 7 child-cell propagation (`cd3129e9`), 3 portal
(`e0f96a55`), plus the `OnPosition` dual-tail collapse (`edc911b0`) that
retired the duplication behind three separate defects. Suite 11,027 →
**11,090 passed / 4 skipped / 0 failed**. Connected gates: routes 3, 6 and 7
user-passed 2026-08-05 with probe evidence; route 7's is THIN (one
`cause=propagate`) and 4b-3's `cause=cellless` case remains unrun with an
UNESTABLISHED trigger — route 7 invalidated its recorded recipe.
**C5 COMPLETE — the placement campaign is FULLY CLOSED (`addb5657`,
2026-08-07).** C5a deleted the legacy resolver outright and retired
AP-1/AP-145 (closing #318); C5b closed #275 and filed AP-147/AP-148; C5c's
closeout passed its 11,196-test automated gate and the owed connected-gate
batch USER-PASSED 2026-08-07. #280's portal-prefetch fix and its dual
review also landed (AP-149/150/151), and AP-22 retired 2026-08-06. Start
any new placement work at `claude-memory/project_placement_cutover_closed.md`
(probes deliberately NOT stripped; start at #331).

**Read `docs/research/2026-08-05-c4-closeout-handoff.md` before any
placement work.** Its seven process findings remain binding. The two that
cost the most that campaign: a contract asserting a mechanism that does not
exist caused three separate defects, and inferring a fact you can observe
made one fix strictly worse than the bug it replaced — it removed the
invariant failure while leaving the bug.

**Modern Runtime/performance status:** Slices A–K of
`docs/plans/2026-07-24-modern-runtime-architecture.md` are complete. Slice L is
parked at its L1 implementation checkpoint by user direction on 2026-07-27.
Production world-mesh streaming now consumes the validated machine-local
`acdream.pak` through `IPreparedAssetSource`; live DAT extraction remains
explicit bake/equivalence/UI-Studio tooling. Capped, uncapped, dense-Arwic,
lifetime, full-suite, and user-visual gates passed. Process allocation fell
41.8–61.9%, GC pause time fell 48.4–54.1%, uncapped CPU/GPU p99 improved
17.0%/20.6%, and invalid Setup-probe exceptions fell to zero. Slice D unified
typed residency policy/accounting and bounded retained caches. Slice E now
enforce typed completion admission, generation-scoped old-world quiescence,
metered full-window/recenter retirement, and retained cursor-budgeted
render/physics/static/building/EnvCell publication. The canonical reveal
generation now owns one exact destination reservation across every typed
budget dimension; incomplete portal destinations stay in the authored tunnel
and receive retail's centered wait cue instead of forced early reveal. E6
deterministic/resource suites, Release build, complete tests, capped/uncapped
nine-stop routes, and pinned dense Arwic pass on exact binary `91e82c3c`.
Every checkpoint converged without pending publication, retirement, upload,
warmup, or class backlog. The user explicitly approved Slices F–L, including
the F/G ECS and Slice J gameplay-owner gates, on 2026-07-24. G0–G5 are
complete. G4's 46,599-comparison automated gate has zero mismatches, the user
accepted the physical-display visual matrix, and G5 removed the production
`InteriorEntityPartition`. The ordinary production profile sustains 519.7 FPS
with CPU/GPU p50 1.869/1.096 ms and 652.1/928.3 MiB working/private memory.
The G5 profile's 22.34 KiB/frame remainder led into Slice I1. That slice is
now complete: player, remote, projectile, camera, and grounded
walkable-publication profiles each measure 0 B/resolve, with bit-identical
fresh-vs-reused results and complete reset/reentrancy gates. Slice I2 is also
complete: immutable physics/containment BSP, polygon, Setup, bounds, and
EnvCell-topology records preserve source float bits and ordering across
synthetic corruption gates and representative installed DATs without changing
production traversal. Slice I3 is complete: bake-tool 4 appends typed GfxObj,
Setup, CellStruct, and EnvCell-topology collision payloads; the collision
interface shares the render package's single mmap. Two complete
29,908,271,024-byte bakes produced 2,232,170 typed keys, zero failures, and the
same SHA-256 across 16 and 7 workers. Corruption, cancellation, installed
package, Release build, and 8,371-test / 5-skip gates pass.
Slice I4 is complete: every current containment, overlap, walkable, and
six-path moving-collision entry point has an integer-indexed flat shadow port.
The exact referee passes 13 focused tests, 7,500 installed-DAT comparisons,
1,200 complete resolver frames, and 10,000 warmed iterations at zero managed
bytes with no mismatch. Release build and 8,384 solution tests / 5 skips pass.
Slice I5 is complete: immutable near-build collision closures and strict live
collision publication install graph and prepared-flat views under canonical
ownership. Cancellation, demotion, rehydration, revisit, removal, and reset
gates pass. The lifecycle/reconnect and nine-stop routes sampled 14,064 exact
queries with zero mismatch, fault, or artifact; graph/flat cell residency
matched at every stable checkpoint and teardown converged. Release build and
8,396 solution tests / 5 skips pass.
Slice I is complete. I6 made gameplay collision flat-authoritative at
`068a0651`; its strict dense-Arwic gate matched 46,309/46,309 queries and the
physical nine-stop soak converged. After user collision acceptance, I7 removed
every production parsed collision graph at `82f8d4f8`. Release build and 8,413
tests / 5 skips pass; both exact-binary connected routes report `0/0/0` parsed
graph residency at every stable checkpoint with graceful teardown. The
cutover rollback is
`git revert 068a06518dd710ca5e7f166754cbb7789ca1ed0f`; graph-removal rollback
is `git revert 82f8d4f82e24ad85042ac3e25c4f6464bebce758`.
Slice J0 is complete at `b632672e`: `AcDream.Runtime` now provides the enforced
presentation-independent assembly boundary without moving gameplay behavior.
Four dependency guards pass. J1 is complete at `854d9e9c`: borrowed runtime
views, typed synchronous commands, ordered deltas, the instance clock,
generation/lifecycle contracts, and teardown acknowledgements project the same
canonical App owners without a mirror or extra frame. Runtime tests pass 13/13,
App tests pass 3,838/3 skips, the complete Release suite passes 8,424/5 skips,
and the exact-binary seven-checkpoint connected lifecycle/reconnect gate passes
with graceful exits. J2 is complete at `75930787`: the canonical
`WorldSession` generation, connect/enter/tick/replace transaction, ordered
inbound route, and retryable teardown acknowledgement now live in Runtime.
App retains only option conversion, graphical callbacks, and one borrowed
inertable UI command projection. Runtime tests pass 79/79, App tests pass
3,776/3 skips, the complete Release suite passes 8,428/5 skips, and the exact-
binary seven-checkpoint gate passes with graceful exits and zero render-shadow
mismatches or pending deltas. J3.1 moved accepted physics timestamp/snapshot
and parent-relation owners into Runtime at `f7442d13`. J3.2 is complete at
`f46ddb5c`: `RuntimeEntityDirectory` now owns the only active GUID/incarnation,
teardown tombstone, local-ID/reverse, accepted-wire, parent, and session-
operation maps; `RuntimeEntityRecord` is presentation-free and App records are
graphical sidecars. Runtime tests pass 110/110, App tests pass 3,758/3 skips,
the complete Release suite passes 8,441/5 skips, and the exact-binary seven-
checkpoint lifecycle/reconnect gate passes with graceful exits, zero render-
shadow mismatches, and zero pending deltas. J3.3 is complete at `420e5eea`
plus exact-spatial correction `e937cc36`: `LiveEntityProjectionStore` and every
materialized presentation/spatial owner now use exact `RuntimeEntityKey`; the
temporary GUID-shaped compatibility view is deleted. App tests pass 3,761/3
skips, the complete Release suite passes 8,444/5 skips, and the final exact-
binary seven-checkpoint gate passes with two graceful exits, zero failures,
zero render-shadow mismatches, and zero pending deltas. J3.4 is complete at
`5ef8b537`: `RuntimeEntityObjectLifetime` owns the sole entity directory and
live `ClientObjectTable`; App, routing, interaction, and UI borrow the exact
instances. Runtime tests pass 118/118, App tests pass 3,762/3 skips, the
complete Release suite passes 8,453/5 skips, and the exact-binary
seven-checkpoint gate passes with graceful exits, zero failures, zero
render-shadow mismatches, and zero pending deltas. J3.5 is complete at
`ce3ac310`: Runtime issues identity before App hydration, publishes entity and
inventory commits through one per-generation sequence, and supplies the same
direct borrowed views to graphical and no-window hosts. Runtime tests pass
134/134, App tests pass 3,765/3 skips, the complete Release suite passes
8,472/5 skips, and the exact-binary seven-checkpoint gate passes with graceful
exits, zero failures, zero render-shadow mismatches, and zero pending deltas.
J3.6 is complete at `119b7c11`: exact teardown receipts precede fallible
callbacks, re-entrant commits retain one monotonic synchronous stream,
accepted-channel versions reject displaced callbacks, and reset/direct
disposal converge the complete ownership ledger to zero. Runtime tests pass
146/146, App tests pass 3,765/3 skips, the complete Release suite passes
8,484/5 skips, and both the exact lifecycle/reconnect and canonical nine-stop
routes pass with graceful zero-code exits and no failures. J3 is closed; J4
gameplay-state lifetime groups are active. J4.1 is complete at `c9d25ade`:
`RuntimeCommunicationState` owns the exact chat transcript, reply/retell
targets, negotiated rooms, friends, and squelch state; graphical and no-window
consumers borrow them. Runtime tests pass 152/152, App tests pass 3,765/3
skips, the complete Release suite passes 8,494/5 skips, and the exact-binary
seven-checkpoint lifecycle/reconnect gate passes with graceful exits and zero
failures. J4.2 is complete at `011efbea`: `RuntimeInventoryState` owns
external-container, item-mana, shortcut/component, shared-busy,
use-reservation, and one-request-at-a-time state while borrowing J3's exact
object table. Runtime tests pass 157/157, App tests pass 3,770/3 skips, the
complete Release suite passes 8,515/5 skips, and the exact-binary
seven-checkpoint lifecycle/reconnect gate passes with graceful exits and zero
failures. J4.3 is complete at `d02a12ce`: `RuntimeCharacterState` owns the
exact coupled spellbook/local-player graph; content, routing, retained UI,
reset, and shutdown borrow it, and the duplicate desired-component snapshot is
deleted. Runtime tests pass 162/162, App tests pass 3,772/3 skips, the complete
Release suite passes 8,522/5 skips, and the exact-binary seven-checkpoint
lifecycle/reconnect gate passes with graceful exits and zero failures. J4.4 is
complete at `dcb61efb`: Runtime owns character options and server run/jump
projections, exposes exact borrowed J4 gameplay views, and routes retained UI
plus future no-window state commands through one synchronous generation-gated
seam. Runtime tests pass 169/169, App tests pass 3,777/3 skips, the complete
Release suite passes 8,534/5 skips, and the exact-binary seven-checkpoint gate
passes with graceful exits and zero failures. J4.5 is complete at `89e6b207`:
Runtime owns the one shortcut manager, graphical/no-window command effects use
the exact inventory/character owners, item-use UI cannot create a second
transaction gate, and the combined failure-safe ownership ledger converges.
Runtime tests pass 175/175, App tests pass 3,780/3 skips, the complete Release
suite passes 8,544/5 skips, and both exact-binary lifecycle/reconnect and
canonical nine-stop gates pass with graceful exits and zero failures. J5.1 is
complete at `b298f99f`: `RuntimeActionState` owns the exact selection, combat,
and temporary target-mode graph; Program, plugins, retained UI, session
routing, typed commands/views, and shutdown borrow its children, while the App
interaction-state class and private controller fallback are deleted. Runtime
tests pass 182/182, App tests pass 3,779/3 skips, the complete Release suite
passes 8,550/5 skips, and the exact-binary seven-checkpoint
lifecycle/reconnect gate passes with graceful exits and zero failures. J5.2 is
complete at `f5f7b417`: `RuntimeActionState.Transactions` owns the strict use
gate, exact use/appraisal identity, typed interaction FIFO, and exact
post-arrival pickup token while borrowing J4's sole inventory busy/request
gate. App retains picking, movement/transport, and presentation only. Runtime
tests pass 197/197, App tests pass 3,775/3 skips, the complete Release suite
passes 8,561/5 skips, and the exact-binary seven-checkpoint gate passes with
graceful exits and zero failures. J5.3 is complete at `20df9d15`:
`RuntimeActionState` owns the exact combat-attack, combat-target, combat-mode,
and spell-cast intent children. Retained bars and graphical input borrow those
owners; direct Runtime commands drive the same operations and snapshots.
Runtime tests pass 223/223, App tests pass 3,754/3 skips, the complete Release
suite passes 8,566/5 skips, and the exact-binary seven-checkpoint gate passes
with graceful exits and zero failures. J5.4 is complete at `aa3f4a60`:
`RuntimeLocalPlayerMovementState` owns the exact local movement controller,
construction seam, autorun latch, typed view, and terminal ledger; graphical
input and direct Runtime commands borrow the same state, and outbound
MTS/jump/AP cadence lives in Runtime. Runtime tests pass 303/303, App tests
pass 3,716/3 skips, the complete Release suite passes 8,575/5 skips, and both
the exact-binary lifecycle/reconnect and canonical nine-stop movement gates
pass with graceful exits and zero failures. J5.5 is complete at `7e6033d0`:
`RuntimePhysicsState` owns the sole per-session engine, production cache/cell
graph, transition scratch, shadow registry, typed collision admissions,
canonical body/host/remote components, ordinary/remote worksets, simulation,
and full-cell commits. App publishes prepared collision and projects committed
snapshots only. Runtime tests pass 314/314, App tests pass 3,718/3 skips, the
complete Release suite passes 8,588/5 skips, and both exact-binary
lifecycle/reconnect and canonical nine-stop collision/movement gates pass
with graceful exits and zero failures. J5.6 is complete at `2aee3356`:
Runtime owns the canonical projectile component/workset,
prediction/correction state, and unchanged retail projectile simulation while
App resolves immutable DAT shape data and projects committed frames. Runtime
tests pass 317/317, App tests pass 3,718/3 skips, 47 focused Core projectile
tests pass, the complete Release suite passes 8,591/5 skips, and the exact
arrow/bolt/spell, lifecycle/reconnect, and canonical nine-stop gates pass with
graceful exits and zero failures. J5.7 and J5 are complete at `cdee7a4b`:
Runtime owns accepted remote-body/vector activation, final simulation
retirement, terminal physics/shadow/workset cleanup, and one combined
entity/object/gameplay/physics ownership ledger. The Runtime-only fixture
drives movement, use, combat, casting, and projectiles without loading
presentation/backend assemblies. Runtime tests pass 323/323, App tests pass
3,717/3 skips, the complete Release suite passes 8,596/5 skips, and the exact
lifecycle/reconnect plus canonical nine-stop gates match binary/source,
converge every backlog, and exit gracefully with zero failures. J6
world/portal/environment and projection-handshake ownership is active. J6.1
landed at `902076c0`: Runtime owns the instance-scoped Dereth calendar,
server-synchronized clock, weather, day-group selection, and AdminEnvirons
state while App only projects immutable DAT sky definitions into rendering.
Its 332 Runtime tests, 3,718 App tests / 3 skips, 8,611 complete Release tests
/ 5 skips, and exact-binary lifecycle/reconnect route pass. J6.2 landed at
`a6860d55` plus `acb845d8`: Runtime owns the sole reveal generation,
destination/readiness latch, materialization/simulation edge, viewport,
completion, cancellation, wait cue, and portal count. App's lifecycle mirror
is deleted. Its 349 Runtime tests, 3,716 App tests / 3 skips, 8,626 complete
Release tests / 5 skips, and exact-binary lifecycle/reconnect route pass with
zero reveal invariants. J6.3 landed at `6a063a27`: Runtime owns wrap-safe F751
history, both accepted F751/Position orders, the exact destination, and
generation/sequence/cell placement and materialization validation. App's
transit coordinator and destination mirror are deleted. Its 360 Runtime tests,
3,710 App tests / 3 skips, 8,631 complete Release tests / 5 skips, and
exact-binary lifecycle/reconnect route pass. J6.4 landed at `18d17d8b`:
Runtime owns the exact generation/cell-scoped host acknowledgement suffix and
App owns only retryable graphical resource receipts. Its 365 Runtime tests,
3,716 App tests / 3 skips, 8,642 complete Release tests / 5 skips, and
exact-binary lifecycle/reconnect route pass with every environment,
transit, and pending-host ledger at zero. J6 is complete. J7.1 created the
single `GameRuntime` root at `96ddd165`; J7.2/J7.3 cut graphical production
and shutdown over at `ce41efb9`. Its 383 Runtime tests, 3,717 App tests /
3 skips, 8,661 complete Release tests / 5 skips, lifecycle/reconnect route,
canonical nine-stop route, and the user's 2026-07-27 exact post-cutover visual
matrix pass. J7 is closed. J8 closed Slice J at `a9a822f2`: graphical and
no-window hosts share one `GameRuntime`, one retryable canonical-generation
reset transaction, and one gameplay-owner graph. Its 395 Runtime tests, 3,731
App tests / 3 skips, 8,696 complete Release tests / 5 skips, exact-binary
lifecycle/reconnect route, and canonical nine-stop route pass. Slice K
Linux headless/multi-session implementation is complete. K0 completed at
`aada8a37`: `AcDream.Headless` references only Runtime, strict no-connect
validation and dependency/loaded-assembly guards pass, and the local Ubuntu
closure passes 600 Core.Net, 119 Content, 395 Runtime, and 12 Headless tests.
K1 completed at `f8cb840f`: portable XDG/Windows paths, strict config,
redacted credentials, direct Runtime command/entity/portal routes, and the
production single-session host pass the same real ACE connect, portal,
graceful-reconnect, and terminal-teardown gate on Windows and Linux/WSL.
Runtime tests pass 402/402, Headless tests pass 25/25, the complete Windows
Release suite passes 8,728/5 skips. K2 completed at `7e8acb74` plus
`38e83640`: the monotonic absolute-deadline scheduler, shared Runtime
local-player frame sequence, complete generation-gated bot commands, and
ordered lifecycle/entity/inventory/chat/movement/portal/combat/command event
stream pass 411 Runtime tests, 31 Headless tests, 3,732 App tests / 3 skips,
and 8,744 complete Release tests / 5 skips. K3 completed across `12b500d3`,
`9569dadb`, `b6547ff3`, and `3f340125`: exact process content leases,
immutable magic/terrain/bounded collision sharing, presentation-free
local-player/collision hydration, 1/5/10-session same-GUID/portal/reconnect
isolation, and policy-fault quarantine pass 412 Runtime, 42 Headless, 3,722 App
tests / 3 skips, and 8,758 complete Release tests / 5 skips. The connected
closeout adds direct single-session CLI launch, four-stop portal routing,
external teleport handling, retail-correct normal Position versus
ForcePosition projection, explicit-only collision diagnostics, visible Windows
and native Linux production runs, user-accepted smooth retail-observer
movement, and ACE-confirmed graceful logout. Final gates pass 412 Runtime, 47
Headless, 3,722 App / 3 skips, and 8,764 complete Release tests / 5 skips.
K4 implementation is complete through `776482da`. `cb512fd0` added one
process-scheduler observation deadline and corrected pre-connect deadline
arming plus a Linux sub-millisecond `Task.Delay` busy loop. `97c174fb` added
1/5/10/30-root content, same-GUID, portal, reconnect, and two-hour simulated
endurance gates; `bd236ce5` added death and randomized cancellation coverage;
`776482da` committed the diagnostic-only 30-session resource envelope and
exact running/terminal ownership checks. Windows and native Ubuntu Headless
tests pass 67/67; the complete Release suite passes 8,784 / 5 skips. The exact
`776482da` native Linux two-account process ran for ten minutes with 20
consecutive passing periodic samples, zero faults/reconnect debt, bounded
scheduler cadence, and every resource dimension inside its ceiling. SIGINT
produced ACE-confirmed graceful logout for both accounts and a passing final
`disposed` sample: two converged Runtime roots, zero entities/inventory/host
or content leases, and disposed shared content. K4 and Slice K are closed;
Slice L Linux graphical/platform work is parked at its L1 implementation
checkpoint by user direction on 2026-07-27. L0 completed at `66f114b2`:
`ApplicationPathSet` is the shared XDG/Windows path authority;
`GraphicalHostPlatformServices` owns one OS/architecture/RID, native manifest,
and frame-waiter factory; Linux uses an absolute `CLOCK_MONOTONIC` wait;
settings, keybindings, Studio, diagnostics, and user plugins consume portable
paths with no-overwrite Windows migration; and the RID-safe App publish plus
Ubuntu graphical CI/package gate pass. Windows passes 415 Runtime, 67
Headless, 543 UI, and 3,736 App tests / 3 skips; the complete Release suite
passes 8,799 / 5 skips. Native Ubuntu passes the portable closure, 14 L0 App
tests, and exact `linux-x64` publish. L1 context/extension/native-backend
validation implementation landed at `11501d52`: immutable
Win32/X11/Wayland selection, packaged GLFW 3.4 preference, atomic capability
reporting, and active bindless/draw-parameters/MDI/SSBO/timer/FBO/persistent-
buffer probes now gate renderer construction. Native Windows AMD passes every
active probe and terminal graphical/audio ownership converges to zero. WSLg
X11/Wayland correctly reject Mesa D3D12/llvmpipe because mandatory
`GL_ARB_bindless_texture` is absent. App tests pass 3,763 / 3 skips and the
complete Release suite passes 8,826 / 5 skips. A supported physical Linux
AMD/NVIDIA driver row remains the first gate when work resumes; that gate and
L2–L6 are deferred.
J0's rollback is
`git revert b632672e5ccabfb44c551e08f1c411ab2669c44a`.
J1's rollback is
`git revert 854d9e9cd13092bd5aaa3cf025d73eeb4600e9f8`.
J2's rollback is
`git revert 75930787741db40a83eab8663e4464dce8d687ba`.
J3.2's rollback is
`git revert f46ddb5cdb1e145752bea49aeb1d62bfe71284d3`.
J3.3's rollback is, newest first,
`git revert e937cc36df39cf6ea1eaba2f9c0243d1929da702` then
`git revert 420e5eea70fd2c29cf9c8614e6298a1f84d64045`.
J3.4's rollback is
`git revert 5ef8b5371d8990f0380acd939e71cd711289d429`.
J3.5's rollback is
`git revert ce3ac310d92722ffb637e81cb1957458874dd220`.
J3.6's rollback is
`git revert 119b7c115107245546180b2f5cb3cb44c7d5476a`.
J4.1's rollback is
`git revert c9d25ade50c0a5c4f7db5b6cca680e01e35cc18e`.
J4.2's rollback is
`git revert 011efbeaa72509b35ea7f4a442e50a2377ae1ea4`.
J4.3's rollback is
`git revert d02a12ceac54d035797b4c58f2fc2f0ccad9a4d6`.
J4.4's rollback is
`git revert dcb61efb5af6c12bd619369e28cf11bacc37bc73`.
J4.5's rollback is
`git revert 89e6b207f81946b40c38c8dc6597817ad99fc6e0`.
J5.1's rollback is
`git revert b298f99f913249d299796e6a71f7a9b6b283ac1a`.
J5.2's rollback is
`git revert f5f7b4177f449ebcad9724bfea263ef73ab60255`.
J5.3's rollback is
`git revert 20df9d155db50706a42420d60a9b15861cf4bfe7`.
J5.4's rollback is
`git revert aa3f4a60f87f2cbebc3d8ecd5e33d779b7fb13c1`.
J5.5's rollback is
`git revert 7e6033d0adcd0b572c20e89dd275746fb442d52f`.
J5.6's rollback is
`git revert 2aee33569f0268d7bc0f4f52437dfa0b405432a4`.
J5.7's rollback is
`git revert cdee7a4b49addb5e1500753f6a885f7c899bd0f0`.
J6.1's rollback is
`git revert 902076c0a42079596a8a273e9be402776cabf4b0`.
J6.2's rollback is, newest first,
`git revert acb845d812574206da1693fb379fec8a6f175fcb` then
`git revert a6860d5563ae845a2cbb916abacf2b4aee515cdb`.
J6.3's rollback is
`git revert 6a063a27d4c805cd166d5a487afc290c34c400fd`.
J6.4's rollback is
`git revert 18d17d8bb17ed9ff3ed01da8273e2948abe6398b`.
J7.1's rollback is
`git revert 96ddd16539e670a5ce9b1f86677530e3fbc3f635`.
J7.2/J7.3's rollback is
`git revert ce41efb9e5938f79a7580476b949d172f52a1e69`.
J8's rollback is
`git revert a9a822f206cc6021bc099988144488f3bd7c397b`.
K0's rollback is
`git revert aada8a37c1e933f9f0a3f41dc4f05615b01023bc`.
K1's rollback is
`git revert f8cb840fb15b27f61afa5c33cad6c4dba8584949`.
K2's rollback is, newest first,
`git revert 38e83640d907ee3e0819f3b38ca117ca60914d6b` then
`git revert 7e8acb74dd20931d5ba88430fd100cd074a32e4d`.
K3's connected-closeout rollback is
`git revert 3f3401257c83bdd9f557eb577ba08cf2e5ec9a06`; its earlier automated
checkpoint rollbacks remain recorded in the Slice K plan.
K4's current rollbacks, newest first, are
`git revert 776482da8225d88a7c6128022d137d26f9266a87`,
`git revert bd236ce553718cfb1248703f4a2b17b35733b11c`,
`git revert 97c174fbb2d72fb94e2fe07448bb257989ed8941`, then
`git revert cb512fd0916fbf49285c9b64df1630c5a69a0d20`.
L0's rollback is
`git revert 66f114b258c0c37b51a7c0e04ca0d6441f4b1699`.
L1's implementation-checkpoint rollback is
`git revert 11501d52cad942850d88f83490710faf1d5cdf28`.
Slice H's retained UI/frame, bounded-light, and pooled/borrowed/direct network
work is complete; the exact seven-checkpoint connected lifecycle/reconnect gate
passes. Slice I is closed in
`docs/plans/2026-07-25-modern-runtime-slice-i.md`; the coherent Slice J campaign
executes from `docs/plans/2026-07-25-modern-runtime-slice-j.md`; J3.6 closeout
is `docs/research/2026-07-26-slice-j3-6-lifetime-closeout.md`; J4 executes from
`docs/plans/2026-07-26-modern-runtime-slice-j4.md`; J4.1 closeout is
`docs/research/2026-07-26-slice-j4-1-communication-state.md`; J4.2 closeout is
`docs/research/2026-07-26-slice-j4-2-inventory-state.md`; J4.3 closeout is
`docs/research/2026-07-26-slice-j4-3-character-state.md`; J4.4 closeout is
`docs/research/2026-07-26-slice-j4-4-character-projections.md`; J4.5 closeout
is `docs/research/2026-07-26-slice-j4-5-gameplay-state-closeout.md`; J5.1
closeout is
`docs/research/2026-07-26-slice-j5-1-canonical-action-state.md`; J5.2 closeout
is `docs/research/2026-07-26-slice-j5-2-interaction-transactions.md`; J5.3
closeout is `docs/research/2026-07-26-slice-j5-3-combat-magic-intent.md`; J5.4
closeout is
`docs/research/2026-07-26-slice-j5-4-local-movement-ownership.md`; J5.5
closeout is
`docs/research/2026-07-26-slice-j5-5-physics-remote-ownership.md`; J5.6
closeout is
`docs/research/2026-07-26-slice-j5-6-projectile-ownership.md`; J5.7 closeout is
`docs/research/2026-07-26-slice-j5-7-simulation-ownership-closeout.md`; J6.3
closeout is
`docs/research/2026-07-26-slice-j6-3-teleport-correlation.md`; J6 closeout is
`docs/research/2026-07-26-slice-j6-4-host-acknowledgement.md`. J7 closeout is
`docs/research/2026-07-26-slice-j7-game-runtime-root-cutover.md`; J8/Slice-J
closeout is
`docs/research/2026-07-27-slice-j8-no-window-closeout.md`; K0 closeout is
`docs/research/2026-07-27-slice-k0-portability-boundary.md`; K1 closeout is
`docs/research/2026-07-27-slice-k1-single-session-headless.md`; K2 closeout is
`docs/research/2026-07-27-slice-k2-deterministic-bot-parity.md`; Slice K is
closed in `docs/plans/2026-07-26-modern-runtime-slice-k.md`; K4 evidence is
`docs/research/2026-07-27-slice-k4-resource-telemetry-checkpoint.md`; Slice L
executes from `docs/plans/2026-07-26-modern-runtime-slice-l.md`; L0 evidence is
`docs/research/2026-07-27-slice-l0-platform-services.md`; L1 checkpoint
evidence is
`docs/research/2026-07-27-slice-l1-graphical-capability-checkpoint.md`. The exact G4 visual
rollback
is `git revert ef1d263337997bb030eadb7b8e71d73dc659907a`; do not revert G3 or
the portal-warmup corrections. Evidence:
`docs/research/2026-07-25-slice-h-closeout.md` and
`docs/research/2026-07-25-slice-g5-production-profile.md` and
`docs/research/2026-07-25-slice-i1-transition-scratch.md` and
`docs/research/2026-07-25-slice-i2-flat-collision-schema.md` and
`docs/research/2026-07-25-slice-i3-prepared-collision-package.md` and
`docs/research/2026-07-25-slice-i4-flat-bsp-differential.md` and
`docs/research/2026-07-25-slice-i5-dual-collision-shadow.md` and
`docs/research/2026-07-25-slice-i6-flat-production-cutover.md` and
`docs/research/2026-07-25-slice-i7-closeout.md` and
`docs/research/2026-07-25-slice-j1-runtime-contract-closeout.md` and
`docs/research/2026-07-25-slice-j2-session-lifetime-closeout.md` and
`docs/research/2026-07-25-slice-j3-2-canonical-entity-directory-closeout.md` and
`docs/research/2026-07-25-slice-j3-3-exact-projection-store.md` and
`docs/research/2026-07-26-slice-j3-4-canonical-object-lifetime.md` and
`docs/research/2026-07-26-slice-j3-5-canonical-delta-stream.md` and
`docs/research/2026-07-26-slice-j3-6-lifetime-closeout.md`.

**Structural prerequisite before new M4 subsystem work:** all eight
behavior-preserving `GameWindow` decomposition slices and the automated
closeout landed 2026-07-22. The class is now a 1,622-line native
composition/callback shell, down 14,101 lines (89.7%) from baseline. Ordered
startup, update/render frame graphs, native/input callbacks, settings,
session/reset wiring, canonical checkpoint capture, and retryable shutdown are
owned by focused typed collaborators without a service locator or stored
window back-reference. All 293 focused tests, App Release 3,462/3, the complete
Release suite 7,835/5, connected lifecycle/reconnect, two fresh-process
canonical nine-stop soaks, three corrected-diff reviews, and the exact Slice-7
framebuffer comparison pass. Issue #232 is closed without loosening process
limits. The user's connected visual matrix passed 2026-07-23, including the
post-closeout radar correction; the structural campaign is complete and M4
feature bodies may resume after any active regression gate.
The capped/RDP jump-presentation cadence alias is deferred as issue #235:
uncapped Release presentation is smooth, while physics, collision, and wire
truth remain correct.
See `docs/plans/2026-07-22-gamewindow-slice-8-composition-lifecycle.md` and
`docs/architecture/code-structure.md`. **Carried:** #116 (Campaign P P2),
remaining R6 ownership cleanup, TS-50/TS-51/TS-53, Modern Runtime Slice L,
and #225's lifestone/particle alpha visual gate. #153 closed 2026-07-30
(Campaign P P5 ledger evidence chain).

Start structural work at `memory/project_gamewindow_decomposition.md` and
`docs/architecture/code-structure.md`; start
magic follow-up at `claude-memory/project_magic_ui_and_casting.md`; start
render/streaming work at `claude-memory/project_render_pipeline_digest.md`.

Documentation entry point: [`docs/README.md`](docs/README.md).

For canonical state, read in this order:
- [`docs/plans/2026-07-29-network-transport-campaign.md`](docs/plans/2026-07-29-network-transport-campaign.md) — Campaign N, the retail reliable-transport port — **CLOSED 2026-07-29, user-accepted** (#260 closed; a real wire loss recovered live during the acceptance session). Still the SSOT for the transport mechanism, the ACE constraint table, and the landmine list — read it (or `claude-memory/project_network_transport_digest.md`) before touching anything under `src/AcDream.Core.Net/`.
- [`docs/plans/2026-07-27-vulkan-campaign.md`](docs/plans/2026-07-27-vulkan-campaign.md) — Campaign V, OpenGL → Vulkan — **CLOSED 2026-07-29**; the completed record of the RHI contract, V0–V11 slices, and the GL deletion. Historical reference for `src/AcDream.App/Rendering/`.
- [`docs/plans/2026-05-12-milestones.md`](docs/plans/2026-05-12-milestones.md) — milestone targets + freeze list per milestone
- [`docs/plans/2026-04-11-roadmap.md`](docs/plans/2026-04-11-roadmap.md) — what's shipped, what's in flight, what's next
- [`docs/ISSUES.md`](docs/ISSUES.md) — open + recently closed bugs (tactical)
- [`docs/architecture/retail-divergence-register.md`](docs/architecture/retail-divergence-register.md) — every known acdream-vs-retail deviation (see the register rules in the workflow section)

**Domain entry points (START HERE before domain work):**
- `claude-memory/project_render_pipeline_digest.md` — indoor render / doorway-FLAP / portal flood SSOT, with the DO-NOT-RETRY table
- `claude-memory/project_physics_collision_digest.md` — physics / collision / cell-membership SSOT, with the DO-NOT-RETRY table

For engineering reference (read on demand, not at session start):
- `memory/reference_modern_rendering_pipeline.md` — N.4/N.5 bindless+MDI dispatch, WbMeshAdapter/WbDrawDispatcher, translucency model
- `memory/reference_two_tier_streaming.md` — Phase A.5 streaming architecture
- `memory/reference_indoor_cell_tracking.md` — Phase 2 + A4 portal-based cell tracking + multi-cell BSP iteration
- `memory/reference_obsidian_vault.md` — Obsidian-as-memory-viewer setup + the memory-handling protocol
- `memory/reference_ghidra_projects.md` — Ghidra + GhidraMCP for acclient RE
- `memory/reference_repos.md` — what each `references/*` repo is for

The memory dir also holds `feedback_*.md` lessons-learned (cross-cutting
patterns the project has agreed on) and `project_*.md` per-subsystem
cribs (chat pipeline, input pipeline, interaction pipeline, etc.).
See `claude-memory/MEMORY.md` for the index.

## Code Structure Rules

These are the structural rules the project commits to. They are
**process rules** (where code goes, what depends on what), not style
rules (formatting / naming). They exist to keep the layer split honest
and to stop `GameWindow.cs` from continuing to grow into a 10k-line
god object. The full rationale + the extraction sequence we're
pursuing live in [`docs/architecture/code-structure.md`](docs/architecture/code-structure.md).

1. **No new substantial feature bodies in `GameWindow.cs`.** It is now the
   roughly 1,600-line native composition/callback shell. New runtime
   work goes into a dedicated controller / sink / orchestrator class
   in `src/AcDream.App/` (or deeper in `AcDream.Core` when it's pure
   logic). Adding a handful of fields and a one-paragraph method to
   wire an extracted class in is fine; adding a new ~200-line feature
   directly is not. When in doubt, file a small follow-up extraction
   as part of the change.

2. **`AcDream.Core` must not depend on the window / GL / backend
   projects, except via documented interop seams.** As of Phase O,
   the only allowed seams are the extracted helpers in
   `src/AcDream.Core/Rendering/Wb/` (`TerrainUtils`, `TerrainEntry`,
   `RegionInfo`, `SceneryHelpers`, `TextureHelpers` — stateless, no GL).
   The former `WorldBuilder.Shared` and `Chorizite.OpenGLSDLBackend.Lib`
   project references are gone; their code now lives in our tree at those
   paths. New Core code that needs a GL surface must define an interface
   in Core and let `AcDream.App` implement it — never the reverse. If you
   need to add a project reference to Core, the change must come with an
   inventory-doc update explaining why.

3. **UI panels target `AcDream.UI.Abstractions` only.** No panel may
   import `AcDream.UI.ImGui` or any backend namespace. ViewModels,
   commands, and the `IPanel` / `IPanelRenderer` contract are the
   surface; everything else is backend. This is what lets us swap
   D.2a (ImGui) for D.2b (retail-look) later without rewriting
   panels.

4. **Startup environment variables enter through a typed options
   object.** `AcDream.App.RuntimeOptions` is the single source of
   truth for startup configuration. `Program.cs` reads the
   environment once into `RuntimeOptions` and passes it into
   `GameWindow`. Don't sprinkle `Environment.GetEnvironmentVariable`
   reads through new code paths; add a field to `RuntimeOptions` and
   pipe it through.

5. **Runtime probes (diagnostic toggles) belong in diagnostic owner
   classes.** Today `AcDream.Core.Physics.PhysicsDiagnostics` owns the
   `ACDREAM_PROBE_*` family. The pattern: one static class per
   subsystem, exposing typed bool/int properties read from env vars
   once at startup (with optional runtime-toggleable counterparts for
   the DebugPanel). Per-call-site `Environment.GetEnvironmentVariable`
   reads in new code are a process smell — if a flag survives one
   phase, promote it to a diagnostic owner. The dozens of existing
   `ACDREAM_DUMP_*` reads scattered through `GameWindow` are tech
   debt; do not add more.

6. **Tests live in the project matching the layer under test.** Core
   tests in `tests/AcDream.Core.Tests/`, UI tests in
   `tests/AcDream.UI.Abstractions.Tests/`, network tests in
   `tests/AcDream.Core.Net.Tests/`. App-layer tests (RuntimeOptions
   parsing, etc.) belong in `tests/AcDream.App.Tests/`. When adding a
   new test project, register it in `AcDream.slnx`.

## How to operate

**Memory — read the digests before domain work.** Durable project knowledge
lives in `claude-memory/` (the auto-loaded index is `MEMORY.md`). Before starting
work in a domain that has a **digest**, read it first: `project_render_pipeline_digest.md`
(indoor render / doorway FLAP) and `project_physics_collision_digest.md`
(physics / collision / membership). Each digest is current-truth-on-top
plus a DO-NOT-RETRY table — it supersedes dated banners. The memory-handling
protocol (distill-don't-journal, the digest pattern, tags, recall + capture)
is in `reference_obsidian_vault.md`. **Do NOT add new dated status banners to
this file — update the relevant digest (or the Current state pointer list)
instead.** Obsidian (auto-started in the main repo via a SessionStart hook) is
the live search / graph / tag lens over `claude-memory/` through the
`mcp__obsidian__*` tools when it's running; the files read and write the same
with it closed.

**You are the lead engineer AND architect on this project at all times.**
You own the architecture (`docs/architecture/acdream-architecture.md`),
the execution plan (milestones doc + strategic roadmap), the development
workflow, and all technical decisions. Stop as little as possible. Drive work autonomously and continuously through full phases and
across commit boundaries. Do not stop mid-phase for routine progress check-ins,
permission asks on low-stakes design calls, or "should I continue?" confirmations.
The user has repeatedly authorized direct-to-main commits, multi-commit sessions,
and cross-phase jumps when the work is sequenced in the roadmap.

The only thing that genuinely requires stopping is **visual confirmation** — the
user needs to look at the running client and tell you whether it matches
retail. Everything else is your call.

**No workarounds without explicit approval.** When you spot a bug or
encounter a behavioral mismatch, fix the underlying cause — do not ship a
band-aid, suppression flag, grace period, retry loop, or any other "make
the symptom go away" shortcut, unless the user has explicitly approved
that shape OR you are building a NEW feature with a different design.
This rule exists because every workaround creates architectural debt that
masks the real issue, makes future refactors harder, and erodes the
codebase's retail-faithfulness. Examples of disallowed shortcuts: an
`if (problematicState) return early` guard at the symptom site instead of
investigating why the state happened; a timer-based "settle period" to
hide a race; a flag like `_suppressXDuringY` to mask a wire-level mistake;
a `try/catch` swallowing an exception that signals a real problem. If you
notice a fix is starting to look like a workaround mid-implementation,
stop, file the proper investigation as an issue with full reproduction
notes, and either (a) ask the user before shipping the workaround, or
(b) invest the time to fix the root cause. The user has explicitly
authorized "spend more time, get it right" over "ship a shortcut and
file the cleanup." Quote them: "we should have no workarounds unless I
say so or we want a different feature."

**Only stop and wait for the user when:**

- Visual verification is the acceptance test ("does the drudge look right now?")
- The roadmap and the observed bug disagree and you need to brainstorm a
  new phase or sub-step (use `superpowers:brainstorming`, not a freeform chat)
- A genuinely destructive or hard-to-reverse action is on the table outside
  the normal commit workflow (force push, history rewrite, deleting memory
  files, reverting multiple commits)
- Memory or committed history shows a clear user preference you're about to
  diverge from
- **The request is an investigation, audit, analysis, review, or "report-only"**
  — no edits, no writes, no diagnostic code drops until you've delivered the
  report and the user explicitly approves a fix. Use the `/investigate` skill
  (`.claude/skills/investigate/SKILL.md`) to enter this mode cleanly.
- **A referenced commit, file path, branch, or doc doesn't exist** where the
  user said it would. Ask one short question; don't go hunting across branches
  or worktrees. A 1-line clarification beats 30 minutes of wrong-branch
  exploration.

**Things you should just do without asking:**

- Continue to the next planned sub-step of a phase after the previous one
  lands clean — including immediately starting work on the next phase if the
  current one is done. **You pick what comes next** per the Milestone
  discipline section — never present the user a menu like "should we do X
  or Y?" or ask "what next?". Just choose and announce the choice in one
  sentence. Work-order selection is Claude's job, not the user's.
- Pick between two roughly equivalent implementations; justify the choice in
  the commit message
- Refactor small amounts of surrounding code when genuinely needed to land a
  change cleanly (but not "while I'm here" scope creep)
- Run the test suite, build the project, commit to main with co-author
  attribution
- Add diagnostic logging when you need evidence, then strip it when the
  evidence is in hand
- Spawn subagents for bounded implementation chunks (see Subagent policy)

Before claiming a phase or sub-step is done: run `dotnet build` and
`dotnet test` green, commit with a message that explains the "why", update
memory if there's a durable lesson, update the roadmap's "shipped" table if
a phase just landed, and move to the next todo item.

**If you catch yourself about to ask "should I continue?", the answer is
always yes — keep going.** The single exception is visual verification;
otherwise, act.

## Communication style

The user is a strong systems / C# / network programmer but **less
practiced at 3D math, physics, graphics, and animation**. They want
to learn — they're not asking for dumbed-down content, but for
explanations that build understanding alongside the work.

When discussing 3D / physics / graphics / animation / dat-format /
protocol-internals topics:

- **Name the concept in plain language first**, then introduce the
  term of art. "The angle of a slope (we call its straight-up
  component `Normal.Z`)" rather than dropping `normal.Z = cos θ`
  with no anchor.
- **Give units**: degrees, meters, cm — NOT raw floats. "FloorZ ≈
  0.66 means slopes up to about 49° are walkable" rather than
  "FloorZ = 0.66417414f". Floats are for the code; English is for
  the conversation.
- **Use analogies for spatial concepts** when they fit. A BSP tree
  is "a way of slicing space into nested rooms"; a contact plane is
  "the imaginary floor under the player's feet"; a sphere sweep is
  "rolling a ball forward through space and stopping it on contact";
  a cross product is "the direction perpendicular to two arrows";
  a dot product is "how aligned two arrows are (1 = same, 0 =
  perpendicular, -1 = opposite)".
- **Don't pile on multiple new concepts in one paragraph.** If a
  problem touches step-up AND step-down AND edge-slide AND
  walkable-polygon tracking, walk through them one at a time, each
  with what it does and why it exists.
- **Show the math when it matters, but explain it.** Don't just
  drop a formula and move on; tag it with "what this means
  geometrically".
- **Use frame-by-frame walk-throughs** for control-flow-heavy
  physics: "frame N: player here, lands. Frame N+1: state checks…"
  beats a function-call trace for understanding what's happening
  in motion.
- **Flag terms of art** the first time they appear in a session,
  even if they're sprinkled through code comments. "Broadphase",
  "BSP", "step-up", "ContactPlane", "ValidateWalkable" — they
  earn their meaning the first time you spell it out.

The goal is collaborative learning. Don't simplify the content; just
make sure every term and number is grounded so the user can keep up
and build intuition over time.

## Development workflow: grep named → decompile → verify → port

**This is the mandatory workflow for implementing ANY AC-specific behavior.**
The triangle-boundary Z bug cost 5 failed fix attempts from guessing.
The animation frame-swap bug cost 4 failed attempts. Every time we
checked the decompiled code first, we got it right on the first try.
**Now we have named retail symbols too — Step 0 cuts most lookups
from 30 minutes to 5 seconds. When "what does retail actually DO at
runtime?" is the question and decomp alone isn't enough, attach cdb
to a live retail client (Step -1).**

### For each new feature or bug fix:

-1. **ATTACH cdb TO RETAIL (when behavior is the question, not code).**
   For "what does retail actually DO frame-by-frame?" questions —
   wedges, weird animation flicker, geometry-specific bugs, anything
   where the decomp is correct but it's not clear how it produces the
   visible behavior — **don't guess; attach the Windows debugger to
   a live retail client and trace it.** See "Retail debugger toolchain"
   below for setup. We discovered the steep-roof wedge had a 30Hz
   physics-tick cause this way; would have taken weeks of guessing
   without the trace.

0. **GREP NAMED FIRST.** Before any decompilation work, search
   `docs/research/named-retail/acclient_2013_pseudo_c.txt` by
   `class::method` name. 99.6% of functions have real names from the
   Sept 2013 EoR build PDB. `docs/research/named-retail/acclient.h`
   has every retail struct verbatim. `docs/research/named-retail/symbols.json`
   is greppable by name or address (regenerate via
   `py tools/pdb-extract/pdb_extract.py refs/acclient.pdb`). Only fall
   back to Step 1 below if the named pseudo-C lacks a function (rare —
   covers only the obfuscated/packed minority).

1. **DECOMPILE FIRST (fallback).** Only when grep-named-first returned
   nothing. Find the matching function in the older Ghidra chunks at
   `docs/research/decompiled/` or decompile a new region using
   `tools/decompile_acclient.py`. Use the function map at
   `docs/research/acclient_function_map.md` (cross-port index) +
   `docs/research/named-retail/symbols.json` (raw PDB names) to find
   known functions. If the function isn't mapped yet, search by
   characteristic constants (motion commands, magic numbers, string
   literals).

2. **CROSS-REFERENCE.** Check the decompiled code against ACE's C# port
   (`references/ACE/Source/ACE.Server/Physics/`) and ACME's
   `ClientReference.cs`. The decompiled code is ground truth; ACE and
   ACME are interpretation aids. If they disagree, the decompiled code
   wins.

3. **WRITE PSEUDOCODE.** Translate the decompiled C into readable
   pseudocode before porting to C#. Save it in
   `docs/research/*_pseudocode.md` for future reference. This step
   catches misinterpretations before they become bugs.

4. **PORT FAITHFULLY.** Translate the pseudocode to C# line-by-line.
   Use the same variable names, the same control flow, the same boundary
   conditions. Do not "improve" or "simplify" the algorithm — the retail
   client's code works; our job is to match it.

5. **CONFORMANCE TEST.** Write tests that verify our port matches the
   decompiled behavior. Use golden values from the decompiled code or
   from ACME's conformance tests. If the function touches terrain, port
   the 4M-cell sweep from `TerrainConformanceTests.cs`.

6. **INTEGRATE SURGICALLY.** When wiring ported code into the renderer
   or game loop, change the MINIMUM necessary. Keep existing working
   transform pipelines, only replace the specific computation. The
   animation sequencer integration proved this: replacing the slerp
   source was safe; replacing the entire transform composition broke
   everything.

### The divergence register (mandatory bookkeeping)

[`docs/architecture/retail-divergence-register.md`](docs/architecture/retail-divergence-register.md)
is the single auditable list of every KNOWN place acdream's runtime
behavior can deviate from retail (108 rows at creation, 2026-06-12:
intentional architecture / adaptation / approximation / stopgap /
unclear). Two rules, both binding on subagents too:

1. **Any commit that introduces a deviation** (an adaptation, an
   approximation, a stopgap, a "retail does X but we...") **adds its
   register row IN THE SAME COMMIT.** Any commit that ports the retail
   mechanism deletes the row in the same commit. A deviation found
   without a row is a bug twice over.
2. **Any unexplained visual/physics symptom → scan the register BEFORE
   instrumenting.** The "Risk if assumption breaks" column is written as
   the symptom you'd observe (the #119 vanishing staircase, the #112
   transparent cottage, and the knife-edge flap all lived in rows of
   this register's scope before they had names).

The register holds one-line rows and pointers — detail lives at the
cited `file:line` and in the digests, never in the register itself.

### What NOT to do:

- **Do not guess** at AC-specific algorithms, formulas, constants, wire
  formats, or coordinate conventions. Ever. **The named retail decomp
  has the answer for almost everything; guessing is no longer a
  recoverable error, it's negligence.** If you can't find it in
  `docs/research/named-retail/`, file a research note and ASK before
  writing.
- **Do not "fix" the decompiled code.** If the retail client does
  something that looks wrong, it's probably right. Verify before
  changing.
- **Do not skip the pseudocode step.** The frame-swap bug was caused by
  misreading the decompiled C directly into C# without an intermediate
  translation.
- **Do not integrate via subagent** unless the subagent has the full
  context of the existing code it's modifying. The first animation
  sequencer integration was done by a subagent that didn't understand
  the transform pipeline — it broke everything.
- **Do not replace working retail-faithful logic with a modern redesign**
  without explicit user approval. Two campaigns (267 min remote-entity
  prediction+rubber-band replacing hard-snap; speculative shader edits in
  the sky-fog work) had to be reverted in full because the redesign
  regressed behavior the original port had right. When you see "I could
  simplify this with X" on a retail-port, flag the tradeoff and ask
  before deleting the existing path. Retail-faithful first; "cleaner"
  second.

### Phase completion checklist:

Before marking any phase as done:

- [ ] Every AC-specific algorithm has a decompiled reference cited in
      comments (named symbol + address from `named-retail/symbols.json`,
      OR function address + chunk file from older `decompiled/` chunks)
- [ ] Every retail deviation this phase introduced has a row in
      `docs/architecture/retail-divergence-register.md` (and every
      deviation it retired had its row deleted)
- [ ] Conformance tests exist for the critical paths
- [ ] The code was cross-referenced against at least 2 reference repos
- [ ] `dotnet build` green, `dotnet test` green
- [ ] Visual verification by the user (if applicable)
- [ ] Roadmap updated
- [ ] Memory updated if there's a durable lesson

## Retail debugger toolchain (live runtime trace)

**When the question is "what does retail actually DO frame-by-frame?"**
the decomp alone is often not enough — code paths interact with state
(LastKnownContactPlane, transient flags, accumulated counters) in ways
that aren't obvious from reading. We have a working toolchain to attach
Windows' console debugger (cdb.exe) to a live retail acclient.exe with
full PDB symbols and capture state at any breakpoint. **Use this when
guessing has failed twice in a row.**

### What we have

- **Matching binary**: `C:\Users\erikn\Downloads\acclient.exe`
  v11.4186 (linker timestamp `2013-09-06 00:17:56 UTC`,
  CodeView GUID `9e847e2f-777c-4bd9-886c-22256bb87f32`). Pairs
  exactly with our `refs/acclient.pdb`. The current
  `C:\Turbine\Asheron's Call\acclient.exe` is a 2015 build with GUID
  `08e25c14-e2a1-46d5-b056-92b2e43a7234` and must not be used for
  this PDB/address map.
- **Debugger**: `cdb.exe` (console WinDbg) at
  `C:\Program Files (x86)\Windows Kits\10\Debuggers\x86\cdb.exe`.
  Install via Microsoft Store WinDbg (~50 MB). 32-bit version is
  required for acclient.exe.
- **PDB**: `refs/acclient.pdb` (29 MB, Sept 2013 EoR build).
  18,366 named functions + 5,371 named struct types resolve.
- **Symbol verifier**: `tools/pdb-extract/check_exe_pdb.py <exe>`
  reads any acclient.exe and prints whether it pairs with our PDB
  (`MATCH` / `MISMATCH (expected GUID = ...)`). Always run this on
  a candidate binary BEFORE attaching.
- **PDB metadata dumper**: `tools/pdb-extract/dump_pdb_info.py refs/acclient.pdb`
  prints the PDB's expected timestamp + GUID + age. Use to figure
  out which build to look for if the chain ever breaks.

### Workflow

1. **Verify the binary matches the PDB:**
   ```bash
   py tools/pdb-extract/check_exe_pdb.py "C:/Users/erikn/Downloads/acclient.exe"
   ```
   Expect: `=== MATCH: this exe pairs with our acclient.pdb ===`

2. **Have the user launch retail client** and connect to local ACE.
   Retail must already be in-world before attaching.

3. **Write a `.cdb` script** that arms breakpoints with non-blocking
   actions (count + log + `gc`). Pattern:
   ```
   .logopen <output-path>
   .sympath C:\Users\erikn\source\repos\acdream\refs
   .symopt+ 0x40
   .reload /f acclient.exe

   r $t0 = 0
   bp acclient!CTransition::transitional_insert "r $t0 = @$t0 + 1; .if (@$t0 % 5000 == 0) { .printf \"...\" }; .if (@$t0 >= 30000) { qd } .else { gc }"
   bp acclient!OBJECTINFO::kill_velocity "r $t1 = @$t1 + 1; gc"
   ...
   g
   ```
   `gc` = "go conditional" (continue without breaking). Auto-detach
   via `qd` after a hit-count threshold to avoid manual cleanup.

4. **Launch cdb in the background** via a PowerShell wrapper:
   ```powershell
   & "C:\Program Files (x86)\Windows Kits\10\Debuggers\x86\cdb.exe" `
       -pn acclient.exe -cf <script>.cdb *>&1 |
       Tee-Object -FilePath <log>
   ```

5. **User reproduces the scenario** in the retail client window
   (jump on roof, hit wall, etc.). Breakpoints fire, log fills.

6. **cdb auto-detaches** when the threshold breakpoint fires `qd`.
   Retail keeps running unaffected. Read the log offline.

### Known watchouts

- **PDB function names use snake_case for some classes**
  (BSPTREE, CTransition, OBJECTINFO, COLLISIONINFO, SPHEREPATH) and
  **PascalCase for others** (CPhysicsObj). The Binary Ninja decomp
  shows snake_case for everything; the PDB has Turbine's actual
  PascalCase for CPhysicsObj. Always look up symbols with `x` first
  to find the actual name.

- **`bp acclient!Class::method`** sets a breakpoint by symbol. The
  cdb command parser splits on `;`, so don't put `;` inside the
  action string — use newlines or escape carefully.

- **Symbol path: do NOT use `.sympath srv*<server>;<local>`** — the
  `;` is a cdb command separator, gets split. Use `.sympath <local>`
  (no symbol server, just our refs/) since we don't need Microsoft
  system DLL symbols.

- **Killing cdb kills the debuggee.** Use `qd` (quit detached) inside
  a breakpoint action to detach cleanly. `Stop-Process cdb` will
  take the retail client down with it.

- **High breakpoint hit rates produce game lag.** Each breakpoint hit
  traps the process briefly. For frequent functions
  (transitional_insert at ~10K/sec) the cumulative cost is enough to
  make retail feel sluggish. Mitigate by setting a tight auto-detach
  threshold (e.g., 30,000 hits) and/or moving counters to less-frequent
  functions.

- **acclient.exe is 32-bit + uses thiscall.** When dumping struct
  fields in breakpoint actions, `this` is in `ecx`. Use cdb's
  `dt acclient!ClassName @ecx` for full struct dump.

### When NOT to use this

- **Pure code-port questions** — the decomp at `docs/research/named-retail/`
  has the answer. Don't waste time on cdb if `grep` is enough.
- **Visual / rendering bugs** — debugger doesn't help with shaders or
  framebuffers; use RenderDoc or similar.
- **Network protocol questions** — `holtburger` references + ACE source
  + Wireshark are the right tools, not cdb.

## MCP servers (live tooling)

Two MCP servers extend the static decomp + cdb workflow with live
introspection. **Ghidra MCP** requires Ghidra to be running with a
CodeBrowser open in the target project; **WireMCP** auto-loads at
Claude Code startup.

### Ghidra MCP (LaurieWired v1.4, HTTP)

Starts an HTTP server on **port 8080** (or **8081** if 8080 is
taken — first-open-wins) when a CodeBrowser tool opens a program.
Currently serving **`patchmem.gpr`** — the 2013 v11.4186 build with
full PDB applied, same source as `docs/research/named-retail/`. Use
this when grep'ing `acclient_2013_pseudo_c.txt` returns too much
noise and you want the decomp for one specific function or address
without dumping the whole file into context.

Probe: `curl http://127.0.0.1:8081/methods?limit=3`

Useful endpoints (GET unless noted):

- `/methods?limit=N` — function names
- `/list_functions?limit=N` — `Name at HHHHHHHH` lines
- `/decompile_function?address=0xHHHHHHHH` — decompiled C for one function
- `/function_xrefs?name=...` — callers / callees
- `/classes`, `/namespaces`, `/strings`
- POST `/rename_function_by_address`, POST `/set_decompiler_comment`

NO endpoints for: signature setting, namespace setting, script
execution, save-project. Those still require Ghidra's GUI or
`analyzeHeadless`. Full endpoint catalog + Ghidra project layout in
`memory/reference_ghidra_projects.md`.

### WireMCP (stdio, Node, user-scope)

Wraps `tshark` at `C:\Program Files\Wireshark\tshark.exe`
(auto-detected via the Windows fallback path in `WireMCP/index.js`).
Direct fit for ACE wire-protocol work — capture loopback
(`127.0.0.1:9000`) to cross-check inbound message parsing (`0xF61C`
movement, `0xF74A` pickup despawn, `0xF7DE` chat, etc.) against the
actual bytes, or diff ACE's outbound vs. the holtburger reference.
Replaces ad-hoc Wireshark sessions in the conversation.

Tools exposed:

- `capture_packets` — short live capture on an interface, returns JSON
- `get_summary_stats` — protocol hierarchy stats
- `get_conversations` — TCP/UDP conversation table
- `analyze_pcap` — parse a saved `.pcap` file
- `check_threats`, `check_ip_threats` — URLhaus / threat-feed lookups
- `extract_credentials` — grep for creds across protocols (rarely relevant)

Installed at `C:\Users\erikn\source\repos\WireMCP\` (clone of
`0xKoda/WireMCP`). Registered via `claude mcp add wiremcp --scope user`.

**When NOT to use WireMCP:** decoding the AC packet *format* — that
lives in `holtburger`, ACE, and `Chorizite.ACProtocol`. WireMCP shows
you the bytes on the wire; the reference repos tell you what they
mean.

## Subagent policy

Subagents are the primary tool for saving parent-context and keeping one
session productive across many phases. Use them liberally for:

- Bounded implementation chunks with a clear spec (one file, one test suite,
  a targeted refactor)
- Parallel independent tasks with no shared state
- Research that would otherwise fill the parent context with file reads

**Model selection:**

- **Default: Sonnet.** Use Sonnet for all execution work — implementers,
  research agents, spec-following work, test writing, refactors, repeated
  patterns. Sonnet is the right cost/context/capability tradeoff for this
  codebase and has been validated on every phase since Phase 2a. Do not
  reach for Opus unless you have a specific reason.
- **Opus only for load-bearing quality review** — code review of a phase
  boundary, a design that must be right the first time, a gnarly
  cross-system refactor. "This feels hard" is not enough; specify why it
  needs Opus in the task description.
- Never use Haiku for acdream work unless the task is literally checking
  whether another process is alive.

**Prompt discipline:** when dispatching a subagent, include the relevant
spec path, the files it should read, the acceptance criteria (build + test
green), and the commit message style. Subagents inherit CLAUDE.md so they
follow the same rules.

## Milestone discipline

acdream operates at **two altitudes** above the daily commit:

- **`docs/plans/2026-05-12-milestones.md`** — the morale + scope layer.
  Seven milestones (M0–M7) from "Connect & explore" to "v1.0", each
  defined by a concrete playable scenario and ~6–10 weeks of work. This
  is where you orient when the project feels half-built and you're not
  sure what to work on. Phases are too granular to feel like progress;
  this doc is the multi-week target.
- **`docs/plans/2026-04-11-roadmap.md`** — the strategic roadmap.
  Phase-level index. This is where you orient when you know the
  milestone and need the next concrete sub-phase.

**Work-order autonomy — the meta-rule.** You decide what to work on
next, always. **The user does NOT pick between phases, milestones, or
"what's next?" alternatives.** The milestone discipline + the
per-milestone phase list + the roadmap IS the work order — drive it.
Never ask the user "want me to start X or Y?" or present a menu of
options. If two next steps are genuinely equivalent, state which one
you picked and why in one sentence and start — don't ask. The user
retains the right to redirect if they think you're wrong, but the
default is **Claude drives, user reviews**. The user finds decision
fatigue from constant work-order choices draining — that's literally
what triggered the milestones doc on 2026-05-12. Honoring this rule is
the single biggest morale lever. This is the meta-rule that makes the
four below actually work.

**The four motivation-keeping rules:**

1. **One active milestone at a time.** Work that isn't on the critical
   path to the current milestone gets filed in `docs/ISSUES.md` with
   the appropriate `post-Mx` tag and muted. This is the single rule
   that kills the "jumping between things" feeling. If a phase isn't
   part of the current milestone, it doesn't get touched — even if
   it's tempting, even if it would be "quick", even if it would be
   "while I'm here."

2. **Frozen phases are off-limits.** Shipped-milestone phases are
   frozen until M7's polish pass. Concretely: no rework on streaming,
   chat, input, the WB rendering migration, sky/lighting, the particle
   system, or the network handshake. Those are done. Don't revisit them
   — even if you see something that could be 10% better. Visual
   nice-to-haves and architecture second-guesses on frozen phases are
   explicitly post-M7. The freeze list per milestone lives in the
   milestones doc.

3. **Crossing a milestone is a textual event, not a video event.**
   When a milestone's demo scenario is functionally complete, update
   `2026-05-12-milestones.md` with a one-paragraph writeup describing
   what works end-to-end, flip the freeze list, and update the
   "currently working toward" line in this CLAUDE.md's **Current
   state** section to the next milestone. Do NOT ask the user to
   record a demo video — they find it pointless. The milestones doc
   + the CLAUDE.md flip ARE the milestone artifact. Phases ship;
   milestones land.

4. **State both altitudes at session start.** First action of any
   session: "Currently working toward [milestone]. Current phase:
   [phase]. Next concrete step: [whatever]." This keeps the high-level
   orientation visible alongside the immediate task and makes
   mid-session drift obvious. The **Current state** section at the
   top of this file is the always-current snapshot.

When reality and the milestones diverge — a phase grows beyond the
milestone's scope, a demo scenario turns out to be unreachable without
a new sub-phase, the order needs reshuffling — update the milestones
doc in the same session you discover the divergence. Same rule as the
roadmap.

## Roadmap discipline

acdream's plan lives in two files committed to the repo:

- **`docs/plans/2026-04-11-roadmap.md`** — the strategic roadmap. Single
  source of truth for what's shipped, what's next, and the agreed order.
  When you're about to pick up new work, read this first. When you ship a
  phase or sub-step, move it from "ahead" to "shipped" in the same commit
  that lands the work (or the very next commit).

- **`docs/superpowers/specs/*.md`** — per-phase detailed implementation
  specs. Each active phase has one. When you're about to write code for a
  named phase, read its spec, follow its component boundaries, and match its
  acceptance criteria. Do not drift from the spec without explicit user
  approval.

**Rules:**

1. Before starting a new phase or sub-piece, re-read the roadmap and the
   relevant spec. State which phase you're on in the first action you take.

2. When reality and the plan diverge — the user observes a bug that doesn't
   fit any existing phase, a technical discovery makes a phase description
   wrong, a sub-piece turns out to be larger than expected — **pause and
   brainstorm** with the `superpowers:brainstorming` skill before writing
   code. Update the roadmap in the same session.

3. When shipping a phase, update the roadmap's "shipped" table and commit
   the update in the same commit as (or immediately after) the
   implementation commit.

4. Do not invent new phase numbers / letters on the fly. If you need a new
   phase, add it to the roadmap first with the user, then reference it by
   its assigned identifier. "Phase 11" and "Phase 9.3" conjured
   mid-sentence are process smells — they mean the plan got out of sync
   with the work.

5. If a single session ends up shipping work that spans multiple roadmap
   phases, that's fine, but each commit message should name the phase it
   belongs to (e.g. `feat(core): Phase A.1 — streaming region`).

The roadmap is not sacred — it changes. It IS the source of truth at any
given moment. When it's wrong, fix it. When it's right, follow it.

## Issue tracking — `docs/ISSUES.md`

Tactical rolling list of known bugs + small deferred features. Scope:
anything that fits in one-to-two commits; larger work stays as a Phase
in the roadmap. Maintenance rules:

1. **Start-of-session:** scan OPEN issues in `docs/ISSUES.md` — any of
   them in the area you're about to touch? Plan accordingly.
2. **End-of-session:** if this session observed a defect and didn't fix
   it inline, add an issue. If this session fixed an OPEN issue, move
   it to **Recently closed** with the commit SHA.
3. **Commit messages:** reference issue IDs when a commit closes one
   (`fix #3: periodic TimeSync parsing`). Makes `git log --grep='#3'`
   return the full fix history.
4. **Promotion:** if an issue grows into multi-commit work, promote it
   to a Phase in the roadmap. Close the issue as
   `DONE (promoted to Phase X)` and reference the roadmap commit.

The roadmap is strategic (month-scale, phase-level). ISSUES is tactical
(week-scale, bug-level). They reference each other but don't duplicate.

## Running the client against the live server

The user runs a **local ACE (Asheron's Call Emulator) server on
`127.0.0.1:9000`** that stays up continuously. Iteration loop: launch the
acdream client, connect, test, close the window, rebuild, relaunch.

### Connection details

| Setting | Value |
|---|---|
| Host / port | `127.0.0.1` / `9000` |
| Account | `testaccount` |
| Password | `testpassword` |
| Character | `+Acdream` (server guid `0x5000000A`) — this is a `+` GM-marker character for dev testing |
| DAT directory | `%USERPROFILE%\Documents\Asheron's Call\` (contains `client_portal.dat`, `client_cell_1.dat`, `client_highres.dat`, `client_local_English.dat`) |

### Launch command

The canonical launch is via `dotnet run` with environment variables set.
Use PowerShell (Windows native) — bash struggles with the apostrophe in
`"Asheron's Call"`:

```powershell
$env:ACDREAM_DAT_DIR   = "$env:USERPROFILE\Documents\Asheron's Call"
$env:ACDREAM_LIVE      = "1"
$env:ACDREAM_TEST_HOST = "127.0.0.1"
$env:ACDREAM_TEST_PORT = "9000"
$env:ACDREAM_TEST_USER = "testaccount"
$env:ACDREAM_TEST_PASS = "testpassword"
dotnet run --project src\AcDream.App\AcDream.App.csproj --no-build -c Debug
```

Always pipe to a log file for post-run diagnostic grep:
`2>&1 | Tee-Object -FilePath "launch.log"`. Run in the background via
the `run_in_background: true` parameter so the tool doesn't block waiting
for the window to close.

### Logout-before-reconnect

**ACE keeps your last session alive after a disconnect, and the duration
depends on HOW the client exited.** Two cases:

1. **Graceful close (client sent logout packet to ACE):** session clears
   in ~3–5 seconds. Wait briefly between launches.
2. **Hard kill (Stop-Process, crash, force-close):** no logout packet
   reached ACE. ACE keeps the session marked logged-in until its own
   timeout — observed in practice at ~3+ minutes. Subsequent relaunches
   fail with `live: session failed: CharacterList not received` (exit 29)
   the entire time. **There is no admin command available to us to kick
   the stale session.** Either wait it out, or use the graceful path
   below.

**Prefer the graceful close path when ending a launch.** PowerShell's
`Stop-Process` is a hard kill — it bypasses the client's shutdown hook
which is where the logout packet would have been sent. The graceful
alternative sends WM_CLOSE so the window's close handler runs:

```powershell
$proc = Get-Process -Name AcDream.App -ErrorAction SilentlyContinue
if ($proc) {
    $proc.CloseMainWindow() | Out-Null
    if (-not $proc.WaitForExit(5000)) {
        # Fell through to hard-kill — session WILL be stuck on ACE.
        $proc | Stop-Process -Force
    }
}
Start-Sleep -Seconds 3
# ... then launch ...
```

If `WaitForExit(5000)` returns false (the client didn't exit in 5 seconds
after WM_CLOSE), the client is unresponsive and a hard kill is the only
option — accept that ACE will be unhappy for a few minutes.

**When recovering from a hard-killed session that ACE still considers
active:** the only honest answer is to wait. Don't bother retrying every
30 seconds — make a single retry attempt ~3 minutes after the kill, and
if it still fails wait another 2 minutes before trying again. The user
will likely volunteer when ACE has cleared the session if you ask.

The user has repeatedly confirmed this — don't treat exit-29-after-relaunch
as a code bug. It's a server-side session-cleanup delay whose duration is
governed by whether the previous shutdown was graceful or forced.

### Test character

`+Acdream` at server guid `0x5000000A`. Starts at or near Holtburg. Has
basic stats; `ACDREAM_RUN_SKILL` / `ACDREAM_JUMP_SKILL` env vars (default
200) set the *client-side* skill value used by `PlayerWeenie.InqRunRate`
for local motion prediction. **These are NOT synced to the server** —
ACE's own character data is authoritative for broadcast motion. If you
see a speed/anim mismatch between local and observer views, the fix is
to sync the runSkill from ACE via `UpdateMotion.ForwardSpeed` echo (wired
via `PlayerMovementController.ApplyServerRunRate`) or from
`PlayerDescription (0x0013)`.

### Diagnostic env vars

- `ACDREAM_DUMP_MOTION=1` — dump every inbound `UpdateMotion` (guid,
  stance, cmd, speed) + resulting `SetCycle` call. Massive for remote-
  animation debugging.
- `ACDREAM_STREAM_RADIUS=N` — **legacy** streaming-radius override
  (`RuntimeOptions.LegacyStreamRadius`). **Default is UNSET**, not 2: the
  shipped radii come from the quality preset
  (`QualityPreset.High` = NearRadius 4 / FarRadius 12, i.e. a 9×9 Near ring
  inside a 25×25 Far window). When set it FORCES `NearRadius = N` and only
  ever RAISES `FarRadius` (`SessionPlayerComposition.ComposeCore`), and it is
  silently discarded by any later Settings `ApplyQuality`
  (`RuntimeSettingsTargets.ApplyQuality` → `ReconfigureRadii`). **Leave it
  unset for any measurement or gate run** — with it set you are measuring a
  different window than production. Per-axis overrides
  `ACDREAM_NEAR_RADIUS` / `ACDREAM_FAR_RADIUS` (`QualitySettings.WithEnvOverrides`)
  are the modern spelling.
- `ACDREAM_PROBE_REVEAL_RADIUS=N` — #280 A/B measurement probe
  (`StreamingDiagnostics.RevealRadiusOverride`). Forces the outdoor reveal
  gate to landblock radius N instead of the derived streaming window, so the
  same binary can run a route once with the pre-#280 behaviour (`=1`) and once
  without. Not a user setting; not surfaced in Settings; not persisted.
  Values below 1 are rejected by the parser: an outdoor acknowledgement with
  `RequiredRenderRadius == 0` fails Runtime's `invalid-readiness-shape`
  invariant, so `=0` would hang the route it is meant to measure.
- `ACDREAM_NO_AUDIO=1` — suppress OpenAL init for headless / driver-
  broken setups.
- `ACDREAM_REMOTE_VEL_DIAG=1` — dump per-tick / per-UM remote motion
  diagnostics (`[UM_RAW]`, `[SCFAST]`, `[SCFULL]`, `[SETCYCLE]`,
  `[FWD_WIRE]`, `[OMEGA_DIAG]`, `[SEQSTATE]`, `[PARTSDIAG]`,
  `[VEL_DIAG]`, `[UPCYCLE]`). Heavy.
- `ACDREAM_PROBE_RESOLVE=1` — one `[resolve]` line per
  `PhysicsEngine.ResolveWithTransition` call: input + target + output
  position/cell, ok-vs-partial, grounded-in, contact-plane status,
  wall normal if hit, **responsible entity guid**, env flag, walkable
  polygon valid. Heavy (~30 Hz × every entity). Runtime-toggleable via
  the DebugPanel "Diagnostics" section if `ACDREAM_DEVTOOLS=1`.
- `ACDREAM_PROBE_CELL=1` — one `[cell-transit]` line per
  `PlayerMovementController.CellId` change: old → new cell, world
  position, reason tag (`resolver` / `teleport`). Low volume — only
  fires on actual cell crossings. Runtime-toggleable via the same
  DebugPanel section.
- `ACDREAM_PROBE_PUSH_BACK=1` — emits three line types per physics
  tick: `[push-back]` (per `BSPQuery.AdjustSphereToPlane` call),
  `[push-back-disp]` (per `BSPQuery.FindCollisions` dispatch),
  `[push-back-cell]` (per `Transition.CheckOtherCells` off-cell hit).
  Heavy under motion (~100–500 lines/sec). Pair with retail's cdb
  breakpoint set at `tools/cdb/a6-probe.cdb` for the A6.P1 capture
  protocol. Runtime-toggleable via the DebugPanel.
- `ACDREAM_PROBE_FLAP=1` — capture probe for indoor visibility
  decisions at frame boundaries. Used to converge the U.4c flap fix
  (root indoor visibility at player's cell, not eye).
- `ACDREAM_PROBE_STICKY=1` — per-guid sticky-melee timeline: `[sticky]`
  lifecycle lines (STICK/UNSTICK/LEASE-EXPIRE/TARGET-status teardown),
  per-armed-tick steer lines (signed gap dist, applied delta, heading
  delta), `[sticky-snap-skip]` at the suppressed NPC UP-snap site.
  Heavy while a pack is stuck (~60 Hz × stuck count). Converged the
  #171 residuals (the deep-overlap sign pin AP-82).
- `ACDREAM_PROBE_SUPPORT=1` — **what is holding a body up, and is the
  collision geometry where the visual geometry is?** (#337, TEMPORARY).
  `[support]`: one line per resolve **for every body, not just the player**
  (a corpse falling through geometry is the cheapest control there is on
  "movement code vs geometry data"). It samples the outdoor terrain
  independently at the body's own out-XY and prints the contact plane's own
  height at that same XY, so `support=terrain` / `object` / `none` is a
  measurement rather than an inference; `cpSrc=` names the site that wrote
  the plane so provenance cross-checks the classification. Edge-eager,
  throttled to 4 Hz per body, and emits every 10 cm of vertical movement.
  `[geom]`: once per GfxObj near the mover — the object's physics-BSP vertex
  cloud against its visual mesh AABB in the same frame, with a verdict
  (`coincident` REFUTES "collision isn't where the visual is";
  `no-physics-bsp` / `empty-physics-bsp` / `displaced` / `extent-mismatch`
  each name a data defect). `ACDREAM_PROBE_RESOLVE` alone cannot separate
  those cases — it carries no plane normal, no plane height, no terrain
  sample and no provenance.
- `ACDREAM_WIRE_MESH=1` — upgrades the existing **F2** collision overlay from
  a broadphase proxy cylinder to the real physics-BSP polygon edges (cyan)
  beside the same objects' visual mesh boxes (magenta) and the terrain
  surface (yellow). Settles "visual versus collision" by eye instead of by
  log. `ACDREAM_WIRE_RADIUS=<metres>` sets the window (default 30).
  TEMPORARY, with the #337 probe family.
- `ACDREAM_CAPTURE_RESOLVE=<path>` — live capture of every player-side
  `PhysicsEngine.ResolveWithTransition` call. Each call appends one
  JSON Lines record with full inputs, PhysicsBody snapshot before AND
  after, plus the `ResolveResult`. Filtered to `IsPlayer` mover flag
  — NPC / remote DR calls don't pollute. Pairs with the trajectory
  replay harness comparison tests to diff captured vs harness state
  per field — the first divergence pinpoints missing apparatus state.
  Capture is OFF when the env var is unset (one null-check cost per
  call).
- `ACDREAM_DUMP_CELLS=<path>` / `ACDREAM_DUMP_GFXOBJS=<path>` — dump
  resolved cell/GfxObj polygon tables as JSON when ids cache. Used
  for harness fixture extraction.

### Outbound motion wire format (acdream → ACE)

Important quirk for cross-checking observed remote behavior. acdream's
`PlayerMovementController` + `MoveToState` builder encode motion as:

| Local input | Wire `ForwardCommand` | Wire `HoldKey` | Wire `ForwardSpeed` |
|---|---|---|---|
| W (run) | `WalkForward` (0x05) | `Run` (2) | server runRate (~2.4–2.94) |
| W + Shift (walk) | `WalkForward` (0x05) | `None` (1) | 1.0 |

ACE auto-upgrades `WalkForward + HoldKey.Run` → `RunForward (0x07)`
when relaying to remote observers. So our INBOUND parser sees
`fwd=0x07` for "remote is running." This matches retail's encoding.

When the local player toggles Shift while keeping W held (Run↔Walk
demote/promote), acdream sends a fresh `MoveToState` with the new
HoldKey + ForwardSpeed. Retail's outbound likely does the same, but
ACE's behavior on relay is uncertain — see open issues in `docs/ISSUES.md`
for the Run↔Walk cycle bug on observed retail-driven remotes.

### Visual verification workflow

1. Make a code change.
2. `dotnet build` — must be green before launch.
3. Launch (background). Give it ~8 s to reach in-world state.
4. User tests in the running client (moves, interacts, watches remote
   chars). Close window when done.
5. Read `launch.log` or the task output file for diagnostic lines.
6. Iterate.

Never launch without first confirming the build is green. A failed launch
from a compile error wastes the user's testing time and can kill an
already-running ACE session via the handshake race.

### What the user watches for

- **Own character** in acdream: correct animation, correct speed, proper
  transitions (walk → run, run → stop, jump → land, strafe, turn).
- **Remote toons from a retail client viewing acdream**: the user often
  runs the retail AC client in parallel and watches the acdream `+Acdream`
  character from there. When they report "lagging forward" or "walking
  when I should be running" that's the **retail observer view**, not the
  acdream view. Distinguish these carefully — they're different code paths.
- **NPCs / monsters in acdream**: animate their emotes, idle, attacks,
  stop transitions, and keep their visual position tracked smoothly
  between the 5–10 Hz UpdatePosition bursts (dead-reckoning).

## Reference repos: cross-check the relevant ones

The `references/` tree holds **five** vendored projects (ACE, ACViewer,
WorldBuilder, Chorizite.ACProtocol, holtburger). They overlap in
some areas and disagree in others. Before committing to an approach,
**cross-reference at least two of them** for the domain you're working
in — the per-domain hierarchy in the next section tells you which to
read first. A single reference can be misleading; the intersection of
the relevant references is almost always the truth. The user has
repeatedly had to remind me about this when I narrowly searched one ref
and missed obvious answers in another.

The five references:

- **`references/ACE/`** — ACEmulator server. Authority on the wire
  protocol (packet framing, ISAAC, game message opcodes, serialization
  order). The things a server has to know to parse and produce bytes.
- **`references/ACViewer/`** — MonoGame-based dat viewer that actually
  renders characters + world. Authority on the client-side visual
  pipeline: ObjDesc application, palette overlays, texture decoding
  for the palette-indexed formats. See
  `ACViewer/Render/TextureCache.cs::IndexToColor` for the canonical
  subpalette overlay algorithm.
- **`references/WorldBuilder/`** — **acdream's rendering + dat-handling
  base.** WorldBuilder is not just a reference: `ObjectMeshManager` is
  the production mesh pipeline, `WbMeshAdapter` is the seam, and
  `WbDrawDispatcher` is the production draw path. The modern path is
  **mandatory** — missing bindless throws at startup, there is no
  legacy fallback. **Before re-porting any rendering or dat-handling
  algorithm from retail decomp, read
  `docs/architecture/worldbuilder-inventory.md` first.** The inventory
  tells you what WB covers (terrain, scenery, static objects, EnvCells,
  portals, sky, particles, texture decoding, mesh extraction,
  visibility/culling) and what we still write ourselves (the 🔴 list:
  network, physics, animation, movement, UI, plugin, audio, chat).
  WorldBuilder is MIT-licensed and exact-stack with us (Silk.NET +
  .NET); the divergences we've documented (e.g. WB's terrain split
  formula vs retail's `FSplitNESW`) are called out in the inventory
  doc.
- **`references/Chorizite.ACProtocol/`** — clean-room C# protocol
  library generated from a protocol XML description. Useful sanity check
  on field order, packed-dword conventions, type-prefix handling. The
  generated Types/*.cs files have accurate field comments (e.g. "If
  it is 0, it defaults to 256*8") that ACE's server-side code doesn't.
- **`references/holtburger/`** — **Almost-complete Rust TUI AC client.**
  Not just a crate or a handshake reference: it's a full client that
  logs in, plays the game, sends/receives chat, handles combat, and
  renders state in a terminal. **This is acdream's most authoritative
  reference for client-side behavior** — anything about how a client
  is *supposed* to talk to the server lives here. Specifically:
    - Handshake / login flow including all the post-EnterWorld
      messages retail clients send (LoginComplete, ack pump,
      DDDInterrogation responses, etc).
    - The proper ACK_SEQUENCE pattern (every received packet with
      sequence > 0 gets an ack queued back; not periodic).
    - Outbound game-action message construction with sequence
      numbering.
    - Message routing and session lifecycle.
  Look here FIRST when implementing anything in `WorldSession` or
  the message-builder layer. ACE shows what the server expects;
  holtburger shows what a real client actually sends.

**AC2D is a retired reference (2026-07-29).** It was a C++ AC client demo
and the sixth entry in this list; it is no longer vendored under
`references/` and must not be re-cloned. Everything we took from it is
already written down and still stands: the terrain split formula
`FSplitNESW` (constants `0x0CCAC033`, `0x421BE3BD`, `0x6C1AC587`,
`0x519B8F25`), the `0xF61C` movement packet layout, and the finding that a
client need not compute terrain Z itself. The historical analysis lives in
`docs/research/2026-04-12-movement-deep-dive.md`; the UI dat-id work it fed
is in `docs/research/retail-ui/`. Cite those, not the repo.

### Reference hierarchy by domain

**NEVER GUESS an algorithm, formula, constant, wire format, or coordinate
convention.** Every AC-specific behavior has a reference implementation in
one of the repos below. If you find yourself writing AC-specific code
without having read the matching reference first, STOP and read it. The
triangle-boundary Z bug cost 5 failed fix attempts because we guessed
instead of checking ACME's `ClientReference.cs` — which had the exact
decompiled client code and would have fixed it in minutes.

**The rule: read the reference FIRST, write code SECOND. Always.**

| Domain | Primary Oracle | Secondary | Notes |
|--------|---------------|-----------|-------|
| **Any AC-specific algorithm** | **`docs/research/named-retail/`** (PDB-named decomp + verbatim retail header structs from Sept 2013 EoR build) | the existing references below | The retail client itself, fully named. 18,366 functions + 5,371 struct types + 1.4 M lines of pseudo-C in one searchable tree. Beats every other reference for "what does the real client do." Use for everything in the 🔴 list (network, physics, animation, movement, UI, plugin, audio, chat). |
| **Terrain** (split direction, height sampling, palCode, vertex position, normals) | **WorldBuilder `TerrainGeometryGenerator.cs` + `TerrainUtils.cs`** | retail decomp for cross-check | WB is acdream's terrain base. ACME's port is older/SUPERSEDED by WB. |
| **Terrain blending** (texture atlas, alpha masks, road overlays) | **WorldBuilder `LandSurfaceManager.cs`** | ACME `LandSurfaceManager.cs` (same algo, less complete) | WB is acdream's blending base. |
| **Scenery** (procedural placement: trees, bushes, rocks, fences) | **WorldBuilder `SceneryRenderManager.cs` + `SceneryHelpers.cs`** | retail decomp `CLandBlock::get_land_scenes` | WB is acdream's scenery base. Re-porting from retail decomp is what caused the edge-vertex bug. |
| **GfxObj / Setup rendering** (mesh extraction, multi-part assembly, ObjDesc) | **WorldBuilder `StaticObjectRenderManager.cs` + `ObjectMeshManager.cs`** | ACME `StaticObjectManager.cs` (includes CreaturePalette, GfxObjRemapping, HiddenParts — useful for character appearance which WB doesn't cover) | WB for static objects, ACME for character appearance. |
| **Texture decoding** (INDEX16, P8, DXT, BGRA, alpha) | **WorldBuilder `TextureHelpers.cs`** | ACME `TextureHelpers.cs`; ACViewer's `IndexToColor` is canonical for subpalette overlay | WB is acdream's decode base. |
| **EnvCell / dungeon rendering** (cell geometry, portal visibility, collision mesh) | **WorldBuilder `EnvCellRenderManager.cs` + `PortalRenderManager.cs`** | ACME `EnvCellManager.cs` (more complete for collision); ACViewer `Physics/Common/EnvCell.cs` | WB is acdream's geometry base; ACME for collision until ported. |
| **Particles / sky** (particle systems, weather, sky particles) | **WorldBuilder `SkyboxRenderManager.cs` + `ParticleEmitterRenderer.cs` + `ParticleBatcher.cs`** | retail decomp | WB is acdream's particle base. |
| **Visibility / culling** (frustum, cell visibility) | **WorldBuilder `VisibilityManager.cs` + `Frustum.cs`** | — | WB. |
| **Network protocol** (wire format, packet framing, fragment assembly, ISAAC) | **holtburger** `crates/holtburger-session/` | `docs/research/named-retail/` | ACE shows the server side; holtburger shows the client side. AC2D was the second client-side cross-check here — retired reference; historical analysis remains in `docs/research/2026-04-12-movement-deep-dive.md`. |
| **Client behavior** (what to send when, login flow, ack pattern, keepalive) | **holtburger** `crates/holtburger-core/src/client/` | `docs/research/named-retail/` | holtburger is the most complete. AC2D was the simpler confirmed-working cross-check — retired reference; historical analysis remains in `docs/research/2026-04-12-movement-deep-dive.md`. |
| **Movement** (MoveToState format, AutonomousPosition, sequence counters, speed) | **holtburger** `client/movement/` | `docs/research/named-retail/` | AC2D `cNetwork.cpp:2592-2664` was the `0xF61C` format secondary — retired reference; historical analysis remains in `docs/research/2026-04-12-movement-deep-dive.md`, which carries the packet layout and the terrain-split formula verbatim. |
| **Server expectations** (what ACE accepts/rejects, validation thresholds) | **ACE** `Source/ACE.Server/Network/` | — | Only ACE knows what the server actually validates. |
| **Silk.NET / .NET 10 idioms** (GL calls, shader setup, VAO patterns) | **WorldBuilder original** | ACME (same stack) | Both use the same backend; original has cleaner isolated examples. |
| **Protocol field order** (packed dwords, type prefixes, flag enums) | **Chorizite.ACProtocol** `Types/*.cs` | holtburger (cross-check) | Generated from protocol XML; has accurate field comments. |

### ACME key files quick reference

These are the files you should open FIRST when working on any rendering
or dat-interpretation task:

- **`WorldBuilder.Tests/ClientReference.cs`** — decompiled retail AC
  client C# port. `IsSWtoNECut`, `GetPalCode`, `GetVertexHeight`,
  `GetVertexPosition`. **The ground truth.** If your code disagrees
  with this file, your code is wrong.
- **`WorldBuilder.Tests/TerrainConformanceTests.cs`** — 4M+ cell sweep
  proving ACME matches retail. Port these into acdream's test suite for
  any algorithm you touch.
- **`StaticObjectManager.cs`** — GfxObj+Setup+CreaturePalette pipeline.
- **`EnvCellManager.cs`** — dungeon cells + portal visibility.
- **`TerrainGeometryGenerator.cs`** — `GetHeight()`, `GetNormal()`,
  `CalculateSplitDirection()` matching the mesh index buffer.
- **`TextureHelpers.cs`** — INDEX16, BGRA, DXT decode helpers.

### holtburger key files quick reference

These are the files you should open FIRST when working on any networking
or client-behavior task:

- **`client/movement/system.rs`** — the movement state machine (when to
  send MoveToState vs AutonomousPosition, deduplication logic).
- **`client/movement/actions.rs`** — MoveToState, AutonomousPosition,
  Jump wire format builders.
- **`client/movement/types.rs`** — RawMotionState packed format with
  all flag bits documented.
- **`session/send.rs`** — packet construction, checksum, ISAAC, ACK
  piggybacking.
- **`client/messages.rs`** — post-login message handlers (PlayerCreate
  → LoginComplete, DddInterrogation → response, PlayerTeleport).
- **`spatial/physics.rs`** — dead-reckoning solver (how the client
  advances position between server updates).