@feltdb/core 0.8.5 → 0.8.7

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

@@ -295,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.
     ///
@@ -308,6 +308,8 @@ 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
@@ -321,7 +323,7 @@ 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!(
@@ -331,6 +333,7 @@ impl Display for FlowError {
             FlowError::IncompatibleFormat(incompatibility) => {
                 write!(f, "INCOMPATIBLE_DURABLE_FORMAT: {incompatibility}")
             }
+            FlowError::BackupRejected(problem) => write!(f, "BACKUP_REJECTED: {problem}"),
         }
     }
 }
@@ -393,6 +396,22 @@ 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
@@ -771,6 +790,526 @@ 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
@@ -989,46 +1528,124 @@ fn append_derived_row_locked(
         deleted: false,
         operation: None,
     };
-    append_event(&inner.path, &row)?;
+    append_event_locked(inner, &row)?;
     inner.put_row(row);
     Ok(())
 }
 
-/// Mint a revision for an authoritative write, under the caller's lock.
-///
-/// This is where the resource-scoped model meets the write path. The resource
-/// is the record's key, the parent is that resource's current head, and the
-/// sequence is allocated from the parent — so a resource that returns to a value
-/// it previously held records a *new* revision rather than resurrecting the old
-/// one.
+/// Work out the revision an authoritative write will produce, without writing
+/// anything.
 ///
-/// Retention is applied here too, by the same decision function the explicit
-/// store API uses. Bounding history at the moment history is created is what
-/// keeps automatic minting from being an unbounded-history architecture.
-fn mint_revision_locked(inner: &mut Inner, resource: &str, content: String) -> Result<()> {
+/// 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),
     };
-    let authority = inner.instance_id.clone();
-    let revision = state_model::StateRevision::at(
+    state_model::StateRevision::at(
         resource.to_string(),
         content,
         parent_id,
         sequence,
-        authority,
-    );
+        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 key = format!("state:revision:{}", id.as_hex());
-    let value = serde_json::to_value(&revision)?;
-    append_derived_row_locked(inner, "state", &key, value)?;
-    inner
+    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
-        .insert(resource.to_string(), (id, sequence));
-    apply_retention_locked(inner, resource)
+        .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
@@ -1114,9 +1731,12 @@ impl FeltDb {
         // and before anything is written, so a database this build does not
         // understand is refused with its bytes untouched rather than opened
         // with whatever happened to deserialize.
-        if let FormatCompatibility::Incompatible(incompatibility) = inspect_durable_format(&path)? {
-            return Err(FlowError::IncompatibleFormat(Box::new(incompatibility)));
-        }
+        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)?;
@@ -1144,6 +1764,7 @@ impl FeltDb {
         let mut inner = Inner {
             path: path.clone(),
             instance_id: instance_id.clone(),
+            durable_format: accepted_format,
             ..Inner::default()
         };
 
@@ -1161,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(':')
@@ -1277,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,
@@ -1287,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(),
@@ -1298,12 +2155,12 @@ 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 is_versioned(&capability) {
-                mint_revision_locked(&mut inner, key, value.to_string())?;
+            if let Some(revision) = planned {
+                persist_revision_locked(&mut inner, revision)?;
             }
             let event = ChangeEvent {
                 capability,
@@ -2118,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,
@@ -2129,16 +2991,17 @@ 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 is_versioned(&capability) {
-                mint_revision_locked(&mut inner, &key, canonical)?;
+            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()) {
@@ -2193,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,
@@ -2204,16 +3070,17 @@ 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 is_versioned(&capability) {
-                mint_revision_locked(&mut inner, &key, canonical)?;
+            if let Some(revision) = planned {
+                persist_revision_locked(&mut inner, revision)?;
             }
         }
 
@@ -2955,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()
@@ -2991,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
@@ -3174,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 {
@@ -3519,7 +4447,9 @@ pub fn inspect_durable_format(path: &Path) -> Result<FormatCompatibility> {
         )));
     }
 
-    let lines = read_log_lines(path)?;
+    // 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;
 
@@ -3610,56 +4540,120 @@ pub fn inspect_durable_format(path: &Path) -> Result<FormatCompatibility> {
     Ok(FormatCompatibility::Compatible(DurableFormat::Unversioned))
 }
 
-fn read_log_lines(path: &Path) -> Result<Vec<String>> {
+/// 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;
@@ -3671,7 +4665,10 @@ fn replay_log(inner: &mut Inner) -> Result<()> {
             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 =
@@ -3718,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)
@@ -3754,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;
@@ -3762,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(())
 }
 
@@ -3829,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(())
 }