@feltdb/core 0.4.12 → 0.4.14

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

@@ -0,0 +1,2838 @@
+#[cfg(test)]
+mod acceptance_tests;
+#[cfg(test)]
+mod admission_contract_tests;
+mod acquisition;
+pub mod admission;
+pub mod application;
+pub mod application_runtime;
+pub mod authorization;
+pub mod capabilities;
+mod capability;
+mod content_distribution;
+pub mod convergence;
+mod cron;
+#[cfg(test)]
+mod distributed_tests;
+mod execution;
+pub mod analytics;
+pub mod distributed_indexing;
+pub mod indexing;
+pub mod sharding;
+pub mod transactions;
+pub mod state_hash;
+pub mod crash_injection;
+pub mod concurrency_fuzzing;
+pub mod replay_fuzzing;
+pub mod permutation_scheduler;
+pub mod multi_node_convergence;
+pub mod distributed_transactions;
+pub mod durable_operation_log;
+pub mod durable_dedup_set;
+pub mod replication_protocol;
+pub mod in_process_transport;
+#[cfg(not(target_arch = "wasm32"))]
+pub mod tcp_transport;
+pub mod operation_algebra;
+pub mod crash_atomic_boundary;
+pub mod causal_dependency_barrier;
+pub mod partition_reconciliation;
+pub mod consistency_contract;
+pub mod persistence_reality;
+pub mod adversarial_transport;
+pub mod replication_manager;
+pub mod metrics;
+pub mod query_performance;
+pub mod durable_sync;
+pub mod production_api;
+pub mod observability;
+pub mod durability_guarantees;
+#[cfg(test)]
+mod phase1b_acceptance;
+#[cfg(test)]
+mod phase1c1_acceptance;
+#[cfg(test)]
+mod phase1c2_acceptance;
+#[cfg(test)]
+mod phase1c_atomicity_proof;
+#[cfg(test)]
+mod phase1c3_acceptance;
+#[cfg(test)]
+mod phase_1c_three_node;
+#[cfg(test)]
+mod phase_1c_real_tcp;
+#[cfg(test)]
+mod phase_2a_failures;
+#[cfg(test)]
+mod phase_2b_network;
+#[cfg(test)]
+mod phase_2c_cascading;
+#[cfg(test)]
+mod phase_3_durability;
+#[cfg(test)]
+mod phase_4_baseline;
+#[cfg(test)]
+mod phase_5_soak;
+#[cfg(test)]
+mod phase5_integration;
+#[cfg(test)]
+mod phase5_scenarios;
+#[cfg(test)]
+mod phase6_persistence;
+#[cfg(test)]
+mod phase6_adversarial_scenarios;
+#[cfg(test)]
+mod phase6_convergence_validator;
+#[cfg(test)]
+mod transaction_invariants;
+#[cfg(test)]
+mod crash_recovery_tests;
+#[cfg(test)]
+mod causal_dependency_barrier_phase_7_1;
+mod cardinality_diagnostics;
+pub mod cardinality_endpoint;
+mod materialization;
+mod operation;
+pub mod operation_log;
+pub mod state_transition_store;
+pub mod submission;
+pub mod transaction_api;
+mod peer_registry;
+mod provenance;
+mod references;
+mod routing;
+pub mod state_contract;
+mod storage;
+mod sync;
+pub mod sync_contract;
+mod trigger;
+pub mod worker_mesh;
+mod workflow;
+#[cfg(test)]
+mod workflow_acceptance_tests;
+mod workflow_integration;
+mod workflow_runtime;
+pub mod workload;
+
+pub use acquisition::{
+    AcquisitionDeduplicator, AcquisitionPolicy, AcquisitionResult, ContentRequest, ContentResponse,
+    ContentTransferError,
+};
+pub use capability::{
+    CapabilityAccessModel, CapabilityCheckpoint, CapabilityContext, CapabilityExecutionContext,
+    CapabilityExecutionResult, CapabilityId, CapabilityLifecycleState, CapabilityMetadata,
+    CapabilityOperationResult, CapabilityQuery, CapabilityQueryResult, CapabilityRef,
+    CapabilityRegistry, CapabilityRequirements, CapabilityResolver, CapabilityRole,
+    DistributedCapabilityAdvertisement, ExecutionRef, FlowCapability, StateRequirement,
+};
+pub use content_distribution::{
+    CapabilityLocationRegistry, ContentAcquisitionManager, ContentAddressableStore,
+    DistributedReferenceResolver, ProjectionDistribution,
+};
+pub use convergence::{
+    CausalHistory, ConflictResolution, ConflictResolutionStrategy, MergeResult, StateVersion,
+    VectorClock,
+};
+pub use analytics::{AutoTuner, IndexAnalytics, IndexMetrics, PerformanceReport, QueryTrace, TuningRecommendation};
+pub use cron::{CronSchedule, CronScheduler};
+pub use distributed_indexing::{
+    ConsistencyLevel, ConsistencyProtocol, DistributedIndexManager, DistributedSyncStatus,
+    IndexOperation, IndexReplicationState, IndexSyncMessage, IndexVectorClock, RemoteIndexMetadata,
+    RemoteIndexState, ReplicationStatus, VersionConflict,
+};
+pub use execution::{Execution, ExecutionQueue, ExecutionStatus, RetryPolicy};
+pub use indexing::{IndexConfig, IndexManager, IndexStats, IndexType};
+pub use submission::{SubmissionManager, SubmissionMetrics};
+pub use admission::{SubmissionOutcome, RejectionReason, ProductionRetryPolicy};
+pub use sharding::{
+    HotspotAlert, RebalanceOperation, ShardDistributionSummary, ShardId, ShardKey, ShardManager,
+    ShardMetrics, ShardRange, ShardingStrategy,
+};
+pub use transactions::{
+    CommitId, CommitValidator, ConsistencyContract, OperationCommand,
+    OperationId, StateTransition, StateDependency, TransactionExecutor,
+    TransitionResult,
+};
+pub use state_hash::{CanonicalState, StateHash};
+pub use permutation_scheduler::{OperationSchedule, PermutationScheduler, ScheduleStrategy};
+pub use multi_node_convergence::{
+    ConvergenceAggregation, ConvergenceResult, MultiNodeConvergenceSimulator, NodeExecutionResult,
+};
+pub use distributed_transactions::{
+    DistributedTransactionExecutor, EnvelopeId, ReplicaState, ReplicationMessage, TransactionEnvelope,
+};
+pub use operation_algebra::{
+    ConflictType, ConvergenceSemantic, OperationAlgebra, OperationAlgebraRegistry,
+};
+pub use crash_atomic_boundary::{
+    CrashAtomicExecutor, CrashBoundaryPoint, CrashRecoveryState, InvariantCheckResult,
+    RecoveryDecision,
+};
+pub use causal_dependency_barrier::{
+    ApplyResult, CausalDependencyBarrier, OperationState, PendingOperation, ReceiveResult,
+    StateCounters,
+};
+pub use partition_reconciliation::{
+    DeterminismCheckResult, PartitionDeterminismChecker, PartitionTrace, PartitionedReplica,
+    ReconciliationResult, ReplicaPartition,
+};
+pub use consistency_contract::{
+    CommutativeVerificationResult, ConsensusEnforcementResult, ConsensusRequirementChecker,
+    ConsistencyContractEnforcer, DeterministicMergeVerificationResult, NoDowngradeVerificationResult,
+    OperationApplication,
+};
+pub use persistence_reality::{
+    CorruptionDetectionResult, DurablePersistenceLayer, FsyncDurabilityResult,
+    PersistenceCrashPoint, PersistenceContractVerifier, RecoveryResult, WriteResult, WALEntry,
+};
+pub use adversarial_transport::{
+    AdversarialTransport, ConnectionId, ConnectivityMatrix, FaultSeed, InMemoryTransport,
+    LinkState, MessageId, NetworkEvent, NetworkSchedule, NodeId, ReplicationTransport,
+};
+pub use materialization::{MaterializationHandler, ReactiveCollectionIntegration};
+pub use operation::{MutationOrder, Operation, OperationType, DEFAULT_MUTATION_ORDER};
+pub use operation_log::{MemoryOperationLog, OperationLogEntry};
+pub use state_transition_store::{MemoryStateTransitionStore, StateTransitionRecord};
+pub use transaction_api::{TransactionManager, TxError, TxResult};
+pub use peer_registry::PeerRegistry;
+pub use provenance::{
+    AcquisitionMetadata, DerivedState, DerivedStateProvenance, DerivedValue, OperationSource,
+};
+pub use references::{
+    ContentIdentity, ContentRange, FlowRef, PeerAdvertisement, PeerId, ReferenceResolver,
+    ResolutionMetadata, ResolutionResult,
+};
+pub use routing::{
+    CapabilityRouter, ExecutionClaim, ExecutionClaimer, ExecutionResultPublisher, PeerStateVersion,
+    RouteDecision,
+};
+pub use storage::{CheckpointData, FileStorage, MemoryStorage, Storage};
+pub use sync::{ChangeLog, Conflict, ConflictDetector, PeerState, SyncMessage, SyncState};
+pub use trigger::{Trigger, TriggerFilter, TriggerRegistry};
+pub use workflow::{
+    BlockedReason, WorkflowGraph, WorkflowInstance, WorkflowNode, WorkflowOperation, WorkflowRef,
+    WorkflowState, WorkflowStepRef, WorkflowStepState,
+};
+pub use workflow_integration::{
+    WorkflowCronTrigger, WorkflowIntegration, WorkflowProvenance, WorkflowTrigger,
+};
+pub use workflow_runtime::{WorkflowOperationEntry, WorkflowRuntime};
+
+use serde::de::DeserializeOwned;
+use serde::{Deserialize, Serialize};
+use serde_json::Value;
+use sha2::{Digest, Sha256};
+use std::any::type_name;
+use std::collections::hash_map::DefaultHasher;
+use std::collections::{HashMap, HashSet};
+use std::fmt::{Display, Formatter};
+use std::fs::{self, OpenOptions};
+use std::hash::{Hash, Hasher};
+use std::io::{BufRead, BufReader, Write};
+use std::path::{Path, PathBuf};
+use std::sync::{Arc, Mutex};
+use std::time::{SystemTime, UNIX_EPOCH};
+use tokio::sync::broadcast;
+
+pub type Result<T> = std::result::Result<T, FlowError>;
+
+#[derive(Debug)]
+pub enum FlowError {
+    Io(std::io::Error),
+    Serde(serde_json::Error),
+    CorruptLogLine(String),
+    CapabilityError(String),
+}
+
+impl Display for FlowError {
+    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
+        match self {
+            FlowError::Io(e) => write!(f, "io error: {e}"),
+            FlowError::Serde(e) => write!(f, "serde error: {e}"),
+            FlowError::CorruptLogLine(line) => write!(f, "corrupt log line: {line}"),
+            FlowError::CapabilityError(msg) => write!(f, "capability error: {msg}"),
+        }
+    }
+}
+
+impl std::error::Error for FlowError {}
+
+impl From<std::io::Error> for FlowError {
+    fn from(value: std::io::Error) -> Self {
+        FlowError::Io(value)
+    }
+}
+
+impl From<serde_json::Error> for FlowError {
+    fn from(value: serde_json::Error) -> Self {
+        FlowError::Serde(value)
+    }
+}
+
+impl From<String> for FlowError {
+    fn from(value: String) -> Self {
+        FlowError::CapabilityError(value)
+    }
+}
+
+#[derive(Clone)]
+pub struct FeltDb {
+    inner: Arc<Mutex<Inner>>,
+    event_tx: broadcast::Sender<ChangeEvent>,
+}
+
+#[derive(Default)]
+#[allow(dead_code)] // Reserved runtime subsystems are initialized before their public APIs land.
+struct Inner {
+    path: PathBuf,
+    rows: HashMap<String, HashMap<String, StoredRow>>,
+    key_counters: HashMap<String, u64>,
+    query_count_by_type: HashMap<String, usize>,
+    adaptive_indexes: HashSet<String>,
+    instance_id: String,
+    sequence: u64,
+    sync_state: SyncState,
+    change_log: ChangeLog,
+    execution_queue: ExecutionQueue,
+    trigger_registry: TriggerRegistry,
+    cron_scheduler: CronScheduler,
+    capability_registry: CapabilityRegistry,
+    peer_registry: PeerRegistry,
+    content_store: ContentAddressableStore,
+    capability_locations: CapabilityLocationRegistry,
+    bootstrapped: bool,
+    applied_transactions: HashSet<String>,
+    collection_cardinality: HashMap<String, u64>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct AtomicMutation {
+    pub capability: String,
+    pub key: String,
+    pub value: Option<Value>,
+}
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct AtomicPrecondition {
+    pub capability: String,
+    pub key: String,
+    pub expected_version: Option<u64>,
+}
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct AtomicCommit {
+    pub transaction_id: String,
+    pub state_before: u64,
+    pub state_after: u64,
+    pub rows: Vec<StoredRow>,
+    pub duplicate: bool,
+}
+#[derive(Debug, Clone, Serialize, Deserialize)]
+struct TransactionLogRecord {
+    record_type: String,
+    transaction_id: String,
+    state_before: u64,
+    state_after: u64,
+    rows: Vec<StoredRow>,
+    #[serde(default)]
+    audit: Option<Value>,
+}
+
+/// An event representing a change to the database (insert or update of a record).
+///
+/// This event is broadcast to all live query subscribers so they can update their results.
+#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
+pub struct ChangeEvent {
+    /// The capability namespace of the changed record.
+    pub capability: String,
+    /// The key of the changed record.
+    pub key: String,
+    /// The Rust type name of the changed record.
+    pub rust_type: String,
+    /// The timestamp of the change in milliseconds since UNIX epoch.
+    pub unix_ms: u128,
+}
+
+#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
+pub struct StoredRow {
+    pub capability: String,
+    pub key: String,
+    pub rust_type: String,
+    pub value: Value,
+    pub unix_ms: u128,
+    /// Content hash for deduplication and content addressing
+    #[serde(default)]
+    pub content_hash: Option<String>,
+    /// Reference identity if this row represents a referenced object
+    #[serde(default)]
+    pub flow_ref: Option<FlowRef>,
+    /// Tombstone marker used to durably replay deletions.
+    #[serde(default)]
+    pub deleted: bool,
+    /// Canonical mutation which produced this row. Older logs remain readable.
+    #[serde(default)]
+    pub operation: Option<Operation>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct DatabaseSnapshot {
+    pub rows: Vec<StoredRow>,
+    pub versions: HashMap<String, u64>,
+    pub content_hash: String,
+}
+
+impl DatabaseSnapshot {
+    fn compute_hash(rows: &[StoredRow], versions: &HashMap<String, u64>) -> Result<String> {
+        let mut rows = rows.to_vec();
+        rows.sort_by(|left, right| left.key.cmp(&right.key));
+        let versions: std::collections::BTreeMap<_, _> = versions.iter().collect();
+        let mut hasher = Sha256::new();
+        hasher.update(serde_json::to_vec(&(rows, versions))?);
+        Ok(format!("{:x}", hasher.finalize()))
+    }
+
+    pub fn verify(&self) -> Result<()> {
+        if self.content_hash != Self::compute_hash(&self.rows, &self.versions)? {
+            return Err(FlowError::CapabilityError(
+                "snapshot content hash mismatch".to_string(),
+            ));
+        }
+        Ok(())
+    }
+}
+
+#[derive(Debug, Serialize, Deserialize)]
+struct LogHeader {
+    record_type: String,
+    local_sequence: u64,
+    observed_versions: HashMap<String, u64>,
+}
+
+#[derive(Debug, Default, Serialize, Deserialize)]
+struct SyncMetadata {
+    local_sequence: u64,
+    observed_versions: HashMap<String, u64>,
+    peer_acknowledgements: HashMap<String, HashMap<String, u64>>,
+}
+
+pub fn open<P: AsRef<Path>>(path: P) -> Result<FeltDb> {
+    FeltDb::open(path)
+}
+
+impl FeltDb {
+    pub fn open<P: AsRef<Path>>(path: P) -> Result<Self> {
+        let path = path.as_ref().to_path_buf();
+        if let Some(parent) = path.parent() {
+            fs::create_dir_all(parent)?;
+        }
+        if !path.exists() {
+            OpenOptions::new().create(true).append(true).open(&path)?;
+        }
+
+        // Generate instance ID from path hash
+        let instance_id = format!("feltdb-{:x}", {
+            let mut hasher = DefaultHasher::new();
+            path.to_string_lossy().hash(&mut hasher);
+            hasher.finish()
+        });
+
+        let mut inner = Inner {
+            path: path.clone(),
+            instance_id: instance_id.clone(),
+            ..Inner::default()
+        };
+
+        // Initialize sync state with instance ID
+        inner.sync_state = SyncState::new(instance_id);
+        replay_log(&mut inner)?;
+        load_sync_metadata(&mut inner)?;
+
+        let (event_tx, _) = broadcast::channel(1024);
+
+        Ok(Self {
+            inner: Arc::new(Mutex::new(inner)),
+            event_tx,
+        })
+    }
+
+    pub fn insert<T: Serialize>(&self, key: &str, value: T) -> Result<()> {
+        let capability = key
+            .split_once(':')
+            .map(|(cap, _)| cap)
+            .unwrap_or("default")
+            .to_string();
+        self.insert_internal(capability, key.to_string(), value)?;
+        Ok(())
+    }
+
+    /// Update an existing record with vector clock tracking
+    pub fn update<T: Serialize>(&self, key: &str, value: T) -> Result<()> {
+        let capability = key
+            .split_once(':')
+            .map(|(cap, _)| cap)
+            .unwrap_or("default")
+            .to_string();
+        self.update_internal(capability, key.to_string(), value)?;
+        Ok(())
+    }
+
+    /// Delete a record with vector clock tracking
+    pub fn delete(&self, key: &str) -> Result<()> {
+        let capability = key
+            .split_once(':')
+            .map(|(cap, _)| cap)
+            .unwrap_or("default")
+            .to_string();
+        self.delete_internal(capability, key.to_string())?;
+        Ok(())
+    }
+
+    pub fn get<T: DeserializeOwned>(&self, key: &str) -> Result<Option<T>> {
+        let capability = key
+            .split_once(':')
+            .map(|(cap, _)| cap)
+            .unwrap_or("default")
+            .to_string();
+        let inner = self.inner.lock().expect("lock poisoned");
+        let value = inner
+            .rows
+            .get(&capability)
+            .and_then(|bucket| bucket.get(key))
+            .map(|row| serde_json::from_value::<T>(row.value.clone()))
+            .transpose()?;
+        Ok(value)
+    }
+
+    pub fn query<T, F>(&self, predicate: F) -> Result<Vec<T>>
+    where
+        T: DeserializeOwned,
+        F: Fn(&T) -> bool,
+    {
+        let rust_type = type_name::<T>().to_string();
+        let mut inner = self.inner.lock().expect("lock poisoned");
+        *inner
+            .query_count_by_type
+            .entry(rust_type.clone())
+            .or_default() += 1;
+        if inner.query_count_by_type[&rust_type] >= 3 {
+            inner.adaptive_indexes.insert(rust_type.clone());
+        }
+
+        let mut out = Vec::new();
+        for bucket in inner.rows.values() {
+            for row in bucket.values() {
+                if row.rust_type != rust_type {
+                    continue;
+                }
+                let parsed = serde_json::from_value::<T>(row.value.clone())?;
+                if predicate(&parsed) {
+                    out.push(parsed);
+                }
+            }
+        }
+        Ok(out)
+    }
+
+    pub fn capability(&self, name: &str) -> Capability {
+        Capability {
+            db: self.clone(),
+            name: name.to_string(),
+        }
+    }
+
+    pub fn is_auto_indexed<T>(&self) -> bool {
+        let rust_type = type_name::<T>().to_string();
+        let inner = self.inner.lock().expect("lock poisoned");
+        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");
+        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");
+        Ok(inner.sequence)
+    }
+
+    /// 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");
+        Ok(inner.collection_cardinality.get(capability).copied().unwrap_or(0))
+    }
+
+    /// 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 mut result: Vec<_> = inner
+            .collection_cardinality
+            .iter()
+            .map(|(k, v)| (k.clone(), *v))
+            .collect();
+        result.sort_by(|a, b| b.1.cmp(&a.1)); // Sort by count descending
+        Ok(result)
+    }
+
+    /// 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");
+        Ok(inner
+            .rows
+            .iter()
+            .filter(|(cap, _)| cap.contains(capability_pattern))
+            .map(|(_, bucket)| bucket.values().filter(|row| !row.deleted).count())
+            .sum())
+    }
+
+    /// 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 mut keys: Vec<_> = inner
+            .rows
+            .keys()
+            .filter(|k| k.contains(capability_pattern))
+            .cloned()
+            .collect();
+        keys.sort();
+        Ok(keys)
+    }
+
+    pub fn has_applied_transaction(&self, transaction_id: &str) -> Result<bool> {
+        Ok(self
+            .inner
+            .lock()
+            .expect("lock poisoned")
+            .applied_transactions
+            .contains(transaction_id))
+    }
+
+    /// Atomically validates and durably applies an ordered mutation batch.
+    /// The complete transaction is represented by one log record and becomes
+    /// visible in memory only after that record has been appended successfully.
+    pub fn apply_atomic_transaction(
+        &self,
+        transaction_id: &str,
+        expected_parent: Option<u64>,
+        preconditions: &[AtomicPrecondition],
+        mutations: &[AtomicMutation],
+        audit: Option<Value>,
+    ) -> Result<AtomicCommit> {
+        let (commit, events) = {
+            let mut inner = self.inner.lock().expect("lock poisoned");
+            if inner.applied_transactions.contains(transaction_id) {
+                return Ok(AtomicCommit {
+                    transaction_id: transaction_id.into(),
+                    state_before: inner.sequence,
+                    state_after: inner.sequence,
+                    rows: vec![],
+                    duplicate: true,
+                });
+            }
+            if let Some(expected) = expected_parent {
+                if expected != inner.sequence {
+                    return Err(FlowError::CapabilityError(format!(
+                        "PRECONDITION_FAILED:transaction_parent:{expected}:{}",
+                        inner.sequence
+                    )));
+                }
+            }
+            for condition in preconditions {
+                let actual = inner
+                    .rows
+                    .get(&condition.capability)
+                    .and_then(|bucket| bucket.get(&condition.key))
+                    .and_then(|row| row.operation.as_ref())
+                    .map(|op| op.sequence);
+                if actual != condition.expected_version {
+                    return Err(FlowError::CapabilityError(format!(
+                        "PRECONDITION_FAILED:{}:{}:{:?}:{actual:?}",
+                        condition.capability, condition.key, condition.expected_version
+                    )));
+                }
+            }
+            let state_before = inner.sequence;
+            let mut next_sequence = state_before;
+            let mut rows = Vec::with_capacity(mutations.len());
+            let mut vector_clock = inner.sync_state.get_or_init_vector_clock().clone();
+            for mutation in mutations {
+                next_sequence += 1;
+                *vector_clock.entry(inner.instance_id.clone()).or_default() += 1;
+                let rust_type = "serde_json::Value".to_string();
+                let operation = match &mutation.value {
+                    Some(value)
+                        if inner
+                            .rows
+                            .get(&mutation.capability)
+                            .is_some_and(|bucket| bucket.contains_key(&mutation.key)) =>
+                    {
+                        Operation::update(
+                            next_sequence,
+                            inner.instance_id.clone(),
+                            next_sequence,
+                            mutation.key.clone(),
+                            value.clone(),
+                            rust_type.clone(),
+                            mutation.capability.clone(),
+                        )
+                    }
+                    Some(value) => Operation::insert(
+                        next_sequence,
+                        inner.instance_id.clone(),
+                        next_sequence,
+                        mutation.key.clone(),
+                        value.clone(),
+                        rust_type.clone(),
+                        mutation.capability.clone(),
+                    ),
+                    None => Operation::delete(
+                        next_sequence,
+                        inner.instance_id.clone(),
+                        next_sequence,
+                        mutation.key.clone(),
+                        rust_type.clone(),
+                        mutation.capability.clone(),
+                    ),
+                }
+                .with_vector_clock(vector_clock.clone());
+                rows.push(StoredRow {
+                    capability: mutation.capability.clone(),
+                    key: mutation.key.clone(),
+                    rust_type,
+                    value: mutation.value.clone().unwrap_or(Value::Null),
+                    unix_ms: now_ms(),
+                    content_hash: Some(operation.content_hash.clone()),
+                    flow_ref: None,
+                    deleted: mutation.value.is_none(),
+                    operation: Some(operation),
+                });
+            }
+            let mut audit = audit;
+            if let Some(object) = audit.as_mut().and_then(Value::as_object_mut) {
+                object.insert("state_before".into(), Value::from(state_before));
+                object.insert("state_after".into(), Value::from(next_sequence));
+            }
+            let record = TransactionLogRecord {
+                record_type: "feltdb.transaction.v1".into(),
+                transaction_id: transaction_id.into(),
+                state_before,
+                state_after: next_sequence,
+                rows: rows.clone(),
+                audit,
+            };
+            append_transaction(&inner.path, &record)?;
+            inner.sequence = next_sequence;
+            for row in &rows {
+                if let Some(operation) = row.operation.clone() {
+                    inner.change_log.add_operation(operation);
+                }
+                if row.deleted {
+                    if let Some(bucket) = inner.rows.get_mut(&row.capability) {
+                        bucket.remove(&row.key);
+                    }
+                    // Decrement cardinality on delete
+                    let count = inner.collection_cardinality.entry(row.capability.clone()).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());
+
+                    // Increment cardinality only on insert, not update
+                    if is_insert {
+                        let count = inner.collection_cardinality.entry(row.capability.clone()).or_default();
+                        *count = count.saturating_add(1);
+                    }
+                }
+            }
+            inner.sync_state.merge_vector_clock(&vector_clock);
+            inner.applied_transactions.insert(transaction_id.into());
+            let events = rows
+                .iter()
+                .map(|row| ChangeEvent {
+                    capability: row.capability.clone(),
+                    key: row.key.clone(),
+                    rust_type: row.rust_type.clone(),
+                    unix_ms: row.unix_ms,
+                })
+                .collect::<Vec<_>>();
+            (
+                AtomicCommit {
+                    transaction_id: transaction_id.into(),
+                    state_before,
+                    state_after: inner.sequence,
+                    rows,
+                    duplicate: false,
+                },
+                events,
+            )
+        };
+        for event in events {
+            let _ = self.event_tx.send(event);
+        }
+        Ok(commit)
+    }
+
+    fn insert_internal<T: Serialize>(
+        &self,
+        capability: String,
+        key: String,
+        value: T,
+    ) -> Result<()> {
+        let rust_type = type_name::<T>().to_string();
+        let value_json = serde_json::to_value(value)?;
+        let mut row = StoredRow {
+            capability: capability.clone(),
+            key: key.clone(),
+            rust_type: rust_type.clone(),
+            value: value_json.clone(),
+            unix_ms: now_ms(),
+            content_hash: None,
+            flow_ref: None,
+            deleted: false,
+            operation: None,
+        };
+
+        {
+            let mut inner = self.inner.lock().expect("lock poisoned");
+
+            // Increment sequence number
+            inner.sequence += 1;
+
+            // Increment vector clock for this instance
+            inner.sync_state.increment_vector_clock();
+
+            // Get current vector clock to attach to operation
+            let vector_clock = inner.sync_state.get_or_init_vector_clock().clone();
+
+            // Create an operation with vector clock for convergence
+            let op = Operation::insert(
+                inner.sequence,
+                inner.instance_id.clone(),
+                inner.sequence,
+                key.clone(),
+                value_json,
+                rust_type.clone(),
+                capability.clone(),
+            )
+            .with_vector_clock(vector_clock);
+
+            // Add operation to change log for sync
+            row.operation = Some(op.clone());
+            inner.change_log.add_operation(op.clone());
+
+            append_event(&inner.path, &row)?;
+            inner
+                .rows
+                .entry(capability.clone())
+                .or_default()
+                .insert(key.clone(), 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();
+                *entry = (*entry).max(id + 1);
+            }
+        }
+
+        let event = ChangeEvent {
+            capability,
+            key,
+            rust_type,
+            unix_ms: now_ms(),
+        };
+        let _ = self.event_tx.send(event);
+
+        Ok(())
+    }
+
+    fn update_internal<T: Serialize>(
+        &self,
+        capability: String,
+        key: String,
+        value: T,
+    ) -> Result<()> {
+        let rust_type = type_name::<T>().to_string();
+        let value_json = serde_json::to_value(value)?;
+        let mut row = StoredRow {
+            capability: capability.clone(),
+            key: key.clone(),
+            rust_type: rust_type.clone(),
+            value: value_json.clone(),
+            unix_ms: now_ms(),
+            content_hash: None,
+            flow_ref: None,
+            deleted: false,
+            operation: None,
+        };
+
+        {
+            let mut inner = self.inner.lock().expect("lock poisoned");
+
+            // Increment sequence number
+            inner.sequence += 1;
+
+            // Increment vector clock for this instance
+            inner.sync_state.increment_vector_clock();
+
+            // Get current vector clock to attach to operation
+            let vector_clock = inner.sync_state.get_or_init_vector_clock().clone();
+
+            // Create an update operation with vector clock for convergence
+            let op = Operation::update(
+                inner.sequence,
+                inner.instance_id.clone(),
+                inner.sequence,
+                key.clone(),
+                value_json,
+                rust_type.clone(),
+                capability.clone(),
+            )
+            .with_vector_clock(vector_clock);
+
+            // Add operation to change log for sync
+            row.operation = Some(op.clone());
+            inner.change_log.add_operation(op.clone());
+
+            append_event(&inner.path, &row)?;
+            inner
+                .rows
+                .entry(capability.clone())
+                .or_default()
+                .insert(key.clone(), row);
+        }
+
+        let event = ChangeEvent {
+            capability,
+            key,
+            rust_type,
+            unix_ms: now_ms(),
+        };
+        let _ = self.event_tx.send(event);
+
+        Ok(())
+    }
+
+    fn delete_internal(&self, capability: String, key: String) -> Result<()> {
+        {
+            let mut inner = self.inner.lock().expect("lock poisoned");
+
+            // Get the row to determine its type
+            let rust_type = inner
+                .rows
+                .get(&capability)
+                .and_then(|bucket| bucket.get(&key))
+                .map(|row| row.rust_type.clone())
+                .unwrap_or_else(|| "Unknown".to_string());
+
+            // Increment sequence number
+            inner.sequence += 1;
+
+            // Increment vector clock for this instance
+            inner.sync_state.increment_vector_clock();
+
+            // Get current vector clock to attach to operation
+            let vector_clock = inner.sync_state.get_or_init_vector_clock().clone();
+
+            // Create a delete operation with vector clock for convergence
+            let op = Operation::delete(
+                inner.sequence,
+                inner.instance_id.clone(),
+                inner.sequence,
+                key.clone(),
+                rust_type.clone(),
+                capability.clone(),
+            )
+            .with_vector_clock(vector_clock);
+
+            // Add operation to change log for sync
+            inner.change_log.add_operation(op.clone());
+
+            // Persist a tombstone through the same append-only log used by
+            // inserts and updates. Without this, deleted rows reappeared after
+            // reopening the database.
+            let tombstone = StoredRow {
+                capability: capability.clone(),
+                key: key.clone(),
+                rust_type,
+                value: serde_json::Value::Null,
+                unix_ms: now_ms(),
+                content_hash: None,
+                flow_ref: None,
+                deleted: true,
+                operation: Some(op),
+            };
+            append_event(&inner.path, &tombstone)?;
+
+            // Remove from in-memory store
+            if let Some(bucket) = inner.rows.get_mut(&capability) {
+                bucket.remove(&key);
+            }
+        }
+
+        let event = ChangeEvent {
+            capability,
+            key,
+            rust_type: "Deleted".to_string(),
+            unix_ms: now_ms(),
+        };
+        let _ = self.event_tx.send(event);
+
+        Ok(())
+    }
+    ///
+    /// The subscription returns an initial set of matching results, and provides a stream
+    /// of updated results whenever records matching the predicate are inserted or updated.
+    ///
+    /// # Example
+    ///
+    /// ```ignore
+    /// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
+    /// use feltdb::open;
+    /// let db = open("app.data")?;
+    /// let mut subscription = db.live_query::<User, _>(|u| u.active).await?;
+    /// let initial_users = subscription.initial_results();
+    ///
+    /// while let Some(users) = subscription.next().await {
+    ///     println!("Active users: {:?}", users);
+    /// }
+    /// # Ok(())
+    /// # }
+    /// ```
+    pub async fn live_query<T, F>(&self, predicate: F) -> Result<LiveQuerySubscription<T>>
+    where
+        T: DeserializeOwned + Send + Sync + 'static,
+        F: Fn(&T) -> bool + Send + Sync + 'static,
+    {
+        let rust_type = type_name::<T>().to_string();
+
+        let initial_results = {
+            let mut inner = self.inner.lock().expect("lock poisoned");
+            *inner
+                .query_count_by_type
+                .entry(rust_type.clone())
+                .or_default() += 1;
+            if inner.query_count_by_type[&rust_type] >= 3 {
+                inner.adaptive_indexes.insert(rust_type.clone());
+            }
+
+            let mut out = Vec::new();
+            for bucket in inner.rows.values() {
+                for row in bucket.values() {
+                    if row.rust_type != rust_type {
+                        continue;
+                    }
+                    let parsed = serde_json::from_value::<T>(row.value.clone())?;
+                    if predicate(&parsed) {
+                        out.push(parsed);
+                    }
+                }
+            }
+            out
+        };
+
+        let rx = self.event_tx.subscribe();
+        let db = self.clone();
+        let subscription = LiveQuerySubscription {
+            initial_results,
+            rx,
+            db,
+            rust_type,
+            predicate: Arc::new(Mutex::new(None)),
+        };
+
+        Ok(subscription)
+    }
+
+    /// Get current sync state information
+    pub fn sync_info(&self) -> Result<SyncState> {
+        let inner = self.inner.lock().expect("lock poisoned");
+        Ok(inner.sync_state.clone())
+    }
+
+    /// Read an untyped value for protocol adapters such as the HTTP server.
+    pub fn get_value(&self, key: &str) -> Result<Option<Value>> {
+        self.get::<Value>(key)
+    }
+
+    /// List the canonical values in one collection/capability namespace.
+    pub fn list_collection(&self, capability: &str) -> Result<Vec<StoredRow>> {
+        let inner = self.inner.lock().expect("lock poisoned");
+        Ok(inner
+            .rows
+            .get(capability)
+            .map(|rows| rows.values().cloned().collect())
+            .unwrap_or_default())
+    }
+
+    /// Subscribe to canonical mutation events.
+    pub fn subscribe_changes(&self) -> broadcast::Receiver<ChangeEvent> {
+        self.event_tx.subscribe()
+    }
+
+    /// Add a peer for synchronization
+    pub fn add_sync_peer(&self, peer_id: String) -> Result<()> {
+        let mut inner = self.inner.lock().expect("lock poisoned");
+        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");
+        inner.sync_state.remove_peer(peer_id);
+        Ok(())
+    }
+
+    /// Get pending operations for a peer
+    pub fn get_pending_for_peer(
+        &self,
+        _peer_id: &str,
+        since_sequence: u64,
+    ) -> Result<Vec<Operation>> {
+        let inner = self.inner.lock().expect("lock poisoned");
+        let pending: Vec<Operation> = inner
+            .change_log
+            .pending_operations()
+            .into_iter()
+            .filter(|op| op.sequence > since_sequence)
+            .collect();
+        Ok(pending)
+    }
+
+    /// Return operations missing from a peer's per-origin version vector.
+    pub fn operations_since(
+        &self,
+        versions: &std::collections::HashMap<String, u64>,
+    ) -> Result<Vec<Operation>> {
+        let inner = self.inner.lock().expect("lock poisoned");
+        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");
+        Ok(inner.change_log.versions())
+    }
+
+    pub fn export_snapshot(&self) -> Result<DatabaseSnapshot> {
+        let inner = self.inner.lock().expect("lock poisoned");
+        let mut rows: Vec<StoredRow> = inner
+            .rows
+            .values()
+            .flat_map(|bucket| bucket.values().cloned())
+            .collect();
+        for row in &mut rows {
+            row.operation = None;
+        }
+        rows.sort_by(|left, right| left.key.cmp(&right.key));
+        let versions = inner.change_log.versions();
+        let content_hash = DatabaseSnapshot::compute_hash(&rows, &versions)?;
+        Ok(DatabaseSnapshot {
+            rows,
+            versions,
+            content_hash,
+        })
+    }
+    /// 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");
+        Ok(inner
+            .rows
+            .values()
+            .flat_map(|bucket| bucket.values().cloned())
+            .collect())
+    }
+
+    pub fn can_install_snapshot(&self) -> Result<bool> {
+        let inner = self.inner.lock().expect("lock poisoned");
+        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<()> {
+        snapshot.verify()?;
+        let mut inner = self.inner.lock().expect("lock poisoned");
+        if !inner.rows.is_empty() || !inner.change_log.pending.is_empty() {
+            return Err(FlowError::CapabilityError(
+                "snapshot bootstrap requires a pristine node".to_string(),
+            ));
+        }
+        for row in &snapshot.rows {
+            if row.deleted
+                || row.operation.is_some()
+                || !row.key.starts_with(&format!("{}:", row.capability))
+            {
+                return Err(FlowError::CapabilityError(
+                    "snapshot contains an invalid state row".to_string(),
+                ));
+            }
+        }
+
+        let temporary = inner.path.with_extension("snapshot.tmp");
+        let mut file = OpenOptions::new()
+            .create(true)
+            .write(true)
+            .truncate(true)
+            .open(&temporary)?;
+        write_json_line(
+            &mut file,
+            &LogHeader {
+                record_type: "feltdb.snapshot.v1".to_string(),
+                local_sequence: inner.sequence,
+                observed_versions: snapshot.versions.clone(),
+            },
+        )?;
+        for row in &snapshot.rows {
+            write_json_line(&mut file, row)?;
+        }
+        file.flush()?;
+        file.sync_all()?;
+        fs::rename(temporary, &inner.path)?;
+
+        inner.rows.clear();
+        inner.key_counters.clear();
+        for row in snapshot.rows {
+            if let Some(id) = row
+                .key
+                .rsplit_once(':')
+                .and_then(|(_, right)| right.parse::<u64>().ok())
+            {
+                let counter = inner
+                    .key_counters
+                    .entry(row.capability.clone())
+                    .or_default();
+                *counter = (*counter).max(id + 1);
+            }
+            inner
+                .rows
+                .entry(row.capability.clone())
+                .or_default()
+                .insert(row.key.clone(), row);
+        }
+        inner.change_log.observed_versions = snapshot.versions;
+        inner.bootstrapped = true;
+        persist_sync_metadata(&inner)
+    }
+
+    /// 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");
+        inner.change_log.acknowledge_peer(peer_id, sequence);
+        persist_sync_metadata(&inner)?;
+        Ok(())
+    }
+
+    /// Durably record a peer's per-origin acknowledgement vector.
+    pub fn acknowledge_peer_versions(
+        &self,
+        peer_id: String,
+        versions: HashMap<String, u64>,
+    ) -> Result<()> {
+        let mut inner = self.inner.lock().expect("lock poisoned");
+        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");
+        Ok(inner.change_log.acknowledged_versions(peer_id))
+    }
+
+    pub fn acknowledged_operation_count(&self, active_peers: &[String]) -> Result<usize> {
+        let inner = self.inner.lock().expect("lock poisoned");
+        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 removed = inner.change_log.prune_acknowledged(active_peers);
+        if removed == 0 {
+            return Ok(0);
+        }
+        persist_sync_metadata(&inner)?;
+
+        let temporary = inner.path.with_extension("compact.tmp");
+        let mut file = OpenOptions::new()
+            .create(true)
+            .write(true)
+            .truncate(true)
+            .open(&temporary)?;
+        write_json_line(
+            &mut file,
+            &LogHeader {
+                record_type: "feltdb.snapshot.v1".to_string(),
+                local_sequence: inner.sequence,
+                observed_versions: inner.change_log.versions(),
+            },
+        )?;
+        for operation in inner.change_log.pending_operations() {
+            write_json_line(&mut file, &stored_row_for_operation(operation))?;
+        }
+        for bucket in inner.rows.values() {
+            for row in bucket.values() {
+                let mut snapshot_row = row.clone();
+                snapshot_row.operation = None;
+                write_json_line(&mut file, &snapshot_row)?;
+            }
+        }
+        file.flush()?;
+        file.sync_all()?;
+        fs::rename(temporary, &inner.path)?;
+        inner.bootstrapped = true;
+        Ok(removed)
+    }
+
+    /// Register a peer in the distributed fabric
+    pub fn register_peer(&self, advertisement: PeerAdvertisement) -> Result<()> {
+        let inner = self.inner.lock().expect("lock poisoned");
+        inner
+            .peer_registry
+            .register(advertisement)
+            .map_err(|e| FlowError::CapabilityError(e))
+    }
+
+    /// Get a peer's advertisement
+    pub fn get_peer(&self, peer_id: &PeerId) -> Result<Option<PeerAdvertisement>> {
+        let inner = self.inner.lock().expect("lock poisoned");
+        inner
+            .peer_registry
+            .get(peer_id)
+            .map_err(|e| FlowError::CapabilityError(e))
+    }
+
+    /// 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");
+        inner
+            .peer_registry
+            .peers_for_namespace(namespace)
+            .map_err(|e| FlowError::CapabilityError(e))
+    }
+
+    /// 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");
+        inner
+            .peer_registry
+            .peers_for_capability(capability)
+            .map_err(|e| FlowError::CapabilityError(e))
+    }
+
+    /// Get all registered peers
+    pub fn all_peers(&self) -> Result<Vec<PeerAdvertisement>> {
+        let inner = self.inner.lock().expect("lock poisoned");
+        inner
+            .peer_registry
+            .all_peers()
+            .map_err(|e| FlowError::CapabilityError(e))
+    }
+
+    /// Resolve a FlowRef locally
+    pub fn resolve_ref<T: DeserializeOwned>(&self, flow_ref: &FlowRef) -> Result<Option<T>> {
+        // First, try to resolve locally
+        let key = format!("{}:{}", flow_ref.namespace, flow_ref.object_id);
+        self.get::<T>(&key)
+    }
+
+    /// Get current sync state
+    pub fn sync_state(&self) -> Result<SyncState> {
+        let inner = self.inner.lock().expect("lock poisoned");
+        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");
+
+        if op.content_hash != op.compute_content_hash() {
+            return Err(FlowError::CapabilityError(
+                "remote operation content hash mismatch".to_string(),
+            ));
+        }
+        if inner.change_log.has_operation(&op.instance_id, op.sequence) {
+            return Ok(());
+        }
+        let expected = inner
+            .change_log
+            .versions()
+            .get(&op.instance_id)
+            .copied()
+            .unwrap_or(0)
+            + 1;
+        if op.sequence != expected {
+            return Err(FlowError::CapabilityError(format!(
+                "remote operation sequence gap for {}: expected {}, received {}",
+                op.instance_id, expected, op.sequence
+            )));
+        }
+
+        // Merge the remote vector clock into our own
+        if let Some(remote_clock) = &op.vector_clock {
+            inner.sync_state.merge_vector_clock(remote_clock);
+        }
+
+        // Check if we have a local operation for this key that hasn't been synced yet
+        let local_op_for_key = inner
+            .change_log
+            .pending_operations()
+            .into_iter()
+            .find(|local_op| local_op.key == op.key && local_op.capability == op.capability);
+
+        // Determine which operation to apply (remote or local if conflict)
+        let op_to_apply = if let Some(local_op) = local_op_for_key {
+            // We have a conflict - use LWW with vector clock awareness
+            // Create causal histories for conflict resolution
+            let local_vc = local_op.vector_clock.clone().unwrap_or_default();
+            let remote_vc = op.vector_clock.clone().unwrap_or_default();
+
+            let local_history = CausalHistory::new(
+                StateVersion::from_clocks(local_vc, local_op.timestamp_ms),
+                local_op.instance_id.clone(),
+                local_op.sequence,
+            );
+
+            let remote_history = CausalHistory::new(
+                StateVersion::from_clocks(remote_vc, op.timestamp_ms),
+                op.instance_id.clone(),
+                op.sequence,
+            );
+
+            // Resolve using LWW strategy
+            let resolution = ConflictResolution::resolve_lww(&[local_history, remote_history]);
+
+            // Winner index: 0 = local, 1 = remote
+            if resolution.winner_index == Some(1) {
+                op.clone()
+            } else {
+                // The local value wins, but the received operation still belongs
+                // to the durable causal history so peers do not resend it forever.
+                if let Some(mut history_row) = inner
+                    .rows
+                    .get(&op.capability)
+                    .and_then(|rows| rows.get(&op.key))
+                    .cloned()
+                {
+                    history_row.operation = Some(op.clone());
+                    append_event(&inner.path, &history_row)?;
+                }
+                inner.change_log.add_operation(op);
+                inner.sync_state.increment_received(1);
+                return Ok(());
+            }
+        } else {
+            op.clone()
+        };
+
+        // Apply the winning operation to our state
+        let row = StoredRow {
+            capability: op_to_apply.capability.clone(),
+            key: op_to_apply.key.clone(),
+            rust_type: op_to_apply.rust_type.clone(),
+            value: op_to_apply.value.clone().unwrap_or(serde_json::Value::Null),
+            unix_ms: op_to_apply.timestamp_ms,
+            content_hash: Some(op_to_apply.content_hash.clone()),
+            flow_ref: None,
+            deleted: op_to_apply.op_type == OperationType::Delete,
+            operation: Some(op.clone()),
+        };
+
+        match op_to_apply.op_type {
+            OperationType::Insert | OperationType::Update => {
+                append_event(&inner.path, &row)?;
+                inner
+                    .rows
+                    .entry(op_to_apply.capability.clone())
+                    .or_default()
+                    .insert(op_to_apply.key.clone(), row);
+            }
+            OperationType::Delete => {
+                append_event(&inner.path, &row)?;
+                if let Some(bucket) = inner.rows.get_mut(&op_to_apply.capability) {
+                    bucket.remove(&op_to_apply.key);
+                }
+            }
+        }
+        if let Some(id) = op_to_apply
+            .key
+            .rsplit_once(':')
+            .and_then(|(_, right)| right.parse::<u64>().ok())
+        {
+            let counter = inner
+                .key_counters
+                .entry(op_to_apply.capability.clone())
+                .or_default();
+            *counter = (*counter).max(id + 1);
+        }
+
+        inner.change_log.add_operation(op);
+        inner.sync_state.increment_received(1);
+        let event = ChangeEvent {
+            capability: op_to_apply.capability,
+            key: op_to_apply.key,
+            rust_type: op_to_apply.rust_type,
+            unix_ms: op_to_apply.timestamp_ms,
+        };
+        drop(inner);
+        let _ = self.event_tx.send(event);
+
+        Ok(())
+    }
+
+    /// 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");
+        Ok(inner.sync_state.vector_clock.clone())
+    }
+}
+
+#[derive(Clone)]
+pub struct Capability {
+    db: FeltDb,
+    name: String,
+}
+
+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 next = inner.key_counters.entry(self.name.clone()).or_default();
+            let key = format!("{}:{}", self.name, *next);
+            *next += 1;
+            key
+        };
+        self.db
+            .insert_internal(self.name.clone(), key.clone(), value)?;
+        Ok(key)
+    }
+
+    pub fn insert_with_key<T: Serialize>(&self, key: &str, value: T) -> Result<()> {
+        let full_key = if key.contains(':') {
+            key.to_string()
+        } else {
+            format!("{}:{key}", self.name)
+        };
+        self.db.insert_internal(self.name.clone(), full_key, value)
+    }
+
+    pub fn update<T: Serialize>(&self, key: &str, value: T) -> Result<()> {
+        let full_key = if key.contains(':') {
+            key.to_string()
+        } else {
+            format!("{}:{key}", self.name)
+        };
+        self.db.update_internal(self.name.clone(), full_key, value)
+    }
+
+    pub fn delete(&self, key: &str) -> Result<()> {
+        let full_key = if key.contains(':') {
+            key.to_string()
+        } else {
+            format!("{}:{key}", self.name)
+        };
+        self.db.delete_internal(self.name.clone(), full_key)
+    }
+
+    pub fn get<T: DeserializeOwned>(&self, key: &str) -> Result<Option<T>> {
+        let full_key = if key.contains(':') {
+            key.to_string()
+        } else {
+            format!("{}:{key}", self.name)
+        };
+        self.db.get(&full_key)
+    }
+
+    pub fn find<T, F>(&self, predicate: F) -> Result<Vec<T>>
+    where
+        T: DeserializeOwned,
+        F: Fn(&T) -> bool,
+    {
+        let rust_type = type_name::<T>().to_string();
+        let mut inner = self.db.inner.lock().expect("lock poisoned");
+        *inner
+            .query_count_by_type
+            .entry(rust_type.clone())
+            .or_default() += 1;
+        if inner.query_count_by_type[&rust_type] >= 3 {
+            inner.adaptive_indexes.insert(rust_type.clone());
+        }
+
+        let mut out = Vec::new();
+        if let Some(bucket) = inner.rows.get(&self.name) {
+            for row in bucket.values() {
+                if row.rust_type != rust_type {
+                    continue;
+                }
+                let parsed = serde_json::from_value::<T>(row.value.clone())?;
+                if predicate(&parsed) {
+                    out.push(parsed);
+                }
+            }
+        }
+        Ok(out)
+    }
+
+    /// Creates a live query subscription scoped to this capability.
+    ///
+    /// The subscription returns initial matching results from this capability only, and streams
+    /// updates whenever records within this capability matching the predicate are inserted or updated.
+    ///
+    /// # Example
+    ///
+    /// ```ignore
+    /// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
+    /// use feltdb::open;
+    /// let db = open("app.data")?;
+    /// let users = db.capability("users");
+    /// let mut subscription = users.live_find::<User, _>(|u| u.active).await?;
+    /// let initial_users = subscription.initial_results();
+    ///
+    /// while let Some(users) = subscription.next().await {
+    ///     println!("Active users: {:?}", users);
+    /// }
+    /// # Ok(())
+    /// # }
+    /// ```
+    pub async fn live_find<T, F>(&self, predicate: F) -> Result<LiveCapabilitySubscription<T>>
+    where
+        T: DeserializeOwned + Send + Sync + 'static,
+        F: Fn(&T) -> bool + Send + Sync + 'static,
+    {
+        let rust_type = type_name::<T>().to_string();
+        let capability_name = self.name.clone();
+
+        let initial_results = {
+            let mut inner = self.db.inner.lock().expect("lock poisoned");
+            *inner
+                .query_count_by_type
+                .entry(rust_type.clone())
+                .or_default() += 1;
+            if inner.query_count_by_type[&rust_type] >= 3 {
+                inner.adaptive_indexes.insert(rust_type.clone());
+            }
+
+            let mut out = Vec::new();
+            if let Some(bucket) = inner.rows.get(&capability_name) {
+                for row in bucket.values() {
+                    if row.rust_type != rust_type {
+                        continue;
+                    }
+                    let parsed = serde_json::from_value::<T>(row.value.clone())?;
+                    if predicate(&parsed) {
+                        out.push(parsed);
+                    }
+                }
+            }
+            out
+        };
+
+        let rx = self.db.event_tx.subscribe();
+        let subscription = LiveCapabilitySubscription {
+            initial_results,
+            rx,
+            db: self.db.clone(),
+            capability_name,
+            rust_type,
+            predicate: Arc::new(Mutex::new(None)),
+        };
+
+        Ok(subscription)
+    }
+}
+
+// Type alias for boxed predicates
+type PredicateBox<T> = Arc<Mutex<Option<Box<dyn Fn(&T) -> bool + Send + Sync>>>>;
+
+/// A subscription to a live query that streams updates whenever matching records change.
+///
+/// This struct holds the initial query results and provides a stream interface to receive
+/// updates whenever records matching the query predicate are inserted or updated.
+pub struct LiveQuerySubscription<T> {
+    /// The initial set of records matching the query predicate at subscription time.
+    pub initial_results: Vec<T>,
+    rx: broadcast::Receiver<ChangeEvent>,
+    db: FeltDb,
+    rust_type: String,
+    predicate: PredicateBox<T>,
+}
+
+impl<T> LiveQuerySubscription<T>
+where
+    T: DeserializeOwned + Send + Sync + 'static,
+{
+    pub fn set_predicate<F>(&mut self, predicate: F)
+    where
+        F: Fn(&T) -> bool + Send + Sync + 'static,
+    {
+        *self.predicate.lock().expect("lock poisoned") = Some(Box::new(predicate));
+    }
+
+    /// Waits for the next change event and returns the updated query results.
+    ///
+    /// This method is async and will block until a change event is received for the
+    /// subscribed type. When an event arrives, it re-evaluates the full dataset and
+    /// returns all matching records.
+    ///
+    /// Returns `None` if the broadcast channel has been dropped (all senders are gone).
+    pub async fn next(&mut self) -> Option<Vec<T>> {
+        loop {
+            match self.rx.recv().await {
+                Ok(event) => {
+                    if event.rust_type != self.rust_type {
+                        continue;
+                    }
+
+                    let results = {
+                        let inner = self.db.inner.lock().expect("lock poisoned");
+                        let mut out = Vec::new();
+                        for bucket in inner.rows.values() {
+                            for row in bucket.values() {
+                                if row.rust_type != self.rust_type {
+                                    continue;
+                                }
+                                if let Ok(parsed) = serde_json::from_value::<T>(row.value.clone()) {
+                                    out.push(parsed);
+                                }
+                            }
+                        }
+                        out
+                    };
+
+                    return Some(results);
+                }
+                Err(_) => {
+                    return None;
+                }
+            }
+        }
+    }
+
+    /// Returns a reference to the initial query results captured at subscription time.
+    ///
+    /// This provides access to the baseline set of matching records before any changes
+    /// have been streamed through `next()`.
+    pub fn initial_results(&self) -> &[T] {
+        &self.initial_results
+    }
+}
+
+/// A capability-scoped subscription to a live query that streams updates for records within a specific capability.
+///
+/// Similar to `LiveQuerySubscription`, but only receives updates for records within the specified capability.
+/// This provides more granular control over subscription scope.
+pub struct LiveCapabilitySubscription<T> {
+    pub initial_results: Vec<T>,
+    rx: broadcast::Receiver<ChangeEvent>,
+    db: FeltDb,
+    capability_name: String,
+    rust_type: String,
+    predicate: PredicateBox<T>,
+}
+
+impl<T> LiveCapabilitySubscription<T>
+where
+    T: DeserializeOwned + Send + Sync + 'static,
+{
+    pub fn set_predicate<F>(&mut self, predicate: F)
+    where
+        F: Fn(&T) -> bool + Send + Sync + 'static,
+    {
+        *self.predicate.lock().expect("lock poisoned") = Some(Box::new(predicate));
+    }
+
+    /// Waits for the next change event within this capability and returns the updated query results.
+    ///
+    /// Similar to `LiveQuerySubscription::next()`, but only responds to changes within the
+    /// scoped capability.
+    pub async fn next(&mut self) -> Option<Vec<T>> {
+        loop {
+            match self.rx.recv().await {
+                Ok(event) => {
+                    if event.rust_type != self.rust_type || event.capability != self.capability_name
+                    {
+                        continue;
+                    }
+
+                    let results = {
+                        let inner = self.db.inner.lock().expect("lock poisoned");
+                        let mut out = Vec::new();
+                        if let Some(bucket) = inner.rows.get(&self.capability_name) {
+                            for row in bucket.values() {
+                                if row.rust_type != self.rust_type {
+                                    continue;
+                                }
+                                if let Ok(parsed) = serde_json::from_value::<T>(row.value.clone()) {
+                                    out.push(parsed);
+                                }
+                            }
+                        }
+                        out
+                    };
+
+                    return Some(results);
+                }
+                Err(_) => {
+                    return None;
+                }
+            }
+        }
+    }
+
+    pub fn initial_results(&self) -> &[T] {
+        &self.initial_results
+    }
+}
+
+fn replay_log(inner: &mut Inner) -> Result<()> {
+    let file = OpenOptions::new().read(true).open(&inner.path)?;
+    let reader = BufReader::new(file);
+
+    let mut snapshot_log = false;
+    for line in reader.lines() {
+        let line = line?;
+        if line.trim().is_empty() {
+            continue;
+        }
+        let value: Value =
+            serde_json::from_str(&line).map_err(|_| FlowError::CorruptLogLine(line.clone()))?;
+        if matches!(
+            value.get("record_type").and_then(Value::as_str),
+            Some("feltdb.snapshot.v1" | "flowdb.snapshot.v1")
+        ) {
+            let header: LogHeader = serde_json::from_value(value)?;
+            inner.sequence = inner.sequence.max(header.local_sequence);
+            inner.change_log.observed_versions = header.observed_versions;
+            inner.bootstrapped = true;
+            snapshot_log = true;
+            continue;
+        }
+        if value.get("record_type").and_then(Value::as_str) == Some("feltdb.transaction.v1") {
+            let transaction: TransactionLogRecord = serde_json::from_value(value)?;
+            if inner
+                .applied_transactions
+                .insert(transaction.transaction_id)
+            {
+                for row in transaction.rows {
+                    if let Some(operation) = row.operation.clone() {
+                        inner.sequence = inner.sequence.max(operation.sequence);
+                        if let Some(clock) = &operation.vector_clock {
+                            inner.sync_state.merge_vector_clock(clock);
+                        }
+                        inner.change_log.add_operation(operation);
+                    }
+                    if row.deleted {
+                        if let Some(bucket) = inner.rows.get_mut(&row.capability) {
+                            bucket.remove(&row.key);
+                        }
+                    } else {
+                        inner
+                            .rows
+                            .entry(row.capability.clone())
+                            .or_default()
+                            .insert(row.key.clone(), row);
+                    }
+                }
+            }
+            inner.sequence = inner.sequence.max(transaction.state_after);
+            continue;
+        }
+        let row: StoredRow =
+            serde_json::from_value(value).map_err(|_| FlowError::CorruptLogLine(line.clone()))?;
+        if let Some(operation) = row.operation.clone() {
+            inner.sequence = inner.sequence.max(
+                (operation.instance_id == inner.instance_id)
+                    .then_some(operation.sequence)
+                    .unwrap_or(0),
+            );
+            if let Some(clock) = &operation.vector_clock {
+                inner.sync_state.merge_vector_clock(clock);
+            }
+            inner.change_log.add_operation(operation);
+        } else if !snapshot_log {
+            // Pre-operation-envelope logs were produced only by this local
+            // store. Preserve a monotonic sequence when upgrading them.
+            inner.sequence += 1;
+        }
+        if let Some(id) = row
+            .key
+            .rsplit_once(':')
+            .and_then(|(_, right)| right.parse::<u64>().ok())
+        {
+            let counter = inner
+                .key_counters
+                .entry(row.capability.clone())
+                .or_default();
+            *counter = (*counter).max(id + 1);
+        }
+        if row.deleted {
+            if let Some(bucket) = inner.rows.get_mut(&row.capability) {
+                bucket.remove(&row.key);
+            }
+        } else {
+            inner
+                .rows
+                .entry(row.capability.clone())
+                .or_default()
+                .insert(row.key.clone(), row);
+        }
+    }
+
+    // Compute collection cardinality from final row state (count non-deleted rows per capability)
+    for (capability, bucket) in &inner.rows {
+        let count = bucket.values().filter(|row| !row.deleted).count() as u64;
+        inner.collection_cardinality.insert(capability.clone(), count);
+    }
+
+    Ok(())
+}
+
+fn write_json_line<T: Serialize>(file: &mut std::fs::File, value: &T) -> Result<()> {
+    serde_json::to_writer(&mut *file, value)?;
+    file.write_all(b"\n")?;
+    Ok(())
+}
+
+fn stored_row_for_operation(operation: Operation) -> StoredRow {
+    StoredRow {
+        capability: operation.capability.clone(),
+        key: operation.key.clone(),
+        rust_type: operation.rust_type.clone(),
+        value: operation.value.clone().unwrap_or(Value::Null),
+        unix_ms: operation.timestamp_ms,
+        content_hash: Some(operation.content_hash.clone()),
+        flow_ref: None,
+        deleted: operation.op_type == OperationType::Delete,
+        operation: Some(operation),
+    }
+}
+
+fn sync_metadata_path(path: &Path) -> PathBuf {
+    path.with_extension("sync.json")
+}
+
+fn load_sync_metadata(inner: &mut Inner) -> Result<()> {
+    let path = sync_metadata_path(&inner.path);
+    if !path.exists() {
+        return Ok(());
+    }
+    let metadata: SyncMetadata = serde_json::from_slice(&fs::read(path)?)?;
+    inner.sequence = inner.sequence.max(metadata.local_sequence);
+    for (origin, sequence) in metadata.observed_versions {
+        inner
+            .change_log
+            .observed_versions
+            .entry(origin)
+            .and_modify(|current| *current = (*current).max(sequence))
+            .or_insert(sequence);
+    }
+    inner.change_log.peer_acknowledgements = metadata.peer_acknowledgements;
+    Ok(())
+}
+
+fn persist_sync_metadata(inner: &Inner) -> Result<()> {
+    let path = sync_metadata_path(&inner.path);
+    let temporary = path.with_extension("sync.tmp");
+    let metadata = SyncMetadata {
+        local_sequence: inner.sequence,
+        observed_versions: inner.change_log.versions(),
+        peer_acknowledgements: inner.change_log.peer_acknowledgements.clone(),
+    };
+    let mut file = OpenOptions::new()
+        .create(true)
+        .write(true)
+        .truncate(true)
+        .open(&temporary)?;
+    file.write_all(&serde_json::to_vec_pretty(&metadata)?)?;
+    file.flush()?;
+    file.sync_all()?;
+    fs::rename(temporary, path)?;
+    Ok(())
+}
+
+fn append_event(path: &Path, event: &StoredRow) -> Result<()> {
+    let mut file = OpenOptions::new().create(true).append(true).open(path)?;
+    let mut line = serde_json::to_string(event)?;
+    line.push('\n');
+    file.write_all(line.as_bytes())?;
+    file.flush()?;
+    Ok(())
+}
+
+fn append_transaction(path: &Path, transaction: &TransactionLogRecord) -> Result<()> {
+    let mut file = OpenOptions::new().create(true).append(true).open(path)?;
+    write_json_line(&mut file, transaction)?;
+    file.sync_data()?;
+    Ok(())
+}
+
+fn now_ms() -> u128 {
+    SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .expect("time moved backwards")
+        .as_millis()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::sync::atomic::{AtomicU64, Ordering};
+    use std::time::{SystemTime, UNIX_EPOCH};
+
+    static TEMP_FILE_SEQUENCE: AtomicU64 = AtomicU64::new(0);
+
+    #[derive(Debug, Clone, serde::Serialize, serde::Deserialize, PartialEq, Eq)]
+    struct User {
+        email: String,
+        age: u8,
+        active: bool,
+    }
+
+    fn temp_file() -> PathBuf {
+        let nanos = SystemTime::now()
+            .duration_since(UNIX_EPOCH)
+            .expect("time")
+            .as_nanos();
+        let sequence = TEMP_FILE_SEQUENCE.fetch_add(1, Ordering::Relaxed);
+        std::env::temp_dir().join(format!(
+            "feltdb-test-{}-{nanos}-{sequence}.data",
+            std::process::id()
+        ))
+    }
+
+    #[test]
+    fn open_is_zero_init_and_creates_store() {
+        let path = temp_file();
+        let db = open(&path).expect("open");
+        assert!(path.exists());
+        drop(db);
+        let _ = fs::remove_file(path);
+    }
+
+    #[test]
+    fn insert_get_and_reopen_are_durable() {
+        let path = temp_file();
+        let db = open(&path).expect("open");
+        let user = User {
+            email: "a@feltdb.dev".to_string(),
+            age: 33,
+            active: true,
+        };
+        db.insert("user:1", &user).expect("insert");
+        let loaded: User = db.get("user:1").expect("get").expect("some");
+        assert_eq!(loaded, user);
+        drop(db);
+
+        let reopened = open(&path).expect("reopen");
+        let loaded_after_restart: User = reopened.get("user:1").expect("get").expect("some");
+        assert_eq!(loaded_after_restart, user);
+        let _ = fs::remove_file(path);
+    }
+
+    #[test]
+    fn delete_and_reopen_preserves_tombstone() {
+        let path = temp_file();
+        let db = open(&path).expect("open");
+        db.insert("users:deleted", serde_json::json!({"name": "gone"}))
+            .expect("insert");
+        db.delete("users:deleted").expect("delete");
+        drop(db);
+
+        let reopened = open(&path).expect("reopen");
+        assert_eq!(reopened.get_value("users:deleted").expect("get"), None);
+        let _ = fs::remove_file(path);
+    }
+
+    #[test]
+    fn closure_query_and_capability_find_work() {
+        let path = temp_file();
+        let db = open(&path).expect("open");
+        let users = db.capability("users");
+        users
+            .insert(User {
+                email: "one@feltdb.dev".to_string(),
+                age: 28,
+                active: true,
+            })
+            .expect("insert");
+        users
+            .insert(User {
+                email: "two@feltdb.dev".to_string(),
+                age: 41,
+                active: false,
+            })
+            .expect("insert");
+
+        let global = db.query::<User, _>(|u| u.age > 30).expect("query");
+        assert_eq!(global.len(), 1);
+
+        let active = users.find::<User, _>(|u| u.active).expect("find");
+        assert_eq!(active.len(), 1);
+        assert_eq!(active[0].email, "one@feltdb.dev");
+        let _ = fs::remove_file(path);
+    }
+
+    #[test]
+    fn adaptive_index_marks_frequent_query_types() {
+        let path = temp_file();
+        let db = open(&path).expect("open");
+        db.insert(
+            "user:1",
+            User {
+                email: "index@feltdb.dev".to_string(),
+                age: 21,
+                active: true,
+            },
+        )
+        .expect("insert");
+
+        for _ in 0..3 {
+            let _ = db.query::<User, _>(|u| u.active).expect("query");
+        }
+        assert!(db.is_auto_indexed::<User>());
+        let _ = fs::remove_file(path);
+    }
+
+    #[tokio::test]
+    async fn live_query_returns_initial_results() {
+        let path = temp_file();
+        let db = open(&path).expect("open");
+        let users = db.capability("users");
+        users
+            .insert(User {
+                email: "live@feltdb.dev".to_string(),
+                age: 28,
+                active: true,
+            })
+            .expect("insert");
+        users
+            .insert(User {
+                email: "inactive@feltdb.dev".to_string(),
+                age: 35,
+                active: false,
+            })
+            .expect("insert");
+
+        let subscription = db
+            .live_query::<User, _>(|u| u.active)
+            .await
+            .expect("live_query");
+        let initial = subscription.initial_results();
+        assert_eq!(initial.len(), 1);
+        assert_eq!(initial[0].email, "live@feltdb.dev");
+        let _ = fs::remove_file(path);
+    }
+
+    #[tokio::test]
+    async fn live_query_streams_new_changes() {
+        let path = temp_file();
+        let db = open(&path).expect("open");
+        let users = db.capability("users");
+        users
+            .insert(User {
+                email: "initial@feltdb.dev".to_string(),
+                age: 28,
+                active: true,
+            })
+            .expect("insert");
+
+        let mut subscription = db
+            .live_query::<User, _>(|u| u.active)
+            .await
+            .expect("live_query");
+        let initial = subscription.initial_results();
+        assert_eq!(initial.len(), 1);
+
+        let db_for_insert = db.clone();
+        tokio::spawn(async move {
+            tokio::time::sleep(tokio::time::Duration::from_millis(50)).await;
+            let users_inner = db_for_insert.capability("users");
+            users_inner
+                .insert(User {
+                    email: "new@feltdb.dev".to_string(),
+                    age: 25,
+                    active: true,
+                })
+                .expect("insert");
+        });
+
+        let updated = subscription.next().await;
+        assert!(updated.is_some());
+        let results = updated.unwrap();
+        assert_eq!(results.len(), 2);
+        let _ = fs::remove_file(path);
+    }
+
+    #[tokio::test]
+    async fn live_query_filters_by_predicate() {
+        let path = temp_file();
+        let db = open(&path).expect("open");
+        let users = db.capability("users");
+        users
+            .insert(User {
+                email: "active@feltdb.dev".to_string(),
+                age: 28,
+                active: true,
+            })
+            .expect("insert");
+        users
+            .insert(User {
+                email: "inactive@feltdb.dev".to_string(),
+                age: 35,
+                active: false,
+            })
+            .expect("insert");
+
+        let subscription = db
+            .live_query::<User, _>(|u| u.active)
+            .await
+            .expect("live_query");
+        let initial = subscription.initial_results();
+        assert_eq!(initial.len(), 1);
+        assert!(initial[0].active);
+        let _ = fs::remove_file(path);
+    }
+
+    #[tokio::test]
+    async fn change_events_are_emitted_on_insert() {
+        let path = temp_file();
+        let db = open(&path).expect("open");
+
+        let mut subscription = db
+            .live_query::<User, _>(|_| true)
+            .await
+            .expect("live_query");
+        let initial = subscription.initial_results();
+        assert_eq!(initial.len(), 0);
+
+        let db_for_insert = db.clone();
+        tokio::spawn(async move {
+            tokio::time::sleep(tokio::time::Duration::from_millis(50)).await;
+            let users_inner = db_for_insert.capability("users");
+            users_inner
+                .insert(User {
+                    email: "event@feltdb.dev".to_string(),
+                    age: 30,
+                    active: true,
+                })
+                .expect("insert");
+        });
+
+        let update = subscription.next().await;
+        assert!(update.is_some());
+        let users_result = update.unwrap();
+        assert_eq!(users_result.len(), 1);
+        let _ = fs::remove_file(path);
+    }
+
+    #[tokio::test]
+    async fn capability_live_find_returns_initial_results() {
+        let path = temp_file();
+        let db = open(&path).expect("open");
+        let users = db.capability("users");
+        users
+            .insert(User {
+                email: "cap_live@feltdb.dev".to_string(),
+                age: 28,
+                active: true,
+            })
+            .expect("insert");
+        users
+            .insert(User {
+                email: "cap_inactive@feltdb.dev".to_string(),
+                age: 35,
+                active: false,
+            })
+            .expect("insert");
+
+        let subscription = users
+            .live_find::<User, _>(|u| u.active)
+            .await
+            .expect("live_find");
+        let initial = subscription.initial_results();
+        assert_eq!(initial.len(), 1);
+        assert_eq!(initial[0].email, "cap_live@feltdb.dev");
+        let _ = fs::remove_file(path);
+    }
+
+    #[tokio::test]
+    async fn capability_live_find_streams_scoped_changes() {
+        let path = temp_file();
+        let db = open(&path).expect("open");
+        let users = db.capability("users");
+        let _orders = db.capability("orders");
+        users
+            .insert(User {
+                email: "user_scoped@feltdb.dev".to_string(),
+                age: 28,
+                active: true,
+            })
+            .expect("insert");
+
+        let mut subscription = users
+            .live_find::<User, _>(|u| u.active)
+            .await
+            .expect("live_find");
+        let initial = subscription.initial_results();
+        assert_eq!(initial.len(), 1);
+
+        let db_for_insert = db.clone();
+        tokio::spawn(async move {
+            tokio::time::sleep(tokio::time::Duration::from_millis(50)).await;
+            let users_inner = db_for_insert.capability("users");
+            users_inner
+                .insert(User {
+                    email: "new_user_scoped@feltdb.dev".to_string(),
+                    age: 25,
+                    active: true,
+                })
+                .expect("insert");
+        });
+
+        let updated = subscription.next().await;
+        assert!(updated.is_some());
+        let results = updated.unwrap();
+        assert_eq!(results.len(), 2);
+        let _ = fs::remove_file(path);
+    }
+
+    #[test]
+    fn vector_clocks_increment_on_mutations() {
+        let path = temp_file();
+        let db = open(&path).expect("open");
+
+        // Initial vector clock should be empty or have default values
+        let initial_clock = db.get_vector_clock().expect("get_vector_clock");
+        assert!(initial_clock.is_none() || initial_clock.as_ref().unwrap().is_empty());
+
+        // Insert first record
+        db.insert(
+            "users:1",
+            User {
+                email: "user1@feltdb.dev".to_string(),
+                age: 25,
+                active: true,
+            },
+        )
+        .expect("insert");
+
+        // Check pending operations have vector clock
+        let pending = db
+            .get_pending_for_peer("peer-1", 0)
+            .expect("get_pending_for_peer");
+        assert_eq!(pending.len(), 1);
+        assert!(pending[0].vector_clock.is_some());
+
+        // Insert second record
+        db.insert(
+            "users:2",
+            User {
+                email: "user2@feltdb.dev".to_string(),
+                age: 30,
+                active: false,
+            },
+        )
+        .expect("insert");
+
+        // Check we have 2 operations with increasing sequence numbers
+        let pending = db
+            .get_pending_for_peer("peer-1", 0)
+            .expect("get_pending_for_peer");
+        assert_eq!(pending.len(), 2);
+        assert_eq!(pending[0].sequence, 1);
+        assert_eq!(pending[1].sequence, 2);
+
+        let _ = fs::remove_file(path);
+    }
+
+    #[test]
+    fn update_creates_operation_with_vector_clock() {
+        let path = temp_file();
+        let db = open(&path).expect("open");
+
+        // Insert initial record
+        db.insert(
+            "users:1",
+            User {
+                email: "user1@feltdb.dev".to_string(),
+                age: 25,
+                active: true,
+            },
+        )
+        .expect("insert");
+
+        // Update the record
+        db.update(
+            "users:1",
+            User {
+                email: "user1@feltdb.dev".to_string(),
+                age: 26,
+                active: true,
+            },
+        )
+        .expect("update");
+
+        // Check we have operations for both insert and update
+        let pending = db
+            .get_pending_for_peer("peer-1", 0)
+            .expect("get_pending_for_peer");
+        assert_eq!(pending.len(), 2);
+        assert_eq!(pending[0].op_type, OperationType::Insert);
+        assert_eq!(pending[1].op_type, OperationType::Update);
+
+        // Both should have vector clocks
+        assert!(pending[0].vector_clock.is_some());
+        assert!(pending[1].vector_clock.is_some());
+
+        let _ = fs::remove_file(path);
+    }
+
+    #[test]
+    fn delete_creates_operation_with_vector_clock() {
+        let path = temp_file();
+        let db = open(&path).expect("open");
+
+        // Insert record
+        db.insert(
+            "users:1",
+            User {
+                email: "user1@feltdb.dev".to_string(),
+                age: 25,
+                active: true,
+            },
+        )
+        .expect("insert");
+
+        // Delete the record
+        db.delete("users:1").expect("delete");
+
+        // Check we have operations for both insert and delete
+        let pending = db
+            .get_pending_for_peer("peer-1", 0)
+            .expect("get_pending_for_peer");
+        assert_eq!(pending.len(), 2);
+        assert_eq!(pending[0].op_type, OperationType::Insert);
+        assert_eq!(pending[1].op_type, OperationType::Delete);
+
+        // Both should have vector clocks
+        assert!(pending[0].vector_clock.is_some());
+        assert!(pending[1].vector_clock.is_some());
+
+        let _ = fs::remove_file(path);
+    }
+
+    #[test]
+    fn apply_remote_operation_merges_vector_clocks() {
+        let path = temp_file();
+        let db = open(&path).expect("open");
+
+        // Create a remote operation with a vector clock
+        let remote_op = Operation::insert(
+            1,
+            "remote-instance".to_string(),
+            1,
+            "users:100".to_string(),
+            serde_json::json!({"email": "remote@feltdb.dev", "age": 30, "active": true}),
+            "User".to_string(),
+            "users".to_string(),
+        )
+        .with_vector_clock({
+            let mut vc = std::collections::HashMap::new();
+            vc.insert("remote-instance".to_string(), 1);
+            vc
+        });
+
+        // Apply the remote operation
+        db.apply_remote_operation(remote_op)
+            .expect("apply_remote_operation");
+
+        // Check the local vector clock was merged
+        let clock = db.get_vector_clock().expect("get_vector_clock");
+        assert!(clock.is_some());
+        let clock = clock.unwrap();
+        assert_eq!(clock.get("remote-instance"), Some(&1));
+
+        // Verify the data was applied
+        let user: Option<User> = db.get("users:100").expect("get");
+        assert!(user.is_some());
+
+        let _ = fs::remove_file(path);
+    }
+
+    #[test]
+    fn operation_history_survives_restart_and_relays_transitively() {
+        let source_path = temp_file();
+        let relay_path = temp_file();
+        let destination_path = temp_file();
+        let source = open(&source_path).expect("open source");
+        source
+            .insert("docs:1", serde_json::json!({"title": "one"}))
+            .unwrap();
+        source
+            .insert("docs:2", serde_json::json!({"title": "two"}))
+            .unwrap();
+
+        let relay = open(&relay_path).expect("open relay");
+        for operation in source.operations_since(&HashMap::new()).unwrap() {
+            relay.apply_remote_operation(operation).unwrap();
+        }
+        drop(relay);
+
+        let relay = open(&relay_path).expect("reopen relay");
+        let relayed = relay.operations_since(&HashMap::new()).unwrap();
+        assert_eq!(relayed.len(), 2);
+        let destination = open(&destination_path).expect("open destination");
+        for operation in relayed {
+            destination.apply_remote_operation(operation).unwrap();
+        }
+        assert_eq!(
+            destination.get_value("docs:2").unwrap(),
+            Some(serde_json::json!({"title": "two"}))
+        );
+
+        let _ = fs::remove_file(source_path);
+        let _ = fs::remove_file(relay_path);
+        let _ = fs::remove_file(destination_path);
+    }
+
+    #[test]
+    fn remote_operation_sequence_gaps_are_rejected() {
+        let path = temp_file();
+        let db = open(&path).unwrap();
+        let operation = Operation::insert(
+            2,
+            "remote".to_string(),
+            2,
+            "docs:2".to_string(),
+            serde_json::json!({"title": "two"}),
+            "Value".to_string(),
+            "docs".to_string(),
+        );
+        assert!(db.apply_remote_operation(operation).is_err());
+        assert!(db.get_value("docs:2").unwrap().is_none());
+        let _ = fs::remove_file(path);
+    }
+
+    #[test]
+    fn peer_version_acknowledgements_survive_restart() {
+        let path = temp_file();
+        let db = open(&path).unwrap();
+        db.insert("docs:1", serde_json::json!({"title": "one"}))
+            .unwrap();
+        let versions = db.operation_versions().unwrap();
+        db.acknowledge_peer_versions("peer-a".to_string(), versions.clone())
+            .unwrap();
+        drop(db);
+
+        let reopened = open(&path).unwrap();
+        assert_eq!(
+            reopened.acknowledged_peer_versions("peer-a").unwrap(),
+            versions
+        );
+        assert_eq!(
+            reopened
+                .acknowledged_operation_count(&["peer-a".to_string()])
+                .unwrap(),
+            1
+        );
+        let _ = fs::remove_file(sync_metadata_path(&path));
+        let _ = fs::remove_file(path);
+    }
+
+    #[test]
+    fn compacted_history_bootstraps_a_new_peer_without_sequence_gaps() {
+        let source_path = temp_file();
+        let destination_path = temp_file();
+        let source = open(&source_path).unwrap();
+        source
+            .insert("docs:1", serde_json::json!({"title": "one"}))
+            .unwrap();
+        source
+            .insert("docs:2", serde_json::json!({"title": "two"}))
+            .unwrap();
+        let versions = source.operation_versions().unwrap();
+        source
+            .acknowledge_peer_versions("peer-a".to_string(), versions.clone())
+            .unwrap();
+        assert_eq!(
+            source
+                .compact_operation_log(&["peer-a".to_string()])
+                .unwrap(),
+            2
+        );
+        assert!(source.operations_since(&HashMap::new()).unwrap().is_empty());
+        drop(source);
+
+        let source = open(&source_path).unwrap();
+        assert_eq!(source.operation_versions().unwrap(), versions);
+        let snapshot = source.export_snapshot().unwrap();
+        let destination = open(&destination_path).unwrap();
+        destination.install_snapshot(snapshot).unwrap();
+        assert_eq!(destination.operation_versions().unwrap(), versions);
+        assert_eq!(
+            destination.get_value("docs:2").unwrap(),
+            Some(serde_json::json!({"title": "two"}))
+        );
+
+        source
+            .insert("docs:3", serde_json::json!({"title": "three"}))
+            .unwrap();
+        let next = source.operations_since(&versions).unwrap();
+        assert_eq!(next.len(), 1);
+        destination.apply_remote_operation(next[0].clone()).unwrap();
+        assert!(destination.get_value("docs:3").unwrap().is_some());
+
+        let _ = fs::remove_file(sync_metadata_path(&source_path));
+        let _ = fs::remove_file(sync_metadata_path(&destination_path));
+        let _ = fs::remove_file(source_path);
+        let _ = fs::remove_file(destination_path);
+    }
+
+    #[test]
+    fn maintained_cardinality_unfiltered_count_basic() {
+        let path = temp_file();
+        let db = open(&path).unwrap();
+        let capability = "test_collection";
+
+        let mutations = vec![
+            AtomicMutation {
+                capability: capability.to_string(),
+                key: "rec-1".to_string(),
+                value: Some(serde_json::json!({"id": 1, "name": "Record 1"})),
+            },
+            AtomicMutation {
+                capability: capability.to_string(),
+                key: "rec-2".to_string(),
+                value: Some(serde_json::json!({"id": 2, "name": "Record 2"})),
+            },
+        ];
+
+        db.apply_atomic_transaction("txn-1", None, &[], &mutations, None).unwrap();
+
+        let cardinality = db.collection_cardinality(capability).unwrap();
+        assert_eq!(cardinality, 2, "Cardinality should be 2 after 2 inserts");
+
+        let _ = fs::remove_file(path);
+    }
+
+    #[test]
+    fn maintained_cardinality_insert_increments() {
+        let path = temp_file();
+        let db = open(&path).unwrap();
+        let capability = "test_collection";
+
+        for i in 1..=5 {
+            let mutations = vec![AtomicMutation {
+                capability: capability.to_string(),
+                key: format!("rec-{}", i),
+                value: Some(serde_json::json!({"id": i, "name": format!("Record {}", i)})),
+            }];
+
+            db.apply_atomic_transaction(&format!("txn-{}", i), None, &[], &mutations, None).unwrap();
+            let cardinality = db.collection_cardinality(capability).unwrap();
+            assert_eq!(cardinality, i as u64, "Cardinality should be {} after {} inserts", i, i);
+        }
+
+        let _ = fs::remove_file(path);
+    }
+
+    #[test]
+    fn maintained_cardinality_delete_decrements() {
+        let path = temp_file();
+        let db = open(&path).unwrap();
+        let capability = "test_collection";
+
+        let insert_mutations = vec![
+            AtomicMutation {
+                capability: capability.to_string(),
+                key: "rec-1".to_string(),
+                value: Some(serde_json::json!({"id": 1})),
+            },
+            AtomicMutation {
+                capability: capability.to_string(),
+                key: "rec-2".to_string(),
+                value: Some(serde_json::json!({"id": 2})),
+            },
+            AtomicMutation {
+                capability: capability.to_string(),
+                key: "rec-3".to_string(),
+                value: Some(serde_json::json!({"id": 3})),
+            },
+        ];
+
+        db.apply_atomic_transaction("txn-insert", None, &[], &insert_mutations, None).unwrap();
+        assert_eq!(db.collection_cardinality(capability).unwrap(), 3);
+
+        let delete_mutations = vec![
+            AtomicMutation {
+                capability: capability.to_string(),
+                key: "rec-1".to_string(),
+                value: None,
+            },
+        ];
+
+        db.apply_atomic_transaction("txn-delete", None, &[], &delete_mutations, None).unwrap();
+        assert_eq!(db.collection_cardinality(capability).unwrap(), 2, "Cardinality should be 2 after deleting 1 record");
+
+        let _ = fs::remove_file(path);
+    }
+
+    #[test]
+    fn maintained_cardinality_update_does_not_change_count() {
+        let path = temp_file();
+        let db = open(&path).unwrap();
+        let capability = "test_collection";
+
+        let insert_mutations = vec![AtomicMutation {
+            capability: capability.to_string(),
+            key: "rec-1".to_string(),
+            value: Some(serde_json::json!({"id": 1, "status": "active"})),
+        }];
+
+        db.apply_atomic_transaction("txn-insert", None, &[], &insert_mutations, None).unwrap();
+        assert_eq!(db.collection_cardinality(capability).unwrap(), 1);
+
+        let update_mutations = vec![AtomicMutation {
+            capability: capability.to_string(),
+            key: "rec-1".to_string(),
+            value: Some(serde_json::json!({"id": 1, "status": "inactive"})),
+        }];
+
+        db.apply_atomic_transaction("txn-update", None, &[], &update_mutations, None).unwrap();
+        assert_eq!(db.collection_cardinality(capability).unwrap(), 1, "Cardinality should remain 1 after update");
+
+        let _ = fs::remove_file(path);
+    }
+
+    #[test]
+    fn maintained_cardinality_survives_restart() {
+        let path = temp_file();
+
+        {
+            let db = open(&path).unwrap();
+            let capability = "test_collection";
+
+            let mutations = vec![
+                AtomicMutation {
+                    capability: capability.to_string(),
+                    key: "rec-1".to_string(),
+                    value: Some(serde_json::json!({"id": 1})),
+                },
+                AtomicMutation {
+                    capability: capability.to_string(),
+                    key: "rec-2".to_string(),
+                    value: Some(serde_json::json!({"id": 2})),
+                },
+            ];
+
+            db.apply_atomic_transaction("txn-1", None, &[], &mutations, None).unwrap();
+            assert_eq!(db.collection_cardinality(capability).unwrap(), 2);
+        }
+
+        let reopened = open(&path).unwrap();
+        let capability = "test_collection";
+        let cardinality = reopened.collection_cardinality(capability).unwrap();
+        assert_eq!(cardinality, 2, "Cardinality should survive restart and be recomputed from rows");
+
+        let _ = fs::remove_file(path);
+    }
+
+    #[test]
+    fn maintained_cardinality_empty_collection() {
+        let path = temp_file();
+        let db = open(&path).unwrap();
+        let capability = "empty_collection";
+
+        let cardinality = db.collection_cardinality(capability).unwrap();
+        assert_eq!(cardinality, 0, "Empty collection should have cardinality 0");
+
+        let _ = fs::remove_file(path);
+    }
+
+    #[test]
+    fn maintained_cardinality_large_collection() {
+        let path = temp_file();
+        let db = open(&path).unwrap();
+        let capability = "large_collection";
+
+        let mut mutations = Vec::new();
+        for i in 1..=100 {
+            mutations.push(AtomicMutation {
+                capability: capability.to_string(),
+                key: format!("rec-{}", i),
+                value: Some(serde_json::json!({"id": i, "name": format!("Record {}", i)})),
+            });
+        }
+
+        db.apply_atomic_transaction("txn-large", None, &[], &mutations, None).unwrap();
+        let cardinality = db.collection_cardinality(capability).unwrap();
+        assert_eq!(cardinality, 100, "Large collection with 100 records should have cardinality 100");
+
+        let _ = fs::remove_file(path);
+    }
+
+    #[test]
+    fn maintained_cardinality_multiple_collections_isolated() {
+        let path = temp_file();
+        let db = open(&path).unwrap();
+
+        let col1 = "collection_1";
+        let col2 = "collection_2";
+
+        let mutations1 = vec![
+            AtomicMutation {
+                capability: col1.to_string(),
+                key: "rec-1".to_string(),
+                value: Some(serde_json::json!({"id": 1})),
+            },
+            AtomicMutation {
+                capability: col1.to_string(),
+                key: "rec-2".to_string(),
+                value: Some(serde_json::json!({"id": 2})),
+            },
+        ];
+
+        db.apply_atomic_transaction("txn-col1", None, &[], &mutations1, None).unwrap();
+
+        let mutations2 = vec![
+            AtomicMutation {
+                capability: col2.to_string(),
+                key: "rec-1".to_string(),
+                value: Some(serde_json::json!({"id": 1})),
+            },
+            AtomicMutation {
+                capability: col2.to_string(),
+                key: "rec-2".to_string(),
+                value: Some(serde_json::json!({"id": 2})),
+            },
+            AtomicMutation {
+                capability: col2.to_string(),
+                key: "rec-3".to_string(),
+                value: Some(serde_json::json!({"id": 3})),
+            },
+        ];
+
+        db.apply_atomic_transaction("txn-col2", None, &[], &mutations2, None).unwrap();
+
+        assert_eq!(db.collection_cardinality(col1).unwrap(), 2);
+        assert_eq!(db.collection_cardinality(col2).unwrap(), 3);
+
+        let _ = fs::remove_file(path);
+    }
+}