@feltdb/core 0.8.2 → 0.8.4

package/dist/create/server-source/crates/feltdb/src/workload_diagnostics.rs

@@ -0,0 +1,443 @@
+//! Phase-level execution attribution for the sustained workload.
+//!
+//! PR33 named query execution as the sustained-workload bottleneck. PR34
+//! removed whole-collection materialization and PR35 removed the full predicate
+//! scan, taking the workload from 274.1 to 1,665.9 ops/sec on one runner. PR36
+//! asks what is left, and that question cannot be answered from throughput:
+//! an aggregate rate says how fast the system is, never where the time went.
+//!
+//! So this module records **where the time went**, as elapsed nanoseconds and a
+//! call count per execution phase. Three properties keep it honest:
+//!
+//! 1. **The boundaries are real.** Every phase brackets an actual span of
+//!    execution — the wait for the state lock, the index lookup, the record
+//!    fetch, the predicate, the sort, the log append. Nothing here is a
+//!    proportion inferred from wall-clock time, and a phase that cannot be
+//!    bracketed cleanly is simply absent rather than estimated.
+//! 2. **Phases nest, and the report says so.** `STATE_LOCK_HOLD` contains
+//!    `RECORD_MUTATION`, `INDEX_MAINTENANCE` and `PERSISTENCE`; `INDEXED_QUERY`
+//!    contains `INDEX_LOOKUP`, `CANDIDATE_RETRIEVAL` and `PREDICATE_EVALUATION`.
+//!    Summing every phase would double-count, which is why [`Phase::parent`]
+//!    exists and why the analysis distinguishes exclusive time from nested time.
+//! 3. **It is off unless asked for.** Disabled, each instrumented site costs one
+//!    relaxed atomic load and a predictable branch; no clock is read and no
+//!    counter is touched. It is enabled by `FELTDB_WORKLOAD_DIAGNOSTICS=1`, is
+//!    test instrumentation rather than a product surface, and reports counts and
+//!    durations only — never a record, a field, a value or an id.
+//!
+//! Instrumentation that changes what it measures is not a measurement, so the
+//! overhead of *enabled* diagnostics is itself measured, and the headline
+//! production figures are taken with diagnostics off.
+
+use std::sync::atomic::{AtomicU64, Ordering};
+use std::time::Instant;
+
+/// One bracketed span of execution.
+///
+/// Ordered so that a report reads top-down: request, then query phases, then
+/// mutation phases. The discriminant is the counter index, so adding a phase
+/// means adding it here and to [`Phase::ALL`] and nothing else.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+#[repr(usize)]
+pub enum Phase {
+    /// Waiting to acquire the single state lock. Pure contention: no work is
+    /// done here, which is what makes it the one phase whose time is always
+    /// wasted rather than merely spent.
+    StateLockWait = 0,
+    /// Holding the state lock. Contains every phase below that touches state,
+    /// and bounds how long other operations can be made to wait.
+    StateLockHold,
+    /// A bounded query answered from the equality index, end to end.
+    IndexedQuery,
+    /// Turning `(field, value)` into candidate record ids inside the index.
+    IndexLookup,
+    /// Fetching authoritative records for candidate ids.
+    CandidateRetrieval,
+    /// Evaluating the query's conjunction against a record, on either execution.
+    PredicateEvaluation,
+    /// A bounded query answered by scanning the collection, end to end.
+    ScanQuery,
+    /// Sorting the matching set into the query's requested order.
+    Ordering,
+    /// Cloning matches and injecting `recordId` to build the visible result.
+    ResultMaterialization,
+    /// Writing or removing a record in the authoritative map.
+    RecordMutation,
+    /// Maintaining the derived equality index alongside that record change.
+    IndexMaintenance,
+    /// Appending to the durable log, including any fsync it performs.
+    Persistence,
+    /// Transaction bookkeeping around a commit: preconditions, operation
+    /// construction, revision and dedup accounting. Excludes the log append.
+    TransactionCommit,
+    /// A whole HTTP handler, measured inside the server between extraction and
+    /// response. The gap between this and the client's own timing is transport,
+    /// decode and encode.
+    HttpHandler,
+    /// Authenticating and authorizing a request: key lookup, signature and
+    /// capability checks. Nested inside `HttpHandler`, and separated from it
+    /// because "the request costs something outside state" is not an answer —
+    /// which part of the request is.
+    Authorization,
+    /// The request's whole dealing with the security audit subsystem: building
+    /// the event, submitting it to the audit writer, and waiting for the
+    /// writer to accept it. Nested inside `HttpHandler` and deliberately not
+    /// folded into `Persistence`, which is the *state* log — these are two
+    /// different durable writes with two different reasons to exist, and
+    /// attributing them together would hide which one costs what.
+    ///
+    /// Since PR38 this span no longer contains a durability barrier. The
+    /// barrier happens on the audit writer's own threads, in
+    /// `AuditGroupSync`, after the request has already been released.
+    AuditWrite,
+    /// Handing the event to the audit writer's bounded queue. Fails fast when
+    /// the queue is at capacity rather than blocking the request.
+    AuditSubmit,
+    /// Waiting for the audit writer to append the submitted event to the
+    /// stream — the acceptance boundary, and the only part of the audit
+    /// pipeline a request waits for.
+    ///
+    /// This is the audit path's analogue of `StateLockWait`, and it is where
+    /// the single-writer discipline shows up as time: a request waits behind
+    /// the appends in front of it, and behind whatever the writer is doing
+    /// when it arrives.
+    AuditAcceptWait,
+    /// Opening the audit file, on the writer thread. Since PR38 the writer
+    /// keeps the handle, so this happens once per stream rather than once per
+    /// event; it is still measured, because "once" is a claim.
+    AuditOpen,
+    /// Serializing one event into the writer's reusable buffer and issuing the
+    /// single `write(2)` that appends it. On the writer thread.
+    AuditAppend,
+    /// `File::flush` on the audit handle, inside a durability group. A
+    /// `std::fs::File` holds no userspace buffer, so this is measured rather
+    /// than assumed to be free.
+    AuditFlush,
+    /// `File::sync_data` on the audit handle: the durability barrier itself,
+    /// and the one phase that asks the storage stack for a guarantee rather
+    /// than for a write. On the syncer thread, off the request path.
+    AuditFsync,
+    /// One whole durability group: the flush and the barrier that make a
+    /// bounded set of already-accepted events durable. On the syncer thread.
+    AuditGroupSync,
+    /// Closing the audit file handle at shutdown. Measured because it is a
+    /// syscall, and because the point of the writer owning the handle is that
+    /// this no longer happens per event.
+    AuditClose,
+    /// The body of a request handler, from the first line of the handler
+    /// function to its return.
+    ///
+    /// It exists to bracket what a middleware cannot. `HttpHandler` wraps the
+    /// whole route, so it includes axum's extraction — where the request JSON is
+    /// decoded — and the response conversion, where the response JSON is
+    /// encoded. Neither can be timed from inside a handler or from a middleware
+    /// alone. The difference `HttpHandler - HandlerBody - Authorization -
+    /// AuditWrite` is therefore routing plus decode plus encode, measured as a
+    /// difference of two spans rather than asserted.
+    HandlerBody,
+}
+
+impl Phase {
+    pub const ALL: [Phase; 25] = [
+        Phase::StateLockWait,
+        Phase::StateLockHold,
+        Phase::IndexedQuery,
+        Phase::IndexLookup,
+        Phase::CandidateRetrieval,
+        Phase::PredicateEvaluation,
+        Phase::ScanQuery,
+        Phase::Ordering,
+        Phase::ResultMaterialization,
+        Phase::RecordMutation,
+        Phase::IndexMaintenance,
+        Phase::Persistence,
+        Phase::TransactionCommit,
+        Phase::HttpHandler,
+        Phase::Authorization,
+        Phase::AuditWrite,
+        Phase::AuditSubmit,
+        Phase::AuditAcceptWait,
+        Phase::AuditOpen,
+        Phase::AuditAppend,
+        Phase::AuditFlush,
+        Phase::AuditFsync,
+        Phase::AuditGroupSync,
+        Phase::AuditClose,
+        Phase::HandlerBody,
+    ];
+
+    /// The stable name this phase is reported under.
+    pub fn name(self) -> &'static str {
+        match self {
+            Phase::StateLockWait => "state_lock_wait",
+            Phase::StateLockHold => "state_lock_hold",
+            Phase::IndexedQuery => "indexed_query",
+            Phase::IndexLookup => "index_lookup",
+            Phase::CandidateRetrieval => "candidate_retrieval",
+            Phase::PredicateEvaluation => "predicate_evaluation",
+            Phase::ScanQuery => "scan_query",
+            Phase::Ordering => "ordering",
+            Phase::ResultMaterialization => "result_materialization",
+            Phase::RecordMutation => "record_mutation",
+            Phase::IndexMaintenance => "index_maintenance",
+            Phase::Persistence => "persistence",
+            Phase::TransactionCommit => "transaction_commit",
+            Phase::HttpHandler => "http_handler",
+            Phase::Authorization => "authorization",
+            Phase::AuditWrite => "audit_write",
+            Phase::AuditSubmit => "audit_submit",
+            Phase::AuditAcceptWait => "audit_accept_wait",
+            Phase::AuditOpen => "audit_open",
+            Phase::AuditAppend => "audit_append",
+            Phase::AuditFlush => "audit_flush",
+            Phase::AuditFsync => "audit_fsync",
+            Phase::AuditGroupSync => "audit_group_sync",
+            Phase::AuditClose => "audit_close",
+            Phase::HandlerBody => "handler_body",
+        }
+    }
+
+    /// The phase whose span contains this one, when there is one.
+    ///
+    /// This is what stops a reader from adding the columns up. A phase's time is
+    /// already counted inside its parent, so only sibling phases at one level
+    /// can be compared, and only exclusive time can be summed.
+    pub fn parent(self) -> Option<Phase> {
+        match self {
+            Phase::StateLockWait | Phase::StateLockHold | Phase::HttpHandler => None,
+            Phase::IndexedQuery | Phase::ScanQuery => Some(Phase::StateLockHold),
+            Phase::IndexLookup | Phase::CandidateRetrieval => Some(Phase::IndexedQuery),
+            // The predicate runs on both executions, so its parent is the lock
+            // rather than either query phase.
+            Phase::PredicateEvaluation => Some(Phase::StateLockHold),
+            Phase::Authorization | Phase::AuditWrite | Phase::HandlerBody => {
+                Some(Phase::HttpHandler)
+            }
+            Phase::Ordering | Phase::ResultMaterialization => Some(Phase::HandlerBody),
+            Phase::RecordMutation | Phase::IndexMaintenance | Phase::Persistence => {
+                Some(Phase::StateLockHold)
+            }
+            Phase::TransactionCommit => Some(Phase::StateLockHold),
+            // What the request pays decomposes into the submit and the wait for
+            // acceptance, and nothing else: since PR38 no other audit phase
+            // happens on the request's thread.
+            Phase::AuditSubmit | Phase::AuditAcceptWait => Some(Phase::AuditWrite),
+            // The flush and the barrier are the two halves of one durability
+            // group.
+            Phase::AuditFlush | Phase::AuditFsync => Some(Phase::AuditGroupSync),
+            // Deliberately parentless. `AuditOpen`, `AuditAppend`,
+            // `AuditGroupSync` and `AuditClose` run on the audit writer's own
+            // threads, concurrently with the requests that produced them.
+            // Nesting them under `AuditWrite` or `HttpHandler` would let a
+            // reader compute a share of a span they do not run inside, and
+            // that share could exceed one hundred per cent.
+            Phase::AuditOpen
+            | Phase::AuditAppend
+            | Phase::AuditGroupSync
+            | Phase::AuditClose => None,
+        }
+    }
+}
+
+const PHASES: usize = Phase::ALL.len();
+
+#[allow(clippy::declare_interior_mutable_const)]
+const ZERO: AtomicU64 = AtomicU64::new(0);
+static CALLS: [AtomicU64; PHASES] = [ZERO; PHASES];
+static NANOS: [AtomicU64; PHASES] = [ZERO; PHASES];
+static ENABLED: AtomicU64 = AtomicU64::new(UNRESOLVED);
+
+const UNRESOLVED: u64 = 0;
+const OFF: u64 = 1;
+const ON: u64 = 2;
+
+/// Is phase attribution recording?
+///
+/// Resolved once from `FELTDB_WORKLOAD_DIAGNOSTICS`, then a relaxed load. The
+/// environment is read at most once per process, so a hot path never touches the
+/// environment and never allocates.
+#[inline]
+pub fn enabled() -> bool {
+    match ENABLED.load(Ordering::Relaxed) {
+        ON => true,
+        OFF => false,
+        _ => {
+            let resolved = if std::env::var("FELTDB_WORKLOAD_DIAGNOSTICS").as_deref() == Ok("1") {
+                ON
+            } else {
+                OFF
+            };
+            ENABLED.store(resolved, Ordering::Relaxed);
+            resolved == ON
+        }
+    }
+}
+
+/// Turn recording on or off for the current process, for tests that need to
+/// measure the instrumentation itself rather than through it.
+pub fn set_enabled(on: bool) {
+    ENABLED.store(if on { ON } else { OFF }, Ordering::Relaxed);
+}
+
+/// An open span. Dropping it records the elapsed time against its phase.
+///
+/// Constructed only when recording is on, so the disabled path allocates
+/// nothing and never reads the clock.
+#[derive(Debug)]
+pub struct Span {
+    phase: Phase,
+    began: Instant,
+}
+
+impl Drop for Span {
+    fn drop(&mut self) {
+        let elapsed = self.began.elapsed().as_nanos().min(u64::MAX as u128) as u64;
+        let index = self.phase as usize;
+        CALLS[index].fetch_add(1, Ordering::Relaxed);
+        NANOS[index].fetch_add(elapsed, Ordering::Relaxed);
+    }
+}
+
+/// Open a span, or `None` when recording is off.
+///
+/// The `Option` is the whole disabled-path cost: no clock read, no atomic
+/// write, and a branch the predictor gets right every time.
+#[inline]
+pub fn span(phase: Phase) -> Option<Span> {
+    enabled().then(|| Span {
+        phase,
+        began: Instant::now(),
+    })
+}
+
+/// Record a duration measured elsewhere, such as a lock wait that has to be
+/// timed across an acquisition rather than around a closure.
+#[inline]
+pub fn record(phase: Phase, nanos: u64) {
+    if !enabled() {
+        return;
+    }
+    let index = phase as usize;
+    CALLS[index].fetch_add(1, Ordering::Relaxed);
+    NANOS[index].fetch_add(nanos, Ordering::Relaxed);
+}
+
+/// Time one closure into a phase and return its value.
+#[inline]
+pub fn timed<T>(phase: Phase, body: impl FnOnce() -> T) -> T {
+    let _span = span(phase);
+    body()
+}
+
+/// What one phase accumulated: how often, and for how long.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct PhaseCounter {
+    pub phase: Phase,
+    pub calls: u64,
+    pub nanos: u64,
+}
+
+impl PhaseCounter {
+    pub fn mean_nanos(&self) -> u64 {
+        self.nanos.checked_div(self.calls).unwrap_or(0)
+    }
+}
+
+/// Read every phase counter. Monotonic since process start or the last
+/// [`reset`], so a caller compares deltas across a measured window.
+pub fn counters() -> Vec<PhaseCounter> {
+    Phase::ALL
+        .iter()
+        .map(|&phase| PhaseCounter {
+            phase,
+            calls: CALLS[phase as usize].load(Ordering::Relaxed),
+            nanos: NANOS[phase as usize].load(Ordering::Relaxed),
+        })
+        .collect()
+}
+
+/// Zero every counter, so a phase of a measurement starts from a clean base.
+pub fn reset() {
+    for index in 0..PHASES {
+        CALLS[index].store(0, Ordering::Relaxed);
+        NANOS[index].store(0, Ordering::Relaxed);
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::sync::{Mutex, MutexGuard, OnceLock};
+
+    /// Counters are process-global; a counter assertion is only meaningful
+    /// while no other test in this module is recording.
+    fn exclusive() -> MutexGuard<'static, ()> {
+        static SERIAL: OnceLock<Mutex<()>> = OnceLock::new();
+        SERIAL
+            .get_or_init(|| Mutex::new(()))
+            .lock()
+            .unwrap_or_else(|poisoned| poisoned.into_inner())
+    }
+
+    fn counter(phase: Phase) -> PhaseCounter {
+        counters()
+            .into_iter()
+            .find(|counter| counter.phase == phase)
+            .expect("every phase is reported")
+    }
+
+    #[test]
+    fn a_disabled_span_records_nothing() {
+        let _serial = exclusive();
+        set_enabled(false);
+        reset();
+
+        for _ in 0..1_000 {
+            let _span = span(Phase::Ordering);
+        }
+
+        assert_eq!(counter(Phase::Ordering).calls, 0);
+        assert!(
+            span(Phase::Ordering).is_none(),
+            "a disabled span is not constructed, so it reads no clock",
+        );
+    }
+
+    #[test]
+    fn an_enabled_span_records_calls_and_elapsed_time() {
+        let _serial = exclusive();
+        set_enabled(true);
+        reset();
+
+        for _ in 0..8 {
+            timed(Phase::IndexLookup, || std::hint::black_box(0u64));
+        }
+        let observed = counter(Phase::IndexLookup);
+        assert_eq!(observed.calls, 8);
+        assert!(observed.nanos > 0, "a span of real work takes real time");
+
+        set_enabled(false);
+    }
+
+    #[test]
+    fn every_phase_is_reported_and_nesting_is_declared() {
+        let _serial = exclusive();
+        let reported: Vec<&str> = counters()
+            .into_iter()
+            .map(|counter| counter.phase.name())
+            .collect();
+        assert_eq!(reported.len(), Phase::ALL.len());
+        // A phase must not be its own ancestor, or a report could not
+        // distinguish exclusive time from nested time.
+        for phase in Phase::ALL {
+            let mut ancestor = phase.parent();
+            let mut depth = 0;
+            while let Some(current) = ancestor {
+                assert_ne!(current, phase, "{} is its own ancestor", phase.name());
+                depth += 1;
+                assert!(depth < PHASES, "phase nesting must terminate");
+                ancestor = current.parent();
+            }
+        }
+    }
+}

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

@@ -0,0 +1,233 @@
+//! PR34 — bounded query execution without collection materialization.
+//!
+//! `FeltDb::query_collection` is the state-access primitive the bounded query
+//! surface executes on. These tests pin the two properties the query path
+//! depends on: it observes every live record of a collection in record-key
+//! order, and it clones only the records its predicate retains.
+
+use feltdb::{query_execution_diagnostics, FeltDb, StoredRow};
+use serde_json::json;
+use std::sync::{Mutex, MutexGuard, OnceLock};
+use tempfile::TempDir;
+
+/// The read counters are process-global, and the test binary runs its tests in
+/// threads of one process, so a counter assertion is only meaningful while no
+/// other test in this file is reading a collection.
+fn exclusive() -> MutexGuard<'static, ()> {
+    static SERIAL: OnceLock<Mutex<()>> = OnceLock::new();
+    SERIAL
+        .get_or_init(|| Mutex::new(()))
+        .lock()
+        .unwrap_or_else(|poisoned| poisoned.into_inner())
+}
+
+fn seeded(records: usize) -> (TempDir, FeltDb) {
+    let directory = TempDir::new().expect("temp dir");
+    let db = FeltDb::open(directory.path().join("pr34.log")).expect("open db");
+    for index in 0..records {
+        db.insert(
+            &format!("items:record-{index:05}"),
+            json!({ "tenant": format!("tenant-{}", index % 4), "n": index }),
+        )
+        .expect("insert");
+    }
+    (directory, db)
+}
+
+#[test]
+fn scan_returns_only_matching_records() {
+    let _serial = exclusive();
+    let (_directory, db) = seeded(40);
+
+    let matches = db
+        .query_collection("items", None, |row| {
+            row.value.get("tenant") == Some(&json!("tenant-1"))
+        })
+        .expect("scan");
+
+    assert_eq!(matches.len(), 10, "one quarter of the collection matches");
+    assert!(matches
+        .iter()
+        .all(|row| row.value.get("tenant") == Some(&json!("tenant-1"))));
+}
+
+#[test]
+fn scan_of_an_empty_or_unknown_collection_is_empty() {
+    let _serial = exclusive();
+    let (_directory, db) = seeded(0);
+
+    assert!(db
+        .query_collection("items", None, |_| true)
+        .expect("scan")
+        .is_empty());
+    assert!(db
+        .query_collection("no-such-collection", None, |_| true)
+        .expect("scan")
+        .is_empty());
+}
+
+#[test]
+fn scan_visits_records_in_record_key_order() {
+    let _serial = exclusive();
+    let (_directory, db) = seeded(16);
+
+    let keys: Vec<String> = db
+        .query_collection("items", None, |_| true)
+        .expect("scan")
+        .iter()
+        .map(|row: &StoredRow| row.key.clone())
+        .collect();
+    let mut sorted = keys.clone();
+    sorted.sort();
+
+    assert_eq!(keys, sorted, "traversal follows the collection's key order");
+}
+
+#[test]
+fn a_limit_stops_the_traversal_once_it_is_satisfied() {
+    let _serial = exclusive();
+    let (_directory, db) = seeded(500);
+
+    let mut visited = 0usize;
+    let matches = db
+        .query_collection("items", Some(5), |_| {
+            visited += 1;
+            true
+        })
+        .expect("scan");
+
+    assert_eq!(matches.len(), 5, "the limit bounds the result");
+    assert_eq!(
+        visited, 5,
+        "a satisfied limit stops the traversal instead of walking the collection"
+    );
+}
+
+#[test]
+fn a_scan_clones_only_the_records_it_retains() {
+    let _serial = exclusive();
+    let (_directory, db) = seeded(2_000);
+
+    let before = query_execution_diagnostics::counters();
+    let matches = db
+        .query_collection("items", None, |row| row.value.get("n") == Some(&json!(7)))
+        .expect("scan");
+    let after = query_execution_diagnostics::counters();
+
+    assert_eq!(matches.len(), 1);
+    assert_eq!(
+        after.full_collection_materializations, before.full_collection_materializations,
+        "a scan must not fall back to full collection materialization"
+    );
+    assert_eq!(
+        after.scan_records_visited - before.scan_records_visited,
+        2_000,
+        "the predicate observes every record, borrowed"
+    );
+    assert_eq!(
+        after.scan_records_materialized - before.scan_records_materialized,
+        1,
+        "only the matching record is cloned"
+    );
+}
+
+#[test]
+fn full_materialization_is_still_counted_for_readers_that_ask_for_it() {
+    let _serial = exclusive();
+    let (_directory, db) = seeded(32);
+
+    let before = query_execution_diagnostics::counters();
+    let rows = db.list_collection("items").expect("list");
+    let after = query_execution_diagnostics::counters();
+
+    assert_eq!(rows.len(), 32);
+    assert_eq!(
+        after.full_collection_materializations - before.full_collection_materializations,
+        1
+    );
+    assert_eq!(
+        after.full_collection_records_cloned - before.full_collection_records_cloned,
+        32,
+        "listing a collection clones every record in it"
+    );
+}
+
+#[test]
+fn a_scan_result_survives_concurrent_mutation() {
+    let _serial = exclusive();
+    let (_directory, db) = seeded(200);
+
+    let matches = db
+        .query_collection("items", None, |row| {
+            row.value.get("tenant") == Some(&json!("tenant-0"))
+        })
+        .expect("scan");
+
+    // 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");
+    }
+
+    assert_eq!(matches.len(), 50);
+    assert!(matches
+        .iter()
+        .all(|row| row.value.get("tenant") == Some(&json!("tenant-0"))));
+    assert!(db
+        .query_collection("items", None, |_| true)
+        .expect("scan")
+        .is_empty());
+}
+
+/// PR35 addition: the indexed execution must not reach the materializing path.
+///
+/// PR34's claim was that a bounded query never enters `list_collection`. PR35
+/// adds a second execution, and an optimization that quietly fell back into a
+/// whole-collection clone would satisfy every correctness test in this
+/// repository while undoing the thing PR34 established. So the property is
+/// re-asserted against the execution that did not exist when it was first
+/// proved: indexed execution materializes nothing, and does not scan either.
+#[test]
+fn an_indexed_query_neither_materializes_nor_scans_the_collection() {
+    let _serial = exclusive();
+    let (_directory, db) = seeded(400);
+    db.create_equality_index("items", "tenant")
+        .expect("declare index");
+
+    let before = query_execution_diagnostics::counters();
+    let tenant = json!("tenant-1");
+    let matches = db
+        .query_collection_by_equality("items", &[("tenant", &tenant)], |row| {
+            row.value.get("tenant") == Some(&json!("tenant-1"))
+        })
+        .expect("indexed query")
+        .expect("the field is indexed");
+    let after = query_execution_diagnostics::counters();
+
+    assert_eq!(matches.len(), 100, "one quarter of the collection matches");
+    assert_eq!(
+        after.full_collection_materializations - before.full_collection_materializations,
+        0,
+        "indexed execution must not enter the full-collection materialization path",
+    );
+    assert_eq!(
+        after.collection_scans - before.collection_scans,
+        0,
+        "indexed execution is not a scan",
+    );
+    assert_eq!(
+        after.scan_records_visited - before.scan_records_visited,
+        0,
+        "and therefore visits no record by traversal",
+    );
+    assert_eq!(
+        after.queries_indexed - before.queries_indexed,
+        1,
+        "the query is attributed to the indexed execution",
+    );
+    assert_eq!(
+        after.records_predicate_evaluated - before.records_predicate_evaluated,
+        100,
+        "the predicate runs against the candidate set, not the collection",
+    );
+}