@feltdb/core 0.8.3 → 0.8.4

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

@@ -0,0 +1,892 @@
+//! PR35 — deterministic equality index over authoritative state.
+//!
+//! PR34 removed whole-collection *materialization* from bounded query
+//! execution. What it left behind was still `O(N)`: the conjunction had to be
+//! evaluated against every record of the collection. PR35 adds an equality index
+//! so an applicable query can reach its candidates directly.
+//!
+//! An index is only ever an optimization, which makes correctness the whole
+//! difficulty: a faster query that answers differently is not a faster query, it
+//! is a bug. These tests are therefore organized around the four claims that
+//! have to hold before performance is worth measuring at all.
+//!
+//!   1. **Maintenance.** After every mutation class — insert, update, delete,
+//!      CAS accepted and CAS refused, transaction committed and transaction
+//!      refused — the live index equals one rebuilt from authoritative state.
+//!      `verify_equality_index` performs exactly that comparison, so these
+//!      assertions are against the records, not against a second copy of the
+//!      index's own bookkeeping.
+//!   2. **Candidate selection, not answers.** A lookup returns record keys. The
+//!      predicate still decides.
+//!   3. **Recovery.** Reopening the log and re-declaring the index reproduces
+//!      the index exactly, because a rebuild is the only way an index is ever
+//!      populated.
+//!   4. **Values.** Strings, numbers, booleans, explicit nulls and missing
+//!      fields stay distinguishable, and unindexable values are excluded rather
+//!      than coerced.
+
+use feltdb::{AtomicMutation, FeltDb, RecordPrecondition, StoredRow};
+use serde_json::{json, Value};
+use std::collections::BTreeMap;
+use tempfile::TempDir;
+
+type IndexSnapshot = BTreeMap<String, BTreeMap<String, BTreeMap<String, Vec<String>>>>;
+
+fn database() -> (TempDir, FeltDb) {
+    let directory = TempDir::new().expect("temp dir");
+    let db = FeltDb::open(directory.path().join("pr35.log")).expect("open db");
+    (directory, db)
+}
+
+/// 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", "tenantId")
+        .expect("declare");
+    (directory, db)
+}
+
+/// The invariant every mutation must preserve: the maintained index is exactly
+/// what authoritative state derives.
+#[track_caller]
+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}"),
+    }
+}
+
+fn candidates(db: &FeltDb, field: &str, value: Value) -> Option<Vec<String>> {
+    db.equality_index_candidates("items", field, &value)
+        .expect("lookup")
+}
+
+/// Candidate keys for a value the index can answer, as record ids.
+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))
+        .collect()
+}
+
+fn put(db: &FeltDb, id: &str, value: Value) {
+    db.insert(&format!("items:{id}"), &value).expect("insert");
+}
+
+fn snapshot(db: &FeltDb) -> IndexSnapshot {
+    db.equality_index_snapshot().expect("snapshot")
+}
+
+// ---------------------------------------------------------------------------
+// Basic indexing
+// ---------------------------------------------------------------------------
+
+#[test]
+fn one_indexed_record_is_reachable_by_its_value() {
+    let (_directory, db) = indexed();
+    put(&db, "a", json!({ "status": "active" }));
+
+    assert_eq!(ids(&db, "status", json!("active")), vec!["a".to_string()]);
+    assert_index_matches_state(&db, "one insert");
+}
+
+#[test]
+fn records_sharing_a_value_share_a_bucket_and_different_values_do_not() {
+    let (_directory, db) = indexed();
+    put(&db, "a", json!({ "status": "active" }));
+    put(&db, "b", json!({ "status": "active" }));
+    put(&db, "c", json!({ "status": "archived" }));
+
+    assert_eq!(
+        ids(&db, "status", json!("active")),
+        vec!["a".to_string(), "b".to_string()],
+    );
+    assert_eq!(ids(&db, "status", json!("archived")), vec!["c".to_string()]);
+    assert!(
+        ids(&db, "status", json!("nobody-holds-this")).is_empty(),
+        "a value no record holds is an empty answer, not an inapplicable index",
+    );
+    assert_index_matches_state(&db, "inserts across several values");
+}
+
+#[test]
+fn an_unindexed_field_is_inapplicable_rather_than_empty() {
+    let (_directory, db) = indexed();
+    put(&db, "a", json!({ "status": "active", "role": "admin" }));
+
+    assert_eq!(
+        candidates(&db, "role", json!("admin")),
+        None,
+        "an unindexed field must report that the index cannot answer, so execution falls back",
+    );
+    assert_eq!(
+        candidates(&db, "status", json!("nobody")),
+        Some(Vec::new()),
+        "an indexed field with no holder answers emptily, which is a different thing",
+    );
+}
+
+// ---------------------------------------------------------------------------
+// Updates
+// ---------------------------------------------------------------------------
+
+#[test]
+fn changing_an_indexed_field_moves_the_record_between_buckets() {
+    let (_directory, db) = indexed();
+    put(&db, "a", json!({ "status": "active" }));
+    db.update("items:a", &json!({ "status": "archived" }))
+        .expect("update");
+
+    assert!(
+        ids(&db, "status", json!("active")).is_empty(),
+        "the old value must not retain the record",
+    );
+    assert_eq!(ids(&db, "status", json!("archived")), vec!["a".to_string()]);
+    assert_index_matches_state(&db, "an indexed field changing");
+}
+
+#[test]
+fn an_update_that_leaves_the_indexed_field_alone_leaves_the_index_alone() {
+    let (_directory, db) = indexed();
+    put(&db, "a", json!({ "status": "active", "note": "before" }));
+    let before = snapshot(&db);
+    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_index_matches_state(&db, "an unrelated field changing");
+}
+
+#[test]
+fn removing_and_adding_an_indexed_field_adds_and_removes_the_entry() {
+    let (_directory, db) = indexed();
+    put(&db, "a", json!({ "status": "active" }));
+    db.update("items:a", &json!({ "note": "the status is gone" }))
+        .expect("update");
+
+    assert!(
+        ids(&db, "status", json!("active")).is_empty(),
+        "a record that no longer holds the field holds no entry for it",
+    );
+    assert_index_matches_state(&db, "an indexed field being removed");
+
+    db.update("items:a", &json!({ "note": "back", "status": "active" }))
+        .expect("update");
+    assert_eq!(ids(&db, "status", json!("active")), vec!["a".to_string()]);
+    assert_index_matches_state(&db, "an indexed field being added");
+}
+
+// ---------------------------------------------------------------------------
+// Deletes
+// ---------------------------------------------------------------------------
+
+#[test]
+fn deleting_records_empties_buckets_and_deleting_the_last_one_removes_it() {
+    let (_directory, db) = indexed();
+    put(&db, "a", json!({ "status": "active" }));
+    put(&db, "b", json!({ "status": "active" }));
+
+    db.delete("items:a").expect("delete");
+    assert_eq!(
+        ids(&db, "status", json!("active")),
+        vec!["b".to_string()],
+        "deleting one holder leaves the others",
+    );
+    assert_index_matches_state(&db, "deleting one of several holders");
+
+    db.delete("items:b").expect("delete");
+    assert!(ids(&db, "status", json!("active")).is_empty());
+    assert_eq!(
+        db.equality_index_stats().expect("stats").value_buckets,
+        0,
+        "an emptied bucket is absent, which is the representation a rebuild produces",
+    );
+    assert_index_matches_state(&db, "deleting the final holder of a value");
+}
+
+// ---------------------------------------------------------------------------
+// Values
+// ---------------------------------------------------------------------------
+
+#[test]
+fn distinguishable_values_stay_distinguishable() {
+    let (_directory, db) = indexed();
+    let values = [
+        ("null", json!(null)),
+        ("true", json!(true)),
+        ("false", json!(false)),
+        ("zero", json!(0)),
+        ("one", json!(1)),
+        ("zero-text", json!("0")),
+        ("one-text", json!("1")),
+        ("forty-two", json!(42)),
+        ("forty-two-text", json!("42")),
+        ("true-text", json!("true")),
+        ("empty-text", json!("")),
+    ];
+    for (id, value) in &values {
+        put(&db, id, json!({ "status": value }));
+    }
+
+    for (id, value) in &values {
+        assert_eq!(
+            ids(&db, "status", value.clone()),
+            vec![id.to_string()],
+            "{value} must reach exactly the record holding it",
+        );
+    }
+    assert_index_matches_state(&db, "records covering every scalar kind");
+}
+
+#[test]
+fn a_missing_field_is_not_an_explicit_null() {
+    let (_directory, db) = indexed();
+    put(&db, "explicit", json!({ "status": null }));
+    put(&db, "missing", json!({ "note": "no status here" }));
+
+    assert_eq!(
+        ids(&db, "status", json!(null)),
+        vec!["explicit".to_string()],
+        "an absent field must not be reachable as null: the predicate does not treat them as equal",
+    );
+    assert_index_matches_state(&db, "an explicit null beside a missing field");
+}
+
+#[test]
+fn unindexable_values_are_excluded_rather_than_coerced() {
+    let (_directory, db) = indexed();
+    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"));
+
+    assert_eq!(
+        ids(&db, "status", json!("active")),
+        vec!["scalar".to_string()],
+        "a compound value is never equal to a scalar, so excluding it keeps the candidate set complete",
+    );
+    assert_eq!(
+        candidates(&db, "status", json!({ "state": "active" })),
+        None,
+        "a condition the index cannot represent must report inapplicable, never a wrong answer",
+    );
+    assert_index_matches_state(&db, "compound and non-object records");
+}
+
+#[test]
+fn record_id_is_never_indexable() {
+    let (_directory, db) = database();
+    let refusal = db
+        .create_equality_index("items", "recordId")
+        .expect_err("recordId is authority metadata on the query surface");
+    assert!(
+        refusal.to_string().contains("recordId"),
+        "the refusal must name the field: {refusal}",
+    );
+    assert!(db.equality_indexes().expect("indexes").is_empty());
+}
+
+// ---------------------------------------------------------------------------
+// Mutation primitives: CAS and conditional creation
+// ---------------------------------------------------------------------------
+
+#[test]
+fn an_accepted_cas_moves_the_index_and_a_refused_one_changes_nothing() {
+    let (_directory, db) = indexed();
+    put(&db, "a", json!({ "status": "active", "__version": 1 }));
+
+    let refused = db
+        .compare_and_set_json(
+            "items:a",
+            99,
+            None,
+            None,
+            false,
+            json!({ "status": "archived" }),
+        )
+        .expect("cas");
+    assert!(
+        matches!(refused, feltdb::JsonCasResult::VersionConflict { .. }),
+        "the precondition must fail: {refused:?}",
+    );
+    assert_eq!(
+        ids(&db, "status", json!("active")),
+        vec!["a".to_string()],
+        "a refused CAS writes neither the record nor the index",
+    );
+    assert_index_matches_state(&db, "a refused CAS");
+
+    let accepted = db
+        .compare_and_set_json(
+            "items:a",
+            1,
+            None,
+            None,
+            false,
+            json!({ "status": "archived" }),
+        )
+        .expect("cas");
+    assert!(matches!(accepted, feltdb::JsonCasResult::Updated { .. }));
+    assert!(ids(&db, "status", json!("active")).is_empty());
+    assert_eq!(ids(&db, "status", json!("archived")), vec!["a".to_string()]);
+    assert_index_matches_state(&db, "an accepted CAS");
+}
+
+#[test]
+fn conditional_creation_maintains_the_index_when_it_wins_and_not_when_it_loses() {
+    let (_directory, db) = indexed();
+
+    // putIfAbsent, as the transaction surface expresses it: a staged write
+    // fenced by `require_absent`.
+    let absent = RecordPrecondition {
+        capability: "items".into(),
+        key: "items:a".into(),
+        require_absent: true,
+        ..RecordPrecondition::default()
+    };
+    let write = AtomicMutation {
+        capability: "items".into(),
+        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");
+    assert_eq!(ids(&db, "status", json!("active")), vec!["a".to_string()]);
+    assert_index_matches_state(&db, "a conditional creation that won");
+
+    let losing = AtomicMutation {
+        capability: "items".into(),
+        key: "items:a".into(),
+        value: Some(json!({ "status": "archived" })),
+    };
+    db.apply_atomic_transaction_guarded("pr35-put-2", None, None, &[], &[absent], &[losing], None)
+        .expect_err("the record now exists, so the creation must be refused");
+    assert_eq!(
+        ids(&db, "status", json!("active")),
+        vec!["a".to_string()],
+        "a refused conditional creation leaves the index exactly as it was",
+    );
+    assert!(ids(&db, "status", json!("archived")).is_empty());
+    assert_index_matches_state(&db, "a conditional creation that lost");
+}
+
+// ---------------------------------------------------------------------------
+// Transactions
+// ---------------------------------------------------------------------------
+
+fn mutation(key: &str, value: Option<Value>) -> AtomicMutation {
+    AtomicMutation {
+        capability: "items".into(),
+        key: key.into(),
+        value,
+    }
+}
+
+#[test]
+fn a_transaction_of_one_indexed_mutation_is_atomic_with_the_index() {
+    let (_directory, db) = indexed();
+    db.apply_atomic_transaction_guarded(
+        "pr35-tx-1",
+        None,
+        None,
+        &[],
+        &[],
+        &[mutation("items:a", Some(json!({ "status": "active" })))],
+        None,
+    )
+    .expect("commit");
+
+    assert_eq!(ids(&db, "status", json!("active")), vec!["a".to_string()]);
+    assert_index_matches_state(&db, "a single-mutation transaction");
+}
+
+#[test]
+fn one_transaction_of_insert_update_and_delete_lands_wholly_in_the_index() {
+    let (_directory, db) = indexed();
+    put(&db, "a", json!({ "status": "active" }));
+    put(&db, "b", json!({ "status": "pending" }));
+
+    db.apply_atomic_transaction_guarded(
+        "pr35-tx-mixed",
+        None,
+        None,
+        &[],
+        &[],
+        &[
+            // A: an indexed field changes value.
+            mutation("items:a", Some(json!({ "status": "inactive" }))),
+            // B: removed entirely.
+            mutation("items:b", None),
+            // C: created holding the value A just left.
+            mutation("items:c", Some(json!({ "status": "active" }))),
+        ],
+        None,
+    )
+    .expect("commit");
+
+    assert_eq!(ids(&db, "status", json!("active")), vec!["c".to_string()]);
+    assert_eq!(ids(&db, "status", json!("inactive")), vec!["a".to_string()]);
+    assert!(ids(&db, "status", json!("pending")).is_empty());
+    assert_index_matches_state(&db, "a transaction of insert, update and delete");
+}
+
+#[test]
+fn a_refused_transaction_leaves_the_index_at_its_previous_state() {
+    let (_directory, db) = indexed();
+    put(&db, "a", json!({ "status": "active" }));
+    let before = snapshot(&db);
+
+    db.apply_atomic_transaction_guarded(
+        "pr35-tx-refused",
+        None,
+        None,
+        &[],
+        &[RecordPrecondition {
+            capability: "items".into(),
+            key: "items:a".into(),
+            require_absent: true,
+            ..RecordPrecondition::default()
+        }],
+        &[
+            mutation("items:a", Some(json!({ "status": "archived" }))),
+            mutation("items:z", Some(json!({ "status": "archived" }))),
+        ],
+        None,
+    )
+    .expect_err("the precondition must refuse the transaction");
+
+    assert_eq!(
+        snapshot(&db),
+        before,
+        "a refused transaction publishes no part of itself, the index included",
+    );
+    assert!(
+        ids(&db, "status", json!("archived")).is_empty(),
+        "no mutation of a refused transaction is observable through the index",
+    );
+    assert_index_matches_state(&db, "a refused transaction");
+}
+
+#[test]
+fn a_transaction_touching_no_indexed_field_is_still_consistent() {
+    let (_directory, db) = indexed();
+    db.apply_atomic_transaction_guarded(
+        "pr35-tx-unindexed",
+        None,
+        None,
+        &[],
+        &[],
+        &[mutation("items:a", Some(json!({ "role": "admin" })))],
+        None,
+    )
+    .expect("commit");
+
+    assert!(ids(&db, "status", json!("active")).is_empty());
+    assert_eq!(
+        db.equality_index_stats().expect("stats").entries,
+        0,
+        "a record holding no indexed field contributes no entries",
+    );
+    assert_index_matches_state(&db, "a transaction over unindexed fields");
+}
+
+#[test]
+fn an_unindexed_collection_is_untouched_by_index_maintenance() {
+    let (_directory, db) = indexed();
+    db.insert("orders:1", &json!({ "status": "active" }))
+        .expect("insert");
+    db.update("orders:1", &json!({ "status": "archived" }))
+        .expect("update");
+    db.delete("orders:1").expect("delete");
+
+    assert!(snapshot(&db).is_empty());
+    assert_index_matches_state(&db, "mutations of a collection nobody indexed");
+}
+
+// ---------------------------------------------------------------------------
+// Lifecycle and recovery
+// ---------------------------------------------------------------------------
+
+#[test]
+fn declaring_an_index_populates_it_from_state_that_already_exists() {
+    let (_directory, db) = database();
+    put(&db, "a", json!({ "status": "active" }));
+    put(&db, "b", json!({ "status": "archived" }));
+
+    assert_eq!(
+        candidates(&db, "status", json!("active")),
+        None,
+        "before declaration there is no index to consult",
+    );
+    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"),
+        "re-declaring an existing index reports that it created nothing",
+    );
+    assert_index_matches_state(&db, "declaring an index over existing state");
+
+    assert!(db.drop_equality_index("items", "status").expect("drop"));
+    assert_eq!(candidates(&db, "status", json!("active")), None);
+    assert!(!db.drop_equality_index("items", "status").expect("drop"));
+}
+
+#[test]
+fn an_explicit_rebuild_reproduces_the_maintained_index_exactly() {
+    let (_directory, db) = indexed();
+    for step in 0..64 {
+        put(
+            &db,
+            &format!("record-{step:03}"),
+            json!({ "status": if step % 3 == 0 { "active" } else { "archived" }, "tenantId": format!("tenant-{}", step % 4) }),
+        );
+    }
+    db.delete("items:record-000").expect("delete");
+    db.update("items:record-001", &json!({ "status": "active", "tenantId": "tenant-9" }))
+        .expect("update");
+
+    let maintained = snapshot(&db);
+    db.rebuild_equality_indexes().expect("rebuild");
+    assert_eq!(
+        snapshot(&db),
+        maintained,
+        "a rebuild is the definition of correct: maintenance must have produced the same thing",
+    );
+}
+
+#[test]
+fn reopening_the_database_rebuilds_the_index_from_durable_state() {
+    let directory = TempDir::new().expect("temp dir");
+    let path = directory.path().join("pr35-restart.log");
+
+    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");
+        for step in 0..48 {
+            db.insert(
+                &format!("items:record-{step:03}"),
+                &json!({ "status": if step % 5 == 0 { "active" } else { "archived" }, "tenantId": format!("tenant-{}", step % 3) }),
+            )
+            .expect("insert");
+        }
+        db.delete("items:record-005").expect("delete");
+        db.update("items:record-006", &json!({ "status": "active", "tenantId": "tenant-0" }))
+            .expect("update");
+        db.apply_atomic_transaction_guarded(
+            "pr35-restart-tx",
+            None,
+            None,
+            &[],
+            &[],
+            &[
+                mutation("items:record-007", None),
+                mutation("items:record-100", Some(json!({ "status": "active", "tenantId": "tenant-1" }))),
+            ],
+            None,
+        )
+        .expect("commit");
+        snapshot(&db)
+    };
+
+    let reopened = FeltDb::open(&path).expect("reopen");
+    assert!(
+        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");
+
+    assert_eq!(
+        snapshot(&reopened),
+        before,
+        "the index derived from recovered records must equal the index maintained before the restart",
+    );
+    assert_index_matches_state(&reopened, "a restart");
+}
+
+// ---------------------------------------------------------------------------
+// Candidate selection, conjunctions, and scan equivalence
+// ---------------------------------------------------------------------------
+
+/// The scan execution: the predicate against every record of the collection.
+fn scan(db: &FeltDb, conditions: &[(&str, Value)]) -> Vec<String> {
+    let rows = db
+        .query_collection("items", None, |row| matches_all(row, conditions))
+        .expect("scan");
+    rows.into_iter().map(|row| row.key).collect()
+}
+
+/// The indexed execution: candidates from the index, then the same predicate.
+fn indexed_query(db: &FeltDb, conditions: &[(&str, Value)]) -> Option<Vec<String>> {
+    let equalities: Vec<(&str, &Value)> = conditions
+        .iter()
+        .map(|(field, value)| (*field, value))
+        .collect();
+    db.query_collection_by_equality("items", &equalities, |row| matches_all(row, conditions))
+        .expect("indexed query")
+        .map(|rows| rows.into_iter().map(|row| row.key).collect())
+}
+
+fn matches_all(row: &StoredRow, conditions: &[(&str, Value)]) -> bool {
+    conditions
+        .iter()
+        .all(|(field, value)| row.value.get(field) == Some(value))
+}
+
+#[test]
+fn indexed_execution_returns_exactly_what_the_scan_returns() {
+    let (_directory, db) = indexed();
+    let statuses = ["active", "archived", "pending"];
+    for step in 0..200 {
+        put(
+            &db,
+            &format!("record-{step:03}"),
+            json!({
+                "status": statuses[step % 3],
+                "tenantId": format!("tenant-{}", step % 7),
+                "role": if step % 2 == 0 { "admin" } else { "member" },
+            }),
+        );
+    }
+
+    let corpus: Vec<Vec<(&str, Value)>> = vec![
+        vec![("status", json!("active"))],
+        vec![("status", json!("pending"))],
+        vec![("status", json!("nobody-holds-this"))],
+        vec![("tenantId", json!("tenant-3"))],
+        // A indexed, B unindexed.
+        vec![("status", json!("active")), ("role", json!("admin"))],
+        // A unindexed, B indexed.
+        vec![("role", json!("member")), ("tenantId", json!("tenant-2"))],
+        // Both indexed.
+        vec![("status", json!("active")), ("tenantId", json!("tenant-1"))],
+        // Both indexed, no common member.
+        vec![("status", json!("active")), ("status", json!("archived"))],
+        // Three conditions, two of them indexed.
+        vec![
+            ("status", json!("archived")),
+            ("tenantId", json!("tenant-5")),
+            ("role", json!("admin")),
+        ],
+        // One condition matches, the other cannot.
+        vec![("status", json!("active")), ("role", json!("nobody"))],
+        // Neither indexed.
+        vec![("role", json!("admin"))],
+    ];
+
+    for conditions in &corpus {
+        let scanned = scan(&db, conditions);
+        match indexed_query(&db, conditions) {
+            Some(indexed) => assert_eq!(
+                indexed, scanned,
+                "indexed and scan execution disagreed on {conditions:?}",
+            ),
+            None => assert!(
+                conditions
+                    .iter()
+                    .all(|(field, _)| !matches!(*field, "status" | "tenantId")),
+                "only a query with no indexed equality may report the index inapplicable: {conditions:?}",
+            ),
+        }
+    }
+
+    // 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 one = indexed_query(&db, &[("status", json!("active"))]).expect("indexed");
+    assert!(!both.is_empty() && both.len() < one.len());
+}
+
+#[test]
+fn the_index_selects_candidates_and_the_predicate_still_decides() {
+    let (_directory, db) = indexed();
+    put(&db, "a", json!({ "status": "active", "role": "admin" }));
+    put(&db, "b", json!({ "status": "active", "role": "member" }));
+
+    let candidates = candidates(&db, "status", json!("active")).expect("indexed");
+    assert_eq!(
+        candidates,
+        vec!["items:a".to_string(), "items:b".to_string()],
+        "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");
+    assert_eq!(
+        result,
+        vec!["items:a".to_string()],
+        "the predicate, not the index, decides which candidate matches",
+    );
+}
+
+// ---------------------------------------------------------------------------
+// Concurrency
+// ---------------------------------------------------------------------------
+
+/// Mutations and indexed queries against the same collection, at the same time.
+///
+/// The claim under test is not a scheduling order — there is no new isolation
+/// guarantee here and none is being asserted. It is that *every* result a query
+/// observes corresponds to a coherent committed state: a candidate the index
+/// produced is a record that exists, a record the predicate accepted really
+/// satisfies it, and a transaction is never half-visible. A defect in the
+/// mutation boundary would show up here as a candidate with no record behind it
+/// or a record whose bucket no longer describes it.
+#[test]
+fn concurrent_mutation_and_indexed_query_stay_coherent() {
+    use std::sync::atomic::{AtomicBool, Ordering};
+    use std::sync::Arc;
+
+    let (_directory, db) = indexed();
+    for step in 0..400 {
+        put(
+            &db,
+            &format!("seed-{step:03}"),
+            json!({ "status": if step % 2 == 0 { "active" } else { "archived" }, "tenantId": "tenant-0" }),
+        );
+    }
+
+    let running = Arc::new(AtomicBool::new(true));
+    let mut writers = Vec::new();
+    for worker in 0..4 {
+        let db = db.clone();
+        let running = running.clone();
+        writers.push(std::thread::spawn(move || {
+            let mut step = 0usize;
+            while running.load(Ordering::Relaxed) && step < 200 {
+                let id = format!("items:churn-{worker}-{step}");
+                let created = json!({ "status": "active", "tenantId": "tenant-0", "__version": 1 });
+                db.insert(&id, &created).expect("insert");
+                db.update(&id, &json!({ "status": "archived", "tenantId": "tenant-1", "__version": 1 }))
+                    .expect("update");
+                db.compare_and_set_json(&id, 1, None, None, false, json!({ "status": "active", "tenantId": "tenant-1" }))
+                    .expect("cas");
+                // A transaction whose two halves must never be seen apart.
+                db.apply_atomic_transaction_guarded(
+                    &format!("pr35-race-{worker}-{step}"),
+                    None,
+                    None,
+                    &[],
+                    &[],
+                    &[
+                        mutation(&format!("{id}-tx-a"), Some(json!({ "status": "paired", "tenantId": "tenant-2", "pair": worker }))),
+                        mutation(&format!("{id}-tx-b"), Some(json!({ "status": "paired", "tenantId": "tenant-2", "pair": worker }))),
+                    ],
+                    None,
+                )
+                .expect("commit");
+                db.delete(&id).expect("delete");
+                step += 1;
+            }
+            step
+        }));
+    }
+
+    let mut observations = 0usize;
+    let mut failures: Vec<String> = Vec::new();
+    for _ in 0..400 {
+        // Every record the indexed execution reaches must actually hold the
+        // value it was bucketed under.
+        //
+        // The check runs *inside* the execution, because candidate selection and
+        // the record read have to observe one state to mean anything. Copying
+        // candidate keys out and reading the records afterwards would be two
+        // acquisitions of the state lock with a writer between them, and the
+        // dangling key that produces is an artifact of asking the question in
+        // two parts — not a defect in the index. The query path does not ask it
+        // in two parts, and neither does this.
+        for (field, value) in [("status", json!("active")), ("tenantId", json!("tenant-1"))] {
+            // The predicate keeps everything the index reached, so what comes
+            // back is the candidate set itself, read coherently.
+            let reached = db
+                .query_collection_by_equality("items", &[(field, &value)], |_| true)
+                .expect("indexed query")
+                .expect("the field is indexed");
+            for row in reached {
+                if row.value.get(field) != Some(&value) {
+                    failures.push(format!(
+                        "{} was reached through the {field} bucket for {value} but does not hold it",
+                        row.key,
+                    ));
+                }
+            }
+        }
+
+        let paired = indexed_query(&db, &[("status", json!("paired"))]).expect("indexed");
+        let mut halves: BTreeMap<String, usize> = BTreeMap::new();
+        for key in &paired {
+            let sibling = key
+                .strip_suffix("-tx-a")
+                .or_else(|| key.strip_suffix("-tx-b"))
+                .unwrap_or(key)
+                .to_string();
+            *halves.entry(sibling).or_default() += 1;
+        }
+        // A pair is written by one transaction. Seeing exactly one half would
+        // 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"));
+            }
+        }
+        observations += 1;
+    }
+
+    running.store(false, Ordering::Relaxed);
+    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");
+    assert_eq!(failures, Vec::<String>::new());
+    assert_index_matches_state(&db, "concurrent mutation and query");
+}
+
+/// Indexed and scan execution must still agree once the churn has stopped, on a
+/// state that concurrency produced rather than a test wrote by hand.
+#[test]
+fn indexed_and_scan_execution_agree_on_a_concurrently_built_state() {
+    use std::sync::Arc;
+
+    let (_directory, db) = indexed();
+    let mut writers = Vec::new();
+    for worker in 0..4 {
+        let db = Arc::new(db.clone());
+        writers.push(std::thread::spawn(move || {
+            for step in 0..150 {
+                let id = format!("items:w{worker}-{step:03}");
+                db.insert(
+                    &id,
+                    &json!({ "status": if step % 3 == 0 { "active" } else { "archived" }, "tenantId": format!("tenant-{}", step % 5) }),
+                )
+                .expect("insert");
+                if step % 7 == 0 {
+                    db.delete(&id).expect("delete");
+                }
+            }
+        }));
+    }
+    for writer in writers {
+        writer.join().expect("writer");
+    }
+
+    assert_index_matches_state(&db, "four concurrent writers");
+    for conditions in [
+        vec![("status", json!("active"))],
+        vec![("tenantId", json!("tenant-3"))],
+        vec![("status", json!("archived")), ("tenantId", json!("tenant-2"))],
+    ] {
+        assert_eq!(
+            indexed_query(&db, &conditions).expect("indexed"),
+            scan(&db, &conditions),
+            "executions disagreed on {conditions:?} after concurrent writes",
+        );
+    }
+}