@feltdb/core 0.8.3 → 0.8.5

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;
@@ -107,11 +109,14 @@ pub mod replication_manager;
 pub mod replication_protocol;
 mod routing;
 pub mod sharding;
+pub mod state_conflict_contract;
 pub mod state_contract;
+pub mod state_diff_contract;
 pub mod state_facade;
 pub mod state_hash;
 pub mod state_model;
 pub mod state_transition_store;
+pub mod state_trigger;
 mod storage;
 pub mod submission;
 mod sync;
@@ -124,6 +129,7 @@ mod transaction_invariants;
 pub mod transaction_preconditions;
 pub mod transactions;
 mod trigger;
+pub mod trigger_contract;
 pub mod worker_mesh;
 mod workflow;
 #[cfg(test)]
@@ -131,6 +137,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 +189,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};
@@ -218,14 +226,27 @@ pub use sharding::{
     HotspotAlert, RebalanceOperation, ShardDistributionSummary, ShardId, ShardKey, ShardManager,
     ShardMetrics, ShardRange, ShardingStrategy,
 };
+pub use state_conflict_contract::{
+    classify_states, StateConflictInput, StateConflictOutput, STATE_CONFLICT_CONTRACT_ID,
+    STATE_CONFLICT_CONTRACT_VERSION,
+};
+pub use state_diff_contract::{
+    diff_states, StateDiffInput, StateDiffOutput, STATE_DIFF_CONTRACT_ID,
+    STATE_DIFF_CONTRACT_VERSION,
+};
 pub use state_facade::FeltDBStateSystem;
 pub use state_hash::{CanonicalState, StateHash};
 pub use state_model::{
-    ChangeKind, ConflictClass, ConflictClassification, PathComponent, PathConflict,
+    apply_reconciliation_plan, path_relation, paths_overlap, reconcile, resolve_path, ChangeKind,
+    ConflictClass, ConflictClassification, PathComponent, PathConflict, PathRelation,
     ReconciliationPlan, Relationship, SemanticChange, SemanticDiff, StateId,
     StateReconciliationResult, StateRevision, StateStore, StateTopology, STATE_MODEL_VERSION,
 };
 pub use state_transition_store::{MemoryStateTransitionStore, StateTransitionRecord};
+pub use state_trigger::{
+    StateTrigger, StateTriggerChangeKind, StateTriggerError, StateTriggerPredicate,
+    StateTriggerStore, TriggeredWorkload,
+};
 pub use storage::{CheckpointData, FileStorage, MemoryStorage, Storage};
 pub use submission::{SubmissionManager, SubmissionMetrics};
 pub use sync::{ChangeLog, Conflict, ConflictDetector, PeerState, SyncMessage, SyncState};
@@ -235,6 +256,12 @@ pub use transactions::{
     StateTransition, TransactionExecutor, TransitionResult,
 };
 pub use trigger::{Trigger, TriggerFilter, TriggerRegistry};
+pub use trigger_contract::{
+    canonical_input_bytes, canonical_output_bytes, evaluate_canonical, evaluate_trigger,
+    ContractChange, ContractChangeKind, ContractErrorBody, ContractErrorCode, ContractPredicate,
+    ContractRuntime, ContractTrigger, MatchOutcome, MatchReason, TriggerMatchInput,
+    TriggerMatchOutput, TRIGGER_MATCH_CONTRACT_ID, TRIGGER_MATCH_CONTRACT_VERSION,
+};
 pub use workflow::{
     BlockedReason, WorkflowGraph, WorkflowInstance, WorkflowNode, WorkflowOperation, WorkflowRef,
     WorkflowState, WorkflowStepRef, WorkflowStepState,
@@ -251,7 +278,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};
@@ -281,6 +308,12 @@ pub enum FlowError {
         expected: u64,
         actual: u64,
     },
+    /// The durable database is in a format this build does not understand.
+    ///
+    /// Returned by [`FeltDb::open`] **before any record is interpreted**, and
+    /// before anything is written. A database that returns this error is
+    /// untouched.
+    IncompatibleFormat(Box<FormatIncompatibility>),
 }
 
 impl Display for FlowError {
@@ -295,6 +328,9 @@ impl Display for FlowError {
                 f,
                 "REVISION_CONFLICT: expected authority revision {expected}, current revision is {actual}"
             ),
+            FlowError::IncompatibleFormat(incompatibility) => {
+                write!(f, "INCOMPATIBLE_DURABLE_FORMAT: {incompatibility}")
+            }
         }
     }
 }
@@ -352,6 +388,140 @@ 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,
+    /// Each resource's newest revision, as `(id, sequence)`.
+    ///
+    /// Derived from the `state` rows exactly like `equality_index` is derived
+    /// from `rows`: never durable, rebuilt after recovery. It exists so that
+    /// minting a revision does not have to scan a resource's history to find
+    /// the parent it descends from.
+    revision_heads: HashMap<String, (state_model::StateId, u64)>,
+}
+
+/// 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)]
@@ -601,11 +771,107 @@ pub struct StoredRow {
     pub operation: Option<Operation>,
 }
 
+/// The durable format this build writes and understands.
+///
+/// Independent of the package version on purpose: an application release that
+/// changes nothing about persistence must not appear to change the database.
+///
+/// - **1** — everything before revisions became resource-scoped. Never written
+///   by any build; it names the era that predates format versioning.
+/// - **2** — resource-scoped revisions: a `StateRevision` carries `resource`,
+///   `content_id` and `sequence`.
+pub const DURABLE_FORMAT_VERSION: u32 = 2;
+
+/// The log record that carries the format version.
+const FORMAT_RECORD_TYPE: &str = "feltdb.format.v1";
+
+#[derive(Debug, Serialize, Deserialize)]
+struct FormatRecord {
+    record_type: String,
+    format_version: u32,
+}
+
+/// What format a durable database is in.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum DurableFormat {
+    /// A format record states the version.
+    Versioned(u32),
+    /// No format record: the database predates format versioning.
+    ///
+    /// This is a version, not an absence of one. It is the only case where the
+    /// records themselves are examined to decide compatibility, and that
+    /// examination is a deliberate one-time probe rather than a deserialization
+    /// attempt whose failure is discarded.
+    Unversioned,
+}
+
+impl Display for DurableFormat {
+    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
+        match self {
+            DurableFormat::Versioned(version) => write!(f, "version {version}"),
+            DurableFormat::Unversioned => write!(f, "unversioned (predates format versioning)"),
+        }
+    }
+}
+
+/// Why a durable database cannot be opened, and what to do about it.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct FormatIncompatibility {
+    /// What the database is.
+    pub found: DurableFormat,
+    /// What this build requires.
+    pub required: u32,
+    /// What is wrong, in terms of the data rather than the code.
+    pub reason: String,
+    /// What the operator can do.
+    pub action: String,
+}
+
+impl Display for FormatIncompatibility {
+    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
+        write!(
+            f,
+            "durable format {} is incompatible with this FeltDB, which requires \
+             format version {}; {}. No data was read or modified. {}",
+            self.found, self.required, self.reason, self.action
+        )
+    }
+}
+
+/// The result of examining a durable database without opening it.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum FormatCompatibility {
+    /// Safe to open.
+    Compatible(DurableFormat),
+    /// Must not be opened.
+    Incompatible(FormatIncompatibility),
+}
+
+impl FormatCompatibility {
+    /// Whether opening this database is safe.
+    pub fn is_compatible(&self) -> bool {
+        matches!(self, FormatCompatibility::Compatible(_))
+    }
+}
+
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct DatabaseSnapshot {
     pub rows: Vec<StoredRow>,
     pub versions: HashMap<String, u64>,
     pub content_hash: String,
+    /// The durable format the rows are in.
+    ///
+    /// A snapshot carries whole `StoredRow`s, revisions included, so it is a
+    /// durable interchange artifact and not merely a protocol value: installing
+    /// one from a different format would reintroduce exactly the silent
+    /// misinterpretation the on-disk version exists to prevent.
+    ///
+    /// Defaults to 0 so a snapshot serialized before versioning still
+    /// deserializes; 0 is treated as unversioned and refused rather than
+    /// assumed current. `content_hash` deliberately does not cover this field,
+    /// so hashes computed before it existed remain valid.
+    #[serde(default)]
+    pub format_version: u32,
 }
 
 impl DatabaseSnapshot {
@@ -633,6 +899,10 @@ struct LogHeader {
     record_type: String,
     local_sequence: u64,
     observed_versions: HashMap<String, u64>,
+    /// Present since format versioning. Absent in headers written before it,
+    /// which deserialize as 0 and are classified as unversioned.
+    #[serde(default)]
+    format_version: u32,
 }
 
 #[derive(Debug, Default, Serialize, Deserialize)]
@@ -646,14 +916,222 @@ pub fn open<P: AsRef<Path>>(path: P) -> Result<FeltDb> {
     FeltDb::open(path)
 }
 
+/// Capabilities whose rows are not themselves versioned.
+///
+/// `state` holds the revisions, and `_retention` holds the watermark that says
+/// how much of each resource's history survives. Minting a revision of either
+/// would mint a revision of the mint.
+const UNVERSIONED_CAPABILITIES: &[&str] = &["state", "_retention"];
+
+/// Whether a write to this capability creates a revision.
+fn is_versioned(capability: &str) -> bool {
+    !UNVERSIONED_CAPABILITIES.contains(&capability)
+}
+
+/// Rebuild the derived head index from the durable revisions.
+///
+/// Called after recovery, for the same reason `equality_index` is: the index is
+/// a convenience over `rows` and must never be the authority for what `rows`
+/// contains.
+fn rebuild_revision_heads(inner: &mut Inner) {
+    let mut heads: HashMap<String, (state_model::StateId, u64)> = HashMap::new();
+    if let Some(bucket) = inner.rows.get("state") {
+        for row in bucket.values() {
+            if row.deleted || !row.key.starts_with("state:revision:") {
+                continue;
+            }
+            let Ok(revision) =
+                serde_json::from_value::<state_model::StateRevision>(row.value.clone())
+            else {
+                continue;
+            };
+            let entry = heads
+                .entry(revision.resource.clone())
+                .or_insert_with(|| (revision.id.clone(), revision.sequence));
+            if revision.sequence >= entry.1 {
+                *entry = (revision.id.clone(), revision.sequence);
+            }
+        }
+    }
+    inner.revision_heads = heads;
+}
+
+/// Write one derived row inside an already-held state lock.
+///
+/// Deliberately **not** a mutation: no sequence number, no vector clock tick,
+/// no entry in the change log. A revision is a *derived* record of a mutation
+/// that already has all three, and giving it its own would make every write
+/// advance replication twice and double the operation stream.
+///
+/// It is still durable — the row is appended to the log and enters `rows`
+/// inside the same lock as the state it records, so a reader never observes a
+/// mutation whose revision is missing, and a reopened database has both.
+///
+/// The consequence is that revisions are **local and derived**, not replicated.
+/// That is sound in principle, because a revision's identity is a function of
+/// the resource, the content, the parent and the sequence — all of which a peer
+/// that applies the same operation stream has. Whether the sync-apply path
+/// actually mints is a separate question this change does not answer.
+fn append_derived_row_locked(
+    inner: &mut Inner,
+    capability: &str,
+    key: &str,
+    value: Value,
+) -> Result<()> {
+    let row = StoredRow {
+        capability: capability.to_string(),
+        key: key.to_string(),
+        rust_type: "feltdb::state_model::StateRevision".to_string(),
+        value,
+        unix_ms: now_ms(),
+        content_hash: None,
+        flow_ref: None,
+        deleted: false,
+        operation: None,
+    };
+    append_event(&inner.path, &row)?;
+    inner.put_row(row);
+    Ok(())
+}
+
+/// Mint a revision for an authoritative write, under the caller's lock.
+///
+/// This is where the resource-scoped model meets the write path. The resource
+/// is the record's key, the parent is that resource's current head, and the
+/// sequence is allocated from the parent — so a resource that returns to a value
+/// it previously held records a *new* revision rather than resurrecting the old
+/// one.
+///
+/// Retention is applied here too, by the same decision function the explicit
+/// store API uses. Bounding history at the moment history is created is what
+/// keeps automatic minting from being an unbounded-history architecture.
+fn mint_revision_locked(inner: &mut Inner, resource: &str, content: String) -> Result<()> {
+    let parent = inner.revision_heads.get(resource).cloned();
+    let (parent_id, sequence) = match &parent {
+        Some((id, sequence)) => (Some(id.clone()), sequence + 1),
+        None => (None, 0),
+    };
+    let authority = inner.instance_id.clone();
+    let revision = state_model::StateRevision::at(
+        resource.to_string(),
+        content,
+        parent_id,
+        sequence,
+        authority,
+    );
+    let id = revision.id.clone();
+    let key = format!("state:revision:{}", id.as_hex());
+    let value = serde_json::to_value(&revision)?;
+    append_derived_row_locked(inner, "state", &key, value)?;
+    inner
+        .revision_heads
+        .insert(resource.to_string(), (id, sequence));
+    apply_retention_locked(inner, resource)
+}
+
+/// Expire whatever the resource's configured policy no longer retains.
+///
+/// The common path is one map lookup: with no policy configured there is
+/// nothing to scan. A resource's history is only walked once a policy exists to
+/// bound it.
+fn apply_retention_locked(inner: &mut Inner, resource: &str) -> Result<()> {
+    let retention_key = format!("_retention:{resource}");
+    let Some(state_row) = inner
+        .rows
+        .get("_retention")
+        .and_then(|bucket| bucket.get(&retention_key))
+    else {
+        return Ok(());
+    };
+    let Ok(mut state) = serde_json::from_value::<RetentionRecord>(state_row.value.clone()) else {
+        return Ok(());
+    };
+    if state.policy.keep_last.is_none() {
+        return Ok(());
+    }
+
+    let mut history: Vec<(state_model::StateId, u64)> = Vec::new();
+    if let Some(bucket) = inner.rows.get("state") {
+        for row in bucket.values() {
+            if row.deleted || !row.key.starts_with("state:revision:") {
+                continue;
+            }
+            if let Ok(revision) =
+                serde_json::from_value::<state_model::StateRevision>(row.value.clone())
+            {
+                if revision.resource == resource {
+                    history.push((revision.id, revision.sequence));
+                }
+            }
+        }
+    }
+    history.sort_by_key(|(_, sequence)| *sequence);
+
+    let (expire, horizon) = state_model::revisions_to_expire(&history, state.policy.keep_last);
+    if expire.is_empty() {
+        return Ok(());
+    }
+    for id in &expire {
+        let key = format!("state:revision:{}", id.as_hex());
+        if let Some(bucket) = inner.rows.get_mut("state") {
+            bucket.remove(&key);
+        }
+        let tombstone = StoredRow {
+            capability: "state".to_string(),
+            key,
+            rust_type: "feltdb::state_model::StateRevision".to_string(),
+            value: Value::Null,
+            unix_ms: now_ms(),
+            content_hash: None,
+            flow_ref: None,
+            deleted: true,
+            operation: None,
+        };
+        append_event(&inner.path, &tombstone)?;
+    }
+    if let Some(horizon) = horizon {
+        state.horizon = horizon;
+    }
+    let value = serde_json::to_value(&state)?;
+    append_derived_row_locked(inner, "_retention", &retention_key, value)
+}
+
+/// The durable shape of a resource's retention state.
+///
+/// Mirrors `state_model`'s private record so the write boundary can read and
+/// advance the horizon without the store type.
+#[derive(Clone, Debug, Default, Serialize, Deserialize)]
+struct RetentionRecord {
+    policy: state_model::RetentionPolicy,
+    horizon: u64,
+}
+
 impl FeltDb {
     pub fn open<P: AsRef<Path>>(path: P) -> Result<Self> {
         let path = path.as_ref().to_path_buf();
+
+        // Fail closed. The format is decided before any record is interpreted
+        // and before anything is written, so a database this build does not
+        // understand is refused with its bytes untouched rather than opened
+        // with whatever happened to deserialize.
+        if let FormatCompatibility::Incompatible(incompatibility) = inspect_durable_format(&path)? {
+            return Err(FlowError::IncompatibleFormat(Box::new(incompatibility)));
+        }
+
         if let Some(parent) = path.parent() {
             fs::create_dir_all(parent)?;
         }
         if !path.exists() {
-            OpenOptions::new().create(true).append(true).open(&path)?;
+            let mut file = OpenOptions::new().create(true).append(true).open(&path)?;
+            // A new database states its format in its first record, so it never
+            // has to be inferred again.
+            write_json_line(
+                &mut file,
+                &FormatRecord {
+                    record_type: FORMAT_RECORD_TYPE.to_string(),
+                    format_version: DURABLE_FORMAT_VERSION,
+                },
+            )?;
         }
 
         // Generate instance ID from path hash
@@ -673,6 +1151,7 @@ impl FeltDb {
         inner.sync_state = SyncState::new(instance_id);
         replay_log(&mut inner)?;
         load_sync_metadata(&mut inner)?;
+        rebuild_revision_heads(&mut inner);
 
         let (event_tx, _) = broadcast::channel(1024);
 
@@ -722,7 +1201,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 +1301,10 @@ 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());
+            if is_versioned(&capability) {
+                mint_revision_locked(&mut inner, key, value.to_string())?;
+            }
             let event = ChangeEvent {
                 capability,
                 key: key.to_string(),
@@ -975,7 +1453,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 +1469,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 +1502,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 +1522,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 +1540,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 +1551,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 +1564,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 +1576,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 +1673,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 +1863,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 +1966,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 +1977,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 +1985,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 +2000,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 +2012,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 {
@@ -1603,6 +2091,9 @@ impl FeltDb {
     ) -> Result<()> {
         let rust_type = type_name::<T>().to_string();
         let value_json = serde_json::to_value(value)?;
+        // Canonical because `serde_json` is built without `preserve_order`, so
+        // `Map` is a `BTreeMap` and `to_string` emits keys in sorted order.
+        let canonical = value_json.to_string();
         let mut row = StoredRow {
             capability: capability.clone(),
             key: key.clone(),
@@ -1616,7 +2107,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 +2136,10 @@ 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);
+            if is_versioned(&capability) {
+                mint_revision_locked(&mut inner, &key, canonical)?;
+            }
             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();
@@ -1676,6 +2166,9 @@ impl FeltDb {
     ) -> Result<()> {
         let rust_type = type_name::<T>().to_string();
         let value_json = serde_json::to_value(value)?;
+        // Canonical because `serde_json` is built without `preserve_order`, so
+        // `Map` is a `BTreeMap` and `to_string` emits keys in sorted order.
+        let canonical = value_json.to_string();
         let mut row = StoredRow {
             capability: capability.clone(),
             key: key.clone(),
@@ -1689,7 +2182,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 +2211,10 @@ 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);
+            if is_versioned(&capability) {
+                mint_revision_locked(&mut inner, &key, canonical)?;
+            }
         }
 
         let event = ChangeEvent {
@@ -1738,7 +2230,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 +2280,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 +2321,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 +2360,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 +2370,330 @@ 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 +2703,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 +2723,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 +2739,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 +2757,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 +2772,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()
@@ -1992,13 +2799,14 @@ impl FeltDb {
             rows,
             versions,
             content_hash,
+            format_version: DURABLE_FORMAT_VERSION,
         })
     }
     /// Current materialized rows including their causal operation envelopes.
     /// 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 +2820,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,15 +2831,33 @@ 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())
     }
 
     /// Install a verified bootstrap snapshot into a pristine node. A node with
     /// local history must converge through operations rather than overwrite it.
     pub fn install_snapshot(&self, snapshot: DatabaseSnapshot) -> Result<()> {
+        // A snapshot carries whole rows, revisions included, so installing one
+        // from another format would reintroduce exactly the silent
+        // misinterpretation the on-disk version prevents.
+        if snapshot.format_version != DURABLE_FORMAT_VERSION {
+            return Err(FlowError::IncompatibleFormat(Box::new(
+                FormatIncompatibility {
+                    found: if snapshot.format_version == 0 {
+                        DurableFormat::Unversioned
+                    } else {
+                        DurableFormat::Versioned(snapshot.format_version)
+                    },
+                    required: DURABLE_FORMAT_VERSION,
+                    reason: "the snapshot was produced in a different durable format".to_string(),
+                    action: "Take a fresh snapshot from a FeltDB build matching this one."
+                        .to_string(),
+                },
+            )));
+        }
         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(),
@@ -2058,6 +2884,7 @@ impl FeltDb {
             &mut file,
             &LogHeader {
                 record_type: "feltdb.snapshot.v1".to_string(),
+                format_version: DURABLE_FORMAT_VERSION,
                 local_sequence: inner.sequence,
                 observed_versions: snapshot.versions.clone(),
             },
@@ -2069,7 +2896,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 +2910,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 +2919,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 +2931,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);
@@ -2143,6 +2972,7 @@ impl FeltDb {
             &mut file,
             &LogHeader {
                 record_type: "feltdb.snapshot.v1".to_string(),
+                format_version: DURABLE_FORMAT_VERSION,
                 local_sequence: inner.sequence,
                 observed_versions: inner.change_log.versions(),
             },
@@ -2166,7 +2996,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 +3005,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 +3014,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 +3023,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 +3032,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 +3048,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 +3154,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 +3190,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 +3204,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 +3257,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 +3311,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 +3392,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 +3463,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() {
@@ -2677,6 +3501,115 @@ where
 ///
 /// Damage anywhere earlier is not an interrupted write. Recovery refuses it
 /// rather than silently dropping committed history.
+/// Examine a durable database's format **without opening or modifying it**.
+///
+/// This runs before any record is interpreted, and reads the file only. A
+/// database this reports as incompatible is left exactly as it was found.
+///
+/// The order matters: an explicit format record decides, and the records
+/// themselves are examined *only* when no format record exists — the
+/// unversioned era. Compatibility is never inferred from whether a
+/// deserialization happened to succeed.
+pub fn inspect_durable_format(path: &Path) -> Result<FormatCompatibility> {
+    if !path.exists() {
+        // A database that does not exist yet will be created in the current
+        // format.
+        return Ok(FormatCompatibility::Compatible(DurableFormat::Versioned(
+            DURABLE_FORMAT_VERSION,
+        )));
+    }
+
+    let lines = read_log_lines(path)?;
+    let mut declared: Option<u32> = None;
+    let mut legacy_revision = false;
+
+    for line in &lines {
+        if line.trim().is_empty() {
+            continue;
+        }
+        let Ok(value) = serde_json::from_str::<Value>(line) else {
+            continue;
+        };
+        match value.get("record_type").and_then(Value::as_str) {
+            Some(FORMAT_RECORD_TYPE) => {
+                if let Some(version) = value.get("format_version").and_then(Value::as_u64) {
+                    declared = Some(version as u32);
+                }
+            }
+            Some("feltdb.snapshot.v1" | "flowdb.snapshot.v1") => {
+                match value.get("format_version").and_then(Value::as_u64) {
+                    Some(version) if version > 0 => declared = Some(version as u32),
+                    _ => {}
+                }
+            }
+            _ => {
+                // The unversioned-era probe: a revision record that predates
+                // resource-scoped identity. Deliberate and specific — it looks
+                // for a named absence rather than trying to parse and shrugging
+                // at failure.
+                let is_revision = value
+                    .get("key")
+                    .and_then(Value::as_str)
+                    .is_some_and(|key| key.starts_with("state:revision:"));
+                if is_revision
+                    && value
+                        .get("value")
+                        .and_then(Value::as_object)
+                        .is_some_and(|revision| !revision.contains_key("resource"))
+                {
+                    legacy_revision = true;
+                }
+            }
+        }
+    }
+
+    if let Some(version) = declared {
+        return Ok(match version.cmp(&DURABLE_FORMAT_VERSION) {
+            std::cmp::Ordering::Equal => {
+                FormatCompatibility::Compatible(DurableFormat::Versioned(version))
+            }
+            std::cmp::Ordering::Greater => {
+                FormatCompatibility::Incompatible(FormatIncompatibility {
+                    found: DurableFormat::Versioned(version),
+                    required: DURABLE_FORMAT_VERSION,
+                    reason: "the database was written by a newer FeltDB".to_string(),
+                    action: "Run a FeltDB build that understands this format, or restore \
+                             a backup taken in an older format."
+                        .to_string(),
+                })
+            }
+            std::cmp::Ordering::Less => FormatCompatibility::Incompatible(FormatIncompatibility {
+                found: DurableFormat::Versioned(version),
+                required: DURABLE_FORMAT_VERSION,
+                reason: "the database was written in an older durable format".to_string(),
+                action: "Migrate the database with a FeltDB build that supports both \
+                             formats, or restore a backup."
+                    .to_string(),
+            }),
+        });
+    }
+
+    if legacy_revision {
+        return Ok(FormatCompatibility::Incompatible(FormatIncompatibility {
+            found: DurableFormat::Unversioned,
+            required: DURABLE_FORMAT_VERSION,
+            reason: "it holds revision records written before revisions belonged to a \
+                     resource, and those records cannot be migrated without inventing \
+                     information they never contained: a revision recorded no resource, \
+                     so which history each one belongs to is not recoverable from the data"
+                .to_string(),
+            action: "Export the application state you need from a FeltDB build that \
+                     understands the old format, then load it into a new database. The \
+                     existing file has not been modified."
+                .to_string(),
+        }));
+    }
+
+    // No format record and no legacy revision: nothing in this database depends
+    // on the difference.
+    Ok(FormatCompatibility::Compatible(DurableFormat::Unversioned))
+}
+
 fn read_log_lines(path: &Path) -> Result<Vec<String>> {
     let mut file = BufReader::new(OpenOptions::new().read(true).open(path)?);
     let mut lines: Vec<(String, bool)> = Vec::new();
@@ -2733,6 +3666,10 @@ fn replay_log(inner: &mut Inner) -> Result<()> {
             snapshot_log = true;
             continue;
         }
+        if value.get("record_type").and_then(Value::as_str) == Some(FORMAT_RECORD_TYPE) {
+            // Already honoured by `inspect_durable_format` before the open.
+            continue;
+        }
         if value.get("record_type").and_then(Value::as_str) == Some("feltdb.transaction.v1") {
             let transaction: TransactionLogRecord = serde_json::from_value(value)?;
             // Older records did not carry a commit revision. Their durable
@@ -2772,15 +3709,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 +3748,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 +3829,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 +3842,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()?;