@feltdb/core 0.8.4 → 0.8.6

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

@@ -0,0 +1,221 @@
+//! Evidence for the reconciliation reachability audit
+//! (`docs/audits/RECONCILIATION-REACHABILITY-AUDIT.md`).
+//!
+//! This file adds **no capability and no product surface**. It exists to settle
+//! one constructive question the audit had to answer before it could report a
+//! blockage honestly:
+//!
+//! > If a `ReconciliationPlan` cannot be serialized to JSON, can it cross a
+//! > wire at all?
+//!
+//! It can. The recorded limitation is narrower than it first appeared, and the
+//! difference matters, because "the plan cannot be transmitted" would have been
+//! a reason no API could exist. That is not the reason. The reason is in the
+//! audit, and it is about where state lives, not about encoding.
+//!
+//! The DTO below is written here rather than in `src/` deliberately: proving a
+//! shape works is not the same as committing the product to it, and this PR
+//! adds no API.
+
+use feltdb::state_model::PathComponent;
+use serde::{Deserialize, Serialize};
+use serde_json::{json, Value};
+use std::collections::BTreeMap;
+
+fn key(name: &str) -> PathComponent {
+    PathComponent::Key(name.to_string())
+}
+
+/// One override as it would appear on a wire: a *structural* path and a value.
+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
+struct WireOverride {
+    path: Vec<PathComponent>,
+    value: Value,
+}
+
+/// A plan as it would appear on a wire.
+///
+/// The one difference from `ReconciliationPlan` is that `path_overrides` is a
+/// **list**, not a map, because JSON object keys must be strings and a path is
+/// not one. Everything else is carried unchanged.
+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
+struct WirePlan {
+    left_id: String,
+    right_id: String,
+    base_id: String,
+    parent_choice: bool,
+    path_overrides: Vec<WireOverride>,
+}
+
+// ---------------------------------------------------------------------------
+// The limitation is about maps, not about paths
+// ---------------------------------------------------------------------------
+
+/// A path is JSON-encodable, structurally, with no invented syntax.
+///
+/// `ReconciliationPlan` cannot be serialized because `path_overrides` is keyed
+/// by `Vec<PathComponent>` and JSON object keys must be strings. That is a
+/// property of using a path as a *map key*. `PathComponent` itself derives
+/// `Serialize`/`Deserialize` and encodes as a tagged object, so a path is
+/// perfectly transmissible as a JSON array.
+#[test]
+fn a_path_survives_json_as_a_structural_array() {
+    let path = vec![key("o"), PathComponent::Index(0), key("a")];
+    let text = serde_json::to_string(&path).expect("a path serializes");
+    assert_eq!(text, r#"[{"Key":"o"},{"Index":0},{"Key":"a"}]"#);
+
+    let back: Vec<PathComponent> = serde_json::from_str(&text).expect("and parses");
+    assert_eq!(back, path, "and round trips exactly");
+}
+
+/// The two traps the conflict work rejected flattened renderings over survive.
+///
+/// This is the reason the encoding is an array of tagged components rather than
+/// a string. Under `"a.b"` / `"a.bc"` one path is a prefix of the other and the
+/// overlap check would report a containment that does not exist; under any
+/// string rendering an object member named `0` and array index `0` collide.
+#[test]
+fn the_encoding_preserves_the_distinctions_a_flattened_one_would_lose() {
+    let a_b = vec![key("a"), key("b")];
+    let a_bc = vec![key("a"), key("bc")];
+    assert_ne!(
+        serde_json::to_string(&a_b).unwrap(),
+        serde_json::to_string(&a_bc).unwrap(),
+        "['a','b'] and ['a','bc'] stay distinct, so neither contains the other"
+    );
+
+    let member_zero = vec![key("0")];
+    let index_zero = vec![PathComponent::Index(0)];
+    assert_eq!(
+        serde_json::to_string(&member_zero).unwrap(),
+        r#"[{"Key":"0"}]"#
+    );
+    assert_eq!(
+        serde_json::to_string(&index_zero).unwrap(),
+        r#"[{"Index":0}]"#
+    );
+    assert_ne!(
+        serde_json::to_string(&member_zero).unwrap(),
+        serde_json::to_string(&index_zero).unwrap(),
+        "an object member named 0 and the first array element stay different places"
+    );
+}
+
+/// A whole plan crosses a wire when overrides are a list rather than a map.
+#[test]
+fn a_plan_crosses_a_wire_when_its_overrides_are_a_list() {
+    let plan = WirePlan {
+        left_id: "aa".into(),
+        right_id: "bb".into(),
+        base_id: "cc".into(),
+        parent_choice: true,
+        path_overrides: vec![
+            WireOverride {
+                path: vec![key("o"), key("a")],
+                value: json!(9),
+            },
+            WireOverride {
+                path: vec![key("xs"), PathComponent::Index(1)],
+                value: json!("x"),
+            },
+        ],
+    };
+
+    let text = serde_json::to_string(&plan).expect("a wire plan serializes");
+    let back: WirePlan = serde_json::from_str(&text).expect("and parses");
+    assert_eq!(back, plan, "and round trips exactly");
+}
+
+// ---------------------------------------------------------------------------
+// What the list costs
+// ---------------------------------------------------------------------------
+
+/// The wire form reintroduces a hazard the in-memory type forecloses.
+///
+/// `ReconciliationPlan::path_overrides` is a `BTreeMap`, so two overrides at the
+/// same path cannot exist — the type makes the question unaskable, and
+/// `a_repeated_override_path_is_impossible_by_construction` records that. A
+/// *list* has no such property: a client can send the same path twice.
+///
+/// The danger is not that duplicates are possible. It is that collecting the
+/// list into the map **silently resolves them, last-wins**, which is exactly the
+/// shape of defect this sequence has twice corrected: a plausible-looking
+/// collapse that quietly discards one of two competing decisions. An API built
+/// on this DTO must reject duplicates explicitly, and this test exists so that
+/// obligation is recorded before any API exists rather than discovered after.
+#[test]
+fn collecting_a_wire_list_into_a_map_silently_drops_a_duplicate_path() {
+    let duplicated = vec![
+        WireOverride {
+            path: vec![key("o")],
+            value: json!("first"),
+        },
+        WireOverride {
+            path: vec![key("o")],
+            value: json!("second"),
+        },
+    ];
+
+    // The list carries both decisions.
+    assert_eq!(duplicated.len(), 2);
+
+    // The naive conversion keeps one, without erroring.
+    let collapsed: BTreeMap<Vec<PathComponent>, Value> = duplicated
+        .iter()
+        .map(|entry| (entry.path.clone(), entry.value.clone()))
+        .collect();
+    assert_eq!(collapsed.len(), 1, "one decision was dropped");
+    assert_eq!(
+        collapsed[&vec![key("o")]],
+        json!("second"),
+        "silently, and last-wins"
+    );
+
+    // What an API must do instead: detect the duplicate and refuse.
+    let mut seen: BTreeMap<Vec<PathComponent>, Value> = BTreeMap::new();
+    let mut rejected = false;
+    for entry in &duplicated {
+        if seen
+            .insert(entry.path.clone(), entry.value.clone())
+            .is_some()
+        {
+            rejected = true;
+        }
+    }
+    assert!(
+        rejected,
+        "a duplicate path is detectable, and must be refused"
+    );
+}
+
+/// Ordering is not information the wire form may carry.
+///
+/// The in-memory map has one iteration order, sorted structurally. A list has
+/// whatever order the client wrote. Since overlapping override paths are
+/// rejected, no two overrides can affect each other, so order cannot change the
+/// result — and an API must therefore not let a client believe it can.
+#[test]
+fn wire_order_carries_no_meaning() {
+    let one = WireOverride {
+        path: vec![key("a")],
+        value: json!(1),
+    };
+    let two = WireOverride {
+        path: vec![key("b")],
+        value: json!(2),
+    };
+
+    let forward: BTreeMap<_, _> = [one.clone(), two.clone()]
+        .iter()
+        .map(|e| (e.path.clone(), e.value.clone()))
+        .collect();
+    let reversed: BTreeMap<_, _> = [two, one]
+        .iter()
+        .map(|e| (e.path.clone(), e.value.clone()))
+        .collect();
+
+    assert_eq!(
+        forward, reversed,
+        "the map both lists produce is the same, so wire order is not a decision"
+    );
+}

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

@@ -0,0 +1,417 @@
+//! Replicated revision history.
+//!
+//! The question:
+//!
+//! > **When a remote operation is applied, does FeltDB reconstruct the same
+//! > historical revision the originating authority committed, or does
+//! > replication only reproduce current state?**
+//!
+//! It used to be the latter. A replica received the same records and no history
+//! at all, so two authorities agreed about what *is* while disagreeing about
+//! what *happened* — and reconciliation on a replica had no `base`.
+//!
+//! The target invariant:
+//!
+//! > **Replication preserves authoritative revision history, not merely
+//! > materialized state.**
+//!
+//! # Two independent equivalences
+//!
+//! State equivalence and historical equivalence are checked separately and must
+//! stay separate. Two databases can hold identical current records and
+//! completely different histories — one that recorded every step, one that only
+//! ever saw the last. `state_digest` answers the first question and
+//! `history_digest` the second, and
+//! `same_state_with_different_history_is_detected` proves the second is not the
+//! first wearing a different name.
+//!
+//! # What is not done here
+//!
+//! A peer does **not** mint a local revision for the resulting state. That
+//! would give `origin: A → B → C` and `replica: A' → B' → C'` — the same shape
+//! and different facts. The operation carries the revision it produced, and the
+//! peer rebuilds it, checking that the identity follows from its own parts.
+//!
+//! See `docs/architecture/replicated-history.md`.
+
+use feltdb::state_model::{ParentLookup, StateStore};
+use feltdb::{FeltDb, Operation};
+use serde_json::{json, Value};
+use std::collections::HashMap;
+use std::sync::Arc;
+use tempfile::TempDir;
+
+struct Pair {
+    _directory: TempDir,
+    origin: Arc<FeltDb>,
+    replica: Arc<FeltDb>,
+}
+
+fn pair() -> Pair {
+    let directory = TempDir::new().unwrap();
+    let origin = Arc::new(FeltDb::open(directory.path().join("origin.log")).unwrap());
+    let replica = Arc::new(FeltDb::open(directory.path().join("replica.log")).unwrap());
+    Pair {
+        _directory: directory,
+        origin,
+        replica,
+    }
+}
+
+fn store(db: &Arc<FeltDb>) -> StateStore {
+    StateStore::with_feltdb(db.clone()).unwrap()
+}
+
+fn operations(db: &Arc<FeltDb>) -> Vec<Operation> {
+    db.operations_since(&HashMap::new()).unwrap()
+}
+
+fn replicate(from: &Arc<FeltDb>, to: &Arc<FeltDb>) {
+    for operation in operations(from) {
+        to.apply_remote_operation(operation).unwrap();
+    }
+}
+
+/// Everything about one resource's history that must survive replication.
+fn history(db: &Arc<FeltDb>, resource: &str) -> Vec<(String, Option<String>, u64, String, String)> {
+    store(db)
+        .history_of(resource)
+        .into_iter()
+        .map(|revision| {
+            (
+                revision.id.as_hex().to_string(),
+                revision
+                    .parent_id
+                    .as_ref()
+                    .map(|id| id.as_hex().to_string()),
+                revision.sequence,
+                revision.content_id.as_hex().to_string(),
+                revision.authority,
+            )
+        })
+        .collect()
+}
+
+// ---------------------------------------------------------------------------
+// The flagship regression
+// ---------------------------------------------------------------------------
+
+/// **The test #307 was written to make fail.**
+///
+/// Three writes on the origin, replicated. The replica must hold the same three
+/// revisions — identities, parents, sequences, resource and provenance — not
+/// the same final value with no history.
+#[test]
+fn replication_preserves_revision_history_and_ancestry() {
+    let pair = pair();
+    pair.origin.insert("tasks:1", json!({"n": 1})).unwrap();
+    pair.origin.update("tasks:1", json!({"n": 2})).unwrap();
+    pair.origin.update("tasks:1", json!({"n": 3})).unwrap();
+
+    replicate(&pair.origin, &pair.replica);
+
+    // All three, identical in every historical field.
+    let origin_history = history(&pair.origin, "tasks:1");
+    let replica_history = history(&pair.replica, "tasks:1");
+    assert_eq!(origin_history.len(), 3);
+    assert_eq!(replica_history, origin_history);
+
+    // The chain traverses the same way.
+    let replica_store = store(&pair.replica);
+    let chain = replica_store.history_of("tasks:1");
+    assert_eq!(chain[0].parent_id, None);
+    assert_eq!(chain[1].parent_id.as_ref(), Some(&chain[0].id));
+    assert_eq!(chain[2].parent_id.as_ref(), Some(&chain[1].id));
+    for revision in &chain[1..] {
+        assert!(matches!(
+            replica_store.parent_of(&revision.id),
+            Some(ParentLookup::Revision(_))
+        ));
+    }
+
+    // Resource identity and current state.
+    assert!(chain.iter().all(|revision| revision.resource == "tasks:1"));
+    let current: Value = pair.replica.get("tasks:1").unwrap().unwrap();
+    assert_eq!(current["n"], json!(3));
+
+    // And the two independent equivalences, both holding.
+    assert_eq!(
+        pair.replica.state_digest().unwrap(),
+        pair.origin.state_digest().unwrap()
+    );
+    assert_eq!(
+        replica_store.history_digest(),
+        store(&pair.origin).history_digest(),
+        "the replica holds the same history, not merely the same values"
+    );
+}
+
+/// **R10, the mandatory negative control.**
+///
+/// Two databases with the same current state and different histories must not
+/// compare equal. If `history_digest` could not tell these apart, "history
+/// preserved" would silently mean "current values happen to match", and every
+/// other test in this file would be worthless.
+#[test]
+fn same_state_with_different_history_is_detected() {
+    let directory = TempDir::new().unwrap();
+
+    // Recorded every step.
+    let full = Arc::new(FeltDb::open(directory.path().join("full.log")).unwrap());
+    full.insert("tasks:1", json!({"n": 1})).unwrap();
+    full.update("tasks:1", json!({"n": 2})).unwrap();
+    full.update("tasks:1", json!({"n": 3})).unwrap();
+
+    // Only ever saw the last one.
+    let shallow = Arc::new(FeltDb::open(directory.path().join("shallow.log")).unwrap());
+    shallow.insert("tasks:1", json!({"n": 3})).unwrap();
+
+    assert_eq!(
+        full.state_digest().unwrap(),
+        shallow.state_digest().unwrap(),
+        "the fixture requires identical current state"
+    );
+    assert_ne!(
+        store(&full).history_digest(),
+        store(&shallow).history_digest(),
+        "identical state must not be mistaken for identical history"
+    );
+    assert_eq!(store(&full).history_of("tasks:1").len(), 3);
+    assert_eq!(store(&shallow).history_of("tasks:1").len(), 1);
+}
+
+// ---------------------------------------------------------------------------
+// The individual guarantees
+// ---------------------------------------------------------------------------
+
+/// **R6.** A replicated revision keeps the authority that committed the fact.
+///
+/// The replica must not rewrite provenance to itself, as though it had authored
+/// the history it received.
+#[test]
+fn authority_provenance_is_not_rewritten_by_the_replica() {
+    let pair = pair();
+    pair.origin.insert("tasks:1", json!({"n": 1})).unwrap();
+    replicate(&pair.origin, &pair.replica);
+
+    let origin_authority = store(&pair.origin).head_of("tasks:1").unwrap().authority;
+    let replica_authority = store(&pair.replica).head_of("tasks:1").unwrap().authority;
+    assert_eq!(replica_authority, origin_authority);
+
+    // And that authority is the origin's identity, not the replica's own.
+    pair.replica
+        .insert("tasks:2", json!({"local": true}))
+        .unwrap();
+    let local_authority = store(&pair.replica).head_of("tasks:2").unwrap().authority;
+    assert_ne!(
+        replica_authority, local_authority,
+        "a replicated revision is not attributed to the replica"
+    );
+}
+
+/// **R4.** Sequences are authoritative, not reassigned locally.
+///
+/// A replica with its own unrelated history must not renumber what it receives.
+#[test]
+fn sequences_are_preserved_not_renumbered() {
+    let pair = pair();
+
+    // The replica has its own busy history first.
+    for n in 0..5 {
+        pair.replica
+            .insert(&format!("local:{n}"), json!({ "n": n }))
+            .unwrap();
+    }
+    pair.replica.insert("other:1", json!({"a": 1})).unwrap();
+    pair.replica.update("other:1", json!({"a": 2})).unwrap();
+
+    pair.origin.insert("tasks:1", json!({"n": 1})).unwrap();
+    pair.origin.update("tasks:1", json!({"n": 2})).unwrap();
+    replicate(&pair.origin, &pair.replica);
+
+    let sequences: Vec<u64> = store(&pair.replica)
+        .history_of("tasks:1")
+        .iter()
+        .map(|revision| revision.sequence)
+        .collect();
+    assert_eq!(sequences, vec![0, 1], "a resource's history starts at zero");
+}
+
+/// **R7.** Replaying the whole operation stream changes nothing.
+#[test]
+fn replication_is_idempotent() {
+    let pair = pair();
+    pair.origin.insert("tasks:1", json!({"n": 1})).unwrap();
+    pair.origin.update("tasks:1", json!({"n": 2})).unwrap();
+
+    replicate(&pair.origin, &pair.replica);
+    let state_once = pair.replica.state_digest().unwrap();
+    let history_once = store(&pair.replica).history_digest();
+    let count_once = store(&pair.replica).history_of("tasks:1").len();
+
+    // Again, twice.
+    replicate(&pair.origin, &pair.replica);
+    replicate(&pair.origin, &pair.replica);
+
+    assert_eq!(pair.replica.state_digest().unwrap(), state_once);
+    assert_eq!(store(&pair.replica).history_digest(), history_once);
+    assert_eq!(
+        store(&pair.replica).history_of("tasks:1").len(),
+        count_once,
+        "no duplicate history, and no new revision identities"
+    );
+}
+
+/// **R8.** Causal ordering is not weakened to make history easier to rebuild.
+///
+/// An operation delivered before its causal predecessor is still refused, and
+/// the history is reconstructed once the prerequisites arrive.
+#[test]
+fn out_of_order_delivery_is_refused_and_then_converges() {
+    let pair = pair();
+    pair.origin.insert("tasks:1", json!({"n": 1})).unwrap();
+    pair.origin.update("tasks:1", json!({"n": 2})).unwrap();
+    pair.origin.update("tasks:1", json!({"n": 3})).unwrap();
+    let ops = operations(&pair.origin);
+
+    // The third first: refused, and nothing partial is left behind.
+    assert!(pair.replica.apply_remote_operation(ops[2].clone()).is_err());
+    assert!(store(&pair.replica).history_of("tasks:1").is_empty());
+
+    // In order: the same history as the origin.
+    for operation in &ops {
+        pair.replica
+            .apply_remote_operation(operation.clone())
+            .unwrap();
+    }
+    assert_eq!(
+        store(&pair.replica).history_digest(),
+        store(&pair.origin).history_digest()
+    );
+}
+
+/// **R5 and R9.** Concurrent writes on two authorities produce a fork, and the
+/// fork survives replication with both branches and their shared base.
+///
+/// This is the payoff: the replica ends up holding the historical information a
+/// three-way reconciliation needs — two heads and the common ancestor they
+/// descend from. Before, it held one value and no `base` at all.
+#[test]
+fn concurrent_authorities_produce_a_fork_that_survives_replication() {
+    let pair = pair();
+
+    // A shared starting point, replicated both ways.
+    pair.origin.insert("tasks:1", json!({"n": 0})).unwrap();
+    replicate(&pair.origin, &pair.replica);
+    let base = store(&pair.origin).head_of("tasks:1").unwrap();
+
+    // Now each authority writes independently.
+    pair.origin
+        .update("tasks:1", json!({"side": "left"}))
+        .unwrap();
+    pair.replica
+        .update("tasks:1", json!({"side": "right"}))
+        .unwrap();
+
+    let left = store(&pair.origin).head_of("tasks:1").unwrap();
+    let right = store(&pair.replica).head_of("tasks:1").unwrap();
+    assert_ne!(left.id, right.id, "two authorities, two revisions");
+    assert_eq!(left.parent_id.as_ref(), Some(&base.id));
+    assert_eq!(right.parent_id.as_ref(), Some(&base.id), "a real fork");
+
+    // Exchange. Each side must end up holding both branches.
+    replicate(&pair.origin, &pair.replica);
+    replicate(&pair.replica, &pair.origin);
+
+    for db in [&pair.origin, &pair.replica] {
+        let ids: Vec<String> = store(db)
+            .history_of("tasks:1")
+            .iter()
+            .map(|revision| revision.id.as_hex().to_string())
+            .collect();
+        assert!(ids.contains(&base.id.as_hex().to_string()), "the base");
+        assert!(ids.contains(&left.id.as_hex().to_string()), "the left head");
+        assert!(
+            ids.contains(&right.id.as_hex().to_string()),
+            "the right head"
+        );
+
+        // The information reconciliation needs: both heads resolve to the same
+        // common ancestor.
+        let store = store(db);
+        for head in [&left, &right] {
+            match store.parent_of(&head.id) {
+                Some(ParentLookup::Revision(parent)) => assert_eq!(parent.id, base.id),
+                other => panic!("a fork head must resolve to the shared base, got {other:?}"),
+            }
+        }
+    }
+
+    // Both sides now hold the same history, whatever their current values.
+    assert_eq!(
+        store(&pair.origin).history_digest(),
+        store(&pair.replica).history_digest(),
+        "the authorities converged on the same historical facts"
+    );
+}
+
+// ---------------------------------------------------------------------------
+// What replication refuses
+// ---------------------------------------------------------------------------
+
+/// A revision whose stated identity does not follow from its own parts is
+/// refused rather than turned into a plausible local history.
+#[test]
+fn a_tampered_revision_identity_is_refused() {
+    let pair = pair();
+    pair.origin.insert("tasks:1", json!({"n": 1})).unwrap();
+    let mut ops = operations(&pair.origin);
+
+    let provenance = ops[0].revision.as_mut().expect("the operation carries one");
+    provenance.id = "0".repeat(64);
+
+    assert!(
+        pair.replica.apply_remote_operation(ops[0].clone()).is_err(),
+        "a stated identity that does not follow from the parts is refused"
+    );
+    assert!(store(&pair.replica).history_of("tasks:1").is_empty());
+}
+
+/// A revision that does not match the value it arrived with is refused.
+#[test]
+fn a_revision_that_disagrees_with_its_value_is_refused() {
+    let pair = pair();
+    pair.origin.insert("tasks:1", json!({"n": 1})).unwrap();
+    let mut ops = operations(&pair.origin);
+
+    // The content identity no longer matches the operation's value.
+    let provenance = ops[0].revision.as_mut().unwrap();
+    provenance.content_id = "1".repeat(64);
+
+    assert!(pair.replica.apply_remote_operation(ops[0].clone()).is_err());
+}
+
+/// An operation from a build that sends no revision still replicates state, and
+/// carries no history.
+///
+/// The field is additive and outside the content hash, so an older peer's
+/// operations still verify and apply. What they cannot do is contribute
+/// history, and that is a bounded, stated consequence rather than a silent one.
+#[test]
+fn an_operation_without_provenance_replicates_state_only() {
+    let pair = pair();
+    pair.origin.insert("tasks:1", json!({"n": 1})).unwrap();
+    let mut ops = operations(&pair.origin);
+    ops[0].revision = None;
+
+    pair.replica
+        .apply_remote_operation(ops[0].clone())
+        .expect("it still verifies and applies");
+
+    let current: Value = pair.replica.get("tasks:1").unwrap().unwrap();
+    assert_eq!(current["n"], json!(1), "state arrived");
+    assert!(
+        store(&pair.replica).history_of("tasks:1").is_empty(),
+        "and no history was invented for it"
+    );
+}