refactor(runtime): own magic and player state

Move the coupled Spellbook and LocalPlayerState into one Runtime-owned character graph, route content, live-session, retained UI, reset, and shutdown through that exact owner, and delete the duplicate desired-component snapshot from inventory state. Preserve synchronous retail update and reset ordering while adding independent-instance and retryable-failure coverage.

Co-authored-by: Codex <codex@openai.com>

src/AcDream.App/Composition/ContentEffectsAudioComposition.cs

@@ -12,6 +12,7 @@ using AcDream.Core.Physics;
 using AcDream.Core.Rendering;
 using AcDream.Core.Spells;
 using AcDream.Core.Vfx;
+using AcDream.Runtime.Gameplay;
 using DatReaderWriter;
 using Silk.NET.Input;
 using Silk.NET.OpenGL;
@@ -48,7 +49,7 @@ internal sealed record ContentEffectsAudioDependencies(
     ResidencyBudgetOptions ResidencyBudgets,
     PhysicsDataCache PhysicsDataCache,
     bool DumpMotionEnabled,
-    Spellbook SpellBook,
+    RuntimeCharacterState Character,
     AnimationHookRouter HookRouter,
     EntityEffectPoseRegistry EffectPoses,
     DeferredEntityEffectAdvanceSource EntityEffectAdvance,
@@ -85,7 +86,9 @@ internal interface IContentEffectsAudioCompositionFactory
         IDatReaderWriter dats,
         Action<string> diagnostic);
     MagicCatalog LoadMagicCatalog(IDatReaderWriter dats);
-    void InstallSpellMetadata(Spellbook spellBook, MagicCatalog catalog);
+    void InstallSpellMetadata(
+        RuntimeCharacterState character,
+        MagicCatalog catalog);
     int GetSpellCount(MagicCatalog catalog);
     IAnimationLoader CreateAnimationLoader(
         IDatReaderWriter dats,
@@ -143,8 +146,10 @@ internal sealed class RetailContentEffectsAudioCompositionFactory
     public MagicCatalog LoadMagicCatalog(IDatReaderWriter dats) =>
         MagicCatalog.Load(dats);
 
-    public void InstallSpellMetadata(Spellbook spellBook, MagicCatalog catalog) =>
-        spellBook.InstallMetadata(catalog.SpellTable);
+    public void InstallSpellMetadata(
+        RuntimeCharacterState character,
+        MagicCatalog catalog) =>
+        character.InstallSpellMetadata(catalog.SpellTable);
 
     public int GetSpellCount(MagicCatalog catalog) => catalog.SpellTable.Count;
 
@@ -326,7 +331,7 @@ internal sealed class ContentEffectsAudioCompositionPhase :
             MagicCatalog magic = _factory.LoadMagicCatalog(dats);
             _publication.PublishMagicCatalog(magic);
             Fault(ContentEffectsAudioCompositionPoint.MagicCatalogPublished);
-            _factory.InstallSpellMetadata(_dependencies.SpellBook, magic);
+            _factory.InstallSpellMetadata(_dependencies.Character, magic);
             _dependencies.Log(
                 $"spells: loaded {_factory.GetSpellCount(magic)} entries from portal.dat");
             Fault(ContentEffectsAudioCompositionPoint.SpellMetadataInstalled);

src/AcDream.App/Composition/InteractionRetainedUiComposition.cs

@@ -48,9 +48,8 @@ internal sealed record InteractionRetainedUiDependencies(
     SelectionState Selection,
     RuntimeInventoryState Inventory,
     MagicCatalog MagicCatalog,
-    Spellbook Spellbook,
+    RuntimeCharacterState Character,
     RuntimeCommunicationState Communication,
-    LocalPlayerState LocalPlayer,
     StackSplitQuantityState StackSplitQuantity,
     BufferedUiRegistry? UiRegistry,
     LiveCombatModeCommandSlot CombatModeCommands,
@@ -350,7 +349,7 @@ internal sealed class RetailInteractionRetainedUiCompositionFactory
         try
         {
             VitalsVM vitals = d.ExistingVitals
-                ?? new VitalsVM(d.Combat, d.LocalPlayer);
+                ?? new VitalsVM(d.Combat, d.Character.LocalPlayer);
             UiHost host = lease.AcquireHost(
                 () => new UiHost(
                     d.Gl,
@@ -372,7 +371,7 @@ internal sealed class RetailInteractionRetainedUiCompositionFactory
 
             var characterSheet = new CharacterSheetProvider(
                 d.Inventory.Objects,
-                d.LocalPlayer,
+                d.Character.LocalPlayer,
                 playerGuid: () => d.PlayerIdentity.ServerGuid,
                 activeToonName: () => d.Settings.ActiveToonKey,
                 fallbackSheet: Studio.SampleData.SampleCharacter,
@@ -389,7 +388,7 @@ internal sealed class RetailInteractionRetainedUiCompositionFactory
 
             MagicRuntime magic = MagicRuntime.Create(
                 d.MagicCatalog,
-                d.Spellbook,
+                d.Character.Spellbook,
                 d.Inventory.Objects,
                 selectedObject: () => d.Selection.SelectedObjectId,
                 localPlayerId: () => d.PlayerIdentity.ServerGuid,
@@ -421,7 +420,7 @@ internal sealed class RetailInteractionRetainedUiCompositionFactory
 
                 uint skillId = SkillId(school);
                 if (skillId != 0u)
-                    return d.LocalPlayer.GetSkill(skillId)?.CurrentLevel ?? 0u;
+                    return d.Character.LocalPlayer.GetSkill(skillId)?.CurrentLevel ?? 0u;
 
                 uint highest = 0u;
                 foreach (MagicSchool candidate in new[]
@@ -435,7 +434,8 @@ internal sealed class RetailInteractionRetainedUiCompositionFactory
                 {
                     highest = Math.Max(
                         highest,
-                        d.LocalPlayer.GetSkill(SkillId(candidate))?.CurrentLevel ?? 0u);
+                        d.Character.LocalPlayer.GetSkill(
+                            SkillId(candidate))?.CurrentLevel ?? 0u);
                 }
                 return highest;
             }
@@ -527,7 +527,7 @@ internal sealed class RetailInteractionRetainedUiCompositionFactory
                     () => d.Settings.Gameplay,
                     d.Settings.SetCombatGameplay),
                 Magic: new MagicRuntimeBindings(
-                    d.Spellbook,
+                    d.Character.Spellbook,
                     magic.Casting,
                     d.Inventory.Objects,
                     () => d.PlayerIdentity.ServerGuid,
@@ -569,10 +569,10 @@ internal sealed class RetailInteractionRetainedUiCompositionFactory
                     late.Selection.ResolveVividTargetInfo,
                     late.SelectionCamera.UiSnapshot),
                 Indicators: new IndicatorRuntimeBindings(
-                    d.Spellbook,
+                    d.Character.Spellbook,
                     d.Inventory.Objects,
                     () => d.PlayerIdentity.ServerGuid,
-                    () => d.LocalPlayer.GetAttribute(
+                    () => d.Character.LocalPlayer.GetAttribute(
                         LocalPlayerState.AttributeKind.Strength)
                             is { } strength ? (int?)strength.Current : null,
                     () => late.Session.LinkStatus,
@@ -614,7 +614,7 @@ internal sealed class RetailInteractionRetainedUiCompositionFactory
                     () => d.PlayerIdentity.ServerGuid,
                     iconComposer.GetIcon,
                     iconComposer.GetDragIcon,
-                    () => d.LocalPlayer.GetAttribute(
+                    () => d.Character.LocalPlayer.GetAttribute(
                         LocalPlayerState.AttributeKind.Strength)
                             is { } strength ? (int?)strength.Current : null,
                     guid => late.Session.CurrentSession?.SendUse(guid),

src/AcDream.App/Composition/SessionPlayerComposition.cs

@@ -85,8 +85,7 @@ internal sealed record SessionPlayerDependencies(
     CombatState Combat,
     CombatFeedbackSlot CombatFeedback,
     RuntimeCommunicationState Communication,
-    LocalPlayerState LocalPlayer,
-    Spellbook Spellbook,
+    RuntimeCharacterState Character,
     TransferableResourceSlot<PortalTunnelPresentation> PortalTunnelFallback,
     Action<string> Log);
 
@@ -802,8 +801,7 @@ internal sealed class SessionPlayerCompositionPhase
                 d.CharacterOptions),
             new LiveSessionDomainRuntime(
                 d.EntityObjects,
-                d.LocalPlayer,
-                d.Spellbook,
+                d.Character,
                 d.Combat,
                 d.Inventory,
                 d.Communication),

src/AcDream.App/Net/LiveSessionRuntimeFactory.cs

@@ -42,8 +42,7 @@ internal sealed record LiveSessionPlayerRuntime(
 
 internal sealed record LiveSessionDomainRuntime(
     RuntimeEntityObjectLifetime EntityObjects,
-    LocalPlayerState LocalPlayer,
-    Spellbook Spellbook,
+    RuntimeCharacterState Character,
     CombatState Combat,
     RuntimeInventoryState Inventory,
     RuntimeCommunicationState Communication);
@@ -170,12 +169,12 @@ internal sealed class LiveSessionRuntimeFactory
         InventoryTransactions = _domain.Inventory.ResetTransactions,
         SelectionPresentation = _world.SelectionScene.Reset,
         ObjectTable = _domain.EntityObjects.ClearObjects,
-        Spellbook = _domain.Spellbook.Clear,
+        Spellbook = _domain.Character.ResetSpellbook,
         MagicRuntime = () => _ui.Magic?.Reset(),
         CombatAttack = _interaction.CombatAttack.ResetSession,
         CombatState = _domain.Combat.Clear,
         ItemMana = _domain.Inventory.ResetItemMana,
-        LocalPlayer = _domain.LocalPlayer.Clear,
+        LocalPlayer = _domain.Character.ResetLocalPlayer,
         Friends = _domain.Communication.ResetFriends,
         Squelch = _domain.Communication.ResetSquelch,
         TurbineChat = _domain.Communication.ResetNegotiatedChannels,
@@ -256,7 +255,6 @@ internal sealed class LiveSessionRuntimeFactory
 
     private LiveInventorySessionBindings CreateInventoryBindings() => new(
         _domain.Inventory.Objects,
-        _domain.LocalPlayer,
         PlayerGuid: () => _player.Identity.ServerGuid,
         OnShortcuts: _domain.Inventory.Shortcuts.Replace,
         OnUseDone: error =>
@@ -265,7 +263,6 @@ internal sealed class LiveSessionRuntimeFactory
             _domain.Inventory.Transactions.CompleteUse(error);
         },
         _domain.Inventory.ItemMana,
-        OnDesiredComponents: _domain.Inventory.DesiredComponents.Replace,
         ExternalContainers: _domain.Inventory.ExternalContainers,
         OnAppraisal: appraisal =>
         {
@@ -281,7 +278,7 @@ internal sealed class LiveSessionRuntimeFactory
         var skillCreditResolver = new LiveSkillCreditResolver(skillTable);
         return new LiveCharacterSessionBindings(
             _domain.Combat,
-            _domain.Spellbook,
+            _domain.Character,
             ResolveSkillFormulaBonus: skillCreditResolver.Resolve,
             OnSkillsUpdated: (runSkill, jumpSkill) =>
             {
@@ -337,7 +334,7 @@ internal sealed class LiveSessionRuntimeFactory
                 ?? "unknown",
             CurrentPosition: () => _player.Controller.Controller?.CellPosition,
             LastOutsideCorpsePosition: () =>
-                _domain.LocalPlayer.GetPosition(0x0Eu),
+                _domain.Character.LocalPlayer.GetPosition(0x0Eu),
             ShowConfirmation: (message, completed) =>
                 _ui.RetailUi?.ShowConfirmation(message, completed),
             Suicide: session.SendSuicide,
@@ -372,7 +369,6 @@ internal sealed class LiveSessionRuntimeFactory
             ClearDesiredComponents: () =>
             {
                 session.SendClearDesiredComponents();
-                _domain.Inventory.DesiredComponents.Clear();
             },
             HasOpenVendor: () => false,
             FillComponentBuyList: (_, _) => { }),

src/AcDream.App/Rendering/GameWindow.cs

@@ -337,14 +337,14 @@ public sealed class GameWindow :
     public readonly AcDream.Core.Combat.CombatState Combat = new();
     private readonly RuntimeEntityObjectLifetime _runtimeEntityObjects = new();
     private readonly RuntimeInventoryState _runtimeInventory;
+    private readonly RuntimeCharacterState _runtimeCharacter;
     public AcDream.Core.Items.ItemManaState ItemMana =>
         _runtimeInventory.ItemMana;
-    public IReadOnlyList<(uint Id, uint Amount)> DesiredComponents =>
-        _runtimeInventory.DesiredComponents.Items;
     // Retail resolves learned IDs through portal.dat's CSpellTable. MagicCatalog
     // installs that immutable table once DatCollection opens in OnLoad.
     public AcDream.Core.Spells.SpellTable SpellTable => SpellBook.Metadata;
-    public readonly AcDream.Core.Spells.Spellbook SpellBook = null!;
+    public AcDream.Core.Spells.Spellbook SpellBook =>
+        _runtimeCharacter.Spellbook;
     /// <summary>Persisted hotbar shortcuts from the last PlayerDescription (D.5.1 toolbar source).</summary>
     public IReadOnlyList<AcDream.Core.Items.ShortcutEntry> Shortcuts =>
         _runtimeInventory.Shortcuts.Items;
@@ -352,7 +352,8 @@ public sealed class GameWindow :
     // PlayerDescription so the Vitals HUD can render those bars.
     // Issue #6 — wired to SpellBook so GetMaxApprox folds enchantment
     // buffs into the max formula via Spellbook.GetVitalMod.
-    public readonly AcDream.Core.Player.LocalPlayerState LocalPlayer = null!;
+    public AcDream.Core.Player.LocalPlayerState LocalPlayer =>
+        _runtimeCharacter.LocalPlayer;
 
     // Phase D.2a — ImGui devtools UI overlay. Null unless ACDREAM_DEVTOOLS=1.
     // See docs/plans/2026-04-24-ui-framework.md for the staged UI strategy.
@@ -562,6 +563,7 @@ public sealed class GameWindow :
     {
         _options = options ?? throw new System.ArgumentNullException(nameof(options));
         _runtimeInventory = new RuntimeInventoryState(_runtimeEntityObjects);
+        _runtimeCharacter = new RuntimeCharacterState();
         var alphaScratchBudgets =
             AcDream.App.Rendering.Residency.AlphaScratchBudgetProfile.Create(
                 _options.ResidencyBudgets.AlphaScratchBytes);
@@ -591,8 +593,6 @@ public sealed class GameWindow :
         _uiRegistry = uiRegistry;
         _animatedEntities = new LiveEntityAnimationRuntimeView<LiveEntityAnimationState>(
             _liveEntityRuntimeSlot);
-        SpellBook = new AcDream.Core.Spells.Spellbook();
-        LocalPlayer = new AcDream.Core.Player.LocalPlayerState(SpellBook);
         // #184 Slice 2a: the extracted per-remote DR tick. Its stateful
         // setup/motion dependency crosses the fail-fast construction bridge;
         // the server-velocity animation cycle is stateless shared policy.
@@ -1149,7 +1149,7 @@ public sealed class GameWindow :
                     _options.ResidencyBudgets,
                     _physicsDataCache,
                     _animationDiagnostics.DumpMotionEnabled,
-                    SpellBook,
+                    _runtimeCharacter,
                     _hookRouter,
                     _effectPoses,
                     _entityEffectAdvance,
@@ -1261,9 +1261,8 @@ public sealed class GameWindow :
                     _selection,
                     _runtimeInventory,
                     contentEffectsAudio.MagicCatalog,
-                    SpellBook,
+                    _runtimeCharacter,
                     _runtimeCommunication,
-                    LocalPlayer,
                     _stackSplitQuantity,
                     _uiRegistry,
                     _liveCombatModeCommands,
@@ -1405,8 +1404,7 @@ public sealed class GameWindow :
                     Combat,
                     _combatFeedback,
                     _runtimeCommunication,
-                    LocalPlayer,
-                    SpellBook,
+                    _runtimeCharacter,
                     _portalTunnelFallback,
                     Console.WriteLine),
                 this).Compose(
@@ -1582,6 +1580,7 @@ public sealed class GameWindow :
             _liveEntities,
             _runtimeEntityObjects,
             _runtimeInventory,
+            _runtimeCharacter,
             _runtimeCommunication,
             _renderSceneShadow,
             _livePresentationBindings,

src/AcDream.App/Rendering/GameWindowLifetime.cs

@@ -85,6 +85,7 @@ internal sealed record LiveShutdownRoots(
     LiveEntityRuntime? LiveEntities,
     RuntimeEntityObjectLifetime EntityObjects,
     RuntimeInventoryState Inventory,
+    RuntimeCharacterState Character,
     RuntimeCommunicationState Communication,
     RenderSceneShadowRuntime? RenderSceneShadow,
     LivePresentationRuntimeBindings? PresentationBindings,
@@ -391,6 +392,9 @@ internal static class GameWindowShutdownManifest
             ]),
             new ResourceShutdownStage("runtime entity/object stream",
             [
+                Hard(
+                    "runtime character state",
+                    live.Character.Dispose),
                 Hard(
                     "runtime inventory state",
                     live.Inventory.Dispose),