@feltdb/core 0.8.3 → 0.8.5

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

@@ -0,0 +1,1799 @@
+//! Conformance, determinism and capability proofs for the
+//! `feltdb.state.conflict` deterministic contract.
+//!
+//! The third specimen of the pattern proved for `feltdb.trigger.match` and
+//! `feltdb.state.diff`, and the first that reasons over competing changes:
+//!
+//! ```text
+//!     Contract semantics are authoritative.
+//!     Runtime implementation is replaceable.
+//!
+//!     NativeClassify(base, left, right) == WasmClassify(base, left, right)
+//! ```
+//!
+//! The corpus in `tests/fixtures/state_conflict_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 classifier's semantics is caught by the same bytes the
+//! WASM implementation was measured against.
+//!
+//! Beyond conformance, this suite asserts the *semantic invariants* the
+//! classification must satisfy — see `classification_invariants_hold` — because
+//! a contract over competing changes can be reproduced faithfully and still be
+//! meaningless if the relation itself is not pinned.
+
+use feltdb::state_conflict_contract::{
+    canonical_input_bytes, evaluate_canonical, StateConflictInput, STATE_CONFLICT_CONTRACT_ID,
+    STATE_CONFLICT_CONTRACT_VERSION,
+};
+use feltdb::state_model::{ConflictClass, ConflictClassification};
+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<StateConflictInput>,
+    /// 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_CONFLICT_CONTRACT_BLESS=1",
+                self.name
+            )
+        })
+    }
+}
+
+fn corpus_path() -> PathBuf {
+    Path::new(env!("CARGO_MANIFEST_DIR")).join("tests/fixtures/state_conflict_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_CONFLICT_CONTRACT_ID);
+    assert_eq!(corpus.contract_version, STATE_CONFLICT_CONTRACT_VERSION);
+    assert!(
+        corpus.cases.len() >= 150,
+        "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 [
+        // baseline
+        "all_identical",
+        "left_changed_right_unchanged",
+        "right_changed_left_unchanged",
+        "both_changed_identically",
+        "both_changed_differently",
+        // independent
+        "different_top_level_fields",
+        "different_nested_fields",
+        "different_sibling_subtrees",
+        "multiple_independent_changes",
+        "array_different_indexes",
+        // the path relation matrix
+        "relation_same_disagreeing",
+        "relation_same_agreeing",
+        "relation_ancestor_replaced_scalar",
+        "relation_ancestor_removed",
+        "relation_ancestor_two_levels",
+        "relation_descendant_replaced_scalar",
+        "relation_descendant_removed",
+        "relation_disjoint_siblings",
+        "relation_disjoint_string_prefix",
+        "relation_disjoint_key_against_index",
+        "relation_overlap_alongside_independent",
+        "relation_parent_object_to_array",
+        "relation_array_same_index",
+        "relation_array_different_indexes",
+        "relation_array_element_removed_vs_edited_inside",
+        "relation_array_prepend_vs_index_edit",
+        // overlapping
+        "same_path_different_values",
+        "parent_changed_vs_child_changed",
+        "child_changed_vs_parent_changed",
+        "addition_vs_addition_different",
+        "removal_vs_modification",
+        "object_to_scalar_vs_scalar_change",
+        "object_vs_array_at_same_path",
+        "scalar_to_object_vs_scalar_to_array",
+        // null and absence
+        "missing_vs_null",
+        "null_vs_value",
+        "value_vs_null",
+        "missing_vs_value_one_side",
+        "removal_vs_null_insertion",
+        // numbers
+        "integer_vs_float_same_magnitude",
+        "numeric_replacement_conflict",
+        "large_values",
+        "zero_vs_float_zero",
+        // arrays
+        "array_same_index_both_sides",
+        "array_append_both_sides_same",
+        "array_removal_one_side",
+        "array_removal_both_sides",
+        "array_prepend_one_side",
+        "array_reorder_vs_edit",
+        "array_nested_change_each_side",
+        // deep
+        "deeply_nested_independent_edits",
+        "many_simultaneous_conflicts",
+        "mixed_severities_in_one_result",
+        // empty
+        "empty_to_populated_both_sides",
+        "populated_to_empty_both_sides",
+        "empty_object_vs_empty_array",
+        "empty_object_vs_scalar",
+        "empty_array_vs_scalar",
+        // unparseable content
+        "unparseable_base",
+        "unparseable_all_three",
+        // invalid envelopes
+        "malformed_not_json",
+        "malformed_duplicate_envelope_member",
+        "malformed_state_is_not_a_string",
+    ] {
+        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-conflict-contract-wasm";
+const WASM_ARTIFACT: &str =
+    "target/wasm32-unknown-unknown/release/feltdb_state_conflict_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 {
+    // `rustc --print target-libdir` succeeds for any target rustc *knows*, and
+    // prints where the standard library would live if it were installed. It
+    // does not report whether it actually is. Asking only about the exit status
+    // therefore reports every known target as installed, and the skip below
+    // never fires: a machine without `wasm32-unknown-unknown` fails the build
+    // and every WASM test with it, rather than skipping loudly as intended.
+    //
+    // The directory's existence is the fact worth having.
+    Command::new("rustc")
+        .args([
+            "--print",
+            "target-libdir",
+            "--target",
+            "wasm32-unknown-unknown",
+        ])
+        .output()
+        .ok()
+        .filter(|output| output.status.success())
+        .map(|output| String::from_utf8_lossy(&output.stdout).trim().to_string())
+        .is_some_and(|libdir| Path::new(&libdir).is_dir())
+}
+
+/// 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_CONFLICT_CONTRACT_WASM") {
+                return Some(
+                    std::fs::read(path).expect("FELTDB_STATE_CONFLICT_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_CONFLICT_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!(
+            "{:<44} {:<16} {:<16} {}",
+            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_CONFLICT_CONTRACT_VERSION
+    );
+    for case in &corpus().cases {
+        let output: Value = serde_json::from_slice(&evaluate_canonical(&case.bytes())).unwrap();
+        assert_eq!(output["contract"], STATE_CONFLICT_CONTRACT_ID);
+        assert_eq!(output["version"], STATE_CONFLICT_CONTRACT_VERSION);
+    }
+}
+
+/// The native adapter adds nothing to the existing implementation.
+///
+/// The contract must be the classification FeltDB already computes, not a
+/// second one that happens to agree. This runs both entry points over the whole
+/// corpus, constructing revisions the way the adapter does.
+#[test]
+fn the_contract_is_the_existing_classifier() {
+    use feltdb::state_conflict_contract::classify_states;
+    use feltdb::state_model::{ConflictClassification, StateId, StateRevision};
+
+    let revision = |content: &str| StateRevision {
+        id: StateId::compute(content),
+        resource: String::new(),
+        content: content.to_string(),
+        content_id: StateId::compute(content),
+        parent_id: None,
+        sequence: 0,
+        authority: String::new(),
+        timestamp_ms: 0,
+        metadata: Default::default(),
+    };
+
+    let mut checked = 0;
+    for case in &corpus().cases {
+        let Some(input) = case.input.as_ref() else {
+            continue;
+        };
+        assert_eq!(
+            serde_json::to_string(&classify_states(&input.base, &input.left, &input.right))
+                .unwrap(),
+            serde_json::to_string(&ConflictClassification::classify(
+                &revision(&input.base),
+                &revision(&input.left),
+                &revision(&input.right)
+            ))
+            .unwrap(),
+            "the contract adapter changed the result for {}",
+            case.name
+        );
+        checked += 1;
+    }
+    assert!(checked > 80, "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["classification"]["path_conflicts"].as_array() {
+        Some(paths) => format!(
+            "{}/{}",
+            parsed["classification"]["overall"].as_str().unwrap_or("?"),
+            paths.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) {
+        // The base holds the whole sample and both branches replace it with 0,
+        // so the array is emitted once as `base_value` and the sides converge.
+        let base = serde_json::to_string(&Value::Array(
+            chunk.iter().map(|value| Value::from(*value)).collect(),
+        ))
+        .unwrap();
+        let input = canonical_input_bytes(&StateConflictInput::new(
+            base,
+            "0".to_string(),
+            "0".to_string(),
+        ));
+        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_CONFLICT_CONTRACT_ID);
+        assert!(
+            parsed.get("classification").is_some() ^ parsed.get("error").is_some(),
+            "{} produced neither or both of classification 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],
+        // Nesting past the shared recursion bound, inside state content.
+        format!(
+            r#"{{"base":{},"contract":"feltdb.state.conflict","left":"1","right":"1","version":1}}"#,
+            serde_json::to_string(&format!("{}{}", "[".repeat(300), "]".repeat(300))).unwrap()
+        )
+        .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.
+    ///
+    /// Some mutations are expected *not* to be caught, and each such
+    /// expectation is part of the contract rather than a gap. `why_invisible`
+    /// says which reason applies.
+    detected: bool,
+    /// For a mutation expected to go uncaught, why it cannot be observed
+    /// through this contract. Empty for mutations that must be caught.
+    why_invisible: &'static str,
+}
+
+const MUTATIONS: &[Mutation] = &[
+    // --- the overlap relation, which this contract version establishes ---
+    Mutation {
+        name: "ancestor overlap is not detected",
+        file: "src/conflict.rs",
+        from: "    for depth in 0..path.len() {",
+        to: "    for depth in 0..0 {",
+        detected: true,
+        why_invisible: "",
+    },
+    Mutation {
+        name: "descendant overlap is not detected",
+        file: "src/conflict.rs",
+        from: "    changes\n        .get(after)\n        .is_some_and(|change| path_starts_with(&change.path, path))",
+        to: "    changes\n        .get(after)\n        .is_some_and(|_| false)",
+        detected: true,
+        why_invisible: "",
+    },
+    Mutation {
+        name: "overlap is checked against the branch's own changes",
+        file: "src/conflict.rs",
+        from: "                if overlapping_change_exists(&right_changes, &path) {",
+        to: "                if overlapping_change_exists(&left_changes, &path) {",
+        detected: true,
+        why_invisible: "",
+    },
+    Mutation {
+        name: "path components are compared by length alone",
+        file: "src/conflict.rs",
+        from: "    candidate.len() >= prefix.len() && candidate[..prefix.len()] == *prefix",
+        to: "    candidate.len() >= prefix.len()",
+        detected: true,
+        why_invisible: "",
+    },
+    Mutation {
+        name: "only the first path component is compared",
+        file: "src/conflict.rs",
+        from: "    candidate.len() >= prefix.len() && candidate[..prefix.len()] == *prefix",
+        to: "    candidate.len() >= prefix.len()\n        && (prefix.is_empty() || candidate[0] == prefix[0])",
+        detected: true,
+        why_invisible: "",
+    },
+    Mutation {
+        name: "every overlap is reported as convergent rather than conflicting",
+        file: "src/conflict.rs",
+        from: "                if overlapping_change_exists(&right_changes, &path) {\n                    has_conflict = true;\n                    ConflictClass::Conflict",
+        to: "                if overlapping_change_exists(&right_changes, &path) {\n                    has_convergence = true;\n                    ConflictClass::Convergent",
+        detected: true,
+        why_invisible: "",
+    },
+    // --- base_value, corrected in this version ---------------------------
+    Mutation {
+        name: "base_value is read from the left branch rather than the base",
+        file: "src/conflict.rs",
+        from: "            base_value: resolve_path(base, &path).cloned(),",
+        to: "            base_value: resolve_path(left, &path).cloned(),",
+        detected: true,
+        why_invisible: "",
+    },
+    Mutation {
+        name: "base_value is dropped",
+        file: "src/conflict.rs",
+        from: "            base_value: resolve_path(base, &path).cloned(),",
+        to: "            base_value: None,",
+        detected: true,
+        why_invisible: "",
+    },
+    Mutation {
+        name: "base_value resolves array elements as object members",
+        file: "src/conflict.rs",
+        from: "            PathComponent::Index(index) => match current {\n                Json::Array(items) => items.get(*index)?,\n                _ => return None,\n            },",
+        to: "            PathComponent::Index(_) => return None,",
+        detected: true,
+        why_invisible: "",
+    },
+    // --- the classification relation itself ------------------------------
+    Mutation {
+        name: "disagreeing edits are classified as independent",
+        file: "src/conflict.rs",
+        from: "                } else {\n                    has_conflict = true;\n                    ConflictClass::Conflict\n                }",
+        to: "                } else {\n                    ConflictClass::Independent\n                }",
+        detected: true,
+        why_invisible: "",
+    },
+    Mutation {
+        name: "agreeing edits are classified as conflicting",
+        file: "src/conflict.rs",
+        from: "                if one.kind == two.kind && optional_equals(&one.new_value, &two.new_value) {",
+        to: "                if false {",
+        detected: true,
+        why_invisible: "",
+    },
+    Mutation {
+        name: "convergence ignores the new value",
+        file: "src/conflict.rs",
+        from: "                if one.kind == two.kind && optional_equals(&one.new_value, &two.new_value) {",
+        to: "                if one.kind == two.kind {",
+        detected: true,
+        why_invisible: "",
+    },
+    Mutation {
+        name: "a disjoint one-sided change is classified as convergent",
+        file: "src/conflict.rs",
+        from: "                } else {\n                    ConflictClass::Independent\n                }\n            }\n            (None, Some(_)) => {",
+        to: "                } else {\n                    ConflictClass::Convergent\n                }\n            }\n            (None, Some(_)) => {",
+        detected: true,
+        why_invisible: "",
+    },
+    Mutation {
+        name: "the two branches are recorded on the wrong sides",
+        file: "src/conflict.rs",
+        from: "            left_value: left_change.and_then(|change: &Change| change.new_value.clone()),\n            right_value: right_change.and_then(|change: &Change| change.new_value.clone()),",
+        to: "            left_value: right_change.and_then(|change: &Change| change.new_value.clone()),\n            right_value: left_change.and_then(|change: &Change| change.new_value.clone()),",
+        detected: true,
+        why_invisible: "",
+    },
+    Mutation {
+        name: "overall severity prefers convergence over conflict",
+        file: "src/conflict.rs",
+        from: "    let overall = if has_conflict {\n        ConflictClass::Conflict\n    } else if has_convergence {",
+        to: "    let overall = if has_convergence {\n        ConflictClass::Convergent\n    } else if has_conflict {",
+        detected: true,
+        why_invisible: "",
+    },
+    Mutation {
+        name: "overall ignores convergence entirely",
+        file: "src/conflict.rs",
+        from: "    } else if has_convergence {\n        ConflictClass::Convergent\n    } else {",
+        to: "    } else if false {\n        ConflictClass::Convergent\n    } else {",
+        detected: true,
+        why_invisible: "",
+    },
+    // --- the diff the classification is defined over ---------------------
+    Mutation {
+        name: "a null state and a missing member are diffed alike",
+        file: "src/diff.rs",
+        from: "        (Json::Null, Json::Null) => {}",
+        to: "        (Json::Null, Json::Null) if false => {}",
+        detected: true,
+        why_invisible: "",
+    },
+    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,
+        why_invisible: "",
+    },
+    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,
+        why_invisible: "",
+    },
+    Mutation {
+        name: "unparseable state content is an error rather than JSON null",
+        file: "src/lib.rs",
+        from: "        .unwrap_or(json::Json::Null)",
+        to: "        .unwrap_or(json::Json::Bool(false))",
+        detected: true,
+        why_invisible: "",
+    },
+    // --- mutations that must NOT be caught -------------------------------
+    Mutation {
+        name: "object additions are diffed 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,
+        why_invisible: "the diff sorts its own result, so the order additions were emitted in \
+                        cannot survive into either diff or into the classification",
+    },
+    Mutation {
+        name: "ancestor paths are searched from the deepest prefix first",
+        file: "src/conflict.rs",
+        from: "    for depth in 0..path.len() {",
+        to: "    for depth in (0..path.len()).rev() {",
+        detected: false,
+        why_invisible: "the ancestor search only asks whether any prefix is present, so the \
+                        order it visits them in cannot change the answer",
+    },
+    Mutation {
+        name: "convergence ignores the change kind",
+        file: "src/conflict.rs",
+        from: "                if one.kind == two.kind && optional_equals(&one.new_value, &two.new_value) {",
+        to: "                if optional_equals(&one.new_value, &two.new_value) {",
+        detected: false,
+        why_invisible: "the kind comparison is redundant: both diffs share a base, so at a path \
+                        both branches touched the kinds match or the new values already differ",
+    },
+];
+
+/// Every mutation expected to go uncaught explains itself.
+#[test]
+fn uncaught_mutations_record_why_they_are_invisible() {
+    for mutation in MUTATIONS {
+        assert_eq!(
+            mutation.detected,
+            mutation.why_invisible.is_empty(),
+            "mutation {:?}: a mutation is either expected to be caught, or must say why it \
+             cannot be",
+            mutation.name
+        );
+    }
+}
+
+/// 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: {}",
+                mutation.name, mutation.why_invisible
+            ),
+            (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 was expected to be invisible because {}. \
+                 Either the implementation or that reasoning has changed, and both the mutation \
+                 expectation and the contract documentation need revisiting.",
+                mutation.name,
+                caught.len(),
+                mutation.why_invisible
+            )),
+        }
+    }
+    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. Which state is the base, which carries all of it.
+    let mut base_matters = 0;
+    for (case, encoded) in &typed {
+        let mut rotated = encoded.clone();
+        let object = rotated.as_object_mut().unwrap();
+        let base = object["base"].clone();
+        let left = object["left"].clone();
+        object["base"] = left;
+        object["left"] = base;
+        let produced = String::from_utf8(evaluate_canonical(
+            serde_json::to_vec(&rotated).unwrap().as_slice(),
+        ))
+        .unwrap();
+        if produced != case.expected() {
+            base_matters += 1;
+        }
+    }
+    assert!(
+        base_matters > 40,
+        "the ancestor is not interchangeable with a branch; exchanging them should change most \
+         results, but it changed only {base_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(),
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Semantic invariants
+// ---------------------------------------------------------------------------
+
+/// The three states of every typed fixture, for invariant checks.
+fn triples() -> Vec<(&'static str, String, String, String)> {
+    corpus()
+        .cases
+        .iter()
+        .filter_map(|case| {
+            let input = case.input.as_ref()?;
+            Some((
+                Box::leak(case.name.clone().into_boxed_str()) as &str,
+                input.base.clone(),
+                input.left.clone(),
+                input.right.clone(),
+            ))
+        })
+        .collect()
+}
+
+fn classify(base: &str, left: &str, right: &str) -> ConflictClassification {
+    feltdb::state_conflict_contract::classify_states(base, left, right)
+}
+
+/// The relation's own laws, over every state in the corpus.
+///
+/// Conformance proves two implementations agree. These prove the thing they
+/// agree on is the relation the contract describes, which is a different claim
+/// and the one that would survive replacing both implementations.
+#[test]
+fn classification_invariants_hold() {
+    for (name, base, left, right) in triples() {
+        // Nothing changed anywhere: no paths, and Independent overall. There is
+        // no fourth "no change" class.
+        for state in [&base, &left, &right] {
+            let same = classify(state, state, state);
+            assert!(
+                same.path_conflicts.is_empty(),
+                "{name}: identical states must produce no paths"
+            );
+            assert_eq!(
+                same.overall,
+                ConflictClass::Independent,
+                "{name}: identical states are Independent"
+            );
+        }
+
+        // One side unchanged: every path is Independent, both ways round.
+        for (one, two) in [(&left, &base), (&base, &right)] {
+            let single = classify(&base, one, two);
+            assert!(
+                single
+                    .path_conflicts
+                    .iter()
+                    .all(|entry| entry.classification == ConflictClass::Independent),
+                "{name}: a one-sided change cannot collide with anything"
+            );
+            assert_eq!(single.overall, ConflictClass::Independent, "{name}");
+        }
+
+        // Both sides landing on the same state: every path converges, and the
+        // overall class is Convergent unless nothing changed at all.
+        for state in [&left, &right] {
+            let agreeing = classify(&base, state, state);
+            assert!(
+                agreeing
+                    .path_conflicts
+                    .iter()
+                    .all(|entry| entry.classification == ConflictClass::Convergent),
+                "{name}: agreeing branches converge at every path"
+            );
+            let expected = if agreeing.path_conflicts.is_empty() {
+                ConflictClass::Independent
+            } else {
+                ConflictClass::Convergent
+            };
+            assert_eq!(agreeing.overall, expected, "{name}");
+        }
+
+        // `overall` is the maximum severity present, never anything else.
+        let full = classify(&base, &left, &right);
+        let expected = if full
+            .path_conflicts
+            .iter()
+            .any(|entry| entry.classification == ConflictClass::Conflict)
+        {
+            ConflictClass::Conflict
+        } else if full
+            .path_conflicts
+            .iter()
+            .any(|entry| entry.classification == ConflictClass::Convergent)
+        {
+            ConflictClass::Convergent
+        } else {
+            ConflictClass::Independent
+        };
+        assert_eq!(
+            full.overall, expected,
+            "{name}: overall must be the maximum severity present"
+        );
+
+        // Paths are unique and sorted, which is what makes the ordering total.
+        let paths: Vec<_> = full
+            .path_conflicts
+            .iter()
+            .map(|entry| entry.path.clone())
+            .collect();
+        let mut sorted = paths.clone();
+        sorted.sort();
+        assert_eq!(paths, sorted, "{name}: paths are emitted in sorted order");
+        sorted.dedup();
+        assert_eq!(paths.len(), sorted.len(), "{name}: paths are unique");
+    }
+}
+
+/// At a path both branches touched, the change kinds match or the new values
+/// already differ.
+///
+/// This is why `one.kind == two.kind` can never decide convergence, and so why
+/// relabelling a change kind is invisible to this contract. Both diffs are taken
+/// from the same base, so whether a path resolves in the base — which is what
+/// separates `Added` from `Changed` and `Removed` — is a property of the base
+/// alone and cannot differ between them. The remaining pair, `Removed` against
+/// `Changed`, always disagrees on the new value, because a removal has none.
+///
+/// Asserted over the corpus rather than argued alone: if the diff ever produces
+/// a counterexample, the kind comparison becomes load-bearing and the mutation
+/// expectations recorded above must change with it.
+#[test]
+fn the_change_kind_comparison_is_never_decisive() {
+    use feltdb::state_model::SemanticDiff;
+
+    let mut both_touched = 0;
+    for (name, base, left, right) in triples() {
+        let base_value: Value = serde_json::from_str(&base).unwrap_or(Value::Null);
+        let left_value: Value = serde_json::from_str(&left).unwrap_or(Value::Null);
+        let right_value: Value = serde_json::from_str(&right).unwrap_or(Value::Null);
+        let left_diff = SemanticDiff::compute(&base_value, &left_value);
+        let right_diff = SemanticDiff::compute(&base_value, &right_value);
+
+        for one in &left_diff.changes {
+            let Some(two) = right_diff
+                .changes
+                .iter()
+                .find(|other| other.path == one.path)
+            else {
+                continue;
+            };
+            both_touched += 1;
+            assert!(
+                one.kind == two.kind || one.new_value != two.new_value,
+                "{name}: the kind comparison decided the outcome at {:?}, which the contract \
+                 documentation says cannot happen",
+                one.path
+            );
+        }
+    }
+    assert!(
+        both_touched > 30,
+        "the corpus must actually exercise paths both branches touched"
+    );
+    println!("{both_touched} paths were touched by both branches");
+}
+
+/// Swapping the branches has the documented relationship.
+///
+/// `overall`, the path set and each path's `classification` are symmetric, and
+/// `left_value` and `right_value` exchange. `base_value` is now **also**
+/// symmetric, because it is read from the base state rather than from the left
+/// branch's change: version 1 reported it as `null` for a path only the right
+/// branch touched, which made the result side-dependent in a way nothing
+/// wanted. The only side-specific information left is the branch values, which
+/// is the information that ought to be side-specific.
+#[test]
+fn swapping_the_branches_exchanges_only_the_branch_values() {
+    let mut exchanged = 0;
+    for (name, base, left, right) in triples() {
+        let forward = classify(&base, &left, &right);
+        let reversed = classify(&base, &right, &left);
+
+        assert_eq!(
+            forward.overall, reversed.overall,
+            "{name}: the overall class is symmetric"
+        );
+        assert_eq!(
+            forward.path_conflicts.len(),
+            reversed.path_conflicts.len(),
+            "{name}: the same paths are reported either way round"
+        );
+        for (one, two) in forward.path_conflicts.iter().zip(&reversed.path_conflicts) {
+            assert_eq!(one.path, two.path, "{name}: paths are symmetric");
+            assert_eq!(
+                one.classification, two.classification,
+                "{name}: per-path classification is symmetric"
+            );
+            assert_eq!(
+                one.base_value, two.base_value,
+                "{name}: base_value is the ancestor's value, so it does not depend on which \
+                 branch is called left"
+            );
+            assert_eq!(
+                one.left_value, two.right_value,
+                "{name}: the branches exchange sides"
+            );
+            assert_eq!(
+                one.right_value, two.left_value,
+                "{name}: the branches exchange sides"
+            );
+            if one.left_value != one.right_value {
+                exchanged += 1;
+            }
+        }
+    }
+    assert!(
+        exchanged > 40,
+        "the corpus must exercise paths where the two branches hold different values, or the \
+         exchange assertion above proves nothing"
+    );
+    println!("{exchanged} paths held different values on the two branches");
+}
+
+/// An overlapping pair can never be convergent, and the corpus says so.
+///
+/// For a descendant path to exist the base must hold a container there. A change
+/// reported *at* the ancestor path means that branch no longer holds a container
+/// of that kind, while the branch editing inside it still does — so the two
+/// branches' values at the ancestor path always differ. This asserts the
+/// premise directly rather than trusting the argument.
+#[test]
+fn an_overlapping_pair_never_agrees_at_the_ancestor_path() {
+    use feltdb::state_model::{path_relation, resolve_path, PathRelation, SemanticDiff};
+
+    let mut overlaps = 0;
+    for (name, base, left, right) in triples() {
+        let base_value: Value = serde_json::from_str(&base).unwrap_or(Value::Null);
+        let left_value: Value = serde_json::from_str(&left).unwrap_or(Value::Null);
+        let right_value: Value = serde_json::from_str(&right).unwrap_or(Value::Null);
+        let left_diff = SemanticDiff::compute(&base_value, &left_value);
+        let right_diff = SemanticDiff::compute(&base_value, &right_value);
+
+        for one in &left_diff.changes {
+            for two in &right_diff.changes {
+                let ancestor = match path_relation(&one.path, &two.path) {
+                    PathRelation::Ancestor => &one.path,
+                    PathRelation::Descendant => &two.path,
+                    _ => continue,
+                };
+                overlaps += 1;
+                assert_ne!(
+                    resolve_path(&left_value, ancestor),
+                    resolve_path(&right_value, ancestor),
+                    "{name}: the branches agree at an overlapping ancestor path {ancestor:?}, \
+                     which the contract documentation says cannot happen"
+                );
+            }
+        }
+    }
+    assert!(
+        overlaps > 20,
+        "the corpus must actually exercise overlapping path pairs"
+    );
+    println!("{overlaps} overlapping path pairs were exercised");
+}
+
+/// Every entry's `base_value` is the base state's value at that path.
+///
+/// Version 1 read it from the left branch's change, so a path only the right
+/// branch touched reported `null` even where the base held a value. Downstream
+/// reconciliation needs the ancestor's value at a conflicting path to decide
+/// anything, so this is corrected rather than documented as a limitation.
+#[test]
+fn base_value_is_the_base_states_value_at_the_path() {
+    use feltdb::state_model::resolve_path;
+
+    let mut right_only_with_a_base_value = 0;
+    for (name, base, left, right) in triples() {
+        let base_value: Value = serde_json::from_str(&base).unwrap_or(Value::Null);
+        let output = classify(&base, &left, &right);
+        for entry in &output.path_conflicts {
+            assert_eq!(
+                entry.base_value.as_ref(),
+                resolve_path(&base_value, &entry.path),
+                "{name}: base_value must be the base state's value at {:?}",
+                entry.path
+            );
+            if entry.left_value.is_none()
+                && entry.right_value.is_some()
+                && entry.base_value.is_some()
+            {
+                right_only_with_a_base_value += 1;
+            }
+        }
+    }
+    assert!(
+        right_only_with_a_base_value > 0,
+        "the corpus must exercise a right-only change over a base value, which is exactly the \
+         case version 1 reported as null"
+    );
+    println!("{right_only_with_a_base_value} right-only entries carry a base value version 1 lost");
+}
+
+// ---------------------------------------------------------------------------
+// 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_CONFLICT_CONTRACT_BLESS=1 cargo test -p feltdb --test
+/// state_conflict_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_CONFLICT_CONTRACT_BLESS").as_deref(),
+        Ok("1"),
+        "set FELTDB_STATE_CONFLICT_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());
+}