@feltdb/core 0.8.4 → 0.8.6

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

@@ -109,11 +109,14 @@ pub mod replication_manager;
 pub mod replication_protocol;
 mod routing;
 pub mod sharding;
+pub mod state_conflict_contract;
 pub mod state_contract;
+pub mod state_diff_contract;
 pub mod state_facade;
 pub mod state_hash;
 pub mod state_model;
 pub mod state_transition_store;
+pub mod state_trigger;
 mod storage;
 pub mod submission;
 mod sync;
@@ -126,6 +129,7 @@ mod transaction_invariants;
 pub mod transaction_preconditions;
 pub mod transactions;
 mod trigger;
+pub mod trigger_contract;
 pub mod worker_mesh;
 mod workflow;
 #[cfg(test)]
@@ -222,14 +226,27 @@ pub use sharding::{
     HotspotAlert, RebalanceOperation, ShardDistributionSummary, ShardId, ShardKey, ShardManager,
     ShardMetrics, ShardRange, ShardingStrategy,
 };
+pub use state_conflict_contract::{
+    classify_states, StateConflictInput, StateConflictOutput, STATE_CONFLICT_CONTRACT_ID,
+    STATE_CONFLICT_CONTRACT_VERSION,
+};
+pub use state_diff_contract::{
+    diff_states, StateDiffInput, StateDiffOutput, STATE_DIFF_CONTRACT_ID,
+    STATE_DIFF_CONTRACT_VERSION,
+};
 pub use state_facade::FeltDBStateSystem;
 pub use state_hash::{CanonicalState, StateHash};
 pub use state_model::{
-    ChangeKind, ConflictClass, ConflictClassification, PathComponent, PathConflict,
+    apply_reconciliation_plan, path_relation, paths_overlap, reconcile, resolve_path, ChangeKind,
+    ConflictClass, ConflictClassification, PathComponent, PathConflict, PathRelation,
     ReconciliationPlan, Relationship, SemanticChange, SemanticDiff, StateId,
     StateReconciliationResult, StateRevision, StateStore, StateTopology, STATE_MODEL_VERSION,
 };
 pub use state_transition_store::{MemoryStateTransitionStore, StateTransitionRecord};
+pub use state_trigger::{
+    StateTrigger, StateTriggerChangeKind, StateTriggerError, StateTriggerPredicate,
+    StateTriggerStore, TriggeredWorkload,
+};
 pub use storage::{CheckpointData, FileStorage, MemoryStorage, Storage};
 pub use submission::{SubmissionManager, SubmissionMetrics};
 pub use sync::{ChangeLog, Conflict, ConflictDetector, PeerState, SyncMessage, SyncState};
@@ -239,6 +256,12 @@ pub use transactions::{
     StateTransition, TransactionExecutor, TransitionResult,
 };
 pub use trigger::{Trigger, TriggerFilter, TriggerRegistry};
+pub use trigger_contract::{
+    canonical_input_bytes, canonical_output_bytes, evaluate_canonical, evaluate_trigger,
+    ContractChange, ContractChangeKind, ContractErrorBody, ContractErrorCode, ContractPredicate,
+    ContractRuntime, ContractTrigger, MatchOutcome, MatchReason, TriggerMatchInput,
+    TriggerMatchOutput, TRIGGER_MATCH_CONTRACT_ID, TRIGGER_MATCH_CONTRACT_VERSION,
+};
 pub use workflow::{
     BlockedReason, WorkflowGraph, WorkflowInstance, WorkflowNode, WorkflowOperation, WorkflowRef,
     WorkflowState, WorkflowStepRef, WorkflowStepState,
@@ -272,7 +295,7 @@ pub type Result<T> = std::result::Result<T, FlowError>;
 pub enum FlowError {
     Io(std::io::Error),
     Serde(serde_json::Error),
-    CorruptLogLine(String),
+    CorruptLogLine(Box<LogCorruption>),
     CapabilityError(String),
     /// A transaction precondition did not hold. Nothing was written.
     ///
@@ -285,6 +308,14 @@ pub enum FlowError {
         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>),
 }
 
 impl Display for FlowError {
@@ -292,13 +323,17 @@ impl Display for FlowError {
         match self {
             FlowError::Io(e) => write!(f, "io error: {e}"),
             FlowError::Serde(e) => write!(f, "serde error: {e}"),
-            FlowError::CorruptLogLine(line) => write!(f, "corrupt log line: {line}"),
+            FlowError::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::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}"),
         }
     }
 }
@@ -361,6 +396,29 @@ struct Inner {
     /// 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,
+    /// 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)>,
 }
 
 /// The state lock, held with its wait and hold time attributable.
@@ -732,11 +790,627 @@ pub struct StoredRow {
     pub operation: Option<Operation>,
 }
 
+/// 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,
+}
+
+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()
+    }
+}
+
+/// 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,
 }
 
 impl DatabaseSnapshot {
@@ -764,6 +1438,10 @@ struct LogHeader {
     record_type: String,
     local_sequence: u64,
     observed_versions: HashMap<String, u64>,
+    /// Present since format versioning. Absent in headers written before it,
+    /// which deserialize as 0 and are classified as unversioned.
+    #[serde(default)]
+    format_version: u32,
 }
 
 #[derive(Debug, Default, Serialize, Deserialize)]
@@ -777,14 +1455,303 @@ pub fn open<P: AsRef<Path>>(path: P) -> Result<FeltDb> {
     FeltDb::open(path)
 }
 
+/// Capabilities whose rows are not themselves versioned.
+///
+/// `state` holds the revisions, and `_retention` holds the watermark that says
+/// how much of each resource's history survives. Minting a revision of either
+/// would mint a revision of the mint.
+const UNVERSIONED_CAPABILITIES: &[&str] = &["state", "_retention"];
+
+/// Whether a write to this capability creates a revision.
+fn is_versioned(capability: &str) -> bool {
+    !UNVERSIONED_CAPABILITIES.contains(&capability)
+}
+
+/// Rebuild the derived head index from the durable revisions.
+///
+/// Called after recovery, for the same reason `equality_index` is: the index is
+/// a convenience over `rows` and must never be the authority for what `rows`
+/// contains.
+fn rebuild_revision_heads(inner: &mut Inner) {
+    let mut heads: HashMap<String, (state_model::StateId, u64)> = HashMap::new();
+    if let Some(bucket) = inner.rows.get("state") {
+        for row in bucket.values() {
+            if row.deleted || !row.key.starts_with("state:revision:") {
+                continue;
+            }
+            let Ok(revision) =
+                serde_json::from_value::<state_model::StateRevision>(row.value.clone())
+            else {
+                continue;
+            };
+            let entry = heads
+                .entry(revision.resource.clone())
+                .or_insert_with(|| (revision.id.clone(), revision.sequence));
+            if revision.sequence >= entry.1 {
+                *entry = (revision.id.clone(), revision.sequence);
+            }
+        }
+    }
+    inner.revision_heads = heads;
+}
+
+/// Write one derived row inside an already-held state lock.
+///
+/// Deliberately **not** a mutation: no sequence number, no vector clock tick,
+/// no entry in the change log. A revision is a *derived* record of a mutation
+/// that already has all three, and giving it its own would make every write
+/// advance replication twice and double the operation stream.
+///
+/// It is still durable — the row is appended to the log and enters `rows`
+/// inside the same lock as the state it records, so a reader never observes a
+/// mutation whose revision is missing, and a reopened database has both.
+///
+/// The consequence is that revisions are **local and derived**, not replicated.
+/// That is sound in principle, because a revision's identity is a function of
+/// the resource, the content, the parent and the sequence — all of which a peer
+/// that applies the same operation stream has. Whether the sync-apply path
+/// actually mints is a separate question this change does not answer.
+fn append_derived_row_locked(
+    inner: &mut Inner,
+    capability: &str,
+    key: &str,
+    value: Value,
+) -> Result<()> {
+    let row = StoredRow {
+        capability: capability.to_string(),
+        key: key.to_string(),
+        rust_type: "feltdb::state_model::StateRevision".to_string(),
+        value,
+        unix_ms: now_ms(),
+        content_hash: None,
+        flow_ref: None,
+        deleted: false,
+        operation: None,
+    };
+    append_event_locked(inner, &row)?;
+    inner.put_row(row);
+    Ok(())
+}
+
+/// 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 value = serde_json::to_value(&revision)?;
+        append_derived_row_locked(inner, "state", &key, value)?;
+    }
+
+    // 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));
+    }
+
+    apply_retention_locked(inner, &resource)
+}
+
+/// 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.
+/// Expire whatever the resource's configured policy no longer retains.
+///
+/// The common path is one map lookup: with no policy configured there is
+/// nothing to scan. A resource's history is only walked once a policy exists to
+/// bound it.
+fn apply_retention_locked(inner: &mut Inner, resource: &str) -> Result<()> {
+    let retention_key = format!("_retention:{resource}");
+    let Some(state_row) = inner
+        .rows
+        .get("_retention")
+        .and_then(|bucket| bucket.get(&retention_key))
+    else {
+        return Ok(());
+    };
+    let Ok(mut state) = serde_json::from_value::<RetentionRecord>(state_row.value.clone()) else {
+        return Ok(());
+    };
+    if state.policy.keep_last.is_none() {
+        return Ok(());
+    }
+
+    let mut history: Vec<(state_model::StateId, u64)> = Vec::new();
+    if let Some(bucket) = inner.rows.get("state") {
+        for row in bucket.values() {
+            if row.deleted || !row.key.starts_with("state:revision:") {
+                continue;
+            }
+            if let Ok(revision) =
+                serde_json::from_value::<state_model::StateRevision>(row.value.clone())
+            {
+                if revision.resource == resource {
+                    history.push((revision.id, revision.sequence));
+                }
+            }
+        }
+    }
+    history.sort_by_key(|(_, sequence)| *sequence);
+
+    let (expire, horizon) = state_model::revisions_to_expire(&history, state.policy.keep_last);
+    if expire.is_empty() {
+        return Ok(());
+    }
+    for id in &expire {
+        let key = format!("state:revision:{}", id.as_hex());
+        if let Some(bucket) = inner.rows.get_mut("state") {
+            bucket.remove(&key);
+        }
+        let tombstone = StoredRow {
+            capability: "state".to_string(),
+            key,
+            rust_type: "feltdb::state_model::StateRevision".to_string(),
+            value: Value::Null,
+            unix_ms: now_ms(),
+            content_hash: None,
+            flow_ref: None,
+            deleted: true,
+            operation: None,
+        };
+        append_event(&inner.path, &tombstone)?;
+    }
+    if let Some(horizon) = horizon {
+        state.horizon = horizon;
+    }
+    let value = serde_json::to_value(&state)?;
+    append_derived_row_locked(inner, "_retention", &retention_key, value)
+}
+
+/// The durable shape of a resource's retention state.
+///
+/// Mirrors `state_model`'s private record so the write boundary can read and
+/// advance the horizon without the store type.
+#[derive(Clone, Debug, Default, Serialize, Deserialize)]
+struct RetentionRecord {
+    policy: state_model::RetentionPolicy,
+    horizon: u64,
+}
+
 impl FeltDb {
     pub fn open<P: AsRef<Path>>(path: P) -> Result<Self> {
         let path = path.as_ref().to_path_buf();
+
+        // Fail closed. The format is decided before any record is interpreted
+        // and before anything is written, so a database this build does not
+        // understand is refused with its bytes untouched rather than opened
+        // with whatever happened to deserialize.
+        let accepted_format = match inspect_durable_format(&path)? {
+            FormatCompatibility::Incompatible(incompatibility) => {
+                return Err(FlowError::IncompatibleFormat(Box::new(incompatibility)));
+            }
+            FormatCompatibility::Compatible(format) => format,
+        };
+
         if let Some(parent) = path.parent() {
             fs::create_dir_all(parent)?;
         }
         if !path.exists() {
-            OpenOptions::new().create(true).append(true).open(&path)?;
+            let mut file = OpenOptions::new().create(true).append(true).open(&path)?;
+            // A new database states its format in its first record, so it never
+            // has to be inferred again.
+            write_json_line(
+                &mut file,
+                &FormatRecord {
+                    record_type: FORMAT_RECORD_TYPE.to_string(),
+                    format_version: DURABLE_FORMAT_VERSION,
+                },
+            )?;
         }
 
         // Generate instance ID from path hash
@@ -797,6 +1764,7 @@ impl FeltDb {
         let mut inner = Inner {
             path: path.clone(),
             instance_id: instance_id.clone(),
+            durable_format: accepted_format,
             ..Inner::default()
         };
 
@@ -804,6 +1772,7 @@ impl FeltDb {
         inner.sync_state = SyncState::new(instance_id);
         replay_log(&mut inner)?;
         load_sync_metadata(&mut inner)?;
+        rebuild_revision_heads(&mut inner);
 
         let (event_tx, _) = broadcast::channel(1024);
 
@@ -813,6 +1782,239 @@ impl FeltDb {
         })
     }
 
+    /// 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)?;
+        }
+        let mut file = OpenOptions::new()
+            .create(true)
+            .write(true)
+            .truncate(true)
+            .open(path)?;
+        write_json_line(&mut file, &header)?;
+        for row in &rows {
+            write_json_line(&mut file, row)?;
+        }
+        file.flush()?;
+        file.sync_all()?;
+
+        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)?;
+        }
+        {
+            let mut file = OpenOptions::new()
+                .create_new(true)
+                .write(true)
+                .open(target)?;
+            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()?;
+        }
+
+        let restored = FeltDb::open(target)?;
+
+        // The equivalence check. Anything that changed the database's meaning
+        // between the artifact and the live result fails here.
+        let live_rows = {
+            let inner = restored.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
+        };
+        let restored_meaning = backup_meaning_digest(&live_rows)?;
+        if restored_meaning != verification.meaning_digest {
+            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.",
+            ));
+        }
+
+        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,
+            },
+        };
+        DatabaseHealth {
+            durable_format: self.state().durable_format.clone(),
+            recovery,
+            storage,
+        }
+    }
+
+    /// 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(':')
@@ -929,7 +2131,9 @@ impl FeltDb {
             inner.sequence += 1;
             inner.sync_state.increment_vector_clock();
             let vector_clock = inner.sync_state.get_or_init_vector_clock().clone();
-            let operation = Operation::update(
+            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,
@@ -939,6 +2143,7 @@ impl FeltDb {
                 capability.clone(),
             )
             .with_vector_clock(vector_clock);
+            operation.revision = planned.as_ref().map(provenance_of);
             let row = StoredRow {
                 capability: capability.clone(),
                 key: key.to_string(),
@@ -950,10 +2155,13 @@ impl FeltDb {
                 deleted: false,
                 operation: Some(operation.clone()),
             };
-            append_event(&inner.path, &row)?;
+            append_event_locked(&mut inner, &row)?;
             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(),
@@ -1740,6 +2948,9 @@ impl FeltDb {
     ) -> Result<()> {
         let rust_type = type_name::<T>().to_string();
         let value_json = serde_json::to_value(value)?;
+        // Canonical because `serde_json` is built without `preserve_order`, so
+        // `Map` is a `BTreeMap` and `to_string` emits keys in sorted order.
+        let canonical = value_json.to_string();
         let mut row = StoredRow {
             capability: capability.clone(),
             key: key.clone(),
@@ -1764,8 +2975,13 @@ impl FeltDb {
             // 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 op = Operation::insert(
+            let mut op = Operation::insert(
                 inner.sequence,
                 inner.instance_id.clone(),
                 inner.sequence,
@@ -1775,14 +2991,18 @@ impl FeltDb {
                 capability.clone(),
             )
             .with_vector_clock(vector_clock);
+            op.revision = planned.as_ref().map(provenance_of);
 
             // Add operation to change log for sync
             row.operation = Some(op.clone());
             inner.change_log.add_operation(op.clone());
 
-            append_event(&inner.path, &row)?;
+            append_event_locked(&mut inner, &row)?;
             inner.authority_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();
@@ -1809,6 +3029,9 @@ impl FeltDb {
     ) -> Result<()> {
         let rust_type = type_name::<T>().to_string();
         let value_json = serde_json::to_value(value)?;
+        // Canonical because `serde_json` is built without `preserve_order`, so
+        // `Map` is a `BTreeMap` and `to_string` emits keys in sorted order.
+        let canonical = value_json.to_string();
         let mut row = StoredRow {
             capability: capability.clone(),
             key: key.clone(),
@@ -1833,8 +3056,11 @@ impl FeltDb {
             // 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 op = Operation::update(
+            let mut op = Operation::update(
                 inner.sequence,
                 inner.instance_id.clone(),
                 inner.sequence,
@@ -1844,14 +3070,18 @@ impl FeltDb {
                 capability.clone(),
             )
             .with_vector_clock(vector_clock);
+            op.revision = planned.as_ref().map(provenance_of);
 
             // Add operation to change log for sync
             row.operation = Some(op.clone());
             inner.change_log.add_operation(op.clone());
 
-            append_event(&inner.path, &row)?;
+            append_event_locked(&mut inner, &row)?;
             inner.authority_revision += 1;
             inner.put_row(row);
+            if let Some(revision) = planned {
+                persist_revision_locked(&mut inner, revision)?;
+            }
         }
 
         let event = ChangeEvent {
@@ -2062,8 +3292,9 @@ impl FeltDb {
                     // 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);
+                    let _predicate = workload_diagnostics::span(
+                        workload_diagnostics::Phase::PredicateEvaluation,
+                    );
                     if predicate(row) {
                         drop(_predicate);
                         matched.push(row.clone());
@@ -2102,7 +3333,10 @@ impl FeltDb {
         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,
+            acquired
+                .duration_since(requested)
+                .as_nanos()
+                .min(u64::MAX as u128) as u64,
         );
         StateGuard {
             inner,
@@ -2216,7 +3450,7 @@ impl FeltDb {
             }
         }
         Ok(Err(
-            "the live index holds entries no authoritative record derives".to_string()
+            "the live index holds entries no authoritative record derives".to_string(),
         ))
     }
 
@@ -2432,6 +3666,7 @@ impl FeltDb {
             rows,
             versions,
             content_hash,
+            format_version: DURABLE_FORMAT_VERSION,
         })
     }
     /// Current materialized rows including their causal operation envelopes.
@@ -2470,6 +3705,24 @@ impl FeltDb {
     /// Install a verified bootstrap snapshot into a pristine node. A node with
     /// local history must converge through operations rather than overwrite it.
     pub fn install_snapshot(&self, snapshot: DatabaseSnapshot) -> Result<()> {
+        // A snapshot carries whole rows, revisions included, so installing one
+        // from another format would reintroduce exactly the silent
+        // misinterpretation the on-disk version prevents.
+        if snapshot.format_version != DURABLE_FORMAT_VERSION {
+            return Err(FlowError::IncompatibleFormat(Box::new(
+                FormatIncompatibility {
+                    found: if snapshot.format_version == 0 {
+                        DurableFormat::Unversioned
+                    } else {
+                        DurableFormat::Versioned(snapshot.format_version)
+                    },
+                    required: DURABLE_FORMAT_VERSION,
+                    reason: "the snapshot was produced in a different durable format".to_string(),
+                    action: "Take a fresh snapshot from a FeltDB build matching this one."
+                        .to_string(),
+                },
+            )));
+        }
         snapshot.verify()?;
         let mut inner = self.state();
         if !inner.rows.is_empty() || !inner.change_log.pending.is_empty() {
@@ -2498,6 +3751,7 @@ impl FeltDb {
             &mut file,
             &LogHeader {
                 record_type: "feltdb.snapshot.v1".to_string(),
+                format_version: DURABLE_FORMAT_VERSION,
                 local_sequence: inner.sequence,
                 observed_versions: snapshot.versions.clone(),
             },
@@ -2568,12 +3822,56 @@ impl FeltDb {
     /// 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();
         let removed = inner.change_log.prune_acknowledged(active_peers);
         if removed == 0 {
-            return Ok(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.
+        if !force && inner.pruned_since_rewrite < inner.compaction_policy.rewrite_after_pruned {
+            return Ok(CompactionOutcome::Deferred {
+                pruned: removed,
+                pending_since_rewrite: inner.pruned_since_rewrite,
+            });
+        }
 
         let temporary = inner.path.with_extension("compact.tmp");
         let mut file = OpenOptions::new()
@@ -2585,6 +3883,7 @@ impl FeltDb {
             &mut file,
             &LogHeader {
                 record_type: "feltdb.snapshot.v1".to_string(),
+                format_version: DURABLE_FORMAT_VERSION,
                 local_sequence: inner.sequence,
                 observed_versions: inner.change_log.versions(),
             },
@@ -2603,7 +3902,8 @@ impl FeltDb {
         file.sync_all()?;
         fs::rename(temporary, &inner.path)?;
         inner.bootstrapped = true;
-        Ok(removed)
+        inner.pruned_since_rewrite = 0;
+        Ok(CompactionOutcome::Rewritten { pruned: removed })
     }
 
     /// Register a peer in the distributed fabric
@@ -2786,6 +4086,22 @@ impl FeltDb {
             *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 {
@@ -3113,64 +4429,246 @@ where
 ///
 /// Damage anywhere earlier is not an interrupted write. Recovery refuses it
 /// rather than silently dropping committed history.
-fn read_log_lines(path: &Path) -> Result<Vec<String>> {
+/// 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.
+    let scan = scan_log(path)?;
+    let lines: Vec<String> = scan.lines.into_iter().map(|line| line.text).collect();
+    let mut declared: Option<u32> = None;
+    let mut legacy_revision = false;
+
+    for line in &lines {
+        if line.trim().is_empty() {
+            continue;
+        }
+        let Ok(value) = serde_json::from_str::<Value>(line) else {
+            continue;
+        };
+        match value.get("record_type").and_then(Value::as_str) {
+            Some(FORMAT_RECORD_TYPE) => {
+                if let Some(version) = value.get("format_version").and_then(Value::as_u64) {
+                    declared = Some(version as u32);
+                }
+            }
+            Some("feltdb.snapshot.v1" | "flowdb.snapshot.v1") => {
+                match value.get("format_version").and_then(Value::as_u64) {
+                    Some(version) if version > 0 => declared = Some(version as u32),
+                    _ => {}
+                }
+            }
+            _ => {
+                // The unversioned-era probe: a revision record that predates
+                // resource-scoped identity. Deliberate and specific — it looks
+                // for a named absence rather than trying to parse and shrugging
+                // at failure.
+                let is_revision = value
+                    .get("key")
+                    .and_then(Value::as_str)
+                    .is_some_and(|key| key.starts_with("state:revision:"));
+                if is_revision
+                    && value
+                        .get("value")
+                        .and_then(Value::as_object)
+                        .is_some_and(|revision| !revision.contains_key("resource"))
+                {
+                    legacy_revision = true;
+                }
+            }
+        }
+    }
+
+    if let Some(version) = declared {
+        return Ok(match version.cmp(&DURABLE_FORMAT_VERSION) {
+            std::cmp::Ordering::Equal => {
+                FormatCompatibility::Compatible(DurableFormat::Versioned(version))
+            }
+            std::cmp::Ordering::Greater => {
+                FormatCompatibility::Incompatible(FormatIncompatibility {
+                    found: DurableFormat::Versioned(version),
+                    required: DURABLE_FORMAT_VERSION,
+                    reason: "the database was written by a newer FeltDB".to_string(),
+                    action: "Run a FeltDB build that understands this format, or restore \
+                             a backup taken in an older format."
+                        .to_string(),
+                })
+            }
+            std::cmp::Ordering::Less => FormatCompatibility::Incompatible(FormatIncompatibility {
+                found: DurableFormat::Versioned(version),
+                required: DURABLE_FORMAT_VERSION,
+                reason: "the database was written in an older durable format".to_string(),
+                action: "Migrate the database with a FeltDB build that supports both \
+                             formats, or restore a backup."
+                    .to_string(),
+            }),
+        });
+    }
+
+    if legacy_revision {
+        return Ok(FormatCompatibility::Incompatible(FormatIncompatibility {
+            found: DurableFormat::Unversioned,
+            required: DURABLE_FORMAT_VERSION,
+            reason: "it holds revision records written before revisions belonged to a \
+                     resource, and those records cannot be migrated without inventing \
+                     information they never contained: a revision recorded no resource, \
+                     so which history each one belongs to is not recoverable from the data"
+                .to_string(),
+            action: "Export the application state you need from a FeltDB build that \
+                     understands the old format, then load it into a new database. The \
+                     existing file has not been modified."
+                .to_string(),
+        }));
+    }
+
+    // No format record and no legacy revision: nothing in this database depends
+    // on the difference.
+    Ok(FormatCompatibility::Compatible(DurableFormat::Unversioned))
+}
+
+/// 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.
+struct TornTail {
+    byte_offset: u64,
+    bytes: usize,
+}
+
+/// The durable log, read and classified. **This never writes.**
+struct LogScan {
+    lines: Vec<ScannedLine>,
+    torn_tail: Option<TornTail>,
+}
+
+/// Read the durable log without modifying it.
+///
+/// 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 reported
+/// as a torn tail. Everything else — including a complete final record that
+/// happens to be invalid — is returned as a line, 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 scan_log(path: &Path) -> Result<LogScan> {
     let mut file = BufReader::new(OpenOptions::new().read(true).open(path)?);
-    let mut lines: Vec<(String, bool)> = Vec::new();
+    let mut lines = Vec::new();
+    let mut torn_tail = None;
     let mut buffer = Vec::new();
+    let mut offset = 0u64;
+    let mut line_number = 0usize;
+
     loop {
         buffer.clear();
-        if file.read_until(b'\n', &mut buffer)? == 0 {
+        let read = file.read_until(b'\n', &mut buffer)?;
+        if read == 0 {
             break;
         }
         let terminated = buffer.ends_with(b"\n");
         let text = String::from_utf8_lossy(&buffer)
             .trim_end_matches('\n')
             .to_string();
-        lines.push((text, terminated));
-    }
-
-    let mut torn_bytes = 0usize;
-    if let Some((text, terminated)) = lines.last() {
-        let unusable = !*terminated || serde_json::from_str::<Value>(text).is_err();
-        if unusable && !text.trim().is_empty() {
-            torn_bytes = text.len() + usize::from(*terminated);
-            lines.pop();
+        line_number += 1;
+
+        if !terminated {
+            // An unterminated final record: the write did not finish. Empty
+            // trailing bytes are nothing at all and are simply ignored.
+            if !text.trim().is_empty() {
+                torn_tail = Some(TornTail {
+                    byte_offset: offset,
+                    bytes: read,
+                });
+            }
+            break;
         }
-    }
 
-    if torn_bytes > 0 {
-        let file = OpenOptions::new().write(true).open(path)?;
-        let length = file.metadata()?.len();
-        file.set_len(length.saturating_sub(torn_bytes as u64))?;
-        file.sync_all()?;
+        lines.push(ScannedLine {
+            text,
+            line_number,
+            byte_offset: offset,
+        });
+        offset += read as u64;
     }
 
-    Ok(lines.into_iter().map(|(text, _)| text).collect())
+    Ok(LogScan { lines, torn_tail })
+}
+
+/// 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 lines = read_log_lines(&inner.path)?;
+    let scan = scan_log(&inner.path)?;
+    let torn_tail = scan.torn_tail;
+    let lines = scan.lines;
 
     let mut snapshot_log = false;
-    for line in lines {
-        if line.trim().is_empty() {
+    let mut recoverable_revisions: Vec<(operation::RevisionProvenance, Value)> = Vec::new();
+    for line in &lines {
+        if line.text.trim().is_empty() {
             continue;
         }
         let value: Value =
-            serde_json::from_str(&line).map_err(|_| FlowError::CorruptLogLine(line.clone()))?;
+            serde_json::from_str(&line.text).map_err(|_| corruption(line, "not valid JSON"))?;
         if matches!(
             value.get("record_type").and_then(Value::as_str),
             Some("feltdb.snapshot.v1" | "flowdb.snapshot.v1")
         ) {
-            let header: LogHeader = serde_json::from_value(value)?;
+            let header: LogHeader = serde_json::from_value(value)
+                .map_err(|error| corruption(line, &format!("malformed log header: {error}")))?;
             inner.sequence = inner.sequence.max(header.local_sequence);
             inner.change_log.observed_versions = header.observed_versions;
             inner.bootstrapped = true;
             snapshot_log = true;
             continue;
         }
+        if value.get("record_type").and_then(Value::as_str) == Some(FORMAT_RECORD_TYPE) {
+            // Already honoured by `inspect_durable_format` before the open.
+            continue;
+        }
         if value.get("record_type").and_then(Value::as_str) == Some("feltdb.transaction.v1") {
-            let transaction: TransactionLogRecord = serde_json::from_value(value)?;
+            let transaction: TransactionLogRecord =
+                serde_json::from_value(value).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 =
@@ -3217,9 +4715,16 @@ fn replay_log(inner: &mut Inner) -> Result<()> {
             inner.sequence = inner.sequence.max(transaction.state_after);
             continue;
         }
-        let row: StoredRow =
-            serde_json::from_value(value).map_err(|_| FlowError::CorruptLogLine(line.clone()))?;
+        let row: StoredRow = serde_json::from_value(value)
+            .map_err(|_| corruption(line, "not a durable record this build understands"))?;
         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.
+            if let (Some(provenance), Some(value)) = (&operation.revision, &operation.value) {
+                recoverable_revisions.push((provenance.clone(), value.clone()));
+            }
             inner.sequence = inner.sequence.max(
                 (operation.instance_id == inner.instance_id)
                     .then_some(operation.sequence)
@@ -3253,6 +4758,61 @@ fn replay_log(inner: &mut Inner) -> Result<()> {
         }
     }
 
+    // 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 {
+        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 {
+            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;
@@ -3261,6 +4821,17 @@ fn replay_log(inner: &mut Inner) -> Result<()> {
             .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(())
 }
 
@@ -3328,15 +4899,46 @@ fn persist_sync_metadata(inner: &Inner) -> Result<()> {
 }
 
 fn append_event(path: &Path, event: &StoredRow) -> Result<()> {
-    // Single-record durability: the line is written and flushed to the OS, but
-    // not fsynced. `append_transaction` below does fsync. The asymmetry is
-    // pre-existing and PR36 measures it rather than changing it.
+    append_event_with(path, event, DurabilityMode::Flushed, &mut 0)
+}
+
+/// Append one record under the database's configured durability mode.
+fn append_event_locked(inner: &mut Inner, event: &StoredRow) -> Result<()> {
+    let path = inner.path.clone();
+    let mode = inner.durability_mode;
+    append_event_with(&path, event, mode, &mut inner.writes_since_barrier)
+}
+
+/// Append one record, pushing it as far as the durability mode requires.
+///
+/// `since_barrier` counts writes since the last stable-storage barrier and is
+/// only read by [`DurabilityMode::Grouped`].
+fn append_event_with(
+    path: &Path,
+    event: &StoredRow,
+    mode: DurabilityMode,
+    since_barrier: &mut u32,
+) -> Result<()> {
     let _span = workload_diagnostics::span(workload_diagnostics::Phase::Persistence);
     let mut file = OpenOptions::new().create(true).append(true).open(path)?;
     let mut line = serde_json::to_string(event)?;
     line.push('\n');
     file.write_all(line.as_bytes())?;
     file.flush()?;
+
+    // The flush above is what makes a record survive the process dying. What
+    // follows is the only thing that even asks the storage stack for more.
+    match mode {
+        DurabilityMode::Flushed => {}
+        DurabilityMode::Synced => file.sync_all()?,
+        DurabilityMode::Grouped { every } => {
+            *since_barrier += 1;
+            if *since_barrier >= every.max(1) {
+                file.sync_all()?;
+                *since_barrier = 0;
+            }
+        }
+    }
     Ok(())
 }