@feltdb/core 0.8.4 → 0.8.5

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

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

@@ -0,0 +1,288 @@
+//! Evidence for the current-revision authority audit
+//! (`docs/audits/CURRENT-REVISION-AUTHORITY-AUDIT.md`).
+//!
+//! Adds **no capability and no product surface**. It answers one question with
+//! runs rather than readings:
+//!
+//! > Can the existing resource/application authority legitimately own
+//! > `currentRevisionId`, advanced atomically with the resource's durable
+//! > mutation?
+//!
+//! The short answer is that the *mechanism* already exists and does exactly
+//! this for `__version`, but the *place* it keeps it — a field inside the
+//! document — is erasable by the unconditional write path. That is the finding
+//! the audit turns on, and `an_unconditional_write_erases_a_document_maintained_field`
+//! is what pins it.
+
+use feltdb::{FeltDb, JsonCasResult};
+use serde_json::{json, Value};
+use std::collections::HashMap;
+use tempfile::TempDir;
+
+// ---------------------------------------------------------------------------
+// The resource already owns durable currentness
+// ---------------------------------------------------------------------------
+
+/// A resource's current state is already durable and already survives restart.
+///
+/// This is the load-bearing precondition for the audit's hypothesis. Nothing
+/// needs to be invented for a resource to *have* a current state that outlives
+/// the process: the row at `capability:key` is that state, the version fence
+/// advances it atomically, and reopening the log returns exactly what the last
+/// successful mutation left.
+#[test]
+fn a_resource_already_owns_its_current_state_across_restart() {
+    let directory = TempDir::new().unwrap();
+    let path = directory.path().join("resource.log");
+
+    {
+        let db = FeltDb::open(&path).unwrap();
+        db.insert("accounts:1", json!({"balance": 100, "__version": 1}))
+            .unwrap();
+
+        let result = db
+            .compare_and_set_json("accounts:1", 1, None, None, false, json!({"balance": 150}))
+            .unwrap();
+        assert!(
+            matches!(
+                result,
+                JsonCasResult::Updated {
+                    current_version: 2,
+                    ..
+                }
+            ),
+            "the fence advanced the resource's version inside the mutation"
+        );
+    }
+
+    let db = FeltDb::open(&path).unwrap();
+    let recovered: Option<Value> = db.get("accounts:1").unwrap();
+    assert_eq!(
+        recovered,
+        Some(json!({"balance": 150, "__version": 2})),
+        "the resource's current state survives restart without any recovery step"
+    );
+}
+
+/// Advancement is already gated, by three independent fences.
+///
+/// `compare_and_set_json` checks the record version, the authority epoch at
+/// `/authority/epoch`, and an optional lease id — all under the store lock,
+/// before any durable write. "Who is entitled to advance this resource" is a
+/// question the existing authority already answers.
+#[test]
+fn the_existing_authority_already_gates_who_may_advance_a_resource() {
+    let directory = TempDir::new().unwrap();
+    let db = FeltDb::open(directory.path().join("epoch.log")).unwrap();
+    db.insert(
+        "accounts:4",
+        json!({"balance": 10, "__version": 1, "authority": {"epoch": 5}}),
+    )
+    .unwrap();
+
+    // A writer carrying a stale epoch is refused, even with the right version.
+    let stale = db
+        .compare_and_set_json(
+            "accounts:4",
+            1,
+            Some(4),
+            None,
+            false,
+            json!({"balance": 20}),
+        )
+        .unwrap();
+    assert!(
+        matches!(
+            stale,
+            JsonCasResult::AuthorityConflict {
+                current_epoch: 5,
+                ..
+            }
+        ),
+        "a stale authority epoch is refused: {stale:?}"
+    );
+
+    // The holder of the current epoch may advance it.
+    let allowed = db
+        .compare_and_set_json(
+            "accounts:4",
+            1,
+            Some(5),
+            None,
+            false,
+            json!({"balance": 30}),
+        )
+        .unwrap();
+    assert!(
+        matches!(
+            allowed,
+            JsonCasResult::Updated {
+                current_version: 2,
+                current_epoch: 5,
+                ..
+            }
+        ),
+        "the current epoch holder advances the resource: {allowed:?}"
+    );
+}
+
+// ---------------------------------------------------------------------------
+// What a race actually produces
+// ---------------------------------------------------------------------------
+
+/// The version fence **annihilates** the losing writer rather than recording it.
+///
+/// This is the audit's central negative result. Two writers start from the same
+/// parent version. One wins. The loser is told a number — `current_version` —
+/// and its proposed state is never stored, never logged, and never given an
+/// identity. Nothing anywhere records that two states were proposed from one
+/// parent.
+///
+/// So on a single node the existing mechanism does not *detect* divergence, it
+/// *prevents* it. There is no `left` and `right` to reconcile, because `right`
+/// never came into existence. Reconciliation's three inputs cannot be sourced
+/// from this path no matter how it is wired.
+#[test]
+fn the_version_fence_annihilates_the_losing_writer() {
+    let directory = TempDir::new().unwrap();
+    let db = FeltDb::open(directory.path().join("race.log")).unwrap();
+    db.insert("accounts:2", json!({"balance": 100, "__version": 1}))
+        .unwrap();
+
+    // Both writers fence on the same parent version.
+    let winner = db
+        .compare_and_set_json("accounts:2", 1, None, None, false, json!({"balance": 200}))
+        .unwrap();
+    let loser = db
+        .compare_and_set_json("accounts:2", 1, None, None, false, json!({"balance": 300}))
+        .unwrap();
+
+    assert!(matches!(winner, JsonCasResult::Updated { .. }));
+    assert!(
+        matches!(
+            loser,
+            JsonCasResult::VersionConflict {
+                current_version: 2,
+                ..
+            }
+        ),
+        "the loser learns only a version number: {loser:?}"
+    );
+
+    // The stored state is the winner's, and the loser's is nowhere.
+    let stored: Option<Value> = db.get("accounts:2").unwrap();
+    assert_eq!(stored, Some(json!({"balance": 200, "__version": 2})));
+
+    let operations = db.operations_since(&HashMap::new()).unwrap();
+    let for_resource: Vec<_> = operations
+        .iter()
+        .filter(|op| op.key == "accounts:2")
+        .collect();
+    assert_eq!(
+        for_resource.len(),
+        2,
+        "only the insert and the winning update are durable"
+    );
+    for operation in &for_resource {
+        let rendered = operation.value.as_ref().unwrap().to_string();
+        assert!(
+            !rendered.contains("300"),
+            "the losing writer's proposed state appears nowhere: {rendered}"
+        );
+    }
+}
+
+/// The operation log **does** retain an ordered per-resource history.
+///
+/// Worth recording as a positive: the ancestry a revision chain would need is
+/// not absent from the substrate. Every mutation is appended in order, per key,
+/// with a per-origin vector clock. What is missing is not the history — it is
+/// an identity for each resulting *state* and an explicit parent link between
+/// them. The log records operations, not revisions.
+#[test]
+fn the_operation_log_retains_an_ordered_per_resource_history() {
+    let directory = TempDir::new().unwrap();
+    let db = FeltDb::open(directory.path().join("history.log")).unwrap();
+
+    db.insert("accounts:3", json!({"balance": 100, "__version": 1}))
+        .unwrap();
+    db.update("accounts:3", json!({"balance": 200})).unwrap();
+    db.update("accounts:3", json!({"balance": 300})).unwrap();
+
+    let operations = db.operations_since(&HashMap::new()).unwrap();
+    let history: Vec<_> = operations
+        .iter()
+        .filter(|op| op.key == "accounts:3")
+        .collect();
+    assert_eq!(history.len(), 3, "every mutation is retained, in order");
+
+    // Each carries a per-origin causal position, which is a sequence rather
+    // than a statement about state.
+    for operation in &history {
+        assert!(
+            operation
+                .vector_clock
+                .as_ref()
+                .is_some_and(|c| !c.is_empty()),
+            "each operation carries causal evidence"
+        );
+    }
+
+    // But no operation names the state it descended from.
+    let rendered = format!("{:?}", history);
+    assert!(
+        !rendered.contains("parent"),
+        "an operation records what was done, not which state it descended from"
+    );
+}
+
+// ---------------------------------------------------------------------------
+// Why a document field cannot hold the reference
+// ---------------------------------------------------------------------------
+
+/// An unconditional write erases a field the authority maintains by convention.
+///
+/// This is the finding that decides the shape of any future `currentRevisionId`.
+///
+/// `__version` is, by the repository's own transaction-version contract, *"a
+/// document field maintained by convention, not a storage-level attribute"*.
+/// Unconditional writes are documented to remain verbatim — so writing a value
+/// that omits the field stores it omitted. That is correct behaviour for
+/// `update`, and it is exactly why it is not a safe home for a reference the
+/// state model would depend on: one ordinary unconditional write silently
+/// removes the resource's fence.
+///
+/// A `currentRevisionId` kept the same way would inherit the same weakness, and
+/// losing it would sever a resource from its history rather than merely dropping
+/// an optimistic-concurrency check.
+#[test]
+fn an_unconditional_write_erases_a_document_maintained_field() {
+    let directory = TempDir::new().unwrap();
+    let db = FeltDb::open(directory.path().join("erase.log")).unwrap();
+
+    db.insert("accounts:5", json!({"balance": 100, "__version": 1}))
+        .unwrap();
+    // Stand in for a revision pointer kept the same way the version is.
+    db.insert(
+        "accounts:6",
+        json!({"balance": 100, "__version": 1, "__currentRevision": "abc123"}),
+    )
+    .unwrap();
+
+    db.update("accounts:5", json!({"balance": 200})).unwrap();
+    db.update("accounts:6", json!({"balance": 200})).unwrap();
+
+    let versioned: Option<Value> = db.get("accounts:5").unwrap();
+    assert_eq!(
+        versioned,
+        Some(json!({"balance": 200})),
+        "the version field is gone after one unconditional write"
+    );
+
+    let referenced: Option<Value> = db.get("accounts:6").unwrap();
+    assert_eq!(
+        referenced,
+        Some(json!({"balance": 200})),
+        "a revision reference kept the same way is erased identically"
+    );
+}