@feltdb/core 0.8.3 → 0.8.5

package/dist/create/server-source/crates/feltdb/src/sharding.rs

@@ -8,7 +8,6 @@
  * - Query routing to appropriate shards
  * - Data migration between shards
  */
-
 use serde::{Deserialize, Serialize};
 use std::collections::{BTreeMap, HashMap, HashSet};
 
@@ -189,7 +188,9 @@ impl ShardManager {
                 }
                 "delete" => {
                     metrics.entry_count = metrics.entry_count.saturating_sub(records_affected);
-                    metrics.size_bytes = metrics.size_bytes.saturating_sub(size_bytes.min(metrics.size_bytes));
+                    metrics.size_bytes = metrics
+                        .size_bytes
+                        .saturating_sub(size_bytes.min(metrics.size_bytes));
                 }
                 _ => {}
             }
@@ -253,7 +254,9 @@ impl ShardManager {
             }
 
             // High write load
-            if write_std_dev > 0.0 && (metrics.writes as f64 - avg_writes).abs() > write_std_dev * 2.0 {
+            if write_std_dev > 0.0
+                && (metrics.writes as f64 - avg_writes).abs() > write_std_dev * 2.0
+            {
                 alerts.push(HotspotAlert {
                     shard_id: metrics.shard_id.clone(),
                     reason: "High write load".to_string(),
@@ -269,7 +272,9 @@ impl ShardManager {
             }
 
             // Data imbalance
-            if entry_std_dev > 0.0 && (metrics.entry_count as f64 - avg_entries).abs() > entry_std_dev * 3.0 {
+            if entry_std_dev > 0.0
+                && (metrics.entry_count as f64 - avg_entries).abs() > entry_std_dev * 3.0
+            {
                 alerts.push(HotspotAlert {
                     shard_id: metrics.shard_id.clone(),
                     reason: "Data imbalance".to_string(),
@@ -297,13 +302,22 @@ impl ShardManager {
         for hotspot in hotspots {
             if hotspot.severity == "high" {
                 // Find the overloaded shard
-                if let Some(shard_range) = self.shard_ranges.iter().find(|r| r.shard_id == hotspot.shard_id) {
+                if let Some(shard_range) = self
+                    .shard_ranges
+                    .iter()
+                    .find(|r| r.shard_id == hotspot.shard_id)
+                {
                     // Split the hash range in half
-                    let mid_hash = (shard_range.start_hash as u128 + shard_range.end_hash as u128) / 2;
+                    let mid_hash =
+                        (shard_range.start_hash as u128 + shard_range.end_hash as u128) / 2;
                     let mid_hash = mid_hash as u64;
 
                     // Create a new shard ID for the split
-                    let new_shard_id = ShardId(format!("{}-split-{}", hotspot.shard_id.0, current_time_ms()));
+                    let new_shard_id = ShardId(format!(
+                        "{}-split-{}",
+                        hotspot.shard_id.0,
+                        current_time_ms()
+                    ));
 
                     operations.push(RebalanceOperation {
                         source_shard: hotspot.shard_id.clone(),
@@ -415,7 +429,10 @@ mod tests {
             ShardingStrategy::ConsistentHash,
         );
 
-        let shards = vec![ShardId("shard-0".to_string()), ShardId("shard-1".to_string())];
+        let shards = vec![
+            ShardId("shard-0".to_string()),
+            ShardId("shard-1".to_string()),
+        ];
         let mut replicas = HashMap::new();
         replicas.insert("shard-0".to_string(), vec!["node-1".to_string()]);
         replicas.insert("shard-1".to_string(), vec!["node-2".to_string()]);
@@ -435,7 +452,10 @@ mod tests {
             ShardingStrategy::ConsistentHash,
         );
 
-        let shards = vec![ShardId("shard-0".to_string()), ShardId("shard-1".to_string())];
+        let shards = vec![
+            ShardId("shard-0".to_string()),
+            ShardId("shard-1".to_string()),
+        ];
         manager.initialize_shards(shards, HashMap::new());
 
         let shard = manager.get_shard_for_key("user123");
@@ -510,7 +530,13 @@ mod tests {
         manager.initialize_shards(shards, HashMap::new());
 
         // Create severe imbalanced load across 3 shards
-        manager.record_shard_operation(&ShardId("shard-0".to_string()), "write", 5.0, 100000, 50000000);
+        manager.record_shard_operation(
+            &ShardId("shard-0".to_string()),
+            "write",
+            5.0,
+            100000,
+            50000000,
+        );
         manager.record_shard_operation(&ShardId("shard-1".to_string()), "write", 5.0, 1000, 500000);
         manager.record_shard_operation(&ShardId("shard-2".to_string()), "write", 5.0, 100, 50000);
 

package/dist/create/server-source/crates/feltdb/src/state_conflict_contract.rs

@@ -0,0 +1,516 @@
+//! The deterministic contract behind FeltDB's conflict classification.
+//!
+//! The third specimen of the pattern established by [`crate::trigger_contract`]
+//! and [`crate::state_diff_contract`], and the first that reasons over
+//! *competing* changes rather than deciding or computing over one input.
+//!
+//! ```text
+//!        base + left + right, as canonical content
+//!                        │
+//!         ┌──────────────┴──────────────┐
+//!         │                             │
+//!   native evaluation             WASM evaluation
+//!         │                             │
+//!         └──────────────┬──────────────┘
+//!                        │
+//!            canonical classification bytes
+//! ```
+//!
+//! # This module adds no classification semantics
+//!
+//! [`ConflictClassification::classify`] is untouched and remains authoritative.
+//! Everything here is envelope: identity, version, canonical encoding, and the
+//! decision to report an unusable input rather than fail. If this module and
+//! `classify` ever disagree, `classify` is right.
+//!
+//! # Why the input is three strings and not three revisions
+//!
+//! `classify` takes three [`StateRevision`]s and reads exactly one field of
+//! each: `content`. It never looks at `id`, `parent_id`, `authority`,
+//! `timestamp_ms` or `metadata`, and a unit test in this module proves it.
+//!
+//! Taking revisions into the contract would therefore drag a clock reading into
+//! it for nothing — `StateRevision::initial` calls `SystemTime::now()` — along
+//! with an authority identity that has no bearing on the answer. The contract
+//! takes the three content strings instead, which is the real semantic
+//! boundary.
+//!
+//! It is a *string* rather than parsed JSON on purpose: `classify` parses with
+//! `unwrap_or(Value::Null)`, so content that is not JSON classifies as JSON
+//! null instead of failing. That tolerance is part of the semantics, and a
+//! contract taking parsed values could not express it.
+//!
+//! # Determinism budget
+//!
+//! Evaluation reads nothing but its three strings. No clock, filesystem,
+//! network, random source, process identity, authentication context, authority
+//! metadata, revision identity, timestamp, operation provenance or
+//! process-global mutable state participates, and the audit found none in the
+//! implementation either.
+//!
+//! # What the audit established about the semantics
+//!
+//! Recorded here because the contract is defined against the implementation's
+//! actual behaviour rather than against an idea of what a three-way merge
+//! should do. Several of these will surprise a reader who expects a merge tool.
+//!
+//! - **There are three classes and no fourth.** `Independent`, `Convergent`,
+//!   `Conflict`. There is no "no change" class: `classify(a, a, a)` returns an
+//!   empty conflict list whose `overall` is `Independent`.
+//! - **Classification is per overlapping path.** Two changes interact when
+//!   their paths are equal *or* when one contains the other. A branch replacing
+//!   `o` and a branch editing `o.a` cannot both be applied, so both paths are
+//!   `Conflict`. Overlap is structural, over whole path components, so `a.b`
+//!   and `a.bc` are disjoint. Version 1 of this contract collided on equal
+//!   paths only and reported that case as `Independent`; see
+//!   [state model](../../../docs/architecture/state-conflict-semantics.md).
+//! - **Convergence ignores `old_value`.** Two sides agree when their change
+//!   kind and their new value are equal, so both removing a member is
+//!   `Convergent`, and both adding the same value is `Convergent`.
+//! - **Differing kinds always conflict**, even when the outcome would agree —
+//!   removing on one side and changing on the other is a `Conflict`. The kind
+//!   half of the convergence test cannot actually decide anything, though:
+//!   both diffs share a base, so whether a path resolves in it is a property of
+//!   the base alone, and the one kind pair that can differ — `Removed` against
+//!   `Changed` — always disagrees on the new value too, because a removal has
+//!   none. The conformance suite asserts that redundancy rather than assuming
+//!   it, and it is why relabelling a change kind is invisible to this
+//!   contract while the diff contract catches it.
+//! - **`base_value` is the common ancestor's value at the path**, read from the
+//!   base state. Version 1 read it from the left branch's change, which
+//!   reported `null` for a path only the right branch touched even when the
+//!   base held a value there. Correcting it makes the whole result symmetric
+//!   under a branch swap apart from the two branch values exchanging.
+//! - **Absent and null collapse in the recorded values.** All three value
+//!   fields are `Option<Value>` flattened from an optional change, so "no
+//!   change here" and "the value is JSON null" both encode as `null`. The
+//!   `classification` field is what carries the meaning.
+//! - **`overall` is the maximum severity present**: `Conflict` if any path
+//!   conflicts, else `Convergent` if any path converges, else `Independent`.
+//! - **Ordering is total.** Paths are unique — they are the union of two
+//!   path-keyed maps — and the result is sorted by path.
+//! - **Diff semantics are inherited**, including positional arrays, so the same
+//!   index changed on both sides conflicts while different indexes remain
+//!   independent — under positional semantics both index changes survive a
+//!   merge. Removing an array element while the other branch edits inside it
+//!   *is* an overlap, and conflicts.
+
+use crate::state_model::{ConflictClassification, StateId, StateRevision};
+use serde::{Deserialize, Serialize};
+use sha2::{Digest, Sha256};
+use std::collections::BTreeMap;
+
+/// Stable identity of this contract.
+pub const STATE_CONFLICT_CONTRACT_ID: &str = "feltdb.state.conflict";
+
+/// Version of this contract's input shape, output shape and semantics.
+///
+/// The output shape is [`ConflictClassification`]'s own serialization, so a
+/// change to that type is a change to this contract and must bump this.
+pub const STATE_CONFLICT_CONTRACT_VERSION: u32 = 2;
+
+/// The complete deterministic input: three state contents, and the contract's
+/// identity.
+///
+/// Members are declared alphabetically so the canonical struct encoding matches
+/// the sorted-key encoding `serde_json` gives every JSON object.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct StateConflictInput {
+    /// The common ancestor's content.
+    pub base: String,
+    pub contract: String,
+    /// The first branch's content.
+    pub left: String,
+    /// The second branch's content.
+    pub right: String,
+    pub version: u32,
+}
+
+impl StateConflictInput {
+    /// Builds an input stamped with this contract's identity and version.
+    pub fn new(base: String, left: String, right: String) -> Self {
+        Self {
+            base,
+            contract: STATE_CONFLICT_CONTRACT_ID.to_string(),
+            left,
+            right,
+            version: STATE_CONFLICT_CONTRACT_VERSION,
+        }
+    }
+}
+
+/// Why an input could not be evaluated.
+///
+/// The same three codes the other two contracts use. Note that unparseable
+/// *state content* is not one of them: that is a classification, not an error.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "SCREAMING_SNAKE_CASE")]
+pub enum ContractErrorCode {
+    /// The bytes are not a well-formed instance of this contract's input.
+    ContractInputInvalid,
+    /// The input declares a different contract.
+    ContractIdMismatch,
+    /// The input declares a version this implementation does not implement.
+    ContractVersionUnsupported,
+}
+
+/// The error body of a contract output.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct ContractErrorBody {
+    pub code: ContractErrorCode,
+}
+
+/// The complete deterministic output.
+///
+/// Exactly one of `classification` and `error` is present. `classification` is
+/// [`ConflictClassification`] serialized exactly as it already serializes —
+/// this contract does not reshape it, because the existing result is the
+/// contract.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct StateConflictOutput {
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub classification: Option<ConflictClassification>,
+    pub contract: String,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub error: Option<ContractErrorBody>,
+    pub version: u32,
+}
+
+impl StateConflictOutput {
+    fn classified(classification: ConflictClassification) -> Self {
+        Self {
+            classification: Some(classification),
+            contract: STATE_CONFLICT_CONTRACT_ID.to_string(),
+            error: None,
+            version: STATE_CONFLICT_CONTRACT_VERSION,
+        }
+    }
+
+    fn failure(code: ContractErrorCode) -> Self {
+        Self {
+            classification: None,
+            contract: STATE_CONFLICT_CONTRACT_ID.to_string(),
+            error: Some(ContractErrorBody { code }),
+            version: STATE_CONFLICT_CONTRACT_VERSION,
+        }
+    }
+}
+
+/// The runtime that executed a contract, recorded in evidence.
+///
+/// Only [`ContractRuntime::Native`] is wired anywhere.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum ContractRuntime {
+    Native,
+    Wasm,
+}
+
+impl ContractRuntime {
+    pub fn as_str(self) -> &'static str {
+        match self {
+            Self::Native => "native",
+            Self::Wasm => "wasm",
+        }
+    }
+}
+
+/// Wraps state content in the revision shape `classify` expects.
+///
+/// Every field but `content` is fixed, because `classify` reads no other field
+/// and the contract must not acquire an input the decision does not use. In
+/// particular nothing here reads a clock, unlike `StateRevision::initial`.
+fn revision(content: &str) -> StateRevision {
+    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: BTreeMap::new(),
+    }
+}
+
+/// The deterministic contract, natively implemented.
+///
+/// A thin adapter over the existing implementation, deliberately holding no
+/// classification logic of its own.
+pub fn classify_states(base: &str, left: &str, right: &str) -> ConflictClassification {
+    ConflictClassification::classify(&revision(base), &revision(left), &revision(right))
+}
+
+/// The canonical byte encoding of a contract input.
+pub fn canonical_input_bytes(input: &StateConflictInput) -> Vec<u8> {
+    serde_json::to_vec(input).expect("contract input is always serializable")
+}
+
+/// The canonical byte encoding of a contract output.
+pub fn canonical_output_bytes(output: &StateConflictOutput) -> Vec<u8> {
+    serde_json::to_vec(output).expect("contract output is always serializable")
+}
+
+/// Content identity of a contract input, for provenance.
+pub fn input_digest(input: &StateConflictInput) -> String {
+    format!("sha256:{:x}", Sha256::digest(canonical_input_bytes(input)))
+}
+
+/// The runtime-independent entry point: canonical bytes in, canonical bytes out.
+///
+/// Never panics and never returns anything but a canonical output encoding, so
+/// an unusable input is a contract decision rather than a host-specific failure
+/// mode. Unparseable *state content* is not an unusable input: it classifies as
+/// JSON null, which is what the existing implementation does.
+pub fn evaluate_canonical(input: &[u8]) -> Vec<u8> {
+    canonical_output_bytes(&evaluate_canonical_output(input))
+}
+
+/// [`evaluate_canonical`] before encoding, for callers that want the value.
+pub fn evaluate_canonical_output(input: &[u8]) -> StateConflictOutput {
+    let Ok(parsed) = serde_json::from_slice::<StateConflictInput>(input) else {
+        return StateConflictOutput::failure(ContractErrorCode::ContractInputInvalid);
+    };
+    if parsed.contract != STATE_CONFLICT_CONTRACT_ID {
+        return StateConflictOutput::failure(ContractErrorCode::ContractIdMismatch);
+    }
+    if parsed.version != STATE_CONFLICT_CONTRACT_VERSION {
+        return StateConflictOutput::failure(ContractErrorCode::ContractVersionUnsupported);
+    }
+    StateConflictOutput::classified(classify_states(&parsed.base, &parsed.left, &parsed.right))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::state_model::ConflictClass;
+
+    fn classify(base: &str, left: &str, right: &str) -> String {
+        String::from_utf8(canonical_output_bytes(&StateConflictOutput::classified(
+            classify_states(base, left, right),
+        )))
+        .unwrap()
+    }
+
+    fn overall(base: &str, left: &str, right: &str) -> ConflictClass {
+        classify_states(base, left, right).overall
+    }
+
+    #[test]
+    fn the_contract_reads_only_revision_content() {
+        // Two revisions differing in every field the decision does not use must
+        // classify identically. If revision identity, authority, a timestamp or
+        // metadata ever reached the classifier, the contract would stop being
+        // reproducible anywhere and this would fail.
+        let plain = revision(r#"{"x":1}"#);
+        let decorated = StateRevision {
+            id: StateId::compute("something else entirely"),
+            resource: "some:other:resource".into(),
+            content: r#"{"x":1}"#.to_string(),
+            content_id: StateId::compute("not even the content"),
+            parent_id: Some(StateId::compute("a parent")),
+            sequence: 41,
+            authority: "someone-else".into(),
+            timestamp_ms: 1_700_000_000_000,
+            metadata: [("k".to_string(), serde_json::json!("v"))]
+                .into_iter()
+                .collect(),
+        };
+        let base = revision(r#"{"x":0}"#);
+        assert_eq!(
+            serde_json::to_string(&ConflictClassification::classify(&base, &plain, &plain))
+                .unwrap(),
+            serde_json::to_string(&ConflictClassification::classify(
+                &base, &decorated, &decorated
+            ))
+            .unwrap()
+        );
+    }
+
+    #[test]
+    fn identical_states_classify_as_independent_with_no_paths() {
+        // There is no "no change" class; this is what the absence of change
+        // looks like.
+        assert_eq!(
+            classify(r#"{"x":1}"#, r#"{"x":1}"#, r#"{"x":1}"#),
+            r#"{"classification":{"path_conflicts":[],"overall":"Independent"},"contract":"feltdb.state.conflict","version":2}"#
+        );
+    }
+
+    #[test]
+    fn one_sided_changes_are_independent() {
+        assert_eq!(
+            overall(r#"{"x":1}"#, r#"{"x":2}"#, r#"{"x":1}"#),
+            ConflictClass::Independent
+        );
+        assert_eq!(
+            overall(r#"{"x":1}"#, r#"{"x":1}"#, r#"{"x":2}"#),
+            ConflictClass::Independent
+        );
+    }
+
+    #[test]
+    fn agreeing_changes_converge_and_disagreeing_ones_conflict() {
+        assert_eq!(
+            overall(r#"{"x":1}"#, r#"{"x":2}"#, r#"{"x":2}"#),
+            ConflictClass::Convergent
+        );
+        assert_eq!(
+            overall(r#"{"x":1}"#, r#"{"x":2}"#, r#"{"x":3}"#),
+            ConflictClass::Conflict
+        );
+        // Both removing the member agree, because convergence compares the
+        // change kind and the new value, and both are absent.
+        assert_eq!(overall(r#"{"x":1}"#, "{}", "{}"), ConflictClass::Convergent);
+        // Removing on one side and changing on the other does not, because the
+        // kinds differ even though a merge tool might reconcile it.
+        assert_eq!(
+            overall(r#"{"x":1}"#, "{}", r#"{"x":2}"#),
+            ConflictClass::Conflict
+        );
+    }
+
+    #[test]
+    fn an_ancestor_descendant_overlap_conflicts() {
+        // Left replaces the whole of `o` while right edits `o.a`. The paths are
+        // not equal, but one contains the other, and the two changes cannot
+        // both be applied: left decides the value of `o` that right was editing
+        // inside. Version 1 of this contract reported both paths as
+        // `Independent`, which was unsafe as a basis for reconciliation.
+        let output = classify_states(
+            r#"{"o":{"a":1}}"#,
+            r#"{"o":"replaced"}"#,
+            r#"{"o":{"a":2}}"#,
+        );
+        assert_eq!(output.overall, ConflictClass::Conflict);
+        assert_eq!(output.path_conflicts.len(), 2);
+        assert!(output
+            .path_conflicts
+            .iter()
+            .all(|entry| entry.classification == ConflictClass::Conflict));
+
+        // Removing the parent is the same overlap.
+        assert_eq!(
+            overall(r#"{"o":{"a":1}}"#, "{}", r#"{"o":{"a":2}}"#),
+            ConflictClass::Conflict
+        );
+
+        // Sibling paths under an untouched parent still do not overlap.
+        assert_eq!(
+            overall(
+                r#"{"o":{"a":1,"b":1}}"#,
+                r#"{"o":{"a":2,"b":1}}"#,
+                r#"{"o":{"a":1,"b":2}}"#
+            ),
+            ConflictClass::Independent
+        );
+        // Nor do keys that merely share a string prefix.
+        assert_eq!(
+            overall(
+                r#"{"a":{"b":1,"bc":1}}"#,
+                r#"{"a":{"b":2,"bc":1}}"#,
+                r#"{"a":{"b":1,"bc":2}}"#
+            ),
+            ConflictClass::Independent
+        );
+    }
+
+    #[test]
+    fn base_value_is_the_base_states_value_at_the_path() {
+        // The base holds 1 at `x` and only the right branch changed it.
+        // Version 1 read `base_value` from the left branch's change and so
+        // reported `null` here, losing the ancestor's value exactly where a
+        // reconciler would need it.
+        let output = classify_states(r#"{"x":1}"#, r#"{"x":1}"#, r#"{"x":2}"#);
+        let entry = &output.path_conflicts[0];
+        assert_eq!(entry.base_value, Some(serde_json::json!(1)));
+        assert_eq!(entry.left_value, None, "the left branch changed nothing");
+        assert_eq!(entry.right_value, Some(serde_json::json!(2)));
+
+        // A path the base does not hold has no base value.
+        let added = classify_states("{}", r#"{"x":1}"#, "{}");
+        assert_eq!(added.path_conflicts[0].base_value, None);
+
+        // And it does not depend on which branch is called left.
+        let forward = classify_states(r#"{"x":1}"#, r#"{"x":1}"#, r#"{"x":2}"#);
+        let reversed = classify_states(r#"{"x":1}"#, r#"{"x":2}"#, r#"{"x":1}"#);
+        assert_eq!(
+            forward.path_conflicts[0].base_value,
+            reversed.path_conflicts[0].base_value
+        );
+    }
+
+    #[test]
+    fn unparseable_content_classifies_as_json_null_rather_than_failing() {
+        // `classify` parses with `unwrap_or(Value::Null)`. Both sides moving
+        // from unparseable base to the same state therefore converge.
+        let output = classify_states("not json at all", r#"{"x":1}"#, r#"{"x":1}"#);
+        assert_eq!(output.overall, ConflictClass::Convergent);
+        assert_eq!(output.path_conflicts[0].path, vec![]);
+
+        // And it is a classification, not a contract error.
+        let bytes =
+            canonical_input_bytes(&StateConflictInput::new("{".into(), "}".into(), "]".into()));
+        let parsed = evaluate_canonical_output(&bytes);
+        assert!(parsed.error.is_none());
+        assert!(parsed.classification.is_some());
+    }
+
+    #[test]
+    fn unevaluatable_inputs_are_decisions_rather_than_failures() {
+        for (bytes, code) in [
+            (&b"not json"[..], ContractErrorCode::ContractInputInvalid),
+            (
+                br#"{"base":"{}","contract":"other","left":"{}","right":"{}","version":2}"#,
+                ContractErrorCode::ContractIdMismatch,
+            ),
+            (
+                br#"{"base":"{}","contract":"feltdb.state.conflict","left":"{}","right":"{}","version":9}"#,
+                ContractErrorCode::ContractVersionUnsupported,
+            ),
+        ] {
+            let output = evaluate_canonical_output(bytes);
+            assert_eq!(output.error.map(|error| error.code), Some(code));
+            assert!(output.classification.is_none());
+        }
+    }
+
+    #[test]
+    fn canonical_round_trip_is_stable() {
+        let input = StateConflictInput::new(
+            r#"{"x":1}"#.into(),
+            r#"{"x":2}"#.into(),
+            r#"{"x":3}"#.into(),
+        );
+        let once = canonical_input_bytes(&input);
+        let parsed: StateConflictInput = serde_json::from_slice(&once).unwrap();
+        assert_eq!(parsed, input);
+        assert_eq!(canonical_input_bytes(&parsed), once);
+        assert_eq!(input_digest(&parsed), input_digest(&input));
+    }
+
+    #[test]
+    fn the_adapter_is_the_existing_classifier() {
+        // The adapter must be the classification FeltDB already computes, not a
+        // second one that happens to agree.
+        for (base, left, right) in [
+            (r#"{"x":1}"#, r#"{"x":2}"#, r#"{"x":3}"#),
+            (r#"{"a":1,"b":1}"#, r#"{"a":2,"b":1}"#, r#"{"a":1,"b":2}"#),
+            ("[1,2]", "[9,2]", "[8,2]"),
+        ] {
+            assert_eq!(
+                serde_json::to_string(&classify_states(base, left, right)).unwrap(),
+                serde_json::to_string(&ConflictClassification::classify(
+                    &revision(base),
+                    &revision(left),
+                    &revision(right)
+                ))
+                .unwrap()
+            );
+        }
+    }
+}