@feltdb/core 0.13.0 → 0.16.0

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

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

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

@@ -1,249 +0,0 @@
-//! Evidence for the three-way reconciliation input boundary audit
-//! (`docs/audits/THREE-WAY-INPUT-BOUNDARY-AUDIT.md`).
-//!
-//! Adds **no capability and no product surface**. It tests one question:
-//!
-//! > When a resource has mixed local and sync-originated history, what is the
-//! > authoritative source of `base`, `left` and `right`?
-//!
-//! The decisive result is negative and it kills a tempting shortcut: the
-//! operation log cannot serve as the ancestry source, because compaction — a
-//! routine, correct replication maintenance step — deletes the history while
-//! deliberately preserving current state.
-
-use feltdb::state_model::StateId;
-use feltdb::{FeltDb, JsonCasResult};
-use serde_json::{json, Value};
-use std::collections::HashMap;
-use tempfile::TempDir;
-
-/// The canonical content string for a stored value, as a `StateRevision` would
-/// hold it.
-fn canonical(value: &Value) -> String {
-    value.to_string()
-}
-
-// ---------------------------------------------------------------------------
-// What a locally committed state can already produce
-// ---------------------------------------------------------------------------
-
-/// A stored value canonicalizes deterministically, so it can become revision
-/// content without replaying anything.
-///
-/// `serde_json` is compiled without `preserve_order`, so `Map` is a `BTreeMap`
-/// and `to_string` emits keys in sorted order. Two documents that differ only
-/// in the order their keys were written produce the same string and therefore
-/// the same `StateId`. This is what makes candidate B representationally sound:
-/// the artifact that already holds a resource's authoritative state can be
-/// turned into a revision by reading it, not by reconstructing it.
-#[test]
-fn a_stored_value_canonicalizes_deterministically() {
-    let directory = TempDir::new().unwrap();
-    let db = FeltDb::open(directory.path().join("canon.log")).unwrap();
-
-    db.insert("tasks:1", json!({"title": "A", "__version": 1}))
-        .unwrap();
-    let stored: Value = db.get("tasks:1").unwrap().unwrap();
-    let content = canonical(&stored);
-    assert_eq!(content, r#"{"__version":1,"title":"A"}"#);
-
-    // Key order in the source text does not change the canonical form.
-    let one: Value = serde_json::from_str(r#"{"a":1,"b":2}"#).unwrap();
-    let other: Value = serde_json::from_str(r#"{"b":2,"a":1}"#).unwrap();
-    assert_eq!(canonical(&one), canonical(&other));
-    assert_eq!(
-        StateId::compute(&canonical(&one)).as_hex(),
-        StateId::compute(&canonical(&other)).as_hex(),
-        "the same state has one identity regardless of how it was written"
-    );
-}
-
-/// The prior document is in hand at the mutation boundary.
-///
-/// The fence reads the existing row before deciding, and it reads *inside* it:
-/// the authority epoch lives at `/authority/epoch`, a nested field of the
-/// stored document, and a stale epoch is refused on its basis. That is
-/// behavioural proof that the whole previous state — not merely a version
-/// counter — is available under the same lock that performs the write.
-///
-/// So the parent of a revision minted at this boundary is computable at that
-/// instant: it is `StateId::compute` over the canonical form of the document
-/// the fence just read.
-#[test]
-fn the_prior_document_is_read_at_the_mutation_boundary() {
-    let directory = TempDir::new().unwrap();
-    let db = FeltDb::open(directory.path().join("prior.log")).unwrap();
-
-    db.insert(
-        "tasks:2",
-        json!({"title": "A", "__version": 1, "authority": {"epoch": 7}}),
-    )
-    .unwrap();
-
-    // A nested field of the *previous* document decides this write.
-    let refused = db
-        .compare_and_set_json("tasks:2", 1, Some(6), None, false, json!({"title": "B"}))
-        .unwrap();
-    assert!(
-        matches!(
-            refused,
-            JsonCasResult::AuthorityConflict {
-                current_epoch: 7,
-                ..
-            }
-        ),
-        "the fence read into the prior document to refuse this: {refused:?}"
-    );
-
-    // And the prior document is still intact, so it could have been hashed.
-    let prior: Value = db.get("tasks:2").unwrap().unwrap();
-    assert_eq!(prior["authority"]["epoch"], json!(7));
-    assert!(!StateId::compute(&canonical(&prior)).as_hex().is_empty());
-}
-
-// ---------------------------------------------------------------------------
-// The shortcut, and why it fails
-// ---------------------------------------------------------------------------
-
-/// **Compaction destroys ancestry while preserving current state.**
-///
-/// This is the audit's decisive negative result, and it disqualifies
-/// reconstructing `base` from the operation log.
-///
-/// `compact_operation_log` prunes operations every active peer has
-/// acknowledged, then rewrites the log as a header, the still-pending
-/// operations, and a snapshot of the *current rows* — with `operation` set to
-/// `None` on each snapshot row, so even the linkage back to a mutation is
-/// stripped. It is correct, it is routine, and its entire purpose is to stop
-/// the log growing without bound once replication no longer needs it.
-///
-/// The consequence for reconciliation is exact: after compaction the resource's
-/// **current** state is intact and its **previous** state is gone. That is
-/// precisely the wrong half to preserve. A `base` derived from the log is not
-/// merely awkward to compute — it is destroyed by normal operation.
-#[test]
-fn log_compaction_destroys_ancestry_while_preserving_current_state() {
-    let directory = TempDir::new().unwrap();
-    let path = directory.path().join("compact.log");
-    let db = FeltDb::open(&path).unwrap();
-
-    // local A, then local B fenced on A.
-    db.insert("tasks:3", json!({"title": "A", "__version": 1}))
-        .unwrap();
-    db.compare_and_set_json("tasks:3", 1, None, None, false, json!({"title": "B"}))
-        .unwrap();
-
-    // Before compaction both states are in the log.
-    let before = db.operations_since(&HashMap::new()).unwrap();
-    let for_resource: Vec<_> = before.iter().filter(|op| op.key == "tasks:3").collect();
-    assert_eq!(
-        for_resource.len(),
-        2,
-        "insert A and update B are both present"
-    );
-    assert!(
-        for_resource
-            .iter()
-            .any(|op| op.value.as_ref().unwrap()["title"] == json!("A")),
-        "state A is recoverable from the log at this point"
-    );
-
-    // A peer acknowledges everything, and the log is compacted.
-    let versions = db.operation_versions().unwrap();
-    db.acknowledge_peer_versions("peer-1".to_string(), versions)
-        .unwrap();
-    let removed = db.compact_operation_log(&["peer-1".to_string()]).unwrap();
-    assert!(removed > 0, "compaction pruned acknowledged operations");
-
-    // Reopen from the compacted log.
-    drop(db);
-    let reopened = FeltDb::open(&path).unwrap();
-
-    // Current state survived.
-    let current: Value = reopened.get("tasks:3").unwrap().unwrap();
-    assert_eq!(current["title"], json!("B"), "the current state is intact");
-
-    // Ancestry did not.
-    let after = reopened.operations_since(&HashMap::new()).unwrap();
-    assert!(
-        !after
-            .iter()
-            .any(|op| op.value.as_ref().is_some_and(|v| v["title"] == json!("A"))),
-        "state A is no longer recoverable from anywhere in the log"
-    );
-}
-
-// ---------------------------------------------------------------------------
-// The mixed-history case
-// ---------------------------------------------------------------------------
-
-/// **`base` cannot be produced for a locally written resource.**
-///
-/// The scenario the audit was asked to settle:
-///
-/// ```text
-/// local A  →  local B  →  remote proposal C, descended from A
-/// ```
-///
-/// At the moment of conflict:
-///
-/// | input | source | available |
-/// | --- | --- | --- |
-/// | `right` = C | the pushed operation's `value` | yes |
-/// | `left`  = B | the current row, canonicalized | yes |
-/// | `base`  = A | — | **no** |
-///
-/// A is gone from the row, which was overwritten in place; it was never written
-/// to `SyncStore`, which only records sync-originated operations; and it does
-/// not survive compaction of the operation log. Nothing durable holds it.
-///
-/// This is the missing invariant, stated exactly: **no durable artifact
-/// preserves a resource's prior state once it has been overwritten.**
-#[test]
-fn the_prior_state_is_unrecoverable_after_a_second_local_write() {
-    let directory = TempDir::new().unwrap();
-    let db = FeltDb::open(directory.path().join("mixed.log")).unwrap();
-
-    // local A
-    db.insert("tasks:4", json!({"title": "A", "__version": 1}))
-        .unwrap();
-    let a_id = StateId::compute(&canonical(&db.get::<Value>("tasks:4").unwrap().unwrap()));
-
-    // local B, fenced on A
-    db.compare_and_set_json("tasks:4", 1, None, None, false, json!({"title": "B"}))
-        .unwrap();
-
-    // `left` is available and identifiable.
-    let left: Value = db.get("tasks:4").unwrap().unwrap();
-    let left_id = StateId::compute(&canonical(&left));
-    assert_eq!(left["title"], json!("B"));
-    assert_ne!(left_id.as_hex(), a_id.as_hex());
-
-    // The row no longer holds A: it was overwritten in place.
-    assert_ne!(
-        StateId::compute(&canonical(&left)).as_hex(),
-        a_id.as_hex(),
-        "the authoritative row holds B, and nothing holds A beside it"
-    );
-
-    // A is present in the log only for as long as the log is uncompacted,
-    // which the previous test shows is not a durability guarantee.
-    let operations = db.operations_since(&HashMap::new()).unwrap();
-    let a_in_log = operations
-        .iter()
-        .filter(|op| op.key == "tasks:4")
-        .any(|op| op.value.as_ref().unwrap()["title"] == json!("A"));
-    assert!(
-        a_in_log,
-        "A is in the log now — but only until acknowledged operations are pruned"
-    );
-
-    // And there is no revision for it: nothing in this path mints one.
-    // `a_id` was computed by this test, not by FeltDB; no durable record
-    // anywhere associates it with the resource.
-    assert_eq!(
-        a_id.as_hex().len(),
-        64,
-        "an identity for A is computable, but it is computed here and stored nowhere"
-    );
-}