@feltdb/core 0.8.3 → 0.8.5

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

@@ -0,0 +1,868 @@
+//! Applying an explicit `ReconciliationPlan` to materialize a state.
+//!
+//! ```text
+//!     Classification  — which changes can coexist?
+//!     Plan            — what happens to the ones that cannot?
+//!     Application     — produce the resulting state from that decision.
+//! ```
+//!
+//! These tests establish the application semantics, that inputs are never
+//! mutated, that invalid plans are rejected rather than producing arbitrary
+//! state, and the whole causal path from three revisions to a materialized one.
+//!
+//! Nothing here advances a branch head, merges automatically, or reconciles
+//! anything FeltDB was not explicitly told to.
+
+use feltdb::state_model::{
+    apply_reconciliation_plan, reconcile, ConflictClass, ConflictClassification, PathComponent,
+    ReconciliationPlan, SemanticDiff, StateId, StateRevision, StateStore,
+    RECONCILE_CONTENT_UNPARSEABLE, RECONCILE_OVERRIDE_PATHS_OVERLAP,
+    RECONCILE_OVERRIDE_UNADDRESSABLE, RECONCILE_PLAN_INVALID, RECONCILE_REVISION_MISMATCH,
+};
+use serde_json::{json, Value};
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/// A revision with fixed metadata, so tests compare states rather than clocks.
+fn revision(content: &str) -> StateRevision {
+    StateRevision {
+        id: StateId::compute(content),
+        resource: "docs:1".into(),
+        content: content.to_string(),
+        content_id: StateId::compute(content),
+        parent_id: None,
+        sequence: 0,
+        authority: "test".into(),
+        timestamp_ms: 0,
+        metadata: Default::default(),
+    }
+}
+
+fn key(name: &str) -> PathComponent {
+    PathComponent::Key(name.to_string())
+}
+
+const LEFT: bool = true;
+const RIGHT: bool = false;
+
+/// The three revisions a scenario compares, and a plan builder over them.
+struct Scenario {
+    base: StateRevision,
+    left: StateRevision,
+    right: StateRevision,
+}
+
+impl Scenario {
+    fn new(base: &str, left: &str, right: &str) -> Self {
+        Self {
+            base: revision(base),
+            left: revision(left),
+            right: revision(right),
+        }
+    }
+
+    fn plan(&self, parent_choice: bool) -> ReconciliationPlan {
+        ReconciliationPlan::new(
+            self.left.id.clone(),
+            self.right.id.clone(),
+            self.base.id.clone(),
+            parent_choice,
+        )
+    }
+
+    fn apply(&self, plan: &ReconciliationPlan) -> Result<String, String> {
+        apply_reconciliation_plan(&self.base, &self.left, &self.right, plan)
+    }
+
+    /// The applied result as a value, for comparing states rather than text.
+    fn applied(&self, plan: &ReconciliationPlan) -> Value {
+        serde_json::from_str(&self.apply(plan).expect("the plan applies")).unwrap()
+    }
+
+    fn classification(&self) -> ConflictClassification {
+        ConflictClassification::classify(&self.base, &self.left, &self.right)
+    }
+}
+
+/// The error code an application failed with.
+fn code(result: Result<String, String>) -> String {
+    let message = result.expect_err("the plan must be rejected");
+    message
+        .split_once(':')
+        .map(|(code, _)| code.to_string())
+        .unwrap_or(message)
+}
+
+// ---------------------------------------------------------------------------
+// Parent choice
+// ---------------------------------------------------------------------------
+
+/// `parent_choice` selects the state to start from, and has exactly two values.
+///
+/// The field is a `bool`, so there is no third choice and no "unknown parent
+/// choice" for application to reject — the type forecloses it. The ancestor is
+/// not selectable.
+#[test]
+fn parent_choice_selects_the_starting_state() {
+    let scenario = Scenario::new(r#"{"a":1,"b":1}"#, r#"{"a":2,"b":1}"#, r#"{"a":1,"b":2}"#);
+
+    assert_eq!(scenario.applied(&scenario.plan(LEFT)), json!({"a":2,"b":1}));
+    assert_eq!(
+        scenario.applied(&scenario.plan(RIGHT)),
+        json!({"a":1,"b":2})
+    );
+
+    // With no overrides the result is exactly the selected branch's state, not
+    // a merge of the two. Independent changes on the branch not selected are
+    // not carried over: the plan did not ask for them.
+    assert_ne!(
+        scenario.applied(&scenario.plan(LEFT)),
+        json!({"a":2,"b":2}),
+        "application never merges on its own"
+    );
+}
+
+// ---------------------------------------------------------------------------
+// Override semantics
+// ---------------------------------------------------------------------------
+
+#[test]
+fn an_override_replaces_a_value() {
+    let scenario = Scenario::new(r#"{"a":1}"#, r#"{"a":2}"#, r#"{"a":3}"#);
+    let plan = scenario.plan(LEFT).with_override(vec![key("a")], json!(9));
+    assert_eq!(scenario.applied(&plan), json!({"a":9}));
+}
+
+#[test]
+fn an_override_may_add_a_member_to_an_existing_object() {
+    // Assigning a new member creates no structure, so it is addressable. This
+    // is how a plan takes a member the other branch added.
+    let scenario = Scenario::new(r#"{"o":{}}"#, r#"{"o":{}}"#, r#"{"o":{"added":1}}"#);
+    let plan = scenario
+        .plan(LEFT)
+        .with_override(vec![key("o"), key("added")], json!(1));
+    assert_eq!(scenario.applied(&plan), json!({"o":{"added":1}}));
+}
+
+#[test]
+fn an_override_can_set_null_but_cannot_express_removal() {
+    let scenario = Scenario::new(r#"{"a":1,"b":2}"#, r#"{"a":1,"b":2}"#, r#"{"a":1}"#);
+
+    // Null is a value, and setting it is an ordinary override.
+    let nulled = scenario
+        .plan(LEFT)
+        .with_override(vec![key("b")], Value::Null);
+    assert_eq!(scenario.applied(&nulled), json!({"a":1,"b":null}));
+
+    // `path_overrides` maps a path to a `Value`, and a `Value` cannot be
+    // absent. Removing a member means overriding the container that holds it.
+    let removed = scenario.plan(LEFT).with_override(vec![], json!({"a":1}));
+    assert_eq!(scenario.applied(&removed), json!({"a":1}));
+}
+
+#[test]
+fn overrides_reach_nested_paths() {
+    let scenario = Scenario::new(
+        r#"{"o":{"m":{"deep":1}}}"#,
+        r#"{"o":{"m":{"deep":2}}}"#,
+        r#"{"o":{"m":{"deep":3}}}"#,
+    );
+    let plan = scenario
+        .plan(LEFT)
+        .with_override(vec![key("o"), key("m"), key("deep")], json!(9));
+    assert_eq!(scenario.applied(&plan), json!({"o":{"m":{"deep":9}}}));
+}
+
+#[test]
+fn override_paths_are_structural_not_textual() {
+    // `a.b` and `a.bc` share a string prefix and are different locations.
+    let scenario = Scenario::new(
+        r#"{"a":{"b":1,"bc":1}}"#,
+        r#"{"a":{"b":2,"bc":1}}"#,
+        r#"{"a":{"b":1,"bc":2}}"#,
+    );
+    let plan = scenario
+        .plan(LEFT)
+        .with_override(vec![key("a"), key("bc")], json!(9));
+    assert_eq!(scenario.applied(&plan), json!({"a":{"b":2,"bc":9}}));
+
+    // And a key named "0" is not the first element of an array.
+    let mixed = Scenario::new(r#"{"x":{"0":1}}"#, r#"{"x":{"0":2}}"#, r#"{"x":{"0":3}}"#);
+    let by_key = mixed
+        .plan(LEFT)
+        .with_override(vec![key("x"), key("0")], json!(9));
+    assert_eq!(mixed.applied(&by_key), json!({"x":{"0":9}}));
+    let by_index = mixed
+        .plan(LEFT)
+        .with_override(vec![key("x"), PathComponent::Index(0)], json!(9));
+    assert_eq!(
+        code(mixed.apply(&by_index)),
+        RECONCILE_OVERRIDE_UNADDRESSABLE
+    );
+}
+
+/// A repeated override path cannot exist: `path_overrides` is a map.
+#[test]
+fn a_repeated_override_path_is_impossible_by_construction() {
+    let scenario = Scenario::new(r#"{"a":1}"#, r#"{"a":2}"#, r#"{"a":3}"#);
+    let plan = scenario
+        .plan(LEFT)
+        .with_override(vec![key("a")], json!(8))
+        .with_override(vec![key("a")], json!(9));
+    assert_eq!(plan.path_overrides.len(), 1, "the map holds one entry");
+    assert_eq!(scenario.applied(&plan), json!({"a":9}), "the later one");
+}
+
+// ---------------------------------------------------------------------------
+// Root path
+// ---------------------------------------------------------------------------
+
+#[test]
+fn the_root_path_replaces_the_whole_state() {
+    let scenario = Scenario::new(r#"{"o":{"a":1}}"#, r#"{"o":7}"#, r#"{"o":{"a":2}}"#);
+    for replacement in [
+        json!({"whole":"object"}),
+        json!([1, 2, 3]),
+        json!("scalar"),
+        json!(42),
+        Value::Null,
+    ] {
+        let plan = scenario
+            .plan(LEFT)
+            .with_override(vec![], replacement.clone());
+        assert_eq!(
+            scenario.applied(&plan),
+            replacement,
+            "the empty path is the state itself"
+        );
+    }
+}
+
+/// A root override and any other override overlap, so the plan is ambiguous.
+#[test]
+fn a_root_override_excludes_every_other_override() {
+    let scenario = Scenario::new(r#"{"a":1}"#, r#"{"a":2}"#, r#"{"a":3}"#);
+    let plan = scenario
+        .plan(LEFT)
+        .with_override(vec![], json!({"a":8}))
+        .with_override(vec![key("a")], json!(9));
+    assert_eq!(
+        code(scenario.apply(&plan)),
+        RECONCILE_OVERRIDE_PATHS_OVERLAP
+    );
+}
+
+// ---------------------------------------------------------------------------
+// Parent/child overrides
+// ---------------------------------------------------------------------------
+
+/// Overlapping override paths are rejected rather than given an invented
+/// precedence.
+///
+/// The plan is a map from path to value with no stated ordering, so a plan
+/// holding both `o` and `o.a` does not say whether the inner override refines
+/// the outer value or the outer one was meant to stand. Rather than pick one,
+/// application refuses. Overlap is the same structural relation conflict
+/// classification uses.
+#[test]
+fn overlapping_override_paths_are_rejected() {
+    let scenario = Scenario::new(r#"{"o":{"a":1}}"#, r#"{"o":{"a":2}}"#, r#"{"o":{"a":3}}"#);
+    for (one, two) in [
+        (vec![key("o")], vec![key("o"), key("a")]),
+        (vec![key("o"), key("a")], vec![key("o")]),
+        (vec![], vec![key("o")]),
+    ] {
+        let plan = scenario
+            .plan(LEFT)
+            .with_override(one, json!({"a": 8}))
+            .with_override(two, json!(9));
+        assert_eq!(
+            code(scenario.apply(&plan)),
+            RECONCILE_OVERRIDE_PATHS_OVERLAP
+        );
+    }
+
+    // Disjoint paths under a shared, un-overridden parent are fine.
+    let siblings = Scenario::new(
+        r#"{"o":{"a":1,"b":1}}"#,
+        r#"{"o":{"a":2,"b":1}}"#,
+        r#"{"o":{"a":1,"b":2}}"#,
+    );
+    let plan = siblings
+        .plan(LEFT)
+        .with_override(vec![key("o"), key("a")], json!(8))
+        .with_override(vec![key("o"), key("b")], json!(9));
+    assert_eq!(siblings.applied(&plan), json!({"o":{"a":8,"b":9}}));
+}
+
+// ---------------------------------------------------------------------------
+// Arrays
+// ---------------------------------------------------------------------------
+
+#[test]
+fn array_overrides_are_positional() {
+    let scenario = Scenario::new(
+        r#"{"xs":[1,2,3]}"#,
+        r#"{"xs":[9,2,3]}"#,
+        r#"{"xs":[1,8,3]}"#,
+    );
+
+    // Replacing one element leaves the others alone.
+    let replaced = scenario
+        .plan(LEFT)
+        .with_override(vec![key("xs"), PathComponent::Index(1)], json!(8));
+    assert_eq!(scenario.applied(&replaced), json!({"xs":[9,8,3]}));
+
+    // Two different indexes are disjoint paths, so both survive.
+    let both = scenario
+        .plan(LEFT)
+        .with_override(vec![key("xs"), PathComponent::Index(0)], json!(7))
+        .with_override(vec![key("xs"), PathComponent::Index(2)], json!(6));
+    assert_eq!(scenario.applied(&both), json!({"xs":[7,2,6]}));
+
+    // Length changes go through the array itself. There is no separate array
+    // merge algorithm: the plan is authoritative.
+    for (label, value) in [
+        ("append", json!([1, 2, 3, 4])),
+        ("remove", json!([1, 2])),
+        ("prepend", json!([0, 1, 2, 3])),
+        ("empty", json!([])),
+        ("to an object", json!({"0":1})),
+        ("to a scalar", json!("flat")),
+    ] {
+        let plan = scenario
+            .plan(LEFT)
+            .with_override(vec![key("xs")], value.clone());
+        assert_eq!(
+            scenario.applied(&plan),
+            json!({ "xs": value }),
+            "{label} is expressed by overriding the array"
+        );
+    }
+}
+
+#[test]
+fn an_index_past_the_end_is_rejected() {
+    let scenario = Scenario::new(r#"{"xs":[1,2]}"#, r#"{"xs":[9,2]}"#, r#"{"xs":[1,8]}"#);
+    for index in [2usize, 3, 99] {
+        let plan = scenario
+            .plan(LEFT)
+            .with_override(vec![key("xs"), PathComponent::Index(index)], json!(0));
+        assert_eq!(
+            code(scenario.apply(&plan)),
+            RECONCILE_OVERRIDE_UNADDRESSABLE,
+            "index {index} would require inventing the elements before it"
+        );
+    }
+}
+
+#[test]
+fn overrides_reach_inside_array_elements() {
+    let scenario = Scenario::new(
+        r#"{"xs":[{"a":1},{"b":[1]}]}"#,
+        r#"{"xs":[{"a":2},{"b":[1]}]}"#,
+        r#"{"xs":[{"a":1},{"b":[2]}]}"#,
+    );
+    let plan = scenario.plan(LEFT).with_override(
+        vec![
+            key("xs"),
+            PathComponent::Index(1),
+            key("b"),
+            PathComponent::Index(0),
+        ],
+        json!(9),
+    );
+    assert_eq!(scenario.applied(&plan), json!({"xs":[{"a":2},{"b":[9]}]}));
+}
+
+// ---------------------------------------------------------------------------
+// Canonical output
+// ---------------------------------------------------------------------------
+
+/// The result is canonical, whatever the selected parent's content looked like.
+///
+/// Content identity is the hash of the content string, so two revisions holding
+/// the same state with differently ordered members are different revisions.
+/// Applying an equivalent plan to either produces the *same* canonical content,
+/// and therefore the same identity.
+#[test]
+fn the_result_is_canonical_regardless_of_the_parents_representation() {
+    let sorted = Scenario::new(r#"{"a":1,"b":1}"#, r#"{"a":2,"b":1}"#, r#"{"a":1,"b":2}"#);
+    let unsorted = Scenario::new(r#"{"b":1,"a":1}"#, r#"{"b":1,"a":2}"#, r#"{"a":1,"b":2}"#);
+
+    assert_ne!(
+        sorted.left.id, unsorted.left.id,
+        "differently ordered content is a different revision"
+    );
+
+    let one = sorted.apply(&sorted.plan(LEFT)).unwrap();
+    let two = unsorted.apply(&unsorted.plan(LEFT)).unwrap();
+    assert_eq!(one, two, "both applications produce canonical content");
+    assert_eq!(one, r#"{"a":2,"b":1}"#);
+    assert_eq!(
+        StateId::compute(&one),
+        StateId::compute(&two),
+        "so they have the same content identity"
+    );
+}
+
+/// Repeated application produces the same bytes, and the result is a fixed
+/// point of the diff.
+#[test]
+fn application_is_repeatable_and_the_result_is_a_fixed_point() {
+    let scenario = Scenario::new(
+        r#"{"o":{"a":1},"xs":[1,2]}"#,
+        r#"{"o":{"a":2},"xs":[9,2]}"#,
+        r#"{"o":{"a":3},"xs":[1,8]}"#,
+    );
+    let plan = scenario
+        .plan(LEFT)
+        .with_override(vec![key("o"), key("a")], json!(5))
+        .with_override(vec![key("xs"), PathComponent::Index(1)], json!(8));
+
+    let first = scenario.apply(&plan).expect("applies");
+    for _ in 0..8 {
+        assert_eq!(scenario.apply(&plan).expect("applies"), first);
+    }
+
+    let result: Value = serde_json::from_str(&first).unwrap();
+    assert!(
+        SemanticDiff::compute(&result, &result).changes.is_empty(),
+        "the result does not differ from itself"
+    );
+}
+
+// ---------------------------------------------------------------------------
+// Immutability
+// ---------------------------------------------------------------------------
+
+/// Applying a plan mutates nothing it was given.
+#[test]
+fn application_mutates_none_of_its_inputs() {
+    let scenario = Scenario::new(r#"{"o":{"a":1}}"#, r#"{"o":{"a":2}}"#, r#"{"o":{"a":3}}"#);
+    let plan = scenario
+        .plan(LEFT)
+        .with_override(vec![key("o"), key("a")], json!(9));
+
+    let before = (
+        serde_json::to_string(&scenario.base).unwrap(),
+        serde_json::to_string(&scenario.left).unwrap(),
+        serde_json::to_string(&scenario.right).unwrap(),
+        format!("{plan:?}"),
+    );
+
+    let result = reconcile(
+        &scenario.base,
+        &scenario.left,
+        &scenario.right,
+        &plan,
+        "reconciler".into(),
+    )
+    .expect("applies");
+
+    assert_eq!(serde_json::to_string(&scenario.base).unwrap(), before.0);
+    assert_eq!(serde_json::to_string(&scenario.left).unwrap(), before.1);
+    assert_eq!(serde_json::to_string(&scenario.right).unwrap(), before.2);
+    assert_eq!(format!("{plan:?}"), before.3);
+    assert_eq!(
+        result.materialized_state.content, r#"{"o":{"a":9}}"#,
+        "the result is newly materialized"
+    );
+    // And the result is a different revision from all three inputs.
+    for existing in [&scenario.base, &scenario.left, &scenario.right] {
+        assert_ne!(result.materialized_state.id, existing.id);
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Materialization
+// ---------------------------------------------------------------------------
+
+/// The materialized revision uses the existing identity and provenance model.
+#[test]
+fn the_materialized_revision_uses_the_existing_model() {
+    let scenario = Scenario::new(r#"{"a":1}"#, r#"{"a":2}"#, r#"{"a":3}"#);
+
+    for (choice, expected_parent) in [(LEFT, &scenario.left), (RIGHT, &scenario.right)] {
+        let plan = scenario.plan(choice);
+        let result = reconcile(
+            &scenario.base,
+            &scenario.left,
+            &scenario.right,
+            &plan,
+            "reconciler".into(),
+        )
+        .expect("applies");
+        let revision = &result.materialized_state;
+
+        assert!(
+            revision.verify_integrity(),
+            "both identities match what they are computed from"
+        );
+        assert_eq!(
+            revision.content_id,
+            StateId::compute(&revision.content),
+            "no new content-identity algorithm"
+        );
+        assert_ne!(
+            revision.id, revision.content_id,
+            "the revision identity names the occurrence, not the state"
+        );
+        assert_eq!(
+            revision.parent_id.as_ref(),
+            Some(&expected_parent.id),
+            "the selected branch is the parent"
+        );
+        assert_eq!(revision.authority, "reconciler");
+        // The plan travels with the result, so the decision stays attached to
+        // the state it produced.
+        assert_eq!(result.plan.parent_choice, choice);
+    }
+}
+
+/// A materialized revision can be committed through the existing store, and
+/// nothing about branches moves.
+#[test]
+fn a_materialized_revision_commits_through_the_existing_store() {
+    let store = StateStore::new_volatile();
+    let base = store
+        .create("docs:1", r#"{"a":1,"b":1}"#.to_string(), "auth".into())
+        .expect("create");
+    let left = store
+        .commit(r#"{"a":2,"b":1}"#.to_string(), &base, "auth".into())
+        .expect("left");
+    let right = store
+        .commit(r#"{"a":1,"b":2}"#.to_string(), &base, "auth".into())
+        .expect("right");
+
+    let plan = ReconciliationPlan::new(left.id.clone(), right.id.clone(), base.id.clone(), LEFT)
+        .with_override(vec![key("b")], json!(2));
+
+    let result = reconcile(&base, &left, &right, &plan, "reconciler".into()).expect("applies");
+    let committed = store
+        .commit(
+            result.materialized_state.content.clone(),
+            &left,
+            "reconciler".into(),
+        )
+        .expect("commit");
+
+    assert_eq!(committed.content, r#"{"a":2,"b":2}"#);
+    assert_eq!(committed.id, result.materialized_state.id);
+
+    // Applying a plan disturbed nothing it started from: both source revisions
+    // are exactly as retrievable as before. There is no branch head to move,
+    // because the store keeps none.
+    assert_eq!(store.get(&left.id).unwrap().content, left.content);
+    assert_eq!(store.get(&right.id).unwrap().content, right.content);
+}
+
+// ---------------------------------------------------------------------------
+// Rejection
+// ---------------------------------------------------------------------------
+
+#[test]
+fn an_invalid_plan_is_rejected_rather_than_producing_state() {
+    let scenario = Scenario::new(r#"{"a":1}"#, r#"{"a":2}"#, r#"{"a":3}"#);
+
+    // A plan whose ids are empty does not reference three revisions.
+    let mut empty = scenario.plan(LEFT);
+    empty.base_id = StateId::from_hex(String::new());
+    assert_eq!(code(scenario.apply(&empty)), RECONCILE_PLAN_INVALID);
+
+    // A plan that names revisions other than the ones supplied.
+    let other = revision(r#"{"a":99}"#);
+    for (base, left, right) in [
+        (&other, &scenario.left, &scenario.right),
+        (&scenario.base, &other, &scenario.right),
+        (&scenario.base, &scenario.left, &other),
+    ] {
+        assert_eq!(
+            code(apply_reconciliation_plan(
+                base,
+                left,
+                right,
+                &scenario.plan(LEFT)
+            )),
+            RECONCILE_REVISION_MISMATCH
+        );
+    }
+
+    // Content that is not JSON. Classification reads such content as JSON null
+    // because it only describes; materializing a state from it would be
+    // producing arbitrary state, so this refuses.
+    let broken = Scenario::new("{}", "not json", "{}");
+    assert_eq!(
+        code(broken.apply(&broken.plan(LEFT))),
+        RECONCILE_CONTENT_UNPARSEABLE
+    );
+    // The branch that is not selected is not parsed, so it cannot fail the plan.
+    assert_eq!(broken.applied(&broken.plan(RIGHT)), json!({}));
+
+    // Override paths that name nothing assignable.
+    let scenario = Scenario::new(r#"{"o":{"a":1}}"#, r#"{"o":7}"#, r#"{"o":{"a":2}}"#);
+    for path in [
+        vec![key("o"), key("a")],          // `o` is a scalar in the left branch
+        vec![key("missing"), key("deep")], // the prefix does not resolve
+        vec![key("o"), PathComponent::Index(0)], // a scalar is not an array
+    ] {
+        let plan = scenario.plan(LEFT).with_override(path, json!(1));
+        assert_eq!(
+            code(scenario.apply(&plan)),
+            RECONCILE_OVERRIDE_UNADDRESSABLE
+        );
+    }
+}
+
+/// Application does not require every conflict to have an override, and says so.
+///
+/// `unresolved_conflicts` reports which conflicting paths a plan does not
+/// address, so a caller that wants each one decided individually can require it
+/// to be empty. Application itself does not: leaving a conflict unaddressed
+/// resolves it to the selected parent's value, and selecting that parent is
+/// itself an explicit decision.
+#[test]
+fn unresolved_conflicts_are_reported_but_not_required() {
+    let scenario = Scenario::new(r#"{"a":1,"b":1}"#, r#"{"a":2,"b":2}"#, r#"{"a":3,"b":3}"#);
+    let classification = scenario.classification();
+    assert_eq!(classification.overall, ConflictClass::Conflict);
+
+    let bare = scenario.plan(LEFT);
+    let unresolved = bare.unresolved_conflicts(&classification);
+    assert_eq!(unresolved.len(), 2, "neither conflict is addressed");
+
+    // Applying anyway is allowed: the conflicts resolve to the chosen branch.
+    assert_eq!(scenario.applied(&bare), json!({"a":2,"b":2}));
+
+    let partly = scenario.plan(LEFT).with_override(vec![key("a")], json!(9));
+    assert_eq!(partly.unresolved_conflicts(&classification).len(), 1);
+
+    let fully = scenario
+        .plan(LEFT)
+        .with_override(vec![key("a")], json!(9))
+        .with_override(vec![key("b")], json!(8));
+    assert!(fully.unresolved_conflicts(&classification).is_empty());
+    assert_eq!(scenario.applied(&fully), json!({"a":9,"b":8}));
+}
+
+// ---------------------------------------------------------------------------
+// The overlap regression from the corrected classifier
+// ---------------------------------------------------------------------------
+
+/// The ancestor/descendant case the corrected classifier now flags.
+///
+/// ```text
+/// base:  {"o":{"a":1}}
+/// left:  {"o":7}
+/// right: {"o":{"a":2}}
+/// ```
+///
+/// The two changes cannot both be applied. The classifier says so, and
+/// application does not quietly merge them into something that keeps both: the
+/// result is exactly the branch the plan chose, or exactly the override it
+/// supplied.
+#[test]
+fn an_overlapping_conflict_is_resolved_only_as_the_plan_says() {
+    let scenario = Scenario::new(r#"{"o":{"a":1}}"#, r#"{"o":7}"#, r#"{"o":{"a":2}}"#);
+
+    let classification = scenario.classification();
+    assert_eq!(
+        classification.overall,
+        ConflictClass::Conflict,
+        "the corrected classifier identifies the overlap"
+    );
+
+    // Choosing left takes the scalar, whole.
+    assert_eq!(scenario.applied(&scenario.plan(LEFT)), json!({"o":7}));
+    // Choosing right takes the object, whole.
+    assert_eq!(
+        scenario.applied(&scenario.plan(RIGHT)),
+        json!({"o":{"a":2}})
+    );
+    // An explicit override takes exactly what it says.
+    let explicit = scenario
+        .plan(LEFT)
+        .with_override(vec![key("o")], json!({"a":3}));
+    assert_eq!(scenario.applied(&explicit), json!({"o":{"a":3}}));
+
+    // Nothing produces a state carrying both the scalar and the member: these
+    // structures cannot be combined, and application does not try.
+    for plan in [scenario.plan(LEFT), scenario.plan(RIGHT), explicit] {
+        let result = scenario.applied(&plan);
+        let o = &result["o"];
+        assert!(
+            o.is_number() ^ o.is_object(),
+            "the result is one shape or the other, never an invented combination"
+        );
+    }
+}
+
+// ---------------------------------------------------------------------------
+// End to end
+// ---------------------------------------------------------------------------
+
+/// The whole causal path, with independent changes and one real conflict.
+///
+/// ```text
+/// base → left, right → SemanticDiff → ConflictClassification
+///      → explicit ReconciliationPlan → apply → result revision
+/// ```
+#[test]
+fn the_state_model_reconciles_an_explicit_decision_end_to_end() {
+    let store = StateStore::new_volatile();
+
+    // Two branches: each edits a different member independently, and both edit
+    // `shared` differently, which is the conflict.
+    let base = store
+        .create(
+            "docs:1",
+            r#"{"only_left":1,"only_right":1,"shared":1,"untouched":"keep"}"#.to_string(),
+            "auth".into(),
+        )
+        .expect("create");
+    let left = store
+        .commit(
+            r#"{"only_left":2,"only_right":1,"shared":10,"untouched":"keep"}"#.to_string(),
+            &base,
+            "alice".into(),
+        )
+        .expect("left");
+    let right = store
+        .commit(
+            r#"{"only_left":1,"only_right":2,"shared":20,"untouched":"keep"}"#.to_string(),
+            &base,
+            "bob".into(),
+        )
+        .expect("right");
+
+    // The diffs are what classification is defined over.
+    let base_value: Value = serde_json::from_str(&base.content).unwrap();
+    let left_value: Value = serde_json::from_str(&left.content).unwrap();
+    let right_value: Value = serde_json::from_str(&right.content).unwrap();
+    assert_eq!(
+        SemanticDiff::compute(&base_value, &left_value)
+            .changes
+            .len(),
+        2
+    );
+    assert_eq!(
+        SemanticDiff::compute(&base_value, &right_value)
+            .changes
+            .len(),
+        2
+    );
+
+    // Classification separates what can coexist from what cannot.
+    let classification = ConflictClassification::classify(&base, &left, &right);
+    assert_eq!(classification.overall, ConflictClass::Conflict);
+    let conflicting: Vec<_> = classification
+        .path_conflicts
+        .iter()
+        .filter(|entry| entry.classification == ConflictClass::Conflict)
+        .collect();
+    assert_eq!(conflicting.len(), 1, "exactly one path conflicts");
+    assert_eq!(conflicting[0].path, vec![key("shared")]);
+    assert_eq!(conflicting[0].base_value, Some(json!(1)));
+    assert_eq!(conflicting[0].left_value, Some(json!(10)));
+    assert_eq!(conflicting[0].right_value, Some(json!(20)));
+
+    // The caller decides: take the left branch, keep the right branch's
+    // independent change, and resolve the conflict to a third value neither
+    // branch proposed.
+    let plan = ReconciliationPlan::new(left.id.clone(), right.id.clone(), base.id.clone(), LEFT)
+        .with_override(vec![key("only_right")], json!(2))
+        .with_override(vec![key("shared")], json!(99));
+    assert!(
+        plan.unresolved_conflicts(&classification).is_empty(),
+        "every conflict is explicitly addressed"
+    );
+
+    let before = (
+        base.content.clone(),
+        left.content.clone(),
+        right.content.clone(),
+    );
+    let result = reconcile(&base, &left, &right, &plan, "reconciler".into()).expect("applies");
+    let reconciled: Value = serde_json::from_str(&result.materialized_state.content).unwrap();
+
+    // 1. the independent change on the selected branch survives
+    assert_eq!(reconciled["only_left"], json!(2));
+    // 2. the independent change on the other branch survives, because the plan
+    //    asked for it
+    assert_eq!(reconciled["only_right"], json!(2));
+    // 3. the chosen resolution survives, and neither branch's value does
+    assert_eq!(reconciled["shared"], json!(99));
+    assert_ne!(reconciled["shared"], json!(10));
+    assert_ne!(reconciled["shared"], json!(20));
+    // 4. unrelated state is preserved
+    assert_eq!(reconciled["untouched"], json!("keep"));
+    // 5. the result is canonical
+    assert_eq!(
+        result.materialized_state.content,
+        serde_json::to_string(&reconciled).unwrap()
+    );
+    assert!(result.materialized_state.verify_integrity());
+    // 6. the inputs are unchanged
+    assert_eq!(
+        (
+            base.content.clone(),
+            left.content.clone(),
+            right.content.clone()
+        ),
+        before
+    );
+
+    // The result is a revision like any other, committable through the store.
+    let committed = store
+        .commit(
+            result.materialized_state.content.clone(),
+            &left,
+            "reconciler".into(),
+        )
+        .expect("commit");
+    assert_eq!(committed.id, result.materialized_state.id);
+    assert_eq!(committed.parent_id.as_ref(), Some(&left.id));
+
+    // And the reconciled state has no remaining difference from itself.
+    let final_value: Value = serde_json::from_str(&committed.content).unwrap();
+    assert!(SemanticDiff::compute(&final_value, &reconciled)
+        .changes
+        .is_empty());
+}
+
+// ---------------------------------------------------------------------------
+// A recorded limitation of the plan type
+// ---------------------------------------------------------------------------
+
+/// A plan carrying overrides cannot be serialized to JSON.
+///
+/// `path_overrides` is keyed by `Vec<PathComponent>`, and JSON object keys must
+/// be strings, so `serde_json` refuses the map the moment it holds an entry.
+/// The type derives `Serialize`, which makes this look supported; it is not.
+///
+/// This is recorded, not fixed. A plan is presently constructed and applied
+/// in-process, which this PR is what establishes; nothing transmits one. Giving
+/// the path a string encoding would be inventing a second path syntax — exactly
+/// the flattened rendering the conflict work went out of its way to avoid —
+/// and it is not needed by any caller that exists. The test exists so that the
+/// day a caller does need to transmit a plan, the limitation is already stated
+/// rather than discovered.
+#[test]
+fn a_plan_with_overrides_is_not_json_serializable() {
+    let scenario = Scenario::new(r#"{"a":1}"#, r#"{"a":2}"#, r#"{"a":3}"#);
+
+    // Without overrides the plan serializes.
+    let plain = scenario.plan(LEFT);
+    assert!(serde_json::to_string(&plain).is_ok());
+
+    // With one, it does not, and application is unaffected either way.
+    let with_override = plain.clone().with_override(vec![key("a")], json!(9));
+    let error = serde_json::to_string(&with_override).expect_err("non-string key");
+    assert!(
+        error.to_string().contains("key must be a string"),
+        "unexpected error: {error}"
+    );
+    assert_eq!(scenario.apply(&with_override).unwrap(), r#"{"a":9}"#);
+}