diff --git a/docs/testing/kirshara-macos.md b/docs/testing/kirshara-macos.md new file mode 100644 index 00000000..278ef78c --- /dev/null +++ b/docs/testing/kirshara-macos.md @@ -0,0 +1,37 @@ +# Kirshara protections on macOS + +Faster Queue Recovery and Thin Queue Protection use their existing implementation +on Apple Silicon and Intel. Queue Address Guard already supports macOS. The +shared `[control] kirshara_fixes` option controls the protections on every platform; +this change adds no settings and changes no queue policy or defaults. + +## Qualification + +Historical Mac client 199 (`1.000.52486`) inspection found the same 24-byte course +response layout: fleet at 0, success at 8, recall at 9, target at 16. Its aggregate +argument is indirect on Apple Silicon and stack-passed on Intel, matching the host +C++ ABI. The seven detour targets exceeded the architecture-specific SPUD overwrite +windows in those binaries. That historical evidence does not establish native +hook fit for a newer client. Runtime metadata checks reject incompatible managed +layouts; they do not validate native method extent. + +Current Mac build, native-fit and exact-artifact runtime results must be recorded +separately for each tested architecture and game version. + +## Focused smoke test + +1. Set `[control] queue_enabled = true` and `kirshara_fixes = true`. Leave + `[patches] actionqueuerecoveryhooks`, `thinqueueprotectionhooks` and + `queueaddressguardhooks` enabled; restart after changing hook switches. +2. Confirm startup logs report `[FasterQueueRecovery] ready=true`, + `[ThinQueueProtection] ready=true` and `[QueueAddressGuard] ready=true`. + Preserve any unavailable or hook-install failure messages. +3. Queue same-system hostiles on ship A. Move or recall ship B from another + system; A's queue should survive and continue normally. +4. Recall A itself, then separately clear its queue manually. Both should clear. +5. Let another player remove A's queued head before engagement. Check progression + to the next eligible target, then repeat with respawns and two ships. Watch for + duplicate engagements, stalled courses, unexpected clearing or crashes. +6. Compare `kirshara_fixes` off/on. Without the settings UI, edit the existing TOML + key and restart. Record commit, artifact hash, architecture, game version, + exact steps and logs. Disable an affected hook switch and restart if needed. diff --git a/mods/src/patches/parts/action_queue.cc b/mods/src/patches/parts/action_queue.cc index 6d1b9090..86af2e99 100644 --- a/mods/src/patches/parts/action_queue.cc +++ b/mods/src/patches/parts/action_queue.cc @@ -1,9 +1,9 @@ #include "action_queue.h" #include -// The callback ABI below is Windows x64. Validate its contract against the running client. -#if defined(_WIN32) && defined(_M_X64) -#include +// Use the host ABI for the 24-byte value-type callback on Windows and both Mac architectures. +// Validate the managed layout before installing. +#if (defined(_WIN32) && defined(_M_X64)) || (defined(__APPLE__) && (defined(__arm64__) || defined(__x86_64__))) #include #include #include diff --git a/mods/src/patches/parts/thin_queue_protection.cc b/mods/src/patches/parts/thin_queue_protection.cc index 3fdfb095..3769fd7d 100644 --- a/mods/src/patches/parts/thin_queue_protection.cc +++ b/mods/src/patches/parts/thin_queue_protection.cc @@ -2,8 +2,8 @@ #include // Port of the active v2.1.0-guffa.10 guard, not the dormant completion repair. -// Windows x64 callback ABI is validated against running metadata; current native fit is recorded separately. -#if defined(_WIN32) && defined(_M_X64) +// Shared 64-bit managed layout; incompatible runtime contracts leave the feature unavailable. +#if (defined(_WIN32) && defined(_M_X64)) || (defined(__APPLE__) && (defined(__arm64__) || defined(__x86_64__))) #include #include #include