feat(pathfinding): JSONL recorder + public bake helpers (#2449)

## Summary

Adds two pieces of pathfinding tooling on top of PR #2448's lazy `.swb` infrastructure:

- **`PathfindRecorder`** — admin-toggled JSONL telemetry capture; one record per `BitmapAStarAlgorithm.Find` call. Output format matches the BDN harness corpus, so production traffic can be captured and replayed in benchmarks without an adapter.
- **Public bake helpers on `StepCache`** — `ComputeLiveTileDataHash`, `TryReadTileDataHashFromFile`, `BakeMap`, `ClearResidentChunks`. Lets the benchmark project (and any future bake utility) drive cache fill + persist without exposing internal types.

The companion BDN harness update lives in [ModernUO-Benchmarks#kb/pathfinding-pr4-bench](https://github.com/modernuo/ModernUO-Benchmarks/tree/kb/pathfinding-pr4-bench): porting `Benchmarks/PathfindInGame/` from the `kb/ai_pathfinding` branch to the API shipped in #2446–#2448.

## What's in this PR

### `PathfindRecorder` (`PathfindRecorder.cs`)
- Holds a single `StreamWriter` open while recording; its internal buffer absorbs per-record writes without per-call `File.AppendAllText`.
- Single `bool` check on the hot path; cheap when disabled.
- Disabling flushes + disposes; an IO failure during write also disables the recorder.
- Server config:
  - `pathfinding.recorder.enable` — bool, default `false`. Read on boot via `GetOrUpdateSetting`.
  - `pathfinding.recorder.path` — default `<basedir>/Data/Pathfinding/recordings/pathfinds.jsonl`.
- Hooked into `BitmapAStarAlgorithm.Find` — runs once per call, does nothing when disabled.
- Admin command: `[PathRecord [on|off|flush|status]` (default `status`).

### Public cache helpers
- `static ulong StepCache.ComputeLiveTileDataHash()` — wraps the file module's hash function for staleness checks.
- `static bool StepCache.TryReadTileDataHashFromFile(string, out ulong)` — peeks at a `.swb` file's hash field (20 bytes).
- `int StepCache.BakeMap(int, string)` — walks every chunk in the map, populates resident set, saves. Offline / fixture use; blocks for many seconds on a full-map walk.
- `void StepCache.ClearResidentChunks()` — drops chunks + zeros counters but keeps lazy readers open. Lets benchmark loops measure "first query after boot" cost across iterations without the lazy-reader reopen overhead.

Projects/Server/TileMatrix/TileMatrix.cs

@@ -17,6 +17,7 @@ using Server.Logging;
 using System;
 using System.Collections.Generic;
 using System.IO;
+using System.IO.Hashing;
 using System.Runtime.CompilerServices;
 using System.Runtime.InteropServices;
 
@@ -48,6 +49,16 @@ public class TileMatrix
     public FileStream DataStream { get; }
     public BinaryReader IndexReader { get; }
 
+    /// <summary>
+    /// XxHash3 fingerprint over the bytes of the three on-disk files for this map
+    /// (mapX.mul / .uop, staidxX.mul, staticsX.mul). The .mul format has no built-in
+    /// CRC and CentredSharp / UOFiddler rewrite these files in place, so this is the
+    /// only way to detect "client patched / mapper saved" changes that invalidate
+    /// downstream caches keyed on map data. Computed once at construction; never
+    /// changes for the lifetime of the TileMatrix.
+    /// </summary>
+    public ulong MapFilesFingerprint { get; }
+
     public static bool Pre6000ClientSupport { get; private set; }
 
     public static void Configure()
@@ -140,6 +151,12 @@ public class TileMatrix
             {
                 logger.Warning("{File} was not found.", $"statics{fileIndex}.mul");
             }
+
+            // Stream all three on-disk files through XxHash3 once. Saves + restores
+            // each stream's position so this is invisible to the rest of the constructor
+            // (UOP path has already read part of MapStream by now). Cost is ~5-10ms per
+            // map at boot — paid once, then MapFilesFingerprint is a constant.
+            MapFilesFingerprint = ComputeMapFilesFingerprint();
         }
 
         _emptyStaticBlock = new StaticTile[8][][];
@@ -164,6 +181,27 @@ public class TileMatrix
         Patch = new TileMatrixPatch(this, fileIndex);
     }
 
+    private ulong ComputeMapFilesFingerprint()
+    {
+        var hasher = HashUtility.CreateXxHash3();
+        AppendStreamFromStart(hasher, MapStream);
+        AppendStreamFromStart(hasher, IndexStream);
+        AppendStreamFromStart(hasher, DataStream);
+        return hasher.GetCurrentHashAsUInt64();
+    }
+
+    private static void AppendStreamFromStart(XxHash3 hasher, FileStream stream)
+    {
+        if (stream == null)
+        {
+            return;
+        }
+        var originalPosition = stream.Position;
+        stream.Position = 0;
+        hasher.Append(stream);
+        stream.Position = originalPosition;
+    }
+
     public StaticTile[][][] EmptyStaticBlock => _emptyStaticBlock;
 
     public void SetStaticBlock(int x, int y, StaticTile[][][] value)

Projects/Server/Utilities/HashUtility.cs

@@ -14,6 +14,7 @@
  *************************************************************************/
 
 using System;
+using System.IO;
 using System.IO.Hashing;
 using System.Numerics;
 using System.Runtime.InteropServices;
@@ -66,6 +67,36 @@ public static class HashUtility
         return result;
     }
 
+    /// <summary>
+    /// One-shot streaming hash. Reads from the stream's current position to its end and
+    /// returns the XxHash3 result. The caller is responsible for setting the stream
+    /// position before the call (and restoring it afterward, if the stream will be reused).
+    /// Returns 0 on a null or unreadable stream.
+    /// </summary>
+    public static ulong ComputeHash64(Stream stream)
+    {
+        if (stream == null || !stream.CanRead)
+        {
+            return 0;
+        }
+
+        var hasher = _xxHash3 ??= new XxHash3(unchecked((long)xxHash3Seed));
+        hasher.Append(stream);
+
+        var result = hasher.GetCurrentHashAsUInt64();
+        hasher.Reset();
+
+        return result;
+    }
+
+    /// <summary>
+    /// Returns a fresh <see cref="XxHash3"/> seeded with HashUtility's standard seed.
+    /// Use this when you need to combine multiple inputs into a single hash via
+    /// successive Append calls — the one-shot ComputeHash64 overloads are stateless
+    /// (Reset between callers) and can't compose. Caller owns the returned instance.
+    /// </summary>
+    public static XxHash3 CreateXxHash3() => new(unchecked((long)xxHash3Seed));
+
     public static uint ComputeHash32(ReadOnlySpan<char> str)
     {
         if (str == ReadOnlySpan<char>.Empty)