@feltdb/core 0.8.4 → 0.8.6

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

@@ -0,0 +1,309 @@
+//! 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"
+        );
+    }
+
+    // **Superseded.** This assertion read, as a finding of this audit:
+    //
+    //     no operation names the state it descended from
+    //
+    // That was true when the audit ran, and it is the reason a replica could
+    // reproduce current state and no history at all. Replicated revision
+    // history closed it: an operation now carries the revision it produced —
+    // resource, identity, parent, sequence, content identity and authority — so
+    // a peer can rebuild that revision rather than mint a local substitute.
+    //
+    // The finding is kept here inverted rather than deleted, because it is the
+    // exact thing that changed.
+    for operation in &history {
+        let provenance = operation
+            .revision
+            .as_ref()
+            .expect("an operation now names the revision it produced");
+        assert_eq!(provenance.resource, "accounts:3");
+    }
+    let first = history[0].revision.as_ref().unwrap();
+    let second = history[1].revision.as_ref().unwrap();
+    assert_eq!(first.parent_id, None, "the first began the history");
+    assert_eq!(
+        second.parent_id.as_deref(),
+        Some(first.id.as_str()),
+        "and each names the 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"
+    );
+}