@feltdb/core 0.8.3 → 0.8.4

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

@@ -41,6 +41,7 @@ pub mod durable_dedup_set;
 pub mod durable_operation_identity;
 pub mod durable_operation_log;
 pub mod durable_sync;
+pub mod equality_index;
 mod execution;
 pub mod in_process_transport;
 pub mod indexing;
@@ -98,6 +99,7 @@ mod phase_5_soak;
 pub mod policy_evaluation;
 pub mod production_api;
 mod provenance;
+pub mod query_execution_diagnostics;
 pub mod query_performance;
 mod references;
 pub mod replay_fuzzing;
@@ -131,6 +133,7 @@ mod workflow_acceptance_tests;
 mod workflow_integration;
 mod workflow_runtime;
 pub mod workload;
+pub mod workload_diagnostics;
 
 pub use acquisition::{
     AcquisitionDeduplicator, AcquisitionPolicy, AcquisitionResult, ContentRequest, ContentResponse,
@@ -182,6 +185,7 @@ pub use distributed_transactions::{
     DistributedTransactionExecutor, EnvelopeId, ReplicaState, ReplicationMessage,
     TransactionEnvelope,
 };
+pub use equality_index::{EqualityIndex, EqualityIndexStats, IndexKey};
 pub use execution::{Execution, ExecutionQueue, ExecutionStatus, RetryPolicy};
 pub use indexing::{IndexConfig, IndexManager, IndexStats, IndexType};
 pub use materialization::{MaterializationHandler, ReactiveCollectionIntegration};
@@ -251,7 +255,7 @@ use serde_json::Value;
 use sha2::{Digest, Sha256};
 use std::any::type_name;
 use std::collections::hash_map::DefaultHasher;
-use std::collections::{BTreeMap, HashMap, HashSet};
+use std::collections::{BTreeMap, BTreeSet, HashMap, HashSet};
 use std::fmt::{Display, Formatter};
 use std::fs::{self, OpenOptions};
 use std::hash::{Hash, Hasher};
@@ -352,6 +356,133 @@ struct Inner {
     transaction_payload_hashes: HashMap<String, String>,
     transaction_revisions: HashMap<String, (u64, u64)>,
     collection_cardinality: HashMap<String, u64>,
+    /// Derived equality index over `rows`. Never durable, never replicated, and
+    /// never consulted for anything but candidate selection: it is maintained
+    /// inside the same state mutation boundary as `rows` and rebuilt from
+    /// `rows` after recovery.
+    equality_index: EqualityIndex,
+}
+
+/// The state lock, held with its wait and hold time attributable.
+///
+/// FeltDB serializes every read and every write behind one mutex, so "how long
+/// did an operation take" and "how long did it make everything else wait" are
+/// different questions. PR34 showed the second one mattered: a query holding the
+/// lock while it cloned a collection inflated the cost of unrelated writes.
+///
+/// This guard answers both. It records the time spent *waiting* to acquire —
+/// which is pure contention, the one span where no work happens at all — and the
+/// time spent *holding*, which bounds how long anything else can be forced to
+/// wait. Both are off unless `FELTDB_WORKLOAD_DIAGNOSTICS=1`, where acquisition
+/// costs one relaxed atomic load and no clock read.
+///
+/// It dereferences to [`Inner`], so every existing use site reads unchanged.
+struct StateGuard<'a> {
+    inner: std::sync::MutexGuard<'a, Inner>,
+    held_since: Option<std::time::Instant>,
+}
+
+impl std::ops::Deref for StateGuard<'_> {
+    type Target = Inner;
+    fn deref(&self) -> &Inner {
+        &self.inner
+    }
+}
+
+impl std::ops::DerefMut for StateGuard<'_> {
+    fn deref_mut(&mut self) -> &mut Inner {
+        &mut self.inner
+    }
+}
+
+impl Drop for StateGuard<'_> {
+    fn drop(&mut self) {
+        if let Some(since) = self.held_since {
+            workload_diagnostics::record(
+                workload_diagnostics::Phase::StateLockHold,
+                since.elapsed().as_nanos().min(u64::MAX as u128) as u64,
+            );
+        }
+    }
+}
+
+/// The single state mutation boundary for authoritative records.
+///
+/// Every path that changes a record — insert, update, delete, CAS, transaction
+/// commit, replicated operation apply, log replay, snapshot install — goes
+/// through these three methods, and they change the record map and the derived
+/// equality index together while the caller still holds the state lock. That is
+/// the whole atomicity argument: there is no window in which a committed record
+/// exists without its index entries, or an index entry survives its record,
+/// because no code path can write one without the other.
+///
+/// The index is deliberately maintained here rather than through an independent
+/// index API. An independent API would have to be called, correctly, by nine
+/// separate mutation paths; a missed call would be a silent divergence that only
+/// a query would reveal. Routing every write through one boundary makes the
+/// omission impossible to write in the first place.
+impl Inner {
+    /// Write one record, replacing any record already at its key.
+    ///
+    /// Returns `true` when this created a record rather than replacing one, which
+    /// is what collection cardinality accounting needs.
+    fn put_row(&mut self, row: StoredRow) -> bool {
+        let capability = row.capability.clone();
+        let key = row.key.clone();
+        let indexed = self.equality_index.indexes_collection(&capability);
+        let mutation = workload_diagnostics::span(workload_diagnostics::Phase::RecordMutation);
+        let bucket = self.rows.entry(capability.clone()).or_default();
+        let previous = bucket.insert(key.clone(), row);
+        drop(mutation);
+        if !indexed {
+            return previous.is_none();
+        }
+        // From here on the work exists only because an index does. Measuring it
+        // apart from the record write is what makes "did index maintenance
+        // become a write-side cost?" a question with an answer.
+        let _index = workload_diagnostics::span(workload_diagnostics::Phase::IndexMaintenance);
+        // Old entries first, then new ones. Doing it in this order means a
+        // record whose indexed field did not change is removed from and
+        // re-added to the same bucket, which is a no-op rather than a gap.
+        if let Some(previous) = &previous {
+            self.equality_index
+                .remove_record(&capability, &key, &previous.value);
+        }
+        // Disjoint field borrows: the record map is read while the index is
+        // written. Nothing is cloned to maintain the index.
+        let Inner {
+            rows,
+            equality_index,
+            ..
+        } = self;
+        if let Some(current) = rows.get(&capability).and_then(|rows| rows.get(&key)) {
+            equality_index.insert_record(&capability, &key, &current.value);
+        }
+        previous.is_none()
+    }
+
+    /// Remove one record. Returns `true` when a record was actually removed.
+    fn remove_row(&mut self, capability: &str, key: &str) -> bool {
+        let mutation = workload_diagnostics::span(workload_diagnostics::Phase::RecordMutation);
+        let Some(removed) = self
+            .rows
+            .get_mut(capability)
+            .and_then(|bucket| bucket.remove(key))
+        else {
+            return false;
+        };
+        drop(mutation);
+        let _index = workload_diagnostics::span(workload_diagnostics::Phase::IndexMaintenance);
+        self.equality_index
+            .remove_record(capability, key, &removed.value);
+        true
+    }
+
+    /// Drop all records, as a snapshot install does. The index follows.
+    fn clear_rows(&mut self) {
+        self.rows.clear();
+        self.equality_index.clear();
+    }
 }
 
 #[derive(Debug, Clone, Serialize, Deserialize)]
@@ -722,7 +853,7 @@ impl FeltDb {
             .to_string();
         let rust_type = type_name::<Value>().to_string();
         let (result, event) = {
-            let mut inner = self.inner.lock().expect("lock poisoned");
+            let mut inner = self.state();
             let Some(current) = inner.rows.get(&capability).and_then(|rows| rows.get(key)) else {
                 return Ok(JsonCasResult::NotFound);
             };
@@ -822,11 +953,7 @@ impl FeltDb {
             append_event(&inner.path, &row)?;
             inner.authority_revision += 1;
             inner.change_log.add_operation(operation);
-            inner
-                .rows
-                .entry(capability.clone())
-                .or_default()
-                .insert(key.to_string(), row.clone());
+            inner.put_row(row.clone());
             let event = ChangeEvent {
                 capability,
                 key: key.to_string(),
@@ -975,7 +1102,7 @@ impl FeltDb {
             .map(|(cap, _)| cap)
             .unwrap_or("default")
             .to_string();
-        let inner = self.inner.lock().expect("lock poisoned");
+        let inner = self.state();
         let value = inner
             .rows
             .get(&capability)
@@ -991,7 +1118,7 @@ impl FeltDb {
         F: Fn(&T) -> bool,
     {
         let rust_type = type_name::<T>().to_string();
-        let mut inner = self.inner.lock().expect("lock poisoned");
+        let mut inner = self.state();
         *inner
             .query_count_by_type
             .entry(rust_type.clone())
@@ -1024,19 +1151,19 @@ impl FeltDb {
 
     pub fn is_auto_indexed<T>(&self) -> bool {
         let rust_type = type_name::<T>().to_string();
-        let inner = self.inner.lock().expect("lock poisoned");
+        let inner = self.state();
         inner.adaptive_indexes.contains(&rust_type)
     }
 
     /// Get the instance ID for this FeltDB instance
     pub fn instance_id(&self) -> Result<String> {
-        let inner = self.inner.lock().expect("lock poisoned");
+        let inner = self.state();
         Ok(inner.instance_id.clone())
     }
 
     /// Get the current sequence number for this instance
     pub fn sequence(&self) -> Result<u64> {
-        let inner = self.inner.lock().expect("lock poisoned");
+        let inner = self.state();
         Ok(inner.sequence)
     }
 
@@ -1044,13 +1171,13 @@ impl FeltDb {
     /// In multi-process topology callers must use `AuthorityClient::read` to
     /// cross the authority boundary and obtain a current authoritative value.
     pub fn current_revision(&self) -> Result<u64> {
-        Ok(self.inner.lock().expect("lock poisoned").authority_revision)
+        Ok(self.state().authority_revision)
     }
 
     /// Capture revision and rows under one lock. Authority reads must never
     /// pair metadata from one commit with state from another.
     pub(crate) fn authority_state(&self) -> (u64, Vec<StoredRow>) {
-        let inner = self.inner.lock().expect("lock poisoned");
+        let inner = self.state();
         let rows = inner
             .rows
             .values()
@@ -1062,7 +1189,7 @@ impl FeltDb {
     /// Get the maintained cardinality (record count) for a collection capability.
     /// Returns the count of non-deleted records in the collection.
     pub fn collection_cardinality(&self, capability: &str) -> Result<u64> {
-        let inner = self.inner.lock().expect("lock poisoned");
+        let inner = self.state();
         Ok(inner
             .collection_cardinality
             .get(capability)
@@ -1073,7 +1200,7 @@ impl FeltDb {
     /// Diagnostic: List all collection capabilities and their cardinalities.
     /// Used to detect capability format mismatches.
     pub fn list_cardinalities(&self) -> Result<Vec<(String, u64)>> {
-        let inner = self.inner.lock().expect("lock poisoned");
+        let inner = self.state();
         let mut result: Vec<_> = inner
             .collection_cardinality
             .iter()
@@ -1086,7 +1213,7 @@ impl FeltDb {
     /// Diagnostic: Count actual rows for a given capability pattern.
     /// Used to verify that rows exist even if cardinality is 0.
     pub fn diagnostic_row_count(&self, capability_pattern: &str) -> Result<usize> {
-        let inner = self.inner.lock().expect("lock poisoned");
+        let inner = self.state();
         Ok(inner
             .rows
             .iter()
@@ -1098,7 +1225,7 @@ impl FeltDb {
     /// Diagnostic: Get actual persisted capability strings matching a pattern.
     /// Used to identify capability identity formats in use.
     pub fn diagnostic_capability_keys(&self, capability_pattern: &str) -> Result<Vec<String>> {
-        let inner = self.inner.lock().expect("lock poisoned");
+        let inner = self.state();
         let mut keys: Vec<_> = inner
             .rows
             .keys()
@@ -1195,7 +1322,7 @@ impl FeltDb {
         audit: Option<Value>,
     ) -> Result<AtomicCommit> {
         let (commit, events) = {
-            let mut inner = self.inner.lock().expect("lock poisoned");
+            let mut inner = self.state();
             if inner.applied_transactions.contains(transaction_id) {
                 if let Some(expected_hash) = payload_hash {
                     if inner
@@ -1385,6 +1512,14 @@ impl FeltDb {
                 &advanced
             };
 
+            // Transaction bookkeeping is measured as one span per commit even
+            // though it brackets two regions: everything before the durable
+            // append, and the revision, dedup and payload-hash accounting after
+            // the rows are applied. The append itself is `Persistence` and the
+            // apply loop is `RecordMutation` + `IndexMaintenance`, so summing
+            // this with those does not double-count any of them.
+            let mut bookkeeping_nanos = 0u64;
+            let prepare_began = workload_diagnostics::enabled().then(std::time::Instant::now);
             let base_revision = inner.authority_revision;
             if let Some(expected) = expected_parent {
                 if expected != base_revision {
@@ -1480,6 +1615,9 @@ impl FeltDb {
                 rows: rows.clone(),
                 audit,
             };
+            if let Some(began) = prepare_began {
+                bookkeeping_nanos += began.elapsed().as_nanos().min(u64::MAX as u128) as u64;
+            }
             append_transaction(&inner.path, &record)?;
             inner.authority_revision = base_revision + 1;
             inner.sequence = next_sequence;
@@ -1488,9 +1626,7 @@ impl FeltDb {
                     inner.change_log.add_operation(operation);
                 }
                 if row.deleted {
-                    if let Some(bucket) = inner.rows.get_mut(&row.capability) {
-                        bucket.remove(&row.key);
-                    }
+                    inner.remove_row(&row.capability, &row.key);
                     // Decrement cardinality on delete
                     let count = inner
                         .collection_cardinality
@@ -1498,17 +1634,10 @@ impl FeltDb {
                         .or_default();
                     *count = count.saturating_sub(1);
                 } else {
-                    // Track whether this is an insert (new row) or update (existing row)
-                    let is_insert = !inner
-                        .rows
-                        .get(&row.capability)
-                        .is_some_and(|bucket| bucket.contains_key(&row.key));
-
-                    inner
-                        .rows
-                        .entry(row.capability.clone())
-                        .or_default()
-                        .insert(row.key.clone(), row.clone());
+                    // Record and index change together, inside the commit that
+                    // is already holding the state lock: a transaction that is
+                    // refused leaves neither, and one that commits publishes both.
+                    let is_insert = inner.put_row(row.clone());
 
                     // Increment cardinality only on insert, not update
                     if is_insert {
@@ -1520,6 +1649,7 @@ impl FeltDb {
                     }
                 }
             }
+            let tail_began = workload_diagnostics::enabled().then(std::time::Instant::now);
             inner.sync_state.merge_vector_clock(&vector_clock);
             inner.applied_transactions.insert(transaction_id.into());
             let commit_revision = inner.authority_revision;
@@ -1531,6 +1661,13 @@ impl FeltDb {
                     .transaction_payload_hashes
                     .insert(transaction_id.into(), hash.into());
             }
+            if let Some(began) = tail_began {
+                bookkeeping_nanos += began.elapsed().as_nanos().min(u64::MAX as u128) as u64;
+            }
+            workload_diagnostics::record(
+                workload_diagnostics::Phase::TransactionCommit,
+                bookkeeping_nanos,
+            );
             let events = rows
                 .iter()
                 .map(|row| ChangeEvent {
@@ -1616,7 +1753,7 @@ impl FeltDb {
         };
 
         {
-            let mut inner = self.inner.lock().expect("lock poisoned");
+            let mut inner = self.state();
 
             // Increment sequence number
             inner.sequence += 1;
@@ -1645,11 +1782,7 @@ impl FeltDb {
 
             append_event(&inner.path, &row)?;
             inner.authority_revision += 1;
-            inner
-                .rows
-                .entry(capability.clone())
-                .or_default()
-                .insert(key.clone(), row);
+            inner.put_row(row);
             let suffix = key.rsplit_once(':').map(|(_, right)| right);
             if let Some(id) = suffix.and_then(|s| s.parse::<u64>().ok()) {
                 let entry = inner.key_counters.entry(capability.clone()).or_default();
@@ -1689,7 +1822,7 @@ impl FeltDb {
         };
 
         {
-            let mut inner = self.inner.lock().expect("lock poisoned");
+            let mut inner = self.state();
 
             // Increment sequence number
             inner.sequence += 1;
@@ -1718,11 +1851,7 @@ impl FeltDb {
 
             append_event(&inner.path, &row)?;
             inner.authority_revision += 1;
-            inner
-                .rows
-                .entry(capability.clone())
-                .or_default()
-                .insert(key.clone(), row);
+            inner.put_row(row);
         }
 
         let event = ChangeEvent {
@@ -1738,7 +1867,7 @@ impl FeltDb {
 
     fn delete_internal(&self, capability: String, key: String) -> Result<()> {
         {
-            let mut inner = self.inner.lock().expect("lock poisoned");
+            let mut inner = self.state();
 
             // Get the row to determine its type
             let rust_type = inner
@@ -1788,10 +1917,8 @@ impl FeltDb {
             append_event(&inner.path, &tombstone)?;
             inner.authority_revision += 1;
 
-            // Remove from in-memory store
-            if let Some(bucket) = inner.rows.get_mut(&capability) {
-                bucket.remove(&key);
-            }
+            // Remove from in-memory store, index entries included.
+            inner.remove_row(&capability, &key);
         }
 
         let event = ChangeEvent {
@@ -1831,7 +1958,7 @@ impl FeltDb {
         let rust_type = type_name::<T>().to_string();
 
         let initial_results = {
-            let mut inner = self.inner.lock().expect("lock poisoned");
+            let mut inner = self.state();
             *inner
                 .query_count_by_type
                 .entry(rust_type.clone())
@@ -1870,7 +1997,7 @@ impl FeltDb {
 
     /// Get current sync state information
     pub fn sync_info(&self) -> Result<SyncState> {
-        let inner = self.inner.lock().expect("lock poisoned");
+        let inner = self.state();
         Ok(inner.sync_state.clone())
     }
 
@@ -1880,13 +2007,326 @@ impl FeltDb {
     }
 
     /// List the canonical values in one collection/capability namespace.
+    ///
+    /// This clones the whole collection, so its cost is linear in collection
+    /// size. Readers that discard most of what they receive — a filtered query,
+    /// for example — should use [`FeltDb::query_collection`] instead, which
+    /// evaluates borrowed rows and clones only what it keeps.
     pub fn list_collection(&self, capability: &str) -> Result<Vec<StoredRow>> {
-        let inner = self.inner.lock().expect("lock poisoned");
-        Ok(inner
+        let inner = self.state();
+        let rows: Vec<StoredRow> = inner
             .rows
             .get(capability)
             .map(|rows| rows.values().cloned().collect())
-            .unwrap_or_default())
+            .unwrap_or_default();
+        query_execution_diagnostics::record_full_materialization(rows.len());
+        Ok(rows)
+    }
+
+    /// Evaluate a predicate over one collection without materializing it.
+    ///
+    /// The predicate observes each live row *borrowed* from state, so a record
+    /// the predicate rejects is never cloned. Only retained rows are cloned,
+    /// which happens while state protection is still held: the returned rows are
+    /// owned, so nothing the caller keeps can reference storage a concurrent
+    /// mutation may move or drop after the lock is released.
+    ///
+    /// Traversal is the collection's own record-key order, the same order
+    /// [`FeltDb::list_collection_page`] walks. `limit` bounds accumulation and
+    /// stops the traversal as soon as it is satisfied; because early stopping
+    /// truncates in record-key order, a caller that must order results by some
+    /// other field has to pass `None` and bound its own already-filtered set.
+    ///
+    /// The predicate runs under the state lock, so it must not call back into
+    /// the database or block.
+    pub fn query_collection<F>(
+        &self,
+        capability: &str,
+        limit: Option<usize>,
+        mut predicate: F,
+    ) -> Result<Vec<StoredRow>>
+    where
+        F: FnMut(&StoredRow) -> bool,
+    {
+        let mut matched = Vec::new();
+        let mut visited = 0usize;
+        {
+            let inner = self.state();
+            let _query = workload_diagnostics::span(workload_diagnostics::Phase::ScanQuery);
+            if let Some(rows) = inner.rows.get(capability) {
+                for row in rows.values() {
+                    if limit.is_some_and(|bound| matched.len() >= bound) {
+                        break;
+                    }
+                    visited += 1;
+                    // The same predicate phase the indexed execution reports to,
+                    // so the two executions' predicate cost is directly
+                    // comparable rather than being two different measurements.
+                    let _predicate =
+                        workload_diagnostics::span(workload_diagnostics::Phase::PredicateEvaluation);
+                    if predicate(row) {
+                        drop(_predicate);
+                        matched.push(row.clone());
+                    }
+                }
+            }
+        }
+        query_execution_diagnostics::record_scan(visited, matched.len());
+        Ok(matched)
+    }
+
+    // ----------------------------------------------------------------------
+    // Equality index — lifecycle and execution.
+    //
+    // The index is derived state. Every method below either declares what is
+    // derived, re-derives it from authoritative records, or reads candidate
+    // record keys out of it. None of them is a source of truth, and none of
+    // them can answer a query on its own: `query_collection_by_equality` still
+    // evaluates the caller's full predicate against authoritative records.
+    // ----------------------------------------------------------------------
+
+    /// Acquire the state lock, attributing the wait and the hold.
+    ///
+    /// Every path in this file that touches authoritative state goes through
+    /// here, which is what makes lock contention a measured quantity rather than
+    /// a residual inferred from wall-clock time.
+    fn state(&self) -> StateGuard<'_> {
+        if !workload_diagnostics::enabled() {
+            return StateGuard {
+                inner: self.inner.lock().expect("lock poisoned"),
+                held_since: None,
+            };
+        }
+        let requested = std::time::Instant::now();
+        let inner = self.inner.lock().expect("lock poisoned");
+        let acquired = std::time::Instant::now();
+        workload_diagnostics::record(
+            workload_diagnostics::Phase::StateLockWait,
+            acquired.duration_since(requested).as_nanos().min(u64::MAX as u128) as u64,
+        );
+        StateGuard {
+            inner,
+            held_since: Some(acquired),
+        }
+    }
+
+    /// Declare an equality index on one collection field and populate it from
+    /// authoritative state. Returns whether this call created the index.
+    ///
+    /// Creation and population happen under one lock, so an index is never
+    /// observable in a half-built state. Declaring an index that already exists
+    /// is not an error and does not rebuild it.
+    ///
+    /// `recordId` is refused: on the query surface it is authority metadata that
+    /// shadows a document field of the same name on object-valued records only,
+    /// so an index over the document field would answer a different question
+    /// from the one the predicate asks.
+    pub fn create_equality_index(&self, collection: &str, field: &str) -> Result<bool> {
+        let mut inner = self.state();
+        let created = inner
+            .equality_index
+            .declare(collection, field)
+            .map_err(FlowError::CapabilityError)?;
+        if created {
+            let Inner {
+                rows,
+                equality_index,
+                ..
+            } = &mut *inner;
+            equality_index.rebuild_field(collection, field, rows);
+        }
+        Ok(created)
+    }
+
+    /// Drop an equality index and its buckets. Returns whether one existed.
+    pub fn drop_equality_index(&self, collection: &str, field: &str) -> Result<bool> {
+        let mut inner = self.state();
+        Ok(inner.equality_index.undeclare(collection, field))
+    }
+
+    /// Every declared index, as `(collection, field)` in a stable order.
+    pub fn equality_indexes(&self) -> Result<Vec<(String, String)>> {
+        let inner = self.state();
+        Ok(inner.equality_index.declarations())
+    }
+
+    /// Re-derive every declared index from authoritative records.
+    ///
+    /// This is the recovery path. An index is never read from disk and never
+    /// received from a peer: after a restart, a snapshot install, or any other
+    /// reload of authoritative state, the index is whatever this produces.
+    pub fn rebuild_equality_indexes(&self) -> Result<EqualityIndexStats> {
+        let mut inner = self.state();
+        let Inner {
+            rows,
+            equality_index,
+            ..
+        } = &mut *inner;
+        equality_index.rebuild(rows);
+        Ok(equality_index.stats())
+    }
+
+    /// Index size, as counts. Never a value, never a record id.
+    pub fn equality_index_stats(&self) -> Result<EqualityIndexStats> {
+        let inner = self.state();
+        Ok(inner.equality_index.stats())
+    }
+
+    /// A fully ordered rendering of the live index.
+    ///
+    /// Test instrumentation. It exists so a test can compare the live index
+    /// against one rebuilt from authoritative state; nothing in execution reads
+    /// it, and it is not part of any product surface.
+    #[doc(hidden)]
+    pub fn equality_index_snapshot(
+        &self,
+    ) -> Result<BTreeMap<String, BTreeMap<String, BTreeMap<String, Vec<String>>>>> {
+        let inner = self.state();
+        Ok(inner.equality_index.snapshot())
+    }
+
+    /// The index invariant: the live index equals one derived from records now.
+    ///
+    /// Returns a description of the first divergence rather than a bare bool, so
+    /// a failing assertion says what diverged. This is the strongest statement
+    /// available about index maintenance, because it compares the maintained
+    /// structure against the authoritative state it claims to describe rather
+    /// than against a second copy of its own bookkeeping.
+    pub fn verify_equality_index(&self) -> Result<std::result::Result<(), String>> {
+        let inner = self.state();
+        let live = inner.equality_index.snapshot();
+        let mut expected = inner.equality_index.clone();
+        expected.clear();
+        expected.rebuild(&inner.rows);
+        let expected = expected.snapshot();
+        if live == expected {
+            return Ok(Ok(()));
+        }
+        for (collection, fields) in expected.iter() {
+            for (field, buckets) in fields {
+                let observed = live.get(collection).and_then(|fields| fields.get(field));
+                if observed != Some(buckets) {
+                    return Ok(Err(format!(
+                        "index for {collection}.{field} diverges from authoritative state: \
+                         {} value buckets held, {} derived",
+                        observed.map(BTreeMap::len).unwrap_or(0),
+                        buckets.len(),
+                    )));
+                }
+            }
+        }
+        Ok(Err(
+            "the live index holds entries no authoritative record derives".to_string()
+        ))
+    }
+
+    /// Candidate record keys for one equality condition, copied out of the index.
+    ///
+    /// `None` means the index cannot answer that condition — the field is not
+    /// indexed, or the value is not an indexable scalar — and the caller must
+    /// fall back to a scan. `Some(empty)` is an answer, not a failure.
+    ///
+    /// The keys are copied while the state lock is held. Nothing borrowed from
+    /// the index or from the record map escapes this call.
+    pub fn equality_index_candidates(
+        &self,
+        collection: &str,
+        field: &str,
+        value: &Value,
+    ) -> Result<Option<Vec<String>>> {
+        let inner = self.state();
+        Ok(inner
+            .equality_index
+            .candidates(collection, field, value)
+            .map(|keys| keys.iter().cloned().collect()))
+    }
+
+    /// Execute a bounded query through the equality index when one applies.
+    ///
+    /// `equalities` are the query's equality conditions, in the caller's order.
+    /// At least one of them must be indexed and hold an indexable value, or this
+    /// returns `Ok(None)` and the caller falls back to [`FeltDb::query_collection`].
+    /// Returning `None` rather than an empty result is the difference between
+    /// "the index does not apply" and "nothing matches", and conflating the two
+    /// would silently drop records.
+    ///
+    /// When the index does apply, every applicable condition contributes a
+    /// candidate set and the sets are intersected smallest-first. The result is
+    /// still only *candidates*: `predicate` — the caller's existing, unmodified
+    /// predicate — decides what matches, evaluated against authoritative records.
+    /// The index therefore cannot change what a query returns, only how many
+    /// records the predicate has to look at.
+    ///
+    /// Candidate keys, the record lookups they drive and the predicate all run
+    /// under one acquisition of the state lock, so a query observes one coherent
+    /// committed state exactly as a scan does. Records are cloned only when the
+    /// predicate keeps them, and nothing borrowed from state outlives the lock.
+    pub fn query_collection_by_equality<F>(
+        &self,
+        capability: &str,
+        equalities: &[(&str, &Value)],
+        mut predicate: F,
+    ) -> Result<Option<Vec<StoredRow>>>
+    where
+        F: FnMut(&StoredRow) -> bool,
+    {
+        let mut matched = Vec::new();
+        let mut examined = 0usize;
+        let mut evaluated = 0usize;
+        {
+            let inner = self.state();
+            let _query = workload_diagnostics::span(workload_diagnostics::Phase::IndexedQuery);
+            // Candidate selection, timed apart from record access: PR36 has to
+            // be able to say whether the index lookup itself has become a cost,
+            // and "index query time" alone could not distinguish a slow lookup
+            // from a large candidate set.
+            let lookup = workload_diagnostics::span(workload_diagnostics::Phase::IndexLookup);
+            let mut applicable: Vec<&BTreeSet<String>> = Vec::new();
+            for (field, value) in equalities {
+                if let Some(keys) = inner.equality_index.candidates(capability, field, value) {
+                    applicable.push(keys);
+                }
+            }
+            if applicable.is_empty() {
+                drop(lookup);
+                drop(_query);
+                drop(inner);
+                query_execution_diagnostics::record_index_miss();
+                return Ok(None);
+            }
+            // Smallest first. This is not cost estimation: a set's length is
+            // already held by the set, so intersecting from the smallest is
+            // simply the cheaper order to do the same work.
+            applicable.sort_by_key(|keys| keys.len());
+            drop(lookup);
+            let (smallest, rest) = applicable.split_first().expect("non-empty");
+            let bucket = inner.rows.get(capability);
+            for key in smallest.iter() {
+                if !rest.iter().all(|keys| keys.contains(key)) {
+                    continue;
+                }
+                examined += 1;
+                let retrieval =
+                    workload_diagnostics::span(workload_diagnostics::Phase::CandidateRetrieval);
+                let row = bucket.and_then(|rows| rows.get(key));
+                drop(retrieval);
+                let Some(row) = row else {
+                    // An index entry with no record behind it would be a
+                    // maintenance defect. Skipping it keeps the query correct
+                    // rather than surfacing a record that does not exist.
+                    continue;
+                };
+                evaluated += 1;
+                let _predicate =
+                    workload_diagnostics::span(workload_diagnostics::Phase::PredicateEvaluation);
+                if predicate(row) {
+                    drop(_predicate);
+                    matched.push(row.clone());
+                }
+            }
+        }
+        query_execution_diagnostics::record_indexed_query(examined, evaluated, matched.len());
+        Ok(Some(matched))
     }
 
     /// Traverse one collection in immutable record-key order without materializing it.
@@ -1896,7 +2336,7 @@ impl FeltDb {
         after: Option<&str>,
         limit: usize,
     ) -> Result<Vec<StoredRow>> {
-        let inner = self.inner.lock().expect("lock poisoned");
+        let inner = self.state();
         let Some(rows) = inner.rows.get(capability) else {
             return Ok(vec![]);
         };
@@ -1916,7 +2356,7 @@ impl FeltDb {
 
     /// Fetch one live collection record without materializing collection state.
     pub fn get_collection_record(&self, capability: &str, key: &str) -> Result<Option<StoredRow>> {
-        let inner = self.inner.lock().expect("lock poisoned");
+        let inner = self.state();
         Ok(inner
             .rows
             .get(capability)
@@ -1932,14 +2372,14 @@ impl FeltDb {
 
     /// Add a peer for synchronization
     pub fn add_sync_peer(&self, peer_id: String) -> Result<()> {
-        let mut inner = self.inner.lock().expect("lock poisoned");
+        let mut inner = self.state();
         inner.sync_state.add_peer(peer_id);
         Ok(())
     }
 
     /// Remove a peer from synchronization
     pub fn remove_sync_peer(&self, peer_id: &str) -> Result<()> {
-        let mut inner = self.inner.lock().expect("lock poisoned");
+        let mut inner = self.state();
         inner.sync_state.remove_peer(peer_id);
         Ok(())
     }
@@ -1950,7 +2390,7 @@ impl FeltDb {
         _peer_id: &str,
         since_sequence: u64,
     ) -> Result<Vec<Operation>> {
-        let inner = self.inner.lock().expect("lock poisoned");
+        let inner = self.state();
         let pending: Vec<Operation> = inner
             .change_log
             .pending_operations()
@@ -1965,18 +2405,18 @@ impl FeltDb {
         &self,
         versions: &std::collections::HashMap<String, u64>,
     ) -> Result<Vec<Operation>> {
-        let inner = self.inner.lock().expect("lock poisoned");
+        let inner = self.state();
         Ok(inner.change_log.operations_since(versions))
     }
 
     /// Return the highest durable operation sequence observed from each origin.
     pub fn operation_versions(&self) -> Result<std::collections::HashMap<String, u64>> {
-        let inner = self.inner.lock().expect("lock poisoned");
+        let inner = self.state();
         Ok(inner.change_log.versions())
     }
 
     pub fn export_snapshot(&self) -> Result<DatabaseSnapshot> {
-        let inner = self.inner.lock().expect("lock poisoned");
+        let inner = self.state();
         let mut rows: Vec<StoredRow> = inner
             .rows
             .values()
@@ -1998,7 +2438,7 @@ impl FeltDb {
     /// State-contract execution uses this for record-version preconditions;
     /// portable snapshots intentionally continue to strip those envelopes.
     pub fn state_rows(&self) -> Result<Vec<StoredRow>> {
-        let inner = self.inner.lock().expect("lock poisoned");
+        let inner = self.state();
         Ok(inner
             .rows
             .values()
@@ -2012,7 +2452,7 @@ impl FeltDb {
     /// Selecting the capability buckets before cloning prevents one application's
     /// read snapshot from materializing every other application's durable rows.
     pub fn state_rows_for_namespace(&self, state_namespace: &str) -> Result<Vec<StoredRow>> {
-        let inner = self.inner.lock().expect("lock poisoned");
+        let inner = self.state();
         let prefix = format!("{state_namespace}:");
         Ok(inner
             .rows
@@ -2023,7 +2463,7 @@ impl FeltDb {
     }
 
     pub fn can_install_snapshot(&self) -> Result<bool> {
-        let inner = self.inner.lock().expect("lock poisoned");
+        let inner = self.state();
         Ok(!inner.bootstrapped && inner.rows.is_empty() && inner.change_log.pending.is_empty())
     }
 
@@ -2031,7 +2471,7 @@ impl FeltDb {
     /// local history must converge through operations rather than overwrite it.
     pub fn install_snapshot(&self, snapshot: DatabaseSnapshot) -> Result<()> {
         snapshot.verify()?;
-        let mut inner = self.inner.lock().expect("lock poisoned");
+        let mut inner = self.state();
         if !inner.rows.is_empty() || !inner.change_log.pending.is_empty() {
             return Err(FlowError::CapabilityError(
                 "snapshot bootstrap requires a pristine node".to_string(),
@@ -2069,7 +2509,7 @@ impl FeltDb {
         file.sync_all()?;
         fs::rename(temporary, &inner.path)?;
 
-        inner.rows.clear();
+        inner.clear_rows();
         inner.key_counters.clear();
         for row in snapshot.rows {
             if let Some(id) = row
@@ -2083,11 +2523,7 @@ impl FeltDb {
                     .or_default();
                 *counter = (*counter).max(id + 1);
             }
-            inner
-                .rows
-                .entry(row.capability.clone())
-                .or_default()
-                .insert(row.key.clone(), row);
+            inner.put_row(row);
         }
         inner.change_log.observed_versions = snapshot.versions;
         inner.bootstrapped = true;
@@ -2096,7 +2532,7 @@ impl FeltDb {
 
     /// Acknowledge receipt of operations from a peer
     pub fn acknowledge_peer_operations(&self, peer_id: String, sequence: u64) -> Result<()> {
-        let mut inner = self.inner.lock().expect("lock poisoned");
+        let mut inner = self.state();
         inner.change_log.acknowledge_peer(peer_id, sequence);
         persist_sync_metadata(&inner)?;
         Ok(())
@@ -2108,25 +2544,31 @@ impl FeltDb {
         peer_id: String,
         versions: HashMap<String, u64>,
     ) -> Result<()> {
-        let mut inner = self.inner.lock().expect("lock poisoned");
+        let mut inner = self.state();
         inner.change_log.acknowledge_versions(peer_id, versions);
         persist_sync_metadata(&inner)
     }
 
     pub fn acknowledged_peer_versions(&self, peer_id: &str) -> Result<HashMap<String, u64>> {
-        let inner = self.inner.lock().expect("lock poisoned");
+        let inner = self.state();
         Ok(inner.change_log.acknowledged_versions(peer_id))
     }
 
+    /// Earliest operation still available for incremental replay, by origin.
+    pub fn retained_operation_floors(&self) -> Result<HashMap<String, u64>> {
+        let inner = self.state();
+        Ok(inner.change_log.retained_from())
+    }
+
     pub fn acknowledged_operation_count(&self, active_peers: &[String]) -> Result<usize> {
-        let inner = self.inner.lock().expect("lock poisoned");
+        let inner = self.state();
         Ok(inner.change_log.acknowledged_operation_count(active_peers))
     }
 
     /// Atomically replace acknowledged history with a state snapshot and any
     /// operations still needed by at least one configured peer.
     pub fn compact_operation_log(&self, active_peers: &[String]) -> Result<usize> {
-        let mut inner = self.inner.lock().expect("lock poisoned");
+        let mut inner = self.state();
         let removed = inner.change_log.prune_acknowledged(active_peers);
         if removed == 0 {
             return Ok(0);
@@ -2166,7 +2608,7 @@ impl FeltDb {
 
     /// Register a peer in the distributed fabric
     pub fn register_peer(&self, advertisement: PeerAdvertisement) -> Result<()> {
-        let inner = self.inner.lock().expect("lock poisoned");
+        let inner = self.state();
         inner
             .peer_registry
             .register(advertisement)
@@ -2175,7 +2617,7 @@ impl FeltDb {
 
     /// Get a peer's advertisement
     pub fn get_peer(&self, peer_id: &PeerId) -> Result<Option<PeerAdvertisement>> {
-        let inner = self.inner.lock().expect("lock poisoned");
+        let inner = self.state();
         inner
             .peer_registry
             .get(peer_id)
@@ -2184,7 +2626,7 @@ impl FeltDb {
 
     /// Find all peers providing a namespace
     pub fn peers_for_namespace(&self, namespace: &str) -> Result<Vec<PeerAdvertisement>> {
-        let inner = self.inner.lock().expect("lock poisoned");
+        let inner = self.state();
         inner
             .peer_registry
             .peers_for_namespace(namespace)
@@ -2193,7 +2635,7 @@ impl FeltDb {
 
     /// Find all peers providing a capability
     pub fn peers_for_capability(&self, capability: &str) -> Result<Vec<PeerAdvertisement>> {
-        let inner = self.inner.lock().expect("lock poisoned");
+        let inner = self.state();
         inner
             .peer_registry
             .peers_for_capability(capability)
@@ -2202,7 +2644,7 @@ impl FeltDb {
 
     /// Get all registered peers
     pub fn all_peers(&self) -> Result<Vec<PeerAdvertisement>> {
-        let inner = self.inner.lock().expect("lock poisoned");
+        let inner = self.state();
         inner
             .peer_registry
             .all_peers()
@@ -2218,14 +2660,14 @@ impl FeltDb {
 
     /// Get current sync state
     pub fn sync_state(&self) -> Result<SyncState> {
-        let inner = self.inner.lock().expect("lock poisoned");
+        let inner = self.state();
         Ok(inner.sync_state.clone())
     }
 
     /// Apply an operation from a remote peer
     /// This merges the vector clock, resolves conflicts, and applies the mutation
     pub fn apply_remote_operation(&self, op: Operation) -> Result<()> {
-        let mut inner = self.inner.lock().expect("lock poisoned");
+        let mut inner = self.state();
 
         if op.content_hash != op.compute_content_hash() {
             return Err(FlowError::CapabilityError(
@@ -2324,18 +2766,12 @@ impl FeltDb {
             OperationType::Insert | OperationType::Update => {
                 append_event(&inner.path, &row)?;
                 inner.authority_revision += 1;
-                inner
-                    .rows
-                    .entry(op_to_apply.capability.clone())
-                    .or_default()
-                    .insert(op_to_apply.key.clone(), row);
+                inner.put_row(row);
             }
             OperationType::Delete => {
                 append_event(&inner.path, &row)?;
                 inner.authority_revision += 1;
-                if let Some(bucket) = inner.rows.get_mut(&op_to_apply.capability) {
-                    bucket.remove(&op_to_apply.key);
-                }
+                inner.remove_row(&op_to_apply.capability, &op_to_apply.key);
             }
         }
         if let Some(id) = op_to_apply
@@ -2366,7 +2802,7 @@ impl FeltDb {
 
     /// Get the current vector clock state
     pub fn get_vector_clock(&self) -> Result<Option<std::collections::HashMap<String, u64>>> {
-        let inner = self.inner.lock().expect("lock poisoned");
+        let inner = self.state();
         Ok(inner.sync_state.vector_clock.clone())
     }
 }
@@ -2380,7 +2816,7 @@ pub struct Capability {
 impl Capability {
     pub fn insert<T: Serialize>(&self, value: T) -> Result<String> {
         let key = {
-            let mut inner = self.db.inner.lock().expect("lock poisoned");
+            let mut inner = self.db.state();
             let next = inner.key_counters.entry(self.name.clone()).or_default();
             let key = format!("{}:{}", self.name, *next);
             *next += 1;
@@ -2433,7 +2869,7 @@ impl Capability {
         F: Fn(&T) -> bool,
     {
         let rust_type = type_name::<T>().to_string();
-        let mut inner = self.db.inner.lock().expect("lock poisoned");
+        let mut inner = self.db.state();
         *inner
             .query_count_by_type
             .entry(rust_type.clone())
@@ -2487,7 +2923,7 @@ impl Capability {
         let capability_name = self.name.clone();
 
         let initial_results = {
-            let mut inner = self.db.inner.lock().expect("lock poisoned");
+            let mut inner = self.db.state();
             *inner
                 .query_count_by_type
                 .entry(rust_type.clone())
@@ -2568,7 +3004,7 @@ where
                     }
 
                     let results = {
-                        let inner = self.db.inner.lock().expect("lock poisoned");
+                        let inner = self.db.state();
                         let mut out = Vec::new();
                         for bucket in inner.rows.values() {
                             for row in bucket.values() {
@@ -2639,7 +3075,7 @@ where
                     }
 
                     let results = {
-                        let inner = self.db.inner.lock().expect("lock poisoned");
+                        let inner = self.db.state();
                         let mut out = Vec::new();
                         if let Some(bucket) = inner.rows.get(&self.capability_name) {
                             for row in bucket.values() {
@@ -2772,15 +3208,9 @@ fn replay_log(inner: &mut Inner) -> Result<()> {
                         inner.change_log.add_operation(operation);
                     }
                     if row.deleted {
-                        if let Some(bucket) = inner.rows.get_mut(&row.capability) {
-                            bucket.remove(&row.key);
-                        }
+                        inner.remove_row(&row.capability, &row.key);
                     } else {
-                        inner
-                            .rows
-                            .entry(row.capability.clone())
-                            .or_default()
-                            .insert(row.key.clone(), row);
+                        inner.put_row(row);
                     }
                 }
             }
@@ -2817,15 +3247,9 @@ fn replay_log(inner: &mut Inner) -> Result<()> {
             *counter = (*counter).max(id + 1);
         }
         if row.deleted {
-            if let Some(bucket) = inner.rows.get_mut(&row.capability) {
-                bucket.remove(&row.key);
-            }
+            inner.remove_row(&row.capability, &row.key);
         } else {
-            inner
-                .rows
-                .entry(row.capability.clone())
-                .or_default()
-                .insert(row.key.clone(), row);
+            inner.put_row(row);
         }
     }
 
@@ -2904,6 +3328,10 @@ fn persist_sync_metadata(inner: &Inner) -> Result<()> {
 }
 
 fn append_event(path: &Path, event: &StoredRow) -> Result<()> {
+    // Single-record durability: the line is written and flushed to the OS, but
+    // not fsynced. `append_transaction` below does fsync. The asymmetry is
+    // pre-existing and PR36 measures it rather than changing it.
+    let _span = workload_diagnostics::span(workload_diagnostics::Phase::Persistence);
     let mut file = OpenOptions::new().create(true).append(true).open(path)?;
     let mut line = serde_json::to_string(event)?;
     line.push('\n');
@@ -2913,6 +3341,10 @@ fn append_event(path: &Path, event: &StoredRow) -> Result<()> {
 }
 
 fn append_transaction(path: &Path, transaction: &TransactionLogRecord) -> Result<()> {
+    // A transaction commit fsyncs. This span therefore includes the fsync, which
+    // is the point: it is the durability cost of a commit, measured rather than
+    // assumed.
+    let _span = workload_diagnostics::span(workload_diagnostics::Phase::Persistence);
     let mut file = OpenOptions::new().create(true).append(true).open(path)?;
     write_json_line(&mut file, transaction)?;
     file.sync_data()?;