From 1678da16c562ccad24e0de6d22b748abbceaecf6 Mon Sep 17 00:00:00 2001
From: hyperpolymath <6759885+hyperpolymath@users.noreply.github.com>
Date: Tue, 19 May 2026 13:08:13 +0100
Subject: [PATCH] fix(snif): make Wasmex an optional, absence-guarded
 dependency
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Burble.Coprocessor.SNIFBackend called Wasmex.start_link/1 and
Wasmex.call_function/3 directly, and available?/0 only checked the .wasm
file existed — not whether the (undeclared) :wasmex runtime was loadable.
Result: a compile-time "Wasmex is undefined" warning, and SNIF kernels
routing into Wasmex at runtime only to fail by rescued exception instead
of cleanly degrading.

Apply the established :quicer / Burble.Bolt.Quic pattern (ADR-0004):

* server/mix.exs — document :wasmex in the optional-NIF block (Rust/
  wasmtime toolchain; commented like quicer/elmdb).
* snif_backend.ex — `@wasmex Wasmex` alias; call via apply/3 (no direct
  reference => no compile warning); available?/0 now also requires
  Code.ensure_loaded?(@wasmex) and the function exported, so every
  kernel transparently uses ZigBackend when Wasmex is absent.
* CHANGELOG — Fixed entry.

Verified: `mix compile --force` emits no Wasmex warning and no new
unused/undefined warnings in snif_backend.ex.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 CHANGELOG.md                                  |  3 +++
 server/lib/burble/coprocessor/snif_backend.ex | 14 +++++++++++---
 server/mix.exs                                |  4 ++++
 3 files changed, 18 insertions(+), 3 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 94d50b3..7fdcc4b 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -21,6 +21,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `prim__registerCallback` made module-private (unsafe boundary, awaits idris2#3182)
 - `docs/developer/wsl-mirrored-networking.adoc` rewritten — NAT + host forwarder is the recommended WSL2 Bolt path; mirrored networking demoted to last-resort (Win11 24H2/Insider `Wsl/Service/E_UNEXPECTED` instability)
 
+### Fixed
+- SNIF: `Burble.Coprocessor.SNIFBackend` no longer emits a compile warning for the optional `Wasmex` runtime and no longer mis-fails when it is absent — `Wasmex` is referenced via `apply/3` and `available?/0` now gates on it loadable, so kernels degrade cleanly to `ZigBackend` (mirrors the `:quicer` pattern, ADR-0004)
+
 ### Removed
 - TODO.md (superseded by CLAUDE-WORK.md — 0 TODOs remain in codebase)
 
diff --git a/server/lib/burble/coprocessor/snif_backend.ex b/server/lib/burble/coprocessor/snif_backend.ex
index 13c0ea1..f2a513f 100644
--- a/server/lib/burble/coprocessor/snif_backend.ex
+++ b/server/lib/burble/coprocessor/snif_backend.ex
@@ -157,9 +157,17 @@ defmodule Burble.Coprocessor.SNIFBackend do
   3. Verify configuration in `config/runtime.exs`
   4. Check `BURBLE_SNIF_PATH` environment variable
   """
+  # Optional WASM runtime. Referenced via apply/3 (see call_snif_module/3)
+  # so the compiler does not warn when :wasmex is absent at build time —
+  # mirrors the Burble.Bolt.Quic / :quicer pattern (ADR-0004). When absent,
+  # available?/0 is false so every kernel transparently uses ZigBackend.
+  @wasmex Wasmex
+
   @impl true
   def available? do
-    File.exists?(@snif_path)
+    File.exists?(@snif_path) and
+      Code.ensure_loaded?(@wasmex) and
+      function_exported?(@wasmex, :start_link, 1)
   end
 
   # ---------------------------------------------------------------------------
@@ -512,9 +520,9 @@ defmodule Burble.Coprocessor.SNIFBackend do
   # `{:error, reason}` so the caller can fall back gracefully.
   defp call_snif_module(path, function, args) do
     try do
-      case Wasmex.start_link(%{bytes: File.read!(path)}) do
+      case apply(@wasmex, :start_link, [%{bytes: File.read!(path)}]) do
         {:ok, pid} ->
-          result = Wasmex.call_function(pid, function, args)
+          result = apply(@wasmex, :call_function, [pid, function, args])
           GenServer.stop(pid, :normal)
           result
         {:error, reason} -> {:error, {:wasm_load_failed, reason}}
diff --git a/server/mix.exs b/server/mix.exs
index 777f59f..14dd12b 100644
--- a/server/mix.exs
+++ b/server/mix.exs
@@ -196,10 +196,14 @@ defmodule Burble.MixProject do
       #   quicer  — needs msquic (Microsoft QUIC C library)
       #   elmdb   — links liberl_interface which was dropped in OTP 23+
       #   ex_lmdb — depends on elmdb
+      #   wasmex  — Rust NIF (wasmtime); needs a Rust toolchain. SNIF
+      #             (Burble.Coprocessor.SNIFBackend) transparently degrades
+      #             to ZigBackend when absent — available?/0 gates on it.
       #
       # {:quicer, github: "emqx/quic", tag: "0.2.15", submodules: true, optional: true},
       # {:elmdb, "~> 0.4", optional: true},
       # {:ex_lmdb, "~> 0.1", optional: true},
+      # {:wasmex, "~> 0.9", optional: true},
 
       # Media plane — ex_webrtc SFU (audio-only, Opus)
       {:ex_webrtc, "~> 0.16"},