fix(ffi): replace removed std.atomic.Mutex with std.Thread.Mutex (#291)

## The failure

`Zig FFI Tests` has been failing on every PR:

```
src/catalogue.zig:16:22: error: root source file struct 'atomic' has no member named 'Mutex'
```

This was invisible until the repository's Actions policy was fixed — the
workflow
was `startup_failure`ing before any job ran, so the compile error never
surfaced.

## The cause

`std.atomic.Mutex` was removed from Zig's standard library. Nine files
in
`ffi/zig/src/` still carried a **byte-identical** hand-rolled wrapper
around it
(all nine hash to the same value — one template copied nine times):

```zig
const Mutex = struct {
    state: std.atomic.Mutex = .unlocked,
    pub fn lock(m: *Mutex) void {
        while (!m.state.tryLock()) std.atomic.spinLoopHint();
    }
    pub fn unlock(m: *Mutex) void { m.state.unlock(); }
};
```

## The fix

The wrapper's public surface — `lock()` / `unlock()`, instantiated as
`var mutex: Mutex = .{}` — is *already exactly* `std.Thread.Mutex`'s. So
the whole
struct collapses to a one-line alias, with **no call-site changes**:

```zig
const Mutex = std.Thread.Mutex;
```

Two things worth noting:

- **It's a behavioural improvement, not just a compile fix.** The
wrapper busy-waited
via `spinLoopHint`, burning a core under contention. `std.Thread.Mutex`
parks the
  waiting thread.
- **It converges on the in-tree norm.** 81 other files in this repo
already use
`std.Thread.Mutex` directly, so this removes a divergent copy rather
than adding a
  new pattern.

Files: `sla`, `catalogue`, `sdp`, `loader`, `verisimdb`, `guardian`,
`community`,
`federation`, `coprocessor`.

## Verification

Run locally against the **exact CI pin** (zig 0.15.2, per
`zig-test.yml`) — all four
targets the workflow runs:

| Target | Result |
|---|---|
| `zig build test` | **PASS** — 13 + 3 tests passed |
| `zig build readiness` | **PASS** — 28/28 tests passed |
| `zig build lib` | **PASS** — 2/2 steps |
| `zig build bench` | **PASS** — 3/3 steps |

Zero remaining code references to `std.atomic.Mutex` /
`std.atomic.spinLoopHint`.

## Note

`.tool-versions` pins zig `0.15.1` while `zig-test.yml` uses `0.15.2`.
Not changed
here, but the two should be reconciled.

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: hyperpolymath

ffi/zig/src/catalogue.zig

@@ -12,15 +12,12 @@
 
 const std = @import("std");
 
-const Mutex = struct {
-    state: std.atomic.Mutex = .unlocked,
-    pub fn lock(m: *Mutex) void {
-        while (!m.state.tryLock()) std.atomic.spinLoopHint();
-    }
-    pub fn unlock(m: *Mutex) void {
-        m.state.unlock();
-    }
-};
+// `std.atomic.Mutex` was removed from the standard library; its replacement is
+// `std.Thread.Mutex`, whose lock/unlock surface is identical to the hand-rolled
+// wrapper this replaces. The wrapper also busy-waited via `spinLoopHint`, burning
+// a core under contention; `std.Thread.Mutex` parks the thread instead. 81 other
+// files in this repo already use this form.
+const Mutex = std.Thread.Mutex;
 
 // ═══════════════════════════════════════════════════════════════════════
 // Types (must match src/abi/Catalogue.idr encodings)

ffi/zig/src/community.zig

@@ -15,15 +15,12 @@
 
 const std = @import("std");
 
-const Mutex = struct {
-    state: std.atomic.Mutex = .unlocked,
-    pub fn lock(m: *Mutex) void {
-        while (!m.state.tryLock()) std.atomic.spinLoopHint();
-    }
-    pub fn unlock(m: *Mutex) void {
-        m.state.unlock();
-    }
-};
+// `std.atomic.Mutex` was removed from the standard library; its replacement is
+// `std.Thread.Mutex`, whose lock/unlock surface is identical to the hand-rolled
+// wrapper this replaces. The wrapper also busy-waited via `spinLoopHint`, burning
+// a core under contention; `std.Thread.Mutex` parks the thread instead. 81 other
+// files in this repo already use this form.
+const Mutex = std.Thread.Mutex;
 
 // ═══════════════════════════════════════════════════════════════════════
 // Constants

ffi/zig/src/coprocessor.zig

@@ -20,15 +20,12 @@
 
 const std = @import("std");
 
-const Mutex = struct {
-    state: std.atomic.Mutex = .unlocked,
-    pub fn lock(m: *Mutex) void {
-        while (!m.state.tryLock()) std.atomic.spinLoopHint();
-    }
-    pub fn unlock(m: *Mutex) void {
-        m.state.unlock();
-    }
-};
+// `std.atomic.Mutex` was removed from the standard library; its replacement is
+// `std.Thread.Mutex`, whose lock/unlock surface is identical to the hand-rolled
+// wrapper this replaces. The wrapper also busy-waited via `spinLoopHint`, burning
+// a core under contention; `std.Thread.Mutex` parks the thread instead. 81 other
+// files in this repo already use this form.
+const Mutex = std.Thread.Mutex;
 
 extern fn getenv(name: [*:0]const u8) ?[*:0]const u8;
 

ffi/zig/src/federation.zig

@@ -20,15 +20,12 @@
 
 const std = @import("std");
 
-const Mutex = struct {
-    state: std.atomic.Mutex = .unlocked,
-    pub fn lock(m: *Mutex) void {
-        while (!m.state.tryLock()) std.atomic.spinLoopHint();
-    }
-    pub fn unlock(m: *Mutex) void {
-        m.state.unlock();
-    }
-};
+// `std.atomic.Mutex` was removed from the standard library; its replacement is
+// `std.Thread.Mutex`, whose lock/unlock surface is identical to the hand-rolled
+// wrapper this replaces. The wrapper also busy-waited via `spinLoopHint`, burning
+// a core under contention; `std.Thread.Mutex` parks the thread instead. 81 other
+// files in this repo already use this form.
+const Mutex = std.Thread.Mutex;
 
 // ═══════════════════════════════════════════════════════════════════════
 // Proven-hardened: Circuit breaker, retry, and rate limiter state

ffi/zig/src/guardian.zig

@@ -22,15 +22,12 @@
 
 const std = @import("std");
 
-const Mutex = struct {
-    state: std.atomic.Mutex = .unlocked,
-    pub fn lock(m: *Mutex) void {
-        while (!m.state.tryLock()) std.atomic.spinLoopHint();
-    }
-    pub fn unlock(m: *Mutex) void {
-        m.state.unlock();
-    }
-};
+// `std.atomic.Mutex` was removed from the standard library; its replacement is
+// `std.Thread.Mutex`, whose lock/unlock surface is identical to the hand-rolled
+// wrapper this replaces. The wrapper also busy-waited via `spinLoopHint`, burning
+// a core under contention; `std.Thread.Mutex` parks the thread instead. 81 other
+// files in this repo already use this form.
+const Mutex = std.Thread.Mutex;
 
 // ═══════════════════════════════════════════════════════════════════════
 // Constants

ffi/zig/src/loader.zig

@@ -13,15 +13,12 @@
 
 const std = @import("std");
 
-const Mutex = struct {
-    state: std.atomic.Mutex = .unlocked,
-    pub fn lock(m: *Mutex) void {
-        while (!m.state.tryLock()) std.atomic.spinLoopHint();
-    }
-    pub fn unlock(m: *Mutex) void {
-        m.state.unlock();
-    }
-};
+// `std.atomic.Mutex` was removed from the standard library; its replacement is
+// `std.Thread.Mutex`, whose lock/unlock surface is identical to the hand-rolled
+// wrapper this replaces. The wrapper also busy-waited via `spinLoopHint`, burning
+// a core under contention; `std.Thread.Mutex` parks the thread instead. 81 other
+// files in this repo already use this form.
+const Mutex = std.Thread.Mutex;
 const crypto = std.crypto;
 const fs = std.fs;
 

ffi/zig/src/sdp.zig

@@ -16,15 +16,12 @@
 
 const std = @import("std");
 
-const Mutex = struct {
-    state: std.atomic.Mutex = .unlocked,
-    pub fn lock(m: *Mutex) void {
-        while (!m.state.tryLock()) std.atomic.spinLoopHint();
-    }
-    pub fn unlock(m: *Mutex) void {
-        m.state.unlock();
-    }
-};
+// `std.atomic.Mutex` was removed from the standard library; its replacement is
+// `std.Thread.Mutex`, whose lock/unlock surface is identical to the hand-rolled
+// wrapper this replaces. The wrapper also busy-waited via `spinLoopHint`, burning
+// a core under contention; `std.Thread.Mutex` parks the thread instead. 81 other
+// files in this repo already use this form.
+const Mutex = std.Thread.Mutex;
 
 // ═══════════════════════════════════════════════════════════════════════
 // Constants

ffi/zig/src/sla.zig

@@ -15,15 +15,12 @@
 
 const std = @import("std");
 
-const Mutex = struct {
-    state: std.atomic.Mutex = .unlocked,
-    pub fn lock(m: *Mutex) void {
-        while (!m.state.tryLock()) std.atomic.spinLoopHint();
-    }
-    pub fn unlock(m: *Mutex) void {
-        m.state.unlock();
-    }
-};
+// `std.atomic.Mutex` was removed from the standard library; its replacement is
+// `std.Thread.Mutex`, whose lock/unlock surface is identical to the hand-rolled
+// wrapper this replaces. The wrapper also busy-waited via `spinLoopHint`, burning
+// a core under contention; `std.Thread.Mutex` parks the thread instead. 81 other
+// files in this repo already use this form.
+const Mutex = std.Thread.Mutex;
 
 // ═══════════════════════════════════════════════════════════════════════
 // Constants

ffi/zig/src/verisimdb.zig

@@ -16,15 +16,12 @@
 
 const std = @import("std");
 
-const Mutex = struct {
-    state: std.atomic.Mutex = .unlocked,
-    pub fn lock(m: *Mutex) void {
-        while (!m.state.tryLock()) std.atomic.spinLoopHint();
-    }
-    pub fn unlock(m: *Mutex) void {
-        m.state.unlock();
-    }
-};
+// `std.atomic.Mutex` was removed from the standard library; its replacement is
+// `std.Thread.Mutex`, whose lock/unlock surface is identical to the hand-rolled
+// wrapper this replaces. The wrapper also busy-waited via `spinLoopHint`, burning
+// a core under contention; `std.Thread.Mutex` parks the thread instead. 81 other
+// files in this repo already use this form.
+const Mutex = std.Thread.Mutex;
 const Allocator = std.mem.Allocator;
 
 // ═══════════════════════════════════════════════════════════════════════