phase(N.5b) Task 2: TerrainSlotAllocator + tests

Pure-CPU slot allocator for the terrain modern dispatcher's global
VBO/EBO. FIFO free-list + monotonic counter, mirroring WB's
TerrainRenderManager pattern. Caller (TerrainModernRenderer) handles
GPU buffer growth when Allocate sets needsGrow=true.

8 unit tests cover: fresh-allocator returns slot 0, sequential
allocs, free+alloc reuse, FIFO ordering, needsGrow signaling on
capacity overflow, GrowTo, LoadedCount tracking, and double-free
detection.

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

src/AcDream.Core/Terrain/TerrainSlotAllocator.cs

@@ -0,0 +1,76 @@
+using System;
+using System.Collections.Generic;
+
+namespace AcDream.Core.Terrain;
+
+/// <summary>
+/// Pure-CPU slot allocator for the terrain modern dispatcher's global VBO/EBO.
+/// One slot = one landblock's worth of mesh data (384 verts + 384 indices).
+/// Uses a FIFO free-list for slot recycling and a monotonic counter for
+/// first-time growth, mirroring WorldBuilder's TerrainRenderManager pattern.
+/// All bookkeeping is CPU-side; the GPU buffer growth itself is performed
+/// by TerrainModernRenderer when <see cref="Allocate"/> sets needsGrow=true.
+/// </summary>
+public sealed class TerrainSlotAllocator
+{
+    private readonly Queue<int> _freeSlots = new();
+    private readonly HashSet<int> _liveSlots = new();
+    private int _nextFreeSlot;
+    private int _capacity;
+
+    public TerrainSlotAllocator(int initialCapacity = 64)
+    {
+        if (initialCapacity <= 0)
+            throw new ArgumentOutOfRangeException(nameof(initialCapacity), "must be > 0");
+        _capacity = initialCapacity;
+    }
+
+    /// <summary>Current capacity in slots. Growable via <see cref="GrowTo"/>.</summary>
+    public int Capacity => _capacity;
+
+    /// <summary>Slots currently in use (allocated minus freed).</summary>
+    public int LoadedCount => _liveSlots.Count;
+
+    /// <summary>
+    /// Allocate a slot index. Reuses a freed slot via FIFO if available,
+    /// otherwise hands out the next monotonic index. Sets
+    /// <paramref name="needsGrow"/> to true when the returned slot index is
+    /// at or beyond current capacity — caller must <see cref="GrowTo"/>
+    /// before using the slot.
+    /// </summary>
+    public int Allocate(out bool needsGrow)
+    {
+        int slot;
+        if (_freeSlots.TryDequeue(out var freed))
+        {
+            slot = freed;
+        }
+        else
+        {
+            slot = _nextFreeSlot++;
+        }
+        _liveSlots.Add(slot);
+        needsGrow = slot >= _capacity;
+        return slot;
+    }
+
+    /// <summary>
+    /// Return a slot to the free list. Throws if the slot wasn't currently
+    /// allocated (catches double-free bugs).
+    /// </summary>
+    public void Free(int slot)
+    {
+        if (!_liveSlots.Remove(slot))
+            throw new InvalidOperationException(
+                $"Slot {slot} was not allocated (double-free or unknown slot).");
+        _freeSlots.Enqueue(slot);
+    }
+
+    /// <summary>Update capacity counter after the caller has grown the GPU buffers.</summary>
+    public void GrowTo(int newCapacity)
+    {
+        if (newCapacity < _capacity)
+            throw new ArgumentException("Capacity can only grow", nameof(newCapacity));
+        _capacity = newCapacity;
+    }
+}