@feltdb/core 0.15.0 → 0.16.0

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

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