From c8b58fa44f053e5abd952cb7a5ac7daba782383f Mon Sep 17 00:00:00 2001
From: Meta Vens <rwvens@hotmail.com>
Date: Tue, 16 Jun 2026 08:18:16 +0100
Subject: [PATCH] Persist docked entity graph in typed checkpoints

---
 .voidbot/state/aetheria.cc                   | Bin 148602 -> 148330 bytes
 Aetheria.State.Verify/Program.cs             |   3 +
 Aetheria.State/README.md                     |   8 +-
 Assets/Scripts/Gameplay/ActionGameManager.cs | 122 ++++++++++++++++---
 docs/aetheria-perfect-machine-map.md         |  10 +-
 5 files changed, 122 insertions(+), 21 deletions(-)

diff --git a/.voidbot/state/aetheria.cc b/.voidbot/state/aetheria.cc
index 61e56102ad60305715c20e612b257c90b5f26f3d..065ffb53a0262943df078148ed56a49c88a99027 100644
GIT binary patch
delta 1674
zcmZuyO=u)V6lN+xH@K*mK){1fJuHFg+02BUKS7!NY!F#oqVW(Gq0(J5U8cLLt*V}6
zK$u;2QTHf0GzfyAlA~U9VPz2y-o3_)c=aZD5(HmWb<Yf8FEc%_s^9y*?|tvhzn`uA
z^~uWj-;k@FezV!%*lcv0t;5f2t7pHGhYPW;i^-+ad91bRVpo=5CY!<i_2p03murvK
zm&xPxevdK}GsS5T$?%v(0TYIsNib40ivu&sFciitJkBH+MhC5pRy){e2hH}`-$&Pq
zy#@)UU+m`s7A}F1Cy+6vxi)~=VVF>3m|zhke9XX?09T?8T!cv;aWMjq05kC<QcTo=
ziU_tP0ung`#k7(5;m@zz%l0M3rkI^ep<|wD7%G{9gAK=Qq8s0a3FYbUwSNYoy|hPD
zc8dx+VhV06`5_Apg5RDIyj}(mrC{$0n(0^?M<>@<`KITw>m=H<3W1jJ>LPCNFsNcB
zF(l1J@k@iOO%)5JinODpV|&GlqY+XmNx((KPC;ihWI&N=u22V4p4K5mEof*oK3R<%
z!@85rDnYg8Baz|@c)?1SphRG(8Zo0Ausyw`B+x8NIMUj-$vmmIQ8V}Mj+b|fP6qR|
zU?gOS8zFg`CRQ>Z#h`MOBxQj-u}$_@7CPh`R6HJ#=TL;Qjb62&;&||uqsLASoWx9&
z(u^@(b;Fhft}B~RgFr#5BW`HYI7feJZ1BayEf&);mnz5<A5&wElO=S5Un%7x*0wJ)
z%@StV>sSR7&LBBQA~l+!{3u}MF`AoLDjbVCdI8%pW@-XQWu0p_qhU(Wq|yPjp~as~
zvO2x^@n&vv?DTv*5OP%!PNX`9G{-SPe_a|CR2eJ!DZvUeV>Dn#Iv9#!T_vL&&0_u9
za4p1!22vywH-KH7Kql~f=!y;*_AbPZn;6wgQ4}}TfIk*JjF*c4TI68*@ly;Rp{i~O
ztDRu6ahudCw(q;^95oP8>7sqMIHHy9{FFK;FL<TG*tq}o+0KJE4=&z&AJ@~6<G?ER
zQO@lKDEEmoJr=#3!Wj(oBt4ReZH^Omwns8*;<MjAcw=kp7R@lHpUL@(@+K(PmlMwt
zduom1#V57ZqIZL+R_iv7ADWd8(FzqnYu@>4DQ$)!Dn?8fgWXzOyz>%SExLDV&lm7R
z?XG`X>k#woxldSp)gfz3-Tp@LQ-{3b9{%W%-7Dv%H;Z<cyyn7px&-DczumSgzxc9C
rp3H+i|34s?o+<A2NIE;{HQhn+LZ3|M!A%!@^j)9)yfTlrZyf#)2+3M3

delta 2023
zcmah~J!~9B6xOay6iWyN6eA=+jAR6I;=Nm&`23?p!buz#U_c?Fh!E0vckXuN-JQ+M
z?A<NR6+r}$C?XeIQt&4_f{-kb0yH#qly*Z;M?pga-^}jqof8n<-Rzt9zW2TFd-MDI
zbANp>_w{G)qn*tQ%bWgsYh%s7dDodg_}Tq%>TK1XiJ9Tl*@itkJ^P${;nMBJ**lA~
z&f(&$`~Bjji<IezNlv{$q?)HW^WGIH^BDf<!s|(zMV>A)7J8B?EhO_+{FRR9cf94!
z!5@1smRDP@xBJDF`ZlSfNGb;Soy9a@iu72@B-Jb=K`te7+akmk;rKq_IwHV9Y^CyU
z+kI+eOB0%gNCRvs3$!Ad${y2ggOvuFD2=3qCL-;P3x`eC*5^S?d2;N0vlVDA(jA(x
zU7FG!ljM5U%eL)u$256OisXjr^Lm~l7afI)us)MTm9HQwrJ0I^CV3hngF&lU3{>b!
z;*LRTs3VzVT|Qhwl0@`RG;cpQO`8h<lcFuENJAjabtEJo>0*h*V!$MD&;axpa1#_d
zk|OU_tbq=tWp2A9dvVS($x}@-s-q<Wo_HTLfjmI2$Ad&n6D>d{rf;y)EQ`%3GA8Zt
zQ6Di%fjH7d4rPM=YYtKj6zK}taBoOZXpQjnWLY~^fI{zkJO#&=N7|oAqvm_m`ckvh
zls|T6u0%Wz+o1^d5oZZ344Pb8cw9jUJdU9`-88s4j%(&-$>dN<t--h;0s1z~up~pf
z6Xt@5kKzzQT_Q>lQ`g+1V565Nc49iBAXpfh@dNQT9MuzwmMQ7xI+u)8BDTa$CKTkl
zMJ}_5_PLNAW@W~Mt1wGJ&<u@H^s%ZXo(3YxVpjh2vO7OIb{@G_C2r(05OSYDmw60k
zhM+90l~U7GA!vHnq5?Z6Q?i&EbEt@CsBFeE23DKP>O!g(xhh7}3{RQbmNMd@U2Uv!
zLaAVP$d#^U9txYHOZORpn2d=b0Wr~y<rSi5HqOGv$h$Bn(w?>sfal9!?>T47;fi~C
zRQ#`%AKF1DY}lCW0n`=VDanuFwyPbaTDL!i(GPasyEr-$Z()UYIeM4uR?eaQX7YAt
z5>+I7B8G>WP3T$clOSdkX6-GF=@<*Rs$WZWtYu>v1Xrbxo`*11o3ex7-f45bOEcUJ
zgfynI6L@&n77xHO^9BI3rL2U<s;GB{@jg~lC2HdUBewF)eP_P>^G)aN(*MDkKYw)Y
z4HyGMs)j#SeAPEM+BJ@`A}hDHov3{MY4^#6g%g*sXDj-8Ih7&Fvk;CbKU#I~oc*>A
zR3O&qjK*<MKJ%J$uJl*k#}CfDa^57I_x~-f^;Ko?a7%wTd9`l%Ynv~vmcJZ2&z|bo
zKjl%!-G1U8wz%dA^TYtJl`%y5!kW7<gXr?rHJ8-y=|;=<m(6=xe!S-1pE~T+5AUh+
g*1DTaJ}g(!f3LfvsYClrAAYjo{x~-|UGZ=J1Gkjm2mk;8

diff --git a/Aetheria.State.Verify/Program.cs b/Aetheria.State.Verify/Program.cs
index d3b2482d8..f3c6d3553 100644
--- a/Aetheria.State.Verify/Program.cs
+++ b/Aetheria.State.Verify/Program.cs
@@ -846,6 +846,9 @@ static void RequireMainMenuContinueRunState(string root)
         "entity.RecordKey",
         "ReplaceZoneEntitiesFromTypedSnapshots",
         "Zone.Agents.Clear()",
+        "FlattenEntityGraph(Zone)",
+        "RestoreChildAndDockingRelationships",
+        "RestoreCurrentEntityBinding",
         "RestoreEntityContactsFromTypedSnapshot",
         "entity.Target.Value = target",
         "string.Equals(entitySnapshot.RecordKey, currentEntityKey",
diff --git a/Aetheria.State/README.md b/Aetheria.State/README.md
index f48c7e8b2..a539445e9 100644
--- a/Aetheria.State/README.md
+++ b/Aetheria.State/README.md
@@ -177,11 +177,13 @@ orbit/body rows into `AetheriaZoneState`, so `ZoneConstructionBlueprint` is a
 one-shot construction input rather than the retained surface carrying celestial graph facts. Entity checkpoints
 persist hull simulation grids into `AetheriaEntitySnapshot`, so
 `EntityConstructionBlueprint` is no longer the only surface carrying those live
-values. Continue restore lowers the current zone entity graph from exact typed
-entity snapshot records, including position, velocity, target/contact state,
+values. Run checkpoints project the flattened live entity graph, including
+docked children, into exact typed entity snapshot records. Continue restore
+lowers the current zone entity graph from those records, including position,
+velocity, target/contact state, child/docking relationships,
 shutdown/heatsink state, thermal exposure, active consumable timers, and typed
 stat grids for temperature, thermal mass, armor, max armor, and hull conductivity. Broader runtime object graphs
-such as child/docked activation and behavior-private simulation state remain legacy until dedicated typed runtime documents exist. Live behavior
+such as behavior-private simulation state remain legacy until dedicated typed runtime documents exist. Live behavior
 instances expose typed behavior kind and group through `Behavior.Kind` and
 `Behavior.Group`; behavior construction now reads typed payload fields through
 `RuntimeBehaviorDefinition` instead of projecting through config DTOs. Stat
diff --git a/Assets/Scripts/Gameplay/ActionGameManager.cs b/Assets/Scripts/Gameplay/ActionGameManager.cs
index 295359e7c..b25f29b2a 100644
--- a/Assets/Scripts/Gameplay/ActionGameManager.cs
+++ b/Assets/Scripts/Gameplay/ActionGameManager.cs
@@ -619,6 +619,7 @@ public class ActionGameManager : MonoBehaviour
 
     private AetheriaRuntimeRunCheckpointCommit ProjectRunCheckpoint()
     {
+        var entityGraph = FlattenEntityGraph(Zone);
         return new AetheriaRuntimeRunCheckpointCommit
         {
             RunId = IsTutorial ? "tutorial" : "local",
@@ -626,7 +627,7 @@ public class ActionGameManager : MonoBehaviour
             EntranceZoneIndex = ZoneIndex(CurrentGalaxy?.Entrance),
             ExitZoneIndex = ZoneIndex(CurrentGalaxy?.Exit),
             CurrentZoneIndex = ZoneIndex(Zone?.GalaxyZone),
-            CurrentZoneEntityIndex = Zone?.Entities?.IndexOf(CurrentEntity) ?? -1,
+            CurrentZoneEntityIndex = entityGraph.IndexOf(CurrentEntity),
             GenerationSeed = CurrentGalaxy?.GenerationSeed ?? 0,
             DiscoveredZoneIndices = CurrentGalaxy?.DiscoveredZones
                 .Select(ZoneIndex)
@@ -696,6 +697,7 @@ public class ActionGameManager : MonoBehaviour
     private AetheriaRuntimeZoneSnapshotCommit ProjectZoneSnapshot(Zone zone)
     {
         var galaxyZone = zone.GalaxyZone;
+        var entityGraph = FlattenEntityGraph(zone);
         return new AetheriaRuntimeZoneSnapshotCommit
         {
             ZoneIndex = ZoneIndex(galaxyZone),
@@ -715,8 +717,8 @@ public class ActionGameManager : MonoBehaviour
             OwnerFactionIndex = FactionIndex(galaxyZone?.Owner),
             Orbits = ProjectZoneOrbits(zone),
             Bodies = ProjectZoneBodies(zone),
-            Entities = zone.Entities
-                .Select((entity, index) => ProjectEntitySnapshot(zone, entity, index))
+            Entities = entityGraph
+                .Select((entity, index) => ProjectEntitySnapshot(entityGraph, entity, index))
                 .ToArray(),
             DroppedPickups = ProjectDroppedPickups(zone)
         };
@@ -913,7 +915,29 @@ public class ActionGameManager : MonoBehaviour
         };
     }
 
-    private AetheriaRuntimeEntitySnapshotCommit ProjectEntitySnapshot(Zone zone, Entity entity, int entityIndex)
+    private static List<Entity> FlattenEntityGraph(Zone zone)
+    {
+        var entities = new List<Entity>();
+        if (zone == null)
+            return entities;
+
+        var visited = new HashSet<Entity>();
+        foreach (var entity in zone.Entities)
+            AddEntityAndChildren(entity);
+        return entities;
+
+        void AddEntityAndChildren(Entity entity)
+        {
+            if (entity == null || !visited.Add(entity))
+                return;
+
+            entities.Add(entity);
+            foreach (var child in entity.Children)
+                AddEntityAndChildren(child);
+        }
+    }
+
+    private AetheriaRuntimeEntitySnapshotCommit ProjectEntitySnapshot(IReadOnlyList<Entity> entityGraph, Entity entity, int entityIndex)
     {
         return new AetheriaRuntimeEntitySnapshotCommit
         {
@@ -927,7 +951,7 @@ public class ActionGameManager : MonoBehaviour
             DirectionY = entity.Direction.y,
             VelocityX = entity.Velocity.x,
             VelocityY = entity.Velocity.y,
-            TargetEntityIndex = entity.Target?.Value == null ? -1 : zone.Entities.IndexOf(entity.Target.Value),
+            TargetEntityIndex = entity.Target?.Value == null ? -1 : entityGraph.IndexOf(entity.Target.Value),
             IsActive = entity.Active,
             HeatsinksEnabled = entity.HeatsinksEnabled,
             OverrideShutdown = entity.OverrideShutdown,
@@ -946,9 +970,9 @@ public class ActionGameManager : MonoBehaviour
                 .ToArray() ?? Array.Empty<int>(),
             Visibility = entity.Visibility,
             VisibilitySourceCount = entity.VisibilitySources.Count,
-            Contacts = ProjectEntityContacts(zone, entity),
+            Contacts = ProjectEntityContacts(entityGraph, entity),
             ChildEntityIndices = entity.Children?
-                .Select(child => zone.Entities.IndexOf(child))
+                .Select(child => entityGraph.IndexOf(child))
                 .Where(index => index >= 0)
                 .ToArray() ?? Array.Empty<int>(),
             WeaponGroups = entity.WeaponGroups?
@@ -957,17 +981,17 @@ public class ActionGameManager : MonoBehaviour
             StatGrids = ProjectEntityStatGrids(entity),
             ActiveConsumables = ProjectActiveConsumables(entity),
             BehaviorProgress = ProjectBehaviorProgress(entity),
-            WeaponStates = ProjectWeaponStates(zone, entity),
+            WeaponStates = ProjectWeaponStates(entityGraph, entity),
             BehaviorStates = ProjectBehaviorStates(entity)
         };
     }
 
-    private static AetheriaRuntimeEntityContactCommit[] ProjectEntityContacts(Zone zone, Entity entity)
+    private static AetheriaRuntimeEntityContactCommit[] ProjectEntityContacts(IReadOnlyList<Entity> entityGraph, Entity entity)
     {
         return entity.EntityInfoGathered
             .Select(contact =>
             {
-                var targetIndex = zone.Entities.IndexOf(contact.Key);
+                var targetIndex = entityGraph.IndexOf(contact.Key);
                 entity.EntityHostility.TryGetValue(contact.Key, out var hostile);
                 return new AetheriaRuntimeEntityContactCommit
                 {
@@ -1179,22 +1203,22 @@ public class ActionGameManager : MonoBehaviour
         }
     }
 
-    private static AetheriaRuntimeWeaponStateCommit[] ProjectWeaponStates(Zone zone, Entity entity)
+    private static AetheriaRuntimeWeaponStateCommit[] ProjectWeaponStates(IReadOnlyList<Entity> entityGraph, Entity entity)
     {
         var states = new List<AetheriaRuntimeWeaponStateCommit>();
 
         for (var ownerIndex = 0; ownerIndex < entity.Equipment.Count; ownerIndex++)
-            states.AddRange(ProjectWeaponStates(zone, "equipment", ownerIndex, entity.Equipment[ownerIndex].Behaviors));
+            states.AddRange(ProjectWeaponStates(entityGraph, "equipment", ownerIndex, entity.Equipment[ownerIndex].Behaviors));
 
         var activeConsumables = entity.ActiveConsumables;
         for (var ownerIndex = 0; ownerIndex < activeConsumables.Count; ownerIndex++)
-            states.AddRange(ProjectWeaponStates(zone, "active_consumable", ownerIndex, activeConsumables[ownerIndex].Behaviors));
+            states.AddRange(ProjectWeaponStates(entityGraph, "active_consumable", ownerIndex, activeConsumables[ownerIndex].Behaviors));
 
         return states.ToArray();
     }
 
     private static IEnumerable<AetheriaRuntimeWeaponStateCommit> ProjectWeaponStates(
-        Zone zone,
+        IReadOnlyList<Entity> entityGraph,
         string ownerKind,
         int ownerIndex,
         IReadOnlyList<Behavior> behaviors)
@@ -1243,7 +1267,7 @@ public class ActionGameManager : MonoBehaviour
             if (weapon is LockWeapon lockWeapon)
             {
                 state.LockProgress = lockWeapon.LockProgress;
-                state.LockTargetEntityIndex = lockWeapon.LockTarget == null ? -1 : zone.Entities.IndexOf(lockWeapon.LockTarget);
+                state.LockTargetEntityIndex = lockWeapon.LockTarget == null ? -1 : entityGraph.IndexOf(lockWeapon.LockTarget);
             }
 
             yield return state;
@@ -2577,6 +2601,8 @@ public class ActionGameManager : MonoBehaviour
         foreach (var entity in restoredEntities.Values)
             entity.Activate();
 
+        RestoreChildAndDockingRelationships(entitySnapshots, restoredEntities);
+
         foreach (var entitySnapshot in entitySnapshots)
         {
             if (!restoredEntities.TryGetValue(entitySnapshot.RecordKey, out var entity))
@@ -2592,7 +2618,71 @@ public class ActionGameManager : MonoBehaviour
         }
 
         if (restoredEntities.TryGetValue(currentEntityKey, out var currentEntity))
-            BindToEntity(currentEntity);
+            RestoreCurrentEntityBinding(currentEntity);
+    }
+
+    private void RestoreChildAndDockingRelationships(
+        IReadOnlyList<AetheriaRuntimeEntitySnapshot> entitySnapshots,
+        IReadOnlyDictionary<string, Entity> restoredEntities)
+    {
+        foreach (var entitySnapshot in entitySnapshots)
+        {
+            if (!restoredEntities.TryGetValue(entitySnapshot.RecordKey, out var parent))
+                continue;
+
+            foreach (var childKey in entitySnapshot.ChildEntityKeys)
+            {
+                if (!restoredEntities.TryGetValue(childKey, out var child) ||
+                    child == parent ||
+                    child.Parent == parent)
+                {
+                    continue;
+                }
+
+                child.RemoveParent();
+                child.SetParent(parent);
+            }
+
+            for (var bayIndex = 0; bayIndex < entitySnapshot.DockingBayAssignments.Count; bayIndex++)
+            {
+                var childIndex = entitySnapshot.DockingBayAssignments[bayIndex];
+                if (childIndex < 0 ||
+                    childIndex >= entitySnapshot.ChildEntityKeys.Count ||
+                    bayIndex >= parent.DockingBays.Count ||
+                    !restoredEntities.TryGetValue(entitySnapshot.ChildEntityKeys[childIndex], out var child) ||
+                    !(child is Ship ship))
+                {
+                    continue;
+                }
+
+                var dockingBay = parent.DockingBays[bayIndex];
+                dockingBay.DockedShip = ship;
+                if (ship.Parent != parent)
+                {
+                    ship.RemoveParent();
+                    ship.SetParent(parent);
+                }
+                if (Zone.Entities.Contains(ship))
+                    Zone.Entities.Remove(ship);
+                ship.Deactivate();
+            }
+        }
+    }
+
+    private void RestoreCurrentEntityBinding(Entity currentEntity)
+    {
+        if (currentEntity.Parent != null)
+        {
+            var dockingBay = currentEntity.Parent.DockingBays.FirstOrDefault(bay => bay.DockedShip == currentEntity);
+            if (dockingBay != null && currentEntity.Parent is OrbitalEntity)
+            {
+                CurrentEntity = currentEntity;
+                DoDock(currentEntity.Parent, dockingBay);
+                return;
+            }
+        }
+
+        BindToEntity(currentEntity);
     }
 
     private void RestoreEntityContactsFromTypedSnapshot(
diff --git a/docs/aetheria-perfect-machine-map.md b/docs/aetheria-perfect-machine-map.md
index 6002d0dcd..6773381d5 100644
--- a/docs/aetheria-perfect-machine-map.md
+++ b/docs/aetheria-perfect-machine-map.md
@@ -979,10 +979,16 @@ First Aetheria surfaces to publish:
      heatstroke/hypothermia exposure, active consumable item/timer rows,
      typed stat grids for temperature, thermal mass, armor, max armor, and
      hull-conductivity axes, then reconnects target/contact rows among restored
-     entities and binds the saved current entity as the player ship.
+     entities, restores child/docking relationships from typed child keys and
+     docking-bay assignments, and binds the saved current entity as the player
+     ship or docked current ship.
+   - Done: project run checkpoint entity snapshots from the flattened live
+     entity graph, not only `Zone.Entities`, so docked child ships can receive
+     typed entity records and stable child/docking references instead of
+     disappearing from the `.zone` replacement graph.
    - Remaining: add typed documents/mappers for runtime object graphs,
      complete full Continue/run entity graph reconstruction from typed state
-     for child/docked entity activation, restored active-consumable behavior runtime internals,
+     for restored active-consumable behavior runtime internals,
      behavior-private state not covered by progress, weapon, sensor, radiator,
      reactor, or capacitor rows, typed behavior factory construction, and any
      catalog fields not covered by the stable scalar/fingerprint/payload pass.