SNIFs verisim WASM bridge — single boundary for BEAM-side cross-language access

[hyperpolymath]

Background

Architectural plan agreed 2026-06-01: BEAM-side cross-language access to VeriSimDB (Gleam, Erlang, future LFE / Hamler / Akula) flows through the SNIFs WASM bridge rather than per-language SDKs. Closes the "do we ship a Gleam SDK?" question with a single principled answer: no, ship a SNIF-compatible WASM module that any BEAM language can call via wasmex.

Context: SNIFs = hyperpolymath/snifs — Safe NIFs via WebAssembly Sandboxing. WASM guest faults become BEAM error tuples instead of killing the whole VM. Native code (Zig today; the verisim core conceptually) compiles to WASM and loads through wasmex. Crash-isolated NIF semantics for free.

Shape of the bridge

Two delivery options, pick when ready:

Option A — verisim-core compiled to WASM directly.

• Carve out the rust-core API surface that doesn't need tokio (or replace tokio with tokio::runtime::Runtime::new() in the host-driver), compile to wasm32-unknown-unknown or wasm32-wasi.
• Publish a verisim.wasm artefact per release.
• SNIF wrapper exposes the typed API as BEAM NIFs; any BEAM language (Elixir, Gleam, Erlang, LFE) calls them.

Option B — verisim-api as the WASM target.

• Compile the HTTP/JSON API gateway to WASM; SNIF wraps that and serves it locally.
• Less invasive (no need to refactor for async-WASM), but adds JSON encode/decode hop per call.

Recommendation: Option A long-term, B as the v0 if it ships faster.

What this unblocks / replaces

• Gleam SDK (now removed in PR chore(rot): flush silent failures + drop Gleam SDK #85) — replaced by Gleam ↔ wasmex ↔ verisim.wasm
• Future Erlang / LFE / Hamler / Akula support — free once the WASM module ships
• Reduces SDK matrix tracking burden from 6 → 5 (Rust, Elixir, ReScript, Julia, Zig stay first-class)
• Aligns with the vcl-ut Tier-1 recompute-PCC pattern (fail-closed WASM module the consumer re-runs)

Dependencies / sequence

1. Decide between Option A and Option B above (owner)
2. Spike: minimal SNIF integration with a stub verisim WASM (1-2 days)
3. Define which rust-core API surface goes through WASM vs stays Rust-native (architectural — likely OctadStore, DriftCalculator, Normalizer, but NOT planner/optimizer or async federation)
4. Wire vcl-ut wire-codec into the WASM boundary for query-shaped calls
5. Ship a single verisim.wasm per release; publish SNIF wrapper as a hex package
6. Document in docs/architecture/snifs-bridge.adoc (currently a planned doc)

Related

• PR chore(rot): flush silent failures + drop Gleam SDK #85 drops Gleam SDK (this issue absorbs the use-case)
• Cross-repo synthesis: vcl-ut + kategoria + echo-types + tropical-resource-typing → VeriSimDB #84 cross-repo synthesis (mentions SNIFs in the boundary discussion)
• hyperpolymath/snifs upstream
• vcl-ut src/interface/recompute-wasm/ — Tier-1 fail-closed WASM pattern; share infrastructure where it fits

[hyperpolymath]

Blocking-decision note 2026-07-21 — this issue gates #61, and #61 should not start first

Flagging the coupling explicitly, because the sequencing risk is real and one-directional.

Option A (verisim-core compiled to WASM, SNIF-wrapped) would subsume the hand-written verisim-nif that #61 specifies. #61 is scoped at ~3 person-weeks: real query execution against octad-store, a structured error model across the NIF boundary, host-side timeout enforcement, a documented contract for the wasm caller. Under Option A most of that is delivered by the SNIF wrapper rather than by hand-written Rustler NIFs — crash isolation and BEAM error tuples come from the WASM sandbox for free, which is precisely the "no panics into BEAM" acceptance criterion in #61.

So building #61 before this issue is ruled on risks ~3 person-weeks of throwaway. The dependency does not run the other way: ruling here costs nothing and unblocks both.

Recommendation, unchanged from the issue body: A long-term, B as v0 if it ships faster. Two observations that firm that up:

• Option B's cost is a JSON encode/decode hop per call, which is precisely the overhead the NIF path exists to avoid — so B is a stopgap, not a destination.
• verisim-graph already demonstrates the feature-gated-backend pattern (default = [], oxigraph-backend opt-in) that Option A's "which surface goes through WASM" step needs. Step 3 has an in-repo precedent to copy.

Current state of the thing being replaced: verisim-nif no longer fakes success. Every entry point returns not_implemented(), and the source records why — delete_octad "previously returned {"status":"deleted"} without deleting anything". The silent-data-loss hazard is gone, so there is no correctness pressure forcing a rushed #61. The decision can be taken on its merits.

Ask: a ruling on A vs B. Everything downstream is sequenced behind it.