@feltdb/core 0.8.3 → 0.8.5

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/resource_scoped_revisions.rs

@@ -0,0 +1,338 @@
+//! Production-facing evidence for the resource-scoped revision model.
+//!
+//! The [contract](../../../docs/architecture/revision-identity-and-ancestry.md)
+//! proves the 21 clauses; this file proves the scenarios a database has to
+//! survive rather than the clauses a model has to satisfy.
+//!
+//! Three groups: identity, ancestry, and bounded history.
+
+use feltdb::state_model::{
+    ParentLookup, RetentionPolicy, RevisionError, StateRevision, StateStore,
+};
+use feltdb::{FeltDb, JsonCasResult};
+use serde_json::json;
+use std::sync::Arc;
+use tempfile::TempDir;
+
+fn durable(name: &str) -> (TempDir, Arc<FeltDb>, StateStore) {
+    let directory = TempDir::new().unwrap();
+    let db = Arc::new(FeltDb::open(directory.path().join(name)).unwrap());
+    let store = StateStore::with_feltdb(db.clone()).unwrap();
+    (directory, db, store)
+}
+
+fn revision_lines(log: &str) -> usize {
+    log.lines()
+        .filter(|line| line.contains("state:revision:") && !line.contains(r#""deleted":true"#))
+        .count()
+}
+
+// ---------------------------------------------------------------------------
+// Identity
+// ---------------------------------------------------------------------------
+
+/// Writing the same state twice to one resource records two revisions.
+#[test]
+fn same_content_twice_is_distinct() {
+    let (_directory, db, store) = durable("same-twice.log");
+
+    db.insert("tasks:1", json!({"title": "A"})).unwrap();
+    db.update("tasks:1", json!({"title": "A"})).unwrap();
+
+    let history = store.history_of("tasks:1");
+    assert_eq!(history.len(), 2, "two writes, two revisions");
+    assert_ne!(history[0].id, history[1].id);
+    assert_eq!(
+        history[0].content_id, history[1].content_id,
+        "and it was the same state both times"
+    );
+}
+
+/// A revert is a new historical node, not a return to an old one.
+#[test]
+fn revert_creates_new_revision() {
+    let (_directory, db, store) = durable("revert.log");
+
+    db.insert("tasks:1", json!({"title": "A"})).unwrap();
+    db.update("tasks:1", json!({"title": "B"})).unwrap();
+    db.update("tasks:1", json!({"title": "A"})).unwrap();
+
+    let history = store.history_of("tasks:1");
+    assert_eq!(history.len(), 3);
+    assert_ne!(
+        history[0].id, history[2].id,
+        "the revert did not resurrect an identity"
+    );
+    assert_eq!(history[2].parent_id.as_ref(), Some(&history[1].id));
+    assert_eq!(history[1].parent_id.as_ref(), Some(&history[0].id));
+    assert_eq!(history[0].parent_id, None);
+}
+
+/// Identical content on two resources is two histories, never one object.
+#[test]
+fn same_content_across_resources_is_distinct() {
+    let (_directory, db, store) = durable("two-resources.log");
+
+    db.insert("tasks:1", json!({"title": "A"})).unwrap();
+    db.insert("tasks:2", json!({"title": "A"})).unwrap();
+
+    let one = store.head_of("tasks:1").unwrap();
+    let two = store.head_of("tasks:2").unwrap();
+
+    assert_ne!(one.id, two.id);
+    assert_eq!(one.content_id, two.content_id);
+    assert_eq!(one.resource, "tasks:1");
+    assert_eq!(two.resource, "tasks:2");
+    assert_eq!(store.history_of("tasks:1").len(), 1);
+    assert_eq!(store.history_of("tasks:2").len(), 1);
+}
+
+// ---------------------------------------------------------------------------
+// Ancestry
+// ---------------------------------------------------------------------------
+
+/// **T6, closed.** No later mint rewrites an existing revision's ancestry.
+#[test]
+fn committed_parent_is_immutable() {
+    let (_directory, db, store) = durable("immutable.log");
+
+    db.insert("tasks:1", json!({"title": "A"})).unwrap();
+    db.update("tasks:1", json!({"title": "B"})).unwrap();
+    let second = store.head_of("tasks:1").unwrap();
+    let recorded_parent = second.parent_id.clone();
+    assert!(recorded_parent.is_some());
+
+    // Everything that rewrote it before: the same content again, the same
+    // content as a root, and the same content on another resource.
+    db.update("tasks:1", json!({"title": "B"})).unwrap();
+    db.insert("tasks:2", json!({"title": "B"})).unwrap();
+    assert!(store
+        .create("tasks:1", r#"{"title":"B"}"#.into(), "x".into())
+        .is_err());
+
+    assert_eq!(
+        store.get(&second.id).unwrap().parent_id,
+        recorded_parent,
+        "the committed revision kept the parent it was committed with"
+    );
+}
+
+/// **T5, closed.** A parent must be an authoritative stored revision.
+#[test]
+fn foreign_parent_is_rejected() {
+    let (_directory, _db, store) = durable("foreign.log");
+
+    let real = store
+        .create("tasks:1", r#"{"title":"A"}"#.into(), "x".into())
+        .unwrap();
+
+    // A revision the caller built but never committed.
+    let fabricated = StateRevision::at(
+        "tasks:1".into(),
+        r#"{"never":"stored"}"#.into(),
+        None,
+        0,
+        "x".into(),
+    );
+    assert!(matches!(
+        store.commit(r#"{"title":"B"}"#.into(), &fabricated, "x".into()),
+        Err(RevisionError::UnknownParent(_))
+    ));
+
+    // And a real revision, but of another resource.
+    assert!(matches!(
+        store.mint(
+            "tasks:2",
+            r#"{"title":"B"}"#.into(),
+            Some(&real),
+            "x".into()
+        ),
+        Err(RevisionError::ForeignParent { .. })
+    ));
+}
+
+/// The fenced path mints from the revision the fence itself committed against,
+/// so no caller-supplied historical object can choose the ancestry.
+#[test]
+fn the_fenced_path_mints_from_the_current_revision() {
+    let (_directory, db, store) = durable("fenced.log");
+
+    db.insert("tasks:1", json!({"title": "A", "__version": 1}))
+        .unwrap();
+    let before = store.head_of("tasks:1").unwrap();
+
+    // A refused write mints nothing.
+    let refused = db
+        .compare_and_set_json("tasks:1", 99, None, None, false, json!({"title": "Z"}))
+        .unwrap();
+    assert!(matches!(refused, JsonCasResult::VersionConflict { .. }));
+    assert_eq!(store.history_of("tasks:1").len(), 1, "no revision minted");
+
+    // An accepted one descends from what was current.
+    db.compare_and_set_json("tasks:1", 1, None, None, false, json!({"title": "B"}))
+        .unwrap();
+    let after = store.head_of("tasks:1").unwrap();
+    assert_eq!(after.parent_id.as_ref(), Some(&before.id));
+    assert_eq!(after.sequence, before.sequence + 1);
+}
+
+// ---------------------------------------------------------------------------
+// Bounded history
+// ---------------------------------------------------------------------------
+
+/// The whole point of the policy: writing forever does not store forever.
+#[test]
+fn repeated_mutation_has_bounded_history() {
+    let (_directory, db, store) = durable("bounded.log");
+    store
+        .set_retention_policy("tasks:1", RetentionPolicy::keep_last(5))
+        .unwrap();
+
+    db.insert("tasks:1", json!({"n": 0})).unwrap();
+    for n in 1..200 {
+        db.update("tasks:1", json!({ "n": n })).unwrap();
+    }
+
+    assert_eq!(
+        store.history_of("tasks:1").len(),
+        5,
+        "two hundred writes, five retained revisions"
+    );
+}
+
+/// Retention never takes the state the application is using.
+#[test]
+fn current_revision_survives_retention() {
+    let (_directory, db, store) = durable("current.log");
+    // Even asked for zero, the current revision survives.
+    store
+        .set_retention_policy("tasks:1", RetentionPolicy::keep_last(0))
+        .unwrap();
+
+    db.insert("tasks:1", json!({"n": 0})).unwrap();
+    for n in 1..20 {
+        db.update("tasks:1", json!({ "n": n })).unwrap();
+    }
+
+    let history = store.history_of("tasks:1");
+    assert_eq!(history.len(), 1, "keep_last is clamped to at least one");
+    assert!(history[0].content.contains(r#""n":19"#));
+
+    let current: serde_json::Value = db.get("tasks:1").unwrap().unwrap();
+    assert_eq!(current["n"], json!(19), "and the row itself is untouched");
+}
+
+/// A retained revision's ancestry stays valid, and the cut is legible.
+///
+/// This is the hazard the retention rule was designed around: expiring an
+/// ancestor must not silently leave a retained child pointing at nothing. The
+/// child's `parent_id` is never rewritten — that would break immutability — so
+/// the resource records a horizon, and the oldest survivor reports its parent
+/// as **expired** rather than missing.
+#[test]
+fn parent_survives_required_retention() {
+    let (_directory, db, store) = durable("ancestry.log");
+    store
+        .set_retention_policy("tasks:1", RetentionPolicy::keep_last(3))
+        .unwrap();
+
+    db.insert("tasks:1", json!({"n": 0})).unwrap();
+    for n in 1..10 {
+        db.update("tasks:1", json!({ "n": n })).unwrap();
+    }
+
+    let history = store.history_of("tasks:1");
+    assert_eq!(history.len(), 3);
+
+    // Every retained revision but the oldest resolves its parent.
+    for revision in &history[1..] {
+        assert!(
+            matches!(
+                store.parent_of(&revision.id),
+                Some(ParentLookup::Revision(_))
+            ),
+            "a retained child's parent is retained"
+        );
+    }
+
+    // The oldest names a parent that was expired on purpose, and says so.
+    assert!(matches!(
+        store.parent_of(&history[0].id),
+        Some(ParentLookup::Expired(_))
+    ));
+    assert_eq!(
+        store.retention_horizon("tasks:1"),
+        history[0].sequence,
+        "the horizon is exactly where history was cut"
+    );
+}
+
+/// Expired revisions are reclaimed, not merely hidden.
+///
+/// Retention removes them from state immediately. The bytes go when the log is
+/// compacted, which is the operation that reclaims space — and this is the one
+/// place the two mechanisms meet: **retention decides what history exists;
+/// compaction reclaims what retention removed.** Neither does the other's job.
+#[test]
+fn expired_history_is_reclaimable() {
+    let directory = TempDir::new().unwrap();
+    let path = directory.path().join("reclaim.log");
+    let db = Arc::new(FeltDb::open(&path).unwrap());
+    let store = StateStore::with_feltdb(db.clone()).unwrap();
+
+    store
+        .set_retention_policy("tasks:1", RetentionPolicy::keep_last(2))
+        .unwrap();
+    db.insert("tasks:1", json!({"n": 0})).unwrap();
+    for n in 1..50 {
+        db.update("tasks:1", json!({ "n": n })).unwrap();
+    }
+
+    assert_eq!(store.history_of("tasks:1").len(), 2, "history is bounded");
+
+    let versions = db.operation_versions().unwrap();
+    db.acknowledge_peer_versions("peer-1".to_string(), versions)
+        .unwrap();
+    db.compact_operation_log(&["peer-1".to_string()]).unwrap();
+
+    let log = std::fs::read_to_string(&path).unwrap();
+    assert_eq!(
+        revision_lines(&log),
+        2,
+        "compaction wrote out only the revisions retention kept"
+    );
+
+    // And the bound holds across a restart.
+    drop(store);
+    drop(db);
+    let reopened = Arc::new(FeltDb::open(&path).unwrap());
+    let store = StateStore::with_feltdb(reopened.clone()).unwrap();
+    assert_eq!(store.history_of("tasks:1").len(), 2);
+    let current: serde_json::Value = reopened.get("tasks:1").unwrap().unwrap();
+    assert_eq!(current["n"], json!(49), "current state survived all of it");
+}
+
+/// Minting survives a restart: the head index is derived, not durable, and a
+/// reopened database continues the resource's history rather than restarting it.
+#[test]
+fn history_continues_across_a_restart() {
+    let directory = TempDir::new().unwrap();
+    let path = directory.path().join("restart.log");
+    let db = Arc::new(FeltDb::open(&path).unwrap());
+
+    db.insert("tasks:1", json!({"n": 0})).unwrap();
+    db.update("tasks:1", json!({"n": 1})).unwrap();
+    drop(db);
+
+    let reopened = Arc::new(FeltDb::open(&path).unwrap());
+    reopened.update("tasks:1", json!({"n": 2})).unwrap();
+    let store = StateStore::with_feltdb(reopened).unwrap();
+
+    let history = store.history_of("tasks:1");
+    assert_eq!(history.len(), 3, "the third write continued the history");
+    assert_eq!(
+        history[2].sequence, 2,
+        "sequence continued, did not restart"
+    );
+    assert_eq!(history[2].parent_id.as_ref(), Some(&history[1].id));
+}