@feltdb/core 0.8.4 → 0.8.6

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

@@ -0,0 +1,278 @@
+//! Operational health.
+//!
+//! Everything from the format work onward proved what FeltDB *does*. This file
+//! asks a different question:
+//!
+//! > **Can an operator reliably tell what FeltDB knows about itself?**
+//!
+//! The rule the whole surface is built on:
+//!
+//! > **Health can expose a proven fact. It cannot create a stronger
+//! > guarantee.**
+//!
+//! So `DatabaseHealth` reports the durable format an open accepted and whether
+//! replay discarded an incomplete final append, and nothing else. There is no
+//! replication health, no backup freshness and no durability claim, because
+//! none of those has an operational contract yet and inventing one here would
+//! reintroduce exactly the defect this replaces: a reassuring label that
+//! observes nothing.
+//!
+//! See `docs/architecture/operational-health.md`.
+
+use feltdb::{
+    inspect_durable_format, DatabaseHealth, DurableFormat, FeltDb, FlowError, LogRecovery,
+    StorageHealth, DURABLE_FORMAT_VERSION,
+};
+use serde_json::{json, Value};
+use std::io::Write;
+use std::path::Path;
+use tempfile::TempDir;
+
+fn three_writes(path: &Path) -> Vec<u8> {
+    let db = FeltDb::open(path).unwrap();
+    for n in 0..3 {
+        db.insert(&format!("tasks:{n}"), json!({ "n": n })).unwrap();
+    }
+    drop(db);
+    std::fs::read(path).unwrap()
+}
+
+// ---------------------------------------------------------------------------
+// The five questions health has to answer
+// ---------------------------------------------------------------------------
+
+/// **A clean startup reports clean.**
+#[test]
+fn a_clean_open_reports_clean_storage() {
+    let directory = TempDir::new().unwrap();
+    let path = directory.path().join("clean.log");
+    three_writes(&path);
+
+    let db = FeltDb::open(&path).unwrap();
+    let health = db.health();
+
+    assert_eq!(health.storage, StorageHealth::Clean);
+    assert_eq!(health.recovery, LogRecovery::Clean);
+    assert_eq!(
+        health.durable_format,
+        DurableFormat::Versioned(DURABLE_FORMAT_VERSION)
+    );
+    assert!(health.is_nominal());
+    assert_eq!(health.storage.label(), "clean");
+}
+
+/// **The regression that matters.** A database that discarded a torn tail must
+/// not report the same health as one that replayed cleanly.
+///
+/// This is the operational consequence of the corruption work: the distinction
+/// between a clean open and a recovered one was established there, and it is
+/// worth nothing to an operator unless it reaches them.
+#[test]
+fn a_recovered_open_does_not_report_the_same_health_as_a_clean_one() {
+    let directory = TempDir::new().unwrap();
+    let clean_path = directory.path().join("clean.log");
+    let torn_path = directory.path().join("torn.log");
+    let full = three_writes(&clean_path);
+
+    // The same database, with its final append cut short.
+    std::fs::write(&torn_path, &full[..full.len() - 30]).unwrap();
+
+    let clean = FeltDb::open(&clean_path).unwrap().health();
+    let torn = FeltDb::open(&torn_path).unwrap().health();
+
+    assert_ne!(
+        clean, torn,
+        "a database that lost its last write must not look identical to one that did not"
+    );
+    assert!(clean.is_nominal());
+    assert!(!torn.is_nominal(), "recovered is not nominal");
+    assert_ne!(clean.storage.label(), torn.storage.label());
+
+    match torn.storage {
+        StorageHealth::RecoveredIncompleteWrite {
+            byte_offset,
+            discarded_bytes,
+        } => {
+            assert!(byte_offset > 0, "the operator is told where");
+            assert!(discarded_bytes > 0, "and how much");
+        }
+        other => panic!("expected a reported recovery, got {other:?}"),
+    }
+
+    // And it says so in words an operator can act on.
+    let described = torn.storage.to_string();
+    assert!(described.contains("incomplete append"));
+    assert!(described.contains("last write did not land"));
+}
+
+/// **A corrupt database does not become healthy.** It does not open at all.
+///
+/// The ambiguity being removed here is "healthy process, unhealthy database":
+/// there is no state in which a server is serving a database whose durable log
+/// failed to replay.
+#[test]
+fn a_corrupt_database_never_reaches_a_health_report() {
+    let directory = TempDir::new().unwrap();
+    let path = directory.path().join("corrupt.log");
+    three_writes(&path);
+
+    let mut file = std::fs::OpenOptions::new()
+        .append(true)
+        .open(&path)
+        .unwrap();
+    writeln!(file, "this is not json at all").unwrap();
+    drop(file);
+
+    match FeltDb::open(&path) {
+        Err(FlowError::CorruptLogLine(_)) => {}
+        Err(other) => panic!("wrong error: {other}"),
+        Ok(_) => panic!("a corrupt database opened and could have reported health"),
+    }
+}
+
+/// **An incompatible database stays refused**, so a running server cannot be
+/// advertising one.
+#[test]
+fn an_incompatible_database_never_reaches_a_health_report() {
+    let directory = TempDir::new().unwrap();
+    let path = directory.path().join("future.log");
+    std::fs::write(
+        &path,
+        format!(
+            "{}\n",
+            json!({
+                "record_type": "feltdb.format.v1",
+                "format_version": DURABLE_FORMAT_VERSION + 1
+            })
+        ),
+    )
+    .unwrap();
+
+    assert!(!inspect_durable_format(&path).unwrap().is_compatible());
+    assert!(matches!(
+        FeltDb::open(&path),
+        Err(FlowError::IncompatibleFormat(_))
+    ));
+}
+
+/// Health survives the thing it describes: reopening a repaired log reports
+/// clean again, because the condition is genuinely gone.
+///
+/// A status that stayed degraded forever would be as useless as one that never
+/// was.
+#[test]
+fn health_reflects_the_current_open_not_the_database_s_past() {
+    let directory = TempDir::new().unwrap();
+    let path = directory.path().join("repaired.log");
+    let full = three_writes(&path);
+    std::fs::write(&path, &full[..full.len() - 30]).unwrap();
+
+    let recovered = FeltDb::open(&path).unwrap();
+    assert!(!recovered.health().is_nominal());
+    drop(recovered);
+
+    let reopened = FeltDb::open(&path).unwrap();
+    assert!(
+        reopened.health().is_nominal(),
+        "the incomplete append is gone, so the condition is too"
+    );
+}
+
+/// A database with no torn tail but written before format versioning is
+/// reported as what it is, rather than as an error or as current.
+#[test]
+fn an_unversioned_database_reports_its_actual_format() {
+    let directory = TempDir::new().unwrap();
+    let path = directory.path().join("unversioned.log");
+    std::fs::write(
+        &path,
+        format!(
+            "{}\n",
+            json!({
+                "capability": "tasks", "key": "tasks:1",
+                "rust_type": "serde_json::value::Value", "value": {"n": 1},
+                "unix_ms": 1, "content_hash": null, "flow_ref": null,
+                "deleted": false, "operation": null
+            })
+        ),
+    )
+    .unwrap();
+
+    let health = FeltDb::open(&path).unwrap().health();
+    assert_eq!(health.durable_format, DurableFormat::Unversioned);
+    assert!(health.is_nominal(), "unversioned is not unhealthy");
+}
+
+// ---------------------------------------------------------------------------
+// What health deliberately does not say
+// ---------------------------------------------------------------------------
+
+/// **Health does not manufacture a guarantee the database does not have.**
+///
+/// The defect being replaced was `storage: "durable"` — a string constant that
+/// inspected nothing and asserted the one property still unproven. The
+/// replacement is a small closed set of observed conditions, and every label in
+/// it names what was seen rather than what would be reassuring.
+///
+/// In particular nothing here claims durability against power loss, which
+/// remains unproven; nothing claims the database is replicated, backed up, or
+/// within any capacity; and there is no "probably fine".
+#[test]
+fn health_reports_only_conditions_that_were_observed() {
+    let directory = TempDir::new().unwrap();
+    let clean = directory.path().join("a.log");
+    let torn = directory.path().join("b.log");
+    let full = three_writes(&clean);
+    std::fs::write(&torn, &full[..full.len() - 30]).unwrap();
+
+    let labels: Vec<&str> = [&clean, &torn]
+        .iter()
+        .map(|path| FeltDb::open(path).unwrap().health().storage.label())
+        .collect();
+
+    // Exactly two conditions, both naming an observation.
+    assert_eq!(labels, vec!["clean", "recovered-incomplete-write"]);
+    for label in &labels {
+        assert!(
+            !label.contains("durable") && !label.contains("healthy"),
+            "'{label}' would assert more than was observed"
+        );
+    }
+}
+
+/// The health value is derived from the recovery the open recorded, not from
+/// anything a caller can set.
+#[test]
+fn health_is_derived_from_the_open_rather_than_configured() {
+    let directory = TempDir::new().unwrap();
+    let path = directory.path().join("derived.log");
+    let full = three_writes(&path);
+    std::fs::write(&path, &full[..full.len() - 30]).unwrap();
+
+    let db = FeltDb::open(&path).unwrap();
+    let health: DatabaseHealth = db.health();
+
+    // The two agree because one is computed from the other.
+    match (&health.recovery, &health.storage) {
+        (
+            LogRecovery::RecoveredTornTail {
+                byte_offset: recovered_at,
+                discarded_bytes: recovered_bytes,
+            },
+            StorageHealth::RecoveredIncompleteWrite {
+                byte_offset,
+                discarded_bytes,
+            },
+        ) => {
+            assert_eq!(recovered_at, byte_offset);
+            assert_eq!(recovered_bytes, discarded_bytes);
+        }
+        other => panic!("recovery and storage disagree: {other:?}"),
+    }
+
+    // Writing more does not change what the open found.
+    db.insert("tasks:9", json!({"n": 9})).unwrap();
+    assert_eq!(db.health(), health);
+    let value: Value = db.get("tasks:9").unwrap().unwrap();
+    assert_eq!(value["n"], json!(9), "and the database is fully usable");
+}

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

@@ -166,7 +166,8 @@ fn a_scan_result_survives_concurrent_mutation() {
     // The scan returns owned records, so mutation after the lock is released
     // cannot invalidate or rewrite what the caller already holds.
     for index in 0..200 {
-        db.delete(&format!("items:record-{index:05}")).expect("delete");
+        db.delete(&format!("items:record-{index:05}"))
+            .expect("delete");
     }
 
     assert_eq!(matches.len(), 50);

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

@@ -41,7 +41,8 @@ fn database() -> (TempDir, FeltDb) {
 /// A database with `status` and `tenantId` indexed on `items`.
 fn indexed() -> (TempDir, FeltDb) {
     let (directory, db) = database();
-    db.create_equality_index("items", "status").expect("declare");
+    db.create_equality_index("items", "status")
+        .expect("declare");
     db.create_equality_index("items", "tenantId")
         .expect("declare");
     (directory, db)
@@ -53,7 +54,9 @@ fn indexed() -> (TempDir, FeltDb) {
 fn assert_index_matches_state(db: &FeltDb, after: &str) {
     match db.verify_equality_index().expect("verify") {
         Ok(()) => {}
-        Err(divergence) => panic!("index diverged from authoritative state after {after}: {divergence}"),
+        Err(divergence) => {
+            panic!("index diverged from authoritative state after {after}: {divergence}")
+        }
     }
 }
 
@@ -67,7 +70,11 @@ fn ids(db: &FeltDb, field: &str, value: Value) -> Vec<String> {
     candidates(db, field, value)
         .expect("the field is indexed and the value is indexable")
         .into_iter()
-        .map(|key| key.split_once(':').map(|(_, id)| id.to_string()).unwrap_or(key))
+        .map(|key| {
+            key.split_once(':')
+                .map(|(_, id)| id.to_string())
+                .unwrap_or(key)
+        })
         .collect()
 }
 
@@ -155,7 +162,11 @@ fn an_update_that_leaves_the_indexed_field_alone_leaves_the_index_alone() {
     db.update("items:a", &json!({ "status": "active", "note": "after" }))
         .expect("update");
 
-    assert_eq!(snapshot(&db), before, "an unrelated field change is invisible to the index");
+    assert_eq!(
+        snapshot(&db),
+        before,
+        "an unrelated field change is invisible to the index"
+    );
     assert_index_matches_state(&db, "an unrelated field changing");
 }
 
@@ -260,7 +271,11 @@ fn unindexable_values_are_excluded_rather_than_coerced() {
     put(&db, "object", json!({ "status": { "state": "active" } }));
     put(&db, "array", json!({ "status": ["active"] }));
     put(&db, "scalar", json!({ "status": "active" }));
-    put(&db, "not-an-object", json!("items are usually objects, but need not be"));
+    put(
+        &db,
+        "not-an-object",
+        json!("items are usually objects, but need not be"),
+    );
 
     assert_eq!(
         ids(&db, "status", json!("active")),
@@ -351,8 +366,16 @@ fn conditional_creation_maintains_the_index_when_it_wins_and_not_when_it_loses()
         key: "items:a".into(),
         value: Some(json!({ "status": "active" })),
     };
-    db.apply_atomic_transaction_guarded("pr35-put-1", None, None, &[], &[absent.clone()], &[write.clone()], None)
-        .expect("the record is absent, so the creation wins");
+    db.apply_atomic_transaction_guarded(
+        "pr35-put-1",
+        None,
+        None,
+        &[],
+        &[absent.clone()],
+        &[write.clone()],
+        None,
+    )
+    .expect("the record is absent, so the creation wins");
     assert_eq!(ids(&db, "status", json!("active")), vec!["a".to_string()]);
     assert_index_matches_state(&db, "a conditional creation that won");
 
@@ -520,14 +543,17 @@ fn declaring_an_index_populates_it_from_state_that_already_exists() {
         None,
         "before declaration there is no index to consult",
     );
-    assert!(db.create_equality_index("items", "status").expect("declare"));
+    assert!(db
+        .create_equality_index("items", "status")
+        .expect("declare"));
     assert_eq!(
         ids(&db, "status", json!("active")),
         vec!["a".to_string()],
         "declaration derives the index from the records already held",
     );
     assert!(
-        !db.create_equality_index("items", "status").expect("declare"),
+        !db.create_equality_index("items", "status")
+            .expect("declare"),
         "re-declaring an existing index reports that it created nothing",
     );
     assert_index_matches_state(&db, "declaring an index over existing state");
@@ -548,8 +574,11 @@ fn an_explicit_rebuild_reproduces_the_maintained_index_exactly() {
         );
     }
     db.delete("items:record-000").expect("delete");
-    db.update("items:record-001", &json!({ "status": "active", "tenantId": "tenant-9" }))
-        .expect("update");
+    db.update(
+        "items:record-001",
+        &json!({ "status": "active", "tenantId": "tenant-9" }),
+    )
+    .expect("update");
 
     let maintained = snapshot(&db);
     db.rebuild_equality_indexes().expect("rebuild");
@@ -567,8 +596,10 @@ fn reopening_the_database_rebuilds_the_index_from_durable_state() {
 
     let before = {
         let db = FeltDb::open(&path).expect("open");
-        db.create_equality_index("items", "status").expect("declare");
-        db.create_equality_index("items", "tenantId").expect("declare");
+        db.create_equality_index("items", "status")
+            .expect("declare");
+        db.create_equality_index("items", "tenantId")
+            .expect("declare");
         for step in 0..48 {
             db.insert(
                 &format!("items:record-{step:03}"),
@@ -577,8 +608,11 @@ fn reopening_the_database_rebuilds_the_index_from_durable_state() {
             .expect("insert");
         }
         db.delete("items:record-005").expect("delete");
-        db.update("items:record-006", &json!({ "status": "active", "tenantId": "tenant-0" }))
-            .expect("update");
+        db.update(
+            "items:record-006",
+            &json!({ "status": "active", "tenantId": "tenant-0" }),
+        )
+        .expect("update");
         db.apply_atomic_transaction_guarded(
             "pr35-restart-tx",
             None,
@@ -587,7 +621,10 @@ fn reopening_the_database_rebuilds_the_index_from_durable_state() {
             &[],
             &[
                 mutation("items:record-007", None),
-                mutation("items:record-100", Some(json!({ "status": "active", "tenantId": "tenant-1" }))),
+                mutation(
+                    "items:record-100",
+                    Some(json!({ "status": "active", "tenantId": "tenant-1" })),
+                ),
             ],
             None,
         )
@@ -600,8 +637,12 @@ fn reopening_the_database_rebuilds_the_index_from_durable_state() {
         reopened.equality_indexes().expect("indexes").is_empty(),
         "an index is derived state: nothing about it is read back from the log",
     );
-    reopened.create_equality_index("items", "status").expect("declare");
-    reopened.create_equality_index("items", "tenantId").expect("declare");
+    reopened
+        .create_equality_index("items", "status")
+        .expect("declare");
+    reopened
+        .create_equality_index("items", "tenantId")
+        .expect("declare");
 
     assert_eq!(
         snapshot(&reopened),
@@ -699,8 +740,11 @@ fn indexed_execution_returns_exactly_what_the_scan_returns() {
 
     // The conjunction actually narrows rather than merely re-filtering: the
     // intersection is smaller than either side.
-    let both = indexed_query(&db, &[("status", json!("active")), ("tenantId", json!("tenant-1"))])
-        .expect("both fields are indexed");
+    let both = indexed_query(
+        &db,
+        &[("status", json!("active")), ("tenantId", json!("tenant-1"))],
+    )
+    .expect("both fields are indexed");
     let one = indexed_query(&db, &[("status", json!("active"))]).expect("indexed");
     assert!(!both.is_empty() && both.len() < one.len());
 }
@@ -718,8 +762,11 @@ fn the_index_selects_candidates_and_the_predicate_still_decides() {
         "the index answers with candidates, both of which satisfy only the indexed condition",
     );
 
-    let result = indexed_query(&db, &[("status", json!("active")), ("role", json!("admin"))])
-        .expect("indexed");
+    let result = indexed_query(
+        &db,
+        &[("status", json!("active")), ("role", json!("admin"))],
+    )
+    .expect("indexed");
     assert_eq!(
         result,
         vec!["items:a".to_string()],
@@ -834,14 +881,19 @@ fn concurrent_mutation_and_indexed_query_stay_coherent() {
         // mean a partially committed transaction became queryable.
         for (sibling, count) in halves {
             if count != 2 {
-                failures.push(format!("transaction pair {sibling} was observed {count} times, not 2"));
+                failures.push(format!(
+                    "transaction pair {sibling} was observed {count} times, not 2"
+                ));
             }
         }
         observations += 1;
     }
 
     running.store(false, Ordering::Relaxed);
-    let cycles: usize = writers.into_iter().map(|handle| handle.join().expect("writer")).sum();
+    let cycles: usize = writers
+        .into_iter()
+        .map(|handle| handle.join().expect("writer"))
+        .sum();
 
     assert!(cycles > 0, "the writers actually mutated the collection");
     assert!(observations > 0, "the reader actually queried");
@@ -881,7 +933,10 @@ fn indexed_and_scan_execution_agree_on_a_concurrently_built_state() {
     for conditions in [
         vec![("status", json!("active"))],
         vec![("tenantId", json!("tenant-3"))],
-        vec![("status", json!("archived")), ("tenantId", json!("tenant-2"))],
+        vec![
+            ("status", json!("archived")),
+            ("tenantId", json!("tenant-2")),
+        ],
     ] {
         assert_eq!(
             indexed_query(&db, &conditions).expect("indexed"),

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

@@ -17,10 +17,8 @@
 
 use feltdb::{
     state_contract::{
-        StateSchema, CollectionSchema, FieldSchema, FieldType, PrimitiveType,
-        FieldConstraints,
-        AuthorizationContext, CanonicalQuery, begin_read, execute_query,
-        QueryFilter,
+        begin_read, execute_query, AuthorizationContext, CanonicalQuery, CollectionSchema,
+        FieldConstraints, FieldSchema, FieldType, PrimitiveType, QueryFilter, StateSchema,
     },
     FeltDb,
 };
@@ -324,8 +322,7 @@ fn pr7_phase3_self_authorization_proof() -> Result<(), Box<dyn std::error::Error
         field_projections: Default::default(),
     };
 
-    let _bob_context = begin_read(&db, &schema, "app", bob_auth)
-        .map_err(|e| format!("{:?}", e))?;
+    let _bob_context = begin_read(&db, &schema, "app", bob_auth).map_err(|e| format!("{:?}", e))?;
 
     // Query as Bob with self(user) policy
     let _query = CanonicalQuery {
@@ -360,8 +357,8 @@ fn pr7_phase3_self_authorization_proof() -> Result<(), Box<dyn std::error::Error
         field_projections: Default::default(),
     };
 
-    let _alice_context = begin_read(&db, &schema, "app", alice_auth)
-        .map_err(|e| format!("{:?}", e))?;
+    let _alice_context =
+        begin_read(&db, &schema, "app", alice_auth).map_err(|e| format!("{:?}", e))?;
 
     println!("  • Alice is member of Org A");
     println!("  • Invitation.organization = {}", org_a_id);