@@ -2,7 +2,7 @@
 
 //! CrdtState core: document handle, row CRUD, uniqueness probes.
 
-use std::cell::{Cell, RefCell};
+use std::cell::Cell;
 use std::collections::HashSet;
 use std::marker::PhantomData;
 
@@ -12,6 +12,8 @@ use crate::error::{CrdtError, Result};
 use crate::row_lookup::RowLookup;
 use crate::validator::bitemporal::{VALID_UNTIL, VALID_UNTIL_OPEN};
 
+use super::document_cell::DocumentCell;
+
 /// A row is live when its `_ts_valid_until` field is absent, null, or the
 /// open sentinel (`i64::MAX`). Rows with any finite `_ts_valid_until` are
 /// treated as superseded, independent of wall-clock time — the write path
@@ -41,34 +43,49 @@ fn key_is_container(row: &LoroMap, key: &str) -> bool {
 pub struct CrdtState {
     /// Kept private to this state module so callers cannot clone or share a
     /// raw Loro handle around the preview's pending-check/fork critical section.
-    pub(in crate::state) doc: LoroDoc,
+    pub(in crate::state) doc: DocumentCell,
     pub(super) peer_id: u64,
     /// Loro auto-commit state must stay single-owner. This makes accidental
     /// cross-thread sharing of a `CrdtState` a compile error.
     pub(super) _single_owner: PhantomData<Cell<()>>,
-    /// Last memory estimate and the frontier it was taken at.
-    ///
-    /// The estimate is a snapshot export, which costs O(document). Callers
-    /// poll it to decide when to compact, and a document that is not being
-    /// written has the same estimate every time, so it is computed once per
-    /// frontier rather than once per call.
-    pub(super) memory_estimate: RefCell<Option<(loro::VersionVector, usize)>>,
 }
 
 impl CrdtState {
     /// Create a new empty state for the given peer.
     pub fn new(peer_id: u64) -> Result<Self> {
-        let doc = LoroDoc::new();
-        doc.set_peer_id(peer_id)
-            .map_err(|e| CrdtError::Loro(format!("failed to set peer_id {peer_id}: {e}")))?;
         Ok(Self {
-            doc,
+            doc: DocumentCell::new(Self::new_doc(peer_id)?),
             peer_id,
             _single_owner: PhantomData,
-            memory_estimate: RefCell::new(None),
         })
     }
 
+    /// Load a state from an encoded document this process produced itself — a
+    /// snapshot read back from durable storage, or a pre-image exported moments
+    /// earlier for transaction rollback.
+    ///
+    /// Pairs `new` with [`CrdtState::import_local`], because those two steps
+    /// belong together: a caller that assembles them by hand has to know that
+    /// its own bytes must not go through the peer ceilings, and a caller that
+    /// gets that wrong writes a document it can no longer open. See
+    /// `import_local` for why the ceilings do not apply here.
+    pub fn from_local_snapshot(peer_id: u64, snapshot: &[u8]) -> Result<Self> {
+        let state = Self::new(peer_id)?;
+        state.import_local(snapshot)?;
+        Ok(state)
+    }
+
+    /// A fresh Loro document bound to `peer_id`.
+    ///
+    /// Shared by `new` and by the compaction paths, which need the same
+    /// peer-bound document before loading a shallow snapshot into it.
+    pub(in crate::state) fn new_doc(peer_id: u64) -> Result<LoroDoc> {
+        let doc = LoroDoc::new();
+        doc.set_peer_id(peer_id)
+            .map_err(|e| CrdtError::Loro(format!("failed to set peer_id {peer_id}: {e}")))?;
+        Ok(doc)
+    }
+
     /// Fetch a row's existing `LoroMap` container, or create one if absent.
     /// Shared by `upsert` and `set_fields` — both need the same row handle
     /// before diverging on prune-vs-preserve semantics.
 
@@ -0,0 +1,84 @@
+// SPDX-License-Identifier: Apache-2.0
+
+//! The document handle and every value derived from it.
+
+use std::cell::RefCell;
+use std::ops::Deref;
+
+use loro::LoroDoc;
+
+/// A `LoroDoc` together with the values cached from it.
+///
+/// Compaction does not mutate a document, it replaces one: `compact_history`
+/// and `compact_at_version` build a fresh doc from a shallow snapshot and swap
+/// it in. Anything derived from the old doc and stored beside it survives that
+/// swap and goes on describing a document that no longer exists.
+///
+/// The size estimate is the case that bites. A shallow snapshot preserves the
+/// version vector — peers have to keep delta-syncing across a compaction — so
+/// a cache keyed on the version alone still looks current after the bytes it
+/// measured are gone. A caller polling the estimate to decide when to compact
+/// would then never observe its own compaction landing, and would compact
+/// again, and again.
+///
+/// Keeping the cache *inside* the cell removes the possibility: `replace` is
+/// the only way to swap the document, and it drops the derived state with it.
+/// Reads go through `Deref`, so every `self.doc.…` call site is untouched.
+pub(in crate::state) struct DocumentCell {
+    doc: LoroDoc,
+    /// Snapshot size and the oplog version it was measured at. `None` until
+    /// the estimate is first asked for.
+    memory_estimate: RefCell<Option<(loro::VersionVector, usize)>>,
+}
+
+impl DocumentCell {
+    /// Wrap a document with an empty derived-value cache.
+    pub(in crate::state) fn new(doc: LoroDoc) -> Self {
+        Self {
+            doc,
+            memory_estimate: RefCell::new(None),
+        }
+    }
+
+    /// Swap in a different document, discarding everything cached from the
+    /// previous one. The only way to reassign the document.
+    pub(in crate::state) fn replace(&mut self, doc: LoroDoc) {
+        *self = Self::new(doc);
+    }
+
+    /// Snapshot size in bytes, as a proxy for memory footprint.
+    ///
+    /// Loro exposes no direct memory metric. A snapshot export is proportional
+    /// to state size, which is good enough for pressure monitoring but costs
+    /// O(document) — and the callers that want it are polling loops. It is
+    /// therefore measured once per version rather than once per call.
+    /// The version is a sound cache key because `oplog_vv` counts operations
+    /// that are still in an open transaction — a write is visible to the key
+    /// the moment it happens, not when it commits. `state::tests` pins that
+    /// property, since the cache is wrong the day it stops holding.
+    pub(in crate::state) fn estimated_bytes(&self) -> usize {
+        let version = self.doc.oplog_vv();
+        if let Some((measured_at, bytes)) = self.memory_estimate.borrow().as_ref()
+            && *measured_at == version
+        {
+            return *bytes;
+        }
+
+        let Ok(snapshot) = self.doc.export(loro::ExportMode::Snapshot) else {
+            // A failed export is not a measurement. Caching the zero would pin
+            // the document at "empty" until its next write moved the version.
+            return 0;
+        };
+        let bytes = snapshot.len();
+        *self.memory_estimate.borrow_mut() = Some((version, bytes));
+        bytes
+    }
+}
+
+impl Deref for DocumentCell {
+    type Target = LoroDoc;
+
+    fn deref(&self) -> &Self::Target {
+        &self.doc
+    }
+}
@@ -9,7 +9,6 @@ use loro::{LoroDoc, LoroMap, LoroValue, ValueOrContainer};
 use crate::error::{CrdtError, Result};
 
 use super::core::CrdtState;
-use super::import_admission::admit_local_import;
 use super::restore_containers;
 
 impl CrdtState {
@@ -95,24 +94,7 @@ impl CrdtState {
     /// Discards oplog entries before the target version. Current state and
     /// all versions after the target are preserved.
     pub fn compact_at_version(&mut self, version: &loro::VersionVector) -> Result<()> {
-        let frontiers = self.doc.vv_to_frontiers(version);
-        let snapshot = self
-            .doc
-            .export(loro::ExportMode::shallow_snapshot(&frontiers))
-            .map_err(|e| CrdtError::Loro(format!("shallow snapshot export: {e}")))?;
-
-        let new_doc = LoroDoc::new();
-        new_doc
-            .set_peer_id(self.peer_id)
-            .map_err(|e| CrdtError::Loro(format!("set peer_id on compacted doc: {e}")))?;
-        // Locally generated — see `compact_history`.
-        admit_local_import(&snapshot, &new_doc.oplog_vv())?;
-        new_doc
-            .import(&snapshot)
-            .map_err(|e| CrdtError::Loro(format!("shallow snapshot import: {e}")))?;
-
-        self.doc = new_doc;
-        Ok(())
+        self.compact_to_frontiers(&self.doc.vv_to_frontiers(version))
     }
 
     /// Generate a forward restore delta without changing authoritative state.
 
@@ -8,6 +8,7 @@
 
 pub mod bitemporal_archive;
 pub mod core;
+pub(crate) mod document_cell;
 pub mod frontier_digest;
 pub mod history;
 pub(crate) mod import_admission;
 
@@ -16,6 +16,7 @@ use crate::error::{CrdtError, Result};
 use crate::loro_value::loro_to_value;
 
 use super::core::CrdtState;
+use super::document_cell::DocumentCell;
 use super::import_admission::{CrdtImportLimits, admit_import};
 
 /// Maximum raw CRDT delta bytes accepted by the default authoritative preview.
@@ -151,10 +152,9 @@ impl CrdtState {
 
         let resulting_frontier = fork.state_frontiers();
         let fork_state = CrdtState {
-            doc: fork,
+            doc: DocumentCell::new(fork),
             peer_id: self.peer_id,
             _single_owner: std::marker::PhantomData,
-            memory_estimate: std::cell::RefCell::new(None),
         };
         // Loro exposes diffs only as a complete DiffBatch. This runs after
         // byte and imported-operation caps have bounded the fork/import work;
 
@@ -2,8 +2,6 @@
 
 //! Snapshot export/import, history compaction, memory estimation.
 
-use loro::LoroDoc;
-
 use crate::error::{CrdtError, Result};
 
 use super::core::CrdtState;
@@ -106,54 +104,55 @@ impl CrdtState {
     /// Call this periodically (e.g., every 30 minutes or when memory
     /// pressure exceeds threshold) to prevent unbounded history growth.
     pub fn compact_history(&mut self) -> Result<()> {
-        // Export a shallow snapshot at the current frontiers.
-        let frontiers = self.doc.oplog_frontiers();
+        self.compact_to_frontiers(&self.doc.oplog_frontiers())
+    }
+
+    /// Replace this document with a shallow snapshot taken at `frontiers`.
+    ///
+    /// The whole of compaction, shared by `compact_history` (current
+    /// frontiers) and `compact_at_version` (a chosen version), so the two
+    /// cannot drift apart on how the snapshot is admitted or how the document
+    /// is swapped in.
+    ///
+    /// The snapshot is admitted through [`admit_local_import`]: this process
+    /// exported it one line earlier. Under the peer ceilings, compaction would
+    /// be refused for precisely the documents large enough to need it — the
+    /// operation that would bring a document back under the limit gated by
+    /// that limit.
+    pub(in crate::state) fn compact_to_frontiers(
+        &mut self,
+        frontiers: &loro::Frontiers,
+    ) -> Result<()> {
         let snapshot = self
             .doc
-            .export(loro::ExportMode::shallow_snapshot(&frontiers))
+            .export(loro::ExportMode::shallow_snapshot(frontiers))
             .map_err(|e| CrdtError::Loro(format!("shallow snapshot export: {e}")))?;
 
-        // Replace the doc with a fresh one loaded from the snapshot.
-        let new_doc = LoroDoc::new();
-        new_doc
-            .set_peer_id(self.peer_id)
-            .map_err(|e| CrdtError::Loro(format!("failed to set peer_id on compacted doc: {e}")))?;
-        // Locally generated: it keeps the metadata and range checks but not
-        // the peer size ceilings, which would otherwise make compaction
-        // impossible for exactly the documents that need it most.
-        admit_local_import(&snapshot, &new_doc.oplog_vv())?;
-        new_doc
+        let compacted = Self::new_doc(self.peer_id)?;
+        admit_local_import(&snapshot, &compacted.oplog_vv())?;
+        compacted
             .import(&snapshot)
             .map_err(|e| CrdtError::Loro(format!("shallow snapshot import: {e}")))?;
 
-        self.doc = new_doc;
+        // `replace` also drops everything cached from the outgoing document. A
+        // shallow snapshot keeps the version vector, so a derived value keyed
+        // on the version alone would look current while describing bytes that
+        // no longer exist.
+        self.doc.replace(compacted);
         Ok(())
     }
 
     /// Estimated memory usage of the CRDT state (bytes).
     ///
     /// Includes operation history, current state, and internal caches.
     /// Use this to decide when to trigger `compact_history()`.
-    /// Cached per frontier: the proxy is a full snapshot export, so polling it
-    /// on an unchanged document would re-serialize the whole document to learn
-    /// a number that cannot have moved.
+    ///
+    /// The proxy is a full snapshot export, so it is measured once per version
+    /// rather than once per call: a document nobody is writing cannot have
+    /// changed size. Compaction discards the measurement along with the
+    /// document it described.
     pub fn estimated_memory_bytes(&self) -> usize {
-        let version = self.doc.oplog_vv();
-        if let Some((cached_at, bytes)) = self.memory_estimate.borrow().as_ref()
-            && *cached_at == version
-        {
-            return *bytes;
-        }
-        // Loro doesn't expose a direct memory metric.
-        // Use snapshot size as a proxy — it's proportional to state size.
-        // This is not precise but good enough for pressure monitoring.
-        let bytes = self
-            .doc
-            .export(loro::ExportMode::Snapshot)
-            .map(|s| s.len())
-            .unwrap_or(0);
-        *self.memory_estimate.borrow_mut() = Some((version, bytes));
-        bytes
+        self.doc.estimated_bytes()
     }
 }
 
@@ -218,6 +217,32 @@ mod tests {
         );
     }
 
+    #[test]
+    fn from_local_snapshot_loads_without_the_peer_ceilings() {
+        let source = CrdtState::new(3).expect("source state");
+        source
+            .upsert("docs", "row", &[("title", LoroValue::String("v".into()))])
+            .expect("source write");
+        let snapshot = source.export_snapshot().expect("snapshot");
+
+        let reloaded = CrdtState::from_local_snapshot(3, &snapshot).expect("reload");
+        assert!(
+            reloaded.row_exists("docs", "row"),
+            "a state loaded from our own snapshot must carry its rows"
+        );
+    }
+
+    #[test]
+    fn from_local_snapshot_rejects_malformed_bytes() {
+        assert!(
+            matches!(
+                CrdtState::from_local_snapshot(1, &[0xff]),
+                Err(CrdtError::ImportMalformed { .. })
+            ),
+            "the convenience constructor keeps every structural check"
+        );
+    }
+
     #[test]
     fn local_import_still_rejects_malformed_metadata() {
         let state = CrdtState::new(1).expect("state");