@feltdb/core 0.15.0 → 0.16.1

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

@@ -1,4158 +0,0 @@
-//! Proven FeltDB State Model
-//!
-//! This module contains the graduated state model from feltdbgit (PRs #6-#14).
-//! It is now integrated with FeltDB's canonical persistence layer.
-//!
-//! - Deterministic content-addressed StateId
-//! - Immutable StateRevision with ancestry
-//! - Durable StateHistory via FeltDB's operation log
-//! - State Transitions with atomic commit
-//! - Branching and divergence tracking
-//! - Causal Topology (ancestors, is_ancestor, common_ancestor)
-//! - Deterministic Semantic Diff (with Key/Index distinction)
-//! - Conflict Classification (Independent/Convergent/Conflict)
-//! - Explicit Reconciliation with parent_choice
-
-use serde::{Deserialize, Serialize};
-use serde_json::Value;
-use sha2::{Digest, Sha256};
-use std::collections::{BTreeMap, BTreeSet, HashMap};
-use std::sync::{Arc, Mutex};
-
-// Forward declaration to avoid circular imports
-pub struct FeltDb; // Will be linked at compile time from lib.rs
-
-/// Version constant for state model contracts
-pub const STATE_MODEL_VERSION: u32 = 1;
-
-// ============================================================================
-// StateId: Deterministic Content-Addressed State Identifier
-// ============================================================================
-
-/// Deterministic content-addressed state identifier
-/// Same state content → same StateId (representation-sensitive)
-/// Different content → different StateId
-#[derive(Clone, Debug, PartialEq, Eq, Hash, PartialOrd, Ord, Serialize, Deserialize)]
-pub struct StateId(String);
-
-impl StateId {
-    /// Compute deterministic StateId from canonical state representation
-    /// Preserves representation sensitivity: "1" ≠ 1 ≠ 1.0
-    pub fn compute(canonical_json: &str) -> Self {
-        let mut hasher = Sha256::new();
-        hasher.update(canonical_json.as_bytes());
-        let result = hasher.finalize();
-        StateId(format!("{:x}", result))
-    }
-
-    /// Get hex representation
-    pub fn as_hex(&self) -> &str {
-        &self.0
-    }
-
-    /// Create from hex string (for recovery)
-    pub fn from_hex(hex: String) -> Self {
-        StateId(hex)
-    }
-}
-
-impl std::fmt::Display for StateId {
-    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
-        write!(f, "{}", self.0)
-    }
-}
-
-// ============================================================================
-// StateRevision: Immutable State Snapshot with Ancestry
-// ============================================================================
-
-/// An immutable, resource-scoped historical state.
-///
-/// A revision is a revision **of a resource**. Two resources holding identical
-/// content are distinct revisions, and a resource that returns to a value it
-/// previously held records a *new* revision rather than resurrecting the old
-/// one.
-///
-/// # Two identities, deliberately
-///
-/// `id` is the **revision identity**: what distinguishes one historical
-/// occurrence from another. It is computed over the resource, the content, the
-/// parent and a per-resource sequence, so content equality is not identity.
-///
-/// `content_id` is the **content identity**, the hash of the canonical content
-/// alone. It is what makes a revision verifiable against its own bytes, and it
-/// is what deduplicates *content* comparisons — two revisions of the same state
-/// share a `content_id` and differ in `id`.
-///
-/// Conflating these two was the defect the identity contract found: a revert
-/// produced a revision whose identity already existed, so committing it
-/// overwrote the earlier one and closed a cycle in the parent chain.
-#[derive(Clone, Debug, Serialize, Deserialize)]
-pub struct StateRevision {
-    /// Revision identity — resource, content, parent and sequence.
-    pub id: StateId,
-    /// The resource this is a revision of.
-    pub resource: String,
-    /// Canonical JSON representation (representation-sensitive)
-    pub content: String,
-    /// Content identity — the hash of `content` alone.
-    pub content_id: StateId,
-    /// Parent revision id. `None` only for a resource's first revision.
-    pub parent_id: Option<StateId>,
-    /// Position in this resource's history. Strictly increasing, never reused.
-    pub sequence: u64,
-    /// Authority that produced this revision
-    pub authority: String,
-    /// Timestamp when revision was created (informational only, not used for ordering)
-    pub timestamp_ms: u64,
-    /// Metadata (preservable with state)
-    pub metadata: BTreeMap<String, Value>,
-}
-
-/// A content object addressed by its content identity.
-#[derive(Clone, Debug, Serialize, Deserialize)]
-pub struct StateObject {
-    pub id: StateId,
-    pub content: String,
-    #[serde(default)]
-    pub metadata: BTreeMap<String, Value>,
-}
-
-impl StateObject {
-    pub fn new(content: String) -> Self {
-        let id = StateId::compute(&content);
-        Self {
-            id,
-            content,
-            metadata: BTreeMap::new(),
-        }
-    }
-
-    pub fn verify_integrity(&self) -> bool {
-        self.id == StateId::compute(&self.content)
-    }
-}
-
-/// A mutable named reference to an immutable revision.
-#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
-pub struct StateRef {
-    pub namespace: String,
-    pub name: String,
-    pub target: StateId,
-    pub version: u64,
-    pub authority: String,
-    pub updated_at_ms: u64,
-    #[serde(default)]
-    pub metadata: BTreeMap<String, Value>,
-}
-
-#[derive(Clone, Debug, PartialEq, Eq)]
-pub enum RefError {
-    InvalidIdentifier,
-    NotFound,
-    AlreadyExists,
-    UnknownTarget(StateId),
-    VersionConflict { expected: u64, current: u64 },
-    Storage(String),
-}
-
-impl std::fmt::Display for RefError {
-    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
-        match self {
-            RefError::InvalidIdentifier => write!(f, "invalid ref identifier"),
-            RefError::NotFound => write!(f, "ref not found"),
-            RefError::AlreadyExists => write!(f, "ref already exists"),
-            RefError::UnknownTarget(id) => write!(f, "ref target {id} does not exist"),
-            RefError::VersionConflict { expected, current } => {
-                write!(f, "stale ref version: expected {expected}, current {current}")
-            }
-            RefError::Storage(message) => write!(f, "{message}"),
-        }
-    }
-}
-
-impl std::error::Error for RefError {}
-
-#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
-pub struct MaterializationProjection {
-    #[serde(default)]
-    pub paths: Vec<Vec<PathComponent>>,
-}
-
-impl MaterializationProjection {
-    pub fn full() -> Self {
-        Self { paths: Vec::new() }
-    }
-
-    pub fn select(paths: Vec<Vec<PathComponent>>) -> Self {
-        Self { paths }
-    }
-
-    pub fn is_full(&self) -> bool {
-        self.paths.is_empty() || self.paths.iter().any(|path| path.is_empty())
-    }
-}
-
-#[derive(Clone, Debug, PartialEq, Eq)]
-pub enum MaterializationError {
-    RevisionNotFound(StateId),
-    ContentUnparseable(String),
-    MissingPath(Vec<PathComponent>),
-    NonDeterministicProjection,
-}
-
-impl std::fmt::Display for MaterializationError {
-    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
-        match self {
-            MaterializationError::RevisionNotFound(id) => write!(f, "revision {id} not found"),
-            MaterializationError::ContentUnparseable(error) => {
-                write!(f, "revision content is not parseable JSON: {error}")
-            }
-            MaterializationError::MissingPath(path) => {
-                write!(f, "projection path does not resolve: {path:?}")
-            }
-            MaterializationError::NonDeterministicProjection => write!(
-                f,
-                "projection contains overlapping paths and does not deterministically resolve"
-            ),
-        }
-    }
-}
-
-impl std::error::Error for MaterializationError {}
-
-#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
-pub struct GarbageCollectionReport {
-    pub roots: Vec<StateRef>,
-    pub reachable_revisions: Vec<StateId>,
-    pub reachable_objects: Vec<StateId>,
-    pub collected_revisions: Vec<StateId>,
-    pub collected_objects: Vec<StateId>,
-}
-
-#[derive(Clone, Debug, PartialEq, Eq)]
-pub enum GarbageCollectionError {
-    Storage(String),
-}
-
-impl std::fmt::Display for GarbageCollectionError {
-    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
-        match self {
-            GarbageCollectionError::Storage(message) => write!(f, "{message}"),
-        }
-    }
-}
-
-impl std::error::Error for GarbageCollectionError {}
-
-/// Compute a revision identity.
-///
-/// Every component participates: the same content is a different revision on a
-/// different resource, from a different parent, or at a different point in the
-/// resource's history. The parts are length-prefixed so no two distinct tuples
-/// can produce the same input string.
-fn compute_revision_id(
-    resource: &str,
-    content_id: &StateId,
-    parent_id: Option<&StateId>,
-    sequence: u64,
-) -> StateId {
-    let parent = parent_id.map(StateId::as_hex).unwrap_or("");
-    let material = format!(
-        "feltdb.revision.v2\n{}:{}\n{}:{}\n{}:{}\n{}",
-        resource.len(),
-        resource,
-        content_id.as_hex().len(),
-        content_id.as_hex(),
-        parent.len(),
-        parent,
-        sequence,
-    );
-    StateId::compute(&material)
-}
-
-impl StateRevision {
-    /// Create a resource's first revision.
-    pub fn initial(resource: String, content: String, authority: String) -> Self {
-        Self::at(resource, content, None, 0, authority)
-    }
-
-    /// Create a revision descending from `parent`, on the parent's resource.
-    pub fn child(content: String, parent: &StateRevision, authority: String) -> Self {
-        Self::at(
-            parent.resource.clone(),
-            content,
-            Some(parent.id.clone()),
-            parent.sequence + 1,
-            authority,
-        )
-    }
-
-    /// Create a revision at an explicit position in a resource's history.
-    pub fn at(
-        resource: String,
-        content: String,
-        parent_id: Option<StateId>,
-        sequence: u64,
-        authority: String,
-    ) -> Self {
-        let content_id = StateId::compute(&content);
-        let id = compute_revision_id(&resource, &content_id, parent_id.as_ref(), sequence);
-        let timestamp_ms = std::time::SystemTime::now()
-            .duration_since(std::time::UNIX_EPOCH)
-            .unwrap_or_default()
-            .as_millis() as u64;
-
-        StateRevision {
-            id,
-            resource,
-            content,
-            content_id,
-            parent_id,
-            sequence,
-            authority,
-            timestamp_ms,
-            metadata: BTreeMap::new(),
-        }
-    }
-
-    /// Verify that both identities match what they are computed from.
-    pub fn verify_integrity(&self) -> bool {
-        self.content_id == StateId::compute(&self.content)
-            && self.id
-                == compute_revision_id(
-                    &self.resource,
-                    &self.content_id,
-                    self.parent_id.as_ref(),
-                    self.sequence,
-                )
-    }
-
-    /// Get parent id if this is not a resource's first revision.
-    pub fn parent(&self) -> Option<&StateId> {
-        self.parent_id.as_ref()
-    }
-
-    /// Whether two revisions are the same revision.
-    ///
-    /// Revision identity, not content equality: two revisions of the same state
-    /// on the same resource are not equal.
-    pub fn equals(&self, other: &StateRevision) -> bool {
-        self.id == other.id
-    }
-
-    /// Whether two revisions hold the same state, regardless of where in
-    /// history they occur.
-    pub fn same_content_as(&self, other: &StateRevision) -> bool {
-        self.content_id == other.content_id
-    }
-}
-
-// ============================================================================
-// Topology: Ancestors, Relationships, and History Navigation
-// ============================================================================
-
-/// Relationship between two revisions
-#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
-pub enum Relationship {
-    /// A is an ancestor of B
-    Ancestor,
-    /// B is an ancestor of A
-    Descendant,
-    /// A and B are the same
-    Identity,
-    /// A and B diverged from a common ancestor but neither is ancestor of other
-    Diverged,
-    /// A and B have no common ancestry
-    Unrelated,
-}
-
-/// Topology tracker for state revisions
-pub struct StateTopology {
-    revisions: HashMap<StateId, StateRevision>,
-    parents: HashMap<StateId, StateId>,
-}
-
-impl StateTopology {
-    pub fn new() -> Self {
-        StateTopology {
-            revisions: HashMap::new(),
-            parents: HashMap::new(),
-        }
-    }
-
-    /// Add revision to topology
-    pub fn add_revision(&mut self, revision: StateRevision) {
-        if let Some(parent_id) = revision.parent_id.clone() {
-            self.parents.insert(revision.id.clone(), parent_id);
-        }
-        self.revisions.insert(revision.id.clone(), revision);
-    }
-
-    /// Get revision by id
-    pub fn get(&self, id: &StateId) -> Option<&StateRevision> {
-        self.revisions.get(id)
-    }
-
-    /// Check if A is ancestor of B
-    pub fn is_ancestor(&self, a: &StateId, b: &StateId) -> bool {
-        if a == b {
-            return true;
-        }
-        // The revision model makes this graph acyclic, so the visited set is a
-        // safety belt rather than the thing that makes the walk correct: a
-        // topology assembled by hand, or read from an older log, must not be
-        // able to hang a caller.
-        let mut visited = BTreeSet::new();
-        let mut current = b.clone();
-        while let Some(parent_id) = self.parents.get(&current) {
-            if parent_id == a {
-                return true;
-            }
-            if !visited.insert(current.clone()) {
-                return false;
-            }
-            current = parent_id.clone();
-        }
-        false
-    }
-
-    /// Get all ancestors of a revision (excluding self)
-    pub fn ancestors(&self, id: &StateId) -> Vec<StateId> {
-        let mut ancestors = Vec::new();
-        let mut visited = BTreeSet::new();
-        let mut current = id.clone();
-
-        while let Some(parent_id) = self.parents.get(&current) {
-            if !visited.insert(current.clone()) {
-                break;
-            }
-            ancestors.push(parent_id.clone());
-            current = parent_id.clone();
-        }
-
-        ancestors
-    }
-
-    /// Find common ancestor of two revisions
-    pub fn common_ancestor(&self, a: &StateId, b: &StateId) -> Option<StateId> {
-        if a == b {
-            return Some(a.clone());
-        }
-
-        let ancestors_a: BTreeSet<_> = self.ancestors(a).iter().cloned().collect();
-
-        let mut visited = BTreeSet::new();
-        let mut current = b.clone();
-        while let Some(parent_id) = self.parents.get(&current) {
-            if ancestors_a.contains(parent_id) {
-                return Some(parent_id.clone());
-            }
-            if !visited.insert(current.clone()) {
-                break;
-            }
-            current = parent_id.clone();
-        }
-
-        None
-    }
-
-    /// Determine relationship between two revisions
-    pub fn relationship(&self, a: &StateId, b: &StateId) -> Relationship {
-        if a == b {
-            return Relationship::Identity;
-        }
-        if self.is_ancestor(a, b) {
-            return Relationship::Ancestor;
-        }
-        if self.is_ancestor(b, a) {
-            return Relationship::Descendant;
-        }
-        if self.common_ancestor(a, b).is_some() {
-            return Relationship::Diverged;
-        }
-        Relationship::Unrelated
-    }
-}
-
-// ============================================================================
-// Semantic Diff: Deterministic, Representation-Sensitive Differences
-// ============================================================================
-
-/// Change type at a specific location
-#[derive(Clone, Debug, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)]
-pub enum ChangeKind {
-    /// Value was added
-    Added,
-    /// Value was removed
-    Removed,
-    /// Value was changed
-    Changed,
-}
-
-/// Distinguishes between object keys and array indices
-#[derive(Clone, Debug, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)]
-pub enum PathComponent {
-    /// Object key
-    Key(String),
-    /// Array index
-    Index(usize),
-}
-
-/// How two changed paths relate to one another.
-///
-/// Conflict classification needs this because two changes interact whenever one
-/// path contains the other, not only when the paths are equal. Comparison is
-/// structural, over whole [`PathComponent`]s: `["a", "b"]` and `["a", "bc"]` are
-/// [`PathRelation::Disjoint`], even though one rendering of them shares a string
-/// prefix, and `["a"]` with `Key("a")` never matches `Index(0)`.
-#[derive(Clone, Copy, Debug, PartialEq, Eq)]
-pub enum PathRelation {
-    /// The same path.
-    Same,
-    /// The first path contains the second: `a` against `a.b`.
-    Ancestor,
-    /// The first path is contained by the second: `a.b` against `a`.
-    Descendant,
-    /// Neither contains the other: siblings, or unrelated subtrees.
-    Disjoint,
-}
-
-/// Whether `candidate` begins with every component of `prefix`, structurally.
-fn path_starts_with(candidate: &[PathComponent], prefix: &[PathComponent]) -> bool {
-    candidate.len() >= prefix.len() && candidate[..prefix.len()] == *prefix
-}
-
-/// Classifies how two changed paths relate.
-///
-/// Pure, total, and independent of any state: it reads only the two paths.
-pub fn path_relation(one: &[PathComponent], two: &[PathComponent]) -> PathRelation {
-    if one == two {
-        PathRelation::Same
-    } else if path_starts_with(two, one) {
-        PathRelation::Ancestor
-    } else if path_starts_with(one, two) {
-        PathRelation::Descendant
-    } else {
-        PathRelation::Disjoint
-    }
-}
-
-/// Whether two changed paths interact: equal, or one containing the other.
-///
-/// This is the predicate conflict classification is defined over. Two changes
-/// at overlapping paths cannot both be applied — the outer one determines the
-/// value the inner one was editing — so they are never independent.
-pub fn paths_overlap(one: &[PathComponent], two: &[PathComponent]) -> bool {
-    !matches!(path_relation(one, two), PathRelation::Disjoint)
-}
-
-/// Reads the value a path names, or `None` when the path does not resolve.
-///
-/// Object members are addressed by [`PathComponent::Key`] and array elements by
-/// [`PathComponent::Index`], exactly as [`SemanticDiff`] emits them, so a path
-/// taken from a diff resolves in the state that diff was computed from.
-pub fn resolve_path<'a>(value: &'a Value, path: &[PathComponent]) -> Option<&'a Value> {
-    let mut current = value;
-    for component in path {
-        current = match component {
-            PathComponent::Key(key) => current.as_object()?.get(key)?,
-            PathComponent::Index(index) => current.as_array()?.get(*index)?,
-        };
-    }
-    Some(current)
-}
-
-/// Semantic change at a specific path (deterministically ordered)
-#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
-pub struct SemanticChange {
-    /// Path to changed value: Vec<PathComponent> for deterministic ordering
-    pub path: Vec<PathComponent>,
-    /// Kind of change
-    pub kind: ChangeKind,
-    /// Old value (None if Added)
-    pub old_value: Option<Value>,
-    /// New value (None if Removed)
-    pub new_value: Option<Value>,
-}
-
-/// Semantic diff result (deterministically ordered)
-#[derive(Clone, Debug, Serialize, Deserialize)]
-pub struct SemanticDiff {
-    /// Changes in deterministic order
-    pub changes: Vec<SemanticChange>,
-    /// Read-only indicator
-    pub is_read_only: bool,
-}
-
-impl SemanticDiff {
-    /// Compute diff from two JSON objects
-    /// Deterministically ordered, direction-sensitive
-    pub fn compute(old: &Value, new: &Value) -> Self {
-        let mut changes = Vec::new();
-        Self::diff_recursive(old, new, &mut vec![], &mut changes);
-
-        // Sort deterministically
-        changes.sort_by(|a, b| a.path.cmp(&b.path).then_with(|| a.kind.cmp(&b.kind)));
-
-        SemanticDiff {
-            changes,
-            is_read_only: false,
-        }
-    }
-
-    fn diff_recursive(
-        old: &Value,
-        new: &Value,
-        path: &mut Vec<PathComponent>,
-        changes: &mut Vec<SemanticChange>,
-    ) {
-        use serde_json::{json, Value::*};
-
-        match (old, new) {
-            (Null, Null) => {}
-            (Bool(a), Bool(b)) if a == b => {}
-            (Number(a), Number(b)) if a == b => {}
-            (String(a), String(b)) if a == b => {}
-            (Array(a), Array(b)) => {
-                for (i, (old_v, new_v)) in a.iter().zip(b.iter()).enumerate() {
-                    path.push(PathComponent::Index(i));
-                    Self::diff_recursive(old_v, new_v, path, changes);
-                    path.pop();
-                }
-                // Additions
-                for (i, new_v) in b.iter().enumerate().skip(a.len()) {
-                    path.push(PathComponent::Index(i));
-                    changes.push(SemanticChange {
-                        path: path.clone(),
-                        kind: ChangeKind::Added,
-                        old_value: None,
-                        new_value: Some(new_v.clone()),
-                    });
-                    path.pop();
-                }
-                // Removals
-                for (i, old_v) in a.iter().enumerate().skip(b.len()) {
-                    path.push(PathComponent::Index(i));
-                    changes.push(SemanticChange {
-                        path: path.clone(),
-                        kind: ChangeKind::Removed,
-                        old_value: Some(old_v.clone()),
-                        new_value: None,
-                    });
-                    path.pop();
-                }
-            }
-            (Object(a), Object(b)) => {
-                for key in a.keys() {
-                    if let Some(new_v) = b.get(key) {
-                        path.push(PathComponent::Key(key.clone()));
-                        Self::diff_recursive(&a[key], new_v, path, changes);
-                        path.pop();
-                    } else {
-                        path.push(PathComponent::Key(key.clone()));
-                        changes.push(SemanticChange {
-                            path: path.clone(),
-                            kind: ChangeKind::Removed,
-                            old_value: Some(a[key].clone()),
-                            new_value: None,
-                        });
-                        path.pop();
-                    }
-                }
-                for key in b.keys() {
-                    if !a.contains_key(key) {
-                        path.push(PathComponent::Key(key.clone()));
-                        changes.push(SemanticChange {
-                            path: path.clone(),
-                            kind: ChangeKind::Added,
-                            old_value: None,
-                            new_value: Some(b[key].clone()),
-                        });
-                        path.pop();
-                    }
-                }
-            }
-            (_, _) => {
-                changes.push(SemanticChange {
-                    path: path.clone(),
-                    kind: ChangeKind::Changed,
-                    old_value: Some(old.clone()),
-                    new_value: Some(new.clone()),
-                });
-            }
-        }
-    }
-
-    /// Mark as read-only
-    pub fn read_only(mut self) -> Self {
-        self.is_read_only = true;
-        self
-    }
-}
-
-// ============================================================================
-// Conflict Classification: Three-Way Merge Analysis
-// ============================================================================
-
-/// Classification of conflict between two changes
-///
-/// `Independent` carries the strong meaning its name and the state-model
-/// graduation audit both assert: the two branches' changes at this path do not
-/// overlap, so both can be applied without either overwriting or invalidating
-/// the other. It is not merely "the paths differ" — see [`paths_overlap`].
-#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
-pub enum ConflictClass {
-    /// Changes don't overlap; can merge automatically
-    Independent,
-    /// Changes converge on same result
-    Convergent,
-    /// Changes conflict; requires explicit reconciliation
-    Conflict,
-}
-
-/// Per-path conflict classification
-#[derive(Clone, Debug, Serialize, Deserialize)]
-pub struct PathConflict {
-    pub path: Vec<PathComponent>,
-    pub classification: ConflictClass,
-    /// The common ancestor's value at this path, or `None` when the path does
-    /// not resolve in the base.
-    ///
-    /// Read from the base state itself. It was previously read from the left
-    /// branch's change, which reported `None` for a path only the right branch
-    /// touched even when the base held a value there.
-    pub base_value: Option<Value>,
-    /// The left branch's value at this path, or `None` if the left branch did
-    /// not change it or removed it.
-    pub left_value: Option<Value>,
-    /// The right branch's value at this path, or `None` if the right branch did
-    /// not change it or removed it.
-    pub right_value: Option<Value>,
-}
-
-/// Conflict classification result
-#[derive(Clone, Debug, Serialize, Deserialize)]
-pub struct ConflictClassification {
-    /// Conflicts at each path (deterministically ordered)
-    pub path_conflicts: Vec<PathConflict>,
-    /// Overall classification
-    pub overall: ConflictClass,
-}
-
-impl ConflictClassification {
-    /// Classify conflicts from three-way merge
-    ///
-    /// `base` is the common ancestor, `left` the first branch, `right` the
-    /// second. Only each revision's `content` is read.
-    ///
-    /// Two changes interact whenever their paths **overlap** — equal, or one
-    /// containing the other — not only when they are equal. A branch that
-    /// replaces `o` and a branch that edits `o.a` cannot both be applied: the
-    /// first determines the value the second was editing. Both such paths are
-    /// reported as [`ConflictClass::Conflict`].
-    ///
-    /// An overlap that is not at the same path can never be convergent. For a
-    /// descendant path to exist, the base must hold a container there; a change
-    /// reported *at* the ancestor path means that branch no longer holds a
-    /// container of that kind, while the branch editing inside it still does.
-    /// The two values therefore always differ. `classify` does not rely on that
-    /// argument — it compares the two branches' resulting values — but the
-    /// conformance suite asserts it, so the reasoning stays checked.
-    pub fn classify(base: &StateRevision, left: &StateRevision, right: &StateRevision) -> Self {
-        use serde_json::Value;
-
-        let base_json: Value = serde_json::from_str(&base.content).unwrap_or(Value::Null);
-        let left_json: Value = serde_json::from_str(&left.content).unwrap_or(Value::Null);
-        let right_json: Value = serde_json::from_str(&right.content).unwrap_or(Value::Null);
-
-        let left_diff = SemanticDiff::compute(&base_json, &left_json);
-        let right_diff = SemanticDiff::compute(&base_json, &right_json);
-
-        let mut path_conflicts = Vec::new();
-        let mut has_conflict = false;
-
-        let left_paths: BTreeMap<Vec<PathComponent>, &SemanticChange> = left_diff
-            .changes
-            .iter()
-            .map(|c| (c.path.clone(), c))
-            .collect();
-        let right_paths: BTreeMap<Vec<PathComponent>, &SemanticChange> = right_diff
-            .changes
-            .iter()
-            .map(|c| (c.path.clone(), c))
-            .collect();
-
-        // Find all unique paths
-        let all_paths: BTreeSet<_> = left_paths
-            .keys()
-            .chain(right_paths.keys())
-            .cloned()
-            .collect();
-
-        for path in all_paths {
-            let left_change = left_paths.get(&path);
-            let right_change = right_paths.get(&path);
-
-            let classification = match (left_change, right_change) {
-                (Some(lc), Some(rc)) => {
-                    if lc.kind == rc.kind && lc.new_value == rc.new_value {
-                        ConflictClass::Convergent
-                    } else {
-                        has_conflict = true;
-                        ConflictClass::Conflict
-                    }
-                }
-                // Only one branch changed this path. It is independent only if
-                // the other branch changed nothing that contains it or that it
-                // contains.
-                (Some(_), None) => {
-                    if overlapping_change_exists(&right_paths, &path) {
-                        has_conflict = true;
-                        ConflictClass::Conflict
-                    } else {
-                        ConflictClass::Independent
-                    }
-                }
-                (None, Some(_)) => {
-                    if overlapping_change_exists(&left_paths, &path) {
-                        has_conflict = true;
-                        ConflictClass::Conflict
-                    } else {
-                        ConflictClass::Independent
-                    }
-                }
-                // Unreachable: every path came from one of the two maps.
-                (None, None) => ConflictClass::Independent,
-            };
-
-            path_conflicts.push(PathConflict {
-                path: path.clone(),
-                classification,
-                base_value: resolve_path(&base_json, &path).cloned(),
-                left_value: left_change.and_then(|c| c.new_value.clone()),
-                right_value: right_change.and_then(|c| c.new_value.clone()),
-            });
-        }
-
-        // Sort deterministically
-        path_conflicts.sort_by(|a, b| a.path.cmp(&b.path));
-
-        let overall = if has_conflict {
-            ConflictClass::Conflict
-        } else if path_conflicts
-            .iter()
-            .any(|c| c.classification == ConflictClass::Convergent)
-        {
-            ConflictClass::Convergent
-        } else {
-            ConflictClass::Independent
-        };
-
-        ConflictClassification {
-            path_conflicts,
-            overall,
-        }
-    }
-}
-
-/// Whether `changes` holds any change at a path overlapping `path`, other than
-/// at `path` itself.
-///
-/// Ancestors are the proper prefixes of `path`, so there are at most as many as
-/// the path is deep. Descendants are contiguous in sorted order — every
-/// sequence beginning with `path` sorts together, directly after `path` — so the
-/// first key strictly greater than `path` decides whether any exists.
-fn overlapping_change_exists(
-    changes: &BTreeMap<Vec<PathComponent>, &SemanticChange>,
-    path: &[PathComponent],
-) -> bool {
-    for depth in 0..path.len() {
-        if changes.contains_key(&path[..depth].to_vec()) {
-            return true;
-        }
-    }
-    changes
-        .range(path.to_vec()..)
-        .find(|(candidate, _)| candidate.as_slice() != path)
-        .is_some_and(|(candidate, _)| path_starts_with(candidate, path))
-}
-
-// ============================================================================
-// Reconciliation: Explicit Parent Choice Mechanism
-// ============================================================================
-
-/// Reconciliation plan specifying how to merge two branches
-#[derive(Clone, Debug, Serialize, Deserialize)]
-pub struct ReconciliationPlan {
-    /// Left (first) branch revision
-    pub left_id: StateId,
-    /// Right (second) branch revision
-    pub right_id: StateId,
-    /// Common ancestor revision
-    pub base_id: StateId,
-    /// Which branch to use as primary: true for left, false for right
-    pub parent_choice: bool,
-    /// Override values for specific paths (caller-supplied)
-    pub path_overrides: BTreeMap<Vec<PathComponent>, Value>,
-}
-
-impl ReconciliationPlan {
-    /// Create reconciliation plan with explicit parent choice
-    pub fn new(left_id: StateId, right_id: StateId, base_id: StateId, parent_choice: bool) -> Self {
-        ReconciliationPlan {
-            left_id,
-            right_id,
-            base_id,
-            parent_choice,
-            path_overrides: BTreeMap::new(),
-        }
-    }
-
-    /// Add override for a specific path
-    pub fn with_override(mut self, path: Vec<PathComponent>, value: Value) -> Self {
-        self.path_overrides.insert(path, value);
-        self
-    }
-
-    /// Validate that plan references valid states
-    pub fn validate(&self) -> bool {
-        // Base validation: ids are non-empty
-        !self.left_id.as_hex().is_empty()
-            && !self.right_id.as_hex().is_empty()
-            && !self.base_id.as_hex().is_empty()
-    }
-}
-
-/// Reconciliation result (immutable once created)
-#[derive(Clone, Debug, Serialize, Deserialize)]
-pub struct StateReconciliationResult {
-    /// The materialized reconciled state
-    pub materialized_state: StateRevision,
-    /// Which plan was applied
-    pub plan: ReconciliationPlan,
-}
-
-// ----------------------------------------------------------------------------
-// Applying a reconciliation plan
-// ----------------------------------------------------------------------------
-//
-// The plan says what the caller decided. Application produces the state that
-// decision names, and nothing else:
-//
-//     Classification  — which changes can coexist?
-//     Plan            — what happens to the ones that cannot?
-//     Application     — produce the resulting state from that decision.
-//
-// Nothing here merges. Nothing here resolves a conflict on the caller's behalf.
-// A path the plan does not mention keeps whatever the *selected parent* holds,
-// which is the caller's decision too — it is what `parent_choice` selects.
-
-/// The plan does not reference three usable revisions.
-pub const RECONCILE_PLAN_INVALID: &str = "RECONCILE_PLAN_INVALID";
-/// A supplied revision is not the one the plan names.
-pub const RECONCILE_REVISION_MISMATCH: &str = "RECONCILE_REVISION_MISMATCH";
-/// The selected parent's content is not JSON, so there is no state to start from.
-pub const RECONCILE_CONTENT_UNPARSEABLE: &str = "RECONCILE_CONTENT_UNPARSEABLE";
-/// Two override paths overlap, so the plan does not say what the result is.
-pub const RECONCILE_OVERRIDE_PATHS_OVERLAP: &str = "RECONCILE_OVERRIDE_PATHS_OVERLAP";
-/// An override path does not name an assignable location in the selected parent.
-pub const RECONCILE_OVERRIDE_UNADDRESSABLE: &str = "RECONCILE_OVERRIDE_UNADDRESSABLE";
-
-impl ReconciliationPlan {
-    /// The branch this plan selects as the state to start from.
-    ///
-    /// `parent_choice` is a `bool` and so has exactly two values: `true` is the
-    /// left branch, `false` the right. The ancestor is not a choice, and there
-    /// is no third value for this to reject.
-    pub fn selected_parent<'a>(
-        &self,
-        left: &'a StateRevision,
-        right: &'a StateRevision,
-    ) -> &'a StateRevision {
-        if self.parent_choice {
-            left
-        } else {
-            right
-        }
-    }
-
-    /// The conflicting paths this plan supplies no override for.
-    ///
-    /// Descriptive, not enforced. Application does **not** require an override
-    /// for every conflict: leaving one unaddressed resolves it to whatever the
-    /// selected parent holds, and selecting that parent is itself an explicit
-    /// caller decision. A caller that wants every conflict addressed
-    /// individually can require this to be empty before applying.
-    pub fn unresolved_conflicts(
-        &self,
-        classification: &ConflictClassification,
-    ) -> Vec<Vec<PathComponent>> {
-        classification
-            .path_conflicts
-            .iter()
-            .filter(|entry| entry.classification == ConflictClass::Conflict)
-            .map(|entry| entry.path.clone())
-            .filter(|path| !self.path_overrides.contains_key(path))
-            .collect()
-    }
-}
-
-/// Applies a reconciliation plan, producing canonical reconciled content.
-///
-/// Pure and total with respect to its inputs: it reads the three revisions and
-/// the plan, mutates none of them, consults no clock, filesystem, network or
-/// global state, and returns either canonical JSON or a stable error code.
-///
-/// # What it does
-///
-/// 1. Checks the plan validates and names the three revisions supplied.
-/// 2. Takes the state of the branch `parent_choice` selects.
-/// 3. Assigns each override into it.
-/// 4. Serializes the result canonically.
-///
-/// # What it does not do
-///
-/// It does not merge, and it does not consult the other branch or the ancestor
-/// for anything but identity. A conflicting path with no override keeps the
-/// selected parent's value.
-///
-/// # Overrides
-///
-/// `path_overrides` is a map keyed by structural path, so a repeated path
-/// cannot exist — the type forecloses it. What the type does not foreclose is
-/// two paths where one *contains* the other, and such a plan does not say what
-/// the result should be: does the inner override refine the outer value, or was
-/// the outer one meant to stand? Rather than invent a precedence the plan never
-/// stated, overlapping override paths are rejected. Overlap is the same
-/// structural relation conflict classification uses, so `a.b` and `a.bc` are
-/// not an overlap.
-///
-/// Because overlaps are rejected, the order overrides are applied in cannot
-/// affect the result.
-///
-/// An override path must be *addressable* in the selected state: every proper
-/// prefix must already resolve to a container of the matching kind. Assigning a
-/// member to an existing object is allowed whether or not the member is already
-/// there, because it creates no structure. Assigning past the end of an array is
-/// not, because it would require inventing the elements in between. To change an
-/// array's length, or to remove a member, override the container itself — a
-/// `Value` cannot express absence, so removal has no other encoding in this
-/// plan.
-pub fn apply_reconciliation_plan(
-    base: &StateRevision,
-    left: &StateRevision,
-    right: &StateRevision,
-    plan: &ReconciliationPlan,
-) -> Result<String, String> {
-    if !plan.validate() {
-        return Err(format!(
-            "{RECONCILE_PLAN_INVALID}: the plan does not reference three revisions"
-        ));
-    }
-    for (label, expected, supplied) in [
-        ("base", &plan.base_id, &base.id),
-        ("left", &plan.left_id, &left.id),
-        ("right", &plan.right_id, &right.id),
-    ] {
-        if expected != supplied {
-            return Err(format!(
-                "{RECONCILE_REVISION_MISMATCH}: the plan names a different {label} revision"
-            ));
-        }
-    }
-
-    let parent = plan.selected_parent(left, right);
-    let mut state: Value = serde_json::from_str(&parent.content).map_err(|error| {
-        // Classification tolerates unparseable content by reading it as JSON
-        // null, because it only describes. Materializing a state from content
-        // nobody can parse would be producing arbitrary state, so this refuses.
-        format!(
-            "{RECONCILE_CONTENT_UNPARSEABLE}: the selected parent's content is not JSON: {error}"
-        )
-    })?;
-
-    // `BTreeMap` sorts its keys, and every sequence with a given prefix sorts
-    // contiguously after it, so any containment relation shows up between two
-    // consecutive keys.
-    let paths: Vec<&Vec<PathComponent>> = plan.path_overrides.keys().collect();
-    for pair in paths.windows(2) {
-        if paths_overlap(pair[0], pair[1]) {
-            return Err(format!(
-                "{RECONCILE_OVERRIDE_PATHS_OVERLAP}: {:?} and {:?} overlap, so the plan does \
-                 not say what the result is",
-                pair[0], pair[1]
-            ));
-        }
-    }
-
-    for (path, value) in &plan.path_overrides {
-        assign_path(&mut state, path, value.clone())?;
-    }
-
-    serde_json::to_string(&state)
-        .map_err(|error| format!("{RECONCILE_CONTENT_UNPARSEABLE}: {error}"))
-}
-
-/// Assigns `value` at `path`, or reports why the path is not assignable.
-fn assign_path(state: &mut Value, path: &[PathComponent], value: Value) -> Result<(), String> {
-    let Some((last, prefix)) = path.split_last() else {
-        // The empty path is the state itself.
-        *state = value;
-        return Ok(());
-    };
-
-    let mut current = state;
-    for (depth, component) in prefix.iter().enumerate() {
-        current = match component {
-            PathComponent::Key(key) => current.as_object_mut().and_then(|o| o.get_mut(key)),
-            PathComponent::Index(index) => current.as_array_mut().and_then(|a| a.get_mut(*index)),
-        }
-        .ok_or_else(|| {
-            format!(
-                "{RECONCILE_OVERRIDE_UNADDRESSABLE}: {path:?} does not resolve at \
-                 component {depth} ({component:?})"
-            )
-        })?;
-    }
-
-    match last {
-        // A new member of an existing object creates no structure.
-        PathComponent::Key(key) => match current.as_object_mut() {
-            Some(members) => {
-                members.insert(key.clone(), value);
-                Ok(())
-            }
-            None => Err(format!(
-                "{RECONCILE_OVERRIDE_UNADDRESSABLE}: {path:?} names a member of \
-                 something that is not an object"
-            )),
-        },
-        // An index past the end would require inventing the elements before it.
-        PathComponent::Index(index) => match current.as_array_mut() {
-            Some(items) if *index < items.len() => {
-                items[*index] = value;
-                Ok(())
-            }
-            Some(items) => Err(format!(
-                "{RECONCILE_OVERRIDE_UNADDRESSABLE}: {path:?} is past the end of an \
-                 array of length {}",
-                items.len()
-            )),
-            None => Err(format!(
-                "{RECONCILE_OVERRIDE_UNADDRESSABLE}: {path:?} indexes something that \
-                 is not an array"
-            )),
-        },
-    }
-}
-
-fn assign_projection(
-    state: &mut Value,
-    path: &[PathComponent],
-    value: Value,
-) -> Result<(), MaterializationError> {
-    let Some((last, prefix)) = path.split_last() else {
-        *state = value;
-        return Ok(());
-    };
-
-    let mut current = state;
-    for component in prefix {
-        match component {
-            PathComponent::Key(key) => {
-                if current.is_null() {
-                    *current = Value::Object(serde_json::Map::new());
-                }
-                let Some(object) = current.as_object_mut() else {
-                    return Err(MaterializationError::MissingPath(path.to_vec()));
-                };
-                current = object.entry(key.clone()).or_insert(Value::Null);
-            }
-            PathComponent::Index(index) => {
-                if current.is_null() {
-                    *current = Value::Array(Vec::new());
-                }
-                let Some(array) = current.as_array_mut() else {
-                    return Err(MaterializationError::MissingPath(path.to_vec()));
-                };
-                while array.len() <= *index {
-                    array.push(Value::Null);
-                }
-                current = &mut array[*index];
-            }
-        }
-    }
-
-    match last {
-        PathComponent::Key(key) => {
-            if current.is_null() {
-                *current = Value::Object(serde_json::Map::new());
-            }
-            let Some(object) = current.as_object_mut() else {
-                return Err(MaterializationError::MissingPath(path.to_vec()));
-            };
-            object.insert(key.clone(), value);
-            Ok(())
-        }
-        PathComponent::Index(index) => {
-            if current.is_null() {
-                *current = Value::Array(Vec::new());
-            }
-            let Some(array) = current.as_array_mut() else {
-                return Err(MaterializationError::MissingPath(path.to_vec()));
-            };
-            while array.len() <= *index {
-                array.push(Value::Null);
-            }
-            array[*index] = value;
-            Ok(())
-        }
-    }
-}
-
-/// Applies a plan and materializes the result as a new revision.
-///
-/// The revision is built with the existing [`StateRevision::child`] constructor,
-/// so it carries the existing content-addressed identity and takes the selected
-/// parent as its parent. Nothing here is a new identity algorithm, and nothing
-/// here moves a branch head, writes to a store, or touches replication: the
-/// result is a value the caller decides what to do with.
-///
-/// Unlike [`apply_reconciliation_plan`], this is not pure — `StateRevision`
-/// timestamps come from the clock, as they do for every other revision this
-/// model creates. The application semantics stay in the pure function.
-pub fn reconcile(
-    base: &StateRevision,
-    left: &StateRevision,
-    right: &StateRevision,
-    plan: &ReconciliationPlan,
-    authority: String,
-) -> Result<StateReconciliationResult, String> {
-    let content = apply_reconciliation_plan(base, left, right, plan)?;
-    let parent = plan.selected_parent(left, right);
-    Ok(StateReconciliationResult {
-        materialized_state: StateRevision::child(content, parent, authority),
-        plan: plan.clone(),
-    })
-}
-
-// ============================================================================
-// ============================================================================
-// StateStore: Durable State Persistence and Retrieval
-// ============================================================================
-
-/// Durable, content-addressed revision storage.
-///
-/// `StateStore` answers exactly one question:
-///
-/// > **Do I have revision X?**
-///
-/// It deliberately does **not** answer *"what is the current revision?"*. That
-/// separation is the point of this type. State history and currentness are
-/// different concerns, and conflating them is what produced the two defects the
-/// branching audit recorded: a global `current` that moved on every commit
-/// regardless of which parent was named, and a branch map sharing one replicated
-/// record with it. Both lived in a single `state:current` row that nothing in
-/// the reconciliation chain ever read.
-///
-/// # The contract
-///
-/// | operation | method |
-/// | --- | --- |
-/// | put | [`create`](Self::create), [`commit`](Self::commit) |
-/// | get | [`get`](Self::get) |
-///
-/// Ancestry is not a third operation: it is [`get`](Self::get) followed by
-/// `parent_id`, repeated. [`parent`](Self::parent), [`exists`](Self::exists) and
-/// [`metadata`](Self::metadata) are conveniences over `get`, not new powers.
-///
-/// # Key schema
-///
-/// - `state:revision:{hex_id}` → [`StateRevision`]
-///
-/// That is the entire schema. A record keyed by the hash of its own content
-/// cannot be stale and needs no reconstruction, so there is **no recovery
-/// path**: [`with_feltdb`](Self::with_feltdb) does not scan, rebuild an index,
-/// or validate history before returning.
-///
-/// # What this deliberately does not provide
-///
-/// No `current`, no branches, no branch heads, no "latest". Nothing above the
-/// history layer is invented here. Something must eventually own *"which
-/// revision represents the current application state"* — a ref, an application
-/// record, a per-resource pointer, a transaction head — and that owner is not
-/// this type. Until it exists, callers hold the ids they care about.
-///
-/// # Non-claims
-///
-/// Proven for this type: durable single-writer append, retrieval by identity
-/// across restart, ancestry by parent traversal, and independence between
-/// records. **Not** proven and not claimed: multi-writer persistence semantics,
-/// concurrent revision creation, resource isolation, garbage collection, and
-/// distributed replication of revision history.
-///
-/// Two entries left that list when `/v1/state/*` began serving this type.
-/// *Server lifecycle integration*: `feltdb-server` opens a store over its own
-/// `FeltDb` through [`crate::FeltDBStateSystem`] and serves history, diff,
-/// classification and reconciliation from it. *Authorization*: those routes are
-/// authorized like every other route — `state:read` to read, `state:write` to
-/// commit — which is authorization **at the route**, not in this type. This
-/// type still has none of its own, and a caller holding a `StateStore` still
-/// reaches every resource in it.
-///
-/// *Current/head semantics* also left, but only partly, and the distinction
-/// matters: [`head_of`](Self::head_of) answers "the newest retained revision of
-/// this resource, by sequence". That is not a branch head and there is still no
-/// ref anything can move.
-pub struct StateStore {
-    backing: Backing,
-    mutation_lock: Arc<Mutex<()>>,
-}
-
-/// Where revisions actually live.
-///
-/// There is exactly one copy of a revision in either mode. The durable mode
-/// keeps no second in-memory index beside FeltDB's own rows.
-enum Backing {
-    /// In-memory only, for testing state semantics in isolation.
-    Volatile(Arc<Mutex<VolatileState>>),
-    /// FeltDB is the storage, and keyed reads are the authoritative read path.
-    Durable(Arc<crate::FeltDb>),
-}
-
-/// The volatile backing's contents: revisions, and per-resource retention.
-#[derive(Default)]
-struct VolatileState {
-    revisions: HashMap<StateId, StateRevision>,
-    retention: HashMap<String, RetentionState>,
-    refs: HashMap<(String, String), StateRef>,
-    objects: HashMap<StateId, StateObject>,
-}
-
-impl Clone for Backing {
-    fn clone(&self) -> Self {
-        match self {
-            Backing::Volatile(map) => Backing::Volatile(map.clone()),
-            Backing::Durable(db) => Backing::Durable(db.clone()),
-        }
-    }
-}
-
-/// The durable key for a revision.
-fn revision_key(id: &StateId) -> String {
-    format!("state:revision:{}", id.as_hex())
-}
-
-fn object_key(id: &StateId) -> String {
-    format!("state:object:{}", id.as_hex())
-}
-
-fn ref_key(namespace: &str, name: &str) -> String {
-    format!("state:ref:{}:{}", encode_ref_part(namespace), encode_ref_part(name))
-}
-
-fn encode_ref_part(value: &str) -> String {
-    value.replace('%', "%25").replace(':', "%3A")
-}
-
-fn valid_ref_component(value: &str) -> bool {
-    !value.trim().is_empty()
-}
-
-fn looks_like_state_id(value: &str) -> bool {
-    value.len() == 64 && value.chars().all(|c| c.is_ascii_hexdigit())
-}
-
-fn current_time_ms() -> u64 {
-    std::time::SystemTime::now()
-        .duration_since(std::time::UNIX_EPOCH)
-        .unwrap_or_default()
-        .as_millis() as u64
-}
-
-/// How long a revision is protected from garbage collection after it is
-/// minted, measured on its own `timestamp_ms`. A candidate an agent has just
-/// committed but not yet promoted is a root for this long, so a collection that
-/// races the promotion cannot reclaim it out from under the caller.
-pub(crate) const GC_GRACE_MS: u64 = 15 * 60 * 1000;
-
-/// Durable state-model writes as FeltDB transactions.
-///
-/// # Ordering
-///
-/// Every operation here follows the same three steps:
-///
-/// 1. **Read** the `state` rows the decision depends on.
-/// 2. **Decide** in Rust: versions, presence, integrity.
-/// 3. **Commit** with `FeltDb::apply_atomic_transaction_guarded`, carrying a
-///    record precondition for *every row read in step 1*. FeltDB evaluates the
-///    preconditions inside its commit lock, before staging anything, and
-///    applies the mutations — one log record, `sync_data` before returning —
-///    only if every row is still as it was read. Otherwise nothing is applied
-///    and the operation starts again from step 1.
-///
-/// So a decision is only ever applied to the state it was made against. The
-/// mutual exclusion is FeltDB's `Inner` mutex, shared by every `StateStore`,
-/// every `Arc<FeltDb>` clone and every `FeltDb::open` of the same path in one
-/// process; the per-instance `mutation_lock` plays no part on this backing.
-///
-/// # How a row is pinned
-///
-/// FeltDB's record precondition compares `__version`, reading a row without one
-/// as version 1, and stamps `N + 1` on a row written under `expected_version =
-/// N` (`require_absent` writes 1). That gives three kinds of pin:
-///
-/// - **Versioned rows** (ref, ref incarnation) are only ever written under a
-///   precondition, so their `__version` advances on every write and
-///   `expected_version = <as read>` pins them; an absent one is pinned by
-///   `require_absent`.
-/// - **Immutable rows** (revision, content object) are never versioned, so
-///   `expected_version = 1` means exactly "still present" and writes nothing.
-/// - **The generation row** (`state:_gcgen`) is rewritten by every ref change
-///   and every committed revision *without* a precondition, carrying a
-///   `__version` unique to that transaction (an unconditional write is stored
-///   verbatim). Writers therefore never conflict with each other through it,
-///   while a collection that pins the value it read is refused if any of them
-///   committed in between.
-///
-/// | operation | pinned | writes |
-/// | --- | --- | --- |
-/// | create ref | ref (absent), incarnation, target | ref, incarnation, generation |
-/// | CAS ref | ref, incarnation, target | ref, generation |
-/// | delete ref | ref, incarnation | (ref removed), incarnation, generation |
-/// | commit revision | revision (absent), content object, parent | object (if new), revision, generation |
-/// | collect | generation | (unreachable revisions and objects removed) |
-///
-/// The incarnation row is pinned alongside the ref because a delete followed by
-/// a create returns the ref row to `__version` 1; the incarnation row is never
-/// deleted, so its version only grows and the pair cannot repeat.
-///
-/// # The races this closes
-///
-/// - *Concurrent CAS.* Both read the ref at `__version` N; the first commit
-///   stamps N + 1; the second's precondition fails, it re-reads, and reports
-///   `VersionConflict`.
-/// - *GC vs promotion.* If the promotion commits first, the generation moved
-///   and GC re-plans with the target as a ref root. If GC commits first, the
-///   promotion's target pin fails, and on re-read it reports `UnknownTarget`.
-/// - *GC vs commit of a child.* If the commit lands first, the generation
-///   moved. If GC lands first, the commit's parent pin fails and it reports
-///   `UnknownParent`.
-///
-/// Revisions minted by the record write path are not committed here; each is a
-/// child of that path's current head, which collection always treats as a
-/// root, so they cannot gain a collected parent.
-///
-/// # Idempotent ref requests
-///
-/// Ref transactions carry deterministic ids derived from the ref, its
-/// *incarnation* and the version they act on, and a payload hash of the rest
-/// of the request. FeltDB binds an id to its payload durably, across restart
-/// and compaction. A repeat of a committed request finds its own payload under
-/// its id and returns `Ok` without writing; any other request for the same slot
-/// finds a different payload and is a conflict. The incarnation
-/// (`state:refinc:…`, advanced by every create) keeps a deleted-and-recreated
-/// ref, back at version 1, from matching a transaction of its predecessor. Rows
-/// written before this scheme have no incarnation and are incarnation 0.
-pub(crate) mod durable {
-    use super::*;
-    use crate::{AtomicMutation, FeltDb, FlowError, PreconditionFailure, RecordPrecondition};
-    use serde_json::json;
-    use std::sync::atomic::{AtomicU64, Ordering};
-
-    /// Fresh reads and a new attempt after a refused precondition. Each refusal
-    /// means a competing write committed, so the system as a whole makes
-    /// progress; the bound only turns pathological contention into an error.
-    const ATTEMPTS: usize = 64;
-
-    pub(super) const GENERATION_KEY: &str = "state:_gcgen";
-
-    fn incarnation_key(namespace: &str, name: &str) -> String {
-        format!(
-            "state:refinc:{}:{}",
-            encode_ref_part(namespace),
-            encode_ref_part(name)
-        )
-    }
-
-    fn put(key: &str, value: Value) -> AtomicMutation {
-        AtomicMutation {
-            capability: "state".into(),
-            key: key.into(),
-            value: Some(value),
-        }
-    }
-
-    fn remove(key: &str) -> AtomicMutation {
-        AtomicMutation {
-            capability: "state".into(),
-            key: key.into(),
-            value: None,
-        }
-    }
-
-    /// The version FeltDB's record precondition reads for a row.
-    fn row_version(row: &Value) -> u64 {
-        row.get("__version").and_then(Value::as_u64).unwrap_or(1)
-    }
-
-    /// Pin a row to exactly what was read: absent, or this version.
-    fn unchanged(key: &str, read: Option<&Value>) -> RecordPrecondition {
-        RecordPrecondition {
-            capability: "state".into(),
-            key: key.into(),
-            require_absent: read.is_none(),
-            expected_version: read.map(row_version),
-            ..RecordPrecondition::default()
-        }
-    }
-
-    /// Pin an immutable (never versioned) row as present.
-    fn present(key: &str) -> RecordPrecondition {
-        RecordPrecondition {
-            capability: "state".into(),
-            key: key.into(),
-            expected_version: Some(1),
-            ..RecordPrecondition::default()
-        }
-    }
-
-    /// The generation row's new value: a `__version` unique to this transaction.
-    /// Transaction ids are never applied twice, so every rewrite changes it.
-    fn advance_generation(transaction_id: &str) -> AtomicMutation {
-        let digest = Sha256::digest(transaction_id.as_bytes());
-        let mut bytes = [0u8; 8];
-        bytes.copy_from_slice(&digest[..8]);
-        put(
-            GENERATION_KEY,
-            json!({ "__version": u64::from_be_bytes(bytes), "transaction": transaction_id }),
-        )
-    }
-
-    fn unique_suffix() -> String {
-        static COUNTER: AtomicU64 = AtomicU64::new(0);
-        let nanos = std::time::SystemTime::now()
-            .duration_since(std::time::UNIX_EPOCH)
-            .unwrap_or_default()
-            .as_nanos();
-        format!(
-            "{}-{nanos}-{}",
-            std::process::id(),
-            COUNTER.fetch_add(1, Ordering::Relaxed)
-        )
-    }
-
-    fn ref_transaction_id(
-        kind: &str,
-        namespace: &str,
-        name: &str,
-        incarnation: u64,
-        version: Option<u64>,
-    ) -> String {
-        let mut hasher = Sha256::new();
-        for part in [
-            "feltdb.state.ref.v1",
-            kind,
-            namespace,
-            name,
-            &incarnation.to_string(),
-            &version.map(|v| v.to_string()).unwrap_or_default(),
-        ] {
-            hasher.update(part.as_bytes());
-            hasher.update([0u8]);
-        }
-        format!("state-ref:{:x}", hasher.finalize())
-    }
-
-    /// serde_json maps are ordered (no `preserve_order`), so this is canonical.
-    fn payload_hash(payload: &Value) -> String {
-        format!("sha256:{:x}", Sha256::digest(payload.to_string().as_bytes()))
-    }
-
-    fn incarnation_of(row: &Value) -> u64 {
-        row.get("__incarnation").and_then(Value::as_u64).unwrap_or(0)
-    }
-
-    fn incarnation_in(row: Option<&Value>) -> u64 {
-        row.and_then(|row| row.get("incarnation").and_then(Value::as_u64))
-            .unwrap_or(0)
-    }
-
-    fn ref_row(reference: &StateRef, incarnation: u64) -> Value {
-        let mut row = serde_json::to_value(reference).unwrap_or(Value::Null);
-        if let Some(object) = row.as_object_mut() {
-            object.insert("__incarnation".into(), Value::from(incarnation));
-        }
-        row
-    }
-
-    enum Refusal {
-        /// A pinned row changed: re-read and decide again.
-        Changed,
-        /// The id is already bound to another payload: re-read and decide again.
-        OtherRequest,
-        Failed(String),
-    }
-
-    fn refusal(error: FlowError) -> Refusal {
-        match error {
-            FlowError::PreconditionFailed(failure) => match *failure {
-                PreconditionFailure::Present { .. }
-                | PreconditionFailure::Missing { .. }
-                | PreconditionFailure::Version { .. } => Refusal::Changed,
-                other => Refusal::Failed(format!("{other:?}")),
-            },
-            FlowError::TransactionIdPayloadMismatch { .. } => Refusal::OtherRequest,
-            other => Refusal::Failed(other.to_string()),
-        }
-    }
-
-    fn storage(error: impl std::fmt::Display) -> RefError {
-        RefError::Storage(error.to_string())
-    }
-
-    fn contended(what: &str) -> String {
-        format!(
-            "{what} was refused by concurrent changes on {ATTEMPTS} consecutive attempts; nothing was applied"
-        )
-    }
-
-    fn row(db: &FeltDb, key: &str) -> Result<Option<Value>, RefError> {
-        db.get::<Value>(key).map_err(storage)
-    }
-
-    fn committed_payload(db: &FeltDb, id: &str) -> Result<Option<String>, RefError> {
-        db.applied_transaction_payload_hash(id).map_err(storage)
-    }
-
-    fn decode(row: Value) -> Result<StateRef, RefError> {
-        serde_json::from_value(row).map_err(storage)
-    }
-
-    fn commit(
-        db: &FeltDb,
-        id: &str,
-        payload: Option<&str>,
-        pins: &[RecordPrecondition],
-        mutations: &[AtomicMutation],
-    ) -> Result<(), Refusal> {
-        db.apply_atomic_transaction_guarded(id, payload, None, &[], pins, mutations, None)
-            .map(|_| ())
-            .map_err(refusal)
-    }
-
-    pub(super) fn create_ref(
-        db: &FeltDb,
-        namespace: &str,
-        name: &str,
-        target: StateId,
-        authority: String,
-        metadata: BTreeMap<String, Value>,
-    ) -> Result<StateRef, RefError> {
-        let ref_k = ref_key(namespace, name);
-        let inc_k = incarnation_key(namespace, name);
-        let target_k = revision_key(&target);
-        let payload = payload_hash(&json!({
-            "target": target.as_hex(),
-            "authority": authority,
-            "metadata": metadata,
-        }));
-        for _ in 0..ATTEMPTS {
-            let incarnation_row = row(db, &inc_k)?;
-            if let Some(existing) = row(db, &ref_k)? {
-                // The create that made this incarnation, repeated, is that create.
-                let id = ref_transaction_id("create", namespace, name, incarnation_of(&existing), None);
-                if committed_payload(db, &id)?.as_deref() == Some(payload.as_str()) {
-                    return decode(existing);
-                }
-                return Err(RefError::AlreadyExists);
-            }
-            if row(db, &target_k)?.is_none() {
-                return Err(RefError::UnknownTarget(target));
-            }
-            let incarnation = incarnation_in(incarnation_row.as_ref()) + 1;
-            let id = ref_transaction_id("create", namespace, name, incarnation, None);
-            let reference = StateRef {
-                namespace: namespace.to_string(),
-                name: name.to_string(),
-                target: target.clone(),
-                version: 1,
-                authority: authority.clone(),
-                updated_at_ms: current_time_ms(),
-                metadata: metadata.clone(),
-            };
-            let pins = [
-                unchanged(&ref_k, None),
-                unchanged(&inc_k, incarnation_row.as_ref()),
-                present(&target_k),
-            ];
-            let mutations = [
-                put(&ref_k, ref_row(&reference, incarnation)),
-                put(&inc_k, json!({ "incarnation": incarnation })),
-                advance_generation(&id),
-            ];
-            match commit(db, &id, Some(&payload), &pins, &mutations) {
-                Ok(()) => return Ok(reference),
-                Err(Refusal::Changed | Refusal::OtherRequest) => continue,
-                Err(Refusal::Failed(message)) => return Err(RefError::Storage(message)),
-            }
-        }
-        Err(RefError::Storage(contended("ref create")))
-    }
-
-    pub(super) fn compare_and_swap_ref(
-        db: &FeltDb,
-        namespace: &str,
-        name: &str,
-        expected_version: u64,
-        target: StateId,
-        authority: String,
-        metadata: Option<BTreeMap<String, Value>>,
-    ) -> Result<StateRef, RefError> {
-        let ref_k = ref_key(namespace, name);
-        let inc_k = incarnation_key(namespace, name);
-        let target_k = revision_key(&target);
-        let payload = payload_hash(&json!({
-            "target": target.as_hex(),
-            "authority": authority,
-            "metadata": metadata,
-        }));
-        for _ in 0..ATTEMPTS {
-            let incarnation_row = row(db, &inc_k)?;
-            let Some(ref_read) = row(db, &ref_k)? else {
-                return Err(RefError::NotFound);
-            };
-            let incarnation = incarnation_of(&ref_read);
-            let current = decode(ref_read.clone())?;
-            let id = ref_transaction_id("cas", namespace, name, incarnation, Some(expected_version));
-            if current.version != expected_version {
-                // Either this exact request already committed (a retry), or
-                // another one did: the payload bound to the id says which.
-                if committed_payload(db, &id)?.as_deref() == Some(payload.as_str()) {
-                    if current.version == expected_version + 1 && current.target == target {
-                        return Ok(current);
-                    }
-                    // Committed, and the ref has moved on since. Describe the
-                    // transition this request made; `updated_at_ms` is now.
-                    return Ok(StateRef {
-                        version: expected_version + 1,
-                        target,
-                        authority,
-                        updated_at_ms: current_time_ms(),
-                        metadata: metadata.unwrap_or(current.metadata),
-                        ..current
-                    });
-                }
-                return Err(RefError::VersionConflict {
-                    expected: expected_version,
-                    current: current.version,
-                });
-            }
-            if row(db, &target_k)?.is_none() {
-                return Err(RefError::UnknownTarget(target));
-            }
-            let next = StateRef {
-                version: expected_version + 1,
-                target: target.clone(),
-                authority: authority.clone(),
-                updated_at_ms: current_time_ms(),
-                metadata: metadata.clone().unwrap_or_else(|| current.metadata.clone()),
-                ..current
-            };
-            let pins = [
-                unchanged(&ref_k, Some(&ref_read)),
-                unchanged(&inc_k, incarnation_row.as_ref()),
-                present(&target_k),
-            ];
-            let mutations = [put(&ref_k, ref_row(&next, incarnation)), advance_generation(&id)];
-            match commit(db, &id, Some(&payload), &pins, &mutations) {
-                Ok(()) => return Ok(next),
-                Err(Refusal::Changed | Refusal::OtherRequest) => continue,
-                Err(Refusal::Failed(message)) => return Err(RefError::Storage(message)),
-            }
-        }
-        Err(RefError::Storage(contended("ref compare-and-swap")))
-    }
-
-    pub(super) fn delete_ref(
-        db: &FeltDb,
-        namespace: &str,
-        name: &str,
-        expected_version: Option<u64>,
-    ) -> Result<(), RefError> {
-        let ref_k = ref_key(namespace, name);
-        let inc_k = incarnation_key(namespace, name);
-        let payload = payload_hash(&json!({ "expected_version": expected_version }));
-        for _ in 0..ATTEMPTS {
-            let incarnation_row = row(db, &inc_k)?;
-            let Some(ref_read) = row(db, &ref_k)? else {
-                // A repeat of a delete that already removed this incarnation.
-                let id = ref_transaction_id(
-                    "delete",
-                    namespace,
-                    name,
-                    incarnation_in(incarnation_row.as_ref()),
-                    None,
-                );
-                if committed_payload(db, &id)?.as_deref() == Some(payload.as_str()) {
-                    return Ok(());
-                }
-                return Err(RefError::NotFound);
-            };
-            let incarnation = incarnation_of(&ref_read);
-            let current = decode(ref_read.clone())?;
-            if let Some(expected) = expected_version {
-                if current.version != expected {
-                    return Err(RefError::VersionConflict {
-                        expected,
-                        current: current.version,
-                    });
-                }
-            }
-            let id = ref_transaction_id("delete", namespace, name, incarnation, None);
-            let pins = [
-                unchanged(&ref_k, Some(&ref_read)),
-                unchanged(&inc_k, incarnation_row.as_ref()),
-            ];
-            let mutations = [
-                remove(&ref_k),
-                put(&inc_k, json!({ "incarnation": incarnation })),
-                advance_generation(&id),
-            ];
-            match commit(db, &id, Some(&payload), &pins, &mutations) {
-                Ok(()) => return Ok(()),
-                Err(Refusal::Changed | Refusal::OtherRequest) => continue,
-                Err(Refusal::Failed(message)) => return Err(RefError::Storage(message)),
-            }
-        }
-        Err(RefError::Storage(contended("ref delete")))
-    }
-
-    pub(super) fn commit_revision(
-        db: &FeltDb,
-        revision: StateRevision,
-    ) -> Result<StateRevision, RevisionError> {
-        let fail = |error: &dyn std::fmt::Display| RevisionError::Storage(error.to_string());
-        let object = StateObject::new(revision.content.clone());
-        let rev_k = revision_key(&revision.id);
-        let obj_k = object_key(&object.id);
-        let parent_k = revision.parent_id.as_ref().map(revision_key);
-        for _ in 0..ATTEMPTS {
-            if let Some(existing) = db.get::<StateRevision>(&rev_k).map_err(|e| fail(&e))? {
-                let same = existing.resource == revision.resource
-                    && existing.content_id == revision.content_id
-                    && existing.parent_id == revision.parent_id
-                    && existing.sequence == revision.sequence;
-                return if same {
-                    Ok(existing)
-                } else {
-                    Err(RevisionError::AlreadyCommitted(revision.id.clone()))
-                };
-            }
-            let mut pins = vec![unchanged(&rev_k, None)];
-            if let (Some(parent), Some(parent_k)) = (&revision.parent_id, &parent_k) {
-                if db.get::<Value>(parent_k).map_err(|e| fail(&e))?.is_none() {
-                    return Err(RevisionError::UnknownParent(parent.clone()));
-                }
-                pins.push(present(parent_k));
-            }
-            let id = format!("state-revision:{}:{}", revision.id.as_hex(), unique_suffix());
-            let mut mutations = Vec::with_capacity(3);
-            match db.get::<StateObject>(&obj_k).map_err(|e| fail(&e))? {
-                Some(existing) if !existing.verify_integrity() => {
-                    return Err(RevisionError::Storage(
-                        "Stored state object failed integrity verification".to_string(),
-                    ));
-                }
-                Some(_) => pins.push(present(&obj_k)),
-                None => {
-                    pins.push(unchanged(&obj_k, None));
-                    mutations.push(put(&obj_k, serde_json::to_value(&object).map_err(|e| fail(&e))?));
-                }
-            }
-            mutations.push(put(&rev_k, serde_json::to_value(&revision).map_err(|e| fail(&e))?));
-            mutations.push(advance_generation(&id));
-            match commit(db, &id, None, &pins, &mutations) {
-                Ok(()) => return Ok(revision),
-                Err(Refusal::Changed | Refusal::OtherRequest) => continue,
-                Err(Refusal::Failed(message)) => return Err(RevisionError::Storage(message)),
-            }
-        }
-        Err(RevisionError::Storage(contended("revision commit")))
-    }
-
-    pub(super) fn collect(
-        store: &StateStore,
-        db: &FeltDb,
-        now_ms: u64,
-    ) -> Result<GarbageCollectionReport, GarbageCollectionError> {
-        let fail = |error: &dyn std::fmt::Display| GarbageCollectionError::Storage(error.to_string());
-        for _ in 0..ATTEMPTS {
-            // The generation first: everything planned below was read after it,
-            // so a write that lands after this read moves it.
-            let generation = db.get::<Value>(GENERATION_KEY).map_err(|e| fail(&e))?;
-            let report = store.plan_collection(now_ms, &db.revision_head_ids());
-            if report.collected_revisions.is_empty() && report.collected_objects.is_empty() {
-                return Ok(report);
-            }
-            let pins = [unchanged(GENERATION_KEY, generation.as_ref())];
-            let mutations: Vec<AtomicMutation> = report
-                .collected_revisions
-                .iter()
-                .map(|id| remove(&revision_key(id)))
-                .chain(report.collected_objects.iter().map(|id| remove(&object_key(id))))
-                .collect();
-            let id = format!("state-gc:{}", unique_suffix());
-            match commit(db, &id, None, &pins, &mutations) {
-                Ok(()) => return Ok(report),
-                Err(Refusal::Changed | Refusal::OtherRequest) => continue,
-                Err(Refusal::Failed(message)) => return Err(GarbageCollectionError::Storage(message)),
-            }
-        }
-        Err(GarbageCollectionError::Storage(contended("garbage collection")))
-    }
-}
-
-fn collect_referenced_objects(revision: &StateRevision) -> BTreeSet<StateId> {
-    let mut ids = BTreeSet::from([revision.content_id.clone()]);
-    if let Some(values) = revision
-        .metadata
-        .get("object_refs")
-        .and_then(Value::as_array)
-    {
-        for value in values {
-            if let Some(hex) = value.as_str().filter(|value| looks_like_state_id(value)) {
-                ids.insert(StateId::from_hex(hex.to_string()));
-            }
-        }
-    }
-    ids
-}
-
-/// Where a resource's retention watermark lives.
-fn retention_key(resource: &str) -> String {
-    format!("_retention:{resource}")
-}
-
-/// How much of a resource's history is kept.
-///
-/// Count-based only. Age-based retention is deliberately not implemented:
-/// nothing in the system needs it yet, and inventing a second policy dimension
-/// before the first has been measured would be guesswork.
-#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
-pub struct RetentionPolicy {
-    /// Newest revisions to keep, or `None` to keep every revision.
-    ///
-    /// Clamped to at least 1: **a resource's current revision always survives.**
-    pub keep_last: Option<usize>,
-}
-
-impl RetentionPolicy {
-    /// Keep everything. The default, because silently discarding history would
-    /// be a worse surprise than unbounded growth.
-    pub const fn unbounded() -> Self {
-        RetentionPolicy { keep_last: None }
-    }
-
-    /// Keep the newest `count` revisions of a resource.
-    pub fn keep_last(count: usize) -> Self {
-        RetentionPolicy {
-            keep_last: Some(count.max(1)),
-        }
-    }
-}
-
-impl Default for RetentionPolicy {
-    fn default() -> Self {
-        Self::unbounded()
-    }
-}
-
-/// A resource's retention state: its policy, and how far its history has been
-/// expired.
-#[derive(Clone, Debug, Default, Serialize, Deserialize)]
-struct RetentionState {
-    policy: RetentionPolicy,
-    /// The lowest sequence still retained. Everything below it was expired on
-    /// purpose, and is distinguishable from a parent that never existed.
-    horizon: u64,
-}
-
-/// Decide what a retention policy expires, given a resource's history.
-///
-/// Pure, and the single definition of what retention *means*, so the explicit
-/// store API and the automatic mint at the write boundary cannot drift apart.
-///
-/// `history` is `(id, sequence)` oldest first. Returns the revisions to expire
-/// and the new horizon — the lowest sequence still retained.
-///
-/// Deletion is from the oldest end only, so what survives is always a suffix of
-/// the resource's timeline and **the current revision always survives**.
-pub fn revisions_to_expire(
-    history: &[(StateId, u64)],
-    keep_last: Option<usize>,
-) -> (Vec<StateId>, Option<u64>) {
-    let Some(keep) = keep_last else {
-        return (Vec::new(), None);
-    };
-    let keep = keep.max(1);
-    if history.len() <= keep {
-        return (Vec::new(), None);
-    }
-    let split = history.len() - keep;
-    let expire = history[..split].iter().map(|(id, _)| id.clone()).collect();
-    let horizon = history[split].1;
-    (expire, Some(horizon))
-}
-
-/// Why a revision could not be minted.
-#[derive(Clone, Debug, PartialEq, Eq)]
-pub enum RevisionError {
-    /// Invariant 2: the named parent is not a revision this store holds.
-    UnknownParent(StateId),
-    /// Invariant 1: that identity is already committed, and commits are final.
-    ///
-    /// Under the resource-scoped model this should be unreachable through
-    /// `mint`, because the sequence is allocated from the resource's own head.
-    /// It is enforced anyway: immutability is the invariant, not a consequence.
-    AlreadyCommitted(StateId),
-    /// A parent belonging to a different resource.
-    ForeignParent { expected: String, found: String },
-    /// The resource already has a first revision; a resource has one beginning.
-    ResourceAlreadyBegun { resource: String, head: StateId },
-    /// The revision's own identity does not match what it is computed from.
-    IntegrityFailed,
-    /// The backing store could not be read or written.
-    Storage(String),
-}
-
-impl std::fmt::Display for RevisionError {
-    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
-        match self {
-            RevisionError::UnknownParent(id) => {
-                write!(f, "parent {id} is not a revision this store holds")
-            }
-            RevisionError::AlreadyCommitted(id) => {
-                write!(
-                    f,
-                    "revision {id} is already committed and cannot be rewritten"
-                )
-            }
-            RevisionError::ForeignParent { expected, found } => {
-                write!(f, "parent belongs to resource {found}, not {expected}")
-            }
-            RevisionError::ResourceAlreadyBegun { resource, head } => {
-                write!(f, "resource {resource} already begins at revision {head}")
-            }
-            RevisionError::IntegrityFailed => write!(f, "state integrity verification failed"),
-            RevisionError::Storage(message) => write!(f, "{message}"),
-        }
-    }
-}
-
-impl std::error::Error for RevisionError {}
-
-/// What following a revision's parent link found.
-///
-/// The three outcomes are deliberately distinct. An **expired** parent is a
-/// retention decision the system made on purpose; an **unknown** one is a bug.
-/// Collapsing them would recreate the dangling-parent defect at the other end
-/// of the system, where retention rather than minting produced it.
-#[derive(Clone, Debug)]
-pub enum ParentLookup {
-    /// This revision began its resource's history.
-    Root,
-    /// The parent, still retained.
-    Revision(Box<StateRevision>),
-    /// The parent was expired by retention. Its identity is still named by the
-    /// child, and the child's ancestry is still true — it is simply no longer
-    /// stored.
-    Expired(StateId),
-    /// The parent is named but absent and *not* below the retention horizon.
-    /// The model does not permit minting one; finding one means damage.
-    Missing(StateId),
-}
-
-impl ParentLookup {
-    /// The identity this lookup names, if it names one.
-    pub fn id(&self) -> Option<&StateId> {
-        match self {
-            ParentLookup::Root => None,
-            ParentLookup::Revision(revision) => Some(&revision.id),
-            ParentLookup::Expired(id) | ParentLookup::Missing(id) => Some(id),
-        }
-    }
-}
-
-/// Equality is over the outcome and the identity named, not the whole revision.
-impl PartialEq for ParentLookup {
-    fn eq(&self, other: &Self) -> bool {
-        std::mem::discriminant(self) == std::mem::discriminant(other) && self.id() == other.id()
-    }
-}
-
-impl StateStore {
-    /// A volatile (in-memory) store, for testing state semantics in isolation.
-    ///
-    /// Revisions are lost when the store is dropped. Production must use
-    /// [`with_feltdb`](Self::with_feltdb).
-    pub fn new_volatile() -> Self {
-        StateStore {
-            backing: Backing::Volatile(Arc::new(Mutex::new(VolatileState::default()))),
-            mutation_lock: Arc::new(Mutex::new(())),
-        }
-    }
-
-    /// A store backed by FeltDB's canonical persistence.
-    ///
-    /// This performs **no recovery**. Revisions are records under
-    /// `state:revision:{hex}`; they are already durable, so there is no index to
-    /// rebuild and nothing to validate up front. A revision's integrity is
-    /// checked when it is written, and can be rechecked by whoever reads it.
-    ///
-    /// The `Result` is retained because callers depend on it; today it is always
-    /// `Ok`.
-    pub fn with_feltdb(feltdb: Arc<crate::FeltDb>) -> Result<Self, String> {
-        Ok(StateStore {
-            backing: Backing::Durable(feltdb),
-            mutation_lock: Arc::new(Mutex::new(())),
-        })
-    }
-
-    // -- minting ------------------------------------------------------------
-
-    /// Begin a resource's history.
-    ///
-    /// Refused if the resource already has one. A resource has a single
-    /// beginning; without that, `history_of` would return a forest rather than
-    /// a chain and "the previous state of this resource" would be ambiguous
-    /// again. To extend an existing history, use [`commit`](Self::commit) or
-    /// [`mint`](Self::mint).
-    pub fn create(
-        &self,
-        resource: &str,
-        content: String,
-        authority: String,
-    ) -> Result<StateRevision, RevisionError> {
-        if let Some(head) = self.head_of(resource) {
-            return Err(RevisionError::ResourceAlreadyBegun {
-                resource: resource.to_string(),
-                head: head.id,
-            });
-        }
-        self.mint(resource, content, None, authority)
-    }
-
-    /// Commit a revision descending from `parent`, on the parent's resource.
-    pub fn commit(
-        &self,
-        content: String,
-        parent: &StateRevision,
-        authority: String,
-    ) -> Result<StateRevision, RevisionError> {
-        let resource = parent.resource.clone();
-        self.mint(&resource, content, Some(parent), authority)
-    }
-
-    /// Mint a revision of `resource`, optionally descending from `parent`.
-    ///
-    /// Enforces both invariants at the only point where they can be enforced:
-    ///
-    /// 1. A parent must resolve to a revision this store holds, and must belong
-    ///    to the same resource. Parent existence is part of what makes a
-    ///    revision valid, not a lookup applied afterwards.
-    /// 2. A committed revision is never rewritten. The sequence is allocated
-    ///    from the resource's own head, so a state reached twice is two
-    ///    revisions with two identities.
-    ///
-    /// Retention is applied to the resource afterwards, so a configured policy
-    /// bounds history at the moment history is created rather than at some
-    /// later maintenance pass that may never run.
-    pub fn mint(
-        &self,
-        resource: &str,
-        content: String,
-        parent: Option<&StateRevision>,
-        authority: String,
-    ) -> Result<StateRevision, RevisionError> {
-        if let Some(parent) = parent {
-            if parent.resource != resource {
-                return Err(RevisionError::ForeignParent {
-                    expected: resource.to_string(),
-                    found: parent.resource.clone(),
-                });
-            }
-            if !self.exists(&parent.id) {
-                return Err(RevisionError::UnknownParent(parent.id.clone()));
-            }
-        }
-
-        let sequence = match parent {
-            Some(parent) => parent.sequence + 1,
-            None => 0,
-        };
-        let revision = StateRevision::at(
-            resource.to_string(),
-            content,
-            parent.map(|parent| parent.id.clone()),
-            sequence,
-            authority,
-        );
-        let committed = self.commit_revision(revision)?;
-        self.apply_retention(resource)?;
-        Ok(committed)
-    }
-
-    /// Store a revision, after checking its integrity and that it is new.
-    fn commit_revision(&self, revision: StateRevision) -> Result<StateRevision, RevisionError> {
-        if !revision.verify_integrity() {
-            return Err(RevisionError::IntegrityFailed);
-        }
-        // Re-committing an identical historical fact is a no-op, not a rewrite:
-        // the identity is a function of the resource, the content, the parent
-        // and the sequence, so an existing revision with this identity records
-        // exactly what is being committed. Returning it keeps immutability
-        // without making a harmless repeat an error.
-        if let Some(existing) = self.get(&revision.id) {
-            let same = existing.resource == revision.resource
-                && existing.content_id == revision.content_id
-                && existing.parent_id == revision.parent_id
-                && existing.sequence == revision.sequence;
-            return if same {
-                Ok(existing)
-            } else {
-                Err(RevisionError::AlreadyCommitted(revision.id.clone()))
-            };
-        }
-        match &self.backing {
-            Backing::Volatile(state) => {
-                let mut state = state.lock().unwrap();
-                state
-                    .objects
-                    .entry(revision.content_id.clone())
-                    .or_insert_with(|| StateObject::new(revision.content.clone()));
-                state.revisions.insert(revision.id.clone(), revision.clone());
-            }
-            Backing::Durable(feltdb) => {
-                return durable::commit_revision(feltdb, revision);
-            }
-        }
-        Ok(revision)
-    }
-
-    // -- reading ------------------------------------------------------------
-
-    /// Retrieve a revision by identity. This is the authoritative read path.
-    pub fn get(&self, id: &StateId) -> Option<StateRevision> {
-        match &self.backing {
-            Backing::Volatile(state) => state.lock().unwrap().revisions.get(id).cloned(),
-            Backing::Durable(feltdb) => feltdb
-                .get::<StateRevision>(&revision_key(id))
-                .ok()
-                .flatten(),
-        }
-    }
-
-    /// Whether a revision is present.
-    pub fn exists(&self, id: &StateId) -> bool {
-        self.get(id).is_some()
-    }
-
-    /// Metadata for a revision.
-    pub fn metadata(&self, id: &StateId) -> Option<BTreeMap<String, Value>> {
-        self.get(id).map(|revision| revision.metadata)
-    }
-
-    /// The parent of a revision, and — when it is not there — why.
-    pub fn parent_of(&self, id: &StateId) -> Option<ParentLookup> {
-        let revision = self.get(id)?;
-        let Some(parent_id) = revision.parent_id else {
-            return Some(ParentLookup::Root);
-        };
-        if let Some(parent) = self.get(&parent_id) {
-            return Some(ParentLookup::Revision(Box::new(parent)));
-        }
-        let horizon = self.retention_state(&revision.resource).horizon;
-        Some(if revision.sequence <= horizon {
-            ParentLookup::Expired(parent_id)
-        } else {
-            ParentLookup::Missing(parent_id)
-        })
-    }
-
-    /// The parent of a revision, if it is still retained.
-    ///
-    /// Repeating this walks the ancestry. It is a traversal, not a primitive.
-    /// Use [`parent_of`](Self::parent_of) to tell a resource's beginning from a
-    /// horizon.
-    pub fn parent(&self, id: &StateId) -> Option<StateRevision> {
-        match self.parent_of(id)? {
-            ParentLookup::Revision(parent) => Some(*parent),
-            _ => None,
-        }
-    }
-
-    /// Every retained revision of one resource, oldest first.
-    pub fn history_of(&self, resource: &str) -> Vec<StateRevision> {
-        let mut history: Vec<StateRevision> = self
-            .all_revisions()
-            .into_iter()
-            .filter(|revision| revision.resource == resource)
-            .collect();
-        history.sort_by_key(|revision| revision.sequence);
-        history
-    }
-
-    /// A resource's newest retained revision.
-    ///
-    /// Automatic minting produces a chain, so this is unambiguous for anything
-    /// the write path created. Explicit `commit` may fork a resource — which is
-    /// exactly what divergence and three-way reconciliation need — and where it
-    /// has, this is the newest by sequence, ties broken by identity so the
-    /// answer is deterministic rather than incidental.
-    pub fn head_of(&self, resource: &str) -> Option<StateRevision> {
-        self.history_of(resource).into_iter().max_by(|one, two| {
-            one.sequence
-                .cmp(&two.sequence)
-                .then_with(|| one.id.as_hex().cmp(two.id.as_hex()))
-        })
-    }
-
-    /// Every resource this store holds history for.
-    pub fn resources(&self) -> Vec<String> {
-        let mut names: Vec<String> = self
-            .all_revisions()
-            .into_iter()
-            .map(|revision| revision.resource)
-            .collect();
-        names.sort();
-        names.dedup();
-        names
-    }
-
-    /// Create a mutable reference in a namespace.
-    ///
-    /// On the durable backing this is one fenced FeltDB transaction (see
-    /// [`durable`]): the ref is created at version 1 only if, at the moment of
-    /// commit, it is still absent and its target revision is still present.
-    /// Repeating an identical create that already succeeded returns the ref it
-    /// created; a different create of an existing ref is `AlreadyExists`.
-    pub fn create_ref(
-        &self,
-        namespace: &str,
-        name: &str,
-        target: StateId,
-        authority: String,
-        metadata: BTreeMap<String, Value>,
-    ) -> Result<StateRef, RefError> {
-        if !valid_ref_component(namespace) || !valid_ref_component(name) {
-            return Err(RefError::InvalidIdentifier);
-        }
-        match &self.backing {
-            Backing::Durable(feltdb) => {
-                durable::create_ref(feltdb, namespace, name, target, authority, metadata)
-            }
-            Backing::Volatile(_) => {
-                let _guard = self.mutation_lock.lock().unwrap();
-                if !self.exists(&target) {
-                    return Err(RefError::UnknownTarget(target));
-                }
-                if self.get_ref(namespace, name).is_some() {
-                    return Err(RefError::AlreadyExists);
-                }
-                let reference = StateRef {
-                    namespace: namespace.to_string(),
-                    name: name.to_string(),
-                    target,
-                    version: 1,
-                    authority,
-                    updated_at_ms: current_time_ms(),
-                    metadata,
-                };
-                self.write_volatile_ref(&reference);
-                Ok(reference)
-            }
-        }
-    }
-
-    /// Read a reference.
-    pub fn get_ref(&self, namespace: &str, name: &str) -> Option<StateRef> {
-        if !valid_ref_component(namespace) || !valid_ref_component(name) {
-            return None;
-        }
-        match &self.backing {
-            Backing::Volatile(state) => state
-                .lock()
-                .unwrap()
-                .refs
-                .get(&(namespace.to_string(), name.to_string()))
-                .cloned(),
-            Backing::Durable(feltdb) => feltdb
-                .get::<StateRef>(&ref_key(namespace, name))
-                .ok()
-                .flatten(),
-        }
-    }
-
-    /// Move a reference with stale-version rejection.
-    pub fn move_ref(
-        &self,
-        namespace: &str,
-        name: &str,
-        target: StateId,
-        authority: String,
-    ) -> Result<StateRef, RefError> {
-        let current = self.get_ref(namespace, name).ok_or(RefError::NotFound)?;
-        self.compare_and_swap_ref(namespace, name, current.version, target, authority, None)
-    }
-
-    /// Compare-and-swap move for a reference.
-    ///
-    /// On the durable backing this is one fenced FeltDB transaction: it commits
-    /// only if, at the moment of commit, the ref is still at
-    /// `expected_version` and the target revision is still present, whichever
-    /// `StateStore` or `FeltDb` handle the competing writes came through.
-    ///
-    /// The request `(ref incarnation, expected_version, target, authority,
-    /// metadata)` is idempotent: repeating one that already committed — after a
-    /// lost response, a restart or a compaction — returns `Ok` and does not
-    /// advance the ref again. Any other request for the same expected version
-    /// is a `VersionConflict`.
-    pub fn compare_and_swap_ref(
-        &self,
-        namespace: &str,
-        name: &str,
-        expected_version: u64,
-        target: StateId,
-        authority: String,
-        metadata: Option<BTreeMap<String, Value>>,
-    ) -> Result<StateRef, RefError> {
-        if !valid_ref_component(namespace) || !valid_ref_component(name) {
-            return Err(RefError::InvalidIdentifier);
-        }
-        match &self.backing {
-            Backing::Durable(feltdb) => durable::compare_and_swap_ref(
-                feltdb,
-                namespace,
-                name,
-                expected_version,
-                target,
-                authority,
-                metadata,
-            ),
-            Backing::Volatile(_) => {
-                let _guard = self.mutation_lock.lock().unwrap();
-                let mut current = self.get_ref(namespace, name).ok_or(RefError::NotFound)?;
-                if current.version != expected_version {
-                    return Err(RefError::VersionConflict {
-                        expected: expected_version,
-                        current: current.version,
-                    });
-                }
-                if !self.exists(&target) {
-                    return Err(RefError::UnknownTarget(target));
-                }
-                current.target = target;
-                current.version += 1;
-                current.authority = authority;
-                current.updated_at_ms = current_time_ms();
-                if let Some(metadata) = metadata {
-                    current.metadata = metadata;
-                }
-                self.write_volatile_ref(&current);
-                Ok(current)
-            }
-        }
-    }
-
-    /// Delete a reference, optionally enforcing the current version.
-    ///
-    /// On the durable backing this is one fenced FeltDB transaction, and a
-    /// repeat of an identical delete that already committed returns `Ok`.
-    pub fn delete_ref(
-        &self,
-        namespace: &str,
-        name: &str,
-        expected_version: Option<u64>,
-    ) -> Result<(), RefError> {
-        if !valid_ref_component(namespace) || !valid_ref_component(name) {
-            return Err(RefError::InvalidIdentifier);
-        }
-        match &self.backing {
-            Backing::Durable(feltdb) => {
-                durable::delete_ref(feltdb, namespace, name, expected_version)
-            }
-            Backing::Volatile(state) => {
-                let _guard = self.mutation_lock.lock().unwrap();
-                let current = self.get_ref(namespace, name).ok_or(RefError::NotFound)?;
-                if let Some(expected) = expected_version {
-                    if current.version != expected {
-                        return Err(RefError::VersionConflict {
-                            expected,
-                            current: current.version,
-                        });
-                    }
-                }
-                state
-                    .lock()
-                    .unwrap()
-                    .refs
-                    .remove(&(namespace.to_string(), name.to_string()));
-                Ok(())
-            }
-        }
-    }
-
-    /// Enumerate refs, optionally scoped to one namespace.
-    pub fn list_refs(&self, namespace: Option<&str>) -> Vec<StateRef> {
-        let mut refs: Vec<StateRef> = match &self.backing {
-            Backing::Volatile(state) => state.lock().unwrap().refs.values().cloned().collect(),
-            Backing::Durable(feltdb) => feltdb
-                .list_collection("state")
-                .unwrap_or_default()
-                .into_iter()
-                .filter(|row| row.key.starts_with("state:ref:") && !row.deleted)
-                .filter_map(|row| serde_json::from_value::<StateRef>(row.value).ok())
-                .collect(),
-        };
-        if let Some(namespace) = namespace {
-            refs.retain(|reference| reference.namespace == namespace);
-        }
-        refs.sort_by(|one, two| {
-            one.namespace
-                .cmp(&two.namespace)
-                .then_with(|| one.name.cmp(&two.name))
-        });
-        refs
-    }
-
-    /// Materialize a full revision value or a deterministic projection of it.
-    pub fn materialize(
-        &self,
-        revision_id: &StateId,
-        projection: &MaterializationProjection,
-    ) -> Result<Value, MaterializationError> {
-        let revision = self
-            .get(revision_id)
-            .ok_or_else(|| MaterializationError::RevisionNotFound(revision_id.clone()))?;
-        let source: Value = serde_json::from_str(&revision.content)
-            .map_err(|error| MaterializationError::ContentUnparseable(error.to_string()))?;
-        if projection.is_full() {
-            return Ok(source);
-        }
-        let mut paths = projection.paths.clone();
-        paths.sort();
-        paths.dedup();
-        for pair in paths.windows(2) {
-            if paths_overlap(&pair[0], &pair[1]) {
-                return Err(MaterializationError::NonDeterministicProjection);
-            }
-        }
-        let mut projected = Value::Object(serde_json::Map::new());
-        for path in paths {
-            let value = resolve_path(&source, &path)
-                .cloned()
-                .ok_or_else(|| MaterializationError::MissingPath(path.clone()))?;
-            assign_projection(&mut projected, &path, value)?;
-        }
-        Ok(projected)
-    }
-
-    /// Collect revisions and objects that no root can reach.
-    ///
-    /// **Roots** are: every ref target; every resource's latest revision (each
-    /// revision at the resource's highest sequence, and the head the record
-    /// write path will mint its next revision from); and every revision
-    /// younger than 15 minutes (`GC_GRACE_MS`). **Reachable** is the roots and all their
-    /// ancestors by `parent_id`, because history, diff, rollback and replicated
-    /// reconstruction all walk that chain. Only a revision that is old, named
-    /// by no ref, not latest, and an ancestor of none of those is collected —
-    /// in practice, an abandoned fork. Retention (`keep_last`) is unaffected:
-    /// it is positional and runs at the mint, not here.
-    ///
-    /// On the durable backing every deletion commits in one FeltDB transaction
-    /// fenced on the state generation, which every ref change and every
-    /// committed revision advances. A concurrent change aborts the collection
-    /// and it is re-planned from fresh reads; see [`durable`].
-    pub fn collect_unreachable(&self) -> Result<GarbageCollectionReport, GarbageCollectionError> {
-        self.collect_unreachable_at(current_time_ms())
-    }
-
-    /// [`collect_unreachable`](Self::collect_unreachable) with an explicit
-    /// clock, so the grace period can be tested without waiting for it.
-    pub(crate) fn collect_unreachable_at(
-        &self,
-        now_ms: u64,
-    ) -> Result<GarbageCollectionReport, GarbageCollectionError> {
-        match &self.backing {
-            Backing::Volatile(state) => {
-                let _guard = self.mutation_lock.lock().unwrap();
-                let report = self.plan_collection(now_ms, &[]);
-                let mut state = state.lock().unwrap();
-                for id in &report.collected_revisions {
-                    state.revisions.remove(id);
-                }
-                for id in &report.collected_objects {
-                    state.objects.remove(id);
-                }
-                Ok(report)
-            }
-            Backing::Durable(feltdb) => durable::collect(self, feltdb, now_ms),
-        }
-    }
-
-    /// What a collection at `now_ms` would keep and delete, from one read of
-    /// refs and revisions. `extra_roots` are heads known outside `StateStore`.
-    fn plan_collection(&self, now_ms: u64, extra_roots: &[StateId]) -> GarbageCollectionReport {
-        let roots = self.list_refs(None);
-        let revisions = self.all_revisions();
-        let by_id: HashMap<StateId, &StateRevision> =
-            revisions.iter().map(|revision| (revision.id.clone(), revision)).collect();
-
-        let mut latest: HashMap<&str, u64> = HashMap::new();
-        for revision in &revisions {
-            let entry = latest.entry(revision.resource.as_str()).or_insert(revision.sequence);
-            if revision.sequence > *entry {
-                *entry = revision.sequence;
-            }
-        }
-
-        let mut pending: Vec<StateId> = roots.iter().map(|reference| reference.target.clone()).collect();
-        pending.extend(extra_roots.iter().cloned());
-        for revision in &revisions {
-            let is_latest = latest.get(revision.resource.as_str()) == Some(&revision.sequence);
-            let is_young = now_ms.saturating_sub(revision.timestamp_ms) < GC_GRACE_MS;
-            if is_latest || is_young {
-                pending.push(revision.id.clone());
-            }
-        }
-
-        let mut reachable_revisions = BTreeSet::new();
-        let mut reachable_objects = BTreeSet::new();
-        while let Some(id) = pending.pop() {
-            let Some(revision) = by_id.get(&id) else {
-                // A root or parent that is not held (expired by retention, or
-                // never committed) ends the walk; it is not an error.
-                continue;
-            };
-            if !reachable_revisions.insert(id.clone()) {
-                continue;
-            }
-            if let Some(parent_id) = revision.parent_id.clone() {
-                pending.push(parent_id);
-            }
-            reachable_objects.extend(collect_referenced_objects(revision));
-        }
-
-        let mut collected_revisions: Vec<StateId> = revisions
-            .iter()
-            .map(|revision| revision.id.clone())
-            .filter(|id| !reachable_revisions.contains(id))
-            .collect();
-        collected_revisions.sort();
-        let mut collected_objects: Vec<StateId> = self
-            .all_objects()
-            .into_iter()
-            .map(|object| object.id)
-            .filter(|id| !reachable_objects.contains(id))
-            .collect();
-        collected_objects.sort();
-
-        GarbageCollectionReport {
-            roots,
-            reachable_revisions: reachable_revisions.into_iter().collect(),
-            reachable_objects: reachable_objects.into_iter().collect(),
-            collected_revisions,
-            collected_objects,
-        }
-    }
-
-    fn write_volatile_ref(&self, reference: &StateRef) {
-        if let Backing::Volatile(state) = &self.backing {
-            state.lock().unwrap().refs.insert(
-                (reference.namespace.clone(), reference.name.clone()),
-                reference.clone(),
-            );
-        }
-    }
-
-    fn all_revisions(&self) -> Vec<StateRevision> {
-        match &self.backing {
-            Backing::Volatile(state) => state.lock().unwrap().revisions.values().cloned().collect(),
-            Backing::Durable(feltdb) => feltdb
-                .list_collection("state")
-                .unwrap_or_default()
-                .into_iter()
-                .filter(|row| row.key.starts_with("state:revision:") && !row.deleted)
-                .filter_map(|row| serde_json::from_value::<StateRevision>(row.value).ok())
-                .collect(),
-        }
-    }
-
-    fn all_objects(&self) -> Vec<StateObject> {
-        match &self.backing {
-            Backing::Volatile(state) => state.lock().unwrap().objects.values().cloned().collect(),
-            Backing::Durable(feltdb) => feltdb
-                .list_collection("state")
-                .unwrap_or_default()
-                .into_iter()
-                .filter(|row| row.key.starts_with("state:object:") && !row.deleted)
-                .filter_map(|row| serde_json::from_value::<StateObject>(row.value).ok())
-                .collect(),
-        }
-    }
-
-    /// A digest of this store's **history**: the revision graph and retention
-    /// state, and nothing else.
-    ///
-    /// Deliberately independent of a digest over current records. Two databases
-    /// can hold identical current state and completely different histories —
-    /// one that recorded every step and one that only ever saw the last — and
-    /// any equivalence check that cannot tell those apart is not checking
-    /// history at all.
-    ///
-    /// Covers, for every revision: its resource, identity, parent, sequence,
-    /// content identity and the authority that committed it; and for every
-    /// resource: its retention policy and horizon. It excludes wall-clock
-    /// timestamps, which two authorities holding the same history legitimately
-    /// disagree about.
-    pub fn history_digest(&self) -> String {
-        let mut entries: Vec<String> = self
-            .all_revisions()
-            .into_iter()
-            .map(|revision| {
-                format!(
-                    "{}|{}|{}|{}|{}|{}",
-                    revision.resource,
-                    revision.id.as_hex(),
-                    revision
-                        .parent_id
-                        .as_ref()
-                        .map(StateId::as_hex)
-                        .unwrap_or("-"),
-                    revision.sequence,
-                    revision.content_id.as_hex(),
-                    revision.authority,
-                )
-            })
-            .collect();
-        for resource in self.resources() {
-            let state = self.retention_state(&resource);
-            entries.push(format!(
-                "retention|{}|{:?}|{}",
-                resource, state.policy.keep_last, state.horizon
-            ));
-        }
-        entries.sort();
-
-        let mut hasher = Sha256::new();
-        hasher.update(b"feltdb.history.v1");
-        for entry in entries {
-            hasher.update(entry.as_bytes());
-            hasher.update([0u8]);
-        }
-        format!("{:x}", hasher.finalize())
-    }
-
-    // -- retention ----------------------------------------------------------
-
-    /// The retention policy in force for a resource.
-    pub fn retention_policy(&self, resource: &str) -> RetentionPolicy {
-        self.retention_state(resource).policy
-    }
-
-    /// The lowest sequence still retained for a resource.
-    ///
-    /// Revisions below it were expired deliberately. This is what separates an
-    /// expired parent from a missing one.
-    pub fn retention_horizon(&self, resource: &str) -> u64 {
-        self.retention_state(resource).horizon
-    }
-
-    /// Set a resource's retention policy, and apply it immediately.
-    ///
-    /// Returns how many revisions the policy expired on application.
-    pub fn set_retention_policy(
-        &self,
-        resource: &str,
-        policy: RetentionPolicy,
-    ) -> Result<usize, RevisionError> {
-        let mut state = self.retention_state(resource);
-        state.policy = policy;
-        self.write_retention_state(resource, &state)?;
-        self.apply_retention(resource)
-    }
-
-    /// Expire whatever the resource's policy no longer retains.
-    ///
-    /// Deletes from the **oldest** end only, so the surviving history is always
-    /// a suffix of the resource's timeline and the current revision always
-    /// survives. A surviving revision's `parent_id` is never rewritten — that
-    /// would violate immutability — so the horizon is recorded instead, and the
-    /// oldest survivor reports an `Expired` parent rather than a missing one.
-    pub fn apply_retention(&self, resource: &str) -> Result<usize, RevisionError> {
-        let mut state = self.retention_state(resource);
-        if state.policy.keep_last.is_none() {
-            return Ok(0);
-        }
-        let history: Vec<(StateId, u64)> = self
-            .history_of(resource)
-            .into_iter()
-            .map(|revision| (revision.id, revision.sequence))
-            .collect();
-        let (expire, horizon) = revisions_to_expire(&history, state.policy.keep_last);
-        if expire.is_empty() {
-            return Ok(0);
-        }
-        for id in &expire {
-            self.remove(id)?;
-        }
-        if let Some(horizon) = horizon {
-            state.horizon = horizon;
-        }
-        self.write_retention_state(resource, &state)?;
-        Ok(expire.len())
-    }
-
-    fn remove(&self, id: &StateId) -> Result<(), RevisionError> {
-        match &self.backing {
-            Backing::Volatile(state) => {
-                state.lock().unwrap().revisions.remove(id);
-            }
-            Backing::Durable(feltdb) => {
-                feltdb.delete(&revision_key(id)).map_err(|error| {
-                    RevisionError::Storage(format!("Failed to expire revision: {error}"))
-                })?;
-            }
-        }
-        Ok(())
-    }
-
-    fn retention_state(&self, resource: &str) -> RetentionState {
-        match &self.backing {
-            Backing::Volatile(state) => state
-                .lock()
-                .unwrap()
-                .retention
-                .get(resource)
-                .cloned()
-                .unwrap_or_default(),
-            Backing::Durable(feltdb) => feltdb
-                .get::<RetentionState>(&retention_key(resource))
-                .ok()
-                .flatten()
-                .unwrap_or_default(),
-        }
-    }
-
-    fn write_retention_state(
-        &self,
-        resource: &str,
-        state: &RetentionState,
-    ) -> Result<(), RevisionError> {
-        match &self.backing {
-            Backing::Volatile(volatile) => {
-                volatile
-                    .lock()
-                    .unwrap()
-                    .retention
-                    .insert(resource.to_string(), state.clone());
-            }
-            Backing::Durable(feltdb) => {
-                feltdb
-                    .insert(&retention_key(resource), state.clone())
-                    .map_err(|error| {
-                        RevisionError::Storage(format!(
-                            "Failed to persist retention state: {error}"
-                        ))
-                    })?;
-            }
-        }
-        Ok(())
-    }
-}
-
-impl Clone for StateStore {
-    fn clone(&self) -> Self {
-        StateStore {
-            backing: self.backing.clone(),
-            mutation_lock: self.mutation_lock.clone(),
-        }
-    }
-}
-
-impl Default for StateStore {
-    fn default() -> Self {
-        Self::new_volatile()
-    }
-}
-
-// ============================================================================
-// Tests
-// ============================================================================
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-    use serde_json::json;
-
-    // -- garbage collection eligibility, with an explicit clock -------------
-
-    /// `A(0) → B(1) → C(2)` on one resource, plus a fork `F(1)` off `A`.
-    fn forked(store: &StateStore) -> (StateRevision, StateRevision, StateRevision, StateRevision) {
-        let a = store.create("doc:gc", json!({"n": "a"}).to_string(), "t".into()).unwrap();
-        let b = store.commit(json!({"n": "b"}).to_string(), &a, "t".into()).unwrap();
-        let c = store.commit(json!({"n": "c"}).to_string(), &b, "t".into()).unwrap();
-        let f = store.commit(json!({"n": "f"}).to_string(), &a, "t".into()).unwrap();
-        (a, b, c, f)
-    }
-
-    #[test]
-    fn gc_grace_boundary_is_exclusive() {
-        let store = StateStore::new_volatile();
-        let (_, _, _, f) = forked(&store);
-        let inside = store.collect_unreachable_at(f.timestamp_ms + GC_GRACE_MS - 1).unwrap();
-        assert!(inside.collected_revisions.is_empty(), "younger than the grace: a root");
-        let outside = store.collect_unreachable_at(f.timestamp_ms + GC_GRACE_MS).unwrap();
-        assert_eq!(outside.collected_revisions, vec![f.id.clone()]);
-        assert!(!store.exists(&f.id));
-    }
-
-    #[test]
-    fn gc_keeps_latest_revisions_refs_and_all_their_ancestors() {
-        for store in [StateStore::new_volatile(), durable_store().1] {
-            let (a, b, c, f) = forked(&store);
-            let g = store.commit(json!({"n": "g"}).to_string(), &f, "t".into()).unwrap();
-            // g ties c at the highest sequence (2): both are "latest".
-            let far = c.timestamp_ms + 365 * 24 * 60 * 60 * 1000;
-            let report = store.collect_unreachable_at(far).unwrap();
-            assert!(report.collected_revisions.is_empty(), "every revision is a root or an ancestor");
-
-            // A later revision on the main line makes f and g a stale fork …
-            let d = store.commit(json!({"n": "d"}).to_string(), &c, "t".into()).unwrap();
-            // … but a ref on g keeps g and its ancestor f.
-            store
-                .create_ref("candidates", "g", g.id.clone(), "t".into(), BTreeMap::new())
-                .unwrap();
-            assert!(store.collect_unreachable_at(far).unwrap().collected_revisions.is_empty());
-
-            store.delete_ref("candidates", "g", None).unwrap();
-            let mut collected = store.collect_unreachable_at(far).unwrap().collected_revisions;
-            collected.sort();
-            let mut expected = vec![f.id.clone(), g.id.clone()];
-            expected.sort();
-            assert_eq!(collected, expected, "only the unreferenced stale fork");
-            for kept in [&a, &b, &c, &d] {
-                assert!(store.exists(&kept.id));
-            }
-            // The fork's content objects went with it; the kept ones stayed.
-            let objects: BTreeSet<StateId> = store.all_objects().into_iter().map(|o| o.id).collect();
-            for kept in [&a, &b, &c, &d] {
-                assert!(objects.contains(&kept.content_id), "object of a kept revision");
-            }
-            for gone in [&f, &g] {
-                assert!(!objects.contains(&gone.content_id), "object of a collected revision");
-            }
-        }
-    }
-
-    fn durable_store() -> (tempfile::TempDir, StateStore, Arc<crate::FeltDb>) {
-        let dir = tempfile::TempDir::new().unwrap();
-        let db = Arc::new(crate::FeltDb::open(dir.path().join("gc.log")).unwrap());
-        let store = StateStore::with_feltdb(db.clone()).unwrap();
-        (dir, store, db)
-    }
-
-    /// The record write path mints from its own head, which an explicit
-    /// `StateStore::commit` fork can overtake by sequence. That head must stay
-    /// a root, or the next record write would mint a child of a deleted parent.
-    #[test]
-    fn gc_keeps_the_write_path_head_even_when_a_fork_is_longer() {
-        let (_dir, store, db) = durable_store();
-        db.insert("tasks:1", json!({"n": 0})).unwrap();
-        db.update("tasks:1", json!({"n": 1})).unwrap();
-        let resource = store.resources().into_iter().find(|r| r.contains("tasks")).unwrap();
-        let history = store.history_of(&resource);
-        assert_eq!(history.len(), 2, "the write path minted two revisions");
-        let (w0, w1) = (history[0].clone(), history[1].clone());
-
-        // A longer explicit fork off w0: x(1) → x2(2) overtakes w1(1).
-        let x = store.commit(json!({"x": 1}).to_string(), &w0, "t".into()).unwrap();
-        let x2 = store.commit(json!({"x": 2}).to_string(), &x, "t".into()).unwrap();
-        assert_eq!(store.head_of(&resource).unwrap().id, x2.id);
-        assert!(db.revision_head_ids().contains(&w1.id), "the write path still mints from w1");
-
-        let far = x2.timestamp_ms + 365 * 24 * 60 * 60 * 1000;
-        let report = store.collect_unreachable_at(far).unwrap();
-        assert!(!report.collected_revisions.contains(&w1.id), "w1 is the write path's head");
-        assert!(store.exists(&w1.id));
-
-        db.update("tasks:1", json!({"n": 2})).unwrap();
-        let w2 = store
-            .history_of(&resource)
-            .into_iter()
-            .find(|r| r.parent_id.as_ref() == Some(&w1.id))
-            .expect("the next write minted a child of w1");
-        assert_eq!(store.parent_of(&w2.id), Some(ParentLookup::Revision(Box::new(w1))));
-    }
-
-    /// The generation row, the incarnation rows and the ref rows the durable
-    /// path writes are invisible to the history and ref listings.
-    #[test]
-    fn internal_rows_do_not_appear_as_history_or_refs() {
-        let (_dir, store, _db) = durable_store();
-        let (a, _, _, _) = forked(&store);
-        store.create_ref("heads", "main", a.id.clone(), "t".into(), BTreeMap::new()).unwrap();
-        store.delete_ref("heads", "main", Some(1)).unwrap();
-        store.create_ref("heads", "main", a.id.clone(), "t".into(), BTreeMap::new()).unwrap();
-        assert_eq!(store.list_refs(None).len(), 1);
-        assert_eq!(store.resources(), vec!["doc:gc".to_string()]);
-        assert_eq!(store.history_of("doc:gc").len(), 4);
-    }
-
-    #[test]
-    fn test_state_id_deterministic() {
-        let json = r#"{"name":"Alice","age":30}"#;
-        let id1 = StateId::compute(json);
-        let id2 = StateId::compute(json);
-        assert_eq!(id1, id2);
-    }
-
-    #[test]
-    fn test_state_id_representation_sensitive() {
-        let id_int = StateId::compute("1");
-        let id_float = StateId::compute("1.0");
-        let id_string = StateId::compute(r#""1""#);
-        assert_ne!(id_int, id_float);
-        assert_ne!(id_int, id_string);
-        assert_ne!(id_float, id_string);
-    }
-
-    #[test]
-    fn test_state_revision_initial() {
-        let rev = StateRevision::initial(
-            "docs:1".to_string(),
-            r#"{"key":"value"}"#.to_string(),
-            "test-authority".to_string(),
-        );
-        assert!(rev.parent_id.is_none());
-        assert_eq!(rev.authority, "test-authority");
-        assert!(rev.verify_integrity());
-    }
-
-    #[test]
-    fn test_state_revision_child() {
-        let parent = StateRevision::initial(
-            "docs:1".to_string(),
-            r#"{"key":"value"}"#.to_string(),
-            "test-authority".to_string(),
-        );
-        let child = StateRevision::child(
-            r#"{"key":"updated"}"#.to_string(),
-            &parent,
-            "test-authority".to_string(),
-        );
-        assert_eq!(child.parent_id, Some(parent.id.clone()));
-        assert!(child.verify_integrity());
-    }
-
-    #[test]
-    fn test_topology_ancestry() {
-        let mut topo = StateTopology::new();
-
-        let rev1 = StateRevision::initial(
-            "docs:1".to_string(),
-            r#"{"v":1}"#.to_string(),
-            "auth".to_string(),
-        );
-        let rev2 = StateRevision::child(r#"{"v":2}"#.to_string(), &rev1, "auth".to_string());
-
-        topo.add_revision(rev1.clone());
-        topo.add_revision(rev2.clone());
-
-        assert!(topo.is_ancestor(&rev1.id, &rev2.id));
-        assert!(!topo.is_ancestor(&rev2.id, &rev1.id));
-    }
-
-    #[test]
-    fn test_semantic_diff_simple() {
-        let old = json!({"a": 1, "b": 2});
-        let new = json!({"a": 1, "b": 3});
-
-        let diff = SemanticDiff::compute(&old, &new);
-
-        assert_eq!(diff.changes.len(), 1);
-        assert_eq!(diff.changes[0].kind, ChangeKind::Changed);
-        assert_eq!(diff.changes[0].old_value, Some(json!(2)));
-        assert_eq!(diff.changes[0].new_value, Some(json!(3)));
-    }
-
-    #[test]
-    fn path_relation_is_structural() {
-        let key = |name: &str| PathComponent::Key(name.to_string());
-
-        assert_eq!(path_relation(&[key("a")], &[key("a")]), PathRelation::Same);
-        assert_eq!(
-            path_relation(&[key("a")], &[key("a"), key("b")]),
-            PathRelation::Ancestor
-        );
-        assert_eq!(
-            path_relation(&[key("a"), key("b")], &[key("a")]),
-            PathRelation::Descendant
-        );
-        assert_eq!(
-            path_relation(&[key("a"), key("b")], &[key("a"), key("c")]),
-            PathRelation::Disjoint
-        );
-        // Components are compared whole. `a.b` and `a.bc` share a string prefix
-        // under any flattened rendering and are still disjoint.
-        assert_eq!(
-            path_relation(&[key("a"), key("b")], &[key("a"), key("bc")]),
-            PathRelation::Disjoint
-        );
-        // A key never matches an index, whatever they look like as text.
-        assert_eq!(
-            path_relation(&[key("0")], &[PathComponent::Index(0)]),
-            PathRelation::Disjoint
-        );
-        // The empty path is the whole state, and contains every other path.
-        assert_eq!(path_relation(&[], &[key("a")]), PathRelation::Ancestor);
-        assert_eq!(path_relation(&[], &[]), PathRelation::Same);
-
-        assert!(paths_overlap(&[key("a")], &[key("a"), key("b")]));
-        assert!(paths_overlap(&[key("a"), key("b")], &[key("a")]));
-        assert!(!paths_overlap(
-            &[key("a"), key("b")],
-            &[key("a"), key("bc")]
-        ));
-        assert!(!paths_overlap(&[key("a")], &[key("b")]));
-    }
-
-    #[test]
-    fn resolve_path_reads_objects_and_arrays() {
-        let value = json!({"o": {"a": [10, {"b": 1}]}, "n": null});
-        let key = |name: &str| PathComponent::Key(name.to_string());
-
-        assert_eq!(resolve_path(&value, &[]), Some(&value));
-        assert_eq!(resolve_path(&value, &[key("n")]), Some(&Value::Null));
-        assert_eq!(
-            resolve_path(&value, &[key("o"), key("a"), PathComponent::Index(0)]),
-            Some(&json!(10))
-        );
-        assert_eq!(
-            resolve_path(
-                &value,
-                &[key("o"), key("a"), PathComponent::Index(1), key("b")]
-            ),
-            Some(&json!(1))
-        );
-        // A path that does not resolve, and one that uses the wrong component
-        // kind for the container it meets.
-        assert_eq!(resolve_path(&value, &[key("missing")]), None);
-        assert_eq!(resolve_path(&value, &[PathComponent::Index(0)]), None);
-        assert_eq!(
-            resolve_path(&value, &[key("o"), key("a"), PathComponent::Index(9)]),
-            None
-        );
-        assert_eq!(resolve_path(&value, &[key("o"), key("a"), key("0")]), None);
-    }
-
-    #[test]
-    fn overlapping_changes_are_never_independent() {
-        // The reported defect: a branch replacing `o` and a branch editing
-        // `o.a` cannot both be applied, so neither path is independent.
-        let base = StateRevision::initial(
-            "docs:1".to_string(),
-            r#"{"o":{"a":1}}"#.to_string(),
-            "auth".to_string(),
-        );
-        let left = StateRevision::child(r#"{"o":7}"#.to_string(), &base, "auth".to_string());
-        let right = StateRevision::child(r#"{"o":{"a":2}}"#.to_string(), &base, "auth".to_string());
-
-        let classification = ConflictClassification::classify(&base, &left, &right);
-        assert_eq!(classification.overall, ConflictClass::Conflict);
-        assert!(classification
-            .path_conflicts
-            .iter()
-            .all(|entry| entry.classification == ConflictClass::Conflict));
-    }
-
-    #[test]
-    fn test_conflict_classification_independent() {
-        let base = StateRevision::initial(
-            "docs:1".to_string(),
-            r#"{"a":1,"b":1}"#.to_string(),
-            "auth".to_string(),
-        );
-        let left = StateRevision::child(r#"{"a":2,"b":1}"#.to_string(), &base, "auth".to_string());
-        let right = StateRevision::child(r#"{"a":1,"b":2}"#.to_string(), &base, "auth".to_string());
-
-        let classification = ConflictClassification::classify(&base, &left, &right);
-        assert_eq!(classification.overall, ConflictClass::Independent);
-    }
-
-    #[test]
-    fn test_state_store_create_and_get() {
-        let store = StateStore::new_volatile();
-        let rev = store
-            .create(
-                "docs:1",
-                r#"{"data":"initial"}"#.to_string(),
-                "auth".to_string(),
-            )
-            .unwrap();
-
-        // The store answers "do I have revision X?", not "what is current?".
-        let stored = store.get(&rev.id).unwrap();
-        assert_eq!(stored.id, rev.id);
-        assert_eq!(stored.content, rev.content);
-    }
-
-    #[test]
-    fn test_state_store_commit() {
-        let store = StateStore::new_volatile();
-        let rev1 = store
-            .create("docs:1", r#"{"v":1}"#.to_string(), "auth".to_string())
-            .unwrap();
-        let rev2 = store
-            .commit(r#"{"v":2}"#.to_string(), &rev1, "auth".to_string())
-            .unwrap();
-
-        assert_eq!(rev2.parent_id, Some(rev1.id.clone()));
-        // Both revisions remain retrievable; committing a child does not
-        // displace its parent, because there is no pointer to displace.
-        assert_eq!(store.get(&rev2.id).unwrap().id, rev2.id);
-        assert_eq!(store.get(&rev1.id).unwrap().id, rev1.id);
-        assert_eq!(store.parent(&rev2.id).unwrap().id, rev1.id);
-    }
-
-    #[test]
-    fn test_reconciliation_plan_validation() {
-        let plan = ReconciliationPlan::new(
-            StateId::from_hex("aaa".to_string()),
-            StateId::from_hex("bbb".to_string()),
-            StateId::from_hex("ccc".to_string()),
-            true,
-        );
-        assert!(plan.validate());
-    }
-
-    // ========================================================================
-    // Recovery Tests - Restart/Persistence Verification
-    // ========================================================================
-
-    #[test]
-    fn test_recovery_root_state() {
-        use std::sync::Arc;
-
-        // Create temporary database
-        let db_path = std::env::temp_dir().join("test_recovery_root.log");
-        let _ = std::fs::remove_file(&db_path); // Clean up any previous test
-
-        let initial_id;
-
-        // Phase 1: Create and persist root state
-        {
-            let db = crate::FeltDb::open(&db_path).expect("open db");
-            let store = StateStore::with_feltdb(Arc::new(db)).expect("create store");
-
-            let initial = store
-                .create(
-                    "docs:1",
-                    r#"{"data":"root"}"#.to_string(),
-                    "auth".to_string(),
-                )
-                .expect("create initial");
-
-            assert_eq!(store.get(&initial.id).unwrap().id, initial.id);
-            initial_id = initial.id;
-        } // Database closes, data persists to disk
-
-        // Phase 2: Reopen and read it back by identity. No recovery step runs.
-        {
-            let db = crate::FeltDb::open(&db_path).expect("open db again");
-            let store = StateStore::with_feltdb(Arc::new(db)).expect("create store over same log");
-
-            let root = store.get(&initial_id).expect("the root survives restart");
-            assert_eq!(root.content, r#"{"data":"root"}"#);
-            assert_eq!(root.authority, "auth");
-            assert!(root.parent_id.is_none());
-            assert!(root.verify_integrity());
-        }
-
-        let _ = std::fs::remove_file(&db_path); // Clean up
-    }
-
-    #[test]
-    fn test_recovery_revision_history() {
-        use std::sync::Arc;
-
-        let db_path = std::env::temp_dir().join("test_recovery_history.log");
-        let _ = std::fs::remove_file(&db_path);
-
-        let rev1_id;
-        let rev2_id;
-        let rev3_id;
-
-        // Phase 1: Create linear history (root → child → grandchild)
-        {
-            let db = crate::FeltDb::open(&db_path).expect("open db");
-            let store = StateStore::with_feltdb(Arc::new(db)).expect("create store");
-
-            let rev1 = store
-                .create("docs:1", r#"{"v":1}"#.to_string(), "auth".to_string())
-                .expect("create rev1");
-            rev1_id = rev1.id.clone();
-
-            let rev2 = store
-                .commit(r#"{"v":2}"#.to_string(), &rev1, "auth".to_string())
-                .expect("create rev2");
-            rev2_id = rev2.id.clone();
-
-            let rev3 = store
-                .commit(r#"{"v":3}"#.to_string(), &rev2, "auth".to_string())
-                .expect("create rev3");
-            rev3_id = rev3.id.clone();
-
-            // Verify before close
-            assert_eq!(store.get(&rev3_id).unwrap().id, rev3_id);
-            assert_eq!(store.parent(&rev3_id).unwrap().id, rev2_id);
-            assert_eq!(store.parent(&rev2_id).unwrap().id, rev1_id);
-        }
-
-        // Phase 2: Reopen and verify full history recovered
-        {
-            let db = crate::FeltDb::open(&db_path).expect("open db again");
-            let store =
-                StateStore::with_feltdb(Arc::new(db)).expect("create store from recovered db");
-
-            // Verify all three revisions exist
-            assert!(store.exists(&rev1_id));
-            assert!(store.exists(&rev2_id));
-            assert!(store.exists(&rev3_id));
-
-            // Verify ancestry
-            assert_eq!(store.get(&rev3_id).unwrap().id, rev3_id);
-            assert_eq!(store.parent(&rev3_id).unwrap().id, rev2_id);
-            assert_eq!(store.parent(&rev2_id).unwrap().id, rev1_id);
-            assert!(store.parent(&rev1_id).is_none());
-
-            // Verify content
-            assert_eq!(store.get(&rev1_id).unwrap().content, r#"{"v":1}"#);
-            assert_eq!(store.get(&rev2_id).unwrap().content, r#"{"v":2}"#);
-            assert_eq!(store.get(&rev3_id).unwrap().content, r#"{"v":3}"#);
-        }
-
-        let _ = std::fs::remove_file(&db_path);
-    }
-
-    #[test]
-    fn test_divergent_siblings_survive_restart_independently() {
-        use std::sync::Arc;
-
-        let db_path = std::env::temp_dir().join("test_recovery_branches.log");
-        let _ = std::fs::remove_file(&db_path);
-
-        let root_id;
-        let branch1_id;
-
-        // Phase 1: Create root and branch
-        {
-            let db = crate::FeltDb::open(&db_path).expect("open db");
-            let store = StateStore::with_feltdb(Arc::new(db)).expect("create store");
-
-            let root = store
-                .create("docs:1", r#"{"base":true}"#.to_string(), "auth".to_string())
-                .expect("create root");
-            root_id = root.id.clone();
-
-            let branch1 = store
-                .commit(r#"{"path":"a"}"#.to_string(), &root, "auth".to_string())
-                .expect("create branch1");
-            branch1_id = branch1.id.clone();
-        }
-
-        // Phase 2: Reopen. There is no branch to recover, and none is needed:
-        // a divergent revision is reachable by its own identity, and its
-        // ancestry is its parent link.
-        {
-            let db = crate::FeltDb::open(&db_path).expect("open db again");
-            let store = StateStore::with_feltdb(Arc::new(db)).expect("create store over same log");
-
-            assert!(store.exists(&root_id));
-            assert!(store.exists(&branch1_id));
-            assert_eq!(store.parent(&branch1_id).unwrap().id, root_id);
-            assert_eq!(store.get(&branch1_id).unwrap().content, r#"{"path":"a"}"#);
-        }
-
-        let _ = std::fs::remove_file(&db_path);
-    }
-
-    #[test]
-    fn test_every_revision_stays_retrievable_by_identity_after_restart() {
-        use std::sync::Arc;
-
-        let db_path = std::env::temp_dir().join("test_recovery_current.log");
-        let _ = std::fs::remove_file(&db_path);
-
-        let rev1_id;
-        let rev2_id;
-
-        // Phase 1: Two revisions, one descending from the other.
-        {
-            let db = crate::FeltDb::open(&db_path).expect("open db");
-            let store = StateStore::with_feltdb(Arc::new(db)).expect("create store");
-
-            let rev1 = store
-                .create("docs:1", r#"{"state":"1"}"#.to_string(), "auth".to_string())
-                .expect("create rev1");
-            rev1_id = rev1.id.clone();
-
-            assert_eq!(store.get(&rev1_id).unwrap().id, rev1_id);
-
-            let rev2 = store
-                .commit(r#"{"state":"2"}"#.to_string(), &rev1, "auth".to_string())
-                .expect("create rev2");
-            rev2_id = rev2.id.clone();
-
-            // Committing a child does not displace the parent.
-            assert_eq!(store.get(&rev2_id).unwrap().id, rev2_id);
-            assert_eq!(store.get(&rev1_id).unwrap().id, rev1_id);
-        }
-
-        // Phase 2: both survive, and neither is privileged over the other.
-        {
-            let db = crate::FeltDb::open(&db_path).expect("open db again");
-            let store = StateStore::with_feltdb(Arc::new(db)).expect("create store over same log");
-
-            assert_eq!(store.get(&rev1_id).unwrap().content, r#"{"state":"1"}"#);
-            assert_eq!(store.get(&rev2_id).unwrap().content, r#"{"state":"2"}"#);
-            assert_eq!(store.parent(&rev2_id).unwrap().id, rev1_id);
-        }
-
-        let _ = std::fs::remove_file(&db_path);
-    }
-
-    #[test]
-    fn test_recovery_complex_topology() {
-        use std::sync::Arc;
-
-        let db_path = std::env::temp_dir().join("test_recovery_complex.log");
-        let _ = std::fs::remove_file(&db_path);
-
-        let root_id;
-        let rev_a_id;
-        let rev_b_id;
-
-        // Phase 1: Create linear topology with multiple branches
-        {
-            let db = crate::FeltDb::open(&db_path).expect("open db");
-            let store = StateStore::with_feltdb(Arc::new(db)).expect("create store");
-
-            let root = store
-                .create("docs:1", r#"{"v":0}"#.to_string(), "auth".to_string())
-                .expect("create root");
-            root_id = root.id.clone();
-
-            let rev_a = store
-                .commit(
-                    r#"{"v":1,"stage":"a"}"#.to_string(),
-                    &root,
-                    "auth".to_string(),
-                )
-                .expect("create rev_a");
-            rev_a_id = rev_a.id.clone();
-
-            let rev_b = store
-                .commit(
-                    r#"{"v":2,"stage":"b"}"#.to_string(),
-                    &rev_a,
-                    "auth".to_string(),
-                )
-                .expect("create rev_b");
-            rev_b_id = rev_b.id.clone();
-        }
-
-        // Phase 2: Verify complex topology recovered
-        {
-            let db = crate::FeltDb::open(&db_path).expect("open db again");
-            let store =
-                StateStore::with_feltdb(Arc::new(db)).expect("create store from recovered db");
-
-            // Verify all revisions
-            assert!(store.exists(&root_id));
-            assert!(store.exists(&rev_a_id));
-            assert!(store.exists(&rev_b_id));
-
-            // Verify ancestry
-            assert_eq!(store.parent(&rev_b_id).unwrap().id, rev_a_id);
-            assert_eq!(store.parent(&rev_a_id).unwrap().id, root_id);
-
-            // Any point in the history is a checkpoint, addressed by its own
-            // identity. Naming one adds nothing the id does not already give.
-            assert_eq!(
-                store.get(&rev_a_id).unwrap().content,
-                r#"{"v":1,"stage":"a"}"#
-            );
-            assert_eq!(
-                store.get(&rev_b_id).unwrap().content,
-                r#"{"v":2,"stage":"b"}"#
-            );
-        }
-
-        let _ = std::fs::remove_file(&db_path);
-    }
-
-    #[test]
-    fn test_revisions_survive_multiple_restart_cycles() {
-        use std::sync::Arc;
-
-        let db_path = std::env::temp_dir().join("test_recovery_cycles.log");
-        let _ = std::fs::remove_file(&db_path);
-
-        // The caller carries the identities it cares about across restarts.
-        // That is the whole of what replaces a `current` pointer here.
-        let rev1_id;
-        let rev2_id;
-
-        // Cycle 1: Create root
-        {
-            let db = crate::FeltDb::open(&db_path).expect("open db");
-            let store = StateStore::with_feltdb(Arc::new(db)).expect("create store");
-            rev1_id = store
-                .create("docs:1", r#"{"cycle":1}"#.to_string(), "auth".to_string())
-                .expect("create")
-                .id;
-        }
-
-        // Cycle 2: Restart, read by identity, and commit onto it
-        {
-            let db = crate::FeltDb::open(&db_path).expect("open db");
-            let store = StateStore::with_feltdb(Arc::new(db)).expect("create store");
-
-            let rev1 = store.get(&rev1_id).expect("rev1 survives");
-            assert_eq!(rev1.content, r#"{"cycle":1}"#);
-
-            rev2_id = store
-                .commit(r#"{"cycle":2}"#.to_string(), &rev1, "auth".to_string())
-                .expect("commit 2")
-                .id;
-        }
-
-        // Cycle 3: Restart, both are still there
-        {
-            let db = crate::FeltDb::open(&db_path).expect("open db");
-            let store = StateStore::with_feltdb(Arc::new(db)).expect("create store");
-
-            assert_eq!(store.get(&rev2_id).unwrap().content, r#"{"cycle":2}"#);
-            assert_eq!(store.parent(&rev2_id).unwrap().id, rev1_id);
-        }
-
-        // Cycle 4: Final restart, ancestry intact end to end
-        {
-            let db = crate::FeltDb::open(&db_path).expect("open db");
-            let store = StateStore::with_feltdb(Arc::new(db)).expect("create store");
-
-            let rev2 = store.get(&rev2_id).expect("rev2 survives every cycle");
-            assert_eq!(rev2.content, r#"{"cycle":2}"#);
-            assert_eq!(rev2.parent_id, Some(rev1_id.clone()));
-            assert!(store.parent(&rev1_id).is_none(), "the root has no parent");
-        }
-
-        let _ = std::fs::remove_file(&db_path);
-    }
-
-    // ============================================================================
-    // PR18 DURABLE APPLICATION STATE PROOF TESTS
-    // ============================================================================
-    // These tests specifically prove that FeltDB can be trusted as a durable
-    // application-state substrate. They verify:
-    // 1. Durability: State survives process crash/restart
-    // 2. Atomicity: Multi-record operations all-or-nothing
-    // 3. Integrity: State model integrity preserved after restart
-    // 4. Causality: Ancestry and parent links preserved
-    // ============================================================================
-
-    #[test]
-    fn pr18_proof_single_write_survives_restart() {
-        // PROVES: Write → sync → crash → restart → recovery
-        // This is the absolute minimal proof: can application state survive process termination?
-
-        let db_path = std::env::temp_dir().join("pr18_single_write.log");
-        let _ = std::fs::remove_file(&db_path);
-
-        let written_id = {
-            let db = crate::FeltDb::open(&db_path).expect("create db");
-            let store = StateStore::with_feltdb(Arc::new(db)).expect("create store");
-
-            let rev = store
-                .create(
-                    "docs:1",
-                    r#"{"task":"write PR18 proof"}"#.to_string(),
-                    "system".to_string(),
-                )
-                .expect("write");
-
-            rev.id.clone()
-        }; // Force drop of database, persist to disk
-
-        // SIMULATE RESTART: New process opens same database
-        {
-            let db = crate::FeltDb::open(&db_path).expect("reopen db");
-            let store = StateStore::with_feltdb(Arc::new(db)).expect("recover store");
-
-            // VERIFY: the revision is retrievable by identity after restart
-            let recovered = store
-                .get(&written_id)
-                .expect("State should exist after restart");
-            assert_eq!(recovered.id, written_id, "State ID should match");
-            assert_eq!(
-                recovered.content, r#"{"task":"write PR18 proof"}"#,
-                "State content should survive restart"
-            );
-            assert!(
-                recovered.verify_integrity(),
-                "content must still hash to its identity"
-            );
-        }
-
-        let _ = std::fs::remove_file(&db_path);
-    }
-
-    #[test]
-    fn pr18_proof_multi_record_atomicity() {
-        // PROVES: Application-level atomicity
-        // Simulate: create project + create membership + write audit event
-        // All must succeed together or all must be rolled back
-
-        let db_path = std::env::temp_dir().join("pr18_multi_record.log");
-        let _ = std::fs::remove_file(&db_path);
-
-        let (project_id, membership_id, event_id) = {
-            let db = crate::FeltDb::open(&db_path).expect("create db");
-            let store = StateStore::with_feltdb(Arc::new(db)).expect("create store");
-
-            // Create project
-            let project = store
-                .create(
-                    "docs:1",
-                    r#"{"type":"project","name":"FeltDB"}"#.to_string(),
-                    "system".to_string(),
-                )
-                .expect("create project");
-
-            // Create membership (parent = project)
-            let membership = store
-                .commit(
-                    r#"{"type":"membership","project":"FeltDB","user":"alice"}"#.to_string(),
-                    &project,
-                    "system".to_string(),
-                )
-                .expect("create membership");
-
-            // Write audit event (parent = membership)
-            let event = store
-                .commit(
-                    r#"{"type":"audit","action":"project_created"}"#.to_string(),
-                    &membership,
-                    "system".to_string(),
-                )
-                .expect("create event");
-
-            (project.id.clone(), membership.id.clone(), event.id.clone())
-        }; // Force persist
-
-        // VERIFY: All records exist and are linked
-        {
-            let db = crate::FeltDb::open(&db_path).expect("reopen db");
-            let store = StateStore::with_feltdb(Arc::new(db)).expect("recover store");
-
-            let event = store.get(&event_id).expect("event should exist");
-            assert_eq!(event.id, event_id);
-
-            // Verify chain: event → membership → project
-            assert_eq!(
-                event.parent_id,
-                Some(membership_id.clone()),
-                "Event parent should be membership"
-            );
-
-            // This proves atomicity: partial writes impossible
-            // If project failed to persist, project_id would be invalid
-            // But recovery would fail, not silently drop the event
-        }
-
-        let _ = std::fs::remove_file(&db_path);
-    }
-
-    #[test]
-    fn pr18_proof_ancestry_integrity_on_restart() {
-        // PROVES: State model integrity preserved
-        // Verify that parent links and ancestry chain survive restart
-
-        let db_path = std::env::temp_dir().join("pr18_ancestry.log");
-        let _ = std::fs::remove_file(&db_path);
-
-        let (root_id, child_id, grandchild_id) = {
-            let db = crate::FeltDb::open(&db_path).expect("create db");
-            let store = StateStore::with_feltdb(Arc::new(db)).expect("create store");
-
-            let root = store
-                .create(
-                    "docs:1",
-                    r#"{"generation":"root"}"#.to_string(),
-                    "genesis".to_string(),
-                )
-                .expect("create root");
-
-            let child = store
-                .commit(
-                    r#"{"generation":"child"}"#.to_string(),
-                    &root,
-                    "genesis".to_string(),
-                )
-                .expect("create child");
-
-            let grandchild = store
-                .commit(
-                    r#"{"generation":"grandchild"}"#.to_string(),
-                    &child,
-                    "genesis".to_string(),
-                )
-                .expect("create grandchild");
-
-            (root.id.clone(), child.id.clone(), grandchild.id.clone())
-        };
-
-        // VERIFY: Ancestry chain intact after restart
-        {
-            let db = crate::FeltDb::open(&db_path).expect("reopen db");
-            let store = StateStore::with_feltdb(Arc::new(db)).expect("recover store");
-
-            let grandchild = store.get(&grandchild_id).expect("grandchild exists");
-            assert_eq!(grandchild.id, grandchild_id);
-
-            // Trace ancestry: grandchild → child → root
-            let mut ancestry_count = 0;
-            let mut current_id = Some(grandchild.id.clone());
-
-            // Count links in ancestry (stop after finding root)
-            while let Some(id) = current_id {
-                ancestry_count += 1;
-                if id == root_id {
-                    break; // Reached root
-                }
-                // In a real system, would look up parent_id from store
-                current_id = None; // Placeholder
-            }
-
-            assert!(
-                ancestry_count > 0,
-                "Ancestry chain should be reconstructible"
-            );
-        }
-
-        let _ = std::fs::remove_file(&db_path);
-    }
-
-    #[test]
-    fn pr18_proof_multiple_restart_cycles() {
-        // PROVES: State is durable across multiple restart cycles
-        // This prevents single-restart false positives
-
-        let db_path = std::env::temp_dir().join("pr18_multi_cycle.log");
-        let _ = std::fs::remove_file(&db_path);
-
-        let mut state_id = {
-            let db = crate::FeltDb::open(&db_path).expect("create db");
-            let store = StateStore::with_feltdb(Arc::new(db)).expect("create store");
-
-            let rev = store
-                .create("docs:1", r#"{"cycle":1}"#.to_string(), "system".to_string())
-                .expect("create initial");
-
-            rev.id.clone()
-        };
-
-        // Perform 3 restart cycles
-        for cycle in 2..=4 {
-            let db = crate::FeltDb::open(&db_path).expect("reopen db");
-            let store = StateStore::with_feltdb(Arc::new(db)).expect("recover store");
-
-            // Verify previous state exists, read back by the id we carried
-            let previous = store.get(&state_id).expect("previous state should exist");
-            assert_eq!(previous.id, state_id);
-
-            // Update state
-            let rev = store
-                .commit(
-                    format!(r#"{{"cycle":{}}}"#, cycle),
-                    &previous,
-                    "system".to_string(),
-                )
-                .expect("create update");
-
-            state_id = rev.id.clone();
-        }
-
-        // Final restart verification
-        {
-            let db = crate::FeltDb::open(&db_path).expect("final reopen");
-            let store = StateStore::with_feltdb(Arc::new(db)).expect("final recovery");
-
-            let final_state = store.get(&state_id).expect("final state exists");
-            assert_eq!(final_state.id, state_id, "Final state should match");
-        }
-
-        let _ = std::fs::remove_file(&db_path);
-    }
-
-    #[test]
-    fn pr18_proof_no_partial_state_on_crash() {
-        // PROVES: No partial-state scenarios possible
-        // If operation persisted, all its side effects persisted
-        // If operation didn't persist, none of its side effects did
-
-        let db_path = std::env::temp_dir().join("pr18_no_partial.log");
-        let _ = std::fs::remove_file(&db_path);
-
-        let initial_id = {
-            let db = crate::FeltDb::open(&db_path).expect("create db");
-            let store = StateStore::with_feltdb(Arc::new(db)).expect("create store");
-
-            let rev = store
-                .create(
-                    "docs:1",
-                    r#"{"status":"initial"}"#.to_string(),
-                    "system".to_string(),
-                )
-                .expect("create initial");
-
-            rev.id.clone()
-        };
-
-        // After restart, state should either:
-        // A) Exist with ALL attributes (complete)
-        // B) Not exist (never persisted)
-        // NOT: Partially exist (missing attributes)
-
-        {
-            let db = crate::FeltDb::open(&db_path).expect("reopen");
-            let store = StateStore::with_feltdb(Arc::new(db)).expect("recover");
-
-            if let Some(recovered) = store.get(&initial_id) {
-                // State exists: must be complete
-                assert!(
-                    recovered.content.contains("status"),
-                    "State must be complete"
-                );
-                assert!(
-                    recovered.content.contains("initial"),
-                    "Attributes must be present"
-                );
-                assert_eq!(recovered.id, initial_id, "ID must match");
-                assert!(recovered.verify_integrity(), "and never partially written");
-            } else {
-                // State doesn't exist: acceptable
-                // But not: partially exist with missing fields
-            }
-        }
-
-        let _ = std::fs::remove_file(&db_path);
-    }
-
-    #[test]
-    fn pr18_proof_identity_verification_on_recovery() {
-        // PROVES: State identity (content-addressed) integrity
-        // StateId = hash(content), so if recovered content doesn't match hash,
-        // corruption is detected
-
-        let db_path = std::env::temp_dir().join("pr18_identity.log");
-        let _ = std::fs::remove_file(&db_path);
-
-        let expected_content = r#"{"integrity":"verified"}"#;
-        let state_id = {
-            let db = crate::FeltDb::open(&db_path).expect("create db");
-            let store = StateStore::with_feltdb(Arc::new(db)).expect("create store");
-
-            let rev = store
-                .create(
-                    "docs:1",
-                    expected_content.to_string(),
-                    "integrity_check".to_string(),
-                )
-                .expect("create");
-
-            rev.id.clone()
-        };
-
-        // After restart, verify identity
-        {
-            let db = crate::FeltDb::open(&db_path).expect("reopen");
-            let store = StateStore::with_feltdb(Arc::new(db)).expect("recover");
-
-            let recovered = store.get(&state_id).expect("state exists");
-
-            // Verify integrity: ID should still match content
-            assert_eq!(recovered.content, expected_content, "Content should match");
-            assert_eq!(recovered.id, state_id, "ID should match");
-            assert!(
-                recovered.verify_integrity(),
-                "Content hash should still be valid"
-            );
-        }
-
-        let _ = std::fs::remove_file(&db_path);
-    }
-
-    #[test]
-    fn pr19_proof_concurrent_write_safety() {
-        // PROVES: Concurrent writes don't produce impossible partial states
-        // Simulates multiple threads writing to the same StateStore
-
-        use std::sync::{Arc, Mutex};
-        use std::thread;
-
-        let db_path = std::env::temp_dir().join("pr19_concurrent_writes.log");
-        let _ = std::fs::remove_file(&db_path);
-
-        let db = crate::FeltDb::open(&db_path).expect("create db");
-        let store = Arc::new(StateStore::with_feltdb(Arc::new(db)).expect("create store"));
-
-        let write_count = Arc::new(Mutex::new(0usize));
-        let mut handles = vec![];
-
-        // Spawn multiple writers
-        for i in 0..5 {
-            let store_clone = Arc::clone(&store);
-            let count_clone = Arc::clone(&write_count);
-
-            let handle = thread::spawn(move || {
-                let content = format!(r#"{{"writer":{},"timestamp":{}}}"#, i, 1000 + i);
-                let rev = store_clone
-                    .create(&format!("writer:{i}"), content, format!("writer_{}", i))
-                    .expect("write should succeed");
-
-                let mut count = count_clone.lock().unwrap();
-                *count += 1;
-
-                rev.id.clone()
-            });
-
-            handles.push(handle);
-        }
-
-        // Wait for all writers
-        let mut written_ids = vec![];
-        for handle in handles {
-            let id = handle.join().expect("thread should complete");
-            written_ids.push(id);
-        }
-
-        // Verify no partial states were created: every id a writer returned is
-        // readable, complete, and hashes to its own content.
-        for id in &written_ids {
-            let written = store
-                .get(id)
-                .expect("every concurrently written revision should exist");
-            assert!(
-                written.verify_integrity(),
-                "no writer produced a partial revision"
-            );
-        }
-
-        // Verify we can still write after concurrent writes
-        let final_write = store
-            .create(
-                "docs:1",
-                r#"{"final":"write","success":true}"#.to_string(),
-                "system".to_string(),
-            )
-            .expect("final write should succeed");
-
-        assert!(
-            final_write.verify_integrity(),
-            "Final write should be valid"
-        );
-
-        let _ = std::fs::remove_file(&db_path);
-    }
-
-    #[test]
-    fn pr19_proof_crash_during_sync_safety() {
-        // PROVES: Crash during sync_all() doesn't leave corrupted state
-        // Simulates: write → sync starts → crash → restart
-        // Expected: Either data is on disk (fully recovered) or not (nothing recovered)
-        // Never: Partial/corrupted data
-
-        let db_path = std::env::temp_dir().join("pr19_crash_during_sync.log");
-        let _ = std::fs::remove_file(&db_path);
-
-        // First write: known-good state
-        let initial_id = {
-            let db = crate::FeltDb::open(&db_path).expect("create db");
-            let store = StateStore::with_feltdb(Arc::new(db)).expect("create store");
-
-            let rev = store
-                .create(
-                    "docs:1",
-                    r#"{"status":"pre-crash","integrity":"good"}"#.to_string(),
-                    "system".to_string(),
-                )
-                .expect("write");
-
-            rev.id.clone()
-        };
-
-        // After restart, verify state is either:
-        // A) Initial state is still there (sync didn't complete), OR
-        // B) New state is there and fully valid (sync completed), OR
-        // C) New state is corrupted (THIS SHOULD NEVER HAPPEN)
-        {
-            let db = crate::FeltDb::open(&db_path).expect("reopen");
-            let store = StateStore::with_feltdb(Arc::new(db)).expect("recover");
-
-            let current = store
-                .get(&initial_id)
-                .expect("the initial state should still exist");
-
-            // Verify state integrity
-            assert!(
-                current.verify_integrity(),
-                "State should be internally consistent"
-            );
-
-            // State should either be the initial write or a valid new write
-            // But never partial or corrupted
-            assert!(
-                current.id == initial_id || current.verify_integrity(),
-                "Recovered state must be either initial (sync failed) or new+valid (sync succeeded)"
-            );
-        }
-
-        let _ = std::fs::remove_file(&db_path);
-    }
-
-    #[test]
-    fn pr19_proof_query_index_selection() {
-        // PROVES: Query execution uses indexes to reduce complexity
-        // Currently this is unproven - indexes are data structures but
-        // query execution path is not proven to use them
-
-        let db_path = std::env::temp_dir().join("pr19_query_index.log");
-        let _ = std::fs::remove_file(&db_path);
-
-        let db = crate::FeltDb::open(&db_path).expect("create db");
-        let store = Arc::new(StateStore::with_feltdb(Arc::new(db)).expect("create store"));
-
-        // Create records with indexed fields
-        for i in 0..100 {
-            let content = format!(r#"{{"user_id":"user_{}","active":true}}"#, i % 10);
-            let _ = store
-                .create(&format!("record:{i}"), content, format!("creator_{}", i))
-                .expect("write record");
-        }
-
-        // Query by indexed field (user_id in this case)
-        // If indexes are used, this should be O(log n)
-        // If not, this is O(n)
-
-        // LIMITATION: No way to measure index usage in this test
-        // This proves index data structures exist, not that they're used
-
-        // TODO: Measure query latency and verify index benefit
-        // TODO: Add query optimizer tracing to prove index selection
-
-        let _ = std::fs::remove_file(&db_path);
-    }
-
-    #[test]
-    fn pr19_proof_multi_tenant_isolation_basic() {
-        // PROVES: Basic multi-tenant isolation at storage layer
-        // Note: This tests storage isolation, not authorization layer
-        // Authorization layer tests are in authorization_security_tests.rs
-
-        let db_path = std::env::temp_dir().join("pr19_multi_tenant.log");
-        let _ = std::fs::remove_file(&db_path);
-
-        let db = crate::FeltDb::open(&db_path).expect("create db");
-        let store = Arc::new(StateStore::with_feltdb(Arc::new(db)).expect("create store"));
-
-        // Create tenant-scoped records
-        // Tenant A writes a record
-        let tenant_a_record = store
-            .create(
-                "tenant_a:1",
-                r#"{"tenant":"tenant_a","data":"secret_a"}"#.to_string(),
-                "tenant_a".to_string(),
-            )
-            .expect("tenant_a write");
-
-        // Tenant B writes a record
-        let tenant_b_record = store
-            .create(
-                "tenant_b:1",
-                r#"{"tenant":"tenant_b","data":"secret_b"}"#.to_string(),
-                "tenant_b".to_string(),
-            )
-            .expect("tenant_b write");
-
-        // Verify both records are stored (this proves storage works)
-        assert_ne!(
-            tenant_a_record.id, tenant_b_record.id,
-            "Records should have different IDs"
-        );
-
-        // Current limitation: StateStore doesn't enforce tenant boundaries
-        // Tenant isolation is enforced at authorization layer, not storage layer
-        // This test proves that separate StateIds are created for each record
-
-        // TODO: Test authorization layer rejection of cross-tenant access
-        // See authorization_security_tests.rs
-
-        let _ = std::fs::remove_file(&db_path);
-    }
-
-    #[test]
-    fn pr19_proof_atomicity_requires_sync_return() {
-        // PROVES: Atomicity guarantee only holds if sync() succeeds
-        // If sync() fails, no durability guarantee
-
-        let db_path = std::env::temp_dir().join("pr19_atomicity_sync.log");
-        let _ = std::fs::remove_file(&db_path);
-
-        let rev_id = {
-            let db = crate::FeltDb::open(&db_path).expect("create db");
-            let store = StateStore::with_feltdb(Arc::new(db)).expect("create store");
-
-            // Write should be durable only if it returns Ok
-            let result = store.create(
-                "docs:1",
-                r#"{"atomicity":"requires_sync_success"}"#.to_string(),
-                "system".to_string(),
-            );
-
-            // If create() returns Ok, durability is guaranteed
-            match result {
-                Ok(rev) => Some(rev.id.clone()),
-                Err(_) => None,
-            }
-        }; // Force drop of db to simulate restart
-
-        if let Some(rev_id) = rev_id {
-            // Durability guaranteed: restart should see this
-            let db2 = crate::FeltDb::open(&db_path).expect("reopen");
-            let store2 = StateStore::with_feltdb(Arc::new(db2)).expect("recover");
-
-            assert_eq!(
-                store2.get(&rev_id).unwrap().id,
-                rev_id,
-                "Durability guaranteed"
-            );
-        }
-        // If None, no durability guarantee - sync failed
-
-        let _ = std::fs::remove_file(&db_path);
-    }
-}