feltdb/

lib.rs

//! # FeltDB
//!
//! A durable, embedded state store. Records live under a *capability* (the part of a key before
//! the first `:`, so `"orders:o-1"` is record `o-1` of capability `orders`). Every write goes
//! through a durable log; several records can be changed in one atomic transaction; an update can
//! be made conditional on the version you read; and a transaction can carry an identity so that a
//! retry after an uncertain outcome is recognized instead of applied twice.
//!
//! ```
//! use feltdb::{AtomicMutation, FeltDb, FlowError, PayloadBinding, RecordPrecondition};
//! use serde_json::{json, Value};
//!
//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
//! let dir = tempfile::tempdir()?;
//! let path = dir.path().join("app.db");
//! let db = FeltDb::open(&path)?;
//!
//! // Create a record only if it is absent: a second create is refused, and refused in a way a
//! // caller can branch on.
//! db.insert_if_absent("orders:o-1", json!({ "status": "pending" }))?;
//! assert!(matches!(
//!     db.insert_if_absent("orders:o-1", json!({})),
//!     Err(FlowError::PreconditionFailed(_))
//! ));
//!
//! // Change several records atomically, and name the transaction so a retry is safe. The payload
//! // hash is yours to compute: FeltDB stores it and compares it for equality.
//! let ship = |hash: &str| {
//!     db.apply_atomic_transaction_content_addressed(
//!         "ship-o-1",
//!         Some(hash),
//!         None,
//!         &[],
//!         &[
//!             AtomicMutation {
//!                 capability: "orders".into(),
//!                 key: "orders:o-1".into(),
//!                 value: Some(json!({ "status": "shipped" })),
//!             },
//!             AtomicMutation {
//!                 capability: "audit".into(),
//!                 key: "audit:a-1".into(),
//!                 value: Some(json!({ "order": "o-1", "event": "shipped" })),
//!             },
//!         ],
//!         None,
//!     )
//! };
//! let first = ship("sha256:payload-v1")?;
//! assert!(!first.duplicate);
//!
//! // The same request again is recognized as the original, not applied a second time.
//! let retry = ship("sha256:payload-v1")?;
//! assert!(retry.duplicate);
//! assert_eq!(retry.payload_binding, Some(PayloadBinding::Verified));
//! assert_eq!(retry.commit_revision, first.commit_revision);
//!
//! // The same id with a different payload is refused, with a typed error. Nothing is written.
//! assert!(matches!(
//!     ship("sha256:payload-v2"),
//!     Err(FlowError::TransactionIdPayloadMismatch { .. })
//! ));
//!
//! // Close and reopen: what was acknowledged is there.
//! drop(db);
//! let db = FeltDb::open(&path)?;
//! assert_eq!(db.get::<Value>("orders:o-1")?, Some(json!({ "status": "shipped" })));
//! # let _ = RecordPrecondition::default();
//! # Ok(())
//! # }
//! ```
//!
//! ## What is supported
//!
//! Only the items in this table are covered by the compatibility policy
//! ([`docs/reference/feltdb-rust-api.md`] in the repository). While the version is `0.x`, a breaking
//! change to them is a minor-version bump and is recorded in the changelog; everything else may
//! change in any release.
//!
//! | To | Use |
//! | --- | --- |
//! | open, recover, reopen | [`FeltDb::open`], [`FeltDb::log_recovery`], [`FeltDb::health`] |
//! | read | [`FeltDb::get`], [`FeltDb::query`] |
//! | write unconditionally | [`FeltDb::insert`], [`FeltDb::update`], [`FeltDb::delete`] (all three are plain writes: see below) |
//! | create only if absent | [`FeltDb::insert_if_absent`] |
//! | update only if unchanged | [`FeltDb::compare_and_set_json`] → [`JsonCasResult`] |
//! | change several records atomically | [`FeltDb::apply_atomic_transaction`], [`FeltDb::apply_atomic_transaction_guarded`] with [`AtomicMutation`] and [`RecordPrecondition`] → [`AtomicCommit`] |
//! | make a retry safe | [`FeltDb::apply_atomic_transaction_content_addressed`], [`FeltDb::has_applied_transaction`], [`FeltDb::applied_transaction_payload_hash`], [`PayloadBinding`] |
//! | tell failures apart | [`FlowError`] and its variants, [`PreconditionFailure`] |
//! | a durable authority for several processes | the [`authority`] module (Unix) |
//!
//! **Behavior to know before relying on it.**
//! `insert`, `update` and `delete` are unconditional: `insert` replaces an existing record, `update`
//! of a missing key *creates* it, and `delete` of a missing key succeeds. A fenced write
//! ([`FeltDb::compare_and_set_json`], a [`RecordPrecondition`] with `expected_version`) treats a record
//! that has never been through one as version 1, and a record's `__version` becomes visible in its JSON
//! after its first fenced write. A transaction refused for a failed precondition writes nothing.
//! A transaction id committed *without* a payload hash can be retried (it is a duplicate, with no
//! [`PayloadBinding`]), but retrying it *with* a hash is refused, because there is nothing to verify against.
//!
//! ## Durability
//!
//! An acknowledged write survives the process being killed. Whether it survives the machine losing
//! power depends on the operating system and drive honouring a flush, and is **not** established.
//! A log ending in an incomplete append is recovered by discarding that append, which was never
//! acknowledged: [`FeltDb::log_recovery`] says so. A corrupt log, or one in a format this build does
//! not understand, refuses to open and is left as found.
//!
//! ## Stability tiers
//!
//! * **Supported**: the table above.
//! * **Experimental**: [`agent_state`], [`agent_transition_contract`], the deterministic-contract
//!   adapters, [`semantic_decision`] and [`semantic_query`]. Public so they can be used, but they
//!   may change shape before they are stabilized.
//! * **Not yet classified**: the other public modules. They are public today and carry no promise;
//!   each is listed with the decision still needed in the repository's Rust API audit.
//! * **Internals**: implementation, fault-injection and diagnostic modules are private unless the
//!   `unstable-internals` feature is enabled, and nothing behind that feature is covered by any promise.
//!
//! `FlowError` is `#[non_exhaustive]`: match on its variants, always with a catch-all arm, and never
//! on message text.
//!
//! [`docs/reference/feltdb-rust-api.md`]: https://github.com/rkendel1/flow_db/blob/main/docs/reference/feltdb-rust-api.md

macro_rules! unstable_internal_modules {
    ($($name:ident),* $(,)?) => {
        $(
            #[cfg(feature = "unstable-internals")]
            pub mod $name;
            #[cfg(not(feature = "unstable-internals"))]
            #[allow(dead_code, unused_imports)]
            mod $name;
        )*
    };
}

unstable_internal_modules! {
    adversarial_transport,
    concurrency_fuzzing,
    crash_injection,
    replay_fuzzing,
    permutation_scheduler,
    persistence_reality,
    in_process_transport,
    query_execution_diagnostics,
    workload_diagnostics,
    cardinality_endpoint,
}

#[cfg(test)]
mod acceptance_tests;
mod acquisition;
pub mod admission;
#[cfg(test)]
mod admission_contract_tests;
pub mod analytics;
pub mod application;
pub mod application_runtime;
pub mod lifecycle_store;
#[cfg(not(target_arch = "wasm32"))]
pub mod authority;
pub mod authority_failover;
pub mod authorization;
#[cfg(test)]
mod authorization_security_tests;
pub mod capabilities;
mod capability;
mod cardinality_diagnostics;
#[cfg(test)]
mod causal_backlog_bound;
pub mod causal_dependency_barrier;
#[cfg(test)]
mod causal_dependency_barrier_phase_7_1;
pub mod consistency_contract;
mod content_distribution;
pub mod convergence;
pub mod crash_atomic_boundary;
#[cfg(test)]
mod crash_recovery_tests;
mod cron;
#[cfg(test)]
mod dedup_bound_investigation;
pub mod distributed_indexing;
#[cfg(test)]
mod distributed_tests;
pub mod distributed_transactions;
pub mod durability_guarantees;
pub mod durable_dedup_set;
#[cfg(test)]
mod durable_operation_identity;
pub mod durable_operation_log;
pub mod durable_sync;
pub mod equality_index;
mod execution;
pub mod indexing;
#[cfg(test)]
mod managed_cas_tests;
mod materialization;
pub mod metrics;
pub mod multi_node_convergence;
pub mod multi_operation_transaction;
pub mod observability;
mod operation;
pub mod operation_algebra;
pub mod operation_log;
#[cfg(test)]
mod p1_application_atomicity;
#[cfg(test)]
mod p1_atomicity_acceptance;
pub mod partition_reconciliation;
mod peer_registry;
#[cfg(test)]
mod phase1b_acceptance;
#[cfg(test)]
mod phase1c1_acceptance;
#[cfg(test)]
mod phase1c2_acceptance;
#[cfg(test)]
mod phase1c3_acceptance;
#[cfg(test)]
mod phase1c_atomicity_proof;
#[cfg(test)]
mod phase5_integration;
#[cfg(test)]
mod phase5_scenarios;
#[cfg(test)]
mod phase6_adversarial_scenarios;
#[cfg(test)]
mod phase6_convergence_validator;
#[cfg(test)]
mod phase6_persistence;
#[cfg(test)]
#[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;
pub mod policy_evaluation;
pub mod production_api;
mod provenance;
pub mod query_performance;
#[cfg(test)]
mod read_basis;
mod references;
pub mod replica_acknowledgements;
pub mod replica_membership;
pub mod replication_manager;
pub mod replication_protocol;
mod routing;
pub mod semantic_decision;
pub mod semantic_query;
pub mod sharding;
pub mod agent_state;
pub mod agent_transition_contract;
pub mod state_conflict_contract;
pub mod state_contract;
pub mod state_diff_contract;
pub mod state_facade;
pub mod state_hash;
pub mod state_model;
pub mod state_transition_store;
pub mod state_trigger;
mod storage;
pub mod submission;
mod sync;
pub mod sync_contract;
#[cfg(not(target_arch = "wasm32"))]
pub mod tcp_transport;
pub mod transaction_api;
#[cfg(test)]
mod transaction_invariants;
#[cfg(test)]
mod transaction_preconditions;
pub mod transactions;
mod trigger;
pub mod trigger_contract;
pub mod versioned_object_substrate;
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 admission::{ProductionRetryPolicy, RejectionReason, SubmissionOutcome};
#[cfg(feature = "unstable-internals")]
pub use adversarial_transport::{
    AdversarialTransport, ConnectionId, ConnectivityMatrix, FaultSeed, InMemoryTransport,
    LinkState, MessageId, NetworkEvent, NetworkSchedule, NodeId, ReplicationTransport,
};
pub use analytics::{
    AutoTuner, IndexAnalytics, IndexMetrics, PerformanceReport, QueryTrace, TuningRecommendation,
};
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 causal_dependency_barrier::{
    ApplyResult, CausalDependencyBarrier, OperationState, PendingOperation, ReceiveResult,
    StateCounters,
};
pub use consistency_contract::{
    CommutativeVerificationResult, ConsensusEnforcementResult, ConsensusRequirementChecker,
    ConsistencyContractEnforcer, DeterministicMergeVerificationResult,
    NoDowngradeVerificationResult, OperationApplication,
};
pub use content_distribution::{
    CapabilityLocationRegistry, ContentAcquisitionManager, ContentAddressableStore,
    DistributedReferenceResolver, ProjectionDistribution,
};
pub use convergence::{
    CausalHistory, ConflictResolution, ConflictResolutionStrategy, MergeResult, StateVersion,
    VectorClock,
};
pub use crash_atomic_boundary::{
    CrashAtomicExecutor, CrashBoundaryPoint, CrashRecoveryState, InvariantCheckResult,
    RecoveryDecision,
};
pub use cron::{CronSchedule, CronScheduler};
pub use distributed_indexing::{
    ConsistencyLevel, ConsistencyProtocol, DistributedIndexManager, DistributedSyncStatus,
    IndexOperation, IndexReplicationState, IndexSyncMessage, IndexVectorClock, RemoteIndexMetadata,
    RemoteIndexState, ReplicationStatus, VersionConflict,
};
pub use distributed_transactions::{
    DistributedTransactionExecutor, EnvelopeId, ReplicaState, ReplicationMessage,
    TransactionEnvelope,
};
pub use equality_index::{EqualityIndex, EqualityIndexStats, IndexKey};
pub use execution::{Execution, ExecutionQueue, ExecutionStatus, RetryPolicy};
pub use indexing::{IndexConfig, IndexManager, IndexStats, IndexType};
pub use materialization::{MaterializationHandler, ReactiveCollectionIntegration};
pub use multi_node_convergence::{
    ConvergenceAggregation, ConvergenceResult, MultiNodeConvergenceSimulator, NodeExecutionResult,
};
pub use operation::{MutationOrder, Operation, OperationType, DEFAULT_MUTATION_ORDER};
pub use operation_algebra::{
    ConflictType, ConvergenceSemantic, OperationAlgebra, OperationAlgebraRegistry,
};
pub use operation_log::{MemoryOperationLog, OperationLogEntry};
pub use partition_reconciliation::{
    DeterminismCheckResult, PartitionDeterminismChecker, PartitionTrace, PartitionedReplica,
    ReconciliationResult, ReplicaPartition,
};
pub use peer_registry::PeerRegistry;
#[cfg(feature = "unstable-internals")]
pub use permutation_scheduler::{OperationSchedule, PermutationScheduler, ScheduleStrategy};
#[cfg(feature = "unstable-internals")]
pub use persistence_reality::{
    CorruptionDetectionResult, DurablePersistenceLayer, FsyncDurabilityResult,
    PersistenceContractVerifier, PersistenceCrashPoint, RecoveryResult, WALEntry, WriteResult,
};
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 semantic_decision::{
    authorize_context, configured_decision_runtime, decide_record, decision_cache_key,
    deterministic_request_key, reuse_record_judgment,
    execute_decision_batch, execute_decision_transport, execute_inline_decision_transport, jev,
    run_choice_diagnostics, run_decision_benchmark, validate_decision_definition,
    validate_decision_result, BinaryDecisionResult, ChoiceDecisionResult, ChoiceDiagnosticsReport,
    ChoiceExpansionObservation, ChoicePermutationObservation, DecisionAuthorizationConfig,
    DecisionAuthorizationDecision, DecisionAuthorizationGate, DecisionBatch, DecisionBatchDecision,
    DecisionBatchEvaluation, DecisionBenchmarkCase, DecisionBenchmarkReport, DecisionContextPacket,
    DecisionDefinition, DecisionError, DecisionEvaluation, DecisionEvidence, DecisionEvidenceField,
    DecisionExecutionMethod, DecisionJudgmentRecord, DecisionKind, DecisionOptions,
    DecisionPrincipal, DecisionProvenance, DecisionRecordRef, DecisionRequest, DecisionResult,
    DecisionRuntime, DecisionRuntimeCapabilities, DecisionRuntimeMetadata, DecisionStateReference,
    DecisionStatus, DecisionTransportAuthorization, DecisionTransportExecutionRequest,
    DecisionTransportExecutionResponse, DecisionTransportRuntime, DeterministicDecisionRuntime,
    ScoreDecisionResult, WeightedOption, DEFAULT_DECISION_COLLECTION,
};
pub use semantic_query::{
    compose_semantic_page, semantic_clause_hash, semantic_definition_hash,
    validate_semantic_clause, SemanticAnnotation, SemanticCandidate, SemanticOrderDirection,
    SemanticPage, SemanticQueryClause, SemanticQueryError, SemanticQueryFilter,
    SemanticQueryMode, SemanticQueryOrder, SemanticStageSummary, SemanticUnevaluated,
    SemanticUnevaluatedReason, MAX_SEMANTIC_CANDIDATES,
};
pub use sharding::{
    HotspotAlert, RebalanceOperation, ShardDistributionSummary, ShardId, ShardKey, ShardManager,
    ShardMetrics, ShardRange, ShardingStrategy,
};
pub use state_conflict_contract::{
    classify_states, StateConflictInput, StateConflictOutput, STATE_CONFLICT_CONTRACT_ID,
    STATE_CONFLICT_CONTRACT_VERSION,
};
pub use state_diff_contract::{
    diff_states, StateDiffInput, StateDiffOutput, STATE_DIFF_CONTRACT_ID,
    STATE_DIFF_CONTRACT_VERSION,
};
pub use state_facade::FeltDBStateSystem;
pub use state_hash::{CanonicalState, StateHash};
pub use state_model::{
    apply_reconciliation_plan, path_relation, paths_overlap, reconcile, resolve_path, ChangeKind,
    ConflictClass, ConflictClassification, GarbageCollectionError, GarbageCollectionReport,
    MaterializationError, MaterializationProjection, PathComponent, PathConflict, PathRelation,
    ReconciliationPlan, RefError, Relationship, SemanticChange, SemanticDiff, StateId, StateObject,
    StateReconciliationResult, StateRef, StateRevision, StateStore, StateTopology,
    STATE_MODEL_VERSION,
};
pub use state_transition_store::{MemoryStateTransitionStore, StateTransitionRecord};
pub use state_trigger::{
    StateTrigger, StateTriggerChangeKind, StateTriggerError, StateTriggerPredicate,
    StateTriggerStore, TriggeredWorkload,
};
pub use storage::{CheckpointData, FileStorage, MemoryStorage, Storage};
pub use submission::{SubmissionManager, SubmissionMetrics};
pub use sync::{ChangeLog, Conflict, ConflictDetector, PeerState, SyncMessage, SyncState};
pub use transaction_api::{TransactionManager, TxError, TxResult};
pub use transactions::{
    CommitId, CommitValidator, ConsistencyContract, OperationCommand, OperationId, StateDependency,
    StateTransition, TransactionExecutor, TransitionResult,
};
pub use trigger::{Trigger, TriggerFilter, TriggerRegistry};
pub use trigger_contract::{
    canonical_input_bytes, canonical_output_bytes, evaluate_canonical, evaluate_trigger,
    ContractChange, ContractChangeKind, ContractErrorBody, ContractErrorCode, ContractPredicate,
    ContractRuntime, ContractTrigger, MatchOutcome, MatchReason, TriggerMatchInput,
    TriggerMatchOutput, TRIGGER_MATCH_CONTRACT_ID, TRIGGER_MATCH_CONTRACT_VERSION,
};
pub use versioned_object_substrate::{
    DurableObjectStore, DurableRef, LocalObjectStore, Reachability, S3CompatibleBucket,
    S3CompatibleObjectStore, SubstrateError, VersionedObjectSubstrate,
};
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 crate::state_contract::AuthorizationContext;
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::{BTreeMap, BTreeSet, HashMap, HashSet, VecDeque};
use std::fmt::{Display, Formatter};
use std::fs::{self, File, OpenOptions};
use std::hash::{Hash, Hasher};
use std::io::{BufRead, BufReader, Write};
use std::ops::Bound::{Excluded, Unbounded};
use std::path::{Path, PathBuf};
use std::sync::{Arc, Mutex, OnceLock, Weak};
use std::time::{SystemTime, UNIX_EPOCH};
use tokio::sync::broadcast;

pub type Result<T> = std::result::Result<T, FlowError>;

/// How [`FeltDb::select_page`] found the rows of a page.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum PageAccess {
    /// Seeked to the cursor in record-key order and stopped after the page.
    KeyRange,
    /// Read the smallest applicable equality-index bucket.
    EqualityIndex,
    /// Examined every record of the collection.
    Scan,
}

/// One bounded page and what it cost.
#[derive(Debug, Clone)]
pub struct SelectedPage {
    /// At most `limit` rows, in the caller's order.
    pub rows: Vec<StoredRow>,
    /// Whether at least one more matching row follows the page.
    pub has_more: bool,
    /// Records the execution looked at.
    pub examined: usize,
    /// Of those, how many matched the predicate (before the cursor bound).
    pub matched_examined: usize,
    pub access: PageAccess,
}

impl SelectedPage {
    fn empty(access: PageAccess) -> Self {
        SelectedPage { rows: Vec::new(), has_more: false, examined: 0, matched_examined: 0, access }
    }
}

/// Why an operation failed.
///
/// Branch on the variant, never on message text. The enum is `#[non_exhaustive]`: a later release
/// may add variants, so a `match` needs a catch-all arm. `CapabilityError` carries a human-readable
/// message, some of which begin with an upper-case code (`INVALID_READ_SET:`, `EMPTY_PRECONDITION:`);
/// those prefixes are **not** a supported way to tell failures apart and may change.
#[derive(Debug)]
#[non_exhaustive]
pub enum FlowError {
    Io(std::io::Error),
    Serde(serde_json::Error),
    CorruptLogLine(Box<LogCorruption>),
    CapabilityError(String),
    /// A transaction precondition did not hold. Nothing was written.
    ///
    /// Separate from `CapabilityError` because a conflict is an expected
    /// outcome of a race and a caller is meant to branch on it, while a
    /// capability error is not.
    PreconditionFailed(Box<PreconditionFailure>),
    /// A transaction id was already committed with a **different** payload. Nothing was written, and
    /// the id still names the original transaction.
    ///
    /// Returned when a payload hash is supplied for an id that was committed with another one, and
    /// also when an id that was committed *without* a hash is retried *with* one, since there is
    /// nothing recorded to verify against. Retrying with the same id cannot succeed: use a new id
    /// for a new transaction, or resend the original payload to confirm the original.
    TransactionIdPayloadMismatch {
        transaction_id: String,
    },
    /// The transaction was based on a revision which is no longer current.
    RevisionConflict {
        expected: u64,
        actual: u64,
    },
    /// A backup artifact was rejected. Nothing was restored.
    BackupRejected(Box<BackupProblem>),
    /// The durable database is in a format this build does not understand.
    ///
    /// Returned by [`FeltDb::open`] **before any record is interpreted**, and
    /// before anything is written. A database that returns this error is
    /// untouched.
    IncompatibleFormat(Box<FormatIncompatibility>),
    /// A write could not be made durable, or was refused because an earlier one
    /// left the durable log in a state this process can no longer vouch for.
    ///
    /// [`DurabilityFailure::committed`] says what is known about the write:
    /// `Some(false)` means nothing of it is durable or visible, `None` means the
    /// outcome is unknown until the database is reopened.
    Durability(Box<DurabilityFailure>),
}

/// Why a write did not become durable.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
#[non_exhaustive]
pub enum DurabilityFailureKind {
    /// The volume or the process's file-size or quota limit refused the bytes
    /// (`ENOSPC`, `EFBIG`, `EDQUOT`). Rolled back; nothing was committed.
    StorageFull,
    /// Writing the record failed for another I/O reason. Rolled back.
    WriteFailed,
    /// The record was written but the stable-storage barrier failed. Rolled
    /// back: the bytes were removed and the removal itself was made durable.
    SyncFailed,
    /// The write failed **and** removing its bytes failed. The record may or
    /// may not be in the durable log; reopening the database decides. The
    /// database refuses further writes until it is reopened.
    Indeterminate,
    /// Refused before anything was written: an earlier write left the log
    /// indeterminate, and this process stopped writing. Reopen the database.
    RecoveryRequired,
}

impl DurabilityFailureKind {
    /// The stable code every surface (Rust, HTTP, TypeScript) reports.
    pub fn code(self) -> &'static str {
        match self {
            DurabilityFailureKind::StorageFull => "STORAGE_FULL",
            DurabilityFailureKind::WriteFailed => "STORAGE_WRITE_FAILED",
            DurabilityFailureKind::SyncFailed => "STORAGE_SYNC_FAILED",
            DurabilityFailureKind::Indeterminate => "DURABILITY_FAILURE",
            DurabilityFailureKind::RecoveryRequired => "RECOVERY_REQUIRED",
        }
    }
}

/// A write that did not become durable, and what is known about its outcome.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct DurabilityFailure {
    pub kind: DurabilityFailureKind,
    /// `Some(false)`: not committed, not visible, safe to retry as a new write.
    /// `None`: unknown until reopen; retry only with the same transaction id.
    pub committed: Option<bool>,
    /// The operating-system error, for an operator. Not for branching.
    pub detail: String,
}

impl DurabilityFailure {
    pub fn code(&self) -> &'static str {
        self.kind.code()
    }
}

impl Display for DurabilityFailure {
    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
        let outcome = match self.committed {
            Some(false) => "nothing was committed",
            Some(true) => "the write was committed",
            None => "whether the write was committed is unknown until the database is reopened",
        };
        write!(f, "{}: {}; {outcome}", self.code(), self.detail)
    }
}

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(corruption) => write!(f, "CORRUPT_DURABLE_LOG: {corruption}"),
            FlowError::CapabilityError(msg) => write!(f, "capability error: {msg}"),
            FlowError::PreconditionFailed(failure) => write!(f, "PRECONDITION_FAILED: {failure}"),
            FlowError::TransactionIdPayloadMismatch { transaction_id } => write!(
                f,
                "IDEMPOTENCY_CONFLICT: transaction {transaction_id} was already committed with a different payload"
            ),
            FlowError::RevisionConflict { expected, actual } => write!(
                f,
                "REVISION_CONFLICT: expected authority revision {expected}, current revision is {actual}"
            ),
            FlowError::IncompatibleFormat(incompatibility) => {
                write!(f, "INCOMPATIBLE_DURABLE_FORMAT: {incompatibility}")
            }
            FlowError::BackupRejected(problem) => write!(f, "BACKUP_REJECTED: {problem}"),
            FlowError::Durability(failure) => write!(f, "{failure}"),
        }
    }
}

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>,
    _ownership: Arc<File>,
    /// `Inner::history`, readable without the state lock (which a compaction
    /// holds while it rewrites the log), so every response can name it. Only
    /// written, under the state lock, where `Inner::history` changes.
    history: Arc<std::sync::RwLock<VersionHistory>>,
}

struct OpenDatabase {
    inner: Weak<Mutex<Inner>>,
    event_tx: broadcast::Sender<ChangeEvent>,
    ownership: Weak<File>,
    history: Weak<std::sync::RwLock<VersionHistory>>,
}

static OPEN_DATABASES: OnceLock<Mutex<HashMap<PathBuf, OpenDatabase>>> = OnceLock::new();

#[derive(Default)]
#[allow(dead_code)] // Reserved runtime subsystems are initialized before their public APIs land.
struct Inner {
    /// The history this database issues versions in; persisted in the sync
    /// metadata, set at creation, by a snapshot install and by a restore.
    history: VersionHistory,
    path: PathBuf,
    rows: HashMap<String, BTreeMap<String, StoredRow>>,
    key_counters: HashMap<String, u64>,
    query_count_by_type: HashMap<String, usize>,
    adaptive_indexes: HashSet<String>,
    instance_id: String,
    sequence: u64,
    /// Monotonic, authority-assigned commit order. Unlike `sequence`, one
    /// transaction advances this exactly once regardless of its mutation count.
    authority_revision: 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>,
    transaction_payload_hashes: HashMap<String, String>,
    transaction_revisions: HashMap<String, (u64, u64)>,
    /// Recent commits, and who asked for them.
    ///
    /// Every transaction already records its actor: the audit document written
    /// into the durable log carries `subject`, tenant, application and
    /// revision. Until this existed that document was written and never read
    /// back — replay parsed the record and discarded the audit — so the
    /// database could say *what* changed and never *who changed it*.
    ///
    /// Bounded on purpose. This answers "who did this, recently", which is the
    /// question a human asks while operating a running system; it is not an
    /// audit archive, and the durable log remains the record of what happened.
    /// Keeping it bounded is what makes it safe to maintain on the commit path.
    transaction_attributions: VecDeque<TransactionAttribution>,
    /// Complete committed transaction order, rebuilt exclusively from the
    /// durable transaction log. Unlike the bounded operator window above this
    /// is the canonical replay/provenance index.
    transaction_history: Vec<TransactionAttribution>,
    collection_cardinality: HashMap<String, u64>,
    /// Derived equality index over `rows`. Never durable, never replicated, and
    /// never consulted for anything but candidate selection: it is maintained
    /// inside the same state mutation boundary as `rows` and rebuilt from
    /// `rows` after recovery.
    equality_index: EqualityIndex,
    /// What replaying the durable log had to do to succeed.
    ///
    /// Recorded rather than logged, so an operator can ask after the fact
    /// whether this database opened cleanly.
    log_recovery: LogRecovery,
    /// The durable format this database was accepted as, recorded at the open
    /// that accepted it.
    durable_format: DurableFormat,
    /// How far a single-record write is pushed before it returns.
    durability_mode: DurabilityMode,
    /// Writes since the last stable-storage barrier, for grouped durability.
    writes_since_barrier: u32,
    /// Set when a failed write could not be rolled back. From then on this
    /// process cannot say what the durable log holds, so it refuses writes
    /// until the database is reopened and replay decides. Never cleared in
    /// place.
    write_fault: Option<String>,
    /// Size of the durable log right after its last rewrite (0 until one
    /// happens in this process). A standalone store rewrites only once the log
    /// has doubled since, which bounds disk to about twice the compacted size
    /// and keeps rewrite cost proportional to what was appended.
    log_bytes_after_rewrite: u64,
    /// When a policy-driven compaction should rewrite the durable log.
    compaction_policy: CompactionPolicy,
    /// Operations pruned since the last log rewrite.
    pruned_since_rewrite: usize,
    /// Each resource's newest revision, as `(id, sequence)`.
    ///
    /// Derived from the `state` rows exactly like `equality_index` is derived
    /// from `rows`: never durable, rebuilt after recovery. It exists so that
    /// minting a revision does not have to scan a resource's history to find
    /// the parent it descends from.
    revision_heads: HashMap<String, (state_model::StateId, u64)>,
    /// Each collection's write version: the value of `collection_clock` when a
    /// record of it was last written, replaced or removed.
    ///
    /// Derived, in memory only, never replicated; rebuilt by replay because
    /// replay writes through the same mutation boundary. It answers one
    /// question inside the commit lock in O(1): has anything in this
    /// collection changed since a decision read it? Values never repeat, so a
    /// changed-and-changed-back collection never looks unchanged.
    collection_versions: HashMap<String, u64>,
    collection_clock: u64,
}

/// The state lock, held with its wait and hold time attributable.
///
/// FeltDB serializes every read and every write behind one mutex, so "how long
/// did an operation take" and "how long did it make everything else wait" are
/// different questions. PR34 showed the second one mattered: a query holding the
/// lock while it cloned a collection inflated the cost of unrelated writes.
///
/// This guard answers both. It records the time spent *waiting* to acquire —
/// which is pure contention, the one span where no work happens at all — and the
/// time spent *holding*, which bounds how long anything else can be forced to
/// wait. Both are off unless `FELTDB_WORKLOAD_DIAGNOSTICS=1`, where acquisition
/// costs one relaxed atomic load and no clock read.
///
/// It dereferences to [`Inner`], so every existing use site reads unchanged.
struct StateGuard<'a> {
    inner: std::sync::MutexGuard<'a, Inner>,
    held_since: Option<std::time::Instant>,
}

impl std::ops::Deref for StateGuard<'_> {
    type Target = Inner;
    fn deref(&self) -> &Inner {
        &self.inner
    }
}

impl std::ops::DerefMut for StateGuard<'_> {
    fn deref_mut(&mut self) -> &mut Inner {
        &mut self.inner
    }
}

impl Drop for StateGuard<'_> {
    fn drop(&mut self) {
        if let Some(since) = self.held_since {
            workload_diagnostics::record(
                workload_diagnostics::Phase::StateLockHold,
                since.elapsed().as_nanos().min(u64::MAX as u128) as u64,
            );
        }
    }
}

/// The single state mutation boundary for authoritative records.
///
/// Every path that changes a record — insert, update, delete, CAS, transaction
/// commit, replicated operation apply, log replay, snapshot install — goes
/// through these three methods, and they change the record map and the derived
/// equality index together while the caller still holds the state lock. That is
/// the whole atomicity argument: there is no window in which a committed record
/// exists without its index entries, or an index entry survives its record,
/// because no code path can write one without the other.
///
/// The index is deliberately maintained here rather than through an independent
/// index API. An independent API would have to be called, correctly, by nine
/// separate mutation paths; a missed call would be a silent divergence that only
/// a query would reveal. Routing every write through one boundary makes the
/// omission impossible to write in the first place.
impl Inner {
    /// Write one record, replacing any record already at its key.
    ///
    /// Returns `true` when this created a record rather than replacing one, which
    /// is what collection cardinality accounting needs.
    fn put_row(&mut self, row: StoredRow) -> bool {
        let capability = row.capability.clone();
        let key = row.key.clone();
        self.bump_collection_version(&capability);
        let indexed = self.equality_index.indexes_collection(&capability);
        let mutation = workload_diagnostics::span(workload_diagnostics::Phase::RecordMutation);
        let bucket = self.rows.entry(capability.clone()).or_default();
        let previous = bucket.insert(key.clone(), row);
        drop(mutation);
        if previous.is_none() {
            *self
                .collection_cardinality
                .entry(capability.clone())
                .or_default() += 1;
        }
        if !indexed {
            return previous.is_none();
        }
        // From here on the work exists only because an index does. Measuring it
        // apart from the record write is what makes "did index maintenance
        // become a write-side cost?" a question with an answer.
        let _index = workload_diagnostics::span(workload_diagnostics::Phase::IndexMaintenance);
        // Old entries first, then new ones. Doing it in this order means a
        // record whose indexed field did not change is removed from and
        // re-added to the same bucket, which is a no-op rather than a gap.
        if let Some(previous) = &previous {
            self.equality_index
                .remove_record(&capability, &key, &previous.value);
        }
        // Disjoint field borrows: the record map is read while the index is
        // written. Nothing is cloned to maintain the index.
        let Inner {
            rows,
            equality_index,
            ..
        } = self;
        if let Some(current) = rows.get(&capability).and_then(|rows| rows.get(&key)) {
            equality_index.insert_record(&capability, &key, &current.value);
        }
        previous.is_none()
    }

    /// Remove one record. Returns `true` when a record was actually removed.
    fn remove_row(&mut self, capability: &str, key: &str) -> bool {
        let mutation = workload_diagnostics::span(workload_diagnostics::Phase::RecordMutation);
        let Some(removed) = self
            .rows
            .get_mut(capability)
            .and_then(|bucket| bucket.remove(key))
        else {
            return false;
        };
        drop(mutation);
        self.bump_collection_version(capability);
        let count = self
            .collection_cardinality
            .entry(capability.to_string())
            .or_default();
        *count = count.saturating_sub(1);
        let _index = workload_diagnostics::span(workload_diagnostics::Phase::IndexMaintenance);
        self.equality_index
            .remove_record(capability, key, &removed.value);
        true
    }

    /// Advance a collection's write version (see `collection_versions`).
    fn bump_collection_version(&mut self, capability: &str) {
        self.collection_clock += 1;
        self.collection_versions
            .insert(capability.to_string(), self.collection_clock);
    }

    /// Drop all records, as a snapshot install does. The index follows.
    fn clear_rows(&mut self) {
        let cleared: Vec<String> = self.rows.keys().cloned().collect();
        for capability in cleared {
            self.bump_collection_version(&capability);
        }
        self.rows.clear();
        self.collection_cardinality.clear();
        self.equality_index.clear();
    }
}

#[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>,
}

/// What must be true of one record for a transaction to commit.
///
/// Distinct from `AtomicPrecondition`, and deliberately so. That one compares
/// the row's internal operation *sequence*, and `None` on it means "this record
/// must not exist". This one compares the fields a caller can actually read
/// back -- the document's `__version`, its authority epoch, its lease -- which
/// are the same fields single-record CAS compares. Plumbing a caller's
/// `expectedVersion` into the sequence check would have compared a document
/// version against a storage sequence: two different numbers that happen to
/// share a name.
///
/// Every predicate is optional and only a supplied one is checked. That differs
/// from CAS, where an absent `expected_lease_id` asserts the record is *not*
/// leased; here an absent predicate asserts nothing at all. The difference is
/// deliberate -- a transaction precondition is a fence the caller opts into,
/// not a full description of the record -- and it is why the fields are named
/// `expected_*` rather than describing a state.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct RecordPrecondition {
    pub capability: String,
    pub key: String,
    /// The record must not exist. Mutually exclusive with the predicates below.
    #[serde(default)]
    pub require_absent: bool,
    /// The document's `__version`, as `updateIfVersion` compares it.
    #[serde(default)]
    pub expected_version: Option<u64>,
    /// The record's authority epoch, at `/authority/epoch`.
    #[serde(default)]
    pub expected_epoch: Option<u64>,
    /// The id of an unexpired lease held on the record.
    #[serde(default)]
    pub expected_lease_id: Option<String>,
}

impl RecordPrecondition {
    /// True when this precondition asks for nothing, which is a caller error
    /// rather than a satisfied fence: a precondition that constrains nothing
    /// would read as protection and provide none.
    pub fn is_empty(&self) -> bool {
        !self.require_absent
            && self.expected_version.is_none()
            && self.expected_epoch.is_none()
            && self.expected_lease_id.is_none()
    }
}

/// State a decision was read from: records by identity, and equality
/// predicates over a collection (every record of `collection` whose fields
/// equal these values, including records that do not exist yet).
///
/// Generic: it names collections, ids, fields, and values, never what they mean.
#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
pub struct ReadSet {
    #[serde(default)]
    pub records: Vec<ReadRecord>,
    #[serde(default)]
    pub predicates: Vec<ReadPredicate>,
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct ReadRecord {
    pub collection: String,
    pub id: String,
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct ReadPredicate {
    pub collection: String,
    #[serde(rename = "where")]
    pub conditions: Vec<ReadCondition>,
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct ReadCondition {
    pub field: String,
    pub eq: Value,
}

/// A read set and what the authority held for it at one moment.
///
/// The token is opaque and meaningful only to the authority that issued it. A
/// transaction fenced by a basis commits only if re-reading the same set,
/// inside the commit's lock, yields the same token.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct ReadBasis {
    pub reads: ReadSet,
    pub token: String,
}

/// The `key` of a collection-fence refusal (`PreconditionFailure::Fence`).
pub(crate) const COLLECTION_FENCE_KEY: &str = "collection-version";

/// Rows read under one acquisition of the state lock, with the write version
/// each whole collection read had at that moment (`collection_versions`).
pub(crate) struct ConsistentRows {
    pub(crate) view: HashMap<String, BTreeMap<String, StoredRow>>,
    pub(crate) versions: HashMap<String, u64>,
}

/// Token prefix for read bases this authority issues.
pub const READ_BASIS_PREFIX: &str = "fr1:";
/// Largest number of records plus predicates one read set may name.
pub const READ_SET_LIMIT: usize = 1_000;

impl ReadSet {
    /// Validate, de-duplicate, and order, so two descriptions of the same reads
    /// are one read set and one token.
    pub fn normalised(&self) -> Result<ReadSet> {
        let valid = |segment: &str| {
            !segment.is_empty()
                && segment.len() <= 128
                && segment
                    .bytes()
                    .all(|byte| byte.is_ascii_alphanumeric() || matches!(byte, b'.' | b'_' | b'-'))
        };
        let mut records: BTreeMap<(String, String), ReadRecord> = BTreeMap::new();
        for record in &self.records {
            if !valid(&record.collection) || !valid(&record.id) {
                return Err(FlowError::CapabilityError(format!(
                    "INVALID_READ_SET:invalid read {}:{}",
                    record.collection, record.id
                )));
            }
            records.insert(
                (record.collection.clone(), record.id.clone()),
                record.clone(),
            );
        }
        let mut predicates: BTreeMap<(String, String), ReadPredicate> = BTreeMap::new();
        for predicate in &self.predicates {
            if !valid(&predicate.collection) || predicate.conditions.is_empty() {
                return Err(FlowError::CapabilityError(format!(
                    "INVALID_READ_SET:a predicate over {} must name at least one field",
                    predicate.collection
                )));
            }
            let mut conditions = predicate.conditions.clone();
            if conditions
                .iter()
                .any(|condition| condition.field.is_empty())
            {
                return Err(FlowError::CapabilityError(
                    "INVALID_READ_SET:a predicate condition requires a field".into(),
                ));
            }
            conditions.sort_by(|left, right| left.field.cmp(&right.field));
            let identity = serde_json::to_string(&conditions).unwrap_or_default();
            predicates.insert(
                (predicate.collection.clone(), identity),
                ReadPredicate {
                    collection: predicate.collection.clone(),
                    conditions,
                },
            );
        }
        if records.is_empty() && predicates.is_empty() {
            return Err(FlowError::CapabilityError(
                "INVALID_READ_SET:a read set that names nothing fences nothing".into(),
            ));
        }
        if records.len() + predicates.len() > READ_SET_LIMIT {
            return Err(FlowError::CapabilityError(format!(
                "INVALID_READ_SET:a read set may name at most {READ_SET_LIMIT} records and predicates"
            )));
        }
        Ok(ReadSet {
            records: records.into_values().collect(),
            predicates: predicates.into_values().collect(),
        })
    }
}

/// Where a read set's logical collections and ids live in storage.
///
/// One read set, one token semantics; only the storage addressing differs
/// between the routes that commit transactions.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum ReadLayout {
    /// The direct transaction route: rows under `collection`, keyed `collection:id`.
    Direct,
    /// An application state namespace: rows under `namespace:collection`, keyed by id.
    Namespace(String),
}

impl ReadLayout {
    fn capability(&self, collection: &str) -> String {
        match self {
            Self::Direct => collection.to_string(),
            Self::Namespace(namespace) => format!("{namespace}:{collection}"),
        }
    }

    fn key(&self, collection: &str, id: &str) -> String {
        match self {
            Self::Direct => format!("{collection}:{id}"),
            Self::Namespace(_) => id.to_string(),
        }
    }

    /// The authority scope a token is valid in. A token is never evaluated in
    /// another scope: it is refused as invalid there, not compared.
    fn scope_tag(&self) -> String {
        match self {
            Self::Direct => "d".into(),
            Self::Namespace(namespace) => {
                let digest = format!(
                    "{:x}",
                    Sha256::digest(format!("namespace\0{namespace}").as_bytes())
                );
                format!("n{}", &digest[..16])
            }
        }
    }

    fn token_prefix(&self) -> String {
        format!("{READ_BASIS_PREFIX}{}:", self.scope_tag())
    }
}

/// What the state a read set names is, now, as one token. Rows are read in
/// full; tombstoned rows are absent; only the named records and the named
/// collections' matching rows are read.
fn read_basis_token(
    rows: &HashMap<String, BTreeMap<String, StoredRow>>,
    reads: &ReadSet,
    layout: &ReadLayout,
) -> String {
    let live = |capability: &str, key: &str| {
        rows.get(capability)
            .and_then(|bucket| bucket.get(key))
            .filter(|row| !row.deleted)
            .map(|row| row.value.clone())
    };
    let records: Vec<Value> = reads
        .records
        .iter()
        .map(|record| {
            let value = live(
                &layout.capability(&record.collection),
                &layout.key(&record.collection, &record.id),
            );
            serde_json::json!([record.collection, record.id, value])
        })
        .collect();
    let predicates: Vec<Value> = reads
        .predicates
        .iter()
        .map(|predicate| {
            let matching: Vec<Value> = rows
                .get(&layout.capability(&predicate.collection))
                .map(|bucket| {
                    bucket
                        .iter()
                        .filter(|(_, row)| !row.deleted)
                        .filter(|(_, row)| {
                            predicate.conditions.iter().all(|condition| {
                                row.value.get(&condition.field) == Some(&condition.eq)
                            })
                        })
                        .map(|(key, row)| serde_json::json!([key, row.value]))
                        .collect()
                })
                .unwrap_or_default();
            serde_json::json!([predicate.collection, predicate.conditions, matching])
        })
        .collect();
    let observed = serde_json::json!({ "records": records, "predicates": predicates });
    format!(
        "{}{:x}",
        layout.token_prefix(),
        Sha256::digest(serde_json::to_vec(&observed).unwrap_or_default())
    )
}

/// Which predicate failed, and what the authority actually holds.
///
/// Structured rather than a formatted string, because the caller has to tell a
/// lost race from a broken deployment: the first is retried with fresh state,
/// the second is not retried at all.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase", tag = "predicate")]
pub enum PreconditionFailure {
    /// Required absent, but the record exists.
    Present { collection: String, key: String },
    /// A predicate was given for a record that does not exist.
    Missing { collection: String, key: String },
    Version {
        collection: String,
        key: String,
        expected: u64,
        actual: u64,
    },
    Epoch {
        collection: String,
        key: String,
        expected: u64,
        actual: u64,
    },
    Lease {
        collection: String,
        key: String,
        expected: String,
        actual: Option<String>,
    },
    /// State named by a read basis changed after the basis was read.
    ///
    /// The tokens are kept for diagnostics inside the authority but never
    /// serialized: a refusal says that the basis changed, not what it digests.
    Fence {
        collection: String,
        key: String,
        #[serde(skip_serializing, default)]
        expected: String,
        #[serde(skip_serializing, default)]
        actual: String,
    },
    /// A client's version was issued in another database history than the
    /// authority's current one (`docs/reference/version-tokens.md`).
    ///
    /// `expected` is the history the client's token names, or `None` for a
    /// bare numeric version, which names no history and is accepted only in a
    /// history that began at genesis. `actual` is the authority's history.
    History {
        collection: String,
        key: String,
        expected: Option<String>,
        actual: String,
    },
}

impl PreconditionFailure {
    pub fn collection(&self) -> &str {
        match self {
            Self::Present { collection, .. }
            | Self::Missing { collection, .. }
            | Self::Version { collection, .. }
            | Self::Epoch { collection, .. }
            | Self::Lease { collection, .. }
            | Self::Fence { collection, .. }
            | Self::History { collection, .. } => collection,
        }
    }
    /// The storage key, which is namespaced as `collection:id`.
    pub fn key(&self) -> &str {
        match self {
            Self::Present { key, .. }
            | Self::Missing { key, .. }
            | Self::Version { key, .. }
            | Self::Epoch { key, .. }
            | Self::Lease { key, .. }
            | Self::Fence { key, .. }
            | Self::History { key, .. } => key,
        }
    }
}

impl PreconditionFailure {
    /// The refusal as every transport serializes it: `predicate`, the
    /// application's `collection` (never a storage namespace), the record `id`,
    /// its `key` as `collection:id`, and `expected` / `actual` where the
    /// predicate has them. A fence names the first fenced collection and
    /// `key: "read-basis"`, with no `id` and no tokens.
    ///
    /// `layout` is where the authority addressed the record: the direct route
    /// keys rows `collection:id` under `collection`; an application namespace
    /// keys them by id under `namespace:collection`.
    pub fn public_json(&self, layout: &ReadLayout) -> Value {
        let mut value = serde_json::to_value(self).unwrap_or(Value::Null);
        if matches!(self, Self::Fence { .. }) {
            return value;
        }
        let (collection, id) = match layout {
            ReadLayout::Direct => {
                let collection = self.collection().to_string();
                let id = self
                    .key()
                    .strip_prefix(&format!("{collection}:"))
                    .unwrap_or(self.key())
                    .to_string();
                (collection, id)
            }
            ReadLayout::Namespace(namespace) => (
                self.collection()
                    .strip_prefix(&format!("{namespace}:"))
                    .unwrap_or(self.collection())
                    .to_string(),
                self.key().to_string(),
            ),
        };
        if let Some(object) = value.as_object_mut() {
            object.insert("key".into(), Value::String(format!("{collection}:{id}")));
            object.insert("collection".into(), Value::String(collection));
            object.insert("id".into(), Value::String(id));
        }
        value
    }
}

impl Display for PreconditionFailure {
    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
        match self {
            Self::Present { collection, key } => {
                write!(f, "{collection}/{key} was required to be absent but exists")
            }
            Self::Missing { collection, key } => write!(f, "{collection}/{key} does not exist"),
            Self::Version {
                collection,
                key,
                expected,
                actual,
            } => write!(
                f,
                "{collection}/{key} is at version {actual}, expected {expected}"
            ),
            Self::Epoch {
                collection,
                key,
                expected,
                actual,
            } => write!(
                f,
                "{collection}/{key} is at epoch {actual}, expected {expected}"
            ),
            Self::Lease {
                collection,
                key,
                expected,
                actual,
            } => write!(
                f,
                "{collection}/{key} holds lease {actual:?}, expected {expected}"
            ),
            Self::Fence { collection, .. } => write!(
                f,
                "state read by this transaction has changed (read basis over {collection})"
            ),
            Self::History { collection, key, expected: Some(expected), actual } => write!(
                f,
                "{collection}/{key}: the version was issued in database history {expected}, not this one ({actual}); read the record again"
            ),
            Self::History { collection, key, expected: None, actual } => write!(
                f,
                "{collection}/{key}: a numeric version names no database history, and this database was restored (history {actual}); fence with a version token read from it"
            ),
        }
    }
}

/// How a database history began (`docs/reference/version-tokens.md`).
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)]
#[serde(rename_all = "snake_case")]
pub enum HistoryOrigin {
    /// The database was created empty, or by an earlier release that had no
    /// history: every version it ever issued is in this history.
    #[default]
    Genesis,
    /// The database was restored from a backup. Versions issued before the
    /// restore, by the backed-up database or any other restore of it, are not
    /// in this history.
    Restored,
}

/// The history in which a database issues record versions.
///
/// A version (a document's `__version`, or a row's storage sequence) means
/// something only within the history that issued it. A restore starts a new
/// history: the restored database holds the backup's records, but versions it
/// goes on to issue can repeat numbers the backed-up database already issued
/// after the backup. A version token names its history, so a token from
/// another history can never fence a write here. A replica bootstrapped from
/// its authority's snapshot shares the authority's history.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, Default)]
pub struct VersionHistory {
    /// 128 random bits, hex.
    pub id: String,
    pub origin: HistoryOrigin,
}

/// The prefix of a version token: `fv1:<history id>:<version>`.
pub const VERSION_TOKEN_PREFIX: &str = "fv1";

impl VersionHistory {
    fn new(origin: HistoryOrigin) -> Self {
        Self { id: format!("{:032x}", rand::random::<u128>()), origin }
    }

    /// The token naming `version` in this history.
    pub fn token(&self, version: u64) -> String {
        format!("{VERSION_TOKEN_PREFIX}:{}:{version}", self.id)
    }
}

/// Split a version token into its history id and version. `None` when it is
/// not one: a token is `fv1:<32 hex digits>:<decimal version>`, nothing else.
pub fn parse_version_token(token: &str) -> Option<(&str, u64)> {
    let mut parts = token.split(':');
    let (prefix, history, version) = (parts.next()?, parts.next()?, parts.next()?);
    if parts.next().is_some()
        || prefix != VERSION_TOKEN_PREFIX
        || history.len() != 32
        || !history.bytes().all(|byte| byte.is_ascii_hexdigit() && !byte.is_ascii_uppercase())
        || version.is_empty()
        || !version.bytes().all(|byte| byte.is_ascii_digit())
    {
        return None;
    }
    Some((history, version.parse().ok()?))
}
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct AtomicCommit {
    pub transaction_id: String,
    pub base_revision: u64,
    pub commit_revision: u64,
    pub status: TransactionStatus,
    pub state_before: u64,
    pub state_after: u64,
    pub rows: Vec<StoredRow>,
    pub duplicate: bool,
    /// How a duplicate was recognized. Present only on a duplicate, and only
    /// when the caller's request could be compared with what was committed
    /// (`Verified`) or was deliberately judged by id alone (`LegacyUnverified`).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub payload_binding: Option<PayloadBinding>,
}

/// What a duplicate transaction id was checked against.
#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "snake_case")]
pub enum PayloadBinding {
    /// The id and the payload hash both match what was committed: this request
    /// is the original one.
    Verified,
    /// The id was committed without a payload hash, so only the id could be
    /// checked. The caller must not read this as proof the payload matches.
    LegacyUnverified,
}

#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "snake_case")]
pub enum TransactionStatus {
    Committed,
}

#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
pub enum JsonCasResult {
    Updated {
        current_version: u64,
        current_epoch: u64,
        value: Value,
    },
    VersionConflict {
        current_version: u64,
        current_epoch: u64,
    },
    AuthorityConflict {
        current_version: u64,
        current_epoch: u64,
    },
    LeaseConflict {
        current_version: u64,
        current_epoch: u64,
    },
    ReplicationConflict {
        current_version: u64,
        current_epoch: u64,
    },
    NotFound,
}
/// How many recent commits keep their attribution in memory.
///
/// Sized to cover what an operator reads in one sitting rather than to be a
/// log. A larger window costs memory on every instance to answer a question the
/// durable log already answers more completely.
const TRANSACTION_ATTRIBUTION_WINDOW: usize = 512;

/// How many of its newest operations a standalone store (one no peer has ever
/// acknowledged) keeps in its operation log. See `ChangeLog::prune_standalone`
/// and docs/reference/storage-growth.md.
pub const STANDALONE_OPERATION_WINDOW: usize = 4096;

/// How many mutated keys one attribution names before it stops listing them.
///
/// A bulk transaction can touch thousands of records; naming them all would
/// make one commit's attribution larger than the rest of the window. The count
/// is always exact, so a truncated list is visible as a truncated list.
const TRANSACTION_ATTRIBUTION_KEYS: usize = 32;

/// Who committed a transaction, and what it touched.
///
/// Projected from the audit document the transaction already writes. It carries
/// no record values: attribution answers *who, when, and to what*, and the
/// values are reachable through the record and revision APIs that authorize
/// each read.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct TransactionAttribution {
    pub transaction_id: String,
    /// Stable operation identities assigned to the rows in this transaction.
    /// These are distinct from both transaction and revision identity.
    #[serde(default)]
    pub operation_ids: Vec<String>,
    /// The actor the caller authenticated as, when the transaction named one.
    pub subject: Option<String>,
    pub tenant_id: Option<String>,
    pub application_id: Option<String>,
    /// The application contract revision the transaction was executed against.
    pub application_revision: Option<String>,
    pub base_revision: u64,
    pub commit_revision: u64,
    pub state_before: u64,
    pub state_after: u64,
    /// `capability:key` for each mutation, truncated at
    /// [`TRANSACTION_ATTRIBUTION_KEYS`].
    pub keys: Vec<String>,
    /// How many mutations the transaction made, whether or not `keys` lists
    /// them all.
    pub operations: usize,
    #[serde(default)]
    pub principal_id: Option<String>,
    #[serde(default)]
    pub agent_id: Option<String>,
    #[serde(default)]
    pub session_id: Option<String>,
    #[serde(default)]
    pub delegator_id: Option<String>,
    #[serde(default)]
    pub work_id: Option<String>,
    /// Milliseconds since the epoch, matching `StoredRow::unix_ms`.
    pub unix_ms: u128,
    /// Canonical transaction metadata exactly as committed. Record values are
    /// deliberately absent; stable work/session/agent/operation references
    /// live here so historical provenance survives process loss.
    #[serde(default)]
    pub audit: Option<Value>,
}

impl TransactionAttribution {
    /// Builds an attribution from a transaction record's own audit document.
    fn from_record(
        transaction_id: &str,
        audit: Option<&Value>,
        base_revision: u64,
        commit_revision: u64,
        state_before: u64,
        state_after: u64,
        rows: &[StoredRow],
        unix_ms: u128,
    ) -> Self {
        let text = |field: &str| {
            audit
                .and_then(|value| value.get(field))
                .and_then(Value::as_str)
                .map(str::to_string)
        };
        TransactionAttribution {
            transaction_id: transaction_id.to_string(),
            operation_ids: rows
                .iter()
                .filter_map(|row| row.operation.as_ref())
                .map(|operation| {
                    format!("operation:{}:{}", operation.instance_id, operation.sequence)
                })
                .collect(),
            subject: text("subject"),
            tenant_id: text("tenant"),
            application_id: text("application"),
            application_revision: text("revision"),
            base_revision,
            commit_revision,
            state_before,
            state_after,
            keys: rows
                .iter()
                .take(TRANSACTION_ATTRIBUTION_KEYS)
                .map(|row| format!("{}:{}", row.capability, row.key))
                .collect(),
            operations: rows.len(),
            principal_id: text("principal_id"),
            agent_id: text("agent_id"),
            session_id: text("session_id"),
            delegator_id: text("delegator_id"),
            work_id: text("work_id").or_else(|| text("workload_id")),
            unix_ms,
            audit: audit.cloned(),
        }
    }

    /// Whether this transaction touched a record, as far as `keys` records it.
    pub fn touched(&self, capability: &str, key: &str) -> bool {
        let target = format!("{capability}:{key}");
        self.keys.iter().any(|held| *held == target)
    }
}

/// Upgrade compacted attribution written before operation identities became a
/// first-class part of canonical history. The mapping is deterministic from
/// durable transaction data, so reopening never regenerates a different ID.
fn normalize_transaction_attribution(
    mut attribution: TransactionAttribution,
) -> TransactionAttribution {
    if attribution.operation_ids.is_empty() {
        if attribution.transaction_id.starts_with("operation:") {
            let operation_id = attribution.transaction_id.clone();
            attribution.transaction_id = operation_id.replacen("operation:", "transaction:", 1);
            attribution.operation_ids.push(operation_id);
        } else {
            attribution.operation_ids = (1..=attribution.operations)
                .map(|index| {
                    format!(
                        "operation:legacy-transaction:{}:{index}",
                        attribution.transaction_id
                    )
                })
                .collect();
        }
    }
    attribution
}

/// Records an attribution, discarding the oldest once the window is full.
fn remember_attribution(inner: &mut Inner, attribution: TransactionAttribution) {
    inner.transaction_history.push(attribution.clone());
    if inner.transaction_attributions.len() >= TRANSACTION_ATTRIBUTION_WINDOW {
        inner.transaction_attributions.pop_front();
    }
    inner.transaction_attributions.push_back(attribution);
}

fn remember_operation_attribution(
    inner: &mut Inner,
    row: &StoredRow,
    base_revision: u64,
    commit_revision: u64,
) {
    let Some(operation) = row.operation.as_ref() else {
        return;
    };
    remember_attribution(
        inner,
        TransactionAttribution {
            transaction_id: format!(
                "transaction:{}:{}",
                operation.instance_id, operation.sequence
            ),
            operation_ids: vec![format!(
                "operation:{}:{}",
                operation.instance_id, operation.sequence
            )],
            subject: None,
            tenant_id: None,
            application_id: None,
            application_revision: operation
                .revision
                .as_ref()
                .map(|revision| revision.id.clone()),
            base_revision,
            commit_revision,
            state_before: operation.sequence.saturating_sub(1),
            state_after: operation.sequence,
            keys: vec![format!("{}:{}", row.capability, row.key)],
            operations: 1,
            principal_id: None,
            agent_id: None,
            session_id: None,
            delegator_id: None,
            work_id: None,
            unix_ms: row.unix_ms,
            audit: None,
        },
    );
}

#[derive(Debug, Clone, Serialize, Deserialize)]
struct TransactionLogRecord {
    record_type: String,
    transaction_id: String,
    #[serde(default)]
    payload_hash: Option<String>,
    state_before: u64,
    state_after: u64,
    #[serde(default)]
    base_revision: u64,
    #[serde(default)]
    commit_revision: 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>,
    /// In a snapshot row (compaction, `export_snapshot`), which carries no
    /// `operation`: the record's version, the sequence of the operation that
    /// last wrote it. [`StoredRow::version`] reads it, so fences and record
    /// versions mean the same after a compaction, restart, restore or replica
    /// bootstrap as before. Absent from every other row, and from snapshot rows
    /// written by earlier releases.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub recorded_version: Option<u64>,
}

impl StoredRow {
    /// The record's version: the sequence of the operation that last wrote it.
    ///
    /// A row loaded from a snapshot carries its version as `recorded_version`.
    /// One written before snapshot rows carried it (a compacted log or a
    /// snapshot from an earlier release) has no recorded version. It is a present record all the same,
    /// so it reads as version 0, which no operation is ever numbered: a
    /// "must be absent" fence refuses it, and a fence on 0 can replace it.
    /// `None` only for a tombstone.
    pub fn version(&self) -> Option<u64> {
        if self.deleted {
            return None;
        }
        Some(match &self.operation {
            Some(operation) => operation.sequence,
            None => self.recorded_version.unwrap_or(0),
        })
    }
}

/// The snapshot form of a live row, as compaction and `export_snapshot` write
/// it. A snapshot row is state, not an operation to replay, so it carries no
/// `operation`, only the record's version as `recorded_version`.
fn snapshot_row(row: &StoredRow) -> StoredRow {
    let mut snapshot = row.clone();
    snapshot.recorded_version = row.version();
    snapshot.operation = None;
    snapshot
}

/// When a compaction should actually rewrite the durable log.
///
/// Pruning acknowledged operations from memory is cheap. **Rewriting the log is
/// not**: it serializes every row in the database and fsyncs it while holding
/// the one lock that serializes every read and every write. Doing that on a
/// short timer stops the world on that timer.
///
/// The policy separates the two. Pruning still happens whenever it can; the
/// rewrite waits until enough has accumulated to be worth the stall.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub struct CompactionPolicy {
    /// Operations that must have been pruned since the last rewrite before the
    /// next one is worth its cost.
    pub rewrite_after_pruned: usize,
}

impl Default for CompactionPolicy {
    fn default() -> Self {
        // Chosen so a busy database rewrites occasionally rather than
        // constantly. At one operation per write this is one rewrite per
        // thousand acknowledged writes instead of one every timer tick.
        CompactionPolicy {
            rewrite_after_pruned: 1000,
        }
    }
}

/// What a policy-driven compaction did.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum CompactionOutcome {
    /// Nothing was acknowledged by every active peer; there was no work.
    Idle,
    /// Operations were pruned from memory and the log rewrite was **deferred**,
    /// because the accumulated gain does not yet justify the stall.
    Deferred {
        pruned: usize,
        pending_since_rewrite: usize,
    },
    /// The durable log was rewritten.
    Rewritten { pruned: usize },
}

impl CompactionOutcome {
    /// Operations pruned from the in-memory log by this call.
    pub fn pruned(&self) -> usize {
        match self {
            CompactionOutcome::Idle => 0,
            CompactionOutcome::Deferred { pruned, .. }
            | CompactionOutcome::Rewritten { pruned } => *pruned,
        }
    }

    /// Whether this call rewrote the durable log.
    pub fn rewrote_log(&self) -> bool {
        matches!(self, CompactionOutcome::Rewritten { .. })
    }
}

/// How far a single-record write is pushed before it returns.
///
/// This is a **contract**, not a tuning knob: it decides what a successful
/// mutation means. Nothing here makes a claim about surviving power loss —
/// see [`DurabilityMode::guarantee`] for what each mode does and does not
/// establish.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub enum DurabilityMode {
    /// Write and flush to the operating system. **The default.**
    ///
    /// The bytes leave the process before the call returns, so a committed
    /// write survives the process dying. They are not forced to the device.
    Flushed,
    /// Write, flush, and `fsync` before returning.
    ///
    /// Issues a stable-storage barrier per mutation. Whether that barrier
    /// actually reaches the platter depends on the filesystem, the mount
    /// options and the drive's write cache — none of which this database can
    /// observe, so this mode buys a barrier, not a proof.
    Synced,
    /// Flush every write, and `fsync` once every `every` writes.
    ///
    /// Amortises the barrier. The cost is an explicit window: up to `every - 1`
    /// acknowledged writes may not yet have been through one.
    Grouped { every: u32 },
}

impl Default for DurabilityMode {
    fn default() -> Self {
        DurabilityMode::Flushed
    }
}

impl DurabilityMode {
    /// What a successful mutation guarantees under this mode, stated so that a
    /// caller can read the contract rather than infer it from an API name.
    pub fn guarantee(&self) -> &'static str {
        match self {
            DurabilityMode::Flushed => {
                "the record has left the process; it survives a process crash.                  Stable-storage durability is not established."
            }
            DurabilityMode::Synced => {
                "a stable-storage barrier was issued for this record. Whether it                  reached the device depends on the storage stack, which this                  database cannot observe."
            }
            DurabilityMode::Grouped { .. } => {
                "the record has left the process. A stable-storage barrier is                  issued periodically, so an acknowledged write may not yet have                  been through one."
            }
        }
    }

    /// How many acknowledged writes may not yet have been through a barrier.
    ///
    /// `None` where no barrier is issued at all.
    pub fn unbarriered_window(&self) -> Option<u32> {
        match self {
            DurabilityMode::Flushed => None,
            DurabilityMode::Synced => Some(0),
            DurabilityMode::Grouped { every } => Some(every.saturating_sub(1)),
        }
    }
}

/// What is actually known about this database's durable storage.
///
/// Every variant corresponds to a fact the open established. There is no
/// variant meaning "probably fine", and none that says anything about power
/// loss — that is unproven, and health may not manufacture a guarantee the
/// database does not have.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum StorageHealth {
    /// Every durable byte replayed as a complete, valid record.
    Clean,
    /// Operational, **and the last write did not land**.
    ///
    /// The log ended in an incomplete append, which was discarded. The database
    /// is usable and is not in the same condition as one that replayed cleanly,
    /// and reporting them identically is what makes an operator unable to tell
    /// a healthy database from one that lost its most recent write.
    RecoveredIncompleteWrite {
        byte_offset: u64,
        discarded_bytes: usize,
    },
}

impl StorageHealth {
    /// Whether the durable log replayed without discarding anything.
    pub fn is_clean(&self) -> bool {
        matches!(self, StorageHealth::Clean)
    }

    /// A short stable label for an operational surface.
    pub fn label(&self) -> &'static str {
        match self {
            StorageHealth::Clean => "clean",
            StorageHealth::RecoveredIncompleteWrite { .. } => "recovered-incomplete-write",
        }
    }
}

impl Display for StorageHealth {
    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
        match self {
            StorageHealth::Clean => write!(f, "durable log replayed cleanly"),
            StorageHealth::RecoveredIncompleteWrite {
                byte_offset,
                discarded_bytes,
            } => write!(
                f,
                "durable log ended in an incomplete append: {discarded_bytes} bytes at offset \
                 {byte_offset} were discarded, so the last write did not land"
            ),
        }
    }
}

/// What this database knows about itself, as facts rather than labels.
///
/// Deliberately small. It reports only conditions the open actually
/// established, and it is not an operations dashboard: replication health,
/// backup freshness and capacity are not here, because none of them has a
/// defined operational contract yet and health must not invent one.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct DatabaseHealth {
    /// The durable format this database was accepted as.
    ///
    /// A database in a format this build does not understand never opens, so
    /// reaching this at all is itself the compatibility fact.
    pub durable_format: DurableFormat,
    /// What replaying the durable log had to do.
    pub recovery: LogRecovery,
    /// The storage condition that follows from it.
    pub storage: StorageHealth,
    /// Whether this process can still accept writes.
    pub writes: WriteAvailability,
}

/// Whether a database can accept writes, as this process knows it.
#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
#[serde(tag = "state", rename_all = "kebab-case")]
pub enum WriteAvailability {
    /// Writes are accepted.
    Available,
    /// A failed write could not be rolled back, so what the durable log holds
    /// is unknown to this process. Every write is refused with
    /// `RECOVERY_REQUIRED` until the database is reopened; reads keep serving
    /// every acknowledged write. Reopening replays the log and decides.
    RecoveryRequired { reason: String },
}

impl WriteAvailability {
    pub fn label(&self) -> &'static str {
        match self {
            WriteAvailability::Available => "available",
            WriteAvailability::RecoveryRequired { .. } => "recovery-required",
        }
    }
}

impl DatabaseHealth {
    /// Whether this database is in the condition a clean open produces.
    ///
    /// **Not** a claim that the database is correct, replicated, backed up or
    /// durable against power loss. It says the durable log replayed with
    /// nothing discarded, and nothing more.
    pub fn is_nominal(&self) -> bool {
        self.storage.is_clean() && self.writes == WriteAvailability::Available
    }
}

/// The backup artifact format this build writes and understands.
///
/// Versioned separately from the on-disk database: a backup is an artifact an
/// operator keeps, moves and restores long after the database that produced it,
/// so its compatibility boundary is its own.
pub const BACKUP_VERSION: u32 = 1;

const BACKUP_RECORD_TYPE: &str = "feltdb.backup.v1";

/// The first line of a backup artifact. Everything needed to verify the rest.
#[derive(Debug, Clone, Serialize, Deserialize)]
struct BackupHeader {
    record_type: String,
    backup_version: u32,
    /// The durable format the rows are in.
    format_version: u32,
    created_unix_ms: u64,
    row_count: usize,
    observed_versions: HashMap<String, u64>,
    /// Digest of the rows exactly as written. Detects any alteration.
    content_digest: String,
    /// Digest of what the database *means* — see [`BackupVerification`].
    meaning_digest: String,
}

/// Why a backup artifact was rejected.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct BackupProblem {
    /// What is wrong, in terms of the artifact rather than the parser.
    pub reason: String,
    /// Where, when the problem has a location.
    pub line_number: Option<usize>,
    /// What the operator can do.
    pub action: String,
}

impl Display for BackupProblem {
    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
        match self.line_number {
            Some(line) => write!(f, "record {line}: {}. {}", self.reason, self.action),
            None => write!(f, "{}. {}", self.reason, self.action),
        }
    }
}

/// What a backup artifact contains, established by reading it.
///
/// `meaning_digest` is the part that matters. A content digest proves the file
/// is intact; it does not prove that restoring it produces the same database.
/// The meaning digest covers what the database *is*, independent of how it was
/// written down:
///
/// - every live record: capability, key and canonical value;
/// - every revision: its resource, identity, parent, sequence and content
///   identity, and the authority that produced it;
/// - every resource's retention policy and horizon.
///
/// It deliberately excludes wall-clock timestamps and sync envelopes, which
/// differ between two databases that mean the same thing. Restore recomputes it
/// from the **restored database** and refuses if it disagrees with the
/// artifact, so a restore proves equivalence rather than mere parseability.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct BackupVerification {
    pub backup_version: u32,
    pub format_version: u32,
    pub created_unix_ms: u64,
    pub rows: usize,
    pub content_digest: String,
    pub meaning_digest: String,
}

fn backup_problem(reason: &str, line_number: Option<usize>, action: &str) -> FlowError {
    FlowError::BackupRejected(Box::new(BackupProblem {
        reason: reason.to_string(),
        line_number,
        action: action.to_string(),
    }))
}

/// Digest the rows exactly as they will be written.
fn backup_content_digest(rows: &[StoredRow]) -> Result<String> {
    let mut hasher = Sha256::new();
    for row in rows {
        hasher.update(serde_json::to_vec(row)?);
        hasher.update(b"\n");
    }
    Ok(format!("{:x}", hasher.finalize()))
}

/// Digest what a set of rows *means*, independent of how it was written.
///
/// Canonical by construction: rows are ordered by capability and key, and only
/// the fields that carry meaning take part. Two databases with the same digest
/// hold the same records, the same revision graph and the same retention state.
fn backup_meaning_digest(rows: &[StoredRow]) -> Result<String> {
    let mut meaningful: Vec<(&str, &str, String)> = rows
        .iter()
        .filter(|row| !row.deleted)
        .map(|row| {
            (
                row.capability.as_str(),
                row.key.as_str(),
                row.value.to_string(),
            )
        })
        .collect();
    meaningful.sort();

    let mut hasher = Sha256::new();
    hasher.update(b"feltdb.backup.meaning.v1");
    for (capability, key, value) in meaningful {
        hasher.update(capability.as_bytes());
        hasher.update([0u8]);
        hasher.update(key.as_bytes());
        hasher.update([0u8]);
        hasher.update(value.as_bytes());
        hasher.update([0u8]);
    }
    Ok(format!("{:x}", hasher.finalize()))
}

/// Read and check a backup artifact **without opening it as a database**.
///
/// Structural and semantic checks only, and it never writes: verifying a backup
/// must be something an operator can do to an artifact they are not yet willing
/// to restore.
pub fn verify_backup(path: &Path) -> Result<BackupVerification> {
    let text = std::fs::read_to_string(path)?;
    let mut lines = text.lines();

    let Some(header_line) = lines.next() else {
        return Err(backup_problem(
            "the artifact is empty",
            None,
            "Restore from a different backup.",
        ));
    };
    let header: BackupHeader = serde_json::from_str(header_line).map_err(|error| {
        backup_problem(
            &format!("the header is not a FeltDB backup header: {error}"),
            Some(1),
            "Check that this file is a FeltDB backup and was not truncated at the start.",
        )
    })?;
    if header.record_type != BACKUP_RECORD_TYPE {
        return Err(backup_problem(
            &format!("unexpected record type {}", header.record_type),
            Some(1),
            "Check that this file is a FeltDB backup.",
        ));
    }
    if header.backup_version != BACKUP_VERSION {
        return Err(backup_problem(
            &format!(
                "backup format version {} is not the version this build reads ({BACKUP_VERSION})",
                header.backup_version
            ),
            Some(1),
            "Restore with a FeltDB build that reads this backup version.",
        ));
    }
    if header.format_version != DURABLE_FORMAT_VERSION {
        return Err(backup_problem(
            &format!(
                "the rows are in durable format version {} and this build requires version {DURABLE_FORMAT_VERSION}",
                header.format_version
            ),
            Some(1),
            "Restore with a FeltDB build matching the format the backup was taken in.",
        ));
    }

    let mut rows = Vec::with_capacity(header.row_count);
    for (index, line) in lines.enumerate() {
        if line.trim().is_empty() {
            continue;
        }
        let row: StoredRow = serde_json::from_str(line).map_err(|error| {
            backup_problem(
                &format!("not a durable record: {error}"),
                Some(index + 2),
                "The backup is damaged. Restore from another copy.",
            )
        })?;
        rows.push(row);
    }

    if rows.len() != header.row_count {
        return Err(backup_problem(
            &format!(
                "the header declares {} records and the artifact holds {}",
                header.row_count,
                rows.len()
            ),
            None,
            "The backup is truncated or was appended to. Restore from another copy.",
        ));
    }

    let content_digest = backup_content_digest(&rows)?;
    if content_digest != header.content_digest {
        return Err(backup_problem(
            "the records do not match the digest in the header",
            None,
            "The backup has been altered or corrupted. Restore from another copy.",
        ));
    }

    let meaning_digest = backup_meaning_digest(&rows)?;
    if meaning_digest != header.meaning_digest {
        return Err(backup_problem(
            "the records do not mean what the header says they mean",
            None,
            "The backup has been altered. Restore from another copy.",
        ));
    }

    Ok(BackupVerification {
        backup_version: header.backup_version,
        format_version: header.format_version,
        created_unix_ms: header.created_unix_ms,
        rows: rows.len(),
        content_digest,
        meaning_digest,
    })
}

/// Where durable corruption was found, and what is wrong with it.
///
/// Carries a location so an operator can find the damage, and an excerpt so
/// they can recognise it, without the error having to quote a whole record.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct LogCorruption {
    /// 1-based line number in the durable log.
    pub line_number: usize,
    /// Byte offset of the start of the record.
    pub byte_offset: u64,
    /// What is wrong, in terms of the record rather than the parser.
    pub reason: String,
    /// The beginning of the record, truncated.
    pub excerpt: String,
}

impl Display for LogCorruption {
    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
        write!(
            f,
            "durable log record {} at byte {} is corrupt: {}. Excerpt: {}. \
             The database was not opened and was not modified.",
            self.line_number, self.byte_offset, self.reason, self.excerpt
        )
    }
}

/// What replaying the durable log had to do to succeed.
///
/// A clean open and an open that discarded an incomplete final append are
/// different facts, and the difference must survive past an internal debug
/// message: an operator needs to know their database opened *and* that its last
/// write did not land.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum LogRecovery {
    /// Every durable byte was a complete, valid record.
    Clean,
    /// The log ended in an incomplete append.
    ///
    /// The final bytes carried no record terminator, so they cannot be a record
    /// this database finished writing. They were not replayed, and the log was
    /// truncated back to the last complete record so that the next append does
    /// not splice onto a partial line.
    ///
    /// **This is the only condition under which durable bytes are discarded.**
    /// A *complete* record that is invalid is corruption, not a torn write, and
    /// refuses the open however close to the end of the file it sits.
    RecoveredTornTail {
        /// Byte offset where the incomplete append began.
        byte_offset: u64,
        /// How many bytes were discarded.
        discarded_bytes: usize,
    },
}

impl Default for LogRecovery {
    fn default() -> Self {
        LogRecovery::Clean
    }
}

impl Default for DurableFormat {
    fn default() -> Self {
        DurableFormat::Versioned(DURABLE_FORMAT_VERSION)
    }
}

impl LogRecovery {
    /// Whether the open replayed the log without discarding anything.
    pub fn is_clean(&self) -> bool {
        matches!(self, LogRecovery::Clean)
    }
}

impl Display for LogRecovery {
    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
        match self {
            LogRecovery::Clean => write!(f, "clean"),
            LogRecovery::RecoveredTornTail {
                byte_offset,
                discarded_bytes,
            } => write!(
                f,
                "recovered from an incomplete final append: {discarded_bytes} bytes at offset \
                 {byte_offset} were not a complete record and were discarded"
            ),
        }
    }
}

/// The durable format this build writes and understands.
///
/// Independent of the package version on purpose: an application release that
/// changes nothing about persistence must not appear to change the database.
///
/// - **1** — everything before revisions became resource-scoped. Never written
///   by any build; it names the era that predates format versioning.
/// - **2** — resource-scoped revisions: a `StateRevision` carries `resource`,
///   `content_id` and `sequence`.
pub const DURABLE_FORMAT_VERSION: u32 = 2;

/// The log record that carries the format version.
const FORMAT_RECORD_TYPE: &str = "feltdb.format.v1";

#[derive(Debug, Serialize, Deserialize)]
struct FormatRecord {
    record_type: String,
    format_version: u32,
}

/// What format a durable database is in.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum DurableFormat {
    /// A format record states the version.
    Versioned(u32),
    /// No format record: the database predates format versioning.
    ///
    /// This is a version, not an absence of one. It is the only case where the
    /// records themselves are examined to decide compatibility, and that
    /// examination is a deliberate one-time probe rather than a deserialization
    /// attempt whose failure is discarded.
    Unversioned,
}

impl Display for DurableFormat {
    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
        match self {
            DurableFormat::Versioned(version) => write!(f, "version {version}"),
            DurableFormat::Unversioned => write!(f, "unversioned (predates format versioning)"),
        }
    }
}

/// Why a durable database cannot be opened, and what to do about it.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct FormatIncompatibility {
    /// What the database is.
    pub found: DurableFormat,
    /// What this build requires.
    pub required: u32,
    /// What is wrong, in terms of the data rather than the code.
    pub reason: String,
    /// What the operator can do.
    pub action: String,
}

impl Display for FormatIncompatibility {
    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
        write!(
            f,
            "durable format {} is incompatible with this FeltDB, which requires \
             format version {}; {}. No data was read or modified. {}",
            self.found, self.required, self.reason, self.action
        )
    }
}

/// The result of examining a durable database without opening it.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum FormatCompatibility {
    /// Safe to open.
    Compatible(DurableFormat),
    /// Must not be opened.
    Incompatible(FormatIncompatibility),
}

impl FormatCompatibility {
    /// Whether opening this database is safe.
    pub fn is_compatible(&self) -> bool {
        matches!(self, FormatCompatibility::Compatible(_))
    }
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct DatabaseSnapshot {
    pub rows: Vec<StoredRow>,
    pub versions: HashMap<String, u64>,
    pub content_hash: String,
    /// The durable format the rows are in.
    ///
    /// A snapshot carries whole `StoredRow`s, revisions included, so it is a
    /// durable interchange artifact and not merely a protocol value: installing
    /// one from a different format would reintroduce exactly the silent
    /// misinterpretation the on-disk version exists to prevent.
    ///
    /// Defaults to 0 so a snapshot serialized before versioning still
    /// deserializes; 0 is treated as unversioned and refused rather than
    /// assumed current. `content_hash` deliberately does not cover this field,
    /// so hashes computed before it existed remain valid.
    #[serde(default)]
    pub format_version: u32,
    /// The history the snapshot's versions were issued in. A replica that
    /// installs the snapshot shares it; a restore starts a new one
    /// ([`FeltDb::begin_restored_history`]). Absent from snapshots of earlier
    /// releases, whose installer then begins a genesis history.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub history: Option<VersionHistory>,
}

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(())
    }

    /// Everything a snapshot must satisfy to be installed, checked the same way
    /// by installation, backup verification and restore, and by
    /// `export_snapshot` on its own output.
    ///
    /// A record's identity is its collection (`capability`) and its key, two
    /// separate fields: the key is the record's own id, kept exactly as written
    /// (`notes:1` through the key-value API, `1` through transactions), and is
    /// never parsed for a collection. So every row must be live state (not a
    /// tombstone, not an operation), name a collection and a key, appear once
    /// per identity.
    pub fn validate(&self) -> Result<()> {
        if self.format_version != DURABLE_FORMAT_VERSION {
            return Err(FlowError::IncompatibleFormat(Box::new(FormatIncompatibility {
                found: if self.format_version == 0 {
                    DurableFormat::Unversioned
                } else {
                    DurableFormat::Versioned(self.format_version)
                },
                required: DURABLE_FORMAT_VERSION,
                reason: "the snapshot was produced in a different durable format".to_string(),
                action: "Take a fresh snapshot from a FeltDB build matching this one.".to_string(),
            })));
        }
        self.verify()?;
        let invalid = |row: &StoredRow, why: &str| {
            FlowError::CapabilityError(format!(
                "snapshot contains an invalid state row: {why} ({:?} {:?})",
                row.capability, row.key
            ))
        };
        let mut identities = HashSet::with_capacity(self.rows.len());
        for row in &self.rows {
            if row.deleted {
                return Err(invalid(row, "a tombstone"));
            }
            if row.operation.is_some() {
                return Err(invalid(row, "an operation, not state"));
            }
            if row.capability.is_empty() || row.key.is_empty() {
                return Err(invalid(row, "no collection or no key"));
            }
            if !identities.insert((row.capability.as_str(), row.key.as_str())) {
                return Err(invalid(row, "a second row with the same identity"));
            }
        }
        Ok(())
    }
}

#[derive(Debug, Serialize, Deserialize)]
struct LogHeader {
    record_type: String,
    local_sequence: u64,
    observed_versions: HashMap<String, u64>,
    /// Present since format versioning. Absent in headers written before it,
    /// which deserialize as 0 and are classified as unversioned.
    #[serde(default)]
    format_version: u32,
    /// Canonical commit provenance retained when operation-log compaction
    /// rewrites current state. This is history, not a derived event store.
    #[serde(default)]
    transaction_history: Vec<TransactionAttribution>,
    /// Durable binding between a caller transaction identity and its semantic
    /// request. Compaction must retain this or an old id could be reused for a
    /// different mutation after restart.
    #[serde(default)]
    transaction_payload_hashes: HashMap<String, String>,
    /// The authority revision when the log was rewritten. Optional and
    /// additive: an older build ignores it, and a header without it (0) is
    /// replayed exactly as before.
    #[serde(default)]
    authority_revision: u64,
}

/// [`LogHeader`] as written by compaction: the same JSON, from borrowed state.
#[derive(Serialize)]
struct LogHeaderRef<'a> {
    record_type: &'a str,
    local_sequence: u64,
    observed_versions: &'a HashMap<String, u64>,
    format_version: u32,
    transaction_history: &'a Vec<TransactionAttribution>,
    transaction_payload_hashes: &'a HashMap<String, String>,
    authority_revision: u64,
}

#[derive(Debug, Default, Serialize, Deserialize)]
struct SyncMetadata {
    local_sequence: u64,
    observed_versions: HashMap<String, u64>,
    peer_acknowledgements: HashMap<String, HashMap<String, u64>>,
    /// Absent in metadata written before version histories.
    #[serde(default)]
    history: Option<VersionHistory>,
}

pub fn open<P: AsRef<Path>>(path: P) -> Result<FeltDb> {
    FeltDb::open(path)
}

/// Capabilities whose rows are not themselves versioned.
///
/// `state` holds the revisions, and `_retention` holds the watermark that says
/// how much of each resource's history survives. Minting a revision of either
/// would mint a revision of the mint.
const UNVERSIONED_CAPABILITIES: &[&str] = &["state", "_retention"];

/// Whether a write to this capability creates a revision.
fn is_versioned(capability: &str) -> bool {
    !UNVERSIONED_CAPABILITIES.contains(&capability)
}

/// Rebuild the derived head index from the durable revisions.
///
/// Called after recovery, for the same reason `equality_index` is: the index is
/// a convenience over `rows` and must never be the authority for what `rows`
/// contains.
fn rebuild_revision_heads(inner: &mut Inner) {
    let mut heads: HashMap<String, (state_model::StateId, u64)> = HashMap::new();
    if let Some(bucket) = inner.rows.get("state") {
        for row in bucket.values() {
            if row.deleted || !row.key.starts_with("state:revision:") {
                continue;
            }
            let Ok(revision) =
                serde_json::from_value::<state_model::StateRevision>(row.value.clone())
            else {
                continue;
            };
            let entry = heads
                .entry(revision.resource.clone())
                .or_insert_with(|| (revision.id.clone(), revision.sequence));
            if revision.sequence >= entry.1 {
                *entry = (revision.id.clone(), revision.sequence);
            }
        }
    }
    inner.revision_heads = heads;
}

/// The derived row recording a revision.
///
/// Deliberately **not** a mutation: no sequence number, no vector clock tick,
/// no entry in the change log. A revision is a *derived* record of a mutation
/// that already has all three, and giving it its own would make every write
/// advance replication twice and double the operation stream.
///
/// It is still durable — a local write appends it in the same write and under
/// the same barrier as the record it describes (see [`revision_row_to_append`]),
/// so a reopened database has both, and a reader never observes a mutation
/// whose revision is missing.
///
/// The consequence is that revisions are **local and derived**, not replicated.
/// That is sound in principle, because a revision's identity is a function of
/// the resource, the content, the parent and the sequence — all of which a peer
/// that applies the same operation stream has. Whether the sync-apply path
/// actually mints is a separate question this change does not answer.
fn revision_row(revision: &state_model::StateRevision) -> Result<StoredRow> {
    Ok(StoredRow {
        recorded_version: None,
        capability: "state".to_string(),
        key: format!("state:revision:{}", revision.id.as_hex()),
        rust_type: "feltdb::state_model::StateRevision".to_string(),
        value: serde_json::to_value(revision)?,
        unix_ms: now_ms(),
        content_hash: None,
        flow_ref: None,
        deleted: false,
        operation: None,
    })
}

/// Commit a local single-record write: its record and the revision it mints,
/// as one append under one barrier. On failure nothing of the write is applied
/// and the sequence number and clock tick it reserved are given back, so a
/// refused write leaves no trace in memory, in the change log or on disk.
fn commit_local_write_locked(
    inner: &mut Inner,
    row: &StoredRow,
    planned: Option<&state_model::StateRevision>,
    reserved: (u64, Option<HashMap<String, u64>>),
) -> Result<()> {
    let revision = revision_row_to_append(inner, planned)?;
    let mut lines = vec![row];
    lines.extend(revision.as_ref());
    if let Err(error) = append_rows_locked(inner, &lines) {
        inner.sequence = reserved.0;
        inner.sync_state.vector_clock = reserved.1;
        return Err(error);
    }
    if let Some(revision) = revision {
        inner.put_row(revision);
    }
    Ok(())
}

/// The revision row a local write appends together with its record, or `None`
/// when the write mints no revision or the revision is already stored.
fn revision_row_to_append(
    inner: &Inner,
    planned: Option<&state_model::StateRevision>,
) -> Result<Option<StoredRow>> {
    let Some(revision) = planned else {
        return Ok(None);
    };
    let row = revision_row(revision)?;
    let stored = inner
        .rows
        .get("state")
        .and_then(|bucket| bucket.get(&row.key))
        .is_some_and(|row| !row.deleted);
    Ok((!stored).then_some(row))
}

/// Work out the revision an authoritative write will produce, without writing
/// anything.
///
/// Separated from persisting it so the operation that carries this mutation can
/// name the revision it produced. A peer then **reconstructs that revision**
/// rather than minting a local substitute for the resulting state — which is
/// the difference between replicating history and replicating the present.
fn plan_revision(inner: &Inner, resource: &str, content: String) -> state_model::StateRevision {
    let parent = inner.revision_heads.get(resource).cloned();
    let (parent_id, sequence) = match &parent {
        Some((id, sequence)) => (Some(id.clone()), sequence + 1),
        None => (None, 0),
    };
    state_model::StateRevision::at(
        resource.to_string(),
        content,
        parent_id,
        sequence,
        inner.instance_id.clone(),
    )
}

/// What a peer needs to rebuild this revision exactly.
fn provenance_of(revision: &state_model::StateRevision) -> operation::RevisionProvenance {
    operation::RevisionProvenance {
        resource: revision.resource.clone(),
        id: revision.id.as_hex().to_string(),
        parent_id: revision
            .parent_id
            .as_ref()
            .map(|id| id.as_hex().to_string()),
        sequence: revision.sequence,
        content_id: revision.content_id.as_hex().to_string(),
        authority: revision.authority.clone(),
    }
}

/// Persist a revision under the caller's lock, and apply the resource's
/// retention policy.
///
/// Idempotent: a revision already stored is left exactly as it is. Committing
/// the same historical fact twice — which replication does routinely — must not
/// rewrite it.
fn persist_revision_locked(inner: &mut Inner, revision: state_model::StateRevision) -> Result<()> {
    let key = format!("state:revision:{}", revision.id.as_hex());
    let already = inner
        .rows
        .get("state")
        .and_then(|bucket| bucket.get(&key))
        .is_some_and(|row| !row.deleted);

    let resource = revision.resource.clone();
    let id = revision.id.clone();
    let sequence = revision.sequence;

    if !already {
        let row = revision_row(&revision)?;
        // Called once the record this revision describes is durable, so the
        // write has committed whatever happens here. If this append fails it is
        // rolled back (or the store fail-stops), and the revision is still
        // adopted: replay rebuilds it from the committed record's operation on
        // every open, so memory holds exactly what the next open will.
        let _ = append_event_locked(inner, &row);
        inner.put_row(row);
    }

    // The head advances only forward. A fork leaves two revisions at one
    // sequence; whichever is seen last does not become "the" head by accident.
    let advance = inner
        .revision_heads
        .get(&resource)
        .is_none_or(|(_, current)| sequence > *current);
    if advance {
        inner
            .revision_heads
            .insert(resource.clone(), (id, sequence));
    }

    // Retention is policy over history, not part of the committed write: if
    // its append fails, nothing expires now (memory and log agree) and the
    // next write to the resource tries again.
    let _ = apply_retention_locked(inner, &resource);
    Ok(())
}

/// Rebuild the revision an operation carries, and check it is the one the
/// originating authority actually committed.
///
/// The identity is recomputed from the parts rather than trusted: if the value
/// that arrived is not the value the revision was computed from, or the stated
/// identity does not follow from the stated resource, parent and sequence, the
/// operation is refused rather than turned into a plausible local history.
fn reconstruct_revision(
    provenance: &operation::RevisionProvenance,
    value: &Value,
) -> Result<state_model::StateRevision> {
    let content = value.to_string();
    let revision = state_model::StateRevision::at(
        provenance.resource.clone(),
        content,
        provenance
            .parent_id
            .as_ref()
            .map(|id| state_model::StateId::from_hex(id.clone())),
        provenance.sequence,
        provenance.authority.clone(),
    );
    if revision.content_id.as_hex() != provenance.content_id {
        return Err(FlowError::CapabilityError(format!(
            "replicated revision {} does not match the value it arrived with",
            provenance.id
        )));
    }
    if revision.id.as_hex() != provenance.id {
        return Err(FlowError::CapabilityError(format!(
            "replicated revision identity {} does not follow from its own resource, parent and sequence",
            provenance.id
        )));
    }
    Ok(revision)
}

/// Expire whatever the resource's configured policy no longer retains.
///
/// The common path is one map lookup: with no policy configured there is
/// nothing to scan. A resource's history is only walked once a policy exists to
/// bound it.
fn apply_retention_locked(inner: &mut Inner, resource: &str) -> Result<()> {
    let retention_key = format!("_retention:{resource}");
    let Some(state_row) = inner
        .rows
        .get("_retention")
        .and_then(|bucket| bucket.get(&retention_key))
    else {
        return Ok(());
    };
    let Ok(mut state) = serde_json::from_value::<RetentionRecord>(state_row.value.clone()) else {
        return Ok(());
    };
    if state.policy.keep_last.is_none() {
        return Ok(());
    }

    let mut history: Vec<(state_model::StateId, u64)> = Vec::new();
    if let Some(bucket) = inner.rows.get("state") {
        for row in bucket.values() {
            if row.deleted || !row.key.starts_with("state:revision:") {
                continue;
            }
            if let Ok(revision) =
                serde_json::from_value::<state_model::StateRevision>(row.value.clone())
            {
                if revision.resource == resource {
                    history.push((revision.id, revision.sequence));
                }
            }
        }
    }
    history.sort_by_key(|(_, sequence)| *sequence);

    let (expire, horizon) = state_model::revisions_to_expire(&history, state.policy.keep_last);
    if expire.is_empty() {
        return Ok(());
    }
    let tombstones: Vec<StoredRow> = expire
        .iter()
        .map(|id| StoredRow {
            recorded_version: None,
            capability: "state".to_string(),
            key: format!("state:revision:{}", id.as_hex()),
            rust_type: "feltdb::state_model::StateRevision".to_string(),
            value: Value::Null,
            unix_ms: now_ms(),
            content_hash: None,
            flow_ref: None,
            deleted: true,
            operation: None,
        })
        .collect();
    if let Some(horizon) = horizon {
        state.horizon = horizon;
    }
    let retention = StoredRow {
        recorded_version: None,
        capability: "_retention".to_string(),
        key: retention_key,
        rust_type: "feltdb::state_model::StateRevision".to_string(),
        value: serde_json::to_value(&state)?,
        unix_ms: now_ms(),
        content_hash: None,
        flow_ref: None,
        deleted: false,
        operation: None,
    };
    // One append, and memory changes only once it succeeded: an expiry that
    // did not reach the log is not applied here either.
    let mut lines: Vec<&StoredRow> = tombstones.iter().collect();
    lines.push(&retention);
    append_rows_locked(inner, &lines)?;
    if let Some(bucket) = inner.rows.get_mut("state") {
        for tombstone in &tombstones {
            bucket.remove(&tombstone.key);
        }
    }
    inner.put_row(retention);
    Ok(())
}

/// The durable shape of a resource's retention state.
///
/// Mirrors `state_model`'s private record so the write boundary can read and
/// advance the horizon without the store type.
#[derive(Clone, Debug, Default, Serialize, Deserialize)]
struct RetentionRecord {
    policy: state_model::RetentionPolicy,
    horizon: u64,
}

impl FeltDb {
    pub fn open<P: AsRef<Path>>(path: P) -> Result<Self> {
        let requested_path = path.as_ref();
        let parent = requested_path
            .parent()
            .filter(|parent| !parent.as_os_str().is_empty())
            .unwrap_or_else(|| Path::new("."));
        fs::create_dir_all(parent)?;
        let path = if requested_path.exists() {
            fs::canonicalize(requested_path)?
        } else {
            let file_name = requested_path.file_name().ok_or_else(|| {
                std::io::Error::new(
                    std::io::ErrorKind::InvalidInput,
                    "FeltDB database path has no file name",
                )
            })?;
            fs::canonicalize(parent)?.join(file_name)
        };

        let databases = OPEN_DATABASES.get_or_init(|| Mutex::new(HashMap::new()));
        let mut databases = databases.lock().expect("open database registry poisoned");
        if let Some(open) = databases.get(&path) {
            if let (Some(inner), Some(ownership), Some(history)) =
                (open.inner.upgrade(), open.ownership.upgrade(), open.history.upgrade())
            {
                return Ok(Self {
                    inner,
                    event_tx: open.event_tx.clone(),
                    _ownership: ownership,
                    history,
                });
            }
        }
        databases.remove(&path);

        let mut ownership_path = path.as_os_str().to_os_string();
        ownership_path.push(".lock");
        let ownership = OpenOptions::new()
            .create(true)
            .read(true)
            .write(true)
            .open(PathBuf::from(ownership_path))?;
        ownership.try_lock().map_err(|error| match error {
            std::fs::TryLockError::WouldBlock => std::io::Error::new(
                std::io::ErrorKind::WouldBlock,
                format!(
                    "FeltDB database {} is already owned by another process",
                    path.display()
                ),
            ),
            std::fs::TryLockError::Error(error) => error,
        })?;

        // A rewrite this process's predecessor did not finish left its
        // temporary file behind. The log it was replacing is still the log
        // (the switch is the rename), and this process holds the owner lock,
        // so nothing else can be writing it: it is garbage.
        for leftover in ["compact.tmp", "snapshot.tmp"] {
            match fs::remove_file(sibling(&path, leftover)) {
                Ok(()) => {}
                Err(error) if error.kind() == std::io::ErrorKind::NotFound => {}
                Err(error) => return Err(error.into()),
            }
        }

        // Fail closed. The format is decided before any record is interpreted
        // and before anything is written, so a database this build does not
        // understand is refused with its bytes untouched rather than opened
        // with whatever happened to deserialize.
        let accepted_format = match inspect_durable_format(&path)? {
            FormatCompatibility::Incompatible(incompatibility) => {
                return Err(FlowError::IncompatibleFormat(Box::new(incompatibility)));
            }
            FormatCompatibility::Compatible(format) => format,
        };

        if !path.exists() {
            let mut file = OpenOptions::new().create(true).append(true).open(&path)?;
            // A new database states its format in its first record, so it never
            // has to be inferred again.
            write_json_line(
                &mut file,
                &FormatRecord {
                    record_type: FORMAT_RECORD_TYPE.to_string(),
                    format_version: DURABLE_FORMAT_VERSION,
                },
            )?;
            // The file's name must survive a power loss as well as its bytes,
            // or the first acknowledged write could vanish with the file.
            file.sync_data()?;
            sync_parent_directory(&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(),
            durable_format: accepted_format,
            ..Inner::default()
        };

        // Initialize sync state with instance ID
        inner.sync_state = SyncState::new(instance_id);
        replay_log(&mut inner)?;
        load_sync_metadata(&mut inner)?;
        if inner.history.id.is_empty() {
            // A new database, or one an earlier release wrote: every version
            // it holds was issued here, so its history begins at genesis.
            inner.history = VersionHistory::new(HistoryOrigin::Genesis);
            persist_sync_metadata(&inner)?;
        }
        rebuild_revision_heads(&mut inner);

        let (event_tx, _) = broadcast::channel(1024);

        let history = Arc::new(std::sync::RwLock::new(inner.history.clone()));
        let database = Self {
            inner: Arc::new(Mutex::new(inner)),
            event_tx,
            _ownership: Arc::new(ownership),
            history,
        };
        databases.insert(
            path,
            OpenDatabase {
                inner: Arc::downgrade(&database.inner),
                event_tx: database.event_tx.clone(),
                ownership: Arc::downgrade(&database._ownership),
                history: Arc::downgrade(&database.history),
            },
        );
        Ok(database)
    }

    /// Write a self-contained durable backup artifact.
    ///
    /// The artifact does not depend on this database remaining present: it
    /// carries every live record, the revision graph, retention state and the
    /// observed operation versions, plus the digests needed to check all of it
    /// without a live database.
    pub fn write_backup(&self, path: &Path) -> Result<BackupVerification> {
        let (rows, observed_versions) = {
            let inner = self.state();
            let mut rows: Vec<StoredRow> = inner
                .rows
                .values()
                .flat_map(|bucket| bucket.values().cloned())
                .filter(|row| !row.deleted)
                .collect();
            rows.sort_by(|left, right| {
                left.capability
                    .cmp(&right.capability)
                    .then_with(|| left.key.cmp(&right.key))
            });
            (rows, inner.change_log.versions())
        };

        let content_digest = backup_content_digest(&rows)?;
        let meaning_digest = backup_meaning_digest(&rows)?;
        let header = BackupHeader {
            record_type: BACKUP_RECORD_TYPE.to_string(),
            backup_version: BACKUP_VERSION,
            format_version: DURABLE_FORMAT_VERSION,
            created_unix_ms: now_ms() as u64,
            row_count: rows.len(),
            observed_versions,
            content_digest: content_digest.clone(),
            meaning_digest: meaning_digest.clone(),
        };

        if let Some(parent) = path.parent() {
            fs::create_dir_all(parent)?;
        }
        // Written beside the destination and renamed over it only once complete
        // and durable: an interrupted backup never replaces a good artifact
        // with a partial one.
        let partial = sibling(path, "partial");
        let mut file = OpenOptions::new()
            .create(true)
            .write(true)
            .truncate(true)
            .open(&partial)?;
        write_json_line(&mut file, &header)?;
        for row in &rows {
            write_json_line(&mut file, row)?;
        }
        file.flush()?;
        file.sync_all()?;
        drop(file);
        fs::rename(&partial, path)?;
        sync_parent_directory(path)?;

        Ok(BackupVerification {
            backup_version: BACKUP_VERSION,
            format_version: DURABLE_FORMAT_VERSION,
            created_unix_ms: header.created_unix_ms,
            rows: rows.len(),
            content_digest,
            meaning_digest,
        })
    }

    /// Restore a backup artifact into a **new** database.
    ///
    /// Refuses to write over an existing database: a restore that could
    /// overwrite the thing an operator is trying to recover is not a recovery
    /// tool. The artifact is verified first, and the restored database is
    /// verified again afterwards — its meaning is recomputed from the live
    /// database and compared with the artifact's. A restore therefore proves
    /// that the result *means the same thing*, not merely that the file parsed.
    pub fn restore_backup(backup: &Path, target: &Path) -> Result<(Self, BackupVerification)> {
        let verification = verify_backup(backup)?;
        if target.exists() {
            return Err(backup_problem(
                "the restore target already exists",
                None,
                "Restore into a new path. FeltDB will not write over an existing database.",
            ));
        }

        let text = std::fs::read_to_string(backup)?;
        let mut lines = text.lines();
        let header: BackupHeader = serde_json::from_str(lines.next().unwrap_or_default())?;

        if let Some(parent) = target.parent() {
            fs::create_dir_all(parent)?;
        }
        // Restored beside the target and renamed into place only after it has
        // been reopened and proven equivalent. An interrupted restore therefore
        // never leaves a database at `target` -- in particular not a truncated
        // one that would open cleanly holding a subset of the backup.
        let staging = sibling(target, "restoring");
        remove_restore_staging(&staging)?;
        {
            let mut file = OpenOptions::new()
                .create_new(true)
                .write(true)
                .open(&staging)?;
            write_json_line(
                &mut file,
                &FormatRecord {
                    record_type: FORMAT_RECORD_TYPE.to_string(),
                    format_version: header.format_version,
                },
            )?;
            for line in lines {
                if line.trim().is_empty() {
                    continue;
                }
                writeln!(file, "{line}")?;
            }
            file.flush()?;
            file.sync_all()?;
        }

        // The equivalence check, on the staged database reopened from disk.
        // Anything that changed the database's meaning between the artifact
        // and the live result fails here, and nothing is placed at `target`.
        let restored_meaning = {
            let staged = FeltDb::open(&staging)?;
            let inner = staged.state();
            let mut rows: Vec<StoredRow> = inner
                .rows
                .values()
                .flat_map(|bucket| bucket.values().cloned())
                .filter(|row| !row.deleted)
                .collect();
            rows.sort_by(|left, right| {
                left.capability
                    .cmp(&right.capability)
                    .then_with(|| left.key.cmp(&right.key))
            });
            backup_meaning_digest(&rows)?
        };
        if restored_meaning != verification.meaning_digest {
            remove_restore_staging(&staging)?;
            return Err(backup_problem(
                "the restored database does not mean what the backup says it means",
                None,
                "The backup or the restore path is damaged. Do not use this database.",
            ));
        }
        if target.exists() {
            remove_restore_staging(&staging)?;
            return Err(backup_problem(
                "the restore target appeared while the restore was running",
                None,
                "Restore into a new path. FeltDB will not write over an existing database.",
            ));
        }
        fs::rename(&staging, target)?;
        sync_parent_directory(target)?;
        remove_restore_staging(&staging)?;

        let restored = FeltDb::open(target)?;
        Ok((restored, verification))
    }

    /// A digest of this database's **application state**: the records an
    /// application reads, and nothing else.
    ///
    /// Excludes revisions and retention state, so it answers only "do these two
    /// databases hold the same values?". Pair it with
    /// `StateStore::history_digest` to ask the separate and stronger question
    /// of whether they hold the same history — two databases can match on this
    /// and differ completely on that, which is exactly the failure replication
    /// used to have.
    pub fn state_digest(&self) -> Result<String> {
        let inner = self.state();
        let mut entries: Vec<(String, String, String)> = inner
            .rows
            .iter()
            .filter(|(capability, _)| is_versioned(capability))
            .flat_map(|(capability, bucket)| {
                bucket
                    .values()
                    .filter(|row| !row.deleted)
                    .map(move |row| (capability.clone(), row.key.clone(), row.value.to_string()))
            })
            .collect();
        entries.sort();

        let mut hasher = Sha256::new();
        hasher.update(b"feltdb.state.v1");
        for (capability, key, value) in entries {
            hasher.update(capability.as_bytes());
            hasher.update([0u8]);
            hasher.update(key.as_bytes());
            hasher.update([0u8]);
            hasher.update(value.as_bytes());
            hasher.update([0u8]);
        }
        Ok(format!("{:x}", hasher.finalize()))
    }

    /// How far a single-record write is pushed before it returns.
    pub fn durability_mode(&self) -> DurabilityMode {
        self.state().durability_mode
    }

    /// Choose what a successful single-record write guarantees.
    ///
    /// This changes the database's contract, not merely its speed. Transaction
    /// commits always issue a stable-storage barrier and are unaffected.
    pub fn set_durability_mode(&self, mode: DurabilityMode) {
        let mut inner = self.state();
        inner.durability_mode = mode;
        inner.writes_since_barrier = 0;
    }

    /// What this database knows about itself.
    ///
    /// Reports facts the open established — the durable format it was accepted
    /// as, and whether replay discarded an incomplete final append. It reports
    /// nothing it has not observed: **health can expose a proven fact, it
    /// cannot create a stronger guarantee.**
    ///
    /// In particular this says nothing about power-loss durability, which is
    /// unproven, nor about replication or backup state, which have no
    /// operational contract yet.
    pub fn health(&self) -> DatabaseHealth {
        let recovery = self.log_recovery();
        let storage = match &recovery {
            LogRecovery::Clean => StorageHealth::Clean,
            LogRecovery::RecoveredTornTail {
                byte_offset,
                discarded_bytes,
            } => StorageHealth::RecoveredIncompleteWrite {
                byte_offset: *byte_offset,
                discarded_bytes: *discarded_bytes,
            },
        };
        let inner = self.state();
        DatabaseHealth {
            durable_format: inner.durable_format.clone(),
            recovery,
            storage,
            writes: match &inner.write_fault {
                None => WriteAvailability::Available,
                Some(reason) => WriteAvailability::RecoveryRequired {
                    reason: reason.clone(),
                },
            },
        }
    }

    /// What replaying the durable log had to do for this database to open.
    ///
    /// [`LogRecovery::Clean`] means every durable byte was a complete, valid
    /// record. [`LogRecovery::RecoveredTornTail`] means the log ended in an
    /// incomplete append that was discarded — the database is usable and its
    /// **last write did not land**, which is a different fact from healthy and
    /// one an operator has to be able to learn.
    ///
    /// A corrupt log does not reach here at all: it refuses the open.
    pub fn log_recovery(&self) -> LogRecovery {
        self.state().log_recovery.clone()
    }

    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, false)?;
        Ok(())
    }

    /// Insert only if the logical record is absent, deciding presence under the
    /// same lock that appends the operation and mints its first revision.
    pub fn insert_if_absent<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, true)
    }

    /// 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(())
    }

    /// Atomically compare the logical record version and authority epoch before
    /// durably replacing a JSON object. Failed predicates append no operation
    /// and emit no change event.
    pub fn compare_and_set_json(
        &self,
        key: &str,
        expected_version: u64,
        expected_epoch: Option<u64>,
        expected_lease_id: Option<&str>,
        reject_if_diverged: bool,
        mut value: Value,
    ) -> Result<JsonCasResult> {
        let capability = key
            .split_once(':')
            .map(|(cap, _)| cap)
            .unwrap_or("default")
            .to_string();
        let rust_type = type_name::<Value>().to_string();
        let (result, event) = {
            let mut inner = self.state();
            let Some(current) = inner.rows.get(&capability).and_then(|rows| rows.get(key)) else {
                return Ok(JsonCasResult::NotFound);
            };
            let current_version = current
                .value
                .get("__version")
                .and_then(Value::as_u64)
                .unwrap_or(1);
            let current_epoch = current
                .value
                .pointer("/authority/epoch")
                .and_then(Value::as_u64)
                .unwrap_or(0);
            if current_version != expected_version {
                return Ok(JsonCasResult::VersionConflict {
                    current_version,
                    current_epoch,
                });
            }
            if expected_epoch.is_some_and(|expected| expected != current_epoch) {
                return Ok(JsonCasResult::AuthorityConflict {
                    current_version,
                    current_epoch,
                });
            }
            let persisted_lease = current.value.get("lease").filter(|lease| !lease.is_null());
            let lease_matches = match (persisted_lease, expected_lease_id) {
                (None, None) => true,
                (None, Some(_)) => false,
                (Some(lease), Some(expected_id)) => {
                    lease.get("leaseId").and_then(Value::as_str) == Some(expected_id)
                        && lease
                            .get("expiresAt")
                            .and_then(Value::as_u64)
                            .is_some_and(|expires_at| expires_at > now_ms() as u64)
                }
                (Some(lease), None) => lease
                    .get("expiresAt")
                    .and_then(Value::as_u64)
                    .is_some_and(|expires_at| expires_at <= now_ms() as u64),
            };
            if !lease_matches {
                return Ok(JsonCasResult::LeaseConflict {
                    current_version,
                    current_epoch,
                });
            }
            if reject_if_diverged && capability == "_cells" {
                let replica_key = key
                    .strip_prefix("_cells:")
                    .map(|suffix| format!("_replicas:{suffix}"));
                let divergent = replica_key.as_ref().and_then(|replica_key| {
                    inner
                        .rows
                        .get("_replicas")
                        .and_then(|rows| rows.get(replica_key))
                        .and_then(|row| row.value.get("divergent"))
                        .and_then(Value::as_bool)
                }) == Some(true);
                if divergent {
                    return Ok(JsonCasResult::ReplicationConflict {
                        current_version,
                        current_epoch,
                    });
                }
            }

            let object = value.as_object_mut().ok_or_else(|| {
                FlowError::CapabilityError("CAS value must be a JSON object".to_string())
            })?;
            object.insert("__version".to_string(), Value::from(expected_version + 1));

            let reserved = (inner.sequence, inner.sync_state.vector_clock.clone());
            inner.sequence += 1;
            inner.sync_state.increment_vector_clock();
            let vector_clock = inner.sync_state.get_or_init_vector_clock().clone();
            let planned =
                is_versioned(&capability).then(|| plan_revision(&inner, key, value.to_string()));
            let mut operation = Operation::update(
                inner.sequence,
                inner.instance_id.clone(),
                inner.sequence,
                key.to_string(),
                value.clone(),
                rust_type.clone(),
                capability.clone(),
            )
            .with_vector_clock(vector_clock);
            operation.revision = planned.as_ref().map(provenance_of);
            let row = StoredRow {
                recorded_version: None,
                capability: capability.clone(),
                key: key.to_string(),
                rust_type: rust_type.clone(),
                value: value.clone(),
                unix_ms: now_ms(),
                content_hash: Some(operation.content_hash.clone()),
                flow_ref: None,
                deleted: false,
                operation: Some(operation.clone()),
            };
            commit_local_write_locked(&mut inner, &row, planned.as_ref(), reserved)?;
            inner.authority_revision += 1;
            inner.change_log.add_operation(operation);
            inner.put_row(row.clone());
            if let Some(revision) = planned {
                persist_revision_locked(&mut inner, revision)?;
            }
            let event = ChangeEvent {
                capability,
                key: key.to_string(),
                rust_type,
                unix_ms: row.unix_ms,
            };
            (
                JsonCasResult::Updated {
                    current_version: expected_version + 1,
                    current_epoch: value
                        .pointer("/authority/epoch")
                        .and_then(Value::as_u64)
                        .unwrap_or(current_epoch),
                    value,
                },
                event,
            )
        };
        let _ = self.event_tx.send(event);
        Ok(result)
    }

    /// 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(())
    }

    /// Evaluate authorization for a mutation
    fn evaluate_authorization(&self, context: &AuthorizationContext) -> Result<()> {
        // Check basic capabilities
        if !context.capabilities.contains(&"state:write".to_string()) {
            return Err(FlowError::CapabilityError(
                "AUTHORIZATION_DENIED:missing_state_write_capability".to_string(),
            ));
        }

        // Tenant isolation check happens implicitly at mutation boundary
        // by only checking against current database tenant_id

        Ok(())
    }

    /// Insert a record with authorization context
    pub fn insert_with_authorization<T: Serialize>(
        &self,
        key: &str,
        value: T,
        context: &AuthorizationContext,
    ) -> Result<()> {
        // Authorize mutation inside FeltDB boundary
        self.evaluate_authorization(context)?;

        let capability = key
            .split_once(':')
            .map(|(cap, _)| cap)
            .unwrap_or("default")
            .to_string();

        // Check if capability is writable
        if !context.writable_collections.is_empty()
            && !context.writable_collections.contains(&capability)
        {
            return Err(FlowError::CapabilityError(format!(
                "AUTHORIZATION_DENIED:not_writable_collection:{}",
                capability
            )));
        }

        // Authorized: apply mutation
        self.insert_internal(capability, key.to_string(), value, false)?;
        Ok(())
    }

    /// Update a record with authorization context
    pub fn update_with_authorization<T: Serialize>(
        &self,
        key: &str,
        value: T,
        context: &AuthorizationContext,
    ) -> Result<()> {
        // Authorize mutation inside FeltDB boundary
        self.evaluate_authorization(context)?;

        let capability = key
            .split_once(':')
            .map(|(cap, _)| cap)
            .unwrap_or("default")
            .to_string();

        // Check if capability is writable
        if !context.writable_collections.is_empty()
            && !context.writable_collections.contains(&capability)
        {
            return Err(FlowError::CapabilityError(format!(
                "AUTHORIZATION_DENIED:not_writable_collection:{}",
                capability
            )));
        }

        // Authorized: apply mutation
        // Pre-state evaluation would happen here in full implementation
        self.update_internal(capability, key.to_string(), value)?;
        Ok(())
    }

    /// Delete a record with authorization context
    pub fn delete_with_authorization(
        &self,
        key: &str,
        context: &AuthorizationContext,
    ) -> Result<()> {
        // Authorize mutation inside FeltDB boundary
        self.evaluate_authorization(context)?;

        let capability = key
            .split_once(':')
            .map(|(cap, _)| cap)
            .unwrap_or("default")
            .to_string();

        // Check if capability is writable
        if !context.writable_collections.is_empty()
            && !context.writable_collections.contains(&capability)
        {
            return Err(FlowError::CapabilityError(format!(
                "AUTHORIZATION_DENIED:not_writable_collection:{}",
                capability
            )));
        }

        // Authorized: apply mutation
        // Pre-state evaluation would happen here in full implementation
        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.state();
        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.state();
        *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.state();
        inner.adaptive_indexes.contains(&rust_type)
    }

    /// Get the instance ID for this FeltDB instance
    pub fn instance_id(&self) -> Result<String> {
        let inner = self.state();
        Ok(inner.instance_id.clone())
    }

    /// Get the current sequence number for this instance
    pub fn sequence(&self) -> Result<u64> {
        let inner = self.state();
        Ok(inner.sequence)
    }

    /// Revision of the snapshot held by this embedded authority instance.
    /// In multi-process topology callers must use `AuthorityClient::read` to
    /// cross the authority boundary and obtain a current authoritative value.
    pub fn current_revision(&self) -> Result<u64> {
        Ok(self.state().authority_revision)
    }

    /// Capture revision and rows under one lock. Authority reads must never
    /// pair metadata from one commit with state from another.
    pub(crate) fn authority_state(&self) -> (u64, Vec<StoredRow>) {
        let inner = self.state();
        let rows = inner
            .rows
            .values()
            .flat_map(|bucket| bucket.values().cloned())
            .collect();
        (inner.authority_revision, rows)
    }

    /// 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.state();
        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.state();
        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.state();
        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.state();
        let mut keys: Vec<_> = inner
            .rows
            .keys()
            .filter(|k| k.contains(capability_pattern))
            .cloned()
            .collect();
        keys.sort();
        Ok(keys)
    }

    /// The record write path's head per resource: the revision its next
    /// authoritative write will name as parent. Garbage collection treats each
    /// one as a root, so a write can never mint a child of a collected revision.
    pub(crate) fn revision_head_ids(&self) -> Vec<state_model::StateId> {
        self.state()
            .revision_heads
            .values()
            .map(|(id, _)| id.clone())
            .collect()
    }

    /// The original commit of a transaction id, if it committed, exactly as a
    /// retry of it through `apply_atomic_transaction_*` would report it: the
    /// original revisions and positions (`duplicate: true`), or
    /// `TransactionIdPayloadMismatch` when `payload_hash` differs from the one
    /// the id was committed with. Read-only.
    pub fn committed_transaction(
        &self,
        transaction_id: &str,
        payload_hash: Option<&str>,
    ) -> Result<Option<AtomicCommit>> {
        let inner = self.state();
        committed_transaction_locked(&inner, transaction_id, payload_hash).transpose()
    }

    pub fn has_applied_transaction(&self, transaction_id: &str) -> Result<bool> {
        Ok(self
            .inner
            .lock()
            .expect("lock poisoned")
            .applied_transactions
            .contains(transaction_id))
    }

    pub fn applied_transaction_payload_hash(&self, transaction_id: &str) -> Result<Option<String>> {
        Ok(self
            .inner
            .lock()
            .expect("lock poisoned")
            .transaction_payload_hashes
            .get(transaction_id)
            .cloned())
    }

    /// 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> {
        self.apply_atomic_transaction_content_addressed(
            transaction_id,
            None,
            expected_parent,
            preconditions,
            mutations,
            audit,
        )
    }

    /// Applies a transaction whose identifier is durably bound to a canonical
    /// payload hash. The same ID with a different payload is always a conflict.
    pub fn apply_atomic_transaction_content_addressed(
        &self,
        transaction_id: &str,
        payload_hash: Option<&str>,
        expected_parent: Option<u64>,
        preconditions: &[AtomicPrecondition],
        mutations: &[AtomicMutation],
        audit: Option<Value>,
    ) -> Result<AtomicCommit> {
        self.apply_atomic_transaction_guarded(
            transaction_id,
            payload_hash,
            expected_parent,
            preconditions,
            &[],
            mutations,
            audit,
        )
    }

    /// Commit a transaction only if every record precondition holds.
    ///
    /// The preconditions are evaluated inside the same lock as the writes and
    /// before any of them, so there is no state in which one record is checked
    /// while the others commit. A failure returns
    /// `FlowError::PreconditionFailed` and applies nothing -- not a prefix, not
    /// the guarded record, nothing.
    ///
    /// A failed precondition does **not** consume the transaction id. The id is
    /// recorded only after a commit, so a caller that loses a race may retry
    /// the same id once it has re-read state, and a caller that wants the
    /// retry to be a distinct decision may use a new one. Both work; the choice
    /// is the caller's and is asserted in the tests rather than left implied.
    #[allow(clippy::too_many_arguments)]
    pub fn apply_atomic_transaction_guarded(
        &self,
        transaction_id: &str,
        payload_hash: Option<&str>,
        expected_parent: Option<u64>,
        preconditions: &[AtomicPrecondition],
        record_preconditions: &[RecordPrecondition],
        mutations: &[AtomicMutation],
        audit: Option<Value>,
    ) -> Result<AtomicCommit> {
        self.apply_atomic_transaction_fenced(
            transaction_id,
            payload_hash,
            expected_parent,
            preconditions,
            record_preconditions,
            &[],
            mutations,
            audit,
        )
    }

    /// Capture a read basis on the direct route, under the same lock every commit takes.
    pub fn read_basis(&self, reads: &ReadSet) -> Result<ReadBasis> {
        self.read_basis_in(reads, &ReadLayout::Direct)
    }

    /// Capture a read basis in a storage layout, under the same lock every commit takes.
    pub fn read_basis_in(&self, reads: &ReadSet, layout: &ReadLayout) -> Result<ReadBasis> {
        let reads = reads.normalised()?;
        let inner = self.state();
        let token = read_basis_token(&inner.rows, &reads, layout);
        Ok(ReadBasis { reads, token })
    }

    /// `apply_atomic_transaction_guarded`, additionally fenced by read bases.
    ///
    /// Each basis is re-evaluated inside the same lock as the writes, after the
    /// record preconditions and before anything is staged. If the state it
    /// names differs from what was read -- whichever write path changed it --
    /// the transaction fails with `PreconditionFailed(Fence)` and applies
    /// nothing. State outside every basis is never read and never conflicts.
    #[allow(clippy::too_many_arguments)]
    pub fn apply_atomic_transaction_fenced(
        &self,
        transaction_id: &str,
        payload_hash: Option<&str>,
        expected_parent: Option<u64>,
        preconditions: &[AtomicPrecondition],
        record_preconditions: &[RecordPrecondition],
        fences: &[ReadBasis],
        mutations: &[AtomicMutation],
        audit: Option<Value>,
    ) -> Result<AtomicCommit> {
        self.apply_atomic_transaction_fenced_in(
            transaction_id,
            payload_hash,
            expected_parent,
            preconditions,
            record_preconditions,
            &ReadLayout::Direct,
            fences,
            mutations,
            audit,
        )
    }

    /// `apply_atomic_transaction_fenced`, with the read bases addressed in
    /// `layout`. The same evaluation, inside the same lock, for every route.
    #[allow(clippy::too_many_arguments)]
    pub fn apply_atomic_transaction_fenced_in(
        &self,
        transaction_id: &str,
        payload_hash: Option<&str>,
        expected_parent: Option<u64>,
        preconditions: &[AtomicPrecondition],
        record_preconditions: &[RecordPrecondition],
        layout: &ReadLayout,
        fences: &[ReadBasis],
        mutations: &[AtomicMutation],
        audit: Option<Value>,
    ) -> Result<AtomicCommit> {
        self.apply_atomic_transaction_collection_fenced_in(
            transaction_id,
            payload_hash,
            expected_parent,
            preconditions,
            record_preconditions,
            layout,
            fences,
            &[],
            mutations,
            audit,
        )
    }

    /// `apply_atomic_transaction_fenced_in`, plus collection fences: each
    /// `(capability, version)` commits only if nothing in that collection was
    /// written, replaced or removed since the decision read it at `version`
    /// (`consistent_rows`). For a decision that depends on the absence of any
    /// matching record where no equality predicate can name the match -- a
    /// non-sparse unique tuple that is entirely null or missing.
    pub(crate) fn apply_atomic_transaction_collection_fenced_in(
        &self,
        transaction_id: &str,
        payload_hash: Option<&str>,
        expected_parent: Option<u64>,
        preconditions: &[AtomicPrecondition],
        record_preconditions: &[RecordPrecondition],
        layout: &ReadLayout,
        fences: &[ReadBasis],
        collection_fences: &[(String, u64)],
        mutations: &[AtomicMutation],
        audit: Option<Value>,
    ) -> Result<AtomicCommit> {
        let (commit, events) = {
            let mut inner = self.state();
            if let Some(duplicate) =
                committed_transaction_locked(&inner, transaction_id, payload_hash)
            {
                return duplicate;
            }
            // Record preconditions, evaluated before anything is staged and
            // under the same lock the writes take. A caller reads state,
            // decides, and commits; this is the fence that makes the decision
            // still true at the moment of the write.
            for condition in record_preconditions {
                if condition.is_empty() {
                    return Err(FlowError::CapabilityError(format!(
                        "EMPTY_PRECONDITION:{}:{}",
                        condition.capability, condition.key
                    )));
                }
                let collection = condition.capability.clone();
                let key = condition.key.clone();
                let current = inner
                    .rows
                    .get(&condition.capability)
                    .and_then(|bucket| bucket.get(&condition.key));

                if condition.require_absent {
                    if current.is_some() {
                        return Err(FlowError::PreconditionFailed(Box::new(
                            PreconditionFailure::Present { collection, key },
                        )));
                    }
                    continue;
                }

                let Some(current) = current else {
                    return Err(FlowError::PreconditionFailed(Box::new(
                        PreconditionFailure::Missing { collection, key },
                    )));
                };

                // The same fields single-record CAS compares, read the same way.
                if let Some(expected) = condition.expected_version {
                    let actual = current
                        .value
                        .get("__version")
                        .and_then(Value::as_u64)
                        .unwrap_or(1);
                    if actual != expected {
                        return Err(FlowError::PreconditionFailed(Box::new(
                            PreconditionFailure::Version {
                                collection,
                                key,
                                expected,
                                actual,
                            },
                        )));
                    }
                }
                if let Some(expected) = condition.expected_epoch {
                    let actual = current
                        .value
                        .pointer("/authority/epoch")
                        .and_then(Value::as_u64)
                        .unwrap_or(0);
                    if actual != expected {
                        return Err(FlowError::PreconditionFailed(Box::new(
                            PreconditionFailure::Epoch {
                                collection,
                                key,
                                expected,
                                actual,
                            },
                        )));
                    }
                }
                if let Some(expected) = &condition.expected_lease_id {
                    let lease = current.value.get("lease").filter(|lease| !lease.is_null());
                    let held = lease.and_then(|lease| {
                        lease
                            .get("leaseId")
                            .and_then(Value::as_str)
                            .map(str::to_string)
                    });
                    // An expired lease is not held, so naming it is a conflict:
                    // the caller believes it owns something it no longer does.
                    let unexpired = lease
                        .and_then(|lease| lease.get("expiresAt").and_then(Value::as_u64))
                        .is_some_and(|expires_at| expires_at > now_ms() as u64);
                    if held.as_deref() != Some(expected.as_str()) || !unexpired {
                        return Err(FlowError::PreconditionFailed(Box::new(
                            PreconditionFailure::Lease {
                                collection,
                                key,
                                expected: expected.clone(),
                                actual: held,
                            },
                        )));
                    }
                }
            }

            for fence in fences {
                if !fence.token.starts_with(&layout.token_prefix()) {
                    return Err(FlowError::CapabilityError(
                        "INVALID_READ_SET:a read basis was not issued by this authority scope"
                            .into(),
                    ));
                }
                let reads = fence.reads.normalised()?;
                let actual = read_basis_token(&inner.rows, &reads, layout);
                if actual != fence.token {
                    let collection = reads
                        .records
                        .first()
                        .map(|record| record.collection.clone())
                        .or_else(|| {
                            reads
                                .predicates
                                .first()
                                .map(|predicate| predicate.collection.clone())
                        })
                        .unwrap_or_default();
                    return Err(FlowError::PreconditionFailed(Box::new(
                        PreconditionFailure::Fence {
                            collection,
                            key: "read-basis".into(),
                            expected: fence.token.clone(),
                            actual,
                        },
                    )));
                }
            }
            for (capability, expected) in collection_fences {
                let actual = inner.collection_versions.get(capability).copied().unwrap_or(0);
                if actual != *expected {
                    return Err(FlowError::PreconditionFailed(Box::new(
                        PreconditionFailure::Fence {
                            collection: capability.clone(),
                            key: COLLECTION_FENCE_KEY.into(),
                            expected: format!("collection-version:{expected}"),
                            actual: format!("collection-version:{actual}"),
                        },
                    )));
                }
            }

            // Every precondition held. The authority owns both ends of the
            // public document-version lifecycle inside this lock:
            //
            // - a create protected by `requireAbsent` writes version 1;
            // - a write fenced by `expected_version = N` writes N + 1.
            //
            // An unconditional write remains verbatim, and a guard-only
            // precondition writes nothing. See
            // docs/architecture/transaction-version-contract.md.
            let advanced: Vec<AtomicMutation>;
            let creates: HashSet<(&str, &str)> = preconditions
                .iter()
                .filter(|condition| condition.expected_version.is_none())
                .map(|condition| (condition.capability.as_str(), condition.key.as_str()))
                .chain(
                    record_preconditions
                        .iter()
                        .filter(|condition| condition.require_absent)
                        .map(|condition| (condition.capability.as_str(), condition.key.as_str())),
                )
                .collect();
            let fenced: HashMap<(&str, &str), u64> = record_preconditions
                .iter()
                .filter_map(|condition| {
                    condition.expected_version.map(|version| {
                        (
                            (condition.capability.as_str(), condition.key.as_str()),
                            version,
                        )
                    })
                })
                .collect();
            let mutations: &[AtomicMutation] = if fenced.is_empty() && creates.is_empty() {
                mutations
            } else {
                advanced = mutations
                    .iter()
                    .map(|mutation| {
                        let record = (mutation.capability.as_str(), mutation.key.as_str());
                        let version = if creates.contains(&record) {
                            Some(1)
                        } else {
                            fenced.get(&record).map(|expected| expected + 1)
                        };
                        let Some(version) = version else {
                            return mutation.clone();
                        };
                        // A delete has no record left to carry a version, so a
                        // fenced delete is fence-then-remove and nothing more.
                        let Some(Value::Object(fields)) = mutation.value.clone() else {
                            return mutation.clone();
                        };
                        let mut fields = fields;
                        // The caller cannot manufacture either the initial or
                        // next authoritative version.
                        fields.insert("__version".to_string(), Value::from(version));
                        AtomicMutation {
                            capability: mutation.capability.clone(),
                            key: mutation.key.clone(),
                            value: Some(Value::Object(fields)),
                        }
                    })
                    .collect();
                &advanced
            };

            // Transaction bookkeeping is measured as one span per commit even
            // though it brackets two regions: everything before the durable
            // append, and the revision, dedup and payload-hash accounting after
            // the rows are applied. The append itself is `Persistence` and the
            // apply loop is `RecordMutation` + `IndexMaintenance`, so summing
            // this with those does not double-count any of them.
            let mut bookkeeping_nanos = 0u64;
            let prepare_began = workload_diagnostics::enabled().then(std::time::Instant::now);
            let base_revision = inner.authority_revision;
            if let Some(expected) = expected_parent {
                if expected != base_revision {
                    return Err(FlowError::RevisionConflict {
                        expected,
                        actual: base_revision,
                    });
                }
            }
            for condition in preconditions {
                let actual = inner
                    .rows
                    .get(&condition.capability)
                    .and_then(|bucket| bucket.get(&condition.key))
                    .and_then(StoredRow::version);
                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 {
                    recorded_version: None,
                    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(),
                payload_hash: payload_hash.map(str::to_owned),
                state_before,
                state_after: next_sequence,
                base_revision,
                commit_revision: base_revision + 1,
                rows: rows.clone(),
                audit,
            };
            if let Some(began) = prepare_began {
                bookkeeping_nanos += began.elapsed().as_nanos().min(u64::MAX as u128) as u64;
            }
            append_transaction_locked(&mut inner, &record)?;
            // Retained from the record that was just made durable, so the
            // in-memory answer to "who committed this" cannot describe a
            // transaction the log does not hold.
            remember_attribution(
                &mut inner,
                TransactionAttribution::from_record(
                    transaction_id,
                    record.audit.as_ref(),
                    base_revision,
                    base_revision + 1,
                    state_before,
                    next_sequence,
                    &record.rows,
                    now_ms(),
                ),
            );
            inner.authority_revision = base_revision + 1;
            inner.sequence = next_sequence;
            for row in &rows {
                if let Some(operation) = row.operation.clone() {
                    inner.change_log.add_operation(operation);
                }
                if row.deleted {
                    inner.remove_row(&row.capability, &row.key);
                } else {
                    // Record and index change together, inside the commit that
                    // is already holding the state lock: a transaction that is
                    // refused leaves neither, and one that commits publishes both.
                    inner.put_row(row.clone());
                }
            }
            let tail_began = workload_diagnostics::enabled().then(std::time::Instant::now);
            inner.sync_state.merge_vector_clock(&vector_clock);
            inner.applied_transactions.insert(transaction_id.into());
            let commit_revision = inner.authority_revision;
            inner
                .transaction_revisions
                .insert(transaction_id.into(), (base_revision, commit_revision));
            if let Some(hash) = payload_hash {
                inner
                    .transaction_payload_hashes
                    .insert(transaction_id.into(), hash.into());
            }
            if let Some(began) = tail_began {
                bookkeeping_nanos += began.elapsed().as_nanos().min(u64::MAX as u128) as u64;
            }
            workload_diagnostics::record(
                workload_diagnostics::Phase::TransactionCommit,
                bookkeeping_nanos,
            );
            let events = rows
                .iter()
                .map(|row| ChangeEvent {
                    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(),
                    base_revision,
                    commit_revision: inner.authority_revision,
                    status: TransactionStatus::Committed,
                    state_before,
                    state_after: inner.sequence,
                    rows,
                    duplicate: false,
                    payload_binding: None,
                },
                events,
            )
        };
        for event in events {
            let _ = self.event_tx.send(event);
        }
        Ok(commit)
    }

    /// Apply atomic transaction with authorization context (atomic rejection on deny)
    pub fn apply_atomic_transaction_with_authorization(
        &self,
        transaction_id: &str,
        expected_parent: Option<u64>,
        preconditions: &[AtomicPrecondition],
        mutations: &[AtomicMutation],
        audit: Option<Value>,
        context: &AuthorizationContext,
    ) -> Result<AtomicCommit> {
        // Authorize ALL mutations before applying ANY of them (atomicity guarantee)
        self.evaluate_authorization(context)?;

        // Check writable collections for all mutations
        for mutation in mutations {
            if !context.writable_collections.is_empty()
                && !context.writable_collections.contains(&mutation.capability)
            {
                return Err(FlowError::CapabilityError(format!(
                    "AUTHORIZATION_DENIED:not_writable_collection:{}",
                    mutation.capability
                )));
            }
        }

        // All authorized: proceed with atomic transaction (no partial application)
        self.apply_atomic_transaction(
            transaction_id,
            expected_parent,
            preconditions,
            mutations,
            audit,
        )
    }

    fn insert_internal<T: Serialize>(
        &self,
        capability: String,
        key: String,
        value: T,
        require_absent: bool,
    ) -> Result<()> {
        let rust_type = type_name::<T>().to_string();
        let value_json = serde_json::to_value(value)?;
        // Canonical because `serde_json` is built without `preserve_order`, so
        // `Map` is a `BTreeMap` and `to_string` emits keys in sorted order.
        let canonical = value_json.to_string();
        let mut row = StoredRow {
            recorded_version: None,
            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.state();

            if require_absent
                && inner
                    .rows
                    .get(&capability)
                    .and_then(|bucket| bucket.get(&key))
                    .is_some()
            {
                return Err(FlowError::PreconditionFailed(Box::new(
                    PreconditionFailure::Present {
                        collection: capability,
                        key,
                    },
                )));
            }

            let reserved = (inner.sequence, inner.sync_state.vector_clock.clone());
            inner.sequence += 1;
            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();

            // The revision this write produces is worked out first, so the
            // operation can name it and a peer can rebuild the same one.
            let planned =
                is_versioned(&capability).then(|| plan_revision(&inner, &key, canonical.clone()));

            // Create an operation with vector clock for convergence
            let mut 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);
            op.revision = planned.as_ref().map(provenance_of);

            // The operation enters the change log only once its record is
            // durable: replication must never send a write the log lacks.
            row.operation = Some(op.clone());
            commit_local_write_locked(&mut inner, &row, planned.as_ref(), reserved)?;
            inner.change_log.add_operation(op);
            let base_revision = inner.authority_revision;
            inner.authority_revision += 1;
            remember_operation_attribution(&mut inner, &row, base_revision, base_revision + 1);
            inner.put_row(row);
            if let Some(revision) = planned {
                persist_revision_locked(&mut inner, revision)?;
            }
            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)?;
        // Canonical because `serde_json` is built without `preserve_order`, so
        // `Map` is a `BTreeMap` and `to_string` emits keys in sorted order.
        let canonical = value_json.to_string();
        let mut row = StoredRow {
            recorded_version: None,
            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.state();

            let reserved = (inner.sequence, inner.sync_state.vector_clock.clone());
            inner.sequence += 1;
            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();

            let planned =
                is_versioned(&capability).then(|| plan_revision(&inner, &key, canonical.clone()));

            // Create an update operation with vector clock for convergence
            let mut 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);
            op.revision = planned.as_ref().map(provenance_of);

            // The operation enters the change log only once its record is
            // durable: replication must never send a write the log lacks.
            row.operation = Some(op.clone());
            commit_local_write_locked(&mut inner, &row, planned.as_ref(), reserved)?;
            inner.change_log.add_operation(op);
            let base_revision = inner.authority_revision;
            inner.authority_revision += 1;
            remember_operation_attribution(&mut inner, &row, base_revision, base_revision + 1);
            inner.put_row(row);
            if let Some(revision) = planned {
                persist_revision_locked(&mut inner, revision)?;
            }
        }

        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.state();

            // 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());

            let reserved = (inner.sequence, inner.sync_state.vector_clock.clone());
            inner.sequence += 1;
            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);

            // 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 {
                recorded_version: None,
                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.clone()),
            };
            commit_local_write_locked(&mut inner, &tombstone, None, reserved)?;
            // Only a durable tombstone is offered to replication.
            inner.change_log.add_operation(op);
            let base_revision = inner.authority_revision;
            inner.authority_revision += 1;
            remember_operation_attribution(
                &mut inner,
                &tombstone,
                base_revision,
                base_revision + 1,
            );

            // Remove from in-memory store, index entries included.
            inner.remove_row(&capability, &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 mut inner = self.state();
            *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());
            }
        }
        // Subscribe before the initial read, so no change between the two is lost.
        let rx = self.event_tx.subscribe();
        let mut matches = LiveMatches::new(rust_type, None);
        matches.rescan(self, &predicate);
        let subscription = LiveQuerySubscription {
            initial_results: matches.results(),
            rx,
            db: self.clone(),
            matches,
            predicate: Arc::new(Mutex::new(Some(Box::new(predicate)))),
        };

        Ok(subscription)
    }

    /// Get current sync state information
    pub fn sync_info(&self) -> Result<SyncState> {
        let inner = self.state();
        Ok(inner.sync_state.clone())
    }

    /// The authority's wall-clock time in milliseconds.
    ///
    /// The same reading the commit-time lease predicate uses, exposed so a
    /// decision that depends on lease expiry can be made against the clock that
    /// will later judge the commit. A caller's own clock is never a substitute.
    pub fn authority_time_ms(&self) -> u64 {
        now_ms() as u64
    }

    /// 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)
    }

    /// One live row of a collection by its key, cloned under the state lock.
    ///
    /// A keyed lookup, not a scan: callers that know the canonical key of the
    /// record they need (Durable Work's projection refresh, for one) use this
    /// rather than a predicate over the whole collection.
    pub(crate) fn live_row(&self, capability: &str, key: &str) -> Option<StoredRow> {
        let inner = self.state();
        inner
            .rows
            .get(capability)
            .and_then(|rows| rows.get(key))
            .filter(|row| !row.deleted)
            .cloned()
    }

    /// List the canonical values in one collection/capability namespace.
    ///
    /// This clones the whole collection, so its cost is linear in collection
    /// size. Readers that discard most of what they receive — a filtered query,
    /// for example — should use [`FeltDb::query_collection`] instead, which
    /// evaluates borrowed rows and clones only what it keeps.
    /// Whole capabilities and single records, read under one acquisition of
    /// the state lock: one consistent view, for a decision whose read basis is
    /// then fenced at commit (`state_contract`). A whole capability is returned
    /// as stored, tombstones included, like `list_collection`; a single record
    /// only when it is live, like `get_collection_record`.
    pub(crate) fn consistent_rows(
        &self,
        capabilities: &BTreeSet<String>,
        records: &BTreeSet<(String, String)>,
    ) -> ConsistentRows {
        let inner = self.state();
        let versions = capabilities
            .iter()
            .map(|capability| {
                (
                    capability.clone(),
                    inner.collection_versions.get(capability).copied().unwrap_or(0),
                )
            })
            .collect();
        let mut view: HashMap<String, BTreeMap<String, StoredRow>> = HashMap::new();
        for capability in capabilities {
            if let Some(bucket) = inner.rows.get(capability) {
                query_execution_diagnostics::record_full_materialization(bucket.len());
                view.insert(capability.clone(), bucket.clone());
            }
        }
        for (capability, key) in records {
            if capabilities.contains(capability) {
                continue;
            }
            if let Some(row) = inner
                .rows
                .get(capability)
                .and_then(|bucket| bucket.get(key))
                .filter(|row| !row.deleted)
            {
                view.entry(capability.clone())
                    .or_default()
                    .insert(key.clone(), row.clone());
            }
        }
        ConsistentRows { view, versions }
    }

    pub fn list_collection(&self, capability: &str) -> Result<Vec<StoredRow>> {
        let inner = self.state();
        let rows: Vec<StoredRow> = inner
            .rows
            .get(capability)
            .map(|rows| rows.values().cloned().collect())
            .unwrap_or_default();
        query_execution_diagnostics::record_full_materialization(rows.len());
        Ok(rows)
    }

    /// Evaluate a predicate over one collection without materializing it.
    ///
    /// The predicate observes each live row *borrowed* from state, so a record
    /// the predicate rejects is never cloned. Only retained rows are cloned,
    /// which happens while state protection is still held: the returned rows are
    /// owned, so nothing the caller keeps can reference storage a concurrent
    /// mutation may move or drop after the lock is released.
    ///
    /// Traversal is the collection's own record-key order, the same order
    /// [`FeltDb::list_collection_page`] walks. `limit` bounds accumulation and
    /// stops the traversal as soon as it is satisfied; because early stopping
    /// truncates in record-key order, a caller that must order results by some
    /// other field has to pass `None` and bound its own already-filtered set.
    ///
    /// The predicate runs under the state lock, so it must not call back into
    /// the database or block.
    pub fn query_collection<F>(
        &self,
        capability: &str,
        limit: Option<usize>,
        mut predicate: F,
    ) -> Result<Vec<StoredRow>>
    where
        F: FnMut(&StoredRow) -> bool,
    {
        let mut matched = Vec::new();
        let mut visited = 0usize;
        {
            let inner = self.state();
            let _query = workload_diagnostics::span(workload_diagnostics::Phase::ScanQuery);
            if let Some(rows) = inner.rows.get(capability) {
                for row in rows.values() {
                    if limit.is_some_and(|bound| matched.len() >= bound) {
                        break;
                    }
                    visited += 1;
                    // The same predicate phase the indexed execution reports to,
                    // so the two executions' predicate cost is directly
                    // comparable rather than being two different measurements.
                    let _predicate = workload_diagnostics::span(
                        workload_diagnostics::Phase::PredicateEvaluation,
                    );
                    if predicate(row) {
                        drop(_predicate);
                        matched.push(row.clone());
                    }
                }
            }
        }
        query_execution_diagnostics::record_scan(visited, matched.len());
        Ok(matched)
    }

    // ----------------------------------------------------------------------
    // Equality index — lifecycle and execution.
    //
    // The index is derived state. Every method below either declares what is
    // derived, re-derives it from authoritative records, or reads candidate
    // record keys out of it. None of them is a source of truth, and none of
    // them can answer a query on its own: `query_collection_by_equality` still
    // evaluates the caller's full predicate against authoritative records.
    // ----------------------------------------------------------------------

    /// Acquire the state lock, attributing the wait and the hold.
    ///
    /// Every path in this file that touches authoritative state goes through
    /// here, which is what makes lock contention a measured quantity rather than
    /// a residual inferred from wall-clock time.
    fn state(&self) -> StateGuard<'_> {
        if !workload_diagnostics::enabled() {
            return StateGuard {
                inner: self.inner.lock().expect("lock poisoned"),
                held_since: None,
            };
        }
        let requested = std::time::Instant::now();
        let inner = self.inner.lock().expect("lock poisoned");
        let acquired = std::time::Instant::now();
        workload_diagnostics::record(
            workload_diagnostics::Phase::StateLockWait,
            acquired
                .duration_since(requested)
                .as_nanos()
                .min(u64::MAX as u128) as u64,
        );
        StateGuard {
            inner,
            held_since: Some(acquired),
        }
    }

    /// Declare an equality index on one collection field and populate it from
    /// authoritative state. Returns whether this call created the index.
    ///
    /// Creation and population happen under one lock, so an index is never
    /// observable in a half-built state. Declaring an index that already exists
    /// is not an error and does not rebuild it.
    ///
    /// `recordId` is refused: on the query surface it is authority metadata that
    /// shadows a document field of the same name on object-valued records only,
    /// so an index over the document field would answer a different question
    /// from the one the predicate asks.
    pub fn create_equality_index(&self, collection: &str, field: &str) -> Result<bool> {
        let mut inner = self.state();
        let created = inner
            .equality_index
            .declare(collection, field)
            .map_err(FlowError::CapabilityError)?;
        if created {
            let Inner {
                rows,
                equality_index,
                ..
            } = &mut *inner;
            equality_index.rebuild_field(collection, field, rows);
        }
        Ok(created)
    }

    /// Drop an equality index and its buckets. Returns whether one existed.
    pub fn drop_equality_index(&self, collection: &str, field: &str) -> Result<bool> {
        let mut inner = self.state();
        Ok(inner.equality_index.undeclare(collection, field))
    }

    /// Every declared index, as `(collection, field)` in a stable order.
    pub fn equality_indexes(&self) -> Result<Vec<(String, String)>> {
        let inner = self.state();
        Ok(inner.equality_index.declarations())
    }

    /// Re-derive every declared index from authoritative records.
    ///
    /// This is the recovery path. An index is never read from disk and never
    /// received from a peer: after a restart, a snapshot install, or any other
    /// reload of authoritative state, the index is whatever this produces.
    pub fn rebuild_equality_indexes(&self) -> Result<EqualityIndexStats> {
        let mut inner = self.state();
        let Inner {
            rows,
            equality_index,
            ..
        } = &mut *inner;
        equality_index.rebuild(rows);
        Ok(equality_index.stats())
    }

    /// Index size, as counts. Never a value, never a record id.
    pub fn equality_index_stats(&self) -> Result<EqualityIndexStats> {
        let inner = self.state();
        Ok(inner.equality_index.stats())
    }

    /// A fully ordered rendering of the live index.
    ///
    /// Test instrumentation. It exists so a test can compare the live index
    /// against one rebuilt from authoritative state; nothing in execution reads
    /// it, and it is not part of any product surface.
    #[doc(hidden)]
    pub fn equality_index_snapshot(
        &self,
    ) -> Result<BTreeMap<String, BTreeMap<String, BTreeMap<String, Vec<String>>>>> {
        let inner = self.state();
        Ok(inner.equality_index.snapshot())
    }

    /// The index invariant: the live index equals one derived from records now.
    ///
    /// Returns a description of the first divergence rather than a bare bool, so
    /// a failing assertion says what diverged. This is the strongest statement
    /// available about index maintenance, because it compares the maintained
    /// structure against the authoritative state it claims to describe rather
    /// than against a second copy of its own bookkeeping.
    pub fn verify_equality_index(&self) -> Result<std::result::Result<(), String>> {
        let inner = self.state();
        let live = inner.equality_index.snapshot();
        let mut expected = inner.equality_index.clone();
        expected.clear();
        expected.rebuild(&inner.rows);
        let expected = expected.snapshot();
        if live == expected {
            return Ok(Ok(()));
        }
        for (collection, fields) in expected.iter() {
            for (field, buckets) in fields {
                let observed = live.get(collection).and_then(|fields| fields.get(field));
                if observed != Some(buckets) {
                    return Ok(Err(format!(
                        "index for {collection}.{field} diverges from authoritative state: \
                         {} value buckets held, {} derived",
                        observed.map(BTreeMap::len).unwrap_or(0),
                        buckets.len(),
                    )));
                }
            }
        }
        Ok(Err(
            "the live index holds entries no authoritative record derives".to_string(),
        ))
    }

    /// Candidate record keys for one equality condition, copied out of the index.
    ///
    /// `None` means the index cannot answer that condition — the field is not
    /// indexed, or the value is not an indexable scalar — and the caller must
    /// fall back to a scan. `Some(empty)` is an answer, not a failure.
    ///
    /// The keys are copied while the state lock is held. Nothing borrowed from
    /// the index or from the record map escapes this call.
    pub fn equality_index_candidates(
        &self,
        collection: &str,
        field: &str,
        value: &Value,
    ) -> Result<Option<Vec<String>>> {
        let inner = self.state();
        Ok(inner
            .equality_index
            .candidates(collection, field, value)
            .map(|keys| keys.iter().cloned().collect()))
    }

    /// Execute a bounded query through the equality index when one applies.
    ///
    /// `equalities` are the query's equality conditions, in the caller's order.
    /// At least one of them must be indexed and hold an indexable value, or this
    /// returns `Ok(None)` and the caller falls back to [`FeltDb::query_collection`].
    /// Returning `None` rather than an empty result is the difference between
    /// "the index does not apply" and "nothing matches", and conflating the two
    /// would silently drop records.
    ///
    /// When the index does apply, every applicable condition contributes a
    /// candidate set and the sets are intersected smallest-first. The result is
    /// still only *candidates*: `predicate` — the caller's existing, unmodified
    /// predicate — decides what matches, evaluated against authoritative records.
    /// The index therefore cannot change what a query returns, only how many
    /// records the predicate has to look at.
    ///
    /// Candidate keys, the record lookups they drive and the predicate all run
    /// under one acquisition of the state lock, so a query observes one coherent
    /// committed state exactly as a scan does. Records are cloned only when the
    /// predicate keeps them, and nothing borrowed from state outlives the lock.
    pub fn query_collection_by_equality<F>(
        &self,
        capability: &str,
        equalities: &[(&str, &Value)],
        mut predicate: F,
    ) -> Result<Option<Vec<StoredRow>>>
    where
        F: FnMut(&StoredRow) -> bool,
    {
        let mut matched = Vec::new();
        let mut examined = 0usize;
        let mut evaluated = 0usize;
        {
            let inner = self.state();
            let _query = workload_diagnostics::span(workload_diagnostics::Phase::IndexedQuery);
            // Candidate selection, timed apart from record access: PR36 has to
            // be able to say whether the index lookup itself has become a cost,
            // and "index query time" alone could not distinguish a slow lookup
            // from a large candidate set.
            let lookup = workload_diagnostics::span(workload_diagnostics::Phase::IndexLookup);
            let mut applicable: Vec<&BTreeSet<String>> = Vec::new();
            for (field, value) in equalities {
                if let Some(keys) = inner.equality_index.candidates(capability, field, value) {
                    applicable.push(keys);
                }
            }
            if applicable.is_empty() {
                drop(lookup);
                drop(_query);
                drop(inner);
                query_execution_diagnostics::record_index_miss();
                return Ok(None);
            }
            // Smallest first. This is not cost estimation: a set's length is
            // already held by the set, so intersecting from the smallest is
            // simply the cheaper order to do the same work.
            applicable.sort_by_key(|keys| keys.len());
            drop(lookup);
            let (smallest, rest) = applicable.split_first().expect("non-empty");
            let bucket = inner.rows.get(capability);
            for key in smallest.iter() {
                if !rest.iter().all(|keys| keys.contains(key)) {
                    continue;
                }
                examined += 1;
                let retrieval =
                    workload_diagnostics::span(workload_diagnostics::Phase::CandidateRetrieval);
                let row = bucket.and_then(|rows| rows.get(key));
                drop(retrieval);
                let Some(row) = row else {
                    // An index entry with no record behind it would be a
                    // maintenance defect. Skipping it keeps the query correct
                    // rather than surfacing a record that does not exist.
                    continue;
                };
                evaluated += 1;
                let _predicate =
                    workload_diagnostics::span(workload_diagnostics::Phase::PredicateEvaluation);
                if predicate(row) {
                    drop(_predicate);
                    matched.push(row.clone());
                }
            }
        }
        query_execution_diagnostics::record_indexed_query(examined, evaluated, matched.len());
        Ok(Some(matched))
    }

    /// Select one bounded page of a collection: at most `limit` matching rows in
    /// the caller's total order, strictly after the caller's cursor, and whether
    /// more remain.
    ///
    /// The engine owns *how* rows are found; the caller owns *what* matches and
    /// *how* rows compare, so every query surface keeps its own semantics:
    ///
    /// - `matches`: the query's predicate (and any record-level authorization).
    /// - `after`: whether a row lies strictly after the continuation position.
    /// - `compare`: a **total** order (ties broken by record key), the same one
    ///   `after` is defined against.
    /// - `key_order`: `Some(after_key)` when `compare` is exactly record-key
    ///   order. The page is then read by seeking to `after_key` in the
    ///   collection (or in the smallest equality-index bucket) and stops after
    ///   `limit + 1` matches, so the rows examined do not grow with the rows
    ///   before the cursor.
    ///
    /// Otherwise every candidate is examined once -- the whole collection, or
    /// the smallest applicable equality-index bucket -- but only `limit + 1`
    /// of them are ever held, and only the returned rows are copied. Memory is
    /// bounded by the page, not by the collection or the matches. The report
    /// says which access ran and how many rows it examined; it never claims an
    /// index or a bound that was not used.
    #[allow(clippy::too_many_arguments)]
    pub fn select_page(
        &self,
        capability: &str,
        equalities: &[(&str, &Value)],
        key_order: Option<Option<&str>>,
        limit: usize,
        mut matches: impl FnMut(&StoredRow) -> bool,
        mut after: impl FnMut(&StoredRow) -> bool,
        mut compare: impl FnMut(&StoredRow, &StoredRow) -> std::cmp::Ordering,
    ) -> Result<SelectedPage> {
        let keep = limit.saturating_add(1);
        let inner = self.state();
        let Some(bucket) = inner.rows.get(capability) else {
            // A collection with no records has nothing to read, but the access
            // reported is the one the query would use: an indexed equality is
            // answered by its (empty) index. Reporting a scan here made a
            // scoped read of an empty collection fail with INDEX_UNAVAILABLE.
            let indexed = equalities
                .iter()
                .any(|(field, value)| inner.equality_index.candidates(capability, field, value).is_some());
            let access = match (indexed, key_order) {
                (true, _) => PageAccess::EqualityIndex,
                (false, Some(_)) => PageAccess::KeyRange,
                (false, None) => PageAccess::Scan,
            };
            return Ok(SelectedPage::empty(access));
        };

        // Candidate keys from the smallest applicable equality bucket, if any.
        let mut applicable: Vec<&BTreeSet<String>> = equalities
            .iter()
            .filter_map(|(field, value)| inner.equality_index.candidates(capability, field, value))
            .collect();
        applicable.sort_by_key(|keys| keys.len());
        if applicable.is_empty() && !equalities.is_empty() {
            // Equality conditions were offered and no index covers any of them.
            query_execution_diagnostics::record_index_miss();
        }
        let access = if applicable.is_empty() {
            match key_order {
                Some(_) => PageAccess::KeyRange,
                None => PageAccess::Scan,
            }
        } else {
            PageAccess::EqualityIndex
        };

        let mut examined = 0usize;
        let mut matched = 0usize;
        let mut held: Vec<&StoredRow> = Vec::new();
        // Whether a row belongs to the page's candidates: it matches and lies
        // after the cursor. Counts what was examined either way.
        let mut consider = |row: &StoredRow| -> bool {
            examined += 1;
            if row.deleted || !matches(row) {
                return false;
            }
            matched += 1;
            after(row)
        };

        match (applicable.split_first(), key_order) {
            // Key order: seek to the cursor, stop once the page and one more
            // are found.
            (None, Some(after_key)) => {
                let range: Box<dyn Iterator<Item = &StoredRow>> = match after_key {
                    Some(key) => Box::new(
                        bucket
                            .range::<str, _>((Excluded(key), Unbounded))
                            .map(|(_, row)| row),
                    ),
                    None => Box::new(bucket.values()),
                };
                for row in range {
                    if consider(row) {
                        held.push(row);
                    }
                    if held.len() >= keep {
                        break;
                    }
                }
            }
            (Some((smallest, rest)), Some(after_key)) => {
                let keys: Box<dyn Iterator<Item = &String>> = match after_key {
                    Some(key) => Box::new(
                        smallest.range::<str, _>((Excluded(key), Unbounded)),
                    ),
                    None => Box::new(smallest.iter()),
                };
                for key in keys {
                    if !rest.iter().all(|keys| keys.contains(key)) {
                        continue;
                    }
                    if let Some(row) = bucket.get(key) {
                        if consider(row) {
                            held.push(row);
                        }
                        if held.len() >= keep {
                            break;
                        }
                    }
                }
            }
            // Any other order: examine every candidate, hold at most a page.
            (applicable, None) => {
                let mut trim = |held: &mut Vec<&StoredRow>| {
                    if held.len() >= keep.saturating_mul(2) {
                        held.select_nth_unstable_by(keep - 1, |left, right| compare(left, right));
                        held.truncate(keep);
                    }
                };
                match applicable {
                    Some((smallest, rest)) => {
                        for key in smallest.iter() {
                            if !rest.iter().all(|keys| keys.contains(key)) {
                                continue;
                            }
                            if let Some(row) = bucket.get(key) {
                                if consider(row) {
                                    held.push(row);
                                    trim(&mut held);
                                }
                            }
                        }
                    }
                    None => {
                        for row in bucket.values() {
                            if consider(row) {
                                held.push(row);
                                trim(&mut held);
                            }
                        }
                    }
                }
            }
        }

        held.sort_by(|left, right| compare(left, right));
        let has_more = held.len() > limit;
        held.truncate(limit);
        let rows: Vec<StoredRow> = held.into_iter().cloned().collect();
        drop(inner);
        match access {
            PageAccess::EqualityIndex => {
                query_execution_diagnostics::record_indexed_query(examined, examined, rows.len())
            }
            _ => query_execution_diagnostics::record_scan(examined, rows.len()),
        }
        Ok(SelectedPage {
            rows,
            has_more,
            examined,
            matched_examined: matched,
            access,
        })
    }

    /// Traverse one collection in immutable record-key order without materializing it.
    pub fn list_collection_page(
        &self,
        capability: &str,
        after: Option<&str>,
        limit: usize,
    ) -> Result<Vec<StoredRow>> {
        let inner = self.state();
        let Some(rows) = inner.rows.get(capability) else {
            return Ok(vec![]);
        };
        let values: Box<dyn Iterator<Item = &StoredRow>> = match after {
            Some(key) => Box::new(
                rows.range::<str, _>((Excluded(key), Unbounded))
                    .map(|(_, row)| row),
            ),
            None => Box::new(rows.values()),
        };
        Ok(values
            .filter(|row| !row.deleted)
            .take(limit)
            .cloned()
            .collect())
    }

    /// Fetch one live collection record without materializing collection state.
    /// The write version of each named collection: the counter the engine
    /// advances whenever any record of that collection changes, by any write
    /// path (the same counter collection fences compare). A reader holding a
    /// projection of a collection compares these to know it is current.
    pub fn collection_write_versions(&self, capabilities: &[String]) -> Vec<u64> {
        let inner = self.state();
        capabilities
            .iter()
            .map(|capability| inner.collection_versions.get(capability).copied().unwrap_or(0))
            .collect()
    }

    pub fn get_collection_record(&self, capability: &str, key: &str) -> Result<Option<StoredRow>> {
        let inner = self.state();
        Ok(inner
            .rows
            .get(capability)
            .and_then(|rows| rows.get(key))
            .filter(|row| !row.deleted)
            .cloned())
    }

    /// Fetch several live collection records without materializing collection state.
    pub fn get_collection_records<'a>(
        &self,
        capability: &str,
        keys: impl IntoIterator<Item = &'a str>,
    ) -> Result<Vec<StoredRow>> {
        let inner = self.state();
        let Some(rows) = inner.rows.get(capability) else {
            return Ok(Vec::new());
        };
        Ok(keys
            .into_iter()
            .filter_map(|key| rows.get(key))
            .filter(|row| !row.deleted)
            .cloned()
            .collect())
    }

    /// 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.state();
        inner.sync_state.add_peer(peer_id);
        Ok(())
    }

    /// Remove a peer from synchronization
    pub fn remove_sync_peer(&self, peer_id: &str) -> Result<()> {
        let mut inner = self.state();
        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.state();
        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.state();
        Ok(inner.change_log.operations_since(versions))
    }

    /// Return the highest durable operation sequence observed from each origin.
    pub fn operation_versions(&self) -> Result<std::collections::HashMap<String, u64>> {
        let inner = self.state();
        Ok(inner.change_log.versions())
    }

    /// The history this database issues record versions in.
    pub fn version_history(&self) -> VersionHistory {
        self.history.read().expect("history lock poisoned").clone()
    }

    /// The token naming `version` in this database's history.
    pub fn version_token(&self, version: u64) -> String {
        self.version_history().token(version)
    }

    fn publish_history(&self, history: &VersionHistory) {
        *self.history.write().expect("history lock poisoned") = history.clone();
    }

    /// Start a new history: what a restore does, so that no version issued
    /// before it can fence a write after it. Records, and their versions, are
    /// unchanged; only which history those numbers belong to changes. Called
    /// by `backup restore` on the restored store, never by a running server.
    pub fn begin_restored_history(&self) -> Result<VersionHistory> {
        let mut inner = self.state();
        refuse_if_faulted(&inner)?;
        inner.history = VersionHistory::new(HistoryOrigin::Restored);
        persist_sync_metadata(&inner)?;
        self.publish_history(&inner.history);
        Ok(inner.history.clone())
    }

    /// The version a client supplied for `collection`/`key`, accepted for a
    /// fence only if it was issued in this database's history.
    ///
    /// `token` is a version token (`fv1:<history>:<n>`): its history must be
    /// this one, and its `n` is the version the fence compares. `version` is a
    /// bare number, which names no history: it is accepted only while this
    /// history began at genesis, where every version ever issued is in it, and
    /// refused once the database has been restored. Both given must agree.
    /// The refusal is a [`PreconditionFailure::History`], so a client sees
    /// the same typed precondition error as for a stale version.
    pub fn accept_client_version(
        &self,
        collection: &str,
        key: &str,
        version: Option<u64>,
        token: Option<&str>,
    ) -> Result<Option<u64>> {
        let history = self.version_history();
        let refused = |expected: Option<String>| {
            FlowError::PreconditionFailed(Box::new(PreconditionFailure::History {
                collection: collection.to_string(),
                key: key.to_string(),
                expected,
                actual: history.id.clone(),
            }))
        };
        match token {
            Some(token) => {
                let (issued_in, number) = parse_version_token(token).ok_or_else(|| {
                    FlowError::CapabilityError(format!(
                        "INVALID_VERSION_TOKEN: {token:?} is not a version token (fv1:<history>:<version>)"
                    ))
                })?;
                if version.is_some_and(|version| version != number) {
                    return Err(FlowError::CapabilityError(format!(
                        "INVALID_VERSION_TOKEN: {token:?} names version {number}, but version {} was also given",
                        version.unwrap_or_default()
                    )));
                }
                if issued_in != history.id {
                    return Err(refused(Some(issued_in.to_string())));
                }
                Ok(Some(number))
            }
            None => match (version, history.origin) {
                (None, _) => Ok(None),
                (Some(version), HistoryOrigin::Genesis) => Ok(Some(version)),
                (Some(_), HistoryOrigin::Restored) => Err(refused(None)),
            },
        }
    }

    pub fn export_snapshot(&self) -> Result<DatabaseSnapshot> {
        let inner = self.state();
        let mut rows: Vec<StoredRow> = inner
            .rows
            .values()
            .flat_map(|bucket| bucket.values().map(snapshot_row))
            .collect();
        // Keys repeat across collections (a record id is unique only within
        // its collection), so the collection breaks ties: two exports of the
        // same state are the same bytes. The content hash still sorts by key
        // alone, stably, so it is unchanged for snapshots without such ties.
        rows.sort_by(|left, right| {
            left.key.cmp(&right.key).then_with(|| left.capability.cmp(&right.capability))
        });
        let versions = inner.change_log.versions();
        let content_hash = DatabaseSnapshot::compute_hash(&rows, &versions)?;
        let snapshot = DatabaseSnapshot {
            rows,
            versions,
            content_hash,
            format_version: DURABLE_FORMAT_VERSION,
            history: Some(inner.history.clone()),
        };
        // What this engine emits, it must accept.
        snapshot.validate()?;
        Ok(snapshot)
    }
    /// Current materialized rows including their causal operation envelopes.
    /// State-contract execution uses this for record-version preconditions;
    /// portable snapshots carry each record's version as `recorded_version`.
    pub fn state_rows(&self) -> Result<Vec<StoredRow>> {
        let inner = self.state();
        Ok(inner
            .rows
            .values()
            .flat_map(|bucket| bucket.values().cloned())
            .collect())
    }

    /// Materialized rows belonging to one application state namespace.
    ///
    /// State-contract capabilities are encoded as `<state namespace>:<collection>`.
    /// Selecting the capability buckets before cloning prevents one application's
    /// read snapshot from materializing every other application's durable rows.
    pub fn state_rows_for_namespace(&self, state_namespace: &str) -> Result<Vec<StoredRow>> {
        let _span = workload_diagnostics::span(workload_diagnostics::Phase::NamespaceSnapshot);
        let inner = self.state();
        let prefix = format!("{state_namespace}:");
        Ok(inner
            .rows
            .iter()
            .filter(|(capability, _)| capability.starts_with(&prefix))
            .flat_map(|(_, bucket)| bucket.values().cloned())
            .collect())
    }

    pub fn can_install_snapshot(&self) -> Result<bool> {
        let inner = self.state();
        Ok(!inner.bootstrapped && inner.rows.is_empty() && inner.change_log.pending.is_empty())
    }

    /// Install a verified bootstrap snapshot into a pristine node. A node with
    /// local history must converge through operations rather than overwrite it.
    pub fn install_snapshot(&self, snapshot: DatabaseSnapshot) -> Result<()> {
        // Format, content hash and row identities, exactly as backup
        // verification and restore check them.
        snapshot.validate()?;
        let mut inner = self.state();
        refuse_if_faulted(&inner)?;
        if !inner.rows.is_empty() || !inner.change_log.pending.is_empty() {
            return Err(FlowError::CapabilityError(
                "snapshot bootstrap requires a pristine node".to_string(),
            ));
        }

        let temporary = sibling(&inner.path, "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(),
                format_version: DURABLE_FORMAT_VERSION,
                local_sequence: inner.sequence,
                observed_versions: snapshot.versions.clone(),
                transaction_history: Vec::new(),
                transaction_payload_hashes: HashMap::new(),
                // A bootstrap snapshot replays as it always has.
                authority_revision: 0,
            },
        )?;
        for row in &snapshot.rows {
            write_json_line(&mut file, row)?;
        }
        file.flush()?;
        file.sync_all()?;
        fs::rename(temporary, &inner.path)?;
        sync_parent_directory(&inner.path)?;

        inner.clear_rows();
        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.put_row(row);
        }
        inner.change_log.observed_versions = snapshot.versions;
        inner.bootstrapped = true;
        // A replica bootstrapped from its authority issues and accepts the
        // authority's versions. A restore replaces this with a new history.
        inner.history = snapshot
            .history
            .unwrap_or_else(|| VersionHistory::new(HistoryOrigin::Genesis));
        self.publish_history(&inner.history);
        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.state();
        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.state();
        inner.change_log.acknowledge_versions(peer_id, versions);
        persist_sync_metadata(&inner)
    }

    pub fn acknowledged_peer_versions(&self, peer_id: &str) -> Result<HashMap<String, u64>> {
        let inner = self.state();
        Ok(inner.change_log.acknowledged_versions(peer_id))
    }

    /// Earliest operation still available for incremental replay, by origin.
    /// Recent commits and who made them, newest first.
    ///
    /// Bounded by [`TRANSACTION_ATTRIBUTION_WINDOW`]. A transaction older than
    /// the window is not absent from history — it is in the durable log — it is
    /// simply no longer answerable from memory, and callers that present this
    /// to a human must say which of the two they are showing.
    pub fn recent_transactions(&self, limit: usize) -> Result<Vec<TransactionAttribution>> {
        let inner = self.state();
        Ok(inner
            .transaction_attributions
            .iter()
            .rev()
            .take(limit)
            .cloned()
            .collect())
    }

    /// One transaction's durable attribution, regardless of the operator
    /// window. This lookup is canonical historical provenance.
    pub fn transaction_attribution(
        &self,
        transaction_id: &str,
    ) -> Result<Option<TransactionAttribution>> {
        let inner = self.state();
        Ok(inner
            .transaction_history
            .iter()
            .rev()
            .find(|attribution| attribution.transaction_id == transaction_id)
            .cloned())
    }

    /// Canonical commit history in authority order, suitable for resumable
    /// event projection and historical provenance reconstruction.
    pub fn committed_transactions_after(
        &self,
        commit_revision: u64,
        limit: usize,
    ) -> Result<Vec<TransactionAttribution>> {
        let inner = self.state();
        Ok(inner
            .transaction_history
            .iter()
            .filter(|transaction| transaction.commit_revision > commit_revision)
            .take(limit)
            .cloned()
            .collect())
    }

    /// Durable commits that named this record, newest first.
    ///
    /// This deliberately reads complete canonical history rather than the
    /// bounded operator window. Historical provenance must not disappear when
    /// a cache rolls over.
    pub fn transactions_touching(
        &self,
        capability: &str,
        key: &str,
        limit: usize,
    ) -> Result<Vec<TransactionAttribution>> {
        let inner = self.state();
        Ok(inner
            .transaction_history
            .iter()
            .rev()
            .filter(|attribution| attribution.touched(capability, key))
            .take(limit)
            .cloned()
            .collect())
    }

    /// How much of the attribution window is in use, and what it can hold.
    ///
    /// Reported so a reader can tell an idle system from a window that has
    /// already rolled over.
    pub fn transaction_attribution_window(&self) -> Result<(usize, usize)> {
        let inner = self.state();
        Ok((
            inner.transaction_attributions.len(),
            TRANSACTION_ATTRIBUTION_WINDOW,
        ))
    }

    pub fn retained_operation_floors(&self) -> Result<HashMap<String, u64>> {
        let inner = self.state();
        Ok(inner.change_log.retained_from())
    }

    pub fn acknowledged_operation_count(&self, active_peers: &[String]) -> Result<usize> {
        let inner = self.state();
        Ok(inner.change_log.acknowledged_operation_count(active_peers))
    }

    /// Atomically replace acknowledged history with a state snapshot and any
    /// operations still needed by at least one configured peer.
    pub fn compact_operation_log(&self, active_peers: &[String]) -> Result<usize> {
        self.compact_internal(active_peers, true)
            .map(|outcome| outcome.pruned())
    }

    /// Compact under the database's [`CompactionPolicy`].
    ///
    /// Prunes acknowledged operations from memory whenever it can, and rewrites
    /// the durable log **only when enough has accumulated to justify the
    /// stall**. Use this on a timer; use
    /// [`compact_operation_log`](Self::compact_operation_log) when a caller is
    /// explicitly asking for a rewrite now.
    ///
    /// The distinction is the whole point. Pruning is cheap and in memory.
    /// Rewriting serializes every row in the database and fsyncs it while
    /// holding the one lock that serializes every read and every write, so
    /// doing it on a short timer stops the world on that timer.
    pub fn maybe_compact_operation_log(
        &self,
        active_peers: &[String],
    ) -> Result<CompactionOutcome> {
        self.compact_internal(active_peers, false)
    }

    /// The policy deciding when a timer-driven compaction rewrites the log.
    pub fn compaction_policy(&self) -> CompactionPolicy {
        self.state().compaction_policy
    }

    /// Set the policy deciding when a timer-driven compaction rewrites the log.
    pub fn set_compaction_policy(&self, policy: CompactionPolicy) {
        self.state().compaction_policy = policy;
    }

    fn compact_internal(&self, active_peers: &[String], force: bool) -> Result<CompactionOutcome> {
        let mut inner = self.state();
        // Rewriting the log from memory would silently decide an indeterminate
        // write as "not committed". Only a reopen gets to decide that.
        refuse_if_faulted(&inner)?;
        // A store that has never replicated bounds its operation log to a
        // window; one with replication history prunes only what every active
        // peer acknowledged.
        let standalone = active_peers.is_empty() && !inner.change_log.has_peer_history();
        let removed = if standalone {
            inner.change_log.prune_standalone(STANDALONE_OPERATION_WINDOW)
        } else {
            inner.change_log.prune_acknowledged(active_peers)
        };
        if removed == 0 {
            return Ok(CompactionOutcome::Idle);
        }
        persist_sync_metadata(&inner)?;
        inner.pruned_since_rewrite += removed;

        // The cheap half is done. The expensive half runs only when asked for
        // explicitly, or when the accumulated gain has earned it. A standalone
        // store prunes on every write once its window is full, so it also
        // waits for the log to double: rewriting costs the whole store, and
        // doubling makes that cost proportional to what was appended.
        let log_bytes = fs::metadata(&inner.path).map(|m| m.len()).unwrap_or(0);
        let doubled = log_bytes >= inner.log_bytes_after_rewrite.saturating_mul(2);
        if !force
            && (inner.pruned_since_rewrite < inner.compaction_policy.rewrite_after_pruned
                || (standalone && !doubled))
        {
            return Ok(CompactionOutcome::Deferred {
                pruned: removed,
                pending_since_rewrite: inner.pruned_since_rewrite,
            });
        }

        rewrite_log_locked(&mut inner)?;
        inner.bootstrapped = true;
        inner.pruned_since_rewrite = 0;
        inner.log_bytes_after_rewrite = fs::metadata(&inner.path).map(|m| m.len()).unwrap_or(0);
        Ok(CompactionOutcome::Rewritten { pruned: removed })
    }

    /// Register a peer in the distributed fabric
    pub fn register_peer(&self, advertisement: PeerAdvertisement) -> Result<()> {
        let inner = self.state();
        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.state();
        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.state();
        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.state();
        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.state();
        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.state();
        Ok(inner.sync_state.clone())
    }

    /// Apply an operation from a remote peer
    /// This merges the vector clock, resolves conflicts, and applies the mutation
    pub fn apply_remote_operation(&self, op: Operation) -> Result<()> {
        let mut inner = self.state();

        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_locked(&mut inner, &history_row)?;
                    inner.authority_revision += 1;
                }
                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 {
            recorded_version: None,
            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_locked(&mut inner, &row)?;
                inner.authority_revision += 1;
                inner.put_row(row);
            }
            OperationType::Delete => {
                append_event_locked(&mut inner, &row)?;
                inner.authority_revision += 1;
                inner.remove_row(&op_to_apply.capability, &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);
        }

        // Reconstruct the historical fact the originating authority recorded.
        //
        // Not a local mint of the resulting state: the identity, parent and
        // sequence come from the operation, so the peer ends up holding the
        // *same* revision rather than an equivalent-looking one of its own.
        // Deliberately independent of which value won any last-writer race
        // above — the origin committed this revision whether or not its value
        // is what is current here, and dropping it would lose the divergence
        // that reconciliation needs to see.
        if let Some(provenance) = op.revision.clone() {
            if let Some(value) = op.value.clone() {
                let revision = reconstruct_revision(&provenance, &value)?;
                persist_revision_locked(&mut inner, revision)?;
            }
        }

        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.state();
        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.state();
            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, false)?;
        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, false)
    }

    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.state();
        *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 mut inner = self.db.state();
            *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 rx = self.db.event_tx.subscribe();
        let mut matches = LiveMatches::new(rust_type, Some(self.name.clone()));
        matches.rescan(&self.db, &predicate);
        let subscription = LiveCapabilitySubscription {
            initial_results: matches.results(),
            rx,
            db: self.db.clone(),
            matches,
            predicate: Arc::new(Mutex::new(Some(Box::new(predicate)))),
        };

        Ok(subscription)
    }
}

// Type alias for boxed predicates
type PredicateBox<T> = Arc<Mutex<Option<Box<dyn Fn(&T) -> bool + Send + Sync>>>>;

/// The current matches of a live subscription, kept by record so a change is
/// applied by re-testing the one record it names.
///
/// Work per change event is one lookup and one predicate evaluation, and a
/// subscription whose result did not change is not woken. Only a lagged
/// receiver (events were dropped) or a new predicate rescans.
struct LiveMatches {
    rust_type: String,
    /// `Some(name)` for a capability-scoped subscription.
    capability: Option<String>,
    matches: BTreeMap<(String, String), Value>,
    stale: bool,
}

impl LiveMatches {
    fn new(rust_type: String, capability: Option<String>) -> Self {
        LiveMatches { rust_type, capability, matches: BTreeMap::new(), stale: false }
    }

    fn in_scope(&self, capability: &str) -> bool {
        self.capability.as_deref().is_none_or(|scope| scope == capability)
    }

    fn admits<T: DeserializeOwned>(&self, row: &StoredRow, predicate: &dyn Fn(&T) -> bool) -> bool {
        !row.deleted
            && row.rust_type == self.rust_type
            && serde_json::from_value::<T>(row.value.clone())
                .is_ok_and(|parsed| predicate(&parsed))
    }

    /// Recompute every match from the database.
    fn rescan<T: DeserializeOwned>(&mut self, db: &FeltDb, predicate: &dyn Fn(&T) -> bool) {
        let inner = db.state();
        self.matches.clear();
        let buckets: Box<dyn Iterator<Item = (&String, &BTreeMap<String, StoredRow>)>> =
            match &self.capability {
                Some(name) => Box::new(inner.rows.get_key_value(name).into_iter()),
                None => Box::new(inner.rows.iter()),
            };
        for (capability, bucket) in buckets {
            for (key, row) in bucket {
                if self.admits(row, predicate) {
                    self.matches.insert((capability.clone(), key.clone()), row.value.clone());
                }
            }
        }
        self.stale = false;
    }

    /// Apply one change; whether the result changed.
    fn apply<T: DeserializeOwned>(
        &mut self,
        db: &FeltDb,
        event: &ChangeEvent,
        predicate: &dyn Fn(&T) -> bool,
    ) -> bool {
        if !self.in_scope(&event.capability) {
            return false;
        }
        let id = (event.capability.clone(), event.key.clone());
        let current = {
            let inner = db.state();
            inner
                .rows
                .get(&event.capability)
                .and_then(|bucket| bucket.get(&event.key))
                .filter(|row| self.admits(row, predicate))
                .map(|row| row.value.clone())
        };
        match current {
            Some(value) => self.matches.insert(id, value.clone()).as_ref() != Some(&value),
            None => self.matches.remove(&id).is_some(),
        }
    }

    fn results<T: DeserializeOwned>(&self) -> Vec<T> {
        self.matches
            .values()
            .filter_map(|value| serde_json::from_value::<T>(value.clone()).ok())
            .collect()
    }
}

/// Wait for the next change that alters a live subscription's result.
async fn next_live_result<T: DeserializeOwned>(
    rx: &mut broadcast::Receiver<ChangeEvent>,
    db: &FeltDb,
    matches: &mut LiveMatches,
    predicate: &PredicateBox<T>,
) -> Option<Vec<T>> {
    loop {
        if matches.stale {
            let guard = predicate.lock().expect("lock poisoned");
            let Some(predicate) = guard.as_ref() else { return None };
            matches.rescan(db, predicate.as_ref());
            return Some(matches.results());
        }
        match rx.recv().await {
            Ok(event) => {
                let guard = predicate.lock().expect("lock poisoned");
                let Some(predicate) = guard.as_ref() else { return None };
                if matches.apply(db, &event, predicate.as_ref()) {
                    return Some(matches.results());
                }
            }
            // Events were dropped: the only way back to a correct result is to
            // recompute it, not to end the subscription.
            Err(broadcast::error::RecvError::Lagged(_)) => matches.stale = true,
            Err(broadcast::error::RecvError::Closed) => return None,
        }
    }
}

/// 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,
    matches: LiveMatches,
    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));
        // The next call recomputes the result under the new predicate.
        self.matches.stale = true;
    }

    /// Waits for the next change event and returns the updated query results.
    ///
    /// Waits until a change alters the result: each change re-tests only the
    /// record it names (one lookup, one predicate call), and a change that leaves
    /// the result as it was does not wake the caller. Returns every current match.
    /// If change events were dropped (a lagged receiver) the result is recomputed
    /// rather than the subscription ending.
    ///
    /// Returns `None` if the broadcast channel has been dropped (all senders are gone).
    pub async fn next(&mut self) -> Option<Vec<T>> {
        next_live_result(&mut self.rx, &self.db, &mut self.matches, &self.predicate).await
    }

    /// 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,
    matches: LiveMatches,
    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));
        // The next call recomputes the result under the new predicate.
        self.matches.stale = true;
    }

    /// 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>> {
        next_live_result(&mut self.rx, &self.db, &mut self.matches, &self.predicate).await
    }

    pub fn initial_results(&self) -> &[T] {
        &self.initial_results
    }
}

/// Read the log, separating a torn tail from real corruption.
///
/// A process that dies while appending leaves a final record that was never
/// terminated. That record was never committed, so recovery discards it and
/// truncates it away: leaving the bytes in place would make the next append
/// splice onto them and turn a normal crash into permanent corruption.
///
/// Damage anywhere earlier is not an interrupted write. Recovery refuses it
/// rather than silently dropping committed history.
/// Examine a durable database's format **without opening or modifying it**.
///
/// This runs before any record is interpreted, and reads the file only. A
/// database this reports as incompatible is left exactly as it was found.
///
/// The order matters: an explicit format record decides, and the records
/// themselves are examined *only* when no format record exists — the
/// unversioned era. Compatibility is never inferred from whether a
/// deserialization happened to succeed.
pub fn inspect_durable_format(path: &Path) -> Result<FormatCompatibility> {
    if !path.exists() {
        // A database that does not exist yet will be created in the current
        // format.
        return Ok(FormatCompatibility::Compatible(DurableFormat::Versioned(
            DURABLE_FORMAT_VERSION,
        )));
    }

    // Read-only: inspecting a database it is about to reject must not touch it.
    // Streamed, and each line is probed for the three fields that matter here
    // without materializing the rest of it.
    #[derive(Deserialize)]
    struct FormatProbe {
        #[serde(default)]
        record_type: Option<Value>,
        #[serde(default)]
        format_version: Option<Value>,
        #[serde(default)]
        key: Option<Value>,
    }
    let mut declared: Option<u32> = None;
    let mut legacy_revision = false;
    visit_log(path, |line| {
        if line.text.trim().is_empty() {
            return Ok(());
        }
        let Ok(probe) = serde_json::from_str::<FormatProbe>(&line.text) else {
            return Ok(());
        };
        match probe.record_type.as_ref().and_then(Value::as_str) {
            Some(FORMAT_RECORD_TYPE) => {
                if let Some(version) = probe.format_version.as_ref().and_then(Value::as_u64) {
                    declared = Some(version as u32);
                }
            }
            Some("feltdb.snapshot.v1" | "flowdb.snapshot.v1") => {
                match probe.format_version.as_ref().and_then(Value::as_u64) {
                    Some(version) if version > 0 => declared = Some(version as u32),
                    _ => {}
                }
            }
            _ => {
                // The unversioned-era probe: a revision record that predates
                // resource-scoped identity. Deliberate and specific — it looks
                // for a named absence rather than trying to parse and shrugging
                // at failure. Only revision lines are read in full.
                let is_revision = probe
                    .key
                    .as_ref()
                    .and_then(Value::as_str)
                    .is_some_and(|key| key.starts_with("state:revision:"));
                if is_revision
                    && serde_json::from_str::<Value>(&line.text).is_ok_and(|value| {
                        value
                            .get("value")
                            .and_then(Value::as_object)
                            .is_some_and(|revision| !revision.contains_key("resource"))
                    })
                {
                    legacy_revision = true;
                }
            }
        }
        Ok(())
    })?;

    if let Some(version) = declared {
        return Ok(match version.cmp(&DURABLE_FORMAT_VERSION) {
            std::cmp::Ordering::Equal => {
                FormatCompatibility::Compatible(DurableFormat::Versioned(version))
            }
            std::cmp::Ordering::Greater => {
                FormatCompatibility::Incompatible(FormatIncompatibility {
                    found: DurableFormat::Versioned(version),
                    required: DURABLE_FORMAT_VERSION,
                    reason: "the database was written by a newer FeltDB".to_string(),
                    action: "Run a FeltDB build that understands this format, or restore \
                             a backup taken in an older format."
                        .to_string(),
                })
            }
            std::cmp::Ordering::Less => FormatCompatibility::Incompatible(FormatIncompatibility {
                found: DurableFormat::Versioned(version),
                required: DURABLE_FORMAT_VERSION,
                reason: "the database was written in an older durable format".to_string(),
                action: "Migrate the database with a FeltDB build that supports both \
                             formats, or restore a backup."
                    .to_string(),
            }),
        });
    }

    if legacy_revision {
        return Ok(FormatCompatibility::Incompatible(FormatIncompatibility {
            found: DurableFormat::Unversioned,
            required: DURABLE_FORMAT_VERSION,
            reason: "it holds revision records written before revisions belonged to a \
                     resource, and those records cannot be migrated without inventing \
                     information they never contained: a revision recorded no resource, \
                     so which history each one belongs to is not recoverable from the data"
                .to_string(),
            action: "Export the application state you need from a FeltDB build that \
                     understands the old format, then load it into a new database. The \
                     existing file has not been modified."
                .to_string(),
        }));
    }

    // No format record and no legacy revision: nothing in this database depends
    // on the difference.
    Ok(FormatCompatibility::Compatible(DurableFormat::Unversioned))
}

/// One complete record in the durable log, with where it came from.
struct ScannedLine {
    text: String,
    line_number: usize,
    byte_offset: u64,
}

/// The bytes at the end of a log that are not a complete record.
#[derive(Clone)]
struct TornTail {
    byte_offset: u64,
    bytes: usize,
}

/// Read the durable log one complete record at a time. **This never writes.**
///
/// Each complete (terminated) record is handed to `visit` and dropped before
/// the next is read, so reading a log costs memory proportional to its largest
/// record, not its size. The only thing separated out here is the
/// **terminator**: a final record with no newline cannot be one this database
/// finished writing, so it is returned as a torn tail and never visited.
/// Everything else — including a complete final record that happens to be
/// invalid — is visited, to be validated by the caller and refused rather than
/// quietly dropped for being near the end.
///
/// Being read-only is load-bearing twice over: a refused open must leave the
/// database byte-identical, and format inspection must be able to run on a
/// database it is about to reject.
fn visit_log(
    path: &Path,
    mut visit: impl FnMut(&ScannedLine) -> Result<()>,
) -> Result<Option<TornTail>> {
    let mut file = BufReader::with_capacity(1 << 20, OpenOptions::new().read(true).open(path)?);
    let mut buffer = Vec::new();
    let mut offset = 0u64;
    let mut line_number = 0usize;

    loop {
        buffer.clear();
        let read = file.read_until(b'\n', &mut buffer)?;
        if read == 0 {
            return Ok(None);
        }
        line_number += 1;
        if !buffer.ends_with(b"\n") {
            // An unterminated final record: the write did not finish. Empty
            // trailing bytes are nothing at all and are simply ignored.
            let blank = buffer.iter().all(u8::is_ascii_whitespace);
            return Ok((!blank).then_some(TornTail {
                byte_offset: offset,
                bytes: read,
            }));
        }
        buffer.pop();
        let line = ScannedLine {
            text: match String::from_utf8(std::mem::take(&mut buffer)) {
                Ok(text) => text,
                Err(error) => String::from_utf8_lossy(error.as_bytes()).into_owned(),
            },
            line_number,
            byte_offset: offset,
        };
        visit(&line)?;
        buffer = line.text.into_bytes();
        offset += read as u64;
    }
}

/// Just enough of a log record to decide how to read the rest of it. Every
/// other field is skipped without being materialized.
#[derive(Deserialize)]
struct RecordProbe {
    #[serde(default)]
    record_type: Option<Value>,
}

/// Classify a line that is not a record object: invalid JSON, or JSON that is
/// not a record this build understands.
fn unreadable(line: &ScannedLine) -> FlowError {
    if serde_json::from_str::<serde::de::IgnoredAny>(&line.text).is_ok() {
        corruption(line, "not a durable record this build understands")
    } else {
        corruption(line, "not valid JSON")
    }
}

/// Discard an incomplete final append, so the next append does not splice onto
/// a partial record.
///
/// Called only after the whole log has replayed successfully. A log that is
/// going to be refused is never truncated.
fn truncate_torn_tail(path: &Path, tail: &TornTail) -> Result<()> {
    let file = OpenOptions::new().write(true).open(path)?;
    file.set_len(tail.byte_offset)?;
    file.sync_all()?;
    Ok(())
}

fn corruption(line: &ScannedLine, reason: &str) -> FlowError {
    let excerpt: String = line.text.chars().take(120).collect();
    FlowError::CorruptLogLine(Box::new(LogCorruption {
        line_number: line.line_number,
        byte_offset: line.byte_offset,
        reason: reason.to_string(),
        excerpt,
    }))
}

fn replay_log(inner: &mut Inner) -> Result<()> {
    let path = inner.path.clone();
    let mut snapshot_log = false;
    let mut snapshot_authority = false;
    let mut snapshot_versions: HashMap<String, u64> = HashMap::new();
    let mut recoverable_revisions: HashMap<String, (operation::RevisionProvenance, Value)> =
        HashMap::new();
    let torn_tail = visit_log(&path, |line| {
        if line.text.trim().is_empty() {
            return Ok(());
        }
        let probe: RecordProbe =
            serde_json::from_str(&line.text).map_err(|_| unreadable(line))?;
        let record_type = probe.record_type.as_ref().and_then(Value::as_str);
        if matches!(record_type, Some("feltdb.snapshot.v1" | "flowdb.snapshot.v1")) {
            let header: LogHeader = serde_json::from_str(&line.text)
                .map_err(|error| corruption(line, &format!("malformed log header: {error}")))?;
            inner.sequence = inner.sequence.max(header.local_sequence);
            // Applied after every line has replayed: the operations compaction
            // retained follow this header, and replaying them against these
            // versions first would discard them as already seen.
            if header.authority_revision > 0 {
                inner.authority_revision = inner.authority_revision.max(header.authority_revision);
                snapshot_authority = true;
            }
            snapshot_versions = header.observed_versions;
            for attribution in header.transaction_history {
                let attribution = normalize_transaction_attribution(attribution);
                inner.authority_revision =
                    inner.authority_revision.max(attribution.commit_revision);
                inner.transaction_revisions.insert(
                    attribution.transaction_id.clone(),
                    (attribution.base_revision, attribution.commit_revision),
                );
                inner
                    .applied_transactions
                    .insert(attribution.transaction_id.clone());
                remember_attribution(inner, attribution);
            }
            inner
                .transaction_payload_hashes
                .extend(header.transaction_payload_hashes);
            inner.bootstrapped = true;
            snapshot_log = true;
            return Ok(());
        }
        if record_type == Some(FORMAT_RECORD_TYPE) {
            // Already honoured by `inspect_durable_format` before the open.
            return Ok(());
        }
        if record_type == Some("feltdb.transaction.v1") {
            let transaction: TransactionLogRecord =
                serde_json::from_str(&line.text).map_err(|error| {
                    corruption(line, &format!("malformed transaction record: {error}"))
                })?;
            // Older records did not carry a commit revision. Their durable
            // order in the log supplies an unambiguous upgrade path.
            inner.authority_revision =
                inner
                    .authority_revision
                    .max(if transaction.commit_revision == 0 {
                        inner.authority_revision + 1
                    } else {
                        transaction.commit_revision
                    });
            let base_revision = if transaction.commit_revision == 0 {
                inner.authority_revision.saturating_sub(1)
            } else {
                transaction.base_revision
            };
            inner.transaction_revisions.insert(
                transaction.transaction_id.clone(),
                (base_revision, inner.authority_revision),
            );
            if let Some(hash) = transaction.payload_hash.clone() {
                inner
                    .transaction_payload_hashes
                    .insert(transaction.transaction_id.clone(), hash);
            }
            // Attribution is restored on replay for the same reason it is kept
            // on commit: an operator who restarts a server must not lose the
            // answer to "who did this" for work the server already holds.
            let attribution = TransactionAttribution::from_record(
                &transaction.transaction_id,
                transaction.audit.as_ref(),
                base_revision,
                inner.authority_revision,
                transaction.state_before,
                transaction.state_after,
                &transaction.rows,
                transaction
                    .rows
                    .first()
                    .map(|row| row.unix_ms)
                    .unwrap_or_default(),
            );
            remember_attribution(inner, attribution);
            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 {
                        inner.remove_row(&row.capability, &row.key);
                    } else {
                        inner.put_row(row);
                    }
                }
            }
            inner.sequence = inner.sequence.max(transaction.state_after);
            return Ok(());
        }
        let row: StoredRow = serde_json::from_str(&line.text)
            .map_err(|_| corruption(line, "not a durable record this build understands"))?;
        let derived_revision = row.capability == "state" && row.operation.is_none();
        if derived_revision {
            if let Some(id) = row.key.strip_prefix("state:revision:") {
                recoverable_revisions.remove(id);
            }
        }
        // In a log whose header records the authority revision, the rows that
        // follow the header -- the snapshot, and the operations compaction
        // retained -- are not new commits: the header already counts them.
        // Only what was appended after the rewrite advances the revision.
        let counted_by_header = snapshot_authority
            && row.operation.as_ref().is_none_or(|operation| {
                snapshot_versions.get(&operation.instance_id).copied().unwrap_or(0)
                    >= operation.sequence
            });
        if let Some(operation) = row.operation.clone() {
            // A revision is a deterministic function of the operation that
            // produced it, so it never has to be lost. If the crash landed
            // between a record and the revision recording it, the revision is
            // rebuilt below rather than left missing. Its own row normally
            // follows on the next line and removes it from this set again, so
            // the set stays small however long the log is.
            if let (Some(provenance), Some(value)) = (&operation.revision, &operation.value) {
                recoverable_revisions.insert(provenance.id.clone(), (provenance.clone(), value.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 && !derived_revision {
            // Pre-operation-envelope logs were produced only by this local
            // store. Preserve a monotonic sequence when upgrading them.
            inner.sequence += 1;
        }
        if !derived_revision && !counted_by_header {
            let base_revision = inner.authority_revision;
            inner.authority_revision += 1;
            // A row appended after a rewrite is a commit like any other and
            // keeps its attribution. (A header without the authority revision
            // cannot tell those rows apart and replays as it always has.)
            if !snapshot_log || snapshot_authority {
                remember_operation_attribution(inner, &row, base_revision, base_revision + 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 {
            inner.remove_row(&row.capability, &row.key);
        } else if row.operation.is_none() && row.recorded_version.is_none() {
            // A snapshot row from before `recorded_version`. If the operation that
            // produced it was retained, it precedes the row in this log: keep
            // its envelope, so the record keeps its version.
            let mut row = row;
            if let (Some(previous), Some(hash)) = (
                inner.rows.get(&row.capability).and_then(|bucket| bucket.get(&row.key)),
                &row.content_hash,
            ) {
                if previous.operation.as_ref().is_some_and(|operation| &operation.content_hash == hash) {
                    row.operation = previous.operation.clone();
                }
            }
            inner.put_row(row);
        } else {
            inner.put_row(row);
        }
            Ok(())
    })?;
    // The versions the snapshot header recorded, merged now that the retained
    // operations have been replayed.
    for (origin, sequence) in snapshot_versions {
        inner
            .change_log
            .observed_versions
            .entry(origin)
            .and_modify(|current| *current = (*current).max(sequence))
            .or_insert(sequence);
    }

    // Rebuild any revision whose record survived but whose own row did not.
    //
    // This is the crash window between appending a record and appending the
    // revision that records it. The revision is derivable from the operation —
    // resource, content, parent, sequence and authority all travel with it —
    // so recovery reconstructs it instead of leaving an authority holding less
    // history than its own operation stream implies. Nothing is invented: the
    // identity is recomputed from its parts and discarded if it does not follow
    // from them.
    //
    // The rebuilt rows are not appended here. They are derived, and stay
    // derivable from the same operations on every subsequent open.
    for (provenance, value) in recoverable_revisions.into_values() {
        let key = format!("state:revision:{}", provenance.id);
        let present = inner
            .rows
            .get("state")
            .and_then(|bucket| bucket.get(&key))
            .is_some_and(|row| !row.deleted);
        if present {
            continue;
        }

        // A revision below the resource's retention horizon is absent because
        // it was expired on purpose. Rebuilding it would make recovery
        // resurrect history a policy deliberately discarded, which is a
        // different kind of wrong from losing it.
        let horizon = inner
            .rows
            .get("_retention")
            .and_then(|bucket| bucket.get(&format!("_retention:{}", provenance.resource)))
            .and_then(|row| serde_json::from_value::<RetentionRecord>(row.value.clone()).ok())
            .map(|state| state.horizon);
        if horizon.is_some_and(|horizon| provenance.sequence < horizon) {
            continue;
        }
        let Ok(revision) = reconstruct_revision(&provenance, &value) else {
            continue;
        };
        let Ok(encoded) = serde_json::to_value(&revision) else {
            continue;
        };
        inner.put_row(StoredRow {
            recorded_version: None,
            capability: "state".to_string(),
            key,
            rust_type: "feltdb::state_model::StateRevision".to_string(),
            value: encoded,
            unix_ms: now_ms(),
            content_hash: None,
            flow_ref: None,
            deleted: false,
            operation: None,
        });
    }

    // 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);
    }

    // Only now, with every complete record replayed, is it safe to discard an
    // incomplete final append. A log that was going to be refused never reaches
    // this point, so a refused open leaves the file byte-identical.
    if let Some(tail) = torn_tail {
        truncate_torn_tail(&inner.path, &tail)?;
        inner.log_recovery = LogRecovery::RecoveredTornTail {
            byte_offset: tail.byte_offset,
            discarded_bytes: tail.bytes,
        };
    }

    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 {
        recorded_version: None,
        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)?)?;
    if let Some(history) = metadata.history {
        inner.history = history;
    }
    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(),
        history: Some(inner.history.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)?;
    sync_parent_directory(&path)?;
    Ok(())
}

/// Append one record under the database's configured durability mode.
fn append_event_locked(inner: &mut Inner, event: &StoredRow) -> Result<()> {
    append_rows_locked(inner, &[event])
}

/// Append records as **one** write under the configured durability mode.
///
/// One write and at most one barrier, so a single-record write and the revision
/// it mints cost one fsync, and either both lines are durable or, after a
/// failure, neither is in the log.
fn append_rows_locked(inner: &mut Inner, rows: &[&StoredRow]) -> Result<()> {
    let mut bytes = Vec::new();
    for row in rows {
        serde_json::to_writer(&mut bytes, row)?;
        bytes.push(b'\n');
    }
    let barrier = match inner.durability_mode {
        DurabilityMode::Flushed => Barrier::None,
        DurabilityMode::Synced => Barrier::Now,
        DurabilityMode::Grouped { every } => {
            inner.writes_since_barrier += 1;
            if inner.writes_since_barrier >= every.max(1) {
                Barrier::Group
            } else {
                Barrier::None
            }
        }
    };
    let outcome = append_bytes_locked(inner, &bytes, barrier);
    if barrier == Barrier::Group && outcome.is_ok() {
        inner.writes_since_barrier = 0;
    }
    outcome
}

/// What an append asks of stable storage before it returns.
#[derive(Clone, Copy, PartialEq, Eq)]
enum Barrier {
    /// Flushed to the operating system only.
    None,
    /// `fdatasync` before returning; this write is durable when it succeeds.
    Now,
    /// `fdatasync` closing a group of earlier, already acknowledged writes.
    Group,
}

/// The persistence boundary. Every byte appended to the durable log, by every
/// write path, goes through here.
///
/// The append is all-or-nothing as far as the log is concerned. On any failure
/// — a short or refused write, a failed flush, a failed barrier — the file is
/// cut back to the length it had before this append, and that cut is itself
/// made durable. Only then is the failure reported as "nothing was
/// committed": the log is exactly what it was, so a later append cannot splice
/// onto a partial record, and a restart cannot resurrect a write that was
/// reported as failed.
///
/// If the cut fails too, this process no longer knows what the log holds. It
/// says so (`Indeterminate`, outcome unknown), records the fault, and refuses
/// every later write (`RecoveryRequired`) until the database is reopened and
/// replay — the only authority on the log — decides.
fn append_bytes_locked(inner: &mut Inner, bytes: &[u8], barrier: Barrier) -> Result<()> {
    let _span = workload_diagnostics::span(workload_diagnostics::Phase::Persistence);
    refuse_if_faulted(inner)?;
    let failed = |kind, error: &std::io::Error| {
        durability_failure(kind, Some(false), error.to_string())
    };
    let mut file = OpenOptions::new()
        .append(true)
        .open(&inner.path)
        .map_err(|error| failed(classify_write_error(&error), &error))?;
    let before = file
        .metadata()
        .map_err(|error| failed(DurabilityFailureKind::WriteFailed, &error))?
        .len();

    let written = fault::write_all(&mut file, bytes).and_then(|()| file.flush());
    let outcome = match written {
        Err(error) => Err((classify_write_error(&error), error)),
        Ok(()) if barrier == Barrier::None => Ok(()),
        Ok(()) => fault::sync_data(&file).map_err(|error| {
            // A failed group barrier also covers earlier writes that were
            // already acknowledged under `Grouped`. Removing this write's bytes
            // does not make theirs durable, so the log is not known-good.
            let kind = if barrier == Barrier::Group {
                DurabilityFailureKind::Indeterminate
            } else {
                DurabilityFailureKind::SyncFailed
            };
            (kind, error)
        }),
    };
    let Err((kind, error)) = outcome else {
        return Ok(());
    };

    let rollback = fault::rollback(&file, before);
    let reason = match (rollback, kind) {
        (Err(rollback_error), _) => format!(
            "{error}; cutting the log back to byte {before} also failed: {rollback_error}"
        ),
        (Ok(()), DurabilityFailureKind::Indeterminate) => format!(
            "{error}; writes acknowledged earlier in this durability group may not be durable"
        ),
        (Ok(()), kind) => return Err(failed(kind, &error)),
    };
    inner.write_fault = Some(reason.clone());
    Err(durability_failure(
        DurabilityFailureKind::Indeterminate,
        None,
        reason,
    ))
}

/// `path` with `.suffix` appended to its file name.
fn sibling(path: &Path, suffix: &str) -> PathBuf {
    let mut name = path.as_os_str().to_os_string();
    name.push(".");
    name.push(suffix);
    PathBuf::from(name)
}

/// Remove a restore's staging database and the files opening it created. They
/// are this restore's own intermediate artifacts and are never served.
fn remove_restore_staging(staging: &Path) -> std::io::Result<()> {
    for path in [staging.to_path_buf(), sibling(staging, "lock")] {
        match fs::remove_file(&path) {
            Ok(()) => {}
            Err(error) if error.kind() == std::io::ErrorKind::NotFound => {}
            Err(error) => return Err(error),
        }
    }
    Ok(())
}

/// Refuse an operation that rewrites the durable log while a failed write has
/// left it indeterminate.
fn refuse_if_faulted(inner: &Inner) -> Result<()> {
    match &inner.write_fault {
        Some(reason) => Err(durability_failure(
            DurabilityFailureKind::RecoveryRequired,
            Some(false),
            format!("an earlier write left the durable log indeterminate ({reason}); reopen the database"),
        )),
        None => Ok(()),
    }
}

/// Replace the durable log with a snapshot of current state, atomically.
///
/// Stages, each of which a crash can interrupt:
///
/// 1. write `<log>.compact.tmp` (named after the whole log file name, so two
///    stores in one directory never share it): the header (canonical commit history,
///    idempotency bindings, versions, authority revision), the operations the
///    operation log still retains, then every current row;
/// 2. fsync it;
/// 3. rename it over the log -- **the switch**;
/// 4. fsync the directory, so the switch survives power loss.
///
/// Before 3 the old log is untouched and complete, so an interruption loses
/// nothing; a failure removes the temporary file. After 3 the new log holds
/// everything the old one meant. If 4 fails, a power loss could still bring
/// back the old log, and a write appended to the new one would be lost with
/// it, so the store stops accepting writes (`RECOVERY_REQUIRED`) until it is
/// reopened.
///
/// Memory: one row at a time, plus the header serialized from borrowed
/// state. Temporary disk: the size of the compacted log.
fn rewrite_log_locked(inner: &mut Inner) -> Result<()> {
    let temporary = sibling(&inner.path, "compact.tmp");
    let written = (|| -> Result<()> {
        fault::stage(fault::Stage::CompactionWrite)?;
        let file = OpenOptions::new()
            .create(true)
            .write(true)
            .truncate(true)
            .open(&temporary)?;
        let mut out = std::io::BufWriter::with_capacity(1 << 20, file);
        // Written from borrowed state: the header carries the whole canonical
        // commit history, and cloning it would double that in memory for the
        // length of the rewrite.
        write_json_line_to(
            &mut out,
            &LogHeaderRef {
                record_type: "feltdb.snapshot.v1",
                format_version: DURABLE_FORMAT_VERSION,
                local_sequence: inner.sequence,
                observed_versions: &inner.change_log.observed_versions,
                transaction_history: &inner.transaction_history,
                transaction_payload_hashes: &inner.transaction_payload_hashes,
                authority_revision: inner.authority_revision,
            },
        )?;
        fault::stage(fault::Stage::CompactionMidWrite)?;
        for operation in inner.change_log.pending.iter().cloned() {
            write_json_line_to(&mut out, &stored_row_for_operation(operation))?;
        }
        for bucket in inner.rows.values() {
            for row in bucket.values() {
                write_json_line_to(&mut out, &snapshot_row(row))?;
            }
        }
        let file = out.into_inner().map_err(|error| error.into_error())?;
        fault::stage(fault::Stage::CompactionSync)?;
        file.sync_all()?;
        fault::stage(fault::Stage::CompactionRename)?;
        fs::rename(&temporary, &inner.path)?;
        Ok(())
    })();
    if let Err(error) = written {
        // The old log is untouched; only the partial snapshot goes.
        let _ = fs::remove_file(&temporary);
        return Err(error);
    }
    if let Err(error) = fault::stage(fault::Stage::CompactionDirectorySync)
        .and_then(|()| sync_parent_directory(&inner.path))
    {
        inner.write_fault = Some(format!(
            "the compacted log replaced the old one, but its directory entry could not be made durable: {error}"
        ));
        return Err(FlowError::Io(error));
    }
    Ok(())
}

fn write_json_line_to<W: Write, T: Serialize>(out: &mut W, value: &T) -> Result<()> {
    serde_json::to_writer(&mut *out, value)?;
    out.write_all(b"\n")?;
    Ok(())
}

fn durability_failure(
    kind: DurabilityFailureKind,
    committed: Option<bool>,
    detail: String,
) -> FlowError {
    FlowError::Durability(Box::new(DurabilityFailure {
        kind,
        committed,
        detail,
    }))
}

/// `ENOSPC`, `EFBIG` and `EDQUOT` are a full volume or an exhausted limit, which
/// an operator fixes by freeing space; anything else is an I/O failure.
fn classify_write_error(error: &std::io::Error) -> DurabilityFailureKind {
    use std::io::ErrorKind;
    match error.kind() {
        ErrorKind::StorageFull | ErrorKind::FileTooLarge | ErrorKind::QuotaExceeded => {
            DurabilityFailureKind::StorageFull
        }
        _ => DurabilityFailureKind::WriteFailed,
    }
}

/// Make a rename or a newly created file's directory entry durable.
///
/// A rename is atomic but, until its directory is synced, not durable: after a
/// power loss the old name can come back. Unsupported platforms report `Ok`.
fn sync_parent_directory(path: &Path) -> std::io::Result<()> {
    #[cfg(unix)]
    {
        let parent = path
            .parent()
            .filter(|parent| !parent.as_os_str().is_empty())
            .unwrap_or(Path::new("."));
        File::open(parent)?.sync_all()
    }
    #[cfg(not(unix))]
    {
        let _ = path;
        Ok(())
    }
}

/// The three operations the persistence boundary performs on the log, with a
/// deterministic fault hook in test builds. Production builds compile to the
/// plain calls: there is no runtime switch that can inject a fault.
mod fault {
    use std::fs::File;
    use std::io::Write;

    #[cfg(test)]
    pub(crate) use injection::*;

    /// A named point in a multi-step persistence operation where a test can
    /// make it fail as if the process had stopped or the volume had failed.
    #[derive(Clone, Copy, PartialEq, Eq, Debug)]
    pub(crate) enum Stage {
        CompactionWrite,
        CompactionMidWrite,
        CompactionSync,
        CompactionRename,
        CompactionDirectorySync,
    }

    pub(crate) fn stage(stage: Stage) -> std::io::Result<()> {
        #[cfg(test)]
        if let Some(error) = injection::take(injection::Fault::At(stage)) {
            return Err(error);
        }
        let _ = stage;
        Ok(())
    }

    pub(crate) fn write_all(file: &mut File, bytes: &[u8]) -> std::io::Result<()> {
        #[cfg(test)]
        if let Some(result) = injection::on_write(file, bytes) {
            return result;
        }
        file.write_all(bytes)
    }

    pub(crate) fn sync_data(file: &File) -> std::io::Result<()> {
        #[cfg(test)]
        if let Some(error) = injection::take(injection::Fault::Sync) {
            return Err(error);
        }
        file.sync_data()
    }

    /// Cut the log back to `length` and make the cut durable.
    pub(crate) fn rollback(file: &File, length: u64) -> std::io::Result<()> {
        #[cfg(test)]
        if let Some(error) = injection::take(injection::Fault::Rollback) {
            return Err(error);
        }
        file.set_len(length)?;
        file.sync_all()
    }

    #[cfg(test)]
    mod injection {
        use std::cell::RefCell;
        use std::fs::File;
        use std::io::Write;

        /// A fault armed for the next matching operation on this thread.
        #[derive(Clone, Copy, PartialEq, Eq, Debug)]
        pub(crate) enum Fault {
            /// Write this many bytes, then fail with the given OS error.
            ShortWrite { bytes: usize, errno: i32 },
            /// The barrier fails with `EIO`.
            Sync,
            /// Cutting the log back fails with `EIO`.
            Rollback,
            /// The named stage fails with `EIO`.
            At(super::Stage),
        }

        thread_local! {
            static ARMED: RefCell<Vec<Fault>> = const { RefCell::new(Vec::new()) };
        }

        pub(crate) fn arm(fault: Fault) {
            ARMED.with(|armed| armed.borrow_mut().push(fault));
        }

        pub(crate) fn disarm() {
            ARMED.with(|armed| armed.borrow_mut().clear());
        }

        pub(super) fn take(kind: Fault) -> Option<std::io::Error> {
            ARMED.with(|armed| {
                let mut armed = armed.borrow_mut();
                let index = armed.iter().position(|fault| *fault == kind)?;
                armed.remove(index);
                Some(std::io::Error::from_raw_os_error(5))
            })
        }

        pub(super) fn on_write(file: &mut File, bytes: &[u8]) -> Option<std::io::Result<()>> {
            let fault = ARMED.with(|armed| {
                let mut armed = armed.borrow_mut();
                let index = armed
                    .iter()
                    .position(|fault| matches!(fault, Fault::ShortWrite { .. }))?;
                Some(armed.remove(index))
            })?;
            let Fault::ShortWrite { bytes: partial, errno } = fault else {
                unreachable!()
            };
            let partial = partial.min(bytes.len());
            Some(
                file.write_all(&bytes[..partial])
                    .and_then(|()| file.flush())
                    .and(Err(std::io::Error::from_raw_os_error(errno))),
            )
        }
    }
}

/// The answer to a retried transaction id, read under the commit lock.
///
/// `None` when the id has not committed. Otherwise the *original* commit's
/// revisions and positions, never the store's current ones, or
/// `TransactionIdPayloadMismatch` when a payload hash is given and differs from
/// the one the id was committed with. Nothing is evaluated and nothing is
/// applied: a duplicate is answered before any precondition is read.
fn committed_transaction_locked(
    inner: &Inner,
    transaction_id: &str,
    payload_hash: Option<&str>,
) -> Option<Result<AtomicCommit>> {
    if !inner.applied_transactions.contains(transaction_id) {
        return None;
    }
    if let Some(expected_hash) = payload_hash {
        if inner
            .transaction_payload_hashes
            .get(transaction_id)
            .map(String::as_str)
            != Some(expected_hash)
        {
            return Some(Err(FlowError::TransactionIdPayloadMismatch {
                transaction_id: transaction_id.to_string(),
            }));
        }
    }
    let (base_revision, commit_revision) = inner
        .transaction_revisions
        .get(transaction_id)
        .copied()
        .unwrap_or((inner.authority_revision, inner.authority_revision));
    let (state_before, state_after) = inner
        .transaction_history
        .iter()
        .find(|attribution| attribution.transaction_id == transaction_id)
        .map(|attribution| (attribution.state_before, attribution.state_after))
        .unwrap_or((inner.sequence, inner.sequence));
    Some(Ok(AtomicCommit {
        transaction_id: transaction_id.into(),
        base_revision,
        commit_revision,
        status: TransactionStatus::Committed,
        state_before,
        state_after,
        rows: vec![],
        duplicate: true,
        payload_binding: payload_hash.map(|_| PayloadBinding::Verified),
    }))
}

/// Append a transaction's commit record. A commit always issues a barrier,
/// whatever the single-record durability mode: this append *is* the commit.
fn append_transaction_locked(inner: &mut Inner, transaction: &TransactionLogRecord) -> Result<()> {
    let mut bytes = serde_json::to_vec(transaction)?;
    bytes.push(b'\n');
    append_bytes_locked(inner, &bytes, Barrier::Now)
}

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()
        ))
    }

    /// A commit is attributable: the audit document a transaction already
    /// writes is retained, so a human can ask who made a change.
    #[test]
    fn a_committed_transaction_records_who_committed_it() {
        let path = temp_file();
        let db = open(&path).expect("open");
        db.apply_atomic_transaction(
            "tx_agent_1",
            None,
            &[],
            &[AtomicMutation {
                capability: "billing:Customer".into(),
                key: "cus_1".into(),
                value: Some(serde_json::json!({"name": "Ada", "status": "active"})),
            }],
            Some(serde_json::json!({
                "subject": "agent_data_cleanup",
                "tenant": "acme",
                "application": "app_billing",
                "revision": "rev_7",
            })),
        )
        .expect("commit");

        let recent = db.recent_transactions(10).expect("attributions");
        assert_eq!(recent.len(), 1);
        assert_eq!(recent[0].transaction_id, "tx_agent_1");
        assert_eq!(recent[0].subject.as_deref(), Some("agent_data_cleanup"));
        assert_eq!(recent[0].application_id.as_deref(), Some("app_billing"));
        assert_eq!(recent[0].operations, 1);
        assert_eq!(recent[0].keys, vec!["billing:Customer:cus_1".to_string()]);
        // Attribution says who and what, never what was written.
        assert!(!serde_json::to_string(&recent[0]).unwrap().contains("Ada"));

        let touching = db
            .transactions_touching("billing:Customer", "cus_1", 10)
            .expect("touching");
        assert_eq!(touching.len(), 1);
        assert_eq!(touching[0].transaction_id, "tx_agent_1");
        assert!(db
            .transactions_touching("billing:Customer", "cus_2", 10)
            .expect("touching")
            .is_empty());

        assert_eq!(
            db.transaction_attribution("tx_agent_1")
                .expect("lookup")
                .map(|value| value.subject)
                .flatten()
                .as_deref(),
            Some("agent_data_cleanup")
        );

        // Attribution survives a restart, because it is rebuilt from the same
        // durable records the rest of recovery replays.
        drop(db);
        let reopened = open(&path).expect("reopen");
        let after = reopened.recent_transactions(10).expect("attributions");
        assert_eq!(after.len(), 1);
        assert_eq!(after[0].subject.as_deref(), Some("agent_data_cleanup"));
        assert_eq!(after[0].keys, vec!["billing:Customer:cus_1".to_string()]);
        drop(reopened);
        let _ = fs::remove_file(path);
    }

    /// The window is bounded, and reports that it is.
    #[test]
    fn transaction_attribution_is_bounded_and_newest_first() {
        let path = temp_file();
        let db = open(&path).expect("open");
        let commits = TRANSACTION_ATTRIBUTION_WINDOW + 5;
        for index in 0..commits {
            db.apply_atomic_transaction(
                &format!("tx_{index}"),
                None,
                &[],
                &[AtomicMutation {
                    capability: "app:Note".into(),
                    key: format!("note_{index}"),
                    value: Some(serde_json::json!({"index": index})),
                }],
                Some(serde_json::json!({"subject": format!("actor_{index}")})),
            )
            .expect("commit");
        }
        let (held, capacity) = db.transaction_attribution_window().expect("window");
        assert_eq!(capacity, TRANSACTION_ATTRIBUTION_WINDOW);
        assert_eq!(held, TRANSACTION_ATTRIBUTION_WINDOW);
        let recent = db.recent_transactions(3).expect("attributions");
        assert_eq!(
            recent
                .iter()
                .map(|value| value.transaction_id.clone())
                .collect::<Vec<_>>(),
            vec![
                format!("tx_{}", commits - 1),
                format!("tx_{}", commits - 2),
                format!("tx_{}", commits - 3),
            ]
        );
        // The oldest commit rolled out of the recent window but remains
        // addressable through canonical history.
        assert!(db
            .transaction_attribution("tx_0")
            .expect("lookup")
            .is_some());
        drop(db);
        let _ = fs::remove_file(path);
    }

    #[test]
    fn canonical_transaction_history_survives_window_restart_and_compaction() {
        let path = temp_file();
        let db = open(&path).expect("open");
        let commits = TRANSACTION_ATTRIBUTION_WINDOW + 1;
        for index in 0..commits {
            db.apply_atomic_transaction(
                &format!("history_tx_{index}"),
                None,
                &[],
                &[AtomicMutation {
                    capability: "history:Note".into(),
                    key: format!("note_{index}"),
                    value: Some(serde_json::json!({"index": index})),
                }],
                Some(serde_json::json!({"subject": "agent", "work_id": "work-1"})),
            )
            .expect("commit");
        }
        let complete = db.committed_transactions_after(0, usize::MAX).unwrap();
        assert_eq!(complete.len(), commits);
        assert_eq!(complete[0].transaction_id, "history_tx_0");
        assert_eq!(complete[0].operation_ids.len(), 1);
        assert_ne!(complete[0].operation_ids[0], complete[0].transaction_id);
        assert_eq!(complete[0].work_id.as_deref(), Some("work-1"));
        assert_eq!(
            db.transactions_touching("history:Note", "note_0", 1)
                .unwrap()[0]
                .transaction_id,
            "history_tx_0"
        );
        assert_eq!(
            db.transaction_attribution("history_tx_0")
                .unwrap()
                .unwrap()
                .audit
                .unwrap()["work_id"],
            "work-1"
        );
        let versions = db.operation_versions().unwrap();
        db.acknowledge_peer_versions("history-peer".into(), versions)
            .unwrap();
        db.compact_operation_log(&["history-peer".into()]).unwrap();
        drop(db);

        let reopened = open(&path).expect("reopen");
        assert_eq!(
            reopened
                .committed_transactions_after(0, usize::MAX)
                .unwrap()
                .len(),
            commits
        );
        assert!(reopened
            .transaction_attribution("history_tx_0")
            .unwrap()
            .is_some());
        assert_eq!(
            reopened
                .transactions_touching("history:Note", "note_0", 1)
                .unwrap()[0]
                .transaction_id,
            "history_tx_0"
        );
        assert_eq!(
            reopened
                .transaction_attribution("history_tx_0")
                .unwrap()
                .unwrap()
                .operation_ids,
            complete[0].operation_ids
        );
        let _ = fs::remove_file(sync_metadata_path(&path));
        let _ = fs::remove_file(path);
    }

    #[test]
    fn transaction_payload_binding_survives_restart_and_compaction() {
        let path = temp_file();
        let db = open(&path).expect("open");
        let mutation = AtomicMutation {
            capability: "managed:State".into(),
            key: "record-1".into(),
            value: Some(serde_json::json!({"value": 1})),
        };
        let first = db
            .apply_atomic_transaction_content_addressed(
                "managed-idempotency-1",
                Some("sha256:request-a"),
                None,
                &[],
                &[mutation.clone()],
                None,
            )
            .expect("initial commit");
        let duplicate = db
            .apply_atomic_transaction_content_addressed(
                "managed-idempotency-1",
                Some("sha256:request-a"),
                None,
                &[],
                &[mutation.clone()],
                None,
            )
            .expect("same semantic request");
        assert!(duplicate.duplicate);
        assert_eq!(duplicate.base_revision, first.base_revision);
        assert_eq!(duplicate.commit_revision, first.commit_revision);
        assert_eq!(duplicate.state_before, first.state_before);
        assert_eq!(duplicate.state_after, first.state_after);

        let versions = db.operation_versions().unwrap();
        db.acknowledge_peer_versions("managed-peer".into(), versions)
            .unwrap();
        db.compact_operation_log(&["managed-peer".into()]).unwrap();
        drop(db);

        let reopened = open(&path).expect("restart");
        let replay = reopened
            .apply_atomic_transaction_content_addressed(
                "managed-idempotency-1",
                Some("sha256:request-a"),
                None,
                &[],
                &[mutation.clone()],
                None,
            )
            .expect("retry after restart");
        assert!(replay.duplicate);
        assert_eq!(replay.commit_revision, first.commit_revision);
        let conflict = reopened
            .apply_atomic_transaction_content_addressed(
                "managed-idempotency-1",
                Some("sha256:request-b"),
                None,
                &[],
                &[mutation],
                None,
            )
            .unwrap_err();
        assert!(
            matches!(
                &conflict,
                FlowError::TransactionIdPayloadMismatch { transaction_id } if transaction_id == "managed-idempotency-1"
            ),
            "expected the typed idempotency conflict, got {conflict:?}"
        );
        let _ = fs::remove_file(sync_metadata_path(&path));
        let _ = fs::remove_file(path);
    }

    #[test]
    fn single_record_commits_are_canonical_history_positions() {
        let path = temp_file();
        let db = open(&path).unwrap();
        db.insert("orders:one", serde_json::json!({"status":"paid"}))
            .unwrap();
        let history = db.committed_transactions_after(0, 10).unwrap();
        assert_eq!(history.len(), 1);
        assert!(history[0].transaction_id.starts_with("transaction:"));
        assert!(history[0].operation_ids[0].starts_with("operation:"));
        assert_ne!(history[0].transaction_id, history[0].operation_ids[0]);
        assert_eq!(history[0].keys, vec!["orders:orders:one"]);
        drop(db);
        let reopened = open(&path).unwrap();
        assert_eq!(
            reopened.committed_transactions_after(0, 10).unwrap()[0].transaction_id,
            history[0].transaction_id
        );
        assert_eq!(
            reopened.committed_transactions_after(0, 10).unwrap()[0].operation_ids,
            history[0].operation_ids
        );
        let _ = fs::remove_file(path);
    }

    #[test]
    fn compacted_legacy_attribution_gets_stable_distinct_operation_identity() {
        let legacy = TransactionAttribution {
            transaction_id: "legacy-transaction".into(),
            operation_ids: Vec::new(),
            subject: Some("agent-1".into()),
            tenant_id: Some("tenant-1".into()),
            application_id: Some("app-1".into()),
            application_revision: None,
            base_revision: 4,
            commit_revision: 5,
            state_before: 4,
            state_after: 5,
            keys: vec!["orders:one".into()],
            operations: 2,
            principal_id: None,
            agent_id: Some("agent-1".into()),
            session_id: None,
            delegator_id: None,
            work_id: None,
            unix_ms: 1,
            audit: None,
        };
        let first = normalize_transaction_attribution(legacy.clone());
        let second = normalize_transaction_attribution(legacy);
        assert_eq!(first, second);
        assert_eq!(first.transaction_id, "legacy-transaction");
        assert_eq!(first.operation_ids.len(), 2);
        assert!(first
            .operation_ids
            .iter()
            .all(|operation| operation.starts_with("operation:legacy-transaction:")));

        let single = TransactionAttribution {
            transaction_id: "operation:authority:9".into(),
            operation_ids: Vec::new(),
            operations: 1,
            ..first
        };
        let upgraded = normalize_transaction_attribution(single);
        assert_eq!(upgraded.transaction_id, "transaction:authority:9");
        assert_eq!(upgraded.operation_ids, vec!["operation:authority:9"]);
    }

    /// A bulk transaction names a bounded sample of keys and an exact count.
    #[test]
    fn a_bulk_transaction_truncates_its_key_list_and_keeps_the_count() {
        let path = temp_file();
        let db = open(&path).expect("open");
        let mutations = (0..TRANSACTION_ATTRIBUTION_KEYS + 20)
            .map(|index| AtomicMutation {
                capability: "app:Customer".into(),
                key: format!("cus_{index}"),
                value: Some(serde_json::json!({"index": index})),
            })
            .collect::<Vec<_>>();
        db.apply_atomic_transaction(
            "tx_bulk",
            None,
            &[],
            &mutations,
            Some(serde_json::json!({"subject": "migration_agent"})),
        )
        .expect("commit");
        let attribution = db
            .transaction_attribution("tx_bulk")
            .expect("lookup")
            .expect("held");
        assert_eq!(attribution.operations, mutations.len());
        assert_eq!(attribution.keys.len(), TRANSACTION_ATTRIBUTION_KEYS);
        drop(db);
        let _ = fs::remove_file(path);
    }

    #[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);
    }
}

/// Deterministic failures at the persistence boundary.
///
/// Each test arms a fault for the next write, barrier or rollback on this
/// thread, performs a real write against a real log file, and then checks the
/// three places a write can live: the response, memory, and the log after a
/// reopen. A write reported as not committed must be in none of them, and the
/// log must keep accepting writes.
#[cfg(test)]
mod durability_tests {
    use super::fault::{arm, disarm, Fault};
    use super::*;
    use serde_json::json;

    const ENOSPC: i32 = 28;
    const EFBIG: i32 = 27;
    const EIO: i32 = 5;

    fn database() -> (PathBuf, FeltDb) {
        let directory = std::env::temp_dir().join(format!(
            "feltdb-durability-{}-{}",
            std::process::id(),
            SystemTime::now()
                .duration_since(UNIX_EPOCH)
                .unwrap()
                .as_nanos()
        ));
        fs::create_dir_all(&directory).unwrap();
        let path = directory.join("state.log");
        let db = FeltDb::open(&path).unwrap();
        db.set_durability_mode(DurabilityMode::Synced);
        (path, db)
    }

    fn reopen(path: &Path, db: FeltDb) -> FeltDb {
        drop(db);
        let db = FeltDb::open(path).expect("the log reopens");
        db.set_durability_mode(DurabilityMode::Synced);
        db
    }

    fn failure(result: Result<impl std::fmt::Debug>) -> DurabilityFailure {
        disarm();
        match result {
            Err(FlowError::Durability(failure)) => *failure,
            other => panic!("expected a durability failure, got {other:?}"),
        }
    }

    fn insert_tx(db: &FeltDb, id: &str) -> Result<AtomicCommit> {
        db.apply_atomic_transaction(
            id,
            None,
            &[],
            &[AtomicMutation {
                capability: "notes".into(),
                key: format!("notes:{id}"),
                value: Some(json!({ "id": id })),
            }],
            None,
        )
    }

    #[test]
    fn a_full_disk_fails_the_write_completely_and_the_next_write_lands() {
        let (path, db) = database();
        db.insert("notes:a", json!({ "id": "a" })).unwrap();
        let length = fs::metadata(&path).unwrap().len();
        let operations = db.operations_since(&HashMap::new()).unwrap().len();
        let sequence = db.sequence().unwrap();

        // Half the record reaches the file, then the volume is full.
        arm(Fault::ShortWrite { bytes: 40, errno: ENOSPC });
        let refused = failure(db.insert("notes:b", json!({ "id": "b" })));
        assert_eq!(refused.kind, DurabilityFailureKind::StorageFull);
        assert_eq!(refused.code(), "STORAGE_FULL");
        assert_eq!(refused.committed, Some(false));

        assert_eq!(fs::metadata(&path).unwrap().len(), length, "the partial bytes were removed");
        assert_eq!(db.get_value("notes:b").unwrap(), None, "not visible");
        assert_eq!(db.sequence().unwrap(), sequence, "the reserved sequence was given back");
        assert_eq!(
            db.operations_since(&HashMap::new()).unwrap().len(),
            operations,
            "replication was never offered the refused write"
        );

        // Space is back: the next write appends cleanly, with no splice.
        db.insert("notes:c", json!({ "id": "c" })).unwrap();
        let db = reopen(&path, db);
        assert_eq!(db.log_recovery(), LogRecovery::Clean);
        assert!(db.get_value("notes:a").unwrap().is_some());
        assert_eq!(db.get_value("notes:b").unwrap(), None);
        assert!(db.get_value("notes:c").unwrap().is_some());
    }

    #[test]
    fn a_partial_transaction_record_never_splices_onto_the_next_commit() {
        // Before rollback-on-failure, this exact sequence produced a log that
        // refused to open: the next commit's bytes completed the partial line.
        let (path, db) = database();
        insert_tx(&db, "t1").unwrap();
        arm(Fault::ShortWrite { bytes: 64, errno: EFBIG });
        let refused = failure(insert_tx(&db, "t2"));
        assert_eq!(refused.kind, DurabilityFailureKind::StorageFull);
        assert_eq!(refused.committed, Some(false));
        insert_tx(&db, "t3").unwrap();

        let db = reopen(&path, db);
        assert_eq!(db.log_recovery(), LogRecovery::Clean);
        assert!(db.get_value("notes:t1").unwrap().is_some());
        assert_eq!(db.get_value("notes:t2").unwrap(), None);
        assert!(db.get_value("notes:t3").unwrap().is_some());
        // The refused id is free: retrying it commits, once.
        assert!(!insert_tx(&db, "t2").unwrap().duplicate);
    }

    #[test]
    fn a_failed_barrier_is_rolled_back_so_a_reported_failure_never_resurrects() {
        // Before: a failed fsync left the record in the page cache; the caller
        // was told it failed, and the next start replayed it as committed.
        let (path, db) = database();
        arm(Fault::Sync);
        let refused = failure(insert_tx(&db, "t1"));
        assert_eq!(refused.kind, DurabilityFailureKind::SyncFailed);
        assert_eq!(refused.code(), "STORAGE_SYNC_FAILED");
        assert_eq!(refused.committed, Some(false));

        arm(Fault::Sync);
        let refused = failure(db.insert("notes:s", json!({ "id": "s" })));
        assert_eq!(refused.kind, DurabilityFailureKind::SyncFailed);

        let db = reopen(&path, db);
        assert_eq!(db.get_value("notes:t1").unwrap(), None);
        assert_eq!(db.get_value("notes:s").unwrap(), None);
        assert_eq!(db.log_recovery(), LogRecovery::Clean);
    }

    #[test]
    fn a_write_that_cannot_be_rolled_back_stops_writes_until_reopen_decides() {
        let (path, db) = database();
        db.insert("notes:a", json!({ "id": "a" })).unwrap();

        // The barrier fails and so does the cut: the bytes are in the file.
        arm(Fault::Sync);
        arm(Fault::Rollback);
        let unknown = failure(insert_tx(&db, "t1"));
        assert_eq!(unknown.kind, DurabilityFailureKind::Indeterminate);
        assert_eq!(unknown.code(), "DURABILITY_FAILURE");
        assert_eq!(unknown.committed, None, "the outcome is unknown, and said so");

        // Fail-stop: every write path refuses, before writing anything.
        let length = fs::metadata(&path).unwrap().len();
        for refused in [
            failure(db.insert("notes:b", json!({ "id": "b" }))),
            failure(db.delete("notes:a")),
            failure(insert_tx(&db, "t2")),
            failure(db.compact_operation_log(&[])),
        ] {
            assert_eq!(refused.kind, DurabilityFailureKind::RecoveryRequired);
            assert_eq!(refused.code(), "RECOVERY_REQUIRED");
            assert_eq!(refused.committed, Some(false));
        }
        assert_eq!(fs::metadata(&path).unwrap().len(), length, "nothing more was written");
        assert!(db.get_value("notes:a").unwrap().is_some(), "reads keep serving acknowledged writes");
        let health = db.health();
        assert_eq!(health.writes.label(), "recovery-required");
        assert!(!health.is_nominal());

        // Reopen decides. Here the record's bytes did reach the log intact, so
        // replay holds it committed -- the "unknown" the caller was given.
        let db = reopen(&path, db);
        assert_eq!(db.health().writes, WriteAvailability::Available);
        assert!(db.get_value("notes:t1").unwrap().is_some());
        assert!(insert_tx(&db, "t1").unwrap().duplicate, "a same-id retry reconciles");
        db.insert("notes:b", json!({ "id": "b" })).unwrap();
    }

    #[test]
    fn an_io_error_on_write_is_typed_and_rolled_back() {
        let (path, db) = database();
        arm(Fault::ShortWrite { bytes: 0, errno: EIO });
        let refused = failure(db.update("notes:x", json!({ "id": "x" })));
        assert_eq!(refused.kind, DurabilityFailureKind::WriteFailed);
        assert_eq!(refused.code(), "STORAGE_WRITE_FAILED");
        assert_eq!(refused.committed, Some(false));
        let db = reopen(&path, db);
        assert_eq!(db.get_value("notes:x").unwrap(), None);
    }

    #[test]
    fn a_single_record_write_and_its_revision_are_one_append() {
        // Before: the record was appended, then the revision append failed, and
        // the caller was told a write failed that was committed and visible.
        let (path, db) = database();
        let before = fs::metadata(&path).unwrap().len();
        let record_bytes = {
            db.insert("notes:a", json!({ "id": "a" })).unwrap();
            fs::metadata(&path).unwrap().len() - before
        };
        // Fail inside the revision line: past the record, short of the end.
        let length = fs::metadata(&path).unwrap().len();
        arm(Fault::ShortWrite { bytes: (record_bytes as usize) - 20, errno: ENOSPC });
        let refused = failure(db.insert("notes:b", json!({ "id": "b" })));
        assert_eq!(refused.committed, Some(false));
        assert_eq!(fs::metadata(&path).unwrap().len(), length);
        assert_eq!(db.get_value("notes:b").unwrap(), None);
        let db = reopen(&path, db);
        assert_eq!(db.get_value("notes:b").unwrap(), None, "the failure is the truth after restart too");
        assert_eq!(db.log_recovery(), LogRecovery::Clean);
    }

    #[test]
    fn a_failed_group_barrier_is_indeterminate_for_the_writes_it_covered() {
        let (path, db) = database();
        db.set_durability_mode(DurabilityMode::Grouped { every: 2 });
        db.insert("notes:a", json!({ "id": "a" })).unwrap(); // acknowledged, not yet synced
        arm(Fault::Sync);
        let unknown = failure(db.insert("notes:b", json!({ "id": "b" })));
        assert_eq!(unknown.kind, DurabilityFailureKind::Indeterminate);
        assert_eq!(db.health().writes.label(), "recovery-required");
        drop(reopen(&path, db));
    }

    #[test]
    fn an_interrupted_restore_leaves_no_database_at_the_target() {
        let (path, db) = database();
        for id in ["a", "b", "c"] {
            db.insert(&format!("notes:{id}"), json!({ "id": id })).unwrap();
        }
        let directory = path.parent().unwrap().to_path_buf();
        let backup = directory.join("state.backup");
        db.write_backup(&backup).unwrap();

        // A restore that died after writing part of its staging file.
        let target = directory.join("restored.log");
        let staging = sibling(&target, "restoring");
        fs::write(&staging, b"{\"record_type\":\"feltdb.format\"").unwrap();
        assert!(!target.exists());

        // Rerunning the restore replaces the stale staging and completes.
        let (restored, verification) = FeltDb::restore_backup(&backup, &target).unwrap();
        assert_eq!(verification.rows, 6, "three records and their three revisions");
        assert!(!staging.exists());
        assert!(restored.get_value("notes:c").unwrap().is_some());
        assert_eq!(
            restored.state_digest().unwrap(),
            db.state_digest().unwrap()
        );
        // A second restore to the same target is refused, and changes nothing.
        drop(restored);
        assert!(matches!(
            FeltDb::restore_backup(&backup, &target),
            Err(FlowError::BackupRejected(_))
        ));
    }
}


/// Bounded history: the operation log of a standalone store is a window,
/// compaction reclaims what live state no longer needs, and no interruption of
/// compaction can lose acknowledged data or canonical history.
///
/// See docs/reference/storage-growth.md. Every compaction-stage fault is
/// injected deterministically through `fault::Stage`.
#[cfg(test)]
mod growth_tests {
    use super::fault::{arm, disarm, Fault, Stage};
    use super::*;
    use serde_json::json;

    fn store(name: &str) -> (PathBuf, FeltDb) {
        let directory = std::env::temp_dir().join(format!(
            "feltdb-growth-{name}-{}-{}",
            std::process::id(),
            SystemTime::now().duration_since(UNIX_EPOCH).unwrap().as_nanos()
        ));
        fs::create_dir_all(&directory).unwrap();
        let path = directory.join("state.log");
        let db = FeltDb::open(&path).unwrap();
        (path, db)
    }

    fn reopen(path: &Path, db: FeltDb) -> FeltDb {
        drop(db);
        FeltDb::open(path).expect("the store reopens")
    }

    fn tx(db: &FeltDb, id: &str, key: &str, value: Option<Value>) {
        db.apply_atomic_transaction(
            id,
            None,
            &[],
            &[AtomicMutation { capability: "notes".into(), key: key.into(), value }],
            None,
        )
        .unwrap();
    }

    /// A history-heavy store: every record written through both write paths
    /// several times, and a quarter of them deleted.
    fn churn(db: &FeltDb, records: usize, rounds: usize) {
        for round in 0..rounds {
            for id in 0..records {
                // Values the size of a typical application record, so the
                // reclaimable superseded state is what it is in practice.
                let value = json!({ "id": id, "round": round, "body": "x".repeat(200) });
                if id % 2 == 0 {
                    tx(db, &format!("t-{id}-{round}"), &format!("notes:{id}"), Some(value));
                } else if round == 0 {
                    db.insert(&format!("notes:{id}"), value).unwrap();
                } else {
                    db.update(&format!("notes:{id}"), value).unwrap();
                }
            }
        }
        for id in (0..records).step_by(4) {
            if id % 2 == 0 {
                tx(db, &format!("d-{id}"), &format!("notes:{id}"), None);
            } else {
                db.delete(&format!("notes:{id}")).unwrap();
            }
        }
    }

    /// Everything a compaction must preserve, as one comparable value.
    #[derive(Debug, PartialEq)]
    struct Meaning {
        state: String,
        revisions: u64,
        commits: usize,
        authority_revision: u64,
        sequence: u64,
        versions: HashMap<String, u64>,
    }

    fn meaning(db: &FeltDb) -> Meaning {
        Meaning {
            state: db.state_digest().unwrap(),
            revisions: db
                .list_cardinalities()
                .unwrap()
                .into_iter()
                .find(|(name, _)| name == "state")
                .map(|(_, count)| count)
                .unwrap_or(0),
            commits: db.committed_transactions_after(0, usize::MAX).unwrap().len(),
            authority_revision: db.current_revision().unwrap(),
            sequence: db.sequence().unwrap(),
            versions: db.operation_versions().unwrap(),
        }
    }

    fn retained(db: &FeltDb) -> usize {
        db.operations_since(&HashMap::new()).unwrap().len()
    }

    // --- Version histories (docs/reference/version-tokens.md) ---

    fn cas_version(db: &FeltDb, key: &str) -> u64 {
        db.get_value(key).unwrap().and_then(|value| value.get("__version").and_then(Value::as_u64)).unwrap_or(1)
    }

    #[test]
    fn a_history_is_created_once_and_survives_restart_and_compaction() {
        let (path, db) = store("history-stable");
        let history = db.version_history();
        assert_eq!(history.origin, HistoryOrigin::Genesis);
        assert_eq!(history.id.len(), 32);
        db.insert("notes:1", json!({"n": 1})).unwrap();
        db.compact_operation_log(&[]).unwrap();
        drop(db);
        let reopened = FeltDb::open(&path).unwrap();
        assert_eq!(reopened.version_history(), history, "restart and compaction keep the history");
        let token = reopened.version_token(7);
        assert_eq!(parse_version_token(&token), Some((history.id.as_str(), 7)));
        assert_eq!(reopened.accept_client_version("notes", "notes:1", None, Some(&token)).unwrap(), Some(7));
        assert_eq!(reopened.accept_client_version("notes", "notes:1", Some(7), None).unwrap(), Some(7), "a bare number is accepted in a genesis history");
    }

    #[test]
    fn a_restore_starts_a_history_no_earlier_token_or_bare_number_can_fence() {
        let (_, db) = store("history-restore-source");
        db.insert("notes:1", json!({"n": 1})).unwrap();
        let old = db.version_token(cas_version(&db, "notes:1"));
        let snapshot = db.export_snapshot().unwrap();
        let (_, restored) = store("history-restore-target");
        restored.install_snapshot(snapshot).unwrap();
        assert_eq!(restored.version_history(), db.version_history(), "an install alone (replica bootstrap) shares the source's history");
        let fresh = restored.begin_restored_history().unwrap();
        assert_eq!(fresh.origin, HistoryOrigin::Restored);
        assert_ne!(fresh.id, db.version_history().id);
        // The record is the same, at the same number; the old token is not valid here.
        let version = cas_version(&restored, "notes:1");
        let refused = restored.accept_client_version("notes", "notes:1", None, Some(&old)).unwrap_err();
        assert!(matches!(&refused, FlowError::PreconditionFailed(failure) if matches!(**failure, PreconditionFailure::History { expected: Some(_), .. })), "{refused}");
        let bare = restored.accept_client_version("notes", "notes:1", Some(version), None).unwrap_err();
        assert!(matches!(&bare, FlowError::PreconditionFailed(failure) if matches!(**failure, PreconditionFailure::History { expected: None, .. })), "{bare}");
        assert_eq!(restored.accept_client_version("notes", "notes:1", None, Some(&restored.version_token(version))).unwrap(), Some(version));
        // A second restore of the same backup is yet another history.
        let again = restored.begin_restored_history().unwrap();
        assert_ne!(again.id, fresh.id);
        assert!(restored.accept_client_version("notes", "notes:1", None, Some(&fresh.token(version))).is_err());
    }

    #[test]
    fn malformed_or_disagreeing_tokens_are_refused_as_invalid_input() {
        let (_, db) = store("history-malformed");
        let good = db.version_token(3);
        for bad in ["", "3", "fv1:abc:3", "fv2:00000000000000000000000000000000:3", &format!("{good}:9"), "fv1:0000000000000000000000000000000G:3", "fv1:00000000000000000000000000000000:-1"] {
            let error = db.accept_client_version("c", "c:1", None, Some(bad)).unwrap_err();
            assert!(matches!(&error, FlowError::CapabilityError(message) if message.starts_with("INVALID_VERSION_TOKEN")), "{bad:?}: {error}");
        }
        assert!(db.accept_client_version("c", "c:1", Some(4), Some(&good)).is_err(), "a token and a number naming different versions");
        assert_eq!(db.accept_client_version("c", "c:1", Some(3), Some(&good)).unwrap(), Some(3));
    }

    // --- Snapshot identity and versions (docs/reference/snapshots.md) ---

    fn put_at(db: &FeltDb, capability: &str, key: &str, expected: Option<u64>, value: Value) -> Result<()> {
        db.apply_atomic_transaction(
            &format!("put-{capability}-{key}-{}", rand::random::<u64>()),
            None,
            &[AtomicPrecondition { capability: capability.into(), key: key.into(), expected_version: expected }],
            &[AtomicMutation { capability: capability.into(), key: key.into(), value: Some(value) }],
            None,
        )
        .map(|_| ())
    }

    /// Every live record: identity -> (value, version).
    fn identities(db: &FeltDb) -> BTreeMap<(String, String), (Value, Option<u64>)> {
        db.state_rows()
            .unwrap()
            .into_iter()
            .filter(|row| !row.deleted)
            .map(|row| {
                let version = row.version();
                ((row.capability, row.key), (row.value, version))
            })
            .collect()
    }

    /// A store holding every key form FeltDB writes: key-value keys
    /// (`notes:1`), bare ids, the same bare id in two collections, ids that
    /// themselves contain `:`, and collections whose names contain `:`.
    fn mixed_store(label: &str) -> (PathBuf, FeltDb) {
        let (path, db) = store(label);
        db.insert("notes:1", json!({"kind": "key-value"})).unwrap();
        put_at(&db, "tenant:app:production:notes", "a-p", None, json!({"body": "A"})).unwrap();
        put_at(&db, "tenant:app:staging:notes", "a-p", None, json!({"body": "A staging"})).unwrap();
        put_at(&db, "orders", "1", None, json!({"n": 1})).unwrap();
        put_at(&db, "invoices", "1", None, json!({"n": 2})).unwrap();
        put_at(&db, "system_durable_work", "tenant/app/work_1", None, json!({"state": "READY"})).unwrap();
        put_at(&db, "links", "https://x.test/a:b", None, json!({"ok": true})).unwrap();
        put_at(&db, "notes", "notes:2", None, json!({"kind": "prefixed through a transaction"})).unwrap();
        // A record updated twice and one deleted: versions move, tombstones go.
        put_at(&db, "orders", "2", None, json!({"n": 1})).unwrap();
        let version = identities(&db)[&("orders".to_string(), "2".to_string())].1;
        put_at(&db, "orders", "2", version, json!({"n": 2})).unwrap();
        put_at(&db, "orders", "gone", None, json!({})).unwrap();
        db.apply_atomic_transaction("delete-gone", None, &[], &[AtomicMutation { capability: "orders".into(), key: "gone".into(), value: None }], None).unwrap();
        (path, db)
    }

    #[test]
    fn a_snapshot_preserves_every_record_identity_value_and_version_and_is_deterministic() {
        let (_, db) = mixed_store("snapshot-identity");
        let before = identities(&db);
        assert_eq!(before.len(), 10);
        assert!(!before.contains_key(&("orders".to_string(), "gone".to_string())));
        let snapshot = db.export_snapshot().unwrap();
        snapshot.validate().unwrap();
        // Exporting the same state twice gives the same bytes and hash.
        let again = db.export_snapshot().unwrap();
        assert_eq!(serde_json::to_vec(&snapshot).unwrap(), serde_json::to_vec(&again).unwrap());

        let (path, restored) = store("snapshot-identity-restored");
        restored.install_snapshot(snapshot.clone()).unwrap();
        assert_eq!(identities(&restored), before, "identities, values and versions are the source's");
        // The installed snapshot is itself a valid source: the round trip is exact.
        let second = restored.export_snapshot().unwrap();
        assert_eq!(second.content_hash, snapshot.content_hash);
        drop(restored);
        let reopened = FeltDb::open(&path).unwrap();
        assert_eq!(identities(&reopened), before, "and durable across a restart");
        // The key-value API still finds its record by its combined key.
        assert_eq!(reopened.get_value("notes:1").unwrap(), Some(json!({"kind": "key-value"})));
        // Fences hold on the restored versions: absent is refused, the real version accepted.
        let order = before[&("orders".to_string(), "2".to_string())].1;
        assert!(put_at(&reopened, "orders", "2", None, json!({})).is_err(), "an existing record is not absent");
        put_at(&reopened, "orders", "2", order, json!({"n": 3})).unwrap();
        // A second install into a fresh store gives the same; a used store refuses.
        let (_, twice) = store("snapshot-identity-twice");
        twice.install_snapshot(snapshot.clone()).unwrap();
        assert_eq!(identities(&twice), before);
        assert!(twice.install_snapshot(snapshot).is_err(), "a store with state refuses a snapshot");
    }

    #[test]
    fn snapshot_validation_refuses_ambiguous_or_forged_rows_and_install_agrees() {
        let (_, db) = mixed_store("snapshot-refusals");
        let good = db.export_snapshot().unwrap();
        let resealed = |mut snapshot: DatabaseSnapshot| {
            snapshot.content_hash = DatabaseSnapshot::compute_hash(&snapshot.rows, &snapshot.versions).unwrap();
            snapshot
        };
        let mut cases: Vec<(&str, DatabaseSnapshot)> = Vec::new();
        let mut duplicate = good.clone();
        duplicate.rows.push(duplicate.rows[0].clone());
        cases.push(("same identity", resealed(duplicate)));
        let mut tombstone = good.clone();
        tombstone.rows[0].deleted = true;
        cases.push(("tombstone", resealed(tombstone)));
        let mut operation = good.clone();
        operation.rows[0].operation = db.state_rows().unwrap().into_iter().find_map(|row| row.operation);
        cases.push(("operation", resealed(operation)));
        let mut empty = good.clone();
        empty.rows[0].key = String::new();
        cases.push(("no key", resealed(empty)));
        let mut tampered = good.clone();
        tampered.rows[0].value = json!({"tampered": true});
        cases.push(("tampered", tampered));
        for (label, snapshot) in cases {
            assert!(snapshot.validate().is_err(), "{label}: validation refuses");
            let (_, fresh) = store("snapshot-refusal");
            assert!(fresh.install_snapshot(snapshot).is_err(), "{label}: install refuses");
            assert!(identities(&fresh).is_empty(), "{label}: a refused install applies nothing");
        }
    }

    #[test]
    fn a_snapshot_from_an_earlier_release_installs_and_its_records_fence_as_present() {
        let (_, db) = mixed_store("snapshot-legacy");
        let before = identities(&db);
        // Earlier releases wrote no `recorded_version`; one older row form mixed in
        // with current ones is accepted too.
        let mut legacy = db.export_snapshot().unwrap();
        for row in legacy.rows.iter_mut().skip(1) {
            row.recorded_version = None;
        }
        legacy.content_hash = DatabaseSnapshot::compute_hash(&legacy.rows, &legacy.versions).unwrap();
        let (path, restored) = store("snapshot-legacy-restored");
        restored.install_snapshot(legacy).unwrap();
        let after = identities(&restored);
        assert_eq!(after.keys().collect::<Vec<_>>(), before.keys().collect::<Vec<_>>(), "no identity changes");
        for (identity, (value, version)) in &after {
            assert_eq!(value, &before[identity].0, "{identity:?}: value");
            assert!(version == &before[identity].1 || version == &Some(0), "{identity:?}: its version, or 0 when none was recorded");
        }
        drop(restored);
        let restored = FeltDb::open(&path).unwrap();
        // A record without a recorded version is present: absent is refused,
        // version 0 is accepted and gives it a real version.
        let unversioned = after.iter().find(|(_, (_, version))| *version == Some(0)).unwrap().0.clone();
        assert!(put_at(&restored, &unversioned.0, &unversioned.1, None, json!({})).is_err());
        put_at(&restored, &unversioned.0, &unversioned.1, Some(0), json!({"replaced": true})).unwrap();
        assert_ne!(identities(&restored)[&unversioned].1, Some(0));
    }

    #[test]
    fn compaction_keeps_record_versions_across_a_restart_and_a_snapshot() {
        let (path, db) = mixed_store("compaction-versions");
        // Push every record's operation out of the retained window, then rewrite.
        for index in 0..STANDALONE_OPERATION_WINDOW + 50 {
            put_at(&db, "padding", &index.to_string(), None, json!(index)).unwrap();
        }
        let before = identities(&db);
        db.compact_operation_log(&[]).unwrap();
        drop(db);
        let db = FeltDb::open(&path).unwrap();
        assert_eq!(identities(&db), before, "versions survive compaction and restart");
        let order = before[&("orders".to_string(), "2".to_string())].1;
        assert!(put_at(&db, "orders", "2", None, json!({})).is_err(), "an existing record is not absent");
        put_at(&db, "orders", "2", order, json!({"n": 4})).unwrap();
        // The compacted store snapshots and installs with the same records.
        let current = identities(&db);
        let (_, restored) = store("compaction-versions-restored");
        restored.install_snapshot(db.export_snapshot().unwrap()).unwrap();
        assert_eq!(identities(&restored), current);
    }

    #[test]
    fn a_log_compacted_by_an_earlier_release_reads_its_records_as_present() {
        let (path, db) = mixed_store("compaction-legacy");
        for index in 0..STANDALONE_OPERATION_WINDOW + 50 {
            put_at(&db, "padding", &index.to_string(), None, json!(index)).unwrap();
        }
        db.compact_operation_log(&[]).unwrap();
        let before = identities(&db);
        drop(db);
        // Rewrite the compacted log as earlier releases wrote it: no `recorded_version`.
        let text = fs::read_to_string(&path).unwrap();
        let legacy: Vec<String> = text
            .lines()
            .map(|line| {
                let mut value: Value = serde_json::from_str(line).unwrap();
                if let Some(object) = value.as_object_mut() {
                    object.remove("recorded_version");
                }
                serde_json::to_string(&value).unwrap()
            })
            .collect();
        fs::write(&path, legacy.join("\n") + "\n").unwrap();
        let db = FeltDb::open(&path).unwrap();
        let after = identities(&db);
        assert_eq!(after.keys().collect::<Vec<_>>(), before.keys().collect::<Vec<_>>());
        let order = ("orders".to_string(), "2".to_string());
        assert_eq!(after[&order].0, before[&order].0);
        // Its operation was pruned, so no version was recorded: it reads as 0
        // and is still present to a fence.
        assert_eq!(after[&order].1, Some(0));
        assert!(put_at(&db, "orders", "2", None, json!({})).is_err(), "an existing record is not absent");
        put_at(&db, "orders", "2", Some(0), json!({"n": 5})).unwrap();
        // A record whose operation was retained keeps its real version.
        let padding = ("padding".to_string(), (STANDALONE_OPERATION_WINDOW + 49).to_string());
        assert_eq!(after[&padding].1, before[&padding].1);
    }

    #[test]
    fn a_standalone_store_keeps_a_window_of_operations_and_compaction_preserves_meaning() {
        let (path, db) = store("window");
        churn(&db, 3000, 3);
        let before = meaning(&db);
        let log_before = fs::metadata(&path).unwrap().len();
        assert!(retained(&db) > STANDALONE_OPERATION_WINDOW);

        let outcome = db.maybe_compact_operation_log(&[]).unwrap();
        assert!(outcome.rewrote_log(), "{outcome:?}");
        assert_eq!(retained(&db), STANDALONE_OPERATION_WINDOW);
        assert_eq!(meaning(&db), before, "compaction changes no meaning");
        // What is reclaimed is superseded state and the operations beyond the
        // window; canonical history (revisions, commit attributions) stays.
        let log_after = fs::metadata(&path).unwrap().len();
        assert!(log_after < log_before, "{log_after} vs {log_before}");
        let current_rows: u64 = db.list_cardinalities().unwrap().iter().map(|(_, n)| n).sum();
        let lines = fs::read_to_string(&path).unwrap().lines().count() as u64;
        assert_eq!(
            lines,
            1 + STANDALONE_OPERATION_WINDOW as u64 + current_rows,
            "header + retained window + current rows: no superseded value, no tombstone"
        );

        // Reopen: the same meaning, the same revision, the same window.
        let db = reopen(&path, db);
        assert_eq!(meaning(&db), before);
        assert_eq!(retained(&db), STANDALONE_OPERATION_WINDOW, "retained operations survive reopen");
        // Idempotency survives: an old transaction id answers as a duplicate.
        assert!(db
            .apply_atomic_transaction("t-0-0", None, &[], &[AtomicMutation {
                capability: "notes".into(), key: "notes:0".into(), value: Some(json!({ "id": 0, "round": 0 })),
            }], None)
            .unwrap()
            .duplicate);
        // New commits continue the revision sequence, and survive another reopen.
        db.insert("notes:new", json!({ "n": 1 })).unwrap();
        assert_eq!(db.current_revision().unwrap(), before.authority_revision + 1);
        let after_write = meaning(&db);
        let db = reopen(&path, db);
        assert_eq!(meaning(&db), after_write);
    }

    #[test]
    fn interrupting_compaction_at_any_stage_before_the_switch_changes_nothing() {
        for stage in [Stage::CompactionWrite, Stage::CompactionMidWrite, Stage::CompactionSync, Stage::CompactionRename] {
            let (path, db) = store("stage");
            churn(&db, 2500, 2);
            let before = meaning(&db);
            let bytes = fs::read(&path).unwrap();
            arm(Fault::At(stage));
            let error = db.compact_operation_log(&[]);
            disarm();
            assert!(error.is_err(), "{stage:?}: the injected failure surfaced");
            assert_eq!(fs::read(&path).unwrap(), bytes, "{stage:?}: the log is untouched");
            assert!(!sibling(&path, "compact.tmp").exists(), "{stage:?}: no partial snapshot left");
            assert_eq!(meaning(&db), before, "{stage:?}");
            // The store keeps working and the next compaction succeeds.
            db.insert("notes:after", json!({ "after": true })).unwrap();
            db.compact_operation_log(&[]).unwrap();
            let expected = meaning(&db);
            let db = reopen(&path, db);
            assert_eq!(meaning(&db), expected, "{stage:?}");
        }
    }

    #[test]
    fn a_switch_whose_directory_entry_is_not_durable_stops_writes_until_reopen() {
        let (path, db) = store("dirsync");
        churn(&db, 2500, 2);
        let before = meaning(&db);
        arm(Fault::At(Stage::CompactionDirectorySync));
        assert!(db.compact_operation_log(&[]).is_err());
        disarm();
        assert_eq!(db.health().writes.label(), "recovery-required");
        assert!(matches!(
            db.insert("notes:x", json!({})),
            Err(FlowError::Durability(failure)) if failure.kind == DurabilityFailureKind::RecoveryRequired
        ));
        assert_eq!(meaning(&db), before, "reads keep serving");
        let db = reopen(&path, db);
        assert_eq!(meaning(&db), before);
        db.insert("notes:x", json!({})).unwrap();
    }

    #[test]
    fn a_process_killed_mid_compaction_leaves_the_old_log_authoritative() {
        // The two on-disk states a kill can leave before the switch: a partial
        // snapshot, and a complete one that was never renamed.
        for complete in [false, true] {
            let (path, db) = store("killed");
            churn(&db, 2500, 2);
            let before = meaning(&db);
            drop(db);
            let snapshot = sibling(&path, "compact.tmp");
            {
                // Produce the real snapshot bytes from a copy, then plant them.
                let copy = path.with_file_name("copy.log");
                fs::copy(&path, &copy).unwrap();
                let other = FeltDb::open(&copy).unwrap();
                other.compact_operation_log(&[]).unwrap();
                drop(other);
                let mut bytes = fs::read(&copy).unwrap();
                if !complete {
                    bytes.truncate(bytes.len() / 2);
                }
                fs::write(&snapshot, bytes).unwrap();
            }
            let db = FeltDb::open(&path).unwrap();
            assert_eq!(meaning(&db), before, "complete={complete}");
            assert!(!snapshot.exists(), "the leftover snapshot was removed at open");
        }
    }

    #[test]
    fn writes_during_repeated_compaction_are_all_preserved() {
        let (path, db) = store("concurrent");
        churn(&db, 2000, 2);
        let writer = {
            let db = db.clone();
            std::thread::spawn(move || {
                for i in 0..600 {
                    db.insert(&format!("live:{i}"), json!({ "i": i })).unwrap();
                }
            })
        };
        let mut rewrites = 0;
        while !writer.is_finished() {
            if db.compact_operation_log(&[]).is_ok() {
                rewrites += 1;
            }
            // Let the writer in between rewrites; the rewrite holds the lock.
            std::thread::sleep(std::time::Duration::from_millis(20));
        }
        writer.join().unwrap();
        assert!(rewrites > 0);
        let expected = meaning(&db);
        let db = reopen(&path, db);
        assert_eq!(meaning(&db), expected);
        for i in 0..600 {
            assert!(db.get_value(&format!("live:{i}")).unwrap().is_some(), "live:{i}");
        }
    }

    #[test]
    fn repeated_compaction_and_recovery_converge() {
        let (path, mut db) = store("repeat");
        for cycle in 0..5 {
            churn(&db, 1500, 2);
            db.compact_operation_log(&[]).unwrap();
            let expected = meaning(&db);
            db = reopen(&path, db);
            assert_eq!(meaning(&db), expected, "cycle {cycle}");
            db = reopen(&path, db);
            assert_eq!(meaning(&db), expected, "cycle {cycle}, second reopen");
            // A rewrite of a rewritten log is the same log: its size is a
            // function of state and history, not of how often it was rewritten.
            let log = fs::read(&path).unwrap();
            db.insert(&format!("cycle:{cycle}"), json!({})).unwrap();
            db.delete(&format!("cycle:{cycle}")).unwrap();
            db.compact_operation_log(&[]).unwrap();
            let again = fs::metadata(&path).unwrap().len() as i64;
            assert!((again - log.len() as i64).abs() < 4096, "cycle {cycle}: {again} vs {}", log.len());
        }
    }

    #[test]
    fn backups_taken_before_and_after_compaction_restore_the_same_state() {
        let (path, db) = store("backup");
        churn(&db, 2500, 2);
        let directory = path.parent().unwrap().to_path_buf();
        db.write_backup(&directory.join("before.backup")).unwrap();
        let state = db.state_digest().unwrap();
        db.compact_operation_log(&[]).unwrap();
        db.write_backup(&directory.join("after.backup")).unwrap();
        for name in ["before", "after"] {
            let (restored, _) = FeltDb::restore_backup(
                &directory.join(format!("{name}.backup")),
                &directory.join(format!("{name}.log")),
            )
            .unwrap();
            assert_eq!(restored.state_digest().unwrap(), state, "{name}");
        }
    }

    #[test]
    fn a_store_that_has_replicated_is_never_pruned_as_standalone() {
        let (path, db) = store("replicated");
        churn(&db, 2500, 2);
        let held = retained(&db);
        db.acknowledge_peer_versions("peer-1".into(), HashMap::new()).unwrap();
        assert!(matches!(db.compact_operation_log(&[]), Ok(0)));
        assert_eq!(retained(&db), held, "nothing pruned without the peer's acknowledgement");
        // The fact survives restart (sync metadata), so it is not forgotten.
        let db = reopen(&path, db);
        assert!(matches!(db.compact_operation_log(&[]), Ok(0)));
    }

    #[test]
    fn a_log_rewritten_by_an_older_build_still_replays_as_before() {
        // A header without `authority_revision` replays with the old counting,
        // so revisions a store already reported do not change under upgrade.
        let (path, db) = store("legacy-header");
        churn(&db, 2500, 2);
        db.compact_operation_log(&[]).unwrap();
        drop(db);
        let text = fs::read_to_string(&path).unwrap();
        let (header, rest) = text.split_once('\n').unwrap();
        let mut header: Value = serde_json::from_str(header).unwrap();
        header.as_object_mut().unwrap().remove("authority_revision");
        fs::write(&path, format!("{header}\n{rest}")).unwrap();
        let first = FeltDb::open(&path).unwrap();
        let revision = first.current_revision().unwrap();
        let state = first.state_digest().unwrap();
        let first = reopen(&path, first);
        assert_eq!(first.current_revision().unwrap(), revision, "deterministic");
        assert_eq!(first.state_digest().unwrap(), state);
    }
}

/// Bounded reads: `select_page` and live subscriptions.
///
/// Every property here is checked against a plain reference (sort everything,
/// then slice), over data with duplicate, missing and null ordering values, so
/// a page that is unstable, incomplete, or silently truncated is caught by
/// comparison rather than by inspection.
#[cfg(test)]
mod read_path_tests {
    use super::*;
    use serde_json::json;
    use std::cmp::Ordering;

    fn store(name: &str) -> FeltDb {
        let directory = std::env::temp_dir().join(format!(
            "feltdb-read-{name}-{}-{}",
            std::process::id(),
            SystemTime::now().duration_since(UNIX_EPOCH).unwrap().as_nanos()
        ));
        fs::create_dir_all(&directory).unwrap();
        FeltDb::open(directory.join("state.log")).unwrap()
    }

    /// The test order: `rank` (missing and null first, equal), then key.
    fn rank(row: &StoredRow) -> Option<i64> {
        row.value.get("rank").and_then(Value::as_i64)
    }
    fn compare(left: &StoredRow, right: &StoredRow) -> Ordering {
        rank(left).cmp(&rank(right)).then_with(|| left.key.cmp(&right.key))
    }

    fn seed(db: &FeltDb, count: usize) {
        for n in 0..count {
            // Ranks repeat (duplicates), and every seventh record has none,
            // every eleventh an explicit null.
            let value = if n % 7 == 0 {
                json!({ "n": n, "even": n % 2 == 0 })
            } else if n % 11 == 0 {
                json!({ "n": n, "rank": null, "even": n % 2 == 0 })
            } else {
                json!({ "n": n, "rank": (n * 37) % 50, "even": n % 2 == 0 })
            };
            db.insert(&format!("items:{n:05}"), value).unwrap();
        }
    }

    /// Read every page of a query and return the keys in order.
    fn walk(db: &FeltDb, ordered: bool, limit: usize, filter: impl Fn(&StoredRow) -> bool) -> Vec<String> {
        let mut keys = Vec::new();
        let mut after: Option<StoredRow> = None;
        loop {
            let key_order = (!ordered).then(|| after.as_ref().map(|row| row.key.as_str()));
            let page = db
                .select_page(
                    "items",
                    &[],
                    key_order,
                    limit,
                    &filter,
                    |row| after.as_ref().is_none_or(|last| {
                        if ordered { compare(row, last) == Ordering::Greater } else { row.key > last.key }
                    }),
                    |left, right| if ordered { compare(left, right) } else { left.key.cmp(&right.key) },
                )
                .unwrap();
            assert!(page.rows.len() <= limit);
            keys.extend(page.rows.iter().map(|row| row.key.clone()));
            if !page.has_more {
                return keys;
            }
            assert_eq!(page.rows.len(), limit, "a page with more after it is full");
            after = page.rows.last().cloned();
        }
    }

    fn reference(db: &FeltDb, ordered: bool, filter: impl Fn(&StoredRow) -> bool) -> Vec<String> {
        let mut rows = db.list_collection("items").unwrap();
        rows.retain(|row| filter(row));
        if ordered { rows.sort_by(compare) } else { rows.sort_by(|a, b| a.key.cmp(&b.key)) }
        rows.into_iter().map(|row| row.key).collect()
    }

    #[test]
    fn every_page_size_walks_exactly_the_sorted_result() {
        let db = store("walk");
        seed(&db, 600);
        let even = |row: &StoredRow| row.value.get("even") == Some(&json!(true));
        for ordered in [true, false] {
            for limit in [1, 7, 50, 599, 600, 1000] {
                assert_eq!(walk(&db, ordered, limit, |_| true), reference(&db, ordered, |_| true), "ordered={ordered} limit={limit}");
                assert_eq!(walk(&db, ordered, limit, even), reference(&db, ordered, even), "filtered ordered={ordered} limit={limit}");
            }
        }
    }

    #[test]
    fn a_key_order_page_examines_the_page_not_the_collection() {
        let db = store("seek");
        seed(&db, 5_000);
        let cursor = "items:04000".to_string();
        let page = db
            .select_page("items", &[], Some(Some(&cursor)), 25, |_| true, |row| row.key > cursor, |a, b| a.key.cmp(&b.key))
            .unwrap();
        assert_eq!(page.access, PageAccess::KeyRange);
        assert_eq!(page.rows.first().unwrap().key, "items:04001");
        assert!(page.examined <= 26, "examined {} rows for a page of 25", page.examined);
        assert!(page.has_more);
    }

    #[test]
    fn an_ordered_page_holds_a_page_and_reports_the_scan_it_ran() {
        let db = store("scan");
        seed(&db, 3_000);
        let page = db.select_page("items", &[], None, 10, |_| true, |_| true, compare).unwrap();
        assert_eq!(page.access, PageAccess::Scan, "no index applies: the plan says scan");
        assert_eq!(page.examined, 3_000, "and it examined the collection, as reported");
        assert_eq!(page.rows.len(), 10);
        assert!(page.has_more);
        let expected: Vec<String> = reference(&db, true, |_| true).into_iter().take(10).collect();
        assert_eq!(page.rows.iter().map(|row| row.key.clone()).collect::<Vec<_>>(), expected);
    }

    #[test]
    fn an_equality_index_bounds_the_candidates_and_is_reported() {
        let db = store("index");
        seed(&db, 2_000);
        db.create_equality_index("items", "even").unwrap();
        let yes = json!(true);
        let page = db
            .select_page("items", &[("even", &yes)], None, 5, |row| row.value.get("even") == Some(&yes), |_| true, compare)
            .unwrap();
        assert_eq!(page.access, PageAccess::EqualityIndex);
        assert_eq!(page.examined, 1_000, "the bucket, not the collection");
    }

    #[test]
    fn pages_stay_stable_while_records_are_inserted_and_deleted_between_them() {
        for ordered in [true, false] {
            let db = store("concurrent");
            seed(&db, 300);
            let survivors: Vec<String> = reference(&db, ordered, |_| true);
            let mut seen: Vec<String> = Vec::new();
            let mut after: Option<StoredRow> = None;
            let mut round = 0;
            loop {
                let key_order = (!ordered).then(|| after.as_ref().map(|row| row.key.as_str()));
                let page = db
                    .select_page(
                        "items",
                        &[],
                        key_order,
                        20,
                        |_| true,
                        |row| after.as_ref().is_none_or(|last| if ordered { compare(row, last) == Ordering::Greater } else { row.key > last.key }),
                        |a, b| if ordered { compare(a, b) } else { a.key.cmp(&b.key) },
                    )
                    .unwrap();
                seen.extend(page.rows.iter().map(|row| row.key.clone()));
                if !page.has_more {
                    break;
                }
                after = page.rows.last().cloned();
                // Between pages: insert new records, delete one already seen
                // and one not yet seen.
                round += 1;
                db.insert(&format!("items:9{round:04}"), json!({ "n": 9000 + round, "rank": round % 50 })).unwrap();
                db.delete(&seen[0]).unwrap();
            }
            let mut unique = seen.clone();
            unique.sort();
            unique.dedup();
            assert_eq!(unique.len(), seen.len(), "ordered={ordered}: no record appears twice");
            for key in &survivors {
                let deleted_before_reached = !seen.contains(key) && db.get_value(key).unwrap().is_none();
                assert!(seen.contains(key) || deleted_before_reached, "ordered={ordered}: {key} existed throughout and was skipped");
            }
        }
    }

    /// Live queries are typed: a record matches only if it was written as the
    /// subscription's Rust type.
    #[derive(serde::Serialize, serde::Deserialize, Debug, Clone)]
    struct Item {
        n: u64,
        #[serde(default)]
        active: bool,
    }

    fn item(n: u64, active: bool) -> Item {
        Item { n, active }
    }

    #[tokio::test]
    async fn a_live_query_applies_its_predicate_to_every_change_and_sees_deletes() {
        let db = store("live");
        db.insert("items:1", item(1, true)).unwrap();
        db.insert("items:2", item(2, false)).unwrap();
        let mut live = db.live_query::<Item, _>(|item| item.active).await.unwrap();
        assert_eq!(live.initial_results().iter().map(|item| item.n).collect::<Vec<_>>(), vec![1]);

        db.update("items:2", item(2, true)).unwrap();
        let next = live.next().await.unwrap();
        assert_eq!(next.iter().map(|item| item.n).collect::<Vec<_>>(), vec![1, 2], "the predicate decides membership on update");

        db.update("items:1", item(1, false)).unwrap();
        let next = live.next().await.unwrap();
        assert_eq!(next.iter().map(|item| item.n).collect::<Vec<_>>(), vec![2], "an update can take a record out");

        db.insert("items:3", item(3, false)).unwrap();
        db.delete("items:2").unwrap();
        let next = live.next().await.unwrap();
        assert!(next.is_empty(), "a non-matching insert does not wake it; a delete does: {next:?}");
    }

    #[tokio::test]
    async fn a_write_that_changes_no_result_does_not_wake_a_subscription() {
        let db = store("quiet");
        db.insert("items:1", item(1, true)).unwrap();
        let mut live = db.capability("items").live_find::<Item, _>(|item| item.n < 10).await.unwrap();
        db.insert("other:1", item(1, true)).unwrap();
        db.insert("items:50", item(50, true)).unwrap();
        let woke = tokio::time::timeout(std::time::Duration::from_millis(200), live.next()).await;
        assert!(woke.is_err(), "neither another collection nor a non-match reevaluates it");
        db.insert("items:2", item(2, true)).unwrap();
        let next = tokio::time::timeout(std::time::Duration::from_secs(5), live.next())
            .await
            .expect("a matching insert wakes it")
            .unwrap();
        assert_eq!(next.len(), 2);
    }

    #[tokio::test]
    async fn a_lagged_subscription_recovers_instead_of_ending() {
        let db = store("lag");
        let mut live = db.capability("items").live_find::<Item, _>(|_| true).await.unwrap();
        // Overflow the change channel's buffer (1024) without reading it.
        for n in 0..3_000u64 {
            db.insert(&format!("items:{n}"), item(n, true)).unwrap();
        }
        let recovered = tokio::time::timeout(std::time::Duration::from_secs(10), live.next())
            .await
            .expect("a lagged subscription answers")
            .expect("and continues");
        assert_eq!(recovered.len(), 3_000, "its result is recomputed in full");
    }
}