@feltdb/core 0.8.4 → 0.8.5

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

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