probe: wasm32 byte-reproducibility across machines (#218)

Author: wormeyman

.github/workflows/wasm-repro.yml

@@ -0,0 +1,40 @@
+# THROWAWAY. Issue #218 only. This file must never reach `main`.
+#
+# The question: does the pinned toolchain produce a byte-identical
+# wasm32-unknown-unknown module on an ubuntu runner and on a macOS dev machine?
+# The answer decides whether the `rust` job can assert byte identity for the
+# committed engine.wasm, or has to fall back to rebuild-and-run-the-tests.
+#
+# `on: push` restricted to this branch, NOT `workflow_dispatch`: GitHub only
+# makes a workflow_dispatch workflow triggerable once the file exists on the
+# DEFAULT branch, so dispatching one that lives only here fails with "workflow
+# does not have 'workflow_dispatch' trigger". Pushing the branch has no such
+# requirement.
+name: wasm-repro
+
+on:
+  push:
+    branches: [probe/wasm-reproducibility]
+
+permissions:
+  contents: read
+
+jobs:
+  hash:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - name: Toolchain
+        run: |
+          rustup toolchain install 1.97.1 --profile minimal
+          rustup target add wasm32-unknown-unknown --toolchain 1.97.1
+          rustup run 1.97.1 rustc --version --verbose
+      - name: Build and hash
+        working-directory: crates-probe
+        run: |
+          rustup run 1.97.1 cargo build --locked --release \
+            --target wasm32-unknown-unknown -p fmw-wasm
+          F=target/wasm32-unknown-unknown/release/fmw_wasm.wasm
+          echo "PROBE_BYTES=$(wc -c < "$F")"
+          echo "PROBE_SHA=$(sha256sum "$F" | cut -d' ' -f1)"

crates-probe/Cargo.lock

@@ -0,0 +1,9 @@
+[workspace]
+resolver = "2"
+members = ["crates/fmw-noise", "crates/fmw-wasm"]
+[profile.release]
+opt-level = 3
+lto = true
+codegen-units = 1
+panic = "abort"
+strip = true

crates-probe/Cargo.toml

@@ -0,0 +1,6 @@
+[package]
+name = "fmw-noise"
+version = "0.0.0"
+edition = "2021"
+publish = false
+[dependencies]

crates-probe/crates/fmw-noise/Cargo.toml

@@ -0,0 +1,43 @@
+const FNV_OFFSET_BASIS: u64 = 0xcbf2_9ce4_8422_2325;
+const FNV_PRIME: u64 = 0x0000_0100_0000_01b3;
+
+#[must_use]
+pub fn fnv1a64(bytes: &[u8]) -> u64 {
+    let mut hash = FNV_OFFSET_BASIS;
+    for &byte in bytes {
+        hash ^= u64::from(byte);
+        hash = hash.wrapping_mul(FNV_PRIME);
+    }
+    hash
+}
+
+#[must_use]
+pub fn fold_f64(acc: u64, value: f64) -> u64 {
+    let mut hash = if acc == 0 { FNV_OFFSET_BASIS } else { acc };
+    for &byte in &value.to_bits().to_le_bytes() {
+        hash ^= u64::from(byte);
+        hash = hash.wrapping_mul(FNV_PRIME);
+    }
+    hash
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    #[test]
+    fn matches_the_published_fnv1a64_vectors() {
+        assert_eq!(fnv1a64(b""), 0xcbf2_9ce4_8422_2325);
+        assert_eq!(fnv1a64(b"a"), 0xaf63_dc4c_8601_ec8c);
+        assert_eq!(fnv1a64(b"foobar"), 0x8594_4171_f739_67e8);
+    }
+    #[test]
+    fn the_fold_is_order_sensitive() {
+        let a = fold_f64(fold_f64(0, 1.5), 2.5);
+        let b = fold_f64(fold_f64(0, 2.5), 1.5);
+        assert_ne!(a, b, "fold must depend on order; an XOR fold would not");
+    }
+    #[test]
+    fn the_fold_depends_on_the_value() {
+        assert_ne!(fold_f64(0, 1.5), fold_f64(0, 1.5000000000000002));
+    }
+}

crates-probe/crates/fmw-noise/src/checksum.rs

@@ -0,0 +1,2 @@
+#![allow(clippy::suboptimal_flops)]
+pub mod checksum;

crates-probe/crates/fmw-noise/src/lib.rs

@@ -0,0 +1,9 @@
+[package]
+name = "fmw-wasm"
+version = "0.0.0"
+edition = "2021"
+publish = false
+[lib]
+crate-type = ["cdylib"]
+[dependencies]
+fmw-noise = { path = "../fmw-noise" }

crates-probe/crates/fmw-wasm/Cargo.toml

@@ -0,0 +1,39 @@
+//! The WASM boundary, and nothing else. No logic lives here.
+
+use fmw_noise::checksum;
+
+/// A fixed scratch region the caller writes into.
+///
+/// No allocator, and that is deliberate rather than minimal: the module's
+/// lifecycle is "instantiate once per worker, fill a buffer per call", so an
+/// allocator would exist only to hand back memory nothing ever frees. Phase 3
+/// replaces this with an explicitly reused render buffer of the same shape.
+const SCRATCH_BYTES: usize = 1 << 16;
+static mut SCRATCH: [u8; SCRATCH_BYTES] = [0; SCRATCH_BYTES];
+
+#[unsafe(no_mangle)]
+pub extern "C" fn scratch_ptr() -> u32 {
+    core::ptr::addr_of!(SCRATCH) as u32
+}
+
+#[unsafe(no_mangle)]
+pub extern "C" fn scratch_len() -> u32 {
+    SCRATCH_BYTES as u32
+}
+
+/// FNV-1a 64 over `len` bytes at the start of the scratch region.
+///
+/// # Safety
+/// The caller must have written `len <= scratch_len()` bytes there.
+#[unsafe(no_mangle)]
+pub extern "C" fn fnv1a64(len: u32) -> u64 {
+    let bytes = unsafe {
+        core::slice::from_raw_parts(core::ptr::addr_of!(SCRATCH).cast::<u8>(), len as usize)
+    };
+    checksum::fnv1a64(bytes)
+}
+
+#[unsafe(no_mangle)]
+pub extern "C" fn fold_f64(acc: u64, value: f64) -> u64 {
+    checksum::fold_f64(acc, value)
+}

crates-probe/crates/fmw-wasm/src/lib.rs

@@ -0,0 +1,5 @@
+[toolchain]
+channel = "1.97.1"
+components = ["rustfmt", "clippy"]
+targets = ["wasm32-unknown-unknown"]
+profile = "minimal"