@feltdb/core 0.13.0 → 0.16.0

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

@@ -1,221 +0,0 @@
-//! 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

@@ -1,417 +0,0 @@
-//! 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"
-    );
-}