perf(pathing): pool the StepCache strata buffer, then clean up the pathing engine around it (#2523)

Started as an allocation pass over `StepCache` and grew into a cleanup of the surrounding pathing engine. Four commits, each independently reviewable; net **−560 lines**.

Build clean (0 warnings). All 122 `Server.Tests.Pathfinding` tests pass.

---

## 1. `perf`: pool the strata buffer, cut a hot-path dictionary lookup

**The headline is that `TryGetMask` — the actual hot path — was already allocation-free.** `StepMask` is a readonly struct, `StaticTileEnumerable` is a `ref struct`, `ChunkMissState` is a struct in a `Dictionary`. So most of this is a bake-throughput and GC-churn win, with one exception noted below.

`BuildChunk` accumulated packed multi-Z strata into a `List<byte>` that grew by doubling (256 → 512 → 1024 → …) and then paid a final `ToArray()`. A full map bake runs it ~114k times. It now writes into a `byte[]` rented from `STArrayPool<byte>.Shared` through a span writer, and hands the chunk one exact-size copy.

**This required fixing a latent out-of-bounds guard.** The record-fit check reserved headroom for **8** strata (`StratumByteLength * 8`) while `ComputeStandableSurfaceZs` can return up to **16** — so a cell could write 305 bytes starting from a 65,383-byte offset. Against a `List` that was benign (it just grew past 64 KB, and emitted offsets stayed under the `NoStrata` sentinel). Against a fixed-size rented buffer it is an out-of-bounds write, so tightening it was a *prerequisite* for the pooling, not a drive-by. The guard is now exact, which additionally proves no emitted offset can collide with `NoStrata == ushort.MaxValue`.

**One genuine query-path win:** `ShouldPromoteAfterMiss` did *two* dictionary lookups per miss — a `TryGetValue`, then an indexer assignment that re-hashes and re-probes. It now mutates in place via `CollectionsMarshal.GetValueRefOrNullRef`. This runs on every uncached chunk touch during A* expansion. The window-expiry branch keeps its explicit early return, so `MissPromotionThreshold == 1` still resets rather than promoting.

Also dropped `StepProbe.ComputeStrataAt` / `ComputedStratum` (dead code, zero callers) and collapsed six 18-argument `new StepMask(0, 0, …, kind)` blocks into `Fallthrough(kind)`.

**Considered and rejected:** pooling the `Direction[]` that `Find` returns. It *escapes* the call — `MovementPath` holds it across ticks while `PathFollower` walks `m_Index` through it — so it cannot be rented-and-returned, and it cannot be borrowed from the shared `BitmapAStarAlgorithm.Instance` without one creature clobbering another's in-flight path. `CheckPath` rate-limits repaths to one per 2s per creature, putting this at roughly 60 KB/sec at 1,000 pathing creatures. Not worth a public API break plus a use-after-return footgun.

## 2. `docs`: rewrite the comments for publication

The comments had accumulated as development notes: internal phase jargon (`Tier 4`, `the Phase-2 synthesizer`), change narration aimed at a reviewer (`which the old ComputeStandingZ anchor missed`, `legacy behavior`), benchmark anecdotes (`benchmarked as near-optimal`, `a ~20 ns lookup`), and paragraphs restating the code.

Rewritten to keep the rationale you cannot recover by reading the code — why the source-Z guard cannot be widened, why multis fall through with a halo, why the promotion gate counts Finds rather than calls, why `ComputeFingerprint` must hash the *files* and not the live tile tables — and drop the history that got us there.

Three comments were **factually wrong**, not just wordy:

- `CacheEvictionTimer` and `CacheStats` documented a class called `StaticWalkabilityCache`. No such class exists — it is `StepCache`.
- `StepCacheFile` declared `File layout v8` while `FormatVersion` is 9, and called the current record layout "the v6 layout" in four places. The layout descriptions are now unversioned so they cannot drift again.
- `StepProbe.ComputeStandingZ` claimed `StepCache` uses it to bake `SourceZ`. It has not since the baker moved to the clearance-aware `ComputeStandableSurfaceZs`; only a parity test calls it.

## 3. `refactor`: simplify `StepCacheFile.Write`, consolidate the format tests

`SaveToFile` walked `_keysList` **twice** — once to count the map's chunks, then again through a `ChunkEnumerator` closure to emit them — because `Write` needed the count up front to size its index array. Both loops had the same root cause. Passing a **span** collapses them: the count is just `span.Length`.

That deletes the `ChunkEnumerator` delegate, the closure over the list enumerator, and **both `InvalidOperationException` throws**, which existed only to police the delegate's "yield exactly `chunkCount` chunks" contract — a contract a span makes unrepresentable.

`Write` now patches the header's `IndexOffset` by seeking back to it rather than reaching into the writer's live buffer with `BinaryPrimitives`. That also retires `IndexOffsetFieldPosition`, a hand-maintained byte offset that had to track the header layout, and sidesteps the stale-array hazard that motivated the manual patch (`BufferWriter` reallocates on growth).

**Tests:** `StepCacheFileV6/V7/V8Tests` were named for the format version that introduced each transform — and the format is now **v9**, so all three names described formats the loader rejects outright. Beyond triplicated builders and plumbing, two things were actually broken:

- The three near-identical rejection tests each cited a `MinSupportedVersion` that had since moved (`"version 5 < MinSupportedVersion 6"`, `"6 < 7"`, `"7 < 8"`). They passed for the wrong reason.
- `AssertBaseEqual` (used by V7 and V8) **silently skipped the swim and strata trailers**. A regression dropping either would not have failed those tests.

Now one `StepCacheFileFormatTests`, named for behavior — predictive-Z elision, compression, compact index — with a single `AssertIdentical` that does check both trailers, the three rejection tests folded into one theory that also covers a future version, and a zero-chunk case the delegate-based writer never had coverage for.

## 4. `test`: consolidate the parity and lifecycle tests

Three files tested "parity" and none of the names said *which*. They were three different layers, and the seams are the useful part, so they are now one `StepCacheParityTests` that names them:

| Test | Compares | Answers |
|---|---|---|
| `ProbeMatchesSlowPath` | StepProbe vs MovementImpl | Is the bake right? |
| `CacheMatchesProbe` | StepCache vs StepProbe | Is it stored and returned intact? |
| `CacheServesReachableWalkStates` | StepCache vs MovementImpl | End to end, over the states A* visits |

Merging removed a duplicated stub `Mobile`, duplicated region seeds, and a filename/class mismatch (`StepProbeParityTests.cs` declared `StaticWalkabilityParityTests`). `SwimBake_ProducesWetCells` moved with it — it lived in the cache parity file but never touched the cache.

Tests reached into `StepCache._chunks` via `GetField` in **9 places**, each rebuilding the key encoding and cell-index arithmetic by hand. `StepCache` now exposes `GetResidentChunk` and `ResidentIndexInSync` alongside the internal test hooks it already had (`LazyReaderHasChunk`, `CurrentFindGeneration`), and the shared arithmetic moved to `PathingTestSupport`. All 9 reflection blocks are gone.

`StepCacheLifecycleTests` is regrouped by what it covers — promotion gate, fallthrough routes, strata, swim layer, eviction — with the `Tier4*` names dropped. Removed `Singleton_IsAvailable`, which asserted an inline-initialized static property was not null; that is the entire 123 → 122 test-count delta.

---

## Verification

Tests were mutation-checked rather than just run, since round-trip and parity tests can pass while a transform silently no-ops:

- Injecting an off-by-one into the `IndexOffset` patch fails **15 of 123** — the format tests are load-bearing.
- Offsetting the cache's cell index by one fails **7 of 10** parity cases, and the 3 that stay green are exactly the ones that do not touch the cache. The layering localizes a fault rather than just reporting one.

Projects/UOContent/Engines/Pathing/PathCacheCommands.cs

@@ -8,23 +8,23 @@ namespace Server.Engines.Pathing;
 
 /// <summary>
 /// Admin commands for inspecting and operating the pathfinding step cache.
-///   [PathCacheStats — current resident-chunk count + hit/miss/eviction telemetry.
-///   [PathCacheClear — drop all cached chunks, close lazy readers, zero counters.
-///   [PathBake       — walk a whole map building the full static cache, then save it.
-///   [PathCacheSave  — persist resident chunks per map to Data/Pathfinding/&lt;mapId&gt;.swb.
-///   [PathCacheLoad  — open those files as lazy backing stores. Also runs at startup.
-///   [PathRecord     — toggle JSONL telemetry capture for replay / benchmark corpora.
+///   [PathCacheStats — resident-chunk count and hit/miss/eviction telemetry.
+///   [PathCacheClear — drop all cached chunks, close the .swb readers, zero the counters.
+///   [PathBake       — build a map's full static cache and save it.
+///   [PathCacheSave  — persist the resident chunks to Data/Pathfinding/&lt;mapId&gt;.swb.
+///   [PathCacheLoad  — open those files as backing stores. Also runs at startup.
+///   [PathRecord     — toggle capture of pathfind telemetry.
 ///
-/// The step cache works WITHOUT any .swb file — chunks build on demand as creatures path.
-/// A baked .swb is an optional optimization that removes first-pathfind-after-boot latency
-/// for shard owners who want it; <see cref="OnPathBake"/> is how you produce one.
+/// None of this is required: the cache builds chunks on demand as creatures path, with or without
+/// a .swb on disk. Baking one is purely an optimization that trades disk and a few minutes of bake
+/// time for the removal of first-pathfind-after-boot latency.
 /// </summary>
 public static class PathCacheCommands
 {
     private static readonly ILogger logger = LogFactory.GetLogger(typeof(PathCacheCommands));
 
-    // modernuo.json flag: when true, Initialize() bakes any missing/stale .swb at startup.
-    // The first-boot ConfigurePrompts() prompt writes it.
+    // When set, Initialize() bakes any missing or stale .swb at startup. ConfigurePrompts() asks
+    // for it on first boot.
     private const string PrebakeSetting = "pathfinding.prebakeMaps";
 
     private static string PathFor(int mapId) =>
@@ -32,9 +32,8 @@ public static class PathCacheCommands
 
     public static void Configure()
     {
-        // Resident-chunk cap is shard-tunable. Default 8192 ≈ 40 MB; small shards may
-        // want lower, large shards (or full-map bakes) may want higher. Setting is
-        // written back to server.cfg on first boot for discoverability.
+        // Resident-chunk cap, shard-tunable — the default works out to roughly 40 MB. Written back
+        // to server.cfg on first boot so it's discoverable.
         StepCache.Instance.MaxResidentChunks = ServerConfiguration.GetOrUpdateSetting(
             "pathfinding.maxResidentChunks",
             8192
@@ -52,13 +51,13 @@ public static class PathCacheCommands
     }
 
     /// <summary>
-    /// First-boot prompt, auto-invoked by <c>AssemblyHandler.Invoke("ConfigurePrompts")</c> in
-    /// the startup sequence — after assemblies load (so content can prompt) but before Serilog
-    /// starts, so the console prompt isn't interleaved with async log output. Offers to pre-bake
-    /// the pathfinding <c>.swb</c> cache for the selected maps; the answer persists in
-    /// modernuo.json (<see cref="PrebakeSetting"/>), so it's asked exactly once. Skipped when the
-    /// setting already exists or when input is redirected (headless/CI) — operators can set the
-    /// flag directly. The bake itself happens later in <see cref="Initialize"/>.
+    /// Asks, once, whether to pre-bake the .swb cache; <see cref="Initialize"/> does the work later.
+    /// The answer persists, so the question is never repeated, and it's skipped entirely when input
+    /// is redirected — a headless or CI boot sets <see cref="PrebakeSetting"/> directly instead.
+    ///
+    /// Runs in the ConfigurePrompts phase because that's the one window where content can prompt:
+    /// assemblies are loaded, but Serilog hasn't started, so console output won't interleave with
+    /// async log writes.
     /// </summary>
     public static void ConfigurePrompts()
     {
@@ -81,16 +80,15 @@ public static class PathCacheCommands
     }
 
     /// <summary>
-    /// Auto-invoked by <c>AssemblyHandler.Invoke("Initialize")</c> after the tile matrix and
-    /// world are loaded. When <see cref="PrebakeSetting"/> is set, bakes any map whose
-    /// <c>.swb</c> is missing or stale, so the first pathfind on each region is already warm. A
-    /// fresh cache makes this a no-op, so only first boot — or a client/map update that changes
-    /// the fingerprint — pays the cost.
+    /// Bakes any map whose <c>.swb</c> is missing or stale, when <see cref="PrebakeSetting"/> is
+    /// set. Runs in the Initialize phase, once the tile matrix and world are loaded. An up-to-date
+    /// cache makes it a no-op, so the cost lands only on a first boot or after a client or map
+    /// update moves the fingerprint.
     ///
-    /// Validity is decided by <see cref="StepCache.HasLazyReader"/>: <see cref="Configure"/> runs
-    /// <see cref="AutoLoadAtStartup"/> in the earlier Configure phase, opening (and fingerprint-
-    /// validating) a reader for every up-to-date <c>.swb</c>. So a map with an open reader is
-    /// already good and we skip it — no need to recompute the fingerprint a second time here.
+    /// A map is judged up-to-date by whether it has an open reader. <see cref="AutoLoadAtStartup"/>
+    /// already ran in the earlier Configure phase and only opens a reader for a .swb whose
+    /// fingerprint validates, so an open reader is proof of a good bake — no need to fingerprint
+    /// the map a second time here.
     /// </summary>
     public static void Initialize()
     {
@@ -110,7 +108,7 @@ public static class PathCacheCommands
 
             if (StepCache.Instance.HasLazyReader(map.MapID))
             {
-                continue; // AutoLoadAtStartup already opened a fingerprint-valid .swb for this map
+                continue; // already has a fingerprint-valid .swb open
             }
 
             var path = PathFor(map.MapID);
@@ -127,15 +125,14 @@ public static class PathCacheCommands
         if (baked > 0)
         {
             logger.Information("PathBake: pre-bake complete ({Count} map(s) written).", baked);
-            AutoLoadAtStartup(); // (re)open the freshly written files as lazy backing stores
+            AutoLoadAtStartup(); // reopen what we just wrote
         }
     }
 
     /// <summary>
-    /// Open Data/Pathfinding/&lt;mapId&gt;.swb as a lazy backing store for every map.
-    /// Reads only the header + chunk-offset index up front (~16 bytes per chunk);
-    /// individual chunk records are fetched on demand when the cache asks for them.
-    /// RAM stays bounded by MaxResidentChunks regardless of file size.
+    /// Opens Data/Pathfinding/&lt;mapId&gt;.swb as a backing store for every map. Only the header and
+    /// index are read up front; chunk records are fetched as the cache asks for them, so resident
+    /// memory stays bounded by the LRU cap however large the files are.
     /// </summary>
     private static void AutoLoadAtStartup()
     {
@@ -196,9 +193,9 @@ public static class PathCacheCommands
                 continue;
             }
 
-            // BakeMap walks the whole map (building every chunk) and writes the .swb. The
-            // chunks are left resident afterward; drop them so peak memory is bounded to one
-            // map at a time and the post-command footprint returns to the LRU cap.
+            // BakeMap leaves every chunk it built resident. Drop them between maps so peak memory
+            // is one map's worth rather than all of them, and the footprint afterwards is back
+            // under the LRU cap.
             var written = StepCache.Instance.BakeMap(map.MapID, PathFor(map.MapID));
             StepCache.Instance.ClearResidentChunks();
 
@@ -218,8 +215,7 @@ public static class PathCacheCommands
             return;
         }
 
-        // Reopen the freshly written files as lazy backing stores so they're usable now
-        // without a restart (resident memory stays bounded by the LRU cap).
+        // Reopen what we just wrote, so the bake is usable immediately without a restart.
         AutoLoadAtStartup();
         from.SendMessage($"PathBake: {totalChunks} chunks across {totalMaps} map(s) in {sw.Elapsed.TotalSeconds:F1}s; lazy readers reopened.");
     }