From d3621726204a9a7e6ec58468af27a4d0eb62c7b4 Mon Sep 17 00:00:00 2001 From: Erik Date: Sun, 26 Jul 2026 08:29:06 +0200 Subject: [PATCH] docs(runtime): close inventory state ownership Record J4.2's single Runtime inventory transaction graph, complete Release evidence, exact-binary lifecycle/reconnect acceptance, rollback, and the J4.3 magic/player-sheet boundary. Synchronize architecture, roadmap, milestones, agent guidance, and durable memory. Co-authored-by: Codex --- AGENTS.md | 13 ++- CLAUDE.md | 13 ++- docs/architecture/acdream-architecture.md | 4 +- docs/plans/2026-04-11-roadmap.md | 11 +- docs/plans/2026-05-12-milestones.md | 7 +- .../2026-07-24-modern-runtime-architecture.md | 5 +- .../2026-07-25-modern-runtime-slice-j.md | 10 +- .../2026-07-26-modern-runtime-slice-j4.md | 22 +++- .../2026-07-26-slice-j4-2-inventory-state.md | 101 ++++++++++++++++++ 9 files changed, 168 insertions(+), 18 deletions(-) create mode 100644 docs/research/2026-07-26-slice-j4-2-inventory-state.md diff --git a/AGENTS.md b/AGENTS.md index 05640ee9..89474ae4 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -245,7 +245,13 @@ 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 inventory transaction ownership is active. J0's rollback is +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 magic/player-sheet ownership is active. J0's rollback is `git revert b632672e5ccabfb44c551e08f1c411ab2669c44a`. J1's rollback is `git revert 854d9e9cd13092bd5aaa3cf025d73eeb4600e9f8`. @@ -264,6 +270,8 @@ J3.6's rollback is `git revert 119b7c115107245546180b2f5cb3cb44c7d5476a`. J4.1's rollback is `git revert c9d25ade50c0a5c4f7db5b6cca680e01e35cc18e`. +J4.2's rollback is +`git revert 011efbeaa72509b35ea7f4a442e50a2377ae1ea4`. 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 @@ -271,7 +279,8 @@ passes. Slice I is closed in 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`. The exact G4 +`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`. The exact G4 visual rollback is `git revert ef1d263337997bb030eadb7b8e71d73dc659907a`; do not revert G3 or the portal-warmup corrections. Evidence: diff --git a/CLAUDE.md b/CLAUDE.md index e6087d1b..f2951778 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -243,7 +243,13 @@ 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 inventory transaction ownership is active. J0's rollback is +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 magic/player-sheet ownership is active. J0's rollback is `git revert b632672e5ccabfb44c551e08f1c411ab2669c44a`. J1's rollback is `git revert 854d9e9cd13092bd5aaa3cf025d73eeb4600e9f8`. @@ -262,6 +268,8 @@ J3.6's rollback is `git revert 119b7c115107245546180b2f5cb3cb44c7d5476a`. J4.1's rollback is `git revert c9d25ade50c0a5c4f7db5b6cca680e01e35cc18e`. +J4.2's rollback is +`git revert 011efbeaa72509b35ea7f4a442e50a2377ae1ea4`. 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 @@ -269,7 +277,8 @@ passes. Slice I is closed in 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`. The exact G4 +`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`. The exact G4 visual rollback is `git revert ef1d263337997bb030eadb7b8e71d73dc659907a`; do not revert G3 or the portal-warmup corrections. Evidence: diff --git a/docs/architecture/acdream-architecture.md b/docs/architecture/acdream-architecture.md index 6448e465..d48fef0c 100644 --- a/docs/architecture/acdream-architecture.md +++ b/docs/architecture/acdream-architecture.md @@ -219,7 +219,9 @@ src/ ParentAttachmentState.cs -> generation-exact parent relations Gameplay/ RuntimeCommunicationState.cs -> one chat/social owner + ordered stream - -> J3 and J4.1 complete; J4.2 inventory transaction ownership active + RuntimeInventoryState.cs -> exact object-table borrower + inventory + transaction/session-state owner + -> J3 and J4.1–J4.2 complete; J4.3 magic/player ownership active -> may reference Core, Core.Net, Content, and Plugin.Abstractions only -> must never reference App, UI, Silk.NET, OpenAL, Arch, or ImGui diff --git a/docs/plans/2026-04-11-roadmap.md b/docs/plans/2026-04-11-roadmap.md index 40a13c0e..ae9f46dd 100644 --- a/docs/plans/2026-04-11-roadmap.md +++ b/docs/plans/2026-04-11-roadmap.md @@ -1,6 +1,6 @@ # acdream — strategic roadmap -**Status:** Living document. Updated 2026-07-26. **M3 landed; M4 is active.** M3's retail casting/UI, R6 locomotion/collision/projectile/teleport/radar rebaseline, deterministic fresh-login/portal world lifecycle, and final two-client portal observer flow are user-gated. All eight slices of the behavior-preserving ownership campaign in [`docs/architecture/code-structure.md`](../architecture/code-structure.md), their automated closeout, and the user's connected visual matrix are complete. Modern Runtime J3's canonical entity/object lifetime and J4.1 communication/social ownership are closed; J4.2 inventory transaction ownership is active. Issue #225's lifestone/particle alpha comparison remains a separate rendering visual gate. +**Status:** Living document. Updated 2026-07-26. **M3 landed; M4 is active.** M3's retail casting/UI, R6 locomotion/collision/projectile/teleport/radar rebaseline, deterministic fresh-login/portal world lifecycle, and final two-client portal observer flow are user-gated. All eight slices of the behavior-preserving ownership campaign in [`docs/architecture/code-structure.md`](../architecture/code-structure.md), their automated closeout, and the user's connected visual matrix are complete. Modern Runtime J3's canonical entity/object lifetime plus J4.1 communication/social and J4.2 inventory-transaction ownership are closed; J4.3 magic/player-sheet ownership is active. Issue #225's lifestone/particle alpha comparison remains a separate rendering visual gate. **Purpose:** One source of truth for where the project is and where it's going. Every observed defect or missing feature has a named phase that owns it; when something looks wrong in-game, look here to find the phase that'll address it. Implementation details live in per-phase specs under `docs/superpowers/specs/`, not in this file. --- @@ -1715,8 +1715,13 @@ port in any phase — no separate listing here. > negotiated rooms, friends, and squelch state; every graphical and no-window > consumer borrows them. Its 152 Runtime tests, 3,765 App tests / 3 skips, > 8,494-test / 5-skip complete Release suite, and exact-binary -> seven-checkpoint lifecycle/reconnect gate pass. J4.2 inventory transaction -> ownership is active. +> seven-checkpoint lifecycle/reconnect gate pass. J4.2 is complete at +> `011efbea`: Runtime 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. Its 157 +> Runtime tests, 3,770 App tests / 3 skips, 8,515-test / 5-skip complete +> Release suite, and exact-binary seven-checkpoint lifecycle/reconnect gate +> pass. J4.3 magic/player-sheet ownership is active. > The historical exact cutover > rollback remains > `git revert ef1d263337997bb030eadb7b8e71d73dc659907a`. Slice H is complete: diff --git a/docs/plans/2026-05-12-milestones.md b/docs/plans/2026-05-12-milestones.md index a2fe2a1a..a1372032 100644 --- a/docs/plans/2026-05-12-milestones.md +++ b/docs/plans/2026-05-12-milestones.md @@ -192,7 +192,12 @@ residency is `0/0/0` at every stable checkpoint and teardown converges. Slice I event stream; all presentation and no-window consumers borrow it. Its 152 Runtime tests, 3,765 App tests / 3 skips, 8,494 full Release tests / 5 skips, and exact-binary seven-checkpoint lifecycle/reconnect route pass. - J4.2 inventory transaction ownership is active under + J4.2 is complete at `011efbea`: Runtime 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. Its + 157 Runtime tests, 3,770 App tests / 3 skips, 8,515 full Release tests / 5 + skips, and exact-binary seven-checkpoint lifecycle/reconnect route pass. + J4.3 magic/player-sheet ownership is active under [`2026-07-25-modern-runtime-slice-j.md`](2026-07-25-modern-runtime-slice-j.md). Slice-I closeout evidence is [`../research/2026-07-25-slice-i7-closeout.md`](../research/2026-07-25-slice-i7-closeout.md). diff --git a/docs/plans/2026-07-24-modern-runtime-architecture.md b/docs/plans/2026-07-24-modern-runtime-architecture.md index 814411e5..40020b83 100644 --- a/docs/plans/2026-07-24-modern-runtime-architecture.md +++ b/docs/plans/2026-07-24-modern-runtime-architecture.md @@ -11,8 +11,9 @@ lifetime and ordered inbound routing; J3.1–J3.6 moved canonical entity identit and object-table lifetime to Runtime, exact graphical projection identity to App, and one ordered canonical entity/object stream plus direct views to all hosts and closed the failure-safe owner ledger. J4.1 moved communication and -social ownership into Runtime at `c9d25ade`; J4.2 inventory transaction -ownership is the active execution point. +social ownership into Runtime at `c9d25ade`; J4.2 moved inventory transaction +ownership into Runtime at `011efbea`; J4.3 magic/player-sheet ownership is the +active execution point. **Scope:** Reconcile and sequence the existing Modern Pipeline (`MP`) and Linux/headless (`LH`) tracks using the 2026-07-24 connected performance audit. diff --git a/docs/plans/2026-07-25-modern-runtime-slice-j.md b/docs/plans/2026-07-25-modern-runtime-slice-j.md index 9db3e5ee..76badbe6 100644 --- a/docs/plans/2026-07-25-modern-runtime-slice-j.md +++ b/docs/plans/2026-07-25-modern-runtime-slice-j.md @@ -1,6 +1,6 @@ # Modern runtime Slice J — presentation-independent runtime -**Status:** J0–J3 COMPLETE; J4.1 COMPLETE; J4.2 inventory ownership active +**Status:** J0–J3 COMPLETE; J4.1–J4.2 COMPLETE; J4.3 magic/player ownership active **Parent:** `2026-07-24-modern-runtime-architecture.md`, Slice J **Authorization:** the user approved Slices F–L, including the otherwise-frozen Slice J gameplay-owner moves, on 2026-07-24 @@ -234,8 +234,12 @@ reply/retell targets, negotiated Turbine rooms, friends, and squelch state. Graphical UI, devtools, command routing, plugins/current-runtime projections, and no-window consumers borrow that one graph. Its 152 Runtime tests, 3,765 App tests / 3 skips, 8,494 complete Release tests / 5 skips, and exact-binary -seven-checkpoint lifecycle/reconnect gate pass. J4.2 inventory transaction -ownership is active. +seven-checkpoint lifecycle/reconnect gate pass. J4.2 completed at `011efbea`: +Runtime 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. Its 157 Runtime tests, 3,770 App tests / 3 skips, 8,515 complete +Release tests / 5 skips, and exact-binary seven-checkpoint +lifecycle/reconnect gate pass. J4.3 magic/player-sheet ownership is active. Detailed execution begins with a source-ownership inventory. Move one coherent lifetime group at a time in this order: diff --git a/docs/plans/2026-07-26-modern-runtime-slice-j4.md b/docs/plans/2026-07-26-modern-runtime-slice-j4.md index 70e7c9e1..2b2809ec 100644 --- a/docs/plans/2026-07-26-modern-runtime-slice-j4.md +++ b/docs/plans/2026-07-26-modern-runtime-slice-j4.md @@ -1,6 +1,6 @@ # Modern runtime Slice J4 — gameplay-state lifetime groups -**Status:** J4.1 COMPLETE; J4.2 ACTIVE +**Status:** J4.1–J4.2 COMPLETE; J4.3 ACTIVE **Parent:** `2026-07-25-modern-runtime-slice-j.md`, J4 **Production base:** `77c013998b902724d66e487589a4ea18538e1ea6` **Authorization:** the user approved Slices F–L, including Slice J gameplay @@ -22,8 +22,8 @@ ordering and its existing retail-derived algorithms. | Group | Status | Evidence | |---|---|---| | J4.1 communication/social | complete | `c9d25ade50c0a5c4f7db5b6cca680e01e35cc18e`; 152 Runtime tests, 3,765 App tests / 3 skips, 8,494 complete Release tests / 5 skips, and `logs/connected-world-gate-20260726-075109/report.json` pass | -| J4.2 inventory transactions | active | Runtime must borrow J3's exact object table and take ownership of external-container, item-mana, shortcut/component, shared busy, and one-request-at-a-time state | -| J4.3 magic/player sheet | pending | starts only after J4.2 exact-binary acceptance | +| J4.2 inventory transactions | complete | `011efbeaa72509b35ea7f4a442e50a2377ae1ea4`; 157 Runtime tests, 3,770 App tests / 3 skips, 8,515 complete Release tests / 5 skips, and `logs/connected-world-gate-20260726-082057/report.json` pass | +| J4.3 magic/player sheet | active | move the coupled `Spellbook` and `LocalPlayerState` owner graph while retaining immutable DAT catalog installation | | J4.4 character projections | pending | starts only after J4.3 acceptance | | J4.5 combined cleanup | pending | combined failure, no-window, connected, and nine-stop closeout | @@ -96,7 +96,7 @@ evidence is recorded in ### J4.2 — inventory transaction state -**Active.** +**Completed 2026-07-26 at `011efbea`.** - Move `ExternalContainerState`, `ItemManaState`, shortcuts, and desired component snapshots into one Runtime owner. @@ -110,6 +110,14 @@ Gate: optimistic move/rollback, external-container open/replace/close, use-completion, mana query, shortcut/component replacement, clear/reconnect, and zero duplicate collection. +Result: `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. App retains only +presentation/input projections. Failure-safe reset and callback delivery +prevent a failed observer or dispatch from stranding the canonical busy gate. +Exact evidence is recorded in +[`../research/2026-07-26-slice-j4-2-inventory-state.md`](../research/2026-07-26-slice-j4-2-inventory-state.md). + ### J4.3 — spell, enchantment, vital, attribute, and skill state - Move construction/lifetime of the coupled `Spellbook` and @@ -187,3 +195,9 @@ J4.1 is independently reversible with: ```text git revert c9d25ade50c0a5c4f7db5b6cca680e01e35cc18e ``` + +J4.2 is independently reversible with: + +```text +git revert 011efbeaa72509b35ea7f4a442e50a2377ae1ea4 +``` diff --git a/docs/research/2026-07-26-slice-j4-2-inventory-state.md b/docs/research/2026-07-26-slice-j4-2-inventory-state.md new file mode 100644 index 00000000..378edf32 --- /dev/null +++ b/docs/research/2026-07-26-slice-j4-2-inventory-state.md @@ -0,0 +1,101 @@ +# Modern runtime J4.2 — inventory transaction ownership + +**Status:** COMPLETE +**Production commit:** `011efbeaa72509b35ea7f4a442e50a2377ae1ea4` +**Parent plan:** `../plans/2026-07-26-modern-runtime-slice-j4.md` + +## Result + +`RuntimeInventoryState` is the single presentation-independent owner for the +live external-container state, item-mana state, shortcut assignments, desired +spell-component counts, and the retail one-inventory-request-at-a-time +transaction gate. + +It borrows J3's exact `ClientObjectTable`; it does not construct or synchronize +a second item collection. The live-session router, item interaction, +retained UI, developer tools, current-runtime/plugin boundary, and future +no-window hosts all observe those same owner instances. + +`InventoryTransactionState` now owns the request/response gate previously +split across App interaction code. It records the retail request token, +matches the corresponding response, maintains the shared busy reference, +tracks use reservations, and resets the transaction atomically. Callback +failures are isolated after canonical state commits, so one observer cannot +strand the busy cursor or prevent a later request. + +Presentation-only state remains in App: pending backpack-slot projection, +drag/drop hover and selection, cursor choice, item icons, panel layout, and +optimistic visual placement. App may borrow the Runtime transaction owner but +cannot dispose or replace it. + +## Retail basis + +The ownership move preserves the already-ported retail transaction behavior: + +- `ACCWeenieObject::RecordRequest` at `0x0058C220`; +- `ACCWeenieObject::RecordResponse` at `0x0058CAB0`; +- `ClientUISystem::UsageCallback` at `0x00565B20`; +- `2026-07-23-retail-use-busy-ownership-pseudocode.md`; +- `2026-07-13-retail-give-item-pseudocode.md`. + +ACE and Holtburger remain interpretation cross-checks as recorded in the +busy-ownership pseudocode. No request ordering, wire packet, optimistic move, +rollback, use-completion, or cursor behavior changed in J4.2. + +## Automated evidence + +- Runtime suite: 157 passed. +- App suite: 3,770 passed / 3 established skips. +- Core suite: 3,305 passed / 2 established skips. +- Complete Release solution: 8,515 passed / 5 established skips. +- Release build: pass, zero errors. A clean rebuild reports 17 established + test warnings; the J4.2 diff introduces none. +- `git diff --check`: pass. + +The focused matrix covers exact object-table identity, external-container +open/replace/close, item-mana replacement, shortcut/component replacement, +request/response matching, use reservations, dispatch failure rollback, +observer failure isolation, reset/reconnect, borrowed lifetime, idempotent +disposal, and two independent Runtime instances. + +One parallel full-suite run hit the established allocation-sensitive portal +projection test with a 1,536-byte measurement. The isolated App rerun passed, +and an immediate complete-solution rerun passed all 8,515 tests without a code +change. + +## Exact-binary connected evidence + +`logs/connected-world-gate-20260726-082057/report.json` passed on exact source +and embedded binary commit +`011efbeaa72509b35ea7f4a442e50a2377ae1ea4`: + +- six capped checkpoints through login, outdoor/dungeon/facility travel and + revisit plus one fresh-process uncapped reconnect checkpoint; +- 244.011-second capped route and 61.422-second reconnect route; +- both sessions exited gracefully with code zero; +- zero failures. + +Its only warning is the established set of 25 expected world-edge landblock +misses. + +## Divergence audit + +J4.2 changes lifetime ownership and failure containment only. It introduces no +new retail behavior and retires no registered divergence, so the divergence +register is unchanged. + +## Rollback + +```text +git revert 011efbeaa72509b35ea7f4a442e50a2377ae1ea4 +``` + +Do not revert J3's canonical entity/object ownership to mask an inventory +transaction failure. + +## Next boundary + +J4.3 moves construction and lifetime of the coupled `Spellbook` and +`LocalPlayerState` into Runtime. Immutable DAT spell tables remain supplied by +the content host; retained spellbook, active-effect, character-sheet, and +paperdoll presentation remain in App/UI.