perf(diag): per-frame history export + checkpoint LOH/cache counters + soak capped mode (2026-07-24 audit review)

An adversarial performance review found our own instruments cannot
measure the project's own performance gates:

- FrameProfiler aggregated CPU/GPU/alloc/stage samples into ~5-second
  windows and reset the ring buffers after each report, so route-wide
  p50/p95/p99 distributions across a whole soak could not be
  reconstructed after the fact. ACDREAM_FRAME_HISTORY=<path> now opts
  into a separate per-frame history (one record per frame, ~72
  bytes/record, accumulated in memory with zero frame-thread I/O) that
  a shutdown-only Dispose() writes as CSV. The aggregated [frame-prof]
  report format and its existing metrics are unchanged.

- The canonical checkpoint JSON tracked cache residency (entry/byte
  counts) but never LOH size/fragmentation, process-wide allocated
  bytes, or cache hit/miss/eviction traffic — a committed audit JSON
  showed 65% LOH fragmentation that no tracked instrument recorded,
  and "does a revisit portal hit or miss the caches" was unanswerable
  from an artifact alone. WorldLifecycleResourceSnapshot now carries
  loh_size_bytes/loh_fragmentation_bytes (GCMemoryInfo.GenerationInfo
  index 3), process_total_allocated_bytes (GC.GetTotalAllocatedBytes),
  and Interlocked hit/miss/eviction counters for the CPU mesh cache,
  decoded-texture cache, and the four bounded DAT-object caches
  (portal/cell/highRes/language, aggregated).

- run-connected-r6-soak.ps1 unconditionally forced
  ACDREAM_UNCAPPED_RENDER=1 with no capped mode, while its sibling
  lifecycle-gate script correctly gated it behind a switch. Added
  -Uncapped (default capped, matching the sibling script's pattern),
  fixed the stationary dwell (12s -> 26s, past the 25s
  LiveEntityLivenessController deadline the adjacent comment already
  cited), and now write an env-disclosure.json into the automation
  artifact directory before every launch listing every ACDREAM_* var
  the script sets plus -Uncapped, since the prior audit could only see
  ACDREAM_DUMP_MOVE_TRUTH and nothing else was ever recorded anywhere.

Cache counters are wired via the existing composition path
(ObjectMeshManager already owns the CPU mesh cache and the mesh
extractor directly; content.Dats is threaded into
WorldLifecycleResourceSnapshotSource the same way every other
composition consumer receives it). The DAT-object cache lives behind
IDatReaderWriter, a third-party interface from the DatReaderWriter
package that cannot be extended; RuntimeDatCollection (the one
production implementation) exposes the aggregate stats directly and a
pattern match reads them, degrading to zero for any test double —
no new static registry was introduced (GpuMemoryTracker remains the
one precedented process-wide static).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
(cherry picked from commit 1da2c33c875b41fa383dd79694ee2765f0e21896)

tests/AcDream.App.Tests/Diagnostics/ConnectedR6SoakContractTests.cs

@@ -116,6 +116,73 @@ public sealed class ConnectedR6SoakContractTests
             "$allocLimit = $pair.First.AllocP50Kb * 1.5 + 16.0"));
     }
 
+    [Fact]
+    public void UncappedRenderDefaultsToCappedAndIsGatedByAParameter()
+    {
+        // 2026-07-24 measurement-tooling review: the soak unconditionally
+        // forced ACDREAM_UNCAPPED_RENDER=1 with no capped mode, while the
+        // sibling lifecycle gate script exposes both. Pin the fix so it
+        // cannot silently regress back to an unconditional '1'.
+        string source = File.ReadAllText(Path.Combine(
+            FindRepoRoot(),
+            "tools",
+            "run-connected-r6-soak.ps1"));
+
+        Assert.Contains("[switch]$Uncapped", source, StringComparison.Ordinal);
+        Assert.Contains(
+            "$env:ACDREAM_UNCAPPED_RENDER = if ($Uncapped) { '1' } else { $null }",
+            source,
+            StringComparison.Ordinal);
+        Assert.DoesNotContain(
+            "$env:ACDREAM_UNCAPPED_RENDER = '1'",
+            source,
+            StringComparison.Ordinal);
+    }
+
+    [Fact]
+    public void StationaryDwellSamplesAfterTheLivenessDeadline()
+    {
+        // LiveEntityLivenessController.DestructionTimeoutSeconds is 25s; the
+        // stationary sample must dwell past it or a prior destination's
+        // records can masquerade as retained memory in the return gate.
+        // The script previously slept only 12s despite the comment already
+        // citing the 25s deadline.
+        string source = File.ReadAllText(Path.Combine(
+            FindRepoRoot(),
+            "tools",
+            "run-connected-r6-soak.ps1"));
+
+        AssertAppearsInOrder(
+            source,
+            "LiveEntityLivenessController's authoritative absence deadline is 25",
+            "Start-Sleep -Seconds 26");
+    }
+
+    [Fact]
+    public void LaunchConfigurationIsDisclosedToTheArtifactDirectoryBeforeLaunch()
+    {
+        // 2026-07-24 measurement-tooling review: a prior audit could only
+        // observe ACDREAM_DUMP_MOVE_TRUTH because no other ACDREAM_* launch
+        // flag the script sets was ever recorded anywhere machine-readable.
+        string source = File.ReadAllText(Path.Combine(
+            FindRepoRoot(),
+            "tools",
+            "run-connected-r6-soak.ps1"));
+
+        AssertAppearsInOrder(
+            source,
+            "Get-ChildItem Env: | Where-Object { $_.Name -like 'ACDREAM_*' }",
+            "Join-Path $artifactDir 'env-disclosure.json'",
+            "try {");
+        Assert.Contains(
+            "EnvDisclosure = Join-Path $artifactDir 'env-disclosure.json'",
+            source,
+            StringComparison.Ordinal);
+        // ACDREAM_DUMP_MOVE_TRUTH stays SET (the exercise gate greps its
+        // output) — it is now disclosed, not removed.
+        Assert.Contains("$env:ACDREAM_DUMP_MOVE_TRUTH = '1'", source, StringComparison.Ordinal);
+    }
+
     private static int CountOccurrences(string source, string value)
     {
         int count = 0;

tests/AcDream.App.Tests/Diagnostics/WorldLifecycleAutomationControllerTests.cs

@@ -278,7 +278,9 @@ public sealed class WorldLifecycleAutomationControllerTests
 
     private static WorldLifecycleResourceSnapshot EmptyResources() => new(
         0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
-        0, 0, 0L, 0, 0L, 0L, 0, 0, 0, 0, 0, 0, 0, 0L, 0L, 0d, 0d, null);
+        0, 0, 0L, 0, 0L, 0L, 0, 0, 0, 0, 0, 0, 0, 0L, 0L,
+        0L, 0L, 0L, 0L, 0L, 0L, 0L, 0L, 0L, 0L, 0L, 0L,
+        0d, 0d, null);
 
     private static string NewDirectory()
     {

tests/AcDream.App.Tests/FrameProfilerReportTests.cs

@@ -1,3 +1,4 @@
+using System.Globalization;
 using AcDream.App.Diagnostics;
 using Xunit;
 
@@ -5,6 +6,35 @@ namespace AcDream.App.Tests;
 
 public class FrameProfilerReportTests
 {
+    [Fact]
+    public void WriteHistoryCsv_WritesHeaderThenOneInvariantRowPerRecord()
+    {
+        // 2026-07-24 measurement-tooling review: ACDREAM_FRAME_HISTORY export.
+        // FrameBoundary itself needs a live GL context (GpuFrameTimer), so —
+        // matching FormatReport's precedent above — the CSV writer is a pure
+        // static method tested directly rather than driven through FrameBoundary.
+        var records = new[]
+        {
+            new FrameHistoryRecord(0, 12.5, 1000, 500, 2048, 100, 200, 30, 40),
+            new FrameHistoryRecord(1, 18.75, 1200, -1, -256, 110, 210, 31, 41),
+        };
+        var buffer = new StringWriter(CultureInfo.InvariantCulture);
+
+        FrameProfiler.WriteHistoryCsv(records, buffer);
+
+        string[] lines = buffer.ToString().Split(
+            Environment.NewLine, StringSplitOptions.RemoveEmptyEntries);
+        Assert.Equal(3, lines.Length);
+        Assert.Equal(
+            "frame,timestamp_ms,cpu_us,gpu_us,alloc_bytes,update_us,upload_us,imgui_us,pacing_us",
+            lines[0]);
+        Assert.Equal("0,12.500,1000,500,2048,100,200,30,40", lines[1]);
+        // gpu_us=-1 marks "no GPU sample available"; alloc_bytes can go
+        // negative (documented alloc-channel behavior, matches FrameStatsBuffer.Max).
+        Assert.Equal("1,18.750,1200,-1,-256,110,210,31,41", lines[2]);
+    }
+
+
     [Fact]
     public void FormatReport_IsInvariantAndComplete()
     {

tests/AcDream.App.Tests/Rendering/Wb/MeshUploadCachesTests.cs

@@ -297,6 +297,26 @@ public sealed class MeshUploadCachesTests
         Assert.True(staging.Stage(DataWithTexture(2, 1)));
     }
 
+    [Fact]
+    public void CpuCacheStats_TracksHitsMissesAndEvictions()
+    {
+        // 2026-07-24 measurement-tooling review: the checkpoint JSON exposes
+        // cache traffic (not just residency) so a revisit's hit/miss ratio
+        // is auditable from an artifact alone.
+        var staging = new MeshUploadStagingQueue();
+        var cache = new CpuMeshUploadCache(capacity: 1);
+
+        Assert.False(cache.TryGetAndStage(1, staging, out _, out _)); // miss
+        cache.Store(DataWithTexture(1, 4));
+        Assert.True(cache.TryGetAndStage(1, staging, out _, out _)); // hit
+        cache.Store(DataWithTexture(2, 4)); // capacity=1 evicts id 1
+
+        CacheStats stats = cache.Stats;
+        Assert.Equal(1, stats.Hits);
+        Assert.Equal(1, stats.Misses);
+        Assert.Equal(1, stats.Evictions);
+    }
+
     private static ObjectMeshData DataWithTexture(ulong id, int bytes)
     {
         var data = new ObjectMeshData { ObjectId = id };

tests/AcDream.Content.Tests/BoundedDatObjectCacheTests.cs

@@ -118,6 +118,25 @@ public sealed class BoundedDatObjectCacheTests
         Assert.Equal(2, cache.Count);
     }
 
+    [Fact]
+    public void Stats_TracksHitsMissesAndEvictions()
+    {
+        // 2026-07-24 measurement-tooling review: the checkpoint JSON exposes
+        // cache traffic (not just residency) so a revisit's hit/miss ratio
+        // is auditable from an artifact alone.
+        var cache = CreateCache(entryLimit: 1, byteLimit: 100);
+
+        Assert.False(cache.TryGet<Surface>(1, out _)); // miss
+        cache.GetOrAdd(1, Surface(1));
+        Assert.True(cache.TryGet<Surface>(1, out _)); // hit
+        cache.GetOrAdd(2, Surface(2)); // entryLimit=1 evicts id 1
+
+        CacheStats stats = cache.Stats;
+        Assert.Equal(1, stats.Hits);
+        Assert.Equal(1, stats.Misses);
+        Assert.Equal(1, stats.Evictions);
+    }
+
     private static BoundedDatObjectCache CreateCache(int entryLimit, long byteLimit) =>
         new(entryLimit, byteLimit, _ => 1);
 

tests/AcDream.Content.Tests/DecodedTextureCacheTests.cs

@@ -144,6 +144,25 @@ public sealed class DecodedTextureCacheTests {
         Assert.Equal(new byte[] { 1 }, recovered);
     }
 
+    [Fact]
+    public void Stats_TracksHitsMissesAndEvictions()
+    {
+        // 2026-07-24 measurement-tooling review: the checkpoint JSON exposes
+        // cache traffic (not just residency) so a revisit's hit/miss ratio
+        // is auditable from an artifact alone.
+        var cache = new DecodedTextureCache(maximumBytes: 4, maximumEntries: 1);
+
+        Assert.False(cache.TryGet(Key(1), out _)); // miss
+        cache.RetainOrUse(Key(1), new byte[4], out _);
+        Assert.True(cache.TryGet(Key(1), out _)); // hit
+        cache.RetainOrUse(Key(2), new byte[4], out _); // maximumEntries=1 evicts key 1
+
+        CacheStats stats = cache.Stats;
+        Assert.Equal(1, stats.Hits);
+        Assert.Equal(1, stats.Misses);
+        Assert.Equal(1, stats.Evictions);
+    }
+
     private static byte[] AssertCacheHit(DecodedTextureCache cache, DecodedTextureKey key)
     {
         Assert.True(cache.TryGet(key, out byte[] pixels));