@feltdb/core 0.8.4 → 0.8.5

package/dist/create/server-source/crates/feltdb/tests/state_diff_contract_conformance.rs

@@ -0,0 +1,1316 @@
+//! Conformance, determinism and capability proofs for the `feltdb.state.diff`
+//! deterministic contract.
+//!
+//! The second specimen of the pattern proved for `feltdb.trigger.match`:
+//!
+//! ```text
+//!     Contract semantics are authoritative.
+//!     Runtime implementation is replaceable.
+//!
+//!     NativeStateDiff(a, b) == WasmStateDiff(a, b)   for every fixture
+//! ```
+//!
+//! The corpus in `tests/fixtures/state_diff_contract_corpus.json` is committed
+//! rather than generated, and carries the canonical output each case must
+//! produce. Three comparisons run over it:
+//!
+//! 1. native output == committed expectation (runs everywhere);
+//! 2. WASM output  == committed expectation (needs `wasm32-unknown-unknown`);
+//! 3. native output == WASM output, byte for byte.
+//!
+//! The first makes the suite meaningful where the WASM toolchain is absent: a
+//! change in the native diff's semantics is caught by the same bytes the WASM
+//! implementation was measured against.
+
+use feltdb::state_diff_contract::{
+    canonical_input_bytes, evaluate_canonical, StateDiffInput, STATE_DIFF_CONTRACT_ID,
+    STATE_DIFF_CONTRACT_VERSION,
+};
+use serde::Deserialize;
+use serde_json::Value;
+use std::path::{Path, PathBuf};
+use std::process::Command;
+use std::sync::OnceLock;
+
+// ---------------------------------------------------------------------------
+// Corpus
+// ---------------------------------------------------------------------------
+
+#[derive(Debug, Deserialize)]
+struct Corpus {
+    corpus_version: u32,
+    contract: String,
+    contract_version: u32,
+    #[allow(dead_code)]
+    about: String,
+    cases: Vec<Case>,
+}
+
+#[derive(Debug, Deserialize)]
+struct Case {
+    name: String,
+    #[allow(dead_code)]
+    why: String,
+    /// A well-formed contract input, canonically encoded by the harness.
+    #[serde(default)]
+    input: Option<StateDiffInput>,
+    /// Bytes fed to the contract verbatim, for non-canonical and malformed
+    /// encodings that a typed value cannot express.
+    #[serde(default)]
+    raw_input: Option<String>,
+    /// The canonical encoding of `input`, recorded so that every consumer of
+    /// the corpus presents the same bytes.
+    ///
+    /// A consumer in another language cannot always reproduce it: JavaScript
+    /// has one number type, so it cannot encode the difference between `42` and
+    /// `42.0` that this contract's value equality depends on.
+    #[serde(default)]
+    canonical_input: Option<String>,
+    /// The canonical output both implementations must produce.
+    #[serde(default)]
+    expected_output: Option<String>,
+}
+
+impl Case {
+    /// The exact bytes this case presents to a contract implementation.
+    fn bytes(&self) -> Vec<u8> {
+        match (&self.input, &self.raw_input) {
+            (Some(input), None) => canonical_input_bytes(input),
+            (None, Some(raw)) => raw.as_bytes().to_vec(),
+            _ => panic!(
+                "case {} must have exactly one of input/raw_input",
+                self.name
+            ),
+        }
+    }
+
+    fn expected(&self) -> &str {
+        self.expected_output.as_deref().unwrap_or_else(|| {
+            panic!(
+                "case {} has no expected_output; regenerate the corpus with \
+                 FELTDB_STATE_DIFF_CONTRACT_BLESS=1",
+                self.name
+            )
+        })
+    }
+}
+
+fn corpus_path() -> PathBuf {
+    Path::new(env!("CARGO_MANIFEST_DIR")).join("tests/fixtures/state_diff_contract_corpus.json")
+}
+
+fn corpus() -> &'static Corpus {
+    static CORPUS: OnceLock<Corpus> = OnceLock::new();
+    CORPUS.get_or_init(|| {
+        let bytes = std::fs::read(corpus_path()).expect("conformance corpus is committed");
+        serde_json::from_slice(&bytes).expect("conformance corpus is well formed")
+    })
+}
+
+#[test]
+fn corpus_addresses_this_contract_at_this_version() {
+    let corpus = corpus();
+    assert_eq!(corpus.corpus_version, 1);
+    assert_eq!(corpus.contract, STATE_DIFF_CONTRACT_ID);
+    assert_eq!(corpus.contract_version, STATE_DIFF_CONTRACT_VERSION);
+    assert!(
+        corpus.cases.len() >= 110,
+        "the corpus is the proof; it should not shrink silently"
+    );
+    let mut names: Vec<&str> = corpus.cases.iter().map(|case| case.name.as_str()).collect();
+    names.sort_unstable();
+    let unique = names.len();
+    names.dedup();
+    assert_eq!(unique, names.len(), "case names identify cases");
+}
+
+/// Every required category of behaviour is represented by at least one case.
+///
+/// A guard against the corpus quietly losing a dimension it was built to
+/// cover, not a substitute for reading it.
+#[test]
+fn corpus_covers_every_required_category() {
+    let names: Vec<&str> = corpus().cases.iter().map(|c| c.name.as_str()).collect();
+    for required in [
+        // basic
+        "identical_objects",
+        "both_empty_objects",
+        "empty_to_populated_object",
+        "populated_to_empty_object",
+        "single_scalar_replacement",
+        // object changes
+        "object_addition",
+        "object_removal",
+        "object_replacement",
+        "nested_addition",
+        "nested_removal",
+        "nested_replacement",
+        "multiple_independent_changes",
+        "deeply_nested_change",
+        "unusual_object_keys",
+        "unicode_keys_and_values",
+        // null and missing
+        "missing_to_value",
+        "value_to_missing",
+        "missing_to_null",
+        "null_to_missing",
+        "null_to_value",
+        "value_to_null",
+        // arrays
+        "empty_to_populated_array",
+        "array_append_one",
+        "array_remove_tail",
+        "array_index_replacement",
+        "array_multiple_index_changes",
+        "array_nested_change",
+        "array_to_object",
+        "object_to_array",
+        "array_reorder_is_positional",
+        // numbers
+        "integer_change",
+        "float_change",
+        "zero_to_positive",
+        "negative_zero_int_against_zero",
+        "large_unsigned",
+        "float_extremes",
+        // structural
+        "many_members",
+        "repeated_nested_modifications",
+        "changes_at_related_paths",
+        "mixed_container_shapes_at_depth",
+        // invalid
+        "malformed_not_json",
+        "malformed_duplicate_envelope_member",
+        "malformed_leading_zero_number",
+        "malformed_truncated_object",
+    ] {
+        assert!(
+            names.contains(&required),
+            "corpus lost coverage: {required}"
+        );
+    }
+}
+
+/// The committed canonical bytes are what this crate's encoder produces.
+///
+/// Consumers outside Rust read `canonical_input` rather than re-canonicalizing,
+/// so this is the check that keeps those bytes honest: if canonicalization
+/// changed, every other reader of the corpus would silently be testing an
+/// encoding FeltDB no longer emits.
+#[test]
+fn committed_canonical_bytes_match_the_encoder() {
+    for case in &corpus().cases {
+        match (&case.input, &case.raw_input) {
+            (Some(input), None) => assert_eq!(
+                case.canonical_input.as_deref(),
+                Some(
+                    String::from_utf8(canonical_input_bytes(input))
+                        .unwrap()
+                        .as_str()
+                ),
+                "{} has a stale canonical_input",
+                case.name
+            ),
+            (None, Some(_)) => assert!(
+                case.canonical_input.is_none(),
+                "{} is a raw case and must not also record canonical_input",
+                case.name
+            ),
+            _ => panic!(
+                "case {} must have exactly one of input/raw_input",
+                case.name
+            ),
+        }
+    }
+}
+
+// ---------------------------------------------------------------------------
+// WASM host
+// ---------------------------------------------------------------------------
+
+const WASM_CRATE: &str = "crates/feltdb-state-diff-contract-wasm";
+const WASM_ARTIFACT: &str =
+    "target/wasm32-unknown-unknown/release/feltdb_state_diff_contract_wasm.wasm";
+
+fn repository_root() -> &'static Path {
+    Path::new(env!("CARGO_MANIFEST_DIR"))
+        .parent()
+        .and_then(Path::parent)
+        .expect("the crate lives at <root>/crates/feltdb")
+}
+
+/// Whether this machine can compile the contract to WebAssembly at all.
+fn wasm_target_installed() -> bool {
+    Command::new("rustc")
+        .args([
+            "--print",
+            "target-libdir",
+            "--target",
+            "wasm32-unknown-unknown",
+        ])
+        .output()
+        .is_ok_and(|output| output.status.success())
+}
+
+/// Compiles a WASM contract crate and returns the module bytes.
+///
+/// A build failure is a defect and panics. A missing `wasm32-unknown-unknown`
+/// target is an environment fact, reported by the caller as a skip.
+fn build_module(manifest_dir: &Path) -> Vec<u8> {
+    let output = Command::new(std::env::var("CARGO").unwrap_or_else(|_| "cargo".into()))
+        .args(["build", "--release", "--target", "wasm32-unknown-unknown"])
+        .current_dir(manifest_dir)
+        // The contract crate is its own workspace; inheriting the outer
+        // build's target directory or flags would defeat that.
+        .env_remove("CARGO_TARGET_DIR")
+        .env_remove("RUSTFLAGS")
+        .output()
+        .expect("cargo is runnable");
+    assert!(
+        output.status.success(),
+        "building the WASM contract at {} failed:\n{}",
+        manifest_dir.display(),
+        String::from_utf8_lossy(&output.stderr)
+    );
+    std::fs::read(manifest_dir.join(WASM_ARTIFACT)).expect("the build emits one module")
+}
+
+/// The committed WASM contract, compiled once for the whole suite.
+fn contract_module() -> Option<&'static [u8]> {
+    static MODULE: OnceLock<Option<Vec<u8>>> = OnceLock::new();
+    MODULE
+        .get_or_init(|| {
+            if let Ok(path) = std::env::var("FELTDB_STATE_DIFF_CONTRACT_WASM") {
+                return Some(
+                    std::fs::read(path).expect("FELTDB_STATE_DIFF_CONTRACT_WASM is readable"),
+                );
+            }
+            if !wasm_target_installed() {
+                return None;
+            }
+            Some(build_module(&repository_root().join(WASM_CRATE)))
+        })
+        .as_deref()
+}
+
+/// Announces a skip loudly, so an absent toolchain is never a silent pass.
+fn skipped(test: &str) {
+    eprintln!(
+        "SKIPPED {test}: the wasm32-unknown-unknown target is not installed, so the WASM \
+         contract implementation could not be built. Native conformance against the committed \
+         expectations still ran. Install the target, or set FELTDB_STATE_DIFF_CONTRACT_WASM to a \
+         prebuilt module, to execute the cross-runtime proof."
+    );
+}
+
+/// One instantiation of the WASM contract.
+///
+/// The linker is empty and stays empty: the module declares no imports, so
+/// there is nothing to satisfy and nothing to grant.
+struct WasmContract {
+    store: wasmi::Store<()>,
+    memory: wasmi::Memory,
+    alloc: wasmi::TypedFunc<u32, u32>,
+    evaluate: wasmi::TypedFunc<(u32, u32), u64>,
+    free: wasmi::TypedFunc<(u32, u32), ()>,
+}
+
+impl WasmContract {
+    fn instantiate(bytes: &[u8]) -> Self {
+        let engine = wasmi::Engine::default();
+        let module = wasmi::Module::new(&engine, bytes).expect("the module validates");
+        let mut store = wasmi::Store::new(&engine, ());
+        let instance = wasmi::Linker::<()>::new(&engine)
+            .instantiate_and_start(&mut store, &module)
+            .expect("an empty linker satisfies a module with no imports");
+        Self {
+            memory: instance
+                .get_memory(&store, "memory")
+                .expect("the module exports its memory"),
+            alloc: instance
+                .get_typed_func(&store, "contract_alloc")
+                .expect("contract_alloc"),
+            evaluate: instance
+                .get_typed_func(&store, "contract_evaluate")
+                .expect("contract_evaluate"),
+            free: instance
+                .get_typed_func(&store, "contract_free")
+                .expect("contract_free"),
+            store,
+        }
+    }
+
+    fn version(bytes: &[u8]) -> u32 {
+        let engine = wasmi::Engine::default();
+        let module = wasmi::Module::new(&engine, bytes).unwrap();
+        let mut store = wasmi::Store::new(&engine, ());
+        let instance = wasmi::Linker::<()>::new(&engine)
+            .instantiate_and_start(&mut store, &module)
+            .unwrap();
+        instance
+            .get_typed_func::<(), u32>(&store, "contract_version")
+            .expect("contract_version")
+            .call(&mut store, ())
+            .expect("contract_version is total")
+    }
+
+    fn evaluate(&mut self, input: &[u8]) -> Vec<u8> {
+        let len = input.len() as u32;
+        let ptr = self.alloc.call(&mut self.store, len).expect("allocation");
+        self.memory
+            .write(&mut self.store, ptr as usize, input)
+            .expect("input fits in linear memory");
+        let packed = self
+            .evaluate
+            .call(&mut self.store, (ptr, len))
+            .expect("the contract never traps on any input");
+        let out_ptr = (packed >> 32) as usize;
+        let out_len = (packed & 0xffff_ffff) as usize;
+        let mut output = vec![0u8; out_len];
+        self.memory
+            .read(&self.store, out_ptr, &mut output)
+            .expect("the output buffer is inside linear memory");
+        self.free.call(&mut self.store, (ptr, len)).expect("free");
+        self.free
+            .call(&mut self.store, (out_ptr as u32, out_len as u32))
+            .expect("free");
+        output
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Conformance
+// ---------------------------------------------------------------------------
+
+/// Native evaluation reproduces the committed canonical output for every case.
+#[test]
+fn native_matches_the_committed_expectations() {
+    let mut divergent = Vec::new();
+    for case in &corpus().cases {
+        let produced = String::from_utf8(evaluate_canonical(&case.bytes())).unwrap();
+        if produced != case.expected() {
+            divergent.push(format!(
+                "{}\n  expected: {}\n  native:   {}",
+                case.name,
+                case.expected(),
+                produced
+            ));
+        }
+    }
+    assert!(
+        divergent.is_empty(),
+        "native contract diverged from the committed expectations:\n{}",
+        divergent.join("\n")
+    );
+}
+
+/// The proof: one corpus, two implementations, byte-identical canonical output.
+#[test]
+fn native_and_wasm_agree_on_every_fixture() {
+    let Some(bytes) = contract_module() else {
+        return skipped("native_and_wasm_agree_on_every_fixture");
+    };
+    let mut wasm = WasmContract::instantiate(bytes);
+
+    println!(
+        "{:<48} {:<9} {:<9} {}",
+        "fixture", "native", "wasm", "equal"
+    );
+    let mut divergent = Vec::new();
+    for case in &corpus().cases {
+        let input = case.bytes();
+        let native = evaluate_canonical(&input);
+        let produced = wasm.evaluate(&input);
+        let equal = native == produced;
+        println!(
+            "{:<48} {:<9} {:<9} {}",
+            case.name,
+            summarize(&native),
+            summarize(&produced),
+            if equal { "yes" } else { "NO" }
+        );
+        if !equal {
+            divergent.push(format!(
+                "{}\n  input:  {}\n  native: {}\n  wasm:   {}",
+                case.name,
+                String::from_utf8_lossy(&input),
+                String::from_utf8_lossy(&native),
+                String::from_utf8_lossy(&produced)
+            ));
+        }
+    }
+    assert!(
+        divergent.is_empty(),
+        "native and WASM contract implementations diverged:\n{}",
+        divergent.join("\n")
+    );
+}
+
+/// The WASM implementation reproduces the committed canonical output too.
+///
+/// Separate from the pairwise comparison on purpose: two implementations can
+/// agree with each other while both having moved.
+#[test]
+fn wasm_matches_the_committed_expectations() {
+    let Some(bytes) = contract_module() else {
+        return skipped("wasm_matches_the_committed_expectations");
+    };
+    let mut wasm = WasmContract::instantiate(bytes);
+    for case in &corpus().cases {
+        assert_eq!(
+            String::from_utf8(wasm.evaluate(&case.bytes())).unwrap(),
+            case.expected(),
+            "WASM contract diverged from the committed expectation for {}",
+            case.name
+        );
+    }
+}
+
+/// Both implementations answer for the same contract at the same version.
+#[test]
+fn both_implementations_declare_the_same_contract_version() {
+    let Some(bytes) = contract_module() else {
+        return skipped("both_implementations_declare_the_same_contract_version");
+    };
+    assert_eq!(WasmContract::version(bytes), STATE_DIFF_CONTRACT_VERSION);
+    for case in &corpus().cases {
+        let output: Value = serde_json::from_slice(&evaluate_canonical(&case.bytes())).unwrap();
+        assert_eq!(output["contract"], STATE_DIFF_CONTRACT_ID);
+        assert_eq!(output["version"], STATE_DIFF_CONTRACT_VERSION);
+    }
+}
+
+/// The native adapter adds nothing to the existing implementation.
+///
+/// The contract must be the diff FeltDB already computes, not a second one that
+/// happens to agree. This runs both entry points over the whole corpus.
+#[test]
+fn the_contract_is_the_existing_semantic_diff() {
+    use feltdb::state_diff_contract::diff_states;
+    use feltdb::state_model::SemanticDiff;
+
+    let mut checked = 0;
+    for case in &corpus().cases {
+        let Some(input) = case.input.as_ref() else {
+            continue;
+        };
+        let through_contract = diff_states(&input.state_a, &input.state_b);
+        let direct = SemanticDiff::compute(&input.state_a, &input.state_b);
+        assert_eq!(
+            serde_json::to_string(&through_contract).unwrap(),
+            serde_json::to_string(&direct).unwrap(),
+            "the contract adapter changed the result for {}",
+            case.name
+        );
+        checked += 1;
+    }
+    assert!(checked > 70, "most of the corpus is typed input");
+}
+
+/// A short rendering of an output, for the printed conformance table.
+fn summarize(output: &[u8]) -> String {
+    let parsed: Value = match serde_json::from_slice(output) {
+        Ok(value) => value,
+        Err(_) => return "?".into(),
+    };
+    match parsed["diff"]["changes"].as_array() {
+        Some(changes) => format!("{} chg", changes.len()),
+        None => "error".into(),
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Float rendering
+// ---------------------------------------------------------------------------
+
+/// The WASM float writer reproduces `serde_json`'s, over far more values than
+/// the corpus can hold.
+///
+/// This is the riskiest part of the second implementation. The contract's
+/// output embeds whole input values, so the WASM module has to render doubles
+/// exactly as `ryu` does — and neither Rust's `Display` nor its `Debug` will
+/// do it: they disagree with `ryu` on presentation (`1e16` against `1e+16`)
+/// and, on a fraction of values, on which shortest representation to pick.
+///
+/// The sample is restricted to doubles `serde_json` parses back from its own
+/// output, for the reason
+/// [`serde_json_does_not_round_trip_every_double`] records: outside that set
+/// the two implementations disagree about which double the bytes denote,
+/// before any rendering happens, and this test would be measuring that instead.
+///
+/// One diff carries the whole array as a single changed value, so this drives
+/// the real module over the whole sample in a handful of calls.
+#[test]
+fn wasm_renders_floats_exactly_as_serde_json_does() {
+    let Some(bytes) = contract_module() else {
+        return skipped("wasm_renders_floats_exactly_as_serde_json_does");
+    };
+    let mut wasm = WasmContract::instantiate(bytes);
+
+    let mut sample: Vec<f64> = vec![
+        0.0,
+        -0.0,
+        1.0,
+        -1.0,
+        100.0,
+        0.5,
+        0.125,
+        3.141592653589793,
+        2.718281828459045,
+        1e15,
+        1e16,
+        1e17,
+        1e21,
+        1e100,
+        1e308,
+        1e-1,
+        1e-4,
+        1e-5,
+        1e-6,
+        1e-7,
+        1e-100,
+        5e-324,
+        f64::MAX,
+        f64::MIN,
+        f64::MIN_POSITIVE,
+        0.1,
+        0.2,
+        0.30000000000000004,
+        9007199254740992.0,
+    ];
+    // A deterministic sweep over bit patterns, and over decimals of the kind
+    // records actually hold.
+    let mut seed: u64 = 0x243F6A8885A308D3;
+    for _ in 0..12_000 {
+        seed = seed
+            .wrapping_mul(6364136223846793005)
+            .wrapping_add(1442695040888963407);
+        let value = f64::from_bits(seed);
+        if value.is_finite() {
+            sample.push(value);
+        }
+    }
+    for step in -6_000i64..6_000 {
+        sample.push(step as f64 / 1000.0);
+    }
+    let offered = sample.len();
+    sample.retain(|value| serde_json_round_trips(*value));
+    let checked = sample.len();
+    assert!(
+        checked > 12_000,
+        "the sample should still be large after excluding what serde_json cannot round trip"
+    );
+
+    for chunk in sample.chunks(4_000) {
+        let state_a = Value::Array(chunk.iter().map(|v| Value::from(*v)).collect());
+        let input = canonical_input_bytes(&StateDiffInput::new(state_a, Value::from(0)));
+        let native = evaluate_canonical(&input);
+        let produced = wasm.evaluate(&input);
+        if native != produced {
+            // Report the first differing value rather than a 100 KB diff.
+            let native_text = String::from_utf8_lossy(&native);
+            let wasm_text = String::from_utf8_lossy(&produced);
+            let at = native_text
+                .char_indices()
+                .zip(wasm_text.char_indices())
+                .find(|((_, a), (_, b))| a != b)
+                .map(|((index, _), _)| index)
+                .unwrap_or(0);
+            let from = at.saturating_sub(40);
+            panic!(
+                "the WASM float writer diverged from serde_json:\n  native: …{}…\n  wasm:   …{}…",
+                &native_text[from..(at + 40).min(native_text.len())],
+                &wasm_text[from..(at + 40).min(wasm_text.len())]
+            );
+        }
+    }
+    println!("float rendering agrees on {checked} of {offered} sampled doubles");
+}
+
+/// Whether `serde_json` reads back the double it itself wrote.
+fn serde_json_round_trips(value: f64) -> bool {
+    let text = serde_json::to_string(&Value::from(value)).expect("finite");
+    serde_json::from_str::<Value>(&text)
+        .ok()
+        .and_then(|parsed| parsed.as_f64())
+        .is_some_and(|parsed| parsed.to_bits() == value.to_bits())
+}
+
+/// `serde_json` does not parse back every double it writes, and that bounds
+/// what this contract can claim.
+///
+/// `serde_json`'s float parser is accurate to within one unit in the last
+/// place but is not correctly rounded, which is its documented default: exact
+/// round-tripping is the opt-in `float_roundtrip` feature, at roughly twice the
+/// parsing cost. The WASM implementation uses `core`'s `dec2flt`, which *is*
+/// correctly rounded, so for the affected literals the two implementations
+/// disagree about which double the bytes denote — before either renders
+/// anything.
+///
+/// This test exists so that boundary is measured and visible rather than
+/// assumed. It asserts only that short, ordinary decimals — the numbers real
+/// records hold — are unaffected. It deliberately does not assert a rate: that
+/// is a property of the dependency and may change when it is upgraded.
+#[test]
+fn serde_json_does_not_round_trip_every_double() {
+    let mut lost = 0usize;
+    let mut total = 0usize;
+    let mut example = None;
+    let mut seed: u64 = 0x243F6A8885A308D3;
+    for _ in 0..200_000 {
+        seed = seed
+            .wrapping_mul(6364136223846793005)
+            .wrapping_add(1442695040888963407);
+        let value = f64::from_bits(seed);
+        if !value.is_finite() {
+            continue;
+        }
+        total += 1;
+        if !serde_json_round_trips(value) {
+            lost += 1;
+            if example.is_none() {
+                example = Some(serde_json::to_string(&Value::from(value)).unwrap());
+            }
+        }
+    }
+    println!(
+        "serde_json {} of {total} random doubles do not survive its own \
+         serialize/parse round trip (example: {})",
+        lost,
+        example.as_deref().unwrap_or("none")
+    );
+    assert!(
+        lost > 0,
+        "if serde_json now round trips every double, the restriction on the float rendering \
+         test and the contract's stated input domain can both be removed"
+    );
+
+    // The values records actually hold are unaffected, which is what makes the
+    // contract useful despite the restriction.
+    for ordinary in [
+        0.0, -0.0, 0.5, 0.125, 1.0, 2.5, 42.0, 99.99, 1e-5, 1e15, 1e16, 1e-6, 3.14, 2.718,
+        1234.5678, -0.001, 100.0, 0.1, 0.2, 0.3,
+    ] {
+        assert!(
+            serde_json_round_trips(ordinary),
+            "an ordinary decimal must round trip: {ordinary}"
+        );
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Determinism
+// ---------------------------------------------------------------------------
+
+/// The same input, in the same instance, produces the same output every time.
+#[test]
+fn wasm_is_deterministic_across_repeated_calls() {
+    let Some(bytes) = contract_module() else {
+        return skipped("wasm_is_deterministic_across_repeated_calls");
+    };
+    let mut wasm = WasmContract::instantiate(bytes);
+    for case in &corpus().cases {
+        let input = case.bytes();
+        let first = wasm.evaluate(&input);
+        for round in 1..16 {
+            assert_eq!(
+                wasm.evaluate(&input),
+                first,
+                "{} changed answer on repeat {round} within one instance",
+                case.name
+            );
+        }
+    }
+}
+
+/// Repeated native evaluation is also stable.
+///
+/// Cheap, and it forecloses the reading in which only the WASM side was ever
+/// at risk of varying.
+#[test]
+fn native_is_deterministic_across_repeated_calls() {
+    for case in &corpus().cases {
+        let input = case.bytes();
+        let first = evaluate_canonical(&input);
+        for round in 1..16 {
+            assert_eq!(
+                evaluate_canonical(&input),
+                first,
+                "{} changed answer on native repeat {round}",
+                case.name
+            );
+        }
+    }
+}
+
+/// The same input produces the same output in a fresh instance.
+///
+/// Each instance gets its own `Store`, so its linear memory, allocator state
+/// and call history all start over. An implementation that carried state
+/// between diffs would show it here.
+#[test]
+fn wasm_is_deterministic_across_fresh_instances() {
+    let Some(bytes) = contract_module() else {
+        return skipped("wasm_is_deterministic_across_fresh_instances");
+    };
+    let mut baseline = WasmContract::instantiate(bytes);
+    let expected: Vec<Vec<u8>> = corpus()
+        .cases
+        .iter()
+        .map(|case| baseline.evaluate(&case.bytes()))
+        .collect();
+
+    for round in 0..4 {
+        let mut fresh = WasmContract::instantiate(bytes);
+        for (case, want) in corpus().cases.iter().zip(&expected) {
+            assert_eq!(
+                &fresh.evaluate(&case.bytes()),
+                want,
+                "{} changed answer in fresh instance {round}",
+                case.name
+            );
+        }
+    }
+}
+
+/// Order of evaluation does not affect any answer.
+#[test]
+fn wasm_answers_do_not_depend_on_evaluation_order() {
+    let Some(bytes) = contract_module() else {
+        return skipped("wasm_answers_do_not_depend_on_evaluation_order");
+    };
+    let mut forwards = WasmContract::instantiate(bytes);
+    let ordered: Vec<Vec<u8>> = corpus()
+        .cases
+        .iter()
+        .map(|case| forwards.evaluate(&case.bytes()))
+        .collect();
+
+    let mut backwards = WasmContract::instantiate(bytes);
+    for (index, case) in corpus().cases.iter().enumerate().rev() {
+        assert_eq!(
+            backwards.evaluate(&case.bytes()),
+            ordered[index],
+            "{} answered differently when the corpus ran in reverse",
+            case.name
+        );
+    }
+}
+
+/// The same input produces the same output in a separate OS process.
+#[test]
+fn wasm_is_deterministic_across_process_boundaries() {
+    let Some(bytes) = contract_module() else {
+        return skipped("wasm_is_deterministic_across_process_boundaries");
+    };
+    let mut here = WasmContract::instantiate(bytes);
+    let mine: Vec<Vec<u8>> = corpus()
+        .cases
+        .iter()
+        .map(|case| here.evaluate(&case.bytes()))
+        .collect();
+
+    let executable = std::env::current_exe().expect("the test binary has a path");
+    let output = Command::new(executable)
+        .args([
+            "--exact",
+            "wasm_is_deterministic_across_fresh_instances",
+            "--nocapture",
+        ])
+        .output()
+        .expect("the test binary re-runs");
+    assert!(
+        output.status.success(),
+        "the corpus did not reproduce in a separate process:\n{}",
+        String::from_utf8_lossy(&output.stdout)
+    );
+
+    for (case, produced) in corpus().cases.iter().zip(&mine) {
+        assert_eq!(String::from_utf8_lossy(produced), case.expected());
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Runtime restrictions
+// ---------------------------------------------------------------------------
+
+/// The module imports nothing.
+///
+/// This is the whole capability argument and it is deliberately narrow. A
+/// WebAssembly module reaches the outside world only through its imports. With
+/// an empty import section there is no clock, no filesystem handle, no socket,
+/// no entropy source and no FeltDB authority state in scope — not because
+/// access was denied at call time, but because no such function is linked. It
+/// says nothing about hostile modules, which this suite does not test.
+#[test]
+fn wasm_module_declares_no_imports() {
+    let Some(bytes) = contract_module() else {
+        return skipped("wasm_module_declares_no_imports");
+    };
+    let engine = wasmi::Engine::default();
+    let module = wasmi::Module::new(&engine, bytes).expect("the module validates");
+    let imports: Vec<String> = module
+        .imports()
+        .map(|import: wasmi::ImportType| format!("{}::{}", import.module(), import.name()))
+        .collect();
+    assert!(
+        imports.is_empty(),
+        "the contract module must import nothing; it imports {imports:?}"
+    );
+}
+
+/// An empty linker instantiates the module.
+#[test]
+fn wasm_module_instantiates_with_no_host_functions() {
+    let Some(bytes) = contract_module() else {
+        return skipped("wasm_module_instantiates_with_no_host_functions");
+    };
+    let engine = wasmi::Engine::default();
+    let module = wasmi::Module::new(&engine, bytes).unwrap();
+    let mut store = wasmi::Store::new(&engine, ());
+    wasmi::Linker::<()>::new(&engine)
+        .instantiate_and_start(&mut store, &module)
+        .expect("no host function is required");
+}
+
+/// The module exports the contract ABI and nothing that could act on FeltDB.
+#[test]
+fn wasm_module_exports_only_the_contract_abi() {
+    let Some(bytes) = contract_module() else {
+        return skipped("wasm_module_exports_only_the_contract_abi");
+    };
+    let engine = wasmi::Engine::default();
+    let module = wasmi::Module::new(&engine, bytes).unwrap();
+    let mut functions: Vec<String> = module
+        .exports()
+        .filter(|export| export.ty().func().is_some())
+        .map(|export| export.name().to_string())
+        .collect();
+    functions.sort();
+    assert_eq!(
+        functions,
+        vec![
+            "contract_alloc".to_string(),
+            "contract_evaluate".to_string(),
+            "contract_free".to_string(),
+            "contract_version".to_string(),
+        ]
+    );
+}
+
+/// WASI is not present, under any of the names a runtime would look for.
+#[test]
+fn wasm_module_requires_no_wasi() {
+    let Some(bytes) = contract_module() else {
+        return skipped("wasm_module_requires_no_wasi");
+    };
+    let text = String::from_utf8_lossy(bytes);
+    for forbidden in [
+        "wasi_snapshot_preview1",
+        "wasi_unstable",
+        "clock_time_get",
+        "random_get",
+        "fd_read",
+        "fd_write",
+        "sock_recv",
+        "path_open",
+    ] {
+        assert!(
+            !text.contains(forbidden),
+            "the contract module names {forbidden}, which it has no reason to"
+        );
+    }
+}
+
+/// The contract never traps, on any corpus input.
+#[test]
+fn wasm_contract_returns_a_result_for_every_input_including_malformed() {
+    let Some(bytes) = contract_module() else {
+        return skipped("wasm_contract_returns_a_result_for_every_input_including_malformed");
+    };
+    let mut wasm = WasmContract::instantiate(bytes);
+    for case in &corpus().cases {
+        let output = wasm.evaluate(&case.bytes());
+        let parsed: Value =
+            serde_json::from_slice(&output).expect("every output is canonical JSON");
+        assert_eq!(parsed["contract"], STATE_DIFF_CONTRACT_ID);
+        assert!(
+            parsed.get("diff").is_some() ^ parsed.get("error").is_some(),
+            "{} produced neither or both of diff and error",
+            case.name
+        );
+    }
+    // Inputs no fixture would contain, to show trap-freedom is not a property
+    // of the corpus. Nesting past the shared recursion bound is included.
+    for hostile in [
+        vec![0u8; 0],
+        vec![0xff; 64],
+        b"{".repeat(4096),
+        b"[".repeat(4096),
+        vec![b'"'; 1024],
+        format!(
+            r#"{{"contract":"feltdb.state.diff","state_a":{}{},"state_b":1,"version":1}}"#,
+            "[".repeat(300),
+            "]".repeat(300)
+        )
+        .into_bytes(),
+    ] {
+        let output = wasm.evaluate(&hostile);
+        assert!(serde_json::from_slice::<Value>(&output).is_ok());
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Mutation: does the suite actually detect divergence?
+// ---------------------------------------------------------------------------
+
+/// A deliberate change to the WASM implementation's source.
+struct Mutation {
+    name: &'static str,
+    file: &'static str,
+    from: &'static str,
+    to: &'static str,
+    /// Whether the corpus must catch it.
+    ///
+    /// One mutation is expected *not* to be caught, and that expectation is
+    /// part of the contract: it changes an ordering the contract does not
+    /// make semantic.
+    detected: bool,
+}
+
+const MUTATIONS: &[Mutation] = &[
+    Mutation {
+        name: "additions are reported as changes",
+        file: "src/diff.rs",
+        from: "                        kind: ChangeKind::Added,\n                        old_value: None,\n                        new_value: Some(new_value.clone()),\n                    });\n                    path.pop();",
+        to: "                        kind: ChangeKind::Changed,\n                        old_value: None,\n                        new_value: Some(new_value.clone()),\n                    });\n                    path.pop();",
+        detected: true,
+    },
+    Mutation {
+        name: "object removals are not reported",
+        file: "src/diff.rs",
+        from: "                    None => changes.push(Change {\n                        path: path.clone(),\n                        kind: ChangeKind::Removed,",
+        to: "                    None => changes.push(Change {\n                        path: path.clone(),\n                        kind: ChangeKind::Added,",
+        detected: true,
+    },
+    Mutation {
+        name: "unequal integers are not reported as changed",
+        file: "src/diff.rs",
+        from: "        (Json::PosInt(a), Json::PosInt(b)) if a == b => {}",
+        to: "        (Json::PosInt(_), Json::PosInt(_)) => {}",
+        detected: true,
+    },
+    Mutation {
+        name: "object path components are dropped",
+        file: "src/diff.rs",
+        from: "            for (key, old_value) in a {\n                path.push(PathComponent::Key(key.clone()));",
+        to: "            for (key, old_value) in a {\n                path.push(PathComponent::Key(alloc::string::String::from(\"x\")));",
+        detected: true,
+    },
+    Mutation {
+        name: "array indexes are off by one",
+        file: "src/diff.rs",
+        from: "            for (index, (old_value, new_value)) in a.iter().zip(b.iter()).enumerate() {\n                path.push(PathComponent::Index(index));",
+        to: "            for (index, (old_value, new_value)) in a.iter().zip(b.iter()).enumerate() {\n                path.push(PathComponent::Index(index + 1));",
+        detected: true,
+    },
+    Mutation {
+        name: "array removals start at the wrong index",
+        file: "src/diff.rs",
+        from: "            for (index, old_value) in a.iter().enumerate().skip(b.len()) {",
+        to: "            for (index, old_value) in a.iter().enumerate().skip(b.len() + 1) {",
+        detected: true,
+    },
+    Mutation {
+        name: "old values are not emitted",
+        file: "src/diff.rs",
+        from: "        (_, _) => changes.push(Change {\n            path: path.clone(),\n            kind: ChangeKind::Changed,\n            old_value: Some(old.clone()),",
+        to: "        (_, _) => changes.push(Change {\n            path: path.clone(),\n            kind: ChangeKind::Changed,\n            old_value: None,",
+        detected: true,
+    },
+    Mutation {
+        name: "new values are not emitted",
+        file: "src/diff.rs",
+        from: "            kind: ChangeKind::Changed,\n            old_value: Some(old.clone()),\n            new_value: Some(new.clone()),",
+        to: "            kind: ChangeKind::Changed,\n            old_value: Some(old.clone()),\n            new_value: None,",
+        detected: true,
+    },
+    Mutation {
+        name: "null against null is reported as a change",
+        file: "src/diff.rs",
+        from: "        (Json::Null, Json::Null) => {}",
+        to: "        (Json::Null, Json::Null) if false => {}",
+        detected: true,
+    },
+    Mutation {
+        name: "integers and floats compare equal",
+        file: "src/diff.rs",
+        from: "        (Json::Float(a), Json::Float(b)) if a == b => {}",
+        to: "        (Json::Float(a), Json::Float(b)) if a == b => {}\n        (Json::PosInt(a), Json::Float(b)) if *a as f64 == *b => {}\n        (Json::Float(a), Json::PosInt(b)) if *a == *b as f64 => {}",
+        detected: true,
+    },
+    Mutation {
+        name: "the result is not sorted by path",
+        file: "src/diff.rs",
+        from: "    changes.sort_by(|a, b| a.path.cmp(&b.path).then_with(|| a.kind.cmp(&b.kind)));",
+        to: "    changes.sort_by(|a, b| b.path.cmp(&a.path).then_with(|| a.kind.cmp(&b.kind)));",
+        detected: true,
+    },
+    Mutation {
+        name: "floats are rendered by Rust rather than by ryu's rule",
+        file: "src/json.rs",
+        from: "    if (-5..=15).contains(&exponent) {",
+        to: "    if (-4..=15).contains(&exponent) {",
+        detected: true,
+    },
+    Mutation {
+        name: "strings skip an escape serde_json emits",
+        file: "src/json.rs",
+        from: "            '\\t' => out.extend_from_slice(b\"\\\\t\"),",
+        to: "            '\\t' => out.extend_from_slice(b\"\\t\"),",
+        detected: true,
+    },
+    // The one mutation that must NOT be caught. Additions are emitted while
+    // walking the new object's members and the whole result is sorted
+    // afterwards; paths are unique within a diff, so the order they were
+    // emitted in cannot survive into the output. If this were ever detected,
+    // the contract would have accidentally made an internal traversal order
+    // part of its semantics.
+    Mutation {
+        name: "object additions are emitted in reverse order before sorting",
+        file: "src/diff.rs",
+        from: "            for (key, new_value) in b {\n                if old.get(key).is_none() {",
+        to: "            for (key, new_value) in b.iter().rev() {\n                if old.get(key).is_none() {",
+        detected: false,
+    },
+];
+
+/// Every deliberate mutation of the WASM contract lands where it should.
+///
+/// Without this the conformance suite proves only that two implementations
+/// agree, not that agreement was ever in question. Each mutant is built from a
+/// copy of the real source with one edit applied. Twelve must fail against the
+/// committed expectations; one must not, because it changes an order the
+/// contract deliberately does not make semantic.
+#[test]
+fn deliberate_wasm_mutations_land_where_they_should() {
+    if contract_module().is_none() {
+        return skipped("deliberate_wasm_mutations_land_where_they_should");
+    }
+    let source = repository_root().join(WASM_CRATE);
+    let scratch = tempfile::tempdir().expect("a scratch directory");
+
+    let mut wrong = Vec::new();
+    for mutation in MUTATIONS {
+        let root = scratch.path().join(mutation.name.replace(' ', "-"));
+        copy_crate(&source, &root);
+        let target = root.join(mutation.file);
+        let original = std::fs::read_to_string(&target).expect("the mutated file exists");
+        assert!(
+            original.matches(mutation.from).count() == 1,
+            "mutation {:?} no longer applies: its anchor is not present exactly once in {}. \
+             The mutation suite must be updated with the implementation it mutates.",
+            mutation.name,
+            mutation.file
+        );
+        std::fs::write(&target, original.replace(mutation.from, mutation.to)).unwrap();
+
+        let mut mutant = WasmContract::instantiate(&build_module(&root));
+        let caught: Vec<&str> = corpus()
+            .cases
+            .iter()
+            .filter(|case| {
+                String::from_utf8_lossy(&mutant.evaluate(&case.bytes())) != case.expected()
+            })
+            .map(|case| case.name.as_str())
+            .collect();
+
+        match (mutation.detected, caught.first()) {
+            (true, Some(first)) => println!(
+                "mutation {:?} caught by {} fixtures, first: {first}",
+                mutation.name,
+                caught.len()
+            ),
+            (false, None) => println!(
+                "mutation {:?} correctly NOT caught: the order it changes is not semantic",
+                mutation.name
+            ),
+            (true, None) => wrong.push(format!(
+                "{:?} was not caught, but the corpus should distinguish it",
+                mutation.name
+            )),
+            (false, Some(_)) => wrong.push(format!(
+                "{:?} was caught by {} fixtures, but it changes an order the contract does not \
+                 make semantic; the contract has accidentally fixed an internal traversal order",
+                mutation.name,
+                caught.len()
+            )),
+        }
+    }
+    assert!(
+        wrong.is_empty(),
+        "mutation outcomes were wrong:\n{}",
+        wrong.join("\n")
+    );
+}
+
+/// Copies the contract crate's source, without its build directory.
+fn copy_crate(from: &Path, to: &Path) {
+    std::fs::create_dir_all(to.join("src")).unwrap();
+    std::fs::copy(from.join("Cargo.toml"), to.join("Cargo.toml")).unwrap();
+    for entry in std::fs::read_dir(from.join("src")).unwrap() {
+        let entry = entry.unwrap();
+        std::fs::copy(entry.path(), to.join("src").join(entry.file_name())).unwrap();
+    }
+}
+
+/// Mutating the input encoding is detected where the encoding is semantically
+/// load-bearing, and not where it is not.
+///
+/// - Reordering members changes nothing, because a JSON object denotes a map
+///   and both implementations decode it to one. The suite must *not* flag it.
+/// - Swapping the two states changes the diff's direction, which is entirely
+///   semantic. The suite must flag it.
+/// - Dropping the contract identity turns every case into an input error.
+#[test]
+fn input_encoding_mutations_are_detected_where_they_matter() {
+    let typed: Vec<(&Case, Value)> = corpus()
+        .cases
+        .iter()
+        .filter_map(|case| {
+            let input = case.input.as_ref()?;
+            Some((case, serde_json::to_value(input).unwrap()))
+        })
+        .collect();
+    assert!(typed.len() > 70, "most of the corpus is typed input");
+
+    // 1. Member order, which carries no meaning.
+    for (case, encoded) in &typed {
+        let produced =
+            String::from_utf8(evaluate_canonical(encode_reversed(encoded).as_bytes())).unwrap();
+        assert_eq!(
+            produced,
+            case.expected(),
+            "{} changed answer under a reordered encoding; object member order is not part of \
+             this contract's semantics",
+            case.name
+        );
+    }
+
+    // 2. Direction, which carries all of it.
+    let mut direction_matters = 0;
+    for (case, encoded) in &typed {
+        let mut swapped = encoded.clone();
+        let object = swapped.as_object_mut().unwrap();
+        let a = object["state_a"].clone();
+        let b = object["state_b"].clone();
+        object["state_a"] = b;
+        object["state_b"] = a;
+        let produced = String::from_utf8(evaluate_canonical(
+            serde_json::to_vec(&swapped).unwrap().as_slice(),
+        ))
+        .unwrap();
+        if produced != case.expected() {
+            direction_matters += 1;
+        }
+    }
+    assert!(
+        direction_matters > 50,
+        "the diff is direction sensitive; swapping the states should change most results, \
+         but it changed only {direction_matters}"
+    );
+
+    // 3. Contract identity dropped.
+    for (case, encoded) in typed.iter().take(1) {
+        let mut mutated = encoded.clone();
+        mutated.as_object_mut().unwrap().remove("contract");
+        let produced = String::from_utf8(evaluate_canonical(
+            serde_json::to_vec(&mutated).unwrap().as_slice(),
+        ))
+        .unwrap();
+        assert_ne!(produced, case.expected());
+        assert!(produced.contains("CONTRACT_INPUT_INVALID"));
+    }
+}
+
+/// Encodes a value with every object's members in reverse sorted order.
+///
+/// `serde_json::Map` re-sorts on insert, so a non-canonical member order has to
+/// be produced as text rather than as a value.
+fn encode_reversed(value: &Value) -> String {
+    match value {
+        Value::Object(members) => {
+            let mut parts: Vec<String> = members
+                .iter()
+                .map(|(key, value)| {
+                    format!(
+                        "{}:{}",
+                        serde_json::to_string(key).unwrap(),
+                        encode_reversed(value)
+                    )
+                })
+                .collect();
+            parts.reverse();
+            format!("{{{}}}", parts.join(","))
+        }
+        Value::Array(items) => format!(
+            "[{}]",
+            items
+                .iter()
+                .map(encode_reversed)
+                .collect::<Vec<_>>()
+                .join(",")
+        ),
+        other => serde_json::to_string(other).unwrap(),
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Corpus maintenance
+// ---------------------------------------------------------------------------
+
+/// Records the canonical output of every case, after both implementations agree.
+///
+/// Ignored by default: it writes the corpus. Run it deliberately with
+/// `FELTDB_STATE_DIFF_CONTRACT_BLESS=1 cargo test -p feltdb --test
+/// state_diff_contract_conformance -- bless --ignored`. It refuses to record
+/// anything unless the WASM implementation is available and agrees, so an
+/// expectation can never be blessed from one implementation alone.
+#[test]
+#[ignore = "rewrites the committed corpus"]
+fn bless() {
+    assert_eq!(
+        std::env::var("FELTDB_STATE_DIFF_CONTRACT_BLESS").as_deref(),
+        Ok("1"),
+        "set FELTDB_STATE_DIFF_CONTRACT_BLESS=1 to rewrite the corpus"
+    );
+    let bytes = contract_module().expect(
+        "blessing requires the WASM implementation: an expectation recorded from the native \
+         implementation alone would prove nothing",
+    );
+    let mut wasm = WasmContract::instantiate(bytes);
+
+    let mut document: Value =
+        serde_json::from_slice(&std::fs::read(corpus_path()).unwrap()).unwrap();
+    for (index, case) in corpus().cases.iter().enumerate() {
+        let input = case.bytes();
+        let native = evaluate_canonical(&input);
+        let produced = wasm.evaluate(&input);
+        assert_eq!(
+            String::from_utf8_lossy(&native),
+            String::from_utf8_lossy(&produced),
+            "refusing to record {}: the implementations disagree",
+            case.name
+        );
+        if case.input.is_some() {
+            document["cases"][index]["canonical_input"] =
+                Value::String(String::from_utf8(input).unwrap());
+        }
+        document["cases"][index]["expected_output"] =
+            Value::String(String::from_utf8(native).unwrap());
+    }
+    let mut text = serde_json::to_string_pretty(&document).unwrap();
+    text.push('\n');
+    std::fs::write(corpus_path(), text).unwrap();
+    println!("recorded {} expectations", corpus().cases.len());
+}