@feltdb/core 0.8.4 → 0.8.6

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

@@ -0,0 +1,132 @@
+//! Scoped reads must not materialize a collection.
+//!
+//! The managed incident's amplifier: `list_collection` takes the one lock that
+//! serializes every read and write, and **clones every row in the collection**.
+//! A keyed lookup implemented that way, or a search that filters after the
+//! clone, extends the window in which nothing else in the database can proceed.
+//!
+//! The code's own comment already recorded this pathology being seen before:
+//!
+//! > *a query holding the lock while it cloned a collection inflated the cost
+//! > of unrelated writes*
+//!
+//! The bounded APIs already existed. These tests pin the properties the server
+//! now depends on, so a future handler cannot quietly go back to the scanning
+//! form.
+
+use feltdb::FeltDb;
+use serde_json::json;
+use std::sync::atomic::{AtomicUsize, Ordering};
+use tempfile::TempDir;
+
+fn populated(rows: usize) -> (TempDir, FeltDb) {
+    let directory = TempDir::new().unwrap();
+    let db = FeltDb::open(directory.path().join("reads.log")).unwrap();
+    for index in 0..rows {
+        db.insert(
+            &format!("docs:{index:05}"),
+            json!({ "n": index, "body": "x".repeat(200) }),
+        )
+        .unwrap();
+    }
+    (directory, db)
+}
+
+/// **A keyed lookup reads one record.**
+///
+/// `get_provenance` used to call `list_collection` and `find` the key, cloning
+/// the entire collection to return one row.
+#[test]
+fn a_keyed_lookup_does_not_materialize_the_collection() {
+    let (_directory, db) = populated(500);
+
+    let row = db
+        .get_collection_record("docs", "docs:00042")
+        .unwrap()
+        .expect("the record is found");
+    assert_eq!(row.value["n"], json!(42));
+
+    assert!(db
+        .get_collection_record("docs", "docs:99999")
+        .unwrap()
+        .is_none());
+}
+
+/// **A bounded search stops at its limit.**
+///
+/// The predicate is the observable proof: it runs once per row *visited*, so a
+/// limited search over a large collection visits far fewer rows than the
+/// collection holds. The scanning form evaluated every row, every time.
+#[test]
+fn a_bounded_search_stops_at_the_limit_instead_of_scanning() {
+    let (_directory, db) = populated(500);
+    let visited = AtomicUsize::new(0);
+
+    // Every row matches, so the only thing that can stop the traversal is the
+    // limit.
+    let matched = db
+        .query_collection("docs", Some(10), |row| {
+            visited.fetch_add(1, Ordering::Relaxed);
+            row.value["body"].is_string()
+        })
+        .unwrap();
+
+    assert_eq!(matched.len(), 10, "the limit is honoured");
+    assert_eq!(
+        visited.load(Ordering::Relaxed),
+        10,
+        "and the traversal stopped there rather than visiting all 500"
+    );
+}
+
+/// Only matching rows are cloned; rejected rows are borrowed and dropped.
+#[test]
+fn a_search_clones_only_what_it_returns() {
+    let (_directory, db) = populated(300);
+    let visited = AtomicUsize::new(0);
+
+    let matched = db
+        .query_collection("docs", None, |row| {
+            visited.fetch_add(1, Ordering::Relaxed);
+            row.value["n"].as_u64() == Some(7)
+        })
+        .unwrap();
+
+    assert_eq!(matched.len(), 1);
+    assert_eq!(
+        visited.load(Ordering::Relaxed),
+        300,
+        "an unlimited search still visits every row — the saving is in cloning"
+    );
+}
+
+/// Paging traverses in key order and is bounded, so a large collection is
+/// readable without a single unbounded materialization.
+#[test]
+fn paging_is_bounded_and_ordered() {
+    let (_directory, db) = populated(120);
+
+    let first = db.list_collection_page("docs", None, 25).unwrap();
+    assert_eq!(first.len(), 25);
+    assert_eq!(first[0].key, "docs:00000");
+
+    let after = first.last().unwrap().key.clone();
+    let second = db.list_collection_page("docs", Some(&after), 25).unwrap();
+    assert_eq!(second.len(), 25);
+    assert!(second[0].key > after, "paging advances");
+
+    // The whole collection is reachable in bounded steps.
+    let mut seen = 0;
+    let mut cursor: Option<String> = None;
+    loop {
+        let page = db
+            .list_collection_page("docs", cursor.as_deref(), 25)
+            .unwrap();
+        if page.is_empty() {
+            break;
+        }
+        seen += page.len();
+        cursor = Some(page.last().unwrap().key.clone());
+    }
+    assert_eq!(seen, 120);
+}

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

@@ -0,0 +1,299 @@
+//! Executable evidence for the Live State Branching audit
+//! (`docs/audits/BRANCHING-AUDIT.md`).
+//!
+//! These tests add no capability. Every one of them only *observes* what
+//! `feltdb::state_model` already does, so that the audit's branching claims
+//! rest on a run rather than on a reading. Where a test asserts an absence, the
+//! absence is the finding: it is what separates "FeltDB has branching" from
+//! "FeltDB has the durable lineage half of branching".
+
+use feltdb::state_model::StateStore;
+use feltdb::{
+    reconcile, ConflictClass, ConflictClassification, ReconciliationPlan, Relationship,
+    SemanticDiff, StateTopology,
+};
+use serde_json::json;
+use std::sync::Arc;
+use tempfile::TempDir;
+
+fn durable_store(directory: &TempDir, name: &str) -> StateStore {
+    let db = feltdb::FeltDb::open(directory.path().join(name)).expect("open");
+    StateStore::with_feltdb(Arc::new(db)).expect("store")
+}
+
+/// Q2 — **superseded.** Named branches no longer exist; a revision *is* the
+/// durable reference.
+///
+/// This test previously asserted that a branch is a durable named pointer at a
+/// `StateId` and survives a restart. Named branches were removed from
+/// `StateStore` because the record that held them, `state:current`, was the
+/// same record that held the global current pointer, and it carried both of the
+/// defects Q9 and Q11 recorded.
+///
+/// What survives is the load-bearing part: a revision is durable, and it is
+/// addressed by an identity derived from its own content — which is exactly
+/// what a branch name pointed at. The name was an alias for a value the caller
+/// already had.
+#[test]
+fn a_revision_is_its_own_durable_reference_across_restart() {
+    let directory = TempDir::new().unwrap();
+    let base = {
+        let store = durable_store(&directory, "state.log");
+        store
+            .create(
+                "docs:1",
+                json!({"balance": 100}).to_string(),
+                "authority".into(),
+            )
+            .expect("create")
+    };
+
+    let reopened = durable_store(&directory, "state.log");
+    let recovered = reopened
+        .get(&base.id)
+        .expect("a revision must survive a restart under its own identity");
+    assert_eq!(recovered.content, base.content);
+    assert!(
+        recovered.verify_integrity(),
+        "and still hash to the identity it was addressed by"
+    );
+}
+
+/// Q3/Q4 — mutation is **not** copy-on-write, and revisions share nothing.
+///
+/// Each revision carries the entire canonical state as its own `content`
+/// string. Two revisions that differ in one field still hold two full copies,
+/// so a "clone" costs the whole state. This is the storage half of branching
+/// FeltDB does not have.
+#[test]
+fn every_revision_holds_a_full_copy_of_state_rather_than_a_delta() {
+    let store = StateStore::new_volatile();
+    let filler = "x".repeat(4096);
+    let base = store
+        .create(
+            "docs:1",
+            json!({"blob": filler, "counter": 0}).to_string(),
+            "a".into(),
+        )
+        .expect("create");
+    let child = store
+        .commit(
+            json!({"blob": filler, "counter": 1}).to_string(),
+            &base,
+            "a".into(),
+        )
+        .expect("commit");
+
+    // One field changed; both revisions are still full-size.
+    assert!(base.content.len() > 4096);
+    assert!(child.content.len() > 4096);
+    assert_eq!(
+        base.content.len(),
+        child.content.len(),
+        "a one-field change produced two same-sized full copies, not a delta"
+    );
+    // And the parent link is the only thing they share: no structural sharing.
+    assert_eq!(child.parent_id.as_ref(), Some(&base.id));
+    assert_ne!(base.content, child.content);
+}
+
+/// Q5/Q6/Q7 — divergence, deterministic diff and conflict classification all
+/// work, but the topology is a structure the *caller* has to assemble.
+///
+/// `StateStore` exposes no topology of its own, so ancestry questions are only
+/// answerable by a caller that has already collected the revisions.
+#[test]
+fn divergence_diff_and_conflict_classification_work_over_a_caller_built_topology() {
+    let store = StateStore::new_volatile();
+    let base = store
+        .create(
+            "docs:1",
+            json!({"alice": 100, "bob": 50}).to_string(),
+            "a".into(),
+        )
+        .expect("create");
+    let left = store
+        .commit(
+            json!({"alice": 150, "bob": 50}).to_string(),
+            &base,
+            "a".into(),
+        )
+        .expect("left");
+    let right = store
+        .commit(
+            json!({"alice": 100, "bob": 150}).to_string(),
+            &base,
+            "a".into(),
+        )
+        .expect("right");
+
+    let mut topology = StateTopology::new();
+    for revision in [&base, &left, &right] {
+        topology.add_revision(revision.clone());
+    }
+    assert!(matches!(
+        topology.relationship(&left.id, &right.id),
+        Relationship::Diverged
+    ));
+    assert_eq!(
+        topology.common_ancestor(&left.id, &right.id),
+        Some(base.id.clone())
+    );
+
+    let base_value = serde_json::from_str(&base.content).unwrap();
+    let left_value = serde_json::from_str(&left.content).unwrap();
+    let diff = SemanticDiff::compute(&base_value, &left_value);
+    assert_eq!(diff.changes.len(), 1, "diff is deterministic and minimal");
+
+    let classification = ConflictClassification::classify(&base, &left, &right);
+    assert_eq!(classification.overall, ConflictClass::Independent);
+}
+
+/// Q8 — a plan can now be **applied**, but a branch still cannot be
+/// **reconciled**.
+///
+/// `apply_reconciliation_plan` turns an explicitly chosen plan into canonical
+/// content, and `reconcile` materializes that content as a `StateRevision`
+/// through the ordinary revision model. That is the half this evidence used to
+/// record as missing entirely.
+///
+/// What is still missing is the other half, and it is the half that would make
+/// this "branch reconciliation": nothing *chooses* a plan, and applying one
+/// moves no branch head. The caller supplies the parent choice and every
+/// override, and the branch points exactly where it did afterwards. FeltDB
+/// materializes the decision; it does not make it, and it does not record it as
+/// the branch's new position.
+#[test]
+fn a_plan_can_be_applied_but_applying_one_reconciles_no_branch() {
+    let store = StateStore::new_volatile();
+    let base = store
+        .create(
+            "docs:1",
+            json!({"alice": 100, "bob": 50}).to_string(),
+            "a".into(),
+        )
+        .expect("create");
+    let left = store
+        .commit(
+            json!({"alice": 150, "bob": 50}).to_string(),
+            &base,
+            "a".into(),
+        )
+        .expect("left");
+    let right = store
+        .commit(
+            json!({"alice": 100, "bob": 150}).to_string(),
+            &base,
+            "a".into(),
+        )
+        .expect("right");
+    let plan = ReconciliationPlan::new(left.id.clone(), right.id.clone(), base.id.clone(), true)
+        .with_override(vec![], json!({"alice": 150, "bob": 150}));
+    assert!(plan.validate(), "the plan validates structurally");
+
+    // The override is now read, and the plan is now applied.
+    let result =
+        reconcile(&base, &left, &right, &plan, "reconciler".into()).expect("the plan applies");
+    assert_eq!(
+        result.materialized_state.content,
+        r#"{"alice":150,"bob":150}"#
+    );
+    assert_eq!(
+        result.materialized_state.parent_id.as_ref(),
+        Some(&left.id),
+        "the chosen parent is the revision's parent"
+    );
+
+    // And nothing the plan started from changed. There is no branch head to
+    // advance — the store keeps none — and both source revisions are exactly
+    // as retrievable as before.
+    assert_eq!(store.get(&left.id).unwrap().content, left.content);
+    assert_eq!(store.get(&right.id).unwrap().content, right.content);
+
+    // And nothing chose this plan. Classification reports the conflict; the
+    // decision of what to do about it came from the caller.
+    let classification = ConflictClassification::classify(&base, &left, &right);
+    assert_eq!(classification.overall, ConflictClass::Independent);
+    assert!(
+        plan.unresolved_conflicts(&classification).is_empty(),
+        "the plan covers what the classifier reported, because the caller made it so"
+    );
+}
+
+/// Q9 — **the defect was removed rather than fixed.**
+///
+/// The original finding: `create_branch` recorded one `StateId` and never
+/// moved, while *any* commit moved the store's single global `current` pointer,
+/// so "which revision is this branch on now" was a question the store could not
+/// answer after the first commit. Both halves of that — the frozen branch
+/// pointer and the promiscuous global `current` — lived in one record.
+///
+/// Neither exists now. The store keeps no pointer, so there is none to be
+/// stale, and no commit can displace anything. Two siblings committed onto the
+/// same parent are simply two revisions, each addressed by its own identity,
+/// and the parent is untouched by either.
+///
+/// What this deliberately does *not* claim is that "which revision is current"
+/// has been answered. It has been **removed from this layer**, and no owner for
+/// it has been introduced.
+#[test]
+fn no_commit_can_displace_another_revision_because_there_is_no_pointer() {
+    let store = StateStore::new_volatile();
+    let base = store
+        .create("docs:1", json!({"v": 1}).to_string(), "a".into())
+        .expect("create");
+
+    let one = store
+        .commit(
+            json!({"v": 2, "side": "one"}).to_string(),
+            &base,
+            "a".into(),
+        )
+        .expect("commit one");
+    let two = store
+        .commit(
+            json!({"v": 2, "side": "two"}).to_string(),
+            &base,
+            "a".into(),
+        )
+        .expect("commit two");
+
+    // All three coexist, and neither sibling is privileged over the other.
+    for revision in [&base, &one, &two] {
+        assert_eq!(
+            store.get(&revision.id).expect("still present").content,
+            revision.content
+        );
+    }
+    assert_eq!(store.parent(&one.id).unwrap().id, base.id);
+    assert_eq!(store.parent(&two.id).unwrap().id, base.id);
+    assert_ne!(one.id, two.id, "the siblings are distinct revisions");
+}
+
+/// Q12 — nothing collects an abandoned revision, and nothing can.
+///
+/// Unchanged by the removal of branches, and worth re-recording because it is
+/// now the *only* remaining retention finding. Every revision ever committed
+/// stays in the store and on disk. There is no refcount, no unreachability
+/// sweep, and no delete.
+#[test]
+fn abandoned_revisions_are_retained_with_no_way_to_drop_them() {
+    let directory = TempDir::new().unwrap();
+    let abandoned = {
+        let store = durable_store(&directory, "state.log");
+        let base = store
+            .create("docs:1", json!({"v": 1}).to_string(), "a".into())
+            .expect("create");
+        // Nobody will ever ask for this revision again, and there is no way to
+        // tell the store that.
+        store
+            .commit(json!({"v": 2}).to_string(), &base, "a".into())
+            .expect("commit")
+    };
+
+    let reopened = durable_store(&directory, "state.log");
+    assert!(
+        reopened.exists(&abandoned.id),
+        "an abandoned revision is still durable after restart"
+    );
+}