@feltdb/core 0.8.4 → 0.8.5

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,
@@ -285,6 +308,12 @@ pub enum FlowError {
         expected: u64,
         actual: u64,
     },
+    /// The durable database is in a format this build does not understand.
+    ///
+    /// Returned by [`FeltDb::open`] **before any record is interpreted**, and
+    /// before anything is written. A database that returns this error is
+    /// untouched.
+    IncompatibleFormat(Box<FormatIncompatibility>),
 }
 
 impl Display for FlowError {
@@ -299,6 +328,9 @@ impl Display for FlowError {
                 f,
                 "REVISION_CONFLICT: expected authority revision {expected}, current revision is {actual}"
             ),
+            FlowError::IncompatibleFormat(incompatibility) => {
+                write!(f, "INCOMPATIBLE_DURABLE_FORMAT: {incompatibility}")
+            }
         }
     }
 }
@@ -361,6 +393,13 @@ struct Inner {
     /// inside the same state mutation boundary as `rows` and rebuilt from
     /// `rows` after recovery.
     equality_index: EqualityIndex,
+    /// Each resource's newest revision, as `(id, sequence)`.
+    ///
+    /// Derived from the `state` rows exactly like `equality_index` is derived
+    /// from `rows`: never durable, rebuilt after recovery. It exists so that
+    /// minting a revision does not have to scan a resource's history to find
+    /// the parent it descends from.
+    revision_heads: HashMap<String, (state_model::StateId, u64)>,
 }
 
 /// The state lock, held with its wait and hold time attributable.
@@ -732,11 +771,107 @@ pub struct StoredRow {
     pub operation: Option<Operation>,
 }
 
+/// The durable format this build writes and understands.
+///
+/// Independent of the package version on purpose: an application release that
+/// changes nothing about persistence must not appear to change the database.
+///
+/// - **1** — everything before revisions became resource-scoped. Never written
+///   by any build; it names the era that predates format versioning.
+/// - **2** — resource-scoped revisions: a `StateRevision` carries `resource`,
+///   `content_id` and `sequence`.
+pub const DURABLE_FORMAT_VERSION: u32 = 2;
+
+/// The log record that carries the format version.
+const FORMAT_RECORD_TYPE: &str = "feltdb.format.v1";
+
+#[derive(Debug, Serialize, Deserialize)]
+struct FormatRecord {
+    record_type: String,
+    format_version: u32,
+}
+
+/// What format a durable database is in.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum DurableFormat {
+    /// A format record states the version.
+    Versioned(u32),
+    /// No format record: the database predates format versioning.
+    ///
+    /// This is a version, not an absence of one. It is the only case where the
+    /// records themselves are examined to decide compatibility, and that
+    /// examination is a deliberate one-time probe rather than a deserialization
+    /// attempt whose failure is discarded.
+    Unversioned,
+}
+
+impl Display for DurableFormat {
+    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
+        match self {
+            DurableFormat::Versioned(version) => write!(f, "version {version}"),
+            DurableFormat::Unversioned => write!(f, "unversioned (predates format versioning)"),
+        }
+    }
+}
+
+/// Why a durable database cannot be opened, and what to do about it.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct FormatIncompatibility {
+    /// What the database is.
+    pub found: DurableFormat,
+    /// What this build requires.
+    pub required: u32,
+    /// What is wrong, in terms of the data rather than the code.
+    pub reason: String,
+    /// What the operator can do.
+    pub action: String,
+}
+
+impl Display for FormatIncompatibility {
+    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
+        write!(
+            f,
+            "durable format {} is incompatible with this FeltDB, which requires \
+             format version {}; {}. No data was read or modified. {}",
+            self.found, self.required, self.reason, self.action
+        )
+    }
+}
+
+/// The result of examining a durable database without opening it.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum FormatCompatibility {
+    /// Safe to open.
+    Compatible(DurableFormat),
+    /// Must not be opened.
+    Incompatible(FormatIncompatibility),
+}
+
+impl FormatCompatibility {
+    /// Whether opening this database is safe.
+    pub fn is_compatible(&self) -> bool {
+        matches!(self, FormatCompatibility::Compatible(_))
+    }
+}
+
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct DatabaseSnapshot {
     pub rows: Vec<StoredRow>,
     pub versions: HashMap<String, u64>,
     pub content_hash: String,
+    /// The durable format the rows are in.
+    ///
+    /// A snapshot carries whole `StoredRow`s, revisions included, so it is a
+    /// durable interchange artifact and not merely a protocol value: installing
+    /// one from a different format would reintroduce exactly the silent
+    /// misinterpretation the on-disk version exists to prevent.
+    ///
+    /// Defaults to 0 so a snapshot serialized before versioning still
+    /// deserializes; 0 is treated as unversioned and refused rather than
+    /// assumed current. `content_hash` deliberately does not cover this field,
+    /// so hashes computed before it existed remain valid.
+    #[serde(default)]
+    pub format_version: u32,
 }
 
 impl DatabaseSnapshot {
@@ -764,6 +899,10 @@ struct LogHeader {
     record_type: String,
     local_sequence: u64,
     observed_versions: HashMap<String, u64>,
+    /// Present since format versioning. Absent in headers written before it,
+    /// which deserialize as 0 and are classified as unversioned.
+    #[serde(default)]
+    format_version: u32,
 }
 
 #[derive(Debug, Default, Serialize, Deserialize)]
@@ -777,14 +916,222 @@ pub fn open<P: AsRef<Path>>(path: P) -> Result<FeltDb> {
     FeltDb::open(path)
 }
 
+/// Capabilities whose rows are not themselves versioned.
+///
+/// `state` holds the revisions, and `_retention` holds the watermark that says
+/// how much of each resource's history survives. Minting a revision of either
+/// would mint a revision of the mint.
+const UNVERSIONED_CAPABILITIES: &[&str] = &["state", "_retention"];
+
+/// Whether a write to this capability creates a revision.
+fn is_versioned(capability: &str) -> bool {
+    !UNVERSIONED_CAPABILITIES.contains(&capability)
+}
+
+/// Rebuild the derived head index from the durable revisions.
+///
+/// Called after recovery, for the same reason `equality_index` is: the index is
+/// a convenience over `rows` and must never be the authority for what `rows`
+/// contains.
+fn rebuild_revision_heads(inner: &mut Inner) {
+    let mut heads: HashMap<String, (state_model::StateId, u64)> = HashMap::new();
+    if let Some(bucket) = inner.rows.get("state") {
+        for row in bucket.values() {
+            if row.deleted || !row.key.starts_with("state:revision:") {
+                continue;
+            }
+            let Ok(revision) =
+                serde_json::from_value::<state_model::StateRevision>(row.value.clone())
+            else {
+                continue;
+            };
+            let entry = heads
+                .entry(revision.resource.clone())
+                .or_insert_with(|| (revision.id.clone(), revision.sequence));
+            if revision.sequence >= entry.1 {
+                *entry = (revision.id.clone(), revision.sequence);
+            }
+        }
+    }
+    inner.revision_heads = heads;
+}
+
+/// Write one derived row inside an already-held state lock.
+///
+/// Deliberately **not** a mutation: no sequence number, no vector clock tick,
+/// no entry in the change log. A revision is a *derived* record of a mutation
+/// that already has all three, and giving it its own would make every write
+/// advance replication twice and double the operation stream.
+///
+/// It is still durable — the row is appended to the log and enters `rows`
+/// inside the same lock as the state it records, so a reader never observes a
+/// mutation whose revision is missing, and a reopened database has both.
+///
+/// The consequence is that revisions are **local and derived**, not replicated.
+/// That is sound in principle, because a revision's identity is a function of
+/// the resource, the content, the parent and the sequence — all of which a peer
+/// that applies the same operation stream has. Whether the sync-apply path
+/// actually mints is a separate question this change does not answer.
+fn append_derived_row_locked(
+    inner: &mut Inner,
+    capability: &str,
+    key: &str,
+    value: Value,
+) -> Result<()> {
+    let row = StoredRow {
+        capability: capability.to_string(),
+        key: key.to_string(),
+        rust_type: "feltdb::state_model::StateRevision".to_string(),
+        value,
+        unix_ms: now_ms(),
+        content_hash: None,
+        flow_ref: None,
+        deleted: false,
+        operation: None,
+    };
+    append_event(&inner.path, &row)?;
+    inner.put_row(row);
+    Ok(())
+}
+
+/// Mint a revision for an authoritative write, under the caller's lock.
+///
+/// This is where the resource-scoped model meets the write path. The resource
+/// is the record's key, the parent is that resource's current head, and the
+/// sequence is allocated from the parent — so a resource that returns to a value
+/// it previously held records a *new* revision rather than resurrecting the old
+/// one.
+///
+/// Retention is applied here too, by the same decision function the explicit
+/// store API uses. Bounding history at the moment history is created is what
+/// keeps automatic minting from being an unbounded-history architecture.
+fn mint_revision_locked(inner: &mut Inner, resource: &str, content: String) -> Result<()> {
+    let parent = inner.revision_heads.get(resource).cloned();
+    let (parent_id, sequence) = match &parent {
+        Some((id, sequence)) => (Some(id.clone()), sequence + 1),
+        None => (None, 0),
+    };
+    let authority = inner.instance_id.clone();
+    let revision = state_model::StateRevision::at(
+        resource.to_string(),
+        content,
+        parent_id,
+        sequence,
+        authority,
+    );
+    let id = revision.id.clone();
+    let key = format!("state:revision:{}", id.as_hex());
+    let value = serde_json::to_value(&revision)?;
+    append_derived_row_locked(inner, "state", &key, value)?;
+    inner
+        .revision_heads
+        .insert(resource.to_string(), (id, sequence));
+    apply_retention_locked(inner, resource)
+}
+
+/// Expire whatever the resource's configured policy no longer retains.
+///
+/// The common path is one map lookup: with no policy configured there is
+/// nothing to scan. A resource's history is only walked once a policy exists to
+/// bound it.
+fn apply_retention_locked(inner: &mut Inner, resource: &str) -> Result<()> {
+    let retention_key = format!("_retention:{resource}");
+    let Some(state_row) = inner
+        .rows
+        .get("_retention")
+        .and_then(|bucket| bucket.get(&retention_key))
+    else {
+        return Ok(());
+    };
+    let Ok(mut state) = serde_json::from_value::<RetentionRecord>(state_row.value.clone()) else {
+        return Ok(());
+    };
+    if state.policy.keep_last.is_none() {
+        return Ok(());
+    }
+
+    let mut history: Vec<(state_model::StateId, u64)> = Vec::new();
+    if let Some(bucket) = inner.rows.get("state") {
+        for row in bucket.values() {
+            if row.deleted || !row.key.starts_with("state:revision:") {
+                continue;
+            }
+            if let Ok(revision) =
+                serde_json::from_value::<state_model::StateRevision>(row.value.clone())
+            {
+                if revision.resource == resource {
+                    history.push((revision.id, revision.sequence));
+                }
+            }
+        }
+    }
+    history.sort_by_key(|(_, sequence)| *sequence);
+
+    let (expire, horizon) = state_model::revisions_to_expire(&history, state.policy.keep_last);
+    if expire.is_empty() {
+        return Ok(());
+    }
+    for id in &expire {
+        let key = format!("state:revision:{}", id.as_hex());
+        if let Some(bucket) = inner.rows.get_mut("state") {
+            bucket.remove(&key);
+        }
+        let tombstone = StoredRow {
+            capability: "state".to_string(),
+            key,
+            rust_type: "feltdb::state_model::StateRevision".to_string(),
+            value: Value::Null,
+            unix_ms: now_ms(),
+            content_hash: None,
+            flow_ref: None,
+            deleted: true,
+            operation: None,
+        };
+        append_event(&inner.path, &tombstone)?;
+    }
+    if let Some(horizon) = horizon {
+        state.horizon = horizon;
+    }
+    let value = serde_json::to_value(&state)?;
+    append_derived_row_locked(inner, "_retention", &retention_key, value)
+}
+
+/// The durable shape of a resource's retention state.
+///
+/// Mirrors `state_model`'s private record so the write boundary can read and
+/// advance the horizon without the store type.
+#[derive(Clone, Debug, Default, Serialize, Deserialize)]
+struct RetentionRecord {
+    policy: state_model::RetentionPolicy,
+    horizon: u64,
+}
+
 impl FeltDb {
     pub fn open<P: AsRef<Path>>(path: P) -> Result<Self> {
         let path = path.as_ref().to_path_buf();
+
+        // Fail closed. The format is decided before any record is interpreted
+        // and before anything is written, so a database this build does not
+        // understand is refused with its bytes untouched rather than opened
+        // with whatever happened to deserialize.
+        if let FormatCompatibility::Incompatible(incompatibility) = inspect_durable_format(&path)? {
+            return Err(FlowError::IncompatibleFormat(Box::new(incompatibility)));
+        }
+
         if let Some(parent) = path.parent() {
             fs::create_dir_all(parent)?;
         }
         if !path.exists() {
-            OpenOptions::new().create(true).append(true).open(&path)?;
+            let mut file = OpenOptions::new().create(true).append(true).open(&path)?;
+            // A new database states its format in its first record, so it never
+            // has to be inferred again.
+            write_json_line(
+                &mut file,
+                &FormatRecord {
+                    record_type: FORMAT_RECORD_TYPE.to_string(),
+                    format_version: DURABLE_FORMAT_VERSION,
+                },
+            )?;
         }
 
         // Generate instance ID from path hash
@@ -804,6 +1151,7 @@ impl FeltDb {
         inner.sync_state = SyncState::new(instance_id);
         replay_log(&mut inner)?;
         load_sync_metadata(&mut inner)?;
+        rebuild_revision_heads(&mut inner);
 
         let (event_tx, _) = broadcast::channel(1024);
 
@@ -954,6 +1302,9 @@ impl FeltDb {
             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())?;
+            }
             let event = ChangeEvent {
                 capability,
                 key: key.to_string(),
@@ -1740,6 +2091,9 @@ impl FeltDb {
     ) -> Result<()> {
         let rust_type = type_name::<T>().to_string();
         let value_json = serde_json::to_value(value)?;
+        // Canonical because `serde_json` is built without `preserve_order`, so
+        // `Map` is a `BTreeMap` and `to_string` emits keys in sorted order.
+        let canonical = value_json.to_string();
         let mut row = StoredRow {
             capability: capability.clone(),
             key: key.clone(),
@@ -1783,6 +2137,9 @@ impl FeltDb {
             append_event(&inner.path, &row)?;
             inner.authority_revision += 1;
             inner.put_row(row);
+            if is_versioned(&capability) {
+                mint_revision_locked(&mut inner, &key, canonical)?;
+            }
             let suffix = key.rsplit_once(':').map(|(_, right)| right);
             if let Some(id) = suffix.and_then(|s| s.parse::<u64>().ok()) {
                 let entry = inner.key_counters.entry(capability.clone()).or_default();
@@ -1809,6 +2166,9 @@ impl FeltDb {
     ) -> Result<()> {
         let rust_type = type_name::<T>().to_string();
         let value_json = serde_json::to_value(value)?;
+        // Canonical because `serde_json` is built without `preserve_order`, so
+        // `Map` is a `BTreeMap` and `to_string` emits keys in sorted order.
+        let canonical = value_json.to_string();
         let mut row = StoredRow {
             capability: capability.clone(),
             key: key.clone(),
@@ -1852,6 +2212,9 @@ impl FeltDb {
             append_event(&inner.path, &row)?;
             inner.authority_revision += 1;
             inner.put_row(row);
+            if is_versioned(&capability) {
+                mint_revision_locked(&mut inner, &key, canonical)?;
+            }
         }
 
         let event = ChangeEvent {
@@ -2062,8 +2425,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 +2466,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 +2583,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 +2799,7 @@ impl FeltDb {
             rows,
             versions,
             content_hash,
+            format_version: DURABLE_FORMAT_VERSION,
         })
     }
     /// Current materialized rows including their causal operation envelopes.
@@ -2470,6 +2838,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 +2884,7 @@ impl FeltDb {
             &mut file,
             &LogHeader {
                 record_type: "feltdb.snapshot.v1".to_string(),
+                format_version: DURABLE_FORMAT_VERSION,
                 local_sequence: inner.sequence,
                 observed_versions: snapshot.versions.clone(),
             },
@@ -2585,6 +2972,7 @@ impl FeltDb {
             &mut file,
             &LogHeader {
                 record_type: "feltdb.snapshot.v1".to_string(),
+                format_version: DURABLE_FORMAT_VERSION,
                 local_sequence: inner.sequence,
                 observed_versions: inner.change_log.versions(),
             },
@@ -3113,6 +3501,115 @@ where
 ///
 /// Damage anywhere earlier is not an interrupted write. Recovery refuses it
 /// rather than silently dropping committed history.
+/// Examine a durable database's format **without opening or modifying it**.
+///
+/// This runs before any record is interpreted, and reads the file only. A
+/// database this reports as incompatible is left exactly as it was found.
+///
+/// The order matters: an explicit format record decides, and the records
+/// themselves are examined *only* when no format record exists — the
+/// unversioned era. Compatibility is never inferred from whether a
+/// deserialization happened to succeed.
+pub fn inspect_durable_format(path: &Path) -> Result<FormatCompatibility> {
+    if !path.exists() {
+        // A database that does not exist yet will be created in the current
+        // format.
+        return Ok(FormatCompatibility::Compatible(DurableFormat::Versioned(
+            DURABLE_FORMAT_VERSION,
+        )));
+    }
+
+    let lines = read_log_lines(path)?;
+    let mut declared: Option<u32> = None;
+    let mut legacy_revision = false;
+
+    for line in &lines {
+        if line.trim().is_empty() {
+            continue;
+        }
+        let Ok(value) = serde_json::from_str::<Value>(line) else {
+            continue;
+        };
+        match value.get("record_type").and_then(Value::as_str) {
+            Some(FORMAT_RECORD_TYPE) => {
+                if let Some(version) = value.get("format_version").and_then(Value::as_u64) {
+                    declared = Some(version as u32);
+                }
+            }
+            Some("feltdb.snapshot.v1" | "flowdb.snapshot.v1") => {
+                match value.get("format_version").and_then(Value::as_u64) {
+                    Some(version) if version > 0 => declared = Some(version as u32),
+                    _ => {}
+                }
+            }
+            _ => {
+                // The unversioned-era probe: a revision record that predates
+                // resource-scoped identity. Deliberate and specific — it looks
+                // for a named absence rather than trying to parse and shrugging
+                // at failure.
+                let is_revision = value
+                    .get("key")
+                    .and_then(Value::as_str)
+                    .is_some_and(|key| key.starts_with("state:revision:"));
+                if is_revision
+                    && value
+                        .get("value")
+                        .and_then(Value::as_object)
+                        .is_some_and(|revision| !revision.contains_key("resource"))
+                {
+                    legacy_revision = true;
+                }
+            }
+        }
+    }
+
+    if let Some(version) = declared {
+        return Ok(match version.cmp(&DURABLE_FORMAT_VERSION) {
+            std::cmp::Ordering::Equal => {
+                FormatCompatibility::Compatible(DurableFormat::Versioned(version))
+            }
+            std::cmp::Ordering::Greater => {
+                FormatCompatibility::Incompatible(FormatIncompatibility {
+                    found: DurableFormat::Versioned(version),
+                    required: DURABLE_FORMAT_VERSION,
+                    reason: "the database was written by a newer FeltDB".to_string(),
+                    action: "Run a FeltDB build that understands this format, or restore \
+                             a backup taken in an older format."
+                        .to_string(),
+                })
+            }
+            std::cmp::Ordering::Less => FormatCompatibility::Incompatible(FormatIncompatibility {
+                found: DurableFormat::Versioned(version),
+                required: DURABLE_FORMAT_VERSION,
+                reason: "the database was written in an older durable format".to_string(),
+                action: "Migrate the database with a FeltDB build that supports both \
+                             formats, or restore a backup."
+                    .to_string(),
+            }),
+        });
+    }
+
+    if legacy_revision {
+        return Ok(FormatCompatibility::Incompatible(FormatIncompatibility {
+            found: DurableFormat::Unversioned,
+            required: DURABLE_FORMAT_VERSION,
+            reason: "it holds revision records written before revisions belonged to a \
+                     resource, and those records cannot be migrated without inventing \
+                     information they never contained: a revision recorded no resource, \
+                     so which history each one belongs to is not recoverable from the data"
+                .to_string(),
+            action: "Export the application state you need from a FeltDB build that \
+                     understands the old format, then load it into a new database. The \
+                     existing file has not been modified."
+                .to_string(),
+        }));
+    }
+
+    // No format record and no legacy revision: nothing in this database depends
+    // on the difference.
+    Ok(FormatCompatibility::Compatible(DurableFormat::Unversioned))
+}
+
 fn read_log_lines(path: &Path) -> Result<Vec<String>> {
     let mut file = BufReader::new(OpenOptions::new().read(true).open(path)?);
     let mut lines: Vec<(String, bool)> = Vec::new();
@@ -3169,6 +3666,10 @@ fn replay_log(inner: &mut Inner) -> Result<()> {
             snapshot_log = true;
             continue;
         }
+        if value.get("record_type").and_then(Value::as_str) == Some(FORMAT_RECORD_TYPE) {
+            // Already honoured by `inspect_durable_format` before the open.
+            continue;
+        }
         if value.get("record_type").and_then(Value::as_str) == Some("feltdb.transaction.v1") {
             let transaction: TransactionLogRecord = serde_json::from_value(value)?;
             // Older records did not carry a commit revision. Their durable