manupawickramasinghe · Jul 20, 2026 · Jul 22, 2026 · Jul 22, 2026 · Jul 22, 2026 · Jul 22, 2026
diff --git a/.github/images/astro-bot.jpg b/.github/images/astro-bot.jpg
diff --git a/.github/images/astros-playroom.jpg b/.github/images/astros-playroom.jpg
diff --git a/.github/images/cult-of-the-lamb.jpg b/.github/images/cult-of-the-lamb.jpg
diff --git a/.github/images/dead-cells.jpg b/.github/images/dead-cells.jpg
diff --git a/.github/images/demons-souls.jpg b/.github/images/demons-souls.jpg
diff --git a/.github/images/gow-sos.jpg b/.github/images/gow-sos.jpg
diff --git a/.github/images/hades.jpg b/.github/images/hades.jpg
diff --git a/.github/images/pac-man-world-re-pac.jpg b/.github/images/pac-man-world-re-pac.jpg
diff --git a/.github/images/tomb-raider-v-remastered.jpg b/.github/images/tomb-raider-v-remastered.jpg
diff --git a/.github/workflows/notify-site.yml b/.github/workflows/notify-site.yml
@@ -12,7 +12,7 @@ on:
 
 jobs:
   dispatch:
-    runs-on: ubuntu-26.04
+    runs-on: ubuntu-latest
     steps:
       - name: Trigger sharpemu-site rebuild
         env:

diff --git a/.github/workflows/pr-build-links.yml b/.github/workflows/pr-build-links.yml
@@ -26,7 +26,7 @@ permissions:
 jobs:
   comment:
     name: Post artifact links
-    runs-on: ubuntu-26.04
+    runs-on: ubuntu-latest
     # Only for successful PR builds — artifacts exist only when the build passed.
     if: >-
       github.event.workflow_run.event == 'pull_request' &&

diff --git a/.github/workflows/workflow.yml b/.github/workflows/workflow.yml
@@ -34,7 +34,7 @@ concurrency:
 jobs:
   init:
     name: Init
-    runs-on: ubuntu-26.04
+    runs-on: ubuntu-latest
     outputs:
       release-name: ${{ steps.vars.outputs.release-name }}
       release-tag: ${{ steps.vars.outputs.release-tag }}
@@ -71,7 +71,7 @@ jobs:
   reuse:
     name: REUSE Compliance
     needs: init
-    runs-on: ubuntu-26.04
+    runs-on: ubuntu-latest
     steps:
       - name: Checkout repository
         uses: actions/checkout@v6
@@ -80,7 +80,7 @@ jobs:
         uses: fsfe/reuse-action@v6
 
   build:
-    name: Build win-x64
+    name: Build Archive
     needs:
       - init
       - reuse
@@ -138,7 +138,7 @@ jobs:
       fail-fast: false
       matrix:
         include:
-          - os: ubuntu-26.04
+          - os: ubuntu-latest
             rid: linux-x64
           - os: macos-latest
             rid: osx-x64
@@ -227,7 +227,7 @@ jobs:
     # Versioned releases are immutable and tag-driven. Branch and manual runs
     # still produce Actions artifacts without modifying a published release.
     if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')
-    runs-on: ubuntu-26.04
+    runs-on: ubuntu-latest
     permissions:
       contents: write
     steps:

diff --git a/.jules/bolt.md b/.jules/bolt.md
@@ -0,0 +1,60 @@
+<!--
+  Copyright (C) 2026 SharpEmu Emulator Project
+  SPDX-License-Identifier: GPL-2.0-or-later
+-->
+
+## 2026-07-25 - Replace reference records with readonly structs for Dictionary keys
+**Context:** Metal Video Presenter / PSO Cache (`PipelineKey`)
+**Learning:** Using `sealed record` for Dictionary keys causes implicit heap allocations on every lookup (due to it being a class reference type). Since PSO caching lookups happen per-frame or per-draw, this creates significant GC pressure.
+**Action:** Replace `sealed record` with `readonly struct` implementing `IEquatable<T>` and explicitly overriding `GetHashCode()` with `HashCode.Combine()` to eliminate allocations in hot dictionary lookups.
+
+## 2024-05-30 - [Kernel String Reading Optimization]
+**Context:** src/SharpEmu.Libs/Kernel/KernelMemoryCompatExports.cs
+**Learning:** Guest string reading operations (TryCompareStrings, Strchr, Strrchr, Memchr, TryCompareStringsCaseInsensitive) read character by character in loops, making a new TryReadCompat call (which grabs locks and searches trees in VirtualMemory) for every single byte. This creates huge overhead for long strings, which could be reduced with chunked reads or reading the whole thing using the existing CString functions.
+**Action:** Use TryReadCString or chunked reads instead of 1-byte read loops.
+
+## 2026-07-26 - Testing Roslyn Incremental Generator Equality Models
+
+**Context:** When working with C# Source Generators, `IIncrementalGenerator` caching relies heavily on the `Equals` and `GetHashCode` implementations of intermediate data models. If these methods are incomplete or flawed, Roslyn will incorrectly cache or regenerate output, leading to performance issues or stale state. In the context of `SysAbiExportGenerator`, the `ExportModel` is a private, nested type that was largely untested for equality logic.
+
+**Learning:** To guarantee 100% line and branch coverage on these critical internal data models, the most direct and reliable approach is to use reflection within standard xUnit tests. This circumvents the need to construct complex `CSharpCompilation` trees and invoke `CSharpGeneratorDriver` incrementally just to trigger `IEquatable` calls, reducing test brittleness and focusing on structural equality.
+
+**Action:** Created `ExportModelEqualityTests` in `SysAbiExportGeneratorTests.cs` using `GetNestedType` and `Activator.CreateInstance` to thoroughly test all branches of `ExportModel` equality logic, improving code reliability for the generator pipeline.
+
+## 2024-05-18 - Optimize PhysicalVirtualMemory FindRegion Bottleneck
+**Context:** `src/SharpEmu.Core/Memory/PhysicalVirtualMemory.cs`
+**Learning:** The `List<T>` indexer inside the `FindRegion` binary search hot path incurred bounds-checking and method-call overhead. Accessing it via `CollectionsMarshal.AsSpan` yielded a measurable decrease in execution time on millions of iterations.
+**Action:** Use `CollectionsMarshal.AsSpan` for hot path reads of `List<T>` instead of indexers when zero-allocation and bounds-checking elision is needed.
+
+## 2026-08-26 - Direct Span Access in Virtual Memory Search
+**Context:** `src/SharpEmu.Core/Memory/VirtualMemory.cs` (`FindInsertionIndex`)
+**Learning:** Standard C# `List<T>` accesses inside high-frequency binary searches introduce unnecessary overhead via indexer property access and bounds checking. The same optimization pattern recently used in `PhysicalVirtualMemory.cs` (commit 980b47b) applies directly to `VirtualMemory.cs`. Bypassing this via `CollectionsMarshal.AsSpan(list)` completely elides these checks, turning the operation into direct O(1) span memory access.
+**Action:** When optimizing binary search loops or hot paths over `List<T>`, immediately refactor to use `CollectionsMarshal.AsSpan()` to access elements and `span.Length` for bounds, alongside the `>>> 1` operator for division.
+## 2026-09-13 - Bounds Check Elision in Guest MMU Read/Write Loops
+**Context:** Guest MMU Address Translation / `VirtualMemory.cs`
+**Learning:** The C# JIT compiler cannot elide array bounds checks for `Span<T>` or arrays when using a `while` loop with a manually managed index. This introduces silent branching overhead in memory-intensive hot paths (like `TryValidateRange`, `CopyFromRegions`).
+**Action:** Always replace `while` loops iterating over sequential buffers with standard `for (var i = start; i < span.Length; i++)` loops to guarantee RyuJIT bounds check elimination in high-frequency emulation paths.
+
+## 2026-09-13 - SysAbiExportGenerator.ExportModel Constructor Signature Updates
+**Context:** Unit Tests / `SysAbiExportGeneratorTests.cs`
+**Learning:** When internal models like `ExportModel` are modified with new parameters (e.g., adding `bool preferLle`), reflection-based unit tests creating instances via `Activator.CreateInstance` will fail with `MissingMethodException` if the test arguments are not updated to match the new constructor signature.
+**Action:** Always verify and update reflection-based test factories whenever internal constructor signatures change to maintain test suite stability.
+## 2026-09-24 - Span Slicing & Bound Check Elision in Guest Memory Hot Paths
+**Context:** Guest MMU / `VirtualMemory.cs`
+**Learning:** Sequential memory chunking operations over spans can be significantly optimized by re-slicing the target spans (`destination = destination.Slice(...)`) instead of manually tracking offset counters and lengths. This enables tighter MSIL generation, reduces stack pressure, and removes redundant arithmetic in tight memory loops. Combined with standard for-loops, this allows the .NET JIT to reliably elide bounds checks.
+**Action:** Use idiomatic `Span.Slice` reassignment instead of indexer tracking for sequential chunked memory operations in C# hot paths.
+
+## 2026-09-26 - Span Slicing Reassignment in Hot Loops
+**Context:** Guest MMU / `VirtualMemory.cs` (`CopyFromRegions`, `CopyToRegions`)
+**Learning:** Sequential tracking over Spans with an external `copied` counter and range indexer (`span[copied..]`) introduces local bounds check validation overhead. Reassigning the span reference in place via `span = span.Slice(chunkLength)` eliminates this and simplifies hot loops into `!span.IsEmpty` checks.
+**Action:** Use idiomatic slice-reassignment (`span = span.Slice(length)`) instead of external integer trackers in loop conditions over `Span<T>` sequential memory operations to reduce arithmetic overhead.
+
+## 2023-10-25 - Kernel Memory Subsystem Allocation Elimination
+**Context:** `KernelMemoryCompatExports.cs`
+**Learning:** LINQ `Where(...).ToArray()` and `Where(...).OrderBy(...).FirstOrDefault()` chains inside the `_memoryGate` lock caused severe GC pressure during guest memory unmapping and querying. Because the critical section naturally isolates concurrent access, we can safely share a single static `List<T>` to collect unmapped regions, eliminating closures, enumerators, and per-call array allocations.
+**Action:** When filtering collections inside an existing critical section (`lock`), aggressively replace LINQ with manual `foreach` loops and cache results in static thread-safe buffers protected by the same lock.
+
+## 2026-10-25 - Chunked Guest Memory String Reading Optimization
+**Context:** src/SharpEmu.Libs/Kernel/KernelMemoryCompatExports.cs (`TryCompareStrings`, `TryCompareStringsCaseInsensitive`)
+**Learning:** Guest string reading operations for comparison previously read character by character in loops. This creates a new `TryReadCompat` call per byte, which means repeated page table lookups, locks, and bounds checks in the memory subsystem.
+**Action:** When optimizing guest memory string reading operations, replace 1-byte read loops with chunk-based reads (e.g. `stackalloc byte[128]`) and `Span<byte>`, reducing tree traversal overhead. Always include a fallback to byte-wise reads to correctly handle strings that terminate right before unmapped page boundaries without throwing false positives.
diff --git a/SharpEmu.slnx b/SharpEmu.slnx
@@ -20,6 +20,7 @@ SPDX-License-Identifier: GPL-2.0-or-later
     <Project Path="src/SharpEmu.SourceGenerators/SharpEmu.SourceGenerators.csproj" />
   </Folder>
   <Folder Name="/tests/">
+    <Project Path="tests/SharpEmu.Core.Tests/SharpEmu.Core.Tests.csproj" />
     <Project Path="tests/SharpEmu.Libs.Tests/SharpEmu.Libs.Tests.csproj" />
     <Project Path="tests/SharpEmu.ShaderCompiler.Metal.Tests/SharpEmu.ShaderCompiler.Metal.Tests.csproj" />
     <Project Path="tests/SharpEmu.ShaderCompiler.Tests/SharpEmu.ShaderCompiler.Tests.csproj" />

diff --git a/src/SharpEmu.Core/Cpu/Native/DirectExecutionBackend.Diagnostics.cs b/src/SharpEmu.Core/Cpu/Native/DirectExecutionBackend.Diagnostics.cs
@@ -253,7 +253,7 @@ private void ProbeReturnRip(ulong returnRip, long dispatchIndex)
 		{
 			Console.Error.WriteLine(
 				$"[LOADER][TRACE] Import#{dispatchIndex} pre-return bytes @0x{returnRip - preludeSize:X16}: " +
-				BitConverter.ToString(prelude.ToArray()).Replace("-", " "));
+				FormatHexBytes(prelude));
 
 			List<DecodedInst>? bestCallChain = null;
 			var preludeAddress = returnRip - preludeSize;
@@ -294,11 +294,17 @@ private void ProbeReturnRip(ulong returnRip, long dispatchIndex)
 		Span<byte> destination = stackalloc byte[128];
 		if (!cpuContext.Memory.TryRead(returnRip, destination))
 		{
-			Log.Debug($"Import#{dispatchIndex} return-rip probe: unreadable @0x{returnRip:X16}");
+			if (Log.IsEnabled(LogLevel.Debug))
+			{
+				Log.Debug($"Import#{dispatchIndex} return-rip probe: unreadable @0x{returnRip:X16}");
+			}
 			return;
 		}
-		string value = BitConverter.ToString(destination.ToArray()).Replace("-", " ");
-		Log.Debug($"Import#{dispatchIndex} return-rip bytes @0x{returnRip:X16}: {value}");
+		if (Log.IsEnabled(LogLevel.Debug))
+		{
+			string value = FormatHexBytes(destination);
+			Log.Debug($"Import#{dispatchIndex} return-rip bytes @0x{returnRip:X16}: {value}");
+		}
 		if (destination[0] == byte.MaxValue && (destination[1] == 21 || destination[1] == 37))
 		{
 			int num = BitConverter.ToInt32(destination.Slice(2, 4));
@@ -365,9 +371,12 @@ private void ProbeReturnRip(ulong returnRip, long dispatchIndex)
 
 			if (cpuContext.Memory.TryRead(target, targetBytes))
 			{
-				Log.Debug(
-					$"Import#{dispatchIndex} near-call target bytes @0x{target:X16}: " +
-					BitConverter.ToString(targetBytes.ToArray()).Replace("-", " "));
+				if (Log.IsEnabled(LogLevel.Debug))
+				{
+					Log.Debug(
+						$"Import#{dispatchIndex} near-call target bytes @0x{target:X16}: " +
+						FormatHexBytes(targetBytes));
+				}
 				if (targetBytes[0] == 0xFF && targetBytes[1] == 0x25)
 				{
 					int slotRel32 = BitConverter.ToInt32(targetBytes.Slice(2, 4));
@@ -402,6 +411,36 @@ private void ProbeReturnRip(ulong returnRip, long dispatchIndex)
 		}
 	}
 
+	private unsafe static string FormatHexBytes(ReadOnlySpan<byte> bytes)
+	{
+		if (bytes.Length == 0) return string.Empty;
+
+		fixed (byte* ptr = &MemoryMarshal.GetReference(bytes))
+		{
+			var ptrCopy = (IntPtr)ptr;
+			int length = bytes.Length;
+			return string.Create(length * 3 - 1, (ptrCopy, length), (span, state) =>
+			{
+				var (p, len) = state;
+				var readSpan = new ReadOnlySpan<byte>((void*)p, len);
+				for (int i = 0; i < readSpan.Length; i++)
+				{
+					byte b = readSpan[i];
+					int highNibble = b >> 4;
+					int lowNibble = b & 0x0F;
+
+					span[i * 3] = (char)(highNibble < 10 ? highNibble + '0' : highNibble - 10 + 'A');
+					span[i * 3 + 1] = (char)(lowNibble < 10 ? lowNibble + '0' : lowNibble - 10 + 'A');
+
+					if (i < readSpan.Length - 1)
+					{
+						span[i * 3 + 2] = ' ';
+					}
+				}
+			});
+		}
+	}
+
 	private static bool IsUnresolvedSentinel(ulong value)
 	{
 		return value == 65534 || value == 4294967294u || value == 18446744073709551614uL;

diff --git a/src/SharpEmu.Core/Cpu/Native/DirectExecutionBackend.Exceptions.cs b/src/SharpEmu.Core/Cpu/Native/DirectExecutionBackend.Exceptions.cs
@@ -81,8 +81,9 @@ private unsafe int UnhandledExceptionFilter(void* exceptionInfo)
 			Console.Error.WriteLine($"[LOADER][FATAL]   RSP: 0x{rsp:X16}");
 			Console.Error.Flush();
 		}
-		catch
+		catch (Exception ex)
 		{
+			Console.Error.WriteLine($"[LOADER][FATAL] Unhandled exception filter logging failed: {ex.Message}");
 		}
 
 		return 0;
@@ -373,7 +374,7 @@ private unsafe int VectoredHandler(void* exceptionInfo)
 					// exactly the faults that need it.
 					if (TryReadGuestOrHostBytes(rip, code))
 					{
-						Console.Error.WriteLine("[LOADER][INFO]   Code at RIP: " + BitConverter.ToString(code).Replace("-", " "));
+						Console.Error.WriteLine("[LOADER][INFO]   Code at RIP: " + FormatHexBytes(code));
 						if (code[0] == 100)
 						{
 							Console.Error.WriteLine("[LOADER][ERROR]   Detected FS segment prefix - TLS access not patched!");
@@ -391,12 +392,12 @@ private unsafe int VectoredHandler(void* exceptionInfo)
 						byte[] before = new byte[16];
 						if (rip > 16 && TryReadGuestOrHostBytes(rip - 16, before))
 						{
-							Console.Error.WriteLine("[LOADER][INFO]   Code before RIP: " + BitConverter.ToString(before).Replace("-", " "));
+							Console.Error.WriteLine("[LOADER][INFO]   Code before RIP: " + FormatHexBytes(before));
 						}
 						byte[] window = new byte[64];
 						if (rip > 32 && TryReadGuestOrHostBytes(rip - 32, window))
 						{
-							Console.Error.WriteLine("[LOADER][INFO]   Code window [RIP-0x20..]: " + BitConverter.ToString(window).Replace("-", " "));
+							Console.Error.WriteLine("[LOADER][INFO]   Code window [RIP-0x20..]: " + FormatHexBytes(window));
 						}
 						for (var stackIndex = 0; stackIndex < 16; stackIndex++)
 						{
@@ -415,7 +416,7 @@ private unsafe int VectoredHandler(void* exceptionInfo)
 							{
 								Console.Error.WriteLine(
 									$"[LOADER][INFO]   Stack guest-code candidate [rsp+0x{stackIndex * 8:X2}]=0x{candidate:X16}, bytes [-0x18..]: " +
-									BitConverter.ToString(callSiteWindow).Replace("-", " "));
+									FormatHexBytes(callSiteWindow));
 							}
 						}
 					}
@@ -450,7 +451,7 @@ private unsafe int VectoredHandler(void* exceptionInfo)
 					byte[] illegalCode = new byte[16];
 					if (TryReadHostBytes(rip, illegalCode))
 					{
-						Console.Error.WriteLine("[LOADER][INFO]   Code at RIP: " + BitConverter.ToString(illegalCode).Replace("-", " "));
+						Console.Error.WriteLine("[LOADER][INFO]   Code at RIP: " + FormatHexBytes(illegalCode));
 					}
 					DumpRecentImportTrace();
 					DumpGuestDisasmDiagnostics(rip, rbp, rsp);
@@ -597,8 +598,9 @@ private unsafe bool TryRecoverAuxiliaryThreadExecuteFault(
 				}
 			}
 		}
-		catch
+		catch (Exception ex)
 		{
+			Log.Error($"Failed to search guest threads by host thread ID {hostThreadId}", ex);
 		}
 
 		return null;

diff --git a/src/SharpEmu.Core/Cpu/Native/DirectExecutionBackend.Imports.cs b/src/SharpEmu.Core/Cpu/Native/DirectExecutionBackend.Imports.cs
@@ -518,7 +518,7 @@ private unsafe ulong DispatchImport(int importIndex, nint argPackPtr)
 			{
 				byte[] array = new byte[64];
 				Marshal.Copy((nint)(num7 - 32), array, 0, array.Length);
-				Console.Error.WriteLine($"[LOADER][TRACE] __stack_chk_fail return-site @0x{num7:X16}: {BitConverter.ToString(array).Replace("-", " ")}");
+				Console.Error.WriteLine($"[LOADER][TRACE] __stack_chk_fail return-site @0x{num7:X16}: {FormatHexBytes(array)}");
 			}
 			catch
 			{
@@ -2318,8 +2318,8 @@ private static string ComputePsNid(string symbolName)
 		var input = new byte[nameBytes.Length + salt.Length];
 		nameBytes.CopyTo(input, 0);
 		salt.CopyTo(input.AsSpan(nameBytes.Length));
-		Span<byte> digest = stackalloc byte[20];
-		SHA1.HashData(input, digest);
+		Span<byte> digest = stackalloc byte[32];
+		SHA256.HashData(input, digest);
 		var value = BinaryPrimitives.ReadUInt64LittleEndian(digest);
 		Span<byte> bigEndianValue = stackalloc byte[sizeof(ulong)];
 		BinaryPrimitives.WriteUInt64BigEndian(bigEndianValue, value);

diff --git a/src/SharpEmu.Core/Cpu/Native/DirectExecutionBackend.NativeWorker.cs b/src/SharpEmu.Core/Cpu/Native/DirectExecutionBackend.NativeWorker.cs
@@ -701,6 +701,7 @@ private static nint RunPrologue(nint executorHandle)
 				}
 				catch
 				{
+					// Ignore failures while writing error diagnostic logs to prevent unhandled exceptions in unmanaged callbacks.
 				}
 				return 0;
 			}
@@ -723,6 +724,7 @@ private static void RunEpilogue(nint executorHandle, ulong nativeResult)
 				}
 				catch
 				{
+					// Ignore failures while writing error diagnostic logs to prevent unhandled exceptions in unmanaged callbacks.
 				}
 			}
 		}
@@ -836,8 +838,12 @@ public void Dispose()
 			{
 				SignalWorkAvailable();
 			}
-			catch (ObjectDisposedException)
+			catch (ObjectDisposedException ex)
 			{
+				// The synchronization event handle (_workAvailable / _workSemaphore) may be disposed
+				// before or concurrently with the native guest worker executor teardown. Log the expected
+				// disposal exception at debug level to retain visibility while allowing cleanup to proceed.
+				Log.Debug($"Work available signal handle was already disposed during native worker disposal: {ex.Message}");
 			}
 			var exited = _threadHandle == 0;
 			if (_threadHandle != 0)

diff --git a/src/SharpEmu.Core/Cpu/Native/DirectExecutionBackend.cs b/src/SharpEmu.Core/Cpu/Native/DirectExecutionBackend.cs
@@ -7339,11 +7339,11 @@ private void LogStallWatchdogSnapshot()
 			Span<byte> destination = stackalloc byte[16];
 			if (cpuContext.Memory.TryRead(cpuContext.Rip, destination))
 			{
-				Console.Error.WriteLine($"[LOADER][ERROR] Stall bytes @rip: {BitConverter.ToString(destination.ToArray()).Replace("-", " ")}");
+				Console.Error.WriteLine($"[LOADER][ERROR] Stall bytes @rip: {FormatHexBytes(destination)}");
 			}
 			else if (cpuContext.Memory.TryRead(num, destination))
 			{
-				Console.Error.WriteLine($"[LOADER][ERROR] Stall bytes @rip_align: {BitConverter.ToString(destination.ToArray()).Replace("-", " ")}");
+				Console.Error.WriteLine($"[LOADER][ERROR] Stall bytes @rip_align: {FormatHexBytes(destination)}");
 			}
 			if (rsp != 0 && cpuContext.TryReadUInt64(rsp, out var value) && cpuContext.TryReadUInt64(rsp + 8, out var value2))
 			{