fix(rendering): bound portal resource lifetime

Separate logical ownership, render publication, and GPU retirement across live entities, landblocks, particles, textures, mesh arenas, portal/UI teardown, and per-frame scratch storage. Add bounded DAT/texture caches, upload budgets, three-frame fence retirement, exact-incarnation appearance reconciliation, frame pacing, and extensive lifetime conformance coverage.\n\nThe seven-destination connected route now cuts peak working/private memory roughly in half, returns Caul to 125-153 FPS locally, and produces no WER or AMD reset.\n\nCo-authored-by: OpenAI Codex <codex@openai.com>

src/AcDream.Content/DecodedTextureCache.cs

@@ -0,0 +1,145 @@
+using System;
+using System.Collections.Generic;
+using System.Collections.Concurrent;
+using System.Threading;
+
+namespace AcDream.Content;
+
+/// <summary>
+/// Thread-safe, byte-bounded residency for canonical decoded texture pixels.
+/// Mesh extraction may run on several workers, so cached arrays are immutable
+/// after admission and callers clone them before applying surface-local alpha.
+/// </summary>
+internal sealed class DecodedTextureCache {
+    private sealed record Entry(DecodedTextureKey Key, byte[] Pixels);
+
+    private readonly object _gate = new();
+    private readonly Dictionary<DecodedTextureKey, LinkedListNode<Entry>> _entries = new();
+    private readonly LinkedList<Entry> _lru = new();
+    private readonly ConcurrentDictionary<DecodedTextureKey, Lazy<byte[]>> _inflight = new();
+    private readonly long _maximumBytes;
+    private readonly int _maximumEntries;
+    private long _residentBytes;
+
+    public DecodedTextureCache(long maximumBytes, int maximumEntries) {
+        ArgumentOutOfRangeException.ThrowIfNegative(maximumBytes);
+        ArgumentOutOfRangeException.ThrowIfNegative(maximumEntries);
+        _maximumBytes = maximumBytes;
+        _maximumEntries = maximumEntries;
+    }
+
+    public int Count {
+        get {
+            lock (_gate) {
+                return _entries.Count;
+            }
+        }
+    }
+
+    public long ResidentBytes {
+        get {
+            lock (_gate) {
+                return _residentBytes;
+            }
+        }
+    }
+
+    public bool TryGet(DecodedTextureKey key, out byte[] pixels) {
+        lock (_gate) {
+            if (!_entries.TryGetValue(key, out var node)) {
+                pixels = null!;
+                return false;
+            }
+
+            Touch(node);
+            pixels = node.Value.Pixels;
+            return true;
+        }
+    }
+
+    /// <summary>
+    /// Returns the canonical pixels for <paramref name="key"/>. If another
+    /// worker admitted the same key first, its array wins. <paramref name="isCached"/>
+    /// reports whether the returned array is retained and therefore immutable.
+    /// </summary>
+    public byte[] RetainOrUse(DecodedTextureKey key, byte[] pixels, out bool isCached) {
+        ArgumentNullException.ThrowIfNull(pixels);
+
+        lock (_gate) {
+            if (_entries.TryGetValue(key, out var existing)) {
+                Touch(existing);
+                isCached = true;
+                return existing.Value.Pixels;
+            }
+
+            if (_maximumEntries == 0 || pixels.LongLength > _maximumBytes) {
+                isCached = false;
+                return pixels;
+            }
+
+            while (_lru.First is { } oldest
+                   && (_entries.Count >= _maximumEntries
+                       || _residentBytes + pixels.LongLength > _maximumBytes)) {
+                Remove(oldest);
+            }
+
+            var node = _lru.AddLast(new Entry(key, pixels));
+            _entries.Add(key, node);
+            _residentBytes += pixels.LongLength;
+            isCached = true;
+            return pixels;
+        }
+    }
+
+    /// <summary>
+    /// Decode a missing key once across concurrent mesh workers. The expensive
+    /// factory runs outside the LRU lock and unrelated keys proceed in parallel.
+    /// A failed or oversized decode is not stranded as permanent in-flight state.
+    /// </summary>
+    public byte[] GetOrCreate(
+        DecodedTextureKey key,
+        Func<byte[]> factory,
+        out bool isCached) {
+        ArgumentNullException.ThrowIfNull(factory);
+        if (TryGet(key, out byte[] cached)) {
+            isCached = true;
+            return cached;
+        }
+
+        var candidate = new Lazy<byte[]>(
+            factory,
+            LazyThreadSafetyMode.ExecutionAndPublication);
+        Lazy<byte[]> shared = _inflight.GetOrAdd(key, candidate);
+        try {
+            byte[] decoded = shared.Value;
+            return RetainOrUse(key, decoded, out isCached);
+        }
+        finally {
+            _inflight.TryRemove(
+                new KeyValuePair<DecodedTextureKey, Lazy<byte[]>>(key, shared));
+        }
+    }
+
+    private void Touch(LinkedListNode<Entry> node) {
+        if (node != _lru.Last) {
+            _lru.Remove(node);
+            _lru.AddLast(node);
+        }
+    }
+
+    private void Remove(LinkedListNode<Entry> node) {
+        _lru.Remove(node);
+        _entries.Remove(node.Value.Key);
+        _residentBytes -= node.Value.Pixels.LongLength;
+    }
+}
+
+/// <summary>
+/// Every input that can change decoded RGBA belongs in the cache identity.
+/// INDEX16/P8 clip-map conversion and A8 additive conversion are surface
+/// dependent even when they reference the same RenderSurface DID.
+/// </summary>
+internal readonly record struct DecodedTextureKey(
+    uint RenderSurfaceId,
+    bool IsClipMap,
+    bool IsAdditive);