@feltdb/core 0.13.0 → 0.16.0

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

@@ -1,1316 +0,0 @@
-//! 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());
-}