acdream/docs/plans/2026-07-26-modern-runtime-slice-j4.md

# Modern runtime Slice J4 — gameplay-state lifetime groups

**Status:** COMPLETE
**Parent:** `2026-07-25-modern-runtime-slice-j.md`, J4
**Production base:** `77c013998b902724d66e487589a4ea18538e1ea6`
**Authorization:** the user approved Slices F–L, including Slice J gameplay
owner moves, on 2026-07-24

## Objective

Move the remaining presentation-independent player/gameplay state into
`AcDream.Runtime` without creating a second model, changing retail behavior,
or making the graphical host authoritative.

Runtime must construct and own each mutable Core state object. App, retained
UI, devtools, plugins, and the live-session router borrow those exact
instances. Every moved group retains current synchronous packet/command
ordering and its existing retail-derived algorithms.

## Execution ledger

| 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 | 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 | complete | `d02a12ceac54d035797b4c58f2fc2f0ccad9a4d6`; 162 Runtime tests, 3,772 App tests / 3 skips, 8,522 complete Release tests / 5 skips, and `logs/connected-world-gate-20260726-083921/report.json` pass |
| J4.4 character projections | complete | `dcb61efb5af6c12bd619369e28cf11bacc37bc73`; 169 Runtime tests, 3,777 App tests / 3 skips, 8,534 complete Release tests / 5 skips, and `logs/connected-world-gate-20260726-091340/report.json` pass |
| J4.5 combined cleanup | complete | `89e6b207f81946b40c38c8dc6597817ad99fc6e0`; 175 Runtime tests, 3,780 App tests / 3 skips, 8,544 complete Release tests / 5 skips, exact-binary lifecycle/reconnect and nine-stop gates |

## Current ownership inventory

The App `GameWindow` currently constructs or roots these
presentation-independent owners:

| Group | Current canonical objects | Current App roots |
|---|---|---|
| Communication/social | `ChatLog`, `TurbineChatState`, `FriendsState`, `SquelchState`; reply/retell targets currently live in `ChatVM` | public `GameWindow` fields plus `ChatVM` subscription |
| Inventory/session transactions | J3's Runtime-owned `ClientObjectTable`; `ExternalContainerState`, `ItemManaState`, shortcut snapshot, desired-component snapshot | `GameWindow`, App snapshot wrappers, and `LiveSessionRuntimeFactory` |
| Magic/effects/player sheet | coupled `Spellbook` + `LocalPlayerState`; learned spells, favorites, filters, desired components, active enchantments, cooldown bucket, attributes, skills, vitals, properties, positions | `GameWindow` fields; App `MagicRuntime` and retained controllers borrow them |
| Character settings/skill motion projection | character options and run/jump controller inputs | App input/composition state |
| Presentation-only state | formatted/layout chat rows, retained panels, text/icons, selected rows, scroll offsets, paperdoll/viewport, effects rendering, cooldown overlays | App/UI; these do **not** move |

`RuntimeEntityObjectLifetime` already owns the inventory object collection and
ordered object deltas. J4 must reuse that owner. It may not introduce a second
inventory list or replay object-table events into another collection.

Selection, approach/use input, movement, combat intent, target state,
projectiles, and outbound motion/cast cadence remain J5. World reveal,
environment, and portal presentation remain J6.

## Fixed invariants

1. One mutable owner instance per state class; adapters and panels borrow.
2. Runtime has no App, UI, Silk, OpenAL, Arch, ImGui, or GL dependency.
3. No asynchronous App seam, extra frame, polling copy, or reconstructed
   ViewModel collection.
4. Existing `WorldSession`/`GameEventWiring` registration order and
   generation acceptance gates remain unchanged.
5. Session reset preserves the current semantic order. Visible chat history
   survives character teardown while reply targets, local identity, negotiated
   rooms, friends, and squelch state reset.
6. Immutable DAT-derived catalog data may be installed once. Mutable learned
   spells, enchantments, filters, favorites, desired components, vitals,
   skills, and cooldown state are session-owned.
7. Every group has a Runtime-only construction/reset/disposal test that loads
   no presentation/backend assembly.
8. The replaced App ownership path is deleted in the same sub-slice.

## Execution

### J4.1 — communication and social state

**Completed 2026-07-26 at `c9d25ade`.**

- Add a Runtime owner for `ChatLog`, `TurbineChatState`, `FriendsState`,
  `SquelchState`, and reply/retell command targets.
- Move reply/retell target tracking out of `ChatVM`; the VM borrows the same
  presentation-independent target state.
- Make `LiveSessionRuntimeFactory`, command routing, current-runtime views,
  retained UI, devtools, and plugins borrow the Runtime owner.
- Replace `GameWindow` object fields with read-only aliases to that owner.
- Preserve transcript lifetime and exact per-session reset semantics.

Gate: incoming/outgoing tell tracking, room negotiation/cookie wrap, friend and
squelch updates, command routing, clear, reset/reconnect, graphical/direct
event traces, disposal, and Runtime dependency closure.

Result: `RuntimeCommunicationState` constructs and owns the exact `ChatLog`,
reply/retell targets, Turbine rooms, friends, and squelch database. Session
routing, both UI stacks, plugins/current-runtime views, and command routing
borrow those instances. The canonical chat stream is synchronous,
failure-isolated, and preserves one monotonic sequence under re-entrant
callbacks without a frame/background queue. Exact-binary lifecycle/reconnect
evidence is recorded in
[`../research/2026-07-26-slice-j4-1-communication-state.md`](../research/2026-07-26-slice-j4-1-communication-state.md).

### J4.2 — inventory transaction state

**Completed 2026-07-26 at `011efbea`.**

- Move `ExternalContainerState`, `ItemManaState`, shortcuts, and desired
  component snapshots into one Runtime owner.
- Keep the J3 object table as the only item collection and borrow it directly.
- Split presentation/input-only portions from item-use reservations only where
  the existing class mixes them; do not move retained drag/drop or panel state.
- Route inbound object/use/mana/shortcut/component updates and bot/plugin views
  through the same owner.

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

**Completed 2026-07-26 at `d02a12ce`.**

- Move construction/lifetime of the coupled `Spellbook` and
  `LocalPlayerState` into Runtime.
- Preserve one-time immutable `SpellTable` installation from App content.
- Keep learned spells, favorites, filters, desired components,
  enchantments/cooldowns, vitals, attributes, skills, properties, and positions
  on those exact owners.
- Retained magic/effects/character panels and App `MagicCatalog` borrow; no
  DAT/UI type enters Runtime.

Gate: complete PlayerDescription, incremental updates, spell/enchantment
add/remove, favorite/filter/component changes, cooldowns, vital modifiers,
clear/reconnect, ViewModel revisions, and graphical/direct trace parity.

Result: `RuntimeCharacterState` constructs and owns the exact coupled
`Spellbook` and `LocalPlayerState`. Content installs immutable DAT metadata
through that owner; routing, retained UI, reset, and shutdown borrow it. The
interim desired-component mirror was deleted, leaving the spellbook as the
only mutable component-count owner. Exact evidence is recorded in
[`../research/2026-07-26-slice-j4-3-character-state.md`](../research/2026-07-26-slice-j4-3-character-state.md).

### J4.4 — character settings and player-state projections

**Completed 2026-07-26 at `dcb61efb`.**

- Move remaining presentation-independent character options and skill-derived
  state needed by commands/bots.
- Keep controller/body/camera/input application in App/J5.
- Expose borrowed immutable views and synchronous typed commands for all J4
  groups.

Gate: character replacement, settings isolation, two Runtime instances in one
process, no static mutable session state, and no backend load.

Result: the Runtime character graph owns both option bitfields and the
server-authoritative run/jump projection; the two former App owners are
deleted. Exact borrowed inventory/character/social views and synchronous
generation-gated state commands are shared by graphical UI and future
no-window hosts. Normalized checkpoints now cover the J4 state. Exact evidence
is recorded in
[`../research/2026-07-26-slice-j4-4-character-projections.md`](../research/2026-07-26-slice-j4-4-character-projections.md).

### J4.5 — combined cleanup and closeout

**Completed 2026-07-26 at `89e6b207`.**

- Delete temporary App owner fields, reset branches, reconstructed runtime
  views/events, and compatibility adapters replaced by J4.
- Prove graphical UI and no-window hosts observe the same owner instances,
  revisions, command effects, and ordered deltas.
- Failure-inject construction, subscription, callback, reset, and disposal for
  every group; require complete owner-ledger convergence.

Run:

1. focused Core and Runtime state tests;
2. UI ViewModel/controller tests;
3. App composition/session/reset/runtime-adapter tests;
4. Runtime dependency/source/assembly-load guards;
5. full Runtime and App suites;
6. Release build and complete Release suite;
7. exact-binary lifecycle/reconnect gate;
8. canonical nine-stop route;
9. documentation, divergence, dependency, and source-ownership audit.

Result: the Runtime inventory graph now owns the one retail 18-slot shortcut
manager, retained toolbar/spell controllers apply command effects through the
canonical Runtime owner, and `ItemInteractionController` can no longer create a
second inventory transaction/busy owner. Exact retail local/send ordering is
pinned for shortcuts, favorites, filters, and desired components. Graphical
and direct no-window command effects match, while a combined failure-safe
ledger proves every J4 owner and subscription converges after reset or terminal
disposal. Exact evidence is recorded in
[`../research/2026-07-26-slice-j4-5-gameplay-state-closeout.md`](../research/2026-07-26-slice-j4-5-gameplay-state-closeout.md).

## Acceptance

J4 is complete only when:

- Runtime constructs and owns every listed presentation-independent object;
- App/UI/plugin/bot consumers borrow exact instances;
- no App mirror, reconstructed collection, or command target remains;
- reset, reconnect, direct disposal, and two-instance isolation pass;
- graphical and Runtime-only normalized traces match;
- Runtime's assembly closure remains backend-free;
- full Release and both exact-binary connected routes pass;
- architecture, roadmap, milestones, AGENTS/CLAUDE, durable memory, evidence,
  and exact rollback are synchronized.

## Rollback

Record each J4 production commit before its connected gate. Revert J4 groups in
reverse order only. J3.6 remains independently reversible with:

```text
git revert 119b7c115107245546180b2f5cb3cb44c7d5476a
```

Do not revert J3 to mask a J4 owner/reset failure.

J4.1 is independently reversible with:

```text
git revert c9d25ade50c0a5c4f7db5b6cca680e01e35cc18e
```

J4.2 is independently reversible with:

```text
git revert 011efbeaa72509b35ea7f4a442e50a2377ae1ea4
```

J4.3 is independently reversible with:

```text
git revert d02a12ceac54d035797b4c58f2fc2f0ccad9a4d6
```

J4.4 is independently reversible with:

```text
git revert dcb61efb5af6c12bd619369e28cf11bacc37bc73
```

J4.5 is independently reversible with:

```text
git revert 89e6b207f81946b40c38c8dc6597817ad99fc6e0
```