@feltdb/core 0.8.3 → 0.8.5

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

@@ -0,0 +1,299 @@
+//! Evidence for the StateStore boundary audit
+//! (`docs/audits/STATESTORE-BOUNDARY-AUDIT.md`).
+//!
+//! These tests add **no capability and no product surface**. They answer one
+//! adversarial question with runs rather than readings:
+//!
+//! > Can FeltDB expose immutable state history through the existing server
+//! > authority with fewer primitives than a conventional database or branch
+//! > system requires?
+//!
+//! The answer is yes, and the margin is large. `MinimalStore` below is written
+//! in this test file deliberately: demonstrating that a shape is sufficient is
+//! not the same as committing the product to it, and this PR adds no API.
+
+use feltdb::state_model::{
+    apply_reconciliation_plan, ConflictClass, ConflictClassification, ReconciliationPlan, StateId,
+    StateRevision, StateStore,
+};
+use feltdb::FeltDb;
+use std::collections::HashMap;
+use std::sync::Arc;
+use tempfile::TempDir;
+
+fn revision(content: &str) -> StateRevision {
+    StateRevision {
+        id: StateId::compute(content),
+        resource: "docs:1".into(),
+        content: content.to_string(),
+        content_id: StateId::compute(content),
+        sequence: 0,
+        parent_id: None,
+        authority: "test".into(),
+        timestamp_ms: 0,
+        metadata: Default::default(),
+    }
+}
+
+// ---------------------------------------------------------------------------
+// A store built from two operations
+// ---------------------------------------------------------------------------
+
+/// A read-through revision store built from nothing but `FeltDb::insert` and
+/// `FeltDb::get`.
+///
+/// No in-memory index, no `current` pointer, no branches, and — because every
+/// record is keyed by the hash of its own content — no recovery path.
+struct MinimalStore {
+    db: Arc<FeltDb>,
+}
+
+impl MinimalStore {
+    fn key(id: &StateId) -> String {
+        format!("state:revision:{}", id.as_hex())
+    }
+
+    fn put(&self, revision: &StateRevision) -> Result<(), String> {
+        if !revision.verify_integrity() {
+            return Err("integrity check failed".into());
+        }
+        self.db
+            .insert(&Self::key(&revision.id), revision.clone())
+            .map_err(|error| error.to_string())
+    }
+
+    fn get(&self, id: &StateId) -> Option<StateRevision> {
+        self.db.get::<StateRevision>(&Self::key(id)).ok().flatten()
+    }
+
+    /// Ancestry is not a third operation. It is `get` and `parent_id`.
+    fn ancestors(&self, id: &StateId) -> Vec<StateId> {
+        let mut out = vec![];
+        let mut cursor = self.get(id).and_then(|revision| revision.parent_id);
+        while let Some(parent) = cursor {
+            out.push(parent.clone());
+            cursor = self.get(&parent).and_then(|revision| revision.parent_id);
+        }
+        out
+    }
+}
+
+/// Two operations carry the whole chain, across a real restart, with no
+/// recovery step and no mutable pointer.
+///
+/// This is the audit's central result. The store is opened, written, dropped,
+/// and reopened over the same log by a *different* `FeltDb` instance; nothing
+/// reconstructs an index, and the three revisions reconciliation needs are read
+/// back by identity alone.
+#[test]
+fn two_operations_carry_the_whole_chain_across_a_restart() {
+    let directory = TempDir::new().unwrap();
+    let path = directory.path().join("minimal.log");
+
+    let (base_id, left_id, right_id) = {
+        let store = MinimalStore {
+            db: Arc::new(FeltDb::open(&path).unwrap()),
+        };
+        let base = StateRevision::initial(
+            "docs:1".to_string(),
+            r#"{"shared":1,"only_left":1}"#.into(),
+            "a".into(),
+        );
+        let left = StateRevision::child(
+            r#"{"shared":10,"only_left":2}"#.into(),
+            &base,
+            "alice".into(),
+        );
+        let right =
+            StateRevision::child(r#"{"shared":20,"only_left":1}"#.into(), &base, "bob".into());
+
+        store.put(&base).unwrap();
+        store.put(&left).unwrap();
+        store.put(&right).unwrap();
+        (base.id.clone(), left.id.clone(), right.id.clone())
+    };
+
+    // A different FeltDb instance over the same log. No recovery is run.
+    let store = MinimalStore {
+        db: Arc::new(FeltDb::open(&path).unwrap()),
+    };
+    let base = store.get(&base_id).expect("base survives");
+    let left = store.get(&left_id).expect("left survives");
+    let right = store.get(&right_id).expect("right survives");
+    assert!(base.verify_integrity() && left.verify_integrity() && right.verify_integrity());
+
+    // The full chain runs against what was read back.
+    let classification = ConflictClassification::classify(&base, &left, &right);
+    assert_eq!(classification.overall, ConflictClass::Conflict);
+
+    let plan = ReconciliationPlan::new(left.id.clone(), right.id.clone(), base.id.clone(), true);
+    let content = apply_reconciliation_plan(&base, &left, &right, &plan).expect("applies");
+    assert_eq!(content, r#"{"only_left":2,"shared":10}"#);
+
+    let result = StateRevision::child(content, &left, "reconciler".into());
+    store.put(&result).expect("the result persists");
+    assert_eq!(
+        store.ancestors(&result.id),
+        vec![left_id, base_id],
+        "ancestry needs no primitive beyond get and parent_id"
+    );
+
+    // And no shared mutable record was ever written.
+    let current = store
+        .db
+        .get::<(String, HashMap<String, String>)>("state:current")
+        .unwrap();
+    assert!(
+        current.is_none(),
+        "a content-addressed history needs no current pointer"
+    );
+}
+
+// ---------------------------------------------------------------------------
+// What the chain actually requires
+// ---------------------------------------------------------------------------
+
+/// Application reads exactly one content, and three identities.
+///
+/// The base and the branch that was *not* selected contribute nothing but their
+/// ids — both may be unparseable and application still succeeds. This bounds
+/// what a store must be able to serve at the moment a plan is applied: one full
+/// state, not three.
+///
+/// Classification is the step that reads all three, so the chain as a whole
+/// still needs all three. The distinction matters for a durable design, because
+/// the two steps could be served differently.
+#[test]
+fn application_reads_one_content_and_three_identities() {
+    let base = revision("this is not json at all");
+    let left = revision(r#"{"a":1}"#);
+    let right = revision("also not json");
+
+    let plan = ReconciliationPlan::new(left.id.clone(), right.id.clone(), base.id.clone(), true);
+    assert_eq!(
+        apply_reconciliation_plan(&base, &left, &right, &plan).expect("applies"),
+        r#"{"a":1}"#,
+        "only the selected parent's content is read"
+    );
+}
+
+/// The chain from three revisions to a reconciled one names no branch.
+#[test]
+fn the_chain_needs_no_branch() {
+    let store = StateStore::new_volatile();
+    let base = store
+        .create("docs:1", r#"{"v":1}"#.into(), "a".into())
+        .unwrap();
+    let left = store
+        .commit(r#"{"v":2}"#.into(), &base, "alice".into())
+        .unwrap();
+    let right = store
+        .commit(r#"{"v":3}"#.into(), &base, "bob".into())
+        .unwrap();
+
+    let plan = ReconciliationPlan::new(left.id.clone(), right.id.clone(), base.id.clone(), true);
+    assert!(apply_reconciliation_plan(&base, &left, &right, &plan).is_ok());
+    assert!(
+        store.get(&base.id).is_some() && store.get(&left.id).is_some(),
+        "the chain named no branch, and every revision stayed addressable"
+    );
+}
+
+// ---------------------------------------------------------------------------
+// What the existing store costs
+// ---------------------------------------------------------------------------
+
+/// No commit writes a shared mutable record. **Regression.**
+///
+/// This test previously asserted the opposite, as a finding: `state:current`
+/// carried the global current pointer *and* the whole branch map in one
+/// replicated record — the record behind both defects the branching audit
+/// reported — and `commit_revision` wrote it unconditionally, so a caller that
+/// never created a branch did not avoid it.
+///
+/// That record no longer exists. The store's entire durable schema is
+/// `state:revision:{hex}`, one record per revision, and nothing else is
+/// written. The two defects were removed with it rather than repaired.
+#[test]
+fn no_commit_writes_a_shared_mutable_record() {
+    let directory = TempDir::new().unwrap();
+    let db = Arc::new(FeltDb::open(directory.path().join("shared.log")).unwrap());
+    let store = StateStore::with_feltdb(db.clone()).unwrap();
+
+    let base = store
+        .create("docs:1", r#"{"v":1}"#.into(), "a".into())
+        .unwrap();
+    let child = store
+        .commit(r#"{"v":2}"#.into(), &base, "a".into())
+        .unwrap();
+
+    assert!(
+        db.get::<(String, HashMap<String, String>)>("state:current")
+            .unwrap()
+            .is_none(),
+        "the record that carried the global pointer and the branch map is gone"
+    );
+
+    // What *is* written is one record per revision, and nothing else.
+    for revision in [&base, &child] {
+        assert_eq!(
+            store
+                .get(&revision.id)
+                .expect("revision is durable")
+                .content,
+            revision.content
+        );
+    }
+}
+
+/// One damaged record no longer refuses the whole store. **Regression.**
+///
+/// This test previously asserted the opposite, as a finding: `with_feltdb`
+/// eagerly loaded every revision, re-verified every content hash, and validated
+/// every parent reference before returning, so a single orphaned record that no
+/// caller would ever request refused the entire store.
+///
+/// There is no recovery step now. Reads are keyed and independent, so a damaged
+/// or unrelated record is simply a record nobody asked for. This is the
+/// operational difference between an index that must be rebuilt and records
+/// addressed by content.
+#[test]
+fn one_damaged_record_does_not_refuse_the_whole_store() {
+    let directory = TempDir::new().unwrap();
+    let path = directory.path().join("domain.log");
+
+    let good_id = {
+        let db = Arc::new(FeltDb::open(&path).unwrap());
+        let store = StateStore::with_feltdb(db.clone()).unwrap();
+        let good = store
+            .create("docs:1", r#"{"v":1}"#.into(), "a".into())
+            .unwrap();
+
+        // An unrelated revision whose parent was never stored. Nothing the
+        // caller will ever ask for.
+        let orphan = StateRevision {
+            id: StateId::compute(r#"{"orphan":true}"#),
+            resource: "docs:1".into(),
+            content: r#"{"orphan":true}"#.into(),
+            content_id: StateId::compute(r#"{"orphan":true}"#),
+            sequence: 0,
+            parent_id: Some(StateId::compute("a parent that was never stored")),
+            authority: "x".into(),
+            timestamp_ms: 0,
+            metadata: Default::default(),
+        };
+        db.insert(&format!("state:revision:{}", orphan.id.as_hex()), orphan)
+            .unwrap();
+        good.id
+    };
+
+    let db = Arc::new(FeltDb::open(&path).unwrap());
+    let store = StateStore::with_feltdb(db).expect("the store opens despite the orphan");
+
+    // The intact revision is readable by identity, unaffected by its neighbour.
+    let good = store
+        .get(&good_id)
+        .expect("the intact revision is readable");
+    assert!(good.verify_integrity());
+    assert_eq!(good.content, r#"{"v":1}"#);
+}

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

@@ -0,0 +1,255 @@
+//! Evidence for the sync divergence boundary audit
+//! (`docs/audits/SYNC-DIVERGENCE-AUDIT.md`).
+//!
+//! Adds **no capability and no product surface**. It tests one question:
+//!
+//! > Is there a concrete transition where two independently valid states need
+//! > to coexist durably — and does a durable representation for the second one
+//! > already exist?
+//!
+//! Both answers are yes, and the second is the surprising one: `SyncStore`
+//! already accepts `ReconciliationOutcome::Conflict` and persists the operation
+//! with its complete proposed value. The representation is not missing. The
+//! server reaches the conflict, declines to record it, and `continue`s.
+
+use feltdb::authorization::{
+    AuthorizationContext, Grant, GrantConstraints, GrantSigner, GrantStatus, Resource,
+    ResourceScope, ResourceScopeKind, Subject,
+};
+use feltdb::state_contract::{TransactionOperation, TransactionOperationKind};
+use feltdb::sync_contract::{ReconciliationOutcome, SyncOperation, SyncStore};
+use serde_json::json;
+use std::collections::BTreeMap;
+use tempfile::TempDir;
+
+/// A pushed operation for `flow://a/tasks/1` carrying `value` as its proposed
+/// state, descending from server position `causal_parent`.
+fn operation(id: &str, value: serde_json::Value, causal_parent: Option<u64>) -> SyncOperation {
+    let signer = GrantSigner::new("k", vec![9; 32]).unwrap();
+    let grant = Grant {
+        contract_version: 1,
+        id: "g".into(),
+        issuer: Subject::Human("h".into()),
+        subject: Subject::Human("u".into()),
+        tenant_id: "t".into(),
+        application_id: "a".into(),
+        capabilities: ["state:write".into(), "state:read".into()].into(),
+        resources: vec![ResourceScope {
+            kind: ResourceScopeKind::ResourcePrefix,
+            uri: "flow://a/tasks/*".into(),
+        }],
+        constraints: GrantConstraints::default(),
+        issued_at: 1,
+        expires_at: 999,
+        parent_grant: None,
+        revision: 1,
+        status: GrantStatus::Active,
+    };
+    let signed = signer.sign(grant).unwrap();
+
+    let mut causal_context = BTreeMap::new();
+    if let Some(position) = causal_parent {
+        causal_context.insert("server".to_string(), position);
+    }
+
+    SyncOperation {
+        contract_version: 1,
+        operation_id: id.into(),
+        tenant_id: "t".into(),
+        application_id: "a".into(),
+        subject: Subject::Human("u".into()),
+        device_id: "d".into(),
+        resource: Resource {
+            uri: "flow://a/tasks/1".into(),
+            attributes: BTreeMap::new(),
+        },
+        operation: TransactionOperation {
+            kind: TransactionOperationKind::Update,
+            collection: "tasks".into(),
+            id: "1".into(),
+            value,
+            if_version: None,
+        },
+        causal_context,
+        schema_version: 1,
+        authorization_context: AuthorizationContext {
+            timestamp: 10,
+            ..Default::default()
+        },
+        offline_grant: signed,
+        application_revision: "r1".into(),
+        created_at: 10,
+    }
+}
+
+// ---------------------------------------------------------------------------
+// What arrives at the boundary
+// ---------------------------------------------------------------------------
+
+/// A pushed operation carries a **complete proposed state**, not a delta.
+///
+/// This is the first half of what reconciliation needs. `TransactionOperation`
+/// is `{kind, collection, id, value, if_version}` and `value` is a whole
+/// `serde_json::Value` — the same shape `/v1/data` accepts. So the remote side
+/// of a divergence arrives at the server fully formed, and is present in memory
+/// at the exact moment the conflict is detected.
+#[test]
+fn a_pushed_operation_carries_a_complete_proposed_state() {
+    let remote = operation("op-remote", json!({"title": "written offline"}), Some(1));
+
+    assert_eq!(
+        remote.operation.value,
+        json!({"title": "written offline"}),
+        "the proposed state is carried whole, not as a change description"
+    );
+    assert_eq!(
+        remote.causal_context.get("server"),
+        Some(&1),
+        "and it names the server position it descended from"
+    );
+}
+
+// ---------------------------------------------------------------------------
+// The durable representation already exists
+// ---------------------------------------------------------------------------
+
+/// `SyncStore` can already record a conflicting operation, durably, with its
+/// full proposed state.
+///
+/// This is the audit's central result. `record` takes a
+/// `ReconciliationOutcome`, and `Conflict` is one of its variants. Recording a
+/// losing operation persists it at its own position, retains its complete
+/// value, and it survives reload — so the "losing state is annihilated" problem
+/// the current-revision audit found in the CAS path **does not apply here for
+/// want of a place to put it**. The place exists.
+///
+/// The server does not use it: at the conflict site it pushes a `SyncConflict`
+/// and `continue`s, skipping both `record` and the transaction.
+#[test]
+fn the_sync_store_can_already_record_a_conflicting_operation_durably() {
+    let directory = TempDir::new().unwrap();
+    let path = directory.path().join("sync.json");
+
+    let accepted_position;
+    let conflicting_position;
+    {
+        let mut store = SyncStore::load(&path).unwrap();
+
+        accepted_position = store
+            .record(
+                operation("op-local", json!({"title": "written on server"}), None),
+                ReconciliationOutcome::Accept,
+                None,
+                100,
+            )
+            .expect("the winning operation records");
+
+        // The losing side, recorded rather than discarded.
+        conflicting_position = store
+            .record(
+                operation("op-remote", json!({"title": "written offline"}), Some(1)),
+                ReconciliationOutcome::Conflict,
+                None,
+                101,
+            )
+            .expect("a conflicting operation records just as well");
+    }
+
+    // Both survive a reload, with their full states intact.
+    let reloaded = SyncStore::load(&path).unwrap();
+    let accepted = reloaded
+        .operations
+        .iter()
+        .find(|stored| stored.position == accepted_position)
+        .expect("the accepted operation is durable");
+    let conflicting = reloaded
+        .operations
+        .iter()
+        .find(|stored| stored.position == conflicting_position)
+        .expect("the conflicting operation is durable too");
+
+    assert!(matches!(accepted.outcome, ReconciliationOutcome::Accept));
+    assert!(matches!(
+        conflicting.outcome,
+        ReconciliationOutcome::Conflict
+    ));
+    assert_eq!(
+        conflicting.operation.operation.value,
+        json!({"title": "written offline"}),
+        "the losing side's complete proposed state is retained"
+    );
+    assert_eq!(
+        conflicting.operation.causal_context.get("server"),
+        Some(&1),
+        "along with the position it claimed to descend from"
+    );
+}
+
+/// Retained operations reconstruct the state a resource held at a position.
+///
+/// This is where `base` would come from. Operations are appended with a
+/// monotonic `position` and never pruned, and each carries the whole value that
+/// was applied, so "what did this resource look like at server position N" is
+/// answerable by lookup — **for the part of its history that arrived through
+/// sync**. See the audit for why that qualifier is the load-bearing one.
+#[test]
+fn retained_operations_reconstruct_the_state_at_a_position() {
+    let directory = TempDir::new().unwrap();
+    let mut store = SyncStore::load(directory.path().join("history.json")).unwrap();
+
+    let first = store
+        .record(
+            operation("op-1", json!({"title": "v1"}), None),
+            ReconciliationOutcome::Accept,
+            None,
+            10,
+        )
+        .unwrap();
+    let second = store
+        .record(
+            operation("op-2", json!({"title": "v2"}), Some(first)),
+            ReconciliationOutcome::Accept,
+            None,
+            11,
+        )
+        .unwrap();
+
+    let at = |position: u64| {
+        store
+            .operations
+            .iter()
+            .find(|stored| {
+                stored.position == position && stored.operation.resource.uri == "flow://a/tasks/1"
+            })
+            .map(|stored| stored.operation.operation.value.clone())
+    };
+
+    assert_eq!(at(first), Some(json!({"title": "v1"})));
+    assert_eq!(at(second), Some(json!({"title": "v2"})));
+    assert!(second > first, "positions are monotonic");
+
+    // Nothing prunes: the earlier state is still there after the later one.
+    assert_eq!(store.operations.len(), 2);
+}
+
+/// The outcome vocabulary already distinguishes the cases a reconciler needs.
+///
+/// Recorded because it bounds how much vocabulary a future change would have to
+/// invent: none. What is missing is a *decision procedure*, not a way to say
+/// what was decided.
+#[test]
+fn the_outcome_vocabulary_already_names_a_conflict() {
+    let outcomes = [
+        ReconciliationOutcome::Accept,
+        ReconciliationOutcome::Conflict,
+        ReconciliationOutcome::Reject,
+        ReconciliationOutcome::Stale,
+        ReconciliationOutcome::AlreadyCommitted,
+    ];
+    // Each is representable and round-trips, so a stored decision is durable.
+    for outcome in outcomes {
+        let text = serde_json::to_string(&outcome).unwrap();
+        let back: ReconciliationOutcome = serde_json::from_str(&text).unwrap();
+        assert_eq!(format!("{outcome:?}"), format!("{back:?}"));
+    }
+}