phase(N.4) Task 11: LandblockSpawnAdapter (atlas-tier ref-count bridge)

Bridges LoadedLandblock load/unload events to IWbMeshAdapter ref counts.
Tier-aware by design: walks WorldEntity collection filtered by
ServerGuid == 0 (procedural / atlas-tier only). Server-spawned entities
are skipped — those will go through EntitySpawnAdapter (Task 17).

Per-landblock id-set snapshot ensures unload pairs 1:1 with load even
when underlying data is released. Duplicate-load idempotency for
defensive resilience to streaming-controller bugs.

Six tests: registers per unique id; dedups across entities; skips
server-spawned; unload matches load; unknown landblock no-ops;
duplicate load no-ops.

Wiring into GpuWorldState lands in Task 12.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

src/AcDream.App/Rendering/Wb/LandblockSpawnAdapter.cs

@@ -0,0 +1,94 @@
+using System.Collections.Generic;
+using AcDream.Core.World;
+
+namespace AcDream.App.Rendering.Wb;
+
+/// <summary>
+/// Bridges landblock streaming events to <see cref="IWbMeshAdapter"/>'s
+/// reference-count lifecycle. <b>Tier-aware by design</b>: only atlas-tier
+/// entities (procedural / dat-hydrated, identified by
+/// <c>ServerGuid == 0</c>) drive ref counts. Server-spawned entities
+/// (per-instance tier) are skipped — those go through
+/// <c>EntitySpawnAdapter</c> + <c>TextureCache.GetOrUploadWithPaletteOverride</c>
+/// (see Phase N.4 spec, Architecture → Two-tier rendering split).
+///
+/// <para>
+/// On load: walks the landblock's atlas-tier entities, collects unique
+/// GfxObj ids from their <c>MeshRefs</c>, calls
+/// <c>IncrementRefCount</c> per id. Snapshots the id-set per landblock so
+/// unload can match the load 1:1.
+/// </para>
+///
+/// <para>
+/// On unload: looks up the snapshot, calls <c>DecrementRefCount</c> per id,
+/// drops the snapshot. Unknown / never-loaded landblocks no-op.
+/// </para>
+///
+/// <para>
+/// Idempotency: a duplicate load for the same landblock is a no-op on
+/// ref-counting (the snapshot is already present). Defensive guard against
+/// streaming-controller bugs.
+/// </para>
+///
+/// <para>
+/// Thread safety: the underlying <see cref="IWbMeshAdapter"/> implementation
+/// uses <c>ConcurrentDictionary</c>, so the streaming worker thread may call
+/// this safely. The internal snapshot dictionary is NOT thread-safe and must
+/// be called from a single streaming thread (the same thread that fires
+/// AddLandblock / RemoveLandblock events).
+/// </para>
+/// </summary>
+public sealed class LandblockSpawnAdapter
+{
+    private readonly IWbMeshAdapter _adapter;
+
+    // Maps landblock id → unique GfxObj ids registered for that landblock.
+    // Written on load, read+cleared on unload. Single-threaded (streaming worker).
+    private readonly Dictionary<uint, HashSet<ulong>> _idsByLandblock = new();
+
+    public LandblockSpawnAdapter(IWbMeshAdapter adapter)
+    {
+        System.ArgumentNullException.ThrowIfNull(adapter);
+        _adapter = adapter;
+    }
+
+    /// <summary>
+    /// Called when a landblock finishes streaming in.
+    /// Registers a ref-count increment with WB for each unique atlas-tier
+    /// GfxObj id in the landblock. Duplicate loads for the same landblock id
+    /// are silently ignored.
+    /// </summary>
+    public void OnLandblockLoaded(LoadedLandblock landblock)
+    {
+        System.ArgumentNullException.ThrowIfNull(landblock);
+
+        // Idempotency: already-loaded landblock is a no-op.
+        if (_idsByLandblock.ContainsKey(landblock.LandblockId)) return;
+
+        var unique = new HashSet<ulong>();
+        foreach (var entity in landblock.Entities)
+        {
+            // Atlas-tier filter: server-spawned entities (ServerGuid != 0)
+            // belong to the per-instance path and are NOT registered with WB.
+            if (entity.ServerGuid != 0) continue;
+
+            foreach (var meshRef in entity.MeshRefs)
+                unique.Add((ulong)meshRef.GfxObjId);
+        }
+
+        _idsByLandblock[landblock.LandblockId] = unique;
+        foreach (var id in unique) _adapter.IncrementRefCount(id);
+    }
+
+    /// <summary>
+    /// Called when a landblock is unloaded from the streaming window.
+    /// Releases the ref-count for every GfxObj id that was registered on load.
+    /// Unknown landblock ids (never loaded, or already unloaded) are no-ops.
+    /// </summary>
+    public void OnLandblockUnloaded(uint landblockId)
+    {
+        if (!_idsByLandblock.TryGetValue(landblockId, out var unique)) return;
+        foreach (var id in unique) _adapter.DecrementRefCount(id);
+        _idsByLandblock.Remove(landblockId);
+    }
+}