fix(streaming): #138 — re-hydrate server objects from the retained spawn table on reload

Doors/NPCs/portals vanished after a portal OUT of the 0x0007 dungeon back
to Holtburg. Root cause confirmed via ACE + holtburger cross-reference:
the dungeon collapse drops a landblock's render entities for FPS, and ACE
will NOT re-broadcast objects whose guid is still in its per-player
KnownObjects set (never cleared on a normal teleport — ACE relies on the
client retaining its object table and culling stale objects itself). So
nothing restored them on the way back.

Retail-faithful fix: a real client keeps its weenie_object_table and
re-renders the world from it (holtburger keeps the table across a
teleport; only suspends physics bodies). acdream's _lastSpawnByGuid (the
parsed CreateObject records — position + Setup + appearance) IS that
table and survives the collapse (the collapse path never calls
RemoveLiveEntityByServerGuid, the only thing that prunes it). On landblock
(re)load, replay OnLiveEntitySpawnedLocked for retained spawns whose
render entity is absent — independent of any ACE re-send.

- LandblockEntityRehydrator: pure selection (landblock match; skip
  already-present, the player, and mesh-less spawns), unit-tested (7).
- StreamingController: onLandblockLoaded callback after AddLandblock
  (Loaded = dungeon-exit expand) and AddEntitiesToExistingLandblock
  (Promoted = Far->Near).
- GameWindow.RehydrateServerEntitiesForLandblock: present-gate keys on
  GpuWorldState (NOT _entitiesByServerGuid, which holds collapse
  orphans), replay under _datLock; the replay's own
  RemoveLiveEntityByServerGuid de-dup scrubs the orphan state.

Corrects the handoff: ClientObjectTable is inventory-only (no world
position/Setup) and cannot rebuild a render entity; _lastSpawnByGuid is
the world-object table. Register row AP-48 (no retail 25s visibility
cull). dotnet build + 1518 Core tests green.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

src/AcDream.App/Rendering/GameWindow.cs

@@ -2295,7 +2295,11 @@ public sealed class GameWindow : IDisposable
                 _cellVisibility.RemoveLandblock((id >> 16) & 0xFFFFu);
                 _buildingRegistries.Remove(id & 0xFFFF0000u);  // Phase A8 (key normalization fix 2026-05-28)
                 _envCellRenderer?.RemoveLandblock(id);  // Phase A8
-            });
+            },
+            // #138: restore retained server objects when a landblock reloads
+            // (dungeon-exit expand or Far→Near promote). ACE won't re-send the
+            // objects it thinks we still know, so we re-project them ourselves.
+            onLandblockLoaded: RehydrateServerEntitiesForLandblock);
         // A.5 T22.5: apply max-completions from resolved quality.
         _streamingController.MaxCompletionsPerFrame = _resolvedQuality.MaxCompletionsPerFrame;
 
@@ -2681,6 +2685,77 @@ public sealed class GameWindow : IDisposable
         }
     }
 
+    /// <summary>
+    /// #138: re-hydrate retained server objects (doors, NPCs, chests, portals)
+    /// into a landblock that just (re)loaded. Fired by
+    /// <see cref="AcDream.App.Streaming.StreamingController"/> after
+    /// <c>AddLandblock</c> / <c>AddEntitiesToExistingLandblock</c>.
+    ///
+    /// <para>
+    /// The dungeon collapse (and Near→Far demote) drops a landblock's render
+    /// entities for FPS but keeps the parsed spawns in <see cref="_lastSpawnByGuid"/>
+    /// (our <c>weenie_object_table</c> for world objects). ACE never
+    /// re-broadcasts objects it believes we still know — its per-player
+    /// <c>KnownObjects</c> set is not cleared on a normal teleport (verified
+    /// against <c>references/ACE</c> <c>ObjectMaint</c>; a real client keeps its
+    /// table and re-renders from it, per <c>references/holtburger</c>). So on
+    /// reload the render side would stay empty. We re-project the objects from
+    /// our own retained table instead — independent of any server re-send.
+    /// </para>
+    ///
+    /// <para>
+    /// Idempotent and cheap when nothing is missing: the selection skips guids
+    /// already present in <see cref="_worldState"/> (initial login, or objects
+    /// ACE did re-send), the player (owned by the persistent-entity rescue
+    /// path), and spawns with no world mesh. The replay's own
+    /// <see cref="RemoveLiveEntityByServerGuid"/> de-dup scrubs the state the
+    /// collapse orphaned — the entity lingers in <see cref="_entitiesByServerGuid"/>
+    /// after <c>RemoveLandblock</c> even though its render entity is gone.
+    /// </para>
+    /// </summary>
+    private void RehydrateServerEntitiesForLandblock(uint loadedLandblockId)
+    {
+        if (_lastSpawnByGuid.Count == 0) return;
+
+        // Server guids that already have a live render entity. The gate keys on
+        // GpuWorldState (the render projection), NOT _entitiesByServerGuid, which
+        // still holds collapse-orphaned entries whose render entity is gone.
+        var present = new HashSet<uint>();
+        foreach (var e in _worldState.Entities)
+            if (e.ServerGuid != 0) present.Add(e.ServerGuid);
+
+        // Snapshot the retained spawns — the replay mutates _lastSpawnByGuid
+        // (remove then re-add), so we must not iterate it live.
+        var retained = new List<AcDream.App.Streaming.LandblockEntityRehydrator.RetainedSpawn>(
+            _lastSpawnByGuid.Count);
+        foreach (var kv in _lastSpawnByGuid)
+        {
+            var sp = kv.Value;
+            bool hasWorldMesh = sp.Position is not null && sp.SetupTableId is not null;
+            uint spawnLb = sp.Position is { } p ? p.LandblockId : 0u;
+            retained.Add(new AcDream.App.Streaming.LandblockEntityRehydrator.RetainedSpawn(
+                kv.Key, spawnLb, hasWorldMesh));
+        }
+
+        var guids = AcDream.App.Streaming.LandblockEntityRehydrator.SelectGuidsToRehydrate(
+            loadedLandblockId, retained, present, _playerServerGuid);
+        if (guids.Count == 0) return;
+
+        // Replay through the normal live-spawn build under the dat lock (it reads
+        // Setup/GfxObj/Surface dats). Each replay rebuilds the render entity into
+        // the now-loaded landblock via AppendLiveEntity's hot path.
+        lock (_datLock)
+        {
+            foreach (var guid in guids)
+                if (_lastSpawnByGuid.TryGetValue(guid, out var spawn))
+                    OnLiveEntitySpawnedLocked(spawn);
+        }
+
+        if (_options.DumpLiveSpawns)
+            Console.WriteLine(
+                $"live: re-hydrated {guids.Count} server object(s) into landblock 0x{loadedLandblockId:X8}");
+    }
+
     /// <summary>
     /// Door detection by server-sent name. Doors fail the generic
     /// multi-frame-idle gate at line 2692 (no idle cycle), so we register

src/AcDream.App/Streaming/LandblockEntityRehydrator.cs

@@ -0,0 +1,86 @@
+using System.Collections.Generic;
+
+namespace AcDream.App.Streaming;
+
+/// <summary>
+/// Decides which retained server-object spawns to re-hydrate (rebuild render
+/// entities for) when a landblock (re)loads. The pure selection half of the
+/// #138 fix; <c>GameWindow</c> owns the replay half (it alone can rebuild a
+/// mesh from a <c>CreateObject</c>).
+///
+/// <para>
+/// <b>Why this exists (retail/ACE model).</b> A real AC client keeps its
+/// <c>weenie_object_table</c> across a teleport and re-projects its rendered
+/// world from that table; the server does NOT re-broadcast objects it believes
+/// the client already knows (ACE's per-player <c>KnownObjects</c> set is never
+/// cleared on a normal teleport — ACE relies on the client retaining the
+/// table, cross-checked against <c>references/holtburger</c> +
+/// <c>references/ACE/Source/ACE.Server/Physics/Common/ObjectMaint.cs</c>).
+/// </para>
+///
+/// <para>
+/// acdream's dungeon-collapse (and Near→Far demote) drops a landblock's
+/// RENDER entities for FPS but retains the parsed spawns
+/// (<c>GameWindow._lastSpawnByGuid</c> — the table is only pruned by an
+/// explicit server <c>DeleteObject</c> or a spawn de-dup). On reload, ACE will
+/// not re-send the objects it still thinks we have, so the render side stays
+/// empty — the #138 symptom. This selects the retained spawns whose render
+/// entity is currently absent so <c>GameWindow</c> can replay them, making
+/// re-delivery independent of the server.
+/// </para>
+/// </summary>
+public static class LandblockEntityRehydrator
+{
+    /// <summary>
+    /// A retained spawn reduced to just the fields the selection needs.
+    /// <paramref name="HasWorldMesh"/> is true only when the spawn carries both
+    /// a world position AND a Setup id — i.e. it would actually build a visible
+    /// render entity (inventory items and setup-less spawns produce none and
+    /// are skipped, matching <c>OnLiveEntitySpawnedLocked</c>'s own guard).
+    /// </summary>
+    public readonly record struct RetainedSpawn(uint Guid, uint SpawnLandblockId, bool HasWorldMesh);
+
+    /// <summary>
+    /// Canonical landblock id (low 16 bits forced to <c>0xFFFF</c>) — the same
+    /// keying <see cref="GpuWorldState.AppendLiveEntity"/> uses, so a
+    /// cell-resolved spawn id (<c>0xAAAA00CC</c>) and a streamed landblock id
+    /// (<c>0xAAAAFFFF</c>) compare equal when they name the same landblock.
+    /// </summary>
+    public static uint Canonicalize(uint landblockId) => (landblockId & 0xFFFF0000u) | 0xFFFFu;
+
+    /// <summary>
+    /// Select the guids whose retained spawn should be replayed for the
+    /// just-loaded <paramref name="loadedLandblockId"/>.
+    /// </summary>
+    /// <param name="loadedLandblockId">The landblock that just (re)loaded.</param>
+    /// <param name="retainedSpawns">Snapshot of the retained world-object spawns.</param>
+    /// <param name="presentServerGuids">
+    /// Server guids that already have a live render entity in
+    /// <see cref="GpuWorldState"/>. A guid here was either never dropped or was
+    /// already re-delivered by the server, so replaying it would be redundant.
+    /// </param>
+    /// <param name="playerServerGuid">
+    /// The local player's guid — never re-hydrated here; it is owned by the
+    /// persistent-entity rescue path (<see cref="GpuWorldState.MarkPersistent"/>
+    /// + <c>DrainRescued</c>), which preserves the player's live pose/position
+    /// rather than resetting it to the spawn snapshot.
+    /// </param>
+    public static List<uint> SelectGuidsToRehydrate(
+        uint loadedLandblockId,
+        IReadOnlyCollection<RetainedSpawn> retainedSpawns,
+        IReadOnlySet<uint> presentServerGuids,
+        uint playerServerGuid)
+    {
+        uint loadedCanonical = Canonicalize(loadedLandblockId);
+        var result = new List<uint>();
+        foreach (var s in retainedSpawns)
+        {
+            if (!s.HasWorldMesh) continue;                              // no visible entity to rebuild
+            if (s.Guid == playerServerGuid) continue;                  // player: persistent-rescue path owns it
+            if (Canonicalize(s.SpawnLandblockId) != loadedCanonical) continue; // different landblock
+            if (presentServerGuids.Contains(s.Guid)) continue;         // already rendered
+            result.Add(s.Guid);
+        }
+        return result;
+    }
+}

src/AcDream.App/Streaming/StreamingController.cs

@@ -23,6 +23,17 @@ public sealed class StreamingController
     private readonly Action<LoadedLandblock, LandblockMeshData> _applyTerrain;
     private readonly Action<uint>? _removeTerrain;
     private readonly Action? _clearPendingLoads;
+
+    /// <summary>
+    /// #138: fired after a landblock's entity layer (re)loads — both the full
+    /// <see cref="LandblockStreamResult.Loaded"/> path (initial / dungeon-exit
+    /// expand) and the <see cref="LandblockStreamResult.Promoted"/> path
+    /// (Far→Near). <c>GameWindow</c> wires it to re-hydrate server objects whose
+    /// render entities were dropped by the collapse/demote but whose parsed
+    /// spawns it still retains. Receives the canonical landblock id. Null in
+    /// tests that don't exercise re-hydration.
+    /// </summary>
+    private readonly Action<uint>? _onLandblockLoaded;
     private readonly GpuWorldState _state;
     private StreamingRegion? _region;
 
@@ -87,7 +98,8 @@ public sealed class StreamingController
         int nearRadius,
         int farRadius,
         Action<uint>? removeTerrain = null,
-        Action? clearPendingLoads = null)
+        Action? clearPendingLoads = null,
+        Action<uint>? onLandblockLoaded = null)
     {
         _enqueueLoad = enqueueLoad;
         _enqueueUnload = enqueueUnload;
@@ -95,6 +107,7 @@ public sealed class StreamingController
         _applyTerrain = applyTerrain;
         _removeTerrain = removeTerrain;
         _clearPendingLoads = clearPendingLoads;
+        _onLandblockLoaded = onLandblockLoaded;
         _state = state;
         NearRadius = nearRadius;
         FarRadius  = farRadius;
@@ -297,10 +310,15 @@ public sealed class StreamingController
                 case LandblockStreamResult.Loaded loaded:
                     _applyTerrain(loaded.Landblock, loaded.MeshData);
                     _state.AddLandblock(loaded.Landblock);
+                    // #138: after the landblock is in _loaded (so AppendLiveEntity
+                    // hot-paths), restore any retained server objects ACE won't
+                    // re-send. Fired AFTER AddLandblock, never before.
+                    _onLandblockLoaded?.Invoke(loaded.Landblock.LandblockId);
                     break;
                 case LandblockStreamResult.Promoted promoted:
                     _applyTerrain(promoted.Landblock, promoted.MeshData);
                     _state.AddEntitiesToExistingLandblock(promoted.LandblockId, promoted.Entities);
+                    _onLandblockLoaded?.Invoke(promoted.LandblockId);
                     break;
                 case LandblockStreamResult.Unloaded unloaded:
                     _state.RemoveLandblock(unloaded.LandblockId);