@feltdb/core 0.8.5 → 0.8.7

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"
+    );
+}