@feltdb/core 0.8.3 → 0.8.5

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

@@ -0,0 +1,994 @@
+//! Conformance, determinism and capability proofs for the
+//! `feltdb.trigger.match` deterministic contract.
+//!
+//! The architectural invariant under test is:
+//!
+//! ```text
+//!     Contract semantics are authoritative.
+//!     Runtime implementation is replaceable.
+//!
+//!     NativeContract(input) == WasmContract(input)   for every fixture
+//! ```
+//!
+//! The corpus in `tests/fixtures/trigger_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 even where the WASM toolchain is
+//! absent: a change in native semantics is caught by the same bytes the WASM
+//! implementation was measured against.
+
+use feltdb::trigger_contract::{
+    canonical_input_bytes, evaluate_canonical, TriggerMatchInput, TRIGGER_MATCH_CONTRACT_ID,
+    TRIGGER_MATCH_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<TriggerMatchInput>,
+    /// Bytes fed to the contract verbatim, for malformed and non-canonical
+    /// 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. Recording the
+    /// bytes makes the corpus self-describing instead of requiring every reader
+    /// to own a canonical encoder.
+    #[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_TRIGGER_CONTRACT_BLESS=1",
+                self.name
+            )
+        })
+    }
+}
+
+fn corpus_path() -> PathBuf {
+    Path::new(env!("CARGO_MANIFEST_DIR")).join("tests/fixtures/trigger_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, TRIGGER_MATCH_CONTRACT_ID);
+    assert_eq!(corpus.contract_version, TRIGGER_MATCH_CONTRACT_VERSION);
+    assert!(
+        corpus.cases.len() >= 90,
+        "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.
+///
+/// This is 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 [
+        "collection_matches",
+        "collection_differs",
+        "change_kind_update_matches",
+        "change_kind_insert_against_update_trigger",
+        "disabled_trigger_rejects_matching_change",
+        "predicate_matches_string",
+        "predicate_value_mismatch",
+        "predicate_absent_matches_any_value",
+        "value_null_present_with_whole_record_predicate",
+        "nested_path_matches",
+        "array_equality_matches",
+        "integer_equality_matches",
+        "fanout_first_trigger_matches",
+        "malformed_not_json",
+        "empty_object_record",
+    ] {
+        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-trigger-contract-wasm";
+const WASM_ARTIFACT: &str =
+    "target/wasm32-unknown-unknown/release/feltdb_trigger_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 profile 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_TRIGGER_CONTRACT_WASM") {
+                return Some(
+                    std::fs::read(path).expect("FELTDB_TRIGGER_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_TRIGGER_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.
+///
+/// The expectations were recorded from a run in which the native and the WASM
+/// implementation already agreed, so this is a full-strength check of native
+/// semantics even on a machine with no WASM toolchain.
+#[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!(
+        "{:<52} {:<7} {:<7} {}",
+        "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!(
+            "{:<52} {:<7} {:<7} {}",
+            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), TRIGGER_MATCH_CONTRACT_VERSION);
+    for case in &corpus().cases {
+        let output: Value = serde_json::from_slice(&evaluate_canonical(&case.bytes())).unwrap();
+        assert_eq!(output["contract"], TRIGGER_MATCH_CONTRACT_ID);
+        assert_eq!(output["version"], TRIGGER_MATCH_CONTRACT_VERSION);
+    }
+}
+
+/// 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(),
+    };
+    if let Some(matched) = parsed["outcome"]["matched"].as_bool() {
+        return if matched { "match" } else { "no-match" }.into();
+    }
+    "error".into()
+}
+
+// ---------------------------------------------------------------------------
+// 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
+            );
+        }
+    }
+}
+
+/// 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 decisions 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.
+///
+/// The corpus is replayed forwards and backwards through one instance. A
+/// decision that depended on what had been evaluated before would differ.
+#[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.
+///
+/// `cargo test` may run the tests above in one process on one thread pool.
+/// This re-runs the corpus in a child process with an independently created
+/// engine, which is the strongest process boundary this harness can establish
+/// without shipping a second binary.
+#[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)
+    );
+
+    // And the parent's own answers still match the committed expectations, so
+    // the child agreeing with itself is not the whole claim.
+    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 and no entropy source in scope — not because they were denied at
+/// call time, but because no such function is linked. It says nothing about
+/// hostile modules, which is a different claim this suite does not make.
+#[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.
+///
+/// The companion to the import check, from the host's side: nothing is
+/// provided, and instantiation still succeeds, so no capability is being
+/// supplied implicitly by the runtime.
+#[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.
+///
+/// The exported surface is memory plus four functions. There is no export that
+/// writes state, creates work, or names a FeltDB concept: the module's only
+/// possible effect on FeltDB is the bytes it returns.
+#[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.
+///
+/// A trap would be a runtime-specific outcome rather than a contract decision,
+/// and the two implementations could not be compared through it.
+#[test]
+fn wasm_contract_returns_a_decision_for_every_input_including_malformed() {
+    let Some(bytes) = contract_module() else {
+        return skipped("wasm_contract_returns_a_decision_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"], TRIGGER_MATCH_CONTRACT_ID);
+        assert!(
+            parsed.get("outcome").is_some() ^ parsed.get("error").is_some(),
+            "{} produced neither or both of outcome and error",
+            case.name
+        );
+    }
+    // Inputs no fixture would contain, to show the trap-freedom is not a
+    // property of the corpus.
+    for hostile in [
+        vec![0u8; 0],
+        vec![0xff; 64],
+        b"{".repeat(4096),
+        b"[".repeat(4096),
+        vec![b'"'; 1024],
+    ] {
+        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,
+}
+
+const MUTATIONS: &[Mutation] = &[
+    Mutation {
+        name: "predicate comparison always succeeds",
+        file: "src/lib.rs",
+        from: "    if !resolved.equals(predicate.equals) {",
+        to: "    if false {",
+    },
+    Mutation {
+        name: "collection comparison is case-insensitive",
+        file: "src/lib.rs",
+        from: "    if change.collection != trigger.source_collection {",
+        to: "    if !change.collection.eq_ignore_ascii_case(trigger.source_collection) {",
+    },
+    Mutation {
+        name: "disabled triggers are accepted",
+        file: "src/lib.rs",
+        from: "    if !trigger.enabled {",
+        to: "    if false {",
+    },
+    Mutation {
+        name: "a null record value counts as absent",
+        file: "src/lib.rs",
+        from: "    let Some(value) = change.value else {",
+        to: "    let Some(value) = change.value.filter(|value| **value != Json::Null) else {",
+    },
+    Mutation {
+        name: "change kind is never compared",
+        file: "src/lib.rs",
+        from: "    if change.change_kind != trigger.change_kind {",
+        to: "    if false {",
+    },
+    Mutation {
+        name: "output encoding renames a member",
+        file: "src/lib.rs",
+        from: r#"out.extend_from_slice(b"\",\"outcome\":{\"matched\":");"#,
+        to: r#"out.extend_from_slice(b"\",\"result\":{\"matched\":");"#,
+    },
+    Mutation {
+        name: "integers and floats compare equal",
+        file: "src/json.rs",
+        from: "            (Json::Float(left), Json::Float(right)) => left == right,",
+        to: "            (Json::Float(left), Json::Float(right)) => left == right,\n            (Json::PosInt(left), Json::Float(right)) => *left as f64 == *right,\n            (Json::Float(left), Json::PosInt(right)) => *left == *right as f64,",
+    },
+];
+
+/// Every deliberate mutation of the WASM contract is caught by the corpus.
+///
+/// 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, and must fail against the
+/// committed expectations.
+#[test]
+fn deliberate_wasm_mutations_are_detected() {
+    if contract_module().is_none() {
+        return skipped("deliberate_wasm_mutations_are_detected");
+    }
+    let source = repository_root().join(WASM_CRATE);
+    let scratch = tempfile::tempdir().expect("a scratch directory");
+
+    let mut undetected = 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 caught.first() {
+            Some(first) => println!(
+                "mutation {:?} caught by {} fixtures, first: {first}",
+                mutation.name,
+                caught.len()
+            ),
+            None => undetected.push(mutation.name),
+        }
+    }
+    assert!(
+        undetected.is_empty(),
+        "the corpus does not distinguish these mutations from correct behaviour: {undetected:?}"
+    );
+}
+
+/// 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 canonical encoding is detected where the encoding is
+/// semantically load-bearing, and not where it is not.
+///
+/// This is the honest shape of the result. Three encoder mutations are applied
+/// to well-formed cases and fed to both implementations:
+///
+/// - conflating an absent record value with `null` changes a decision, and
+///   both implementations change it together, so only the committed
+///   expectations catch it;
+/// - dropping the contract identity turns every case into an input error,
+///   likewise caught by the expectations; and
+/// - emitting members in non-sorted order changes nothing, because JSON object
+///   equality is by member and both parsers agree. The suite correctly does
+///   not flag it, and the contract does not claim byte-canonical input.
+#[test]
+fn canonicalization_mutations_are_detected_where_they_matter() {
+    let cases: 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!(cases.len() > 40, "most of the corpus is typed input");
+
+    // 1. Absence conflated with null.
+    let mut changed = 0;
+    for (case, encoded) in &cases {
+        let mut mutated = encoded.clone();
+        if mutated["change"].get("value").is_none() {
+            mutated["change"]["value"] = Value::Null;
+        }
+        let produced = String::from_utf8(evaluate_canonical(
+            serde_json::to_vec(&mutated).unwrap().as_slice(),
+        ))
+        .unwrap();
+        if produced != case.expected() {
+            changed += 1;
+        }
+    }
+    assert!(
+        changed > 0,
+        "an encoder that writes null for an absent record value must change a decision"
+    );
+
+    // 2. Contract identity dropped.
+    for (case, encoded) in cases.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"));
+    }
+
+    // 3. Member order, which carries no meaning.
+    for (case, encoded) in &cases {
+        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
+        );
+    }
+}
+
+/// 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_TRIGGER_CONTRACT_BLESS=1 cargo test -p feltdb --test
+/// trigger_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_TRIGGER_CONTRACT_BLESS").as_deref(),
+        Ok("1"),
+        "set FELTDB_TRIGGER_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());
+}