yrby 0.2.3 → 0.3.1

data/ext/yrby/src/lib.rs

@@ -8,7 +8,10 @@ use yrs::{Doc, GetString, ReadTxn, Transact};
 
 mod protocol;
 mod read;
-use protocol::{classify_message, merged_doc_update, update_advances_doc, update_is_ready};
+use protocol::{
+    classify_message, has_pending, integrated_update, merged_doc_update, update_advances_doc,
+    update_is_ready,
+};
 
 /// Wrapper around yrs Doc.
 ///
@@ -157,9 +160,11 @@ impl RbDoc {
     fn read_text(&self, name: String) -> Option<String> {
         let doc = &self.0;
         nogvl(move || {
-            doc.transact()
-                .get_text(name.as_str())
-                .map(|t| t.get_string(&doc.transact()))
+            // Exactly ONE transaction per call. Opening a second while the
+            // first is still held deadlocks against a waiting writer — and
+            // inside nogvl that hang can't be interrupted.
+            let txn = doc.transact();
+            txn.get_text(name.as_str()).map(|t| t.get_string(&txn))
         })
     }
 
@@ -188,6 +193,28 @@ impl RbDoc {
         })
     }
 
+    /// True if the doc holds un-integrable pending structs or a pending delete
+    /// set — content that couldn't integrate because a causally-prior update is
+    /// missing. Such content is a recovery buffer, not document state; it heals if
+    /// the missing dependency later arrives. A pure read.
+    fn pending(&self) -> bool {
+        let doc = &self.0;
+        nogvl(move || has_pending(doc))
+    }
+
+    /// Like `encode_state_as_update` (full state), but **gap-free**: it excludes
+    /// any pending (un-integrable) structs and pending delete set. Use this when
+    /// persisting or serving state that other peers will apply — serving pending
+    /// content poisons their sync. Non-destructive: this doc keeps its pending, so
+    /// a genuine gap still heals if its dependency arrives. (`encode_state_as_update`
+    /// stays lossless for raw-update recovery.)
+    fn compacted_state_update(&self) -> Result<RString, Error> {
+        let doc = &self.0;
+        let update = nogvl(move || integrated_update(doc, &yrs::StateVector::default()))
+            .map_err(yrb_error)?;
+        Ok(binary_string(&update))
+    }
+
     /// Encode state as update (optionally diffed against a state vector)
     fn encode_state_as_update(&self, args: &[Value]) -> Result<RString, Error> {
         let sv_bytes: Option<Vec<u8>> = if args.is_empty() {
@@ -263,9 +290,13 @@ impl RbDoc {
                 match msg {
                     Message::Sync(sync_msg) => match sync_msg {
                         SyncMessage::SyncStep1(sv) => {
-                            // Respond with SyncStep2
-                            let txn = doc.transact();
-                            let update = txn.encode_state_as_update_v1(&sv);
+                            // Respond with SyncStep2 carrying only *integrated*
+                            // state. Never hand a peer un-integrable pending
+                            // structs: the peer would park the same pending
+                            // forever and the state-vector/content mismatch drives
+                            // endless resync traffic. (integrated_update is a no-op
+                            // fast path when nothing is pending.)
+                            let update = integrated_update(doc, &sv)?;
                             let response = Message::Sync(SyncMessage::SyncStep2(update));
                             Ok((0, 0, response.encode_v1()))
                         }
@@ -366,6 +397,11 @@ fn init(ruby: &Ruby) -> Result<(), Error> {
     doc_class.define_method("read_text", method!(RbDoc::read_text, 1))?;
     doc_class.define_method("read_xml", method!(RbDoc::read_xml, 1))?;
     doc_class.define_method("read_map", method!(RbDoc::read_map, 1))?;
+    doc_class.define_method("pending?", method!(RbDoc::pending, 0))?;
+    doc_class.define_method(
+        "compacted_state_update",
+        method!(RbDoc::compacted_state_update, 0),
+    )?;
     doc_class.define_method("update_ready?", method!(RbDoc::update_ready, 1))?;
     doc_class.define_method("update_advances?", method!(RbDoc::update_advances, 1))?;
     doc_class.define_method("sync_step1", method!(RbDoc::sync_step1, 0))?;

data/ext/yrby/src/protocol.rs

@@ -8,7 +8,7 @@ use yrs::encoding::read::{Cursor, Read};
 use yrs::sync::protocol::MessageReader;
 use yrs::sync::{Message, SyncMessage};
 use yrs::updates::decoder::{Decode, DecoderV1};
-use yrs::{Doc, ReadTxn, Transact};
+use yrs::{Doc, ReadTxn, StateVector, Transact, Update, WriteTxn};
 
 /// Classify a frame: a non-zero code only for exactly one well-formed message
 /// that consumes the whole buffer (the codes are the match arms below).
@@ -66,14 +66,42 @@ pub(crate) fn merged_doc_update(bytes: &[u8]) -> Result<Option<Vec<u8>>, String>
     Ok(Some(merged))
 }
 
-/// True if applying `update_bytes` to `doc` would integrate cleanly: every
-/// dependency the update references is already present (the doc's state vector
-/// covers the update's lower bound). A pure read; does not mutate the doc.
-/// When false, applying it would park a pending struct, the signal that an
-/// earlier, causally-prior update is missing.
+/// True if applying `update_bytes` to `doc` would integrate cleanly; false if
+/// it would park as pending (a causally-prior update is missing). A pure read.
+///
+/// This must be EXACT: the sync layer records on "ready" and resyncs on "not
+/// ready", and a parked update that slipped through would look like an
+/// already-applied retry downstream — acked and dropped, losing real content.
+///
+/// Clocks alone can't decide it. An update can satisfy every per-client clock
+/// and still fail to integrate: its items may reference other clients' blocks
+/// (origins/parents), and merged updates hide internal gaps behind Skip blocks.
+/// So the clock lower bound serves only as a cheap definitive REJECT; "ready"
+/// is decided by trial-integrating on a throwaway probe seeded with the doc's
+/// integrated state — ready iff nothing parks.
 pub(crate) fn update_is_ready(doc: &Doc, update_bytes: &[u8]) -> Result<bool, String> {
     let update = yrs::Update::decode_v1(update_bytes).map_err(|e| e.to_string())?;
-    Ok(doc.transact().state_vector() >= update.state_vector_lower())
+    // Partial order: "not covered" includes incomparable — not ready either way.
+    let lower_covered = doc.transact().state_vector() >= update.state_vector_lower();
+    if !lower_covered {
+        return Ok(false);
+    }
+    // Seed the probe with the doc's INTEGRATED state (gap-free), for two
+    // reasons. A lossless seed would replant the doc's own pre-existing
+    // pending in the probe, making has_pending true for EVERY update — the
+    // verdict must be about this update, not the doc's baggage. And an update
+    // whose dependency exists only in that pending buffer is genuinely not
+    // ready: recording it would put a gap in the durable log; a resync heals
+    // both it and the pending it leans on as one complete delta.
+    let seed = integrated_update(doc, &StateVector::default())?;
+    let probe = Doc::new();
+    {
+        let mut txn = probe.transact_mut();
+        txn.apply_update(Update::decode_v1(&seed).map_err(|e| e.to_string())?)
+            .map_err(|e| e.to_string())?;
+        txn.apply_update(update).map_err(|e| e.to_string())?;
+    }
+    Ok(!has_pending(&probe))
 }
 
 /// True if applying `update_bytes` would actually change `doc`, i.e. it carries
@@ -107,6 +135,16 @@ pub(crate) fn update_advances_doc(doc: &Doc, update_bytes: &[u8]) -> Result<bool
     let update = yrs::Update::decode_v1(update_bytes).map_err(|e| e.to_string())?;
     let has_deletes = !update.delete_set().is_empty();
 
+    // Fast path: blocks beyond the doc's state vector are content the doc
+    // lacks — the update advances, no probe needed. The common case (a novel
+    // edit) exits here; only retries and ambiguous diffs pay for the probe.
+    if !has_deletes {
+        let covered = doc.transact().state_vector() >= update.state_vector();
+        if !covered {
+            return Ok(true);
+        }
+    }
+
     // Seed an independent probe with the doc's current state so we can measure the
     // update's effect without mutating the real doc.
     let probe = Doc::new();
@@ -117,6 +155,10 @@ pub(crate) fn update_advances_doc(doc: &Doc, update_bytes: &[u8]) -> Result<bool
         .transact_mut()
         .apply_update(yrs::Update::decode_v1(&current).map_err(|e| e.to_string())?)
         .map_err(|e| e.to_string())?;
+    let pending_before = {
+        probe.transact().store().pending_update().is_some()
+            || probe.transact().store().pending_ds().is_some()
+    };
 
     if has_deletes {
         // Deletes don't move the state vector; compare the full encoded state
@@ -139,25 +181,73 @@ pub(crate) fn update_advances_doc(doc: &Doc, update_bytes: &[u8]) -> Result<bool
             .apply_update(update)
             .map_err(|e| e.to_string())?;
         let after = probe.transact().state_vector();
-        Ok(before != after)
+        if before != after {
+            return Ok(true);
+        }
+        // An unchanged state vector is ambiguous. Usually it means the doc
+        // already had everything in this update (a retry — return false, don't
+        // re-record). But it can ALSO mean the update failed to integrate and
+        // was stashed as pending, which doesn't move the state vector either.
+        // That case is missing content, not a duplicate — returning false would
+        // let a caller ack it and drop it. Distinguish the two by whether the
+        // probe gained pending. (The sync flow screens gaps out with
+        // update_is_ready before calling this; the check guards direct callers.)
+        let pending_after = probe.transact().store().pending_update().is_some()
+            || probe.transact().store().pending_ds().is_some();
+        Ok(pending_after != pending_before)
     }
 }
 
-/// True if the doc holds pending structs or a pending delete set: blocks that
-/// couldn't integrate because a dependency is missing. Test-only: asserts the
-/// causal-chain parking behavior in the unit tests below.
-#[cfg(test)]
-pub(crate) fn doc_has_pending(doc: &Doc) -> bool {
+/// True if the doc holds un-integrable pending structs or a pending delete set:
+/// blocks that couldn't integrate because a causally-prior update is missing. A
+/// pure read; does not mutate.
+pub(crate) fn has_pending(doc: &Doc) -> bool {
     let txn = doc.transact();
     txn.store().pending_update().is_some() || txn.store().pending_ds().is_some()
 }
 
+/// Encode the doc's **integrated** state as a v1 update diffed against `sv`,
+/// excluding any pending (un-integrable) structs and pending delete set.
+///
+/// Pending blocks are a recovery buffer, not document state. Serving them across
+/// the sync boundary hands a peer content it can't integrate, so the peer parks
+/// the same pending forever and the state-vector/content mismatch drives endless
+/// resync traffic. `encode_state_as_update_v1` merges pending back in (see yrs
+/// `merge_pending_v1`), so to get a gap-free encode we rebuild the state into a
+/// throwaway doc and `prune_pending` there before re-encoding.
+///
+/// Non-destructive: the prune happens only on the throwaway copy; `doc` keeps its
+/// pending, so a genuine gap still heals if its missing dependency later arrives.
+pub(crate) fn integrated_update(doc: &Doc, sv: &StateVector) -> Result<Vec<u8>, String> {
+    // Pending check and encode share ONE transaction — with two, a concurrent
+    // gappy apply_update could slip between them and the encode would serve
+    // the very pending this function exists to exclude.
+    let full = {
+        let txn = doc.transact();
+        let store = txn.store();
+        // Nothing pending: the direct encode is already gap-free.
+        if store.pending_update().is_none() && store.pending_ds().is_none() {
+            return Ok(txn.encode_state_as_update_v1(sv));
+        }
+        txn.encode_state_as_update_v1(&StateVector::default())
+    };
+    let clean = Doc::new();
+    {
+        let mut txn = clean.transact_mut();
+        txn.apply_update(Update::decode_v1(&full).map_err(|e| e.to_string())?)
+            .map_err(|e| e.to_string())?;
+        txn.prune_pending();
+    }
+    let out = clean.transact().encode_state_as_update_v1(sv);
+    Ok(out)
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
     use yrs::sync::Awareness;
     use yrs::updates::encoder::Encode;
-    use yrs::Text;
+    use yrs::{GetString, Text};
 
     fn text_update(content: &str) -> Vec<u8> {
         let doc = Doc::new();
@@ -418,24 +508,405 @@ mod tests {
             !update_is_ready(&doc, u3).unwrap(),
             "u3 depends on the missing u2"
         );
-        assert!(
-            !doc_has_pending(&doc),
-            "nothing pending until u3 is applied"
-        );
+        assert!(!has_pending(&doc), "nothing pending until u3 is applied");
 
         // Applying u3 anyway parks it as a pending struct.
         doc.transact_mut()
             .apply_update(yrs::Update::decode_v1(u3).unwrap())
             .unwrap();
-        assert!(
-            doc_has_pending(&doc),
-            "u3 is pending: its parent u2 is missing"
-        );
+        assert!(has_pending(&doc), "u3 is pending: its parent u2 is missing");
 
         // Once u2 arrives (via resync), u3 integrates and pending clears.
         doc.transact_mut()
             .apply_update(yrs::Update::decode_v1(u2).unwrap())
             .unwrap();
-        assert!(!doc_has_pending(&doc), "u2 arrived; u3 integrated");
+        assert!(!has_pending(&doc), "u2 arrived; u3 integrated");
+    }
+
+    // Build a cross-client-origin gap: client C creates "abc"; client A applies
+    // it and types between C's characters, so A's delta references C's blocks as
+    // origins. Returns (c_update, a_delta). On a doc missing `c_update`, the
+    // per-client clock lower bound of `a_delta` is satisfied (A starts at clock
+    // 0) but integration parks — the case a clock-only readiness check misses.
+    fn cross_client_origin_gap() -> (Vec<u8>, Vec<u8>) {
+        let c = Doc::new();
+        let ct = c.get_or_insert_text("t");
+        ct.insert(&mut c.transact_mut(), 0, "abc");
+        let c_update = c
+            .transact()
+            .encode_state_as_update_v1(&yrs::StateVector::default());
+
+        let a = Doc::new();
+        a.transact_mut()
+            .apply_update(yrs::Update::decode_v1(&c_update).unwrap())
+            .unwrap();
+        let sv_before = a.transact().state_vector();
+        let at = a.get_or_insert_text("t");
+        at.insert(&mut a.transact_mut(), 1, "X"); // between C's chars
+        let a_delta = a.transact().encode_state_as_update_v1(&sv_before);
+        (c_update, a_delta)
+    }
+
+    #[test]
+    fn cross_client_origin_gap_is_not_ready() {
+        let (c_update, a_delta) = cross_client_origin_gap();
+
+        // A server that never saw C's content: the clock lower bound passes, but
+        // the update can't integrate — it must NOT be ready (previously it was,
+        // and the downstream advances? probe then acked-and-dropped it).
+        let server = Doc::new();
+        assert!(
+            !update_is_ready(&server, &a_delta).unwrap(),
+            "a delta with unmet cross-client origins is not ready"
+        );
+
+        // Once the server has C's content, the same delta is ready and advances.
+        server
+            .transact_mut()
+            .apply_update(yrs::Update::decode_v1(&c_update).unwrap())
+            .unwrap();
+        assert!(update_is_ready(&server, &a_delta).unwrap());
+        assert!(update_advances_doc(&server, &a_delta).unwrap());
+    }
+
+    #[test]
+    fn merged_update_with_internal_skip_gap_is_not_ready() {
+        // Merging u1 and u3 (u2 missing) yields one update with a Skip block; its
+        // clock lower bound is u1's start, but the post-Skip blocks can't
+        // integrate on a doc that lacks u2.
+        let src = Doc::new();
+        let txt = src.get_or_insert_text("t");
+        let mut deltas: Vec<Vec<u8>> = Vec::new();
+        let mut prev = yrs::StateVector::default();
+        for (i, ch) in ["A", "B", "C"].into_iter().enumerate() {
+            txt.insert(&mut src.transact_mut(), i as u32, ch);
+            deltas.push(src.transact().encode_state_as_update_v1(&prev));
+            prev = src.transact().state_vector();
+        }
+        let merged = yrs::merge_updates_v1([deltas[0].as_slice(), deltas[2].as_slice()]).unwrap();
+
+        let server = Doc::new();
+        assert!(
+            !update_is_ready(&server, &merged).unwrap(),
+            "the post-Skip blocks depend on the missing u2"
+        );
+    }
+
+    #[test]
+    fn a_doc_with_legacy_pending_still_accepts_healthy_updates() {
+        // Why update_is_ready seeds its probe with the INTEGRATED state: with a
+        // lossless seed, the doc's own pre-existing pending would park in the
+        // probe and every verdict would come back "not ready" — a server with
+        // one legacy gap would reject every healthy keystroke forever.
+        let (_first, dependent) = gap_pair();
+        let doc = Doc::new();
+        doc.transact_mut()
+            .apply_update(yrs::Update::decode_v1(&dependent).unwrap())
+            .unwrap();
+        assert!(has_pending(&doc), "the doc carries a legacy parked gap");
+
+        // A healthy, self-contained update from an unrelated client.
+        let healthy = {
+            let d = Doc::new();
+            let t = d.get_or_insert_text("other");
+            t.insert(&mut d.transact_mut(), 0, "hello");
+            let txn = d.transact();
+            txn.encode_state_as_update_v1(&yrs::StateVector::default())
+        };
+
+        assert!(
+            update_is_ready(&doc, &healthy).unwrap(),
+            "legacy pending must not veto unrelated healthy updates"
+        );
+        assert!(update_advances_doc(&doc, &healthy).unwrap());
+    }
+
+    #[test]
+    fn an_update_depending_only_on_pending_content_is_not_ready() {
+        // The other half of the integrated-only seed: a dependency that exists
+        // solely in the doc's pending buffer doesn't count — recording such an
+        // update would put a gap in the durable log. Not ready; resync heals
+        // both as one complete delta.
+        let src = Doc::new();
+        let txt = src.get_or_insert_text("t");
+        let mut deltas: Vec<Vec<u8>> = Vec::new();
+        let mut prev = yrs::StateVector::default();
+        for (i, ch) in ["A", "B", "C"].into_iter().enumerate() {
+            txt.insert(&mut src.transact_mut(), i as u32, ch);
+            deltas.push(src.transact().encode_state_as_update_v1(&prev));
+            prev = src.transact().state_vector();
+        }
+
+        // The doc holds u2 only as PENDING (u1 never arrived); u3 depends on u2.
+        let doc = Doc::new();
+        doc.transact_mut()
+            .apply_update(yrs::Update::decode_v1(&deltas[1]).unwrap())
+            .unwrap();
+        assert!(has_pending(&doc), "u2 parked without u1");
+
+        assert!(
+            !update_is_ready(&doc, &deltas[2]).unwrap(),
+            "a dependency satisfied only by pending content is not ready"
+        );
+    }
+
+    #[test]
+    fn update_advances_reports_true_when_the_update_would_park() {
+        // Defense in depth for callers using advances? without the ready gate: a
+        // gappy update parks pending — that changes the doc, so it advances (it
+        // must never be misread as an already-applied retry and dropped).
+        let (_c_update, a_delta) = cross_client_origin_gap();
+        let server = Doc::new();
+        assert!(
+            update_advances_doc(&server, &a_delta).unwrap(),
+            "a parked update is not a duplicate"
+        );
+    }
+
+    // Build a causal gap: `first` inserts "a", `dependent` inserts "b" after it,
+    // so `dependent` alone parks as pending on a doc that lacks `first`.
+    fn gap_pair() -> (Vec<u8>, Vec<u8>) {
+        let src = Doc::new();
+        let txt = src.get_or_insert_text("notepad");
+        txt.insert(&mut src.transact_mut(), 0, "a");
+        let first = src
+            .transact()
+            .encode_state_as_update_v1(&yrs::StateVector::default());
+        let sv = src.transact().state_vector();
+        txt.insert(&mut src.transact_mut(), 1, "b");
+        let dependent = src.transact().encode_state_as_update_v1(&sv);
+        (first, dependent)
+    }
+
+    #[test]
+    fn integrated_update_strips_pending_and_is_non_destructive() {
+        let (_first, dependent) = gap_pair();
+        let doc = Doc::new();
+        doc.transact_mut()
+            .apply_update(yrs::Update::decode_v1(&dependent).unwrap())
+            .unwrap();
+        assert!(has_pending(&doc), "the gappy update parked as pending");
+
+        // encode_state_as_update carries the pending; integrated_update does not.
+        let full = doc
+            .transact()
+            .encode_state_as_update_v1(&yrs::StateVector::default());
+        let gap_free = integrated_update(&doc, &yrs::StateVector::default()).unwrap();
+        assert_ne!(full, gap_free, "integrated_update drops the pending bytes");
+
+        // Applying the gap-free encode to a fresh peer must NOT poison it.
+        let peer = Doc::new();
+        peer.transact_mut()
+            .apply_update(yrs::Update::decode_v1(&gap_free).unwrap())
+            .unwrap();
+        assert!(
+            !has_pending(&peer),
+            "peer got no pending from the gap-free state"
+        );
+
+        // Non-destructive: the source doc keeps its pending (so it can still heal).
+        assert!(
+            has_pending(&doc),
+            "integrated_update did not mutate the source"
+        );
+    }
+
+    #[test]
+    fn integrated_update_fast_path_matches_direct_encode_when_clean() {
+        // No pending -> byte-identical to encode_state_as_update (zero-copy path).
+        let (first, _dependent) = gap_pair();
+        let doc = Doc::new();
+        doc.transact_mut()
+            .apply_update(yrs::Update::decode_v1(&first).unwrap())
+            .unwrap();
+        assert!(!has_pending(&doc));
+        let direct = doc
+            .transact()
+            .encode_state_as_update_v1(&yrs::StateVector::default());
+        let via = integrated_update(&doc, &yrs::StateVector::default()).unwrap();
+        assert_eq!(direct, via);
+    }
+
+    #[test]
+    fn a_healed_gap_serves_its_content() {
+        // After the missing dependency arrives, the (formerly pending) content is
+        // integrated and integrated_update includes it.
+        let (first, dependent) = gap_pair();
+        let doc = Doc::new();
+        doc.transact_mut()
+            .apply_update(yrs::Update::decode_v1(&dependent).unwrap())
+            .unwrap();
+        doc.transact_mut()
+            .apply_update(yrs::Update::decode_v1(&first).unwrap())
+            .unwrap();
+        assert!(!has_pending(&doc), "gap healed once first arrived");
+        let gap_free = integrated_update(&doc, &yrs::StateVector::default()).unwrap();
+        let peer = Doc::new();
+        peer.transact_mut()
+            .apply_update(yrs::Update::decode_v1(&gap_free).unwrap())
+            .unwrap();
+        assert_eq!(
+            peer.get_or_insert_text("notepad")
+                .get_string(&peer.transact()),
+            "ab"
+        );
+    }
+
+    // A gappy insert from its own independent client: inserts two chars and
+    // returns only the second delta, which depends on the (missing) first.
+    fn independent_gappy_insert() -> Vec<u8> {
+        let src = Doc::new();
+        let txt = src.get_or_insert_text("notepad");
+        txt.insert(&mut src.transact_mut(), 0, "x");
+        let sv = src.transact().state_vector();
+        txt.insert(&mut src.transact_mut(), 1, "y");
+        let txn = src.transact();
+        txn.encode_state_as_update_v1(&sv)
+    }
+
+    #[test]
+    fn integrated_update_keeps_content_and_drops_pending_when_mixed() {
+        // The realistic case: a doc with real integrated content AND a pending
+        // struct. Pruning must keep the content and drop only the pending.
+        let (first, _dep) = gap_pair();
+        let doc = Doc::new();
+        doc.transact_mut()
+            .apply_update(yrs::Update::decode_v1(&first).unwrap())
+            .unwrap(); // integrated "a"
+        doc.transact_mut()
+            .apply_update(yrs::Update::decode_v1(&independent_gappy_insert()).unwrap())
+            .unwrap(); // + a pending struct from another client
+        assert!(has_pending(&doc));
+
+        let gap_free = integrated_update(&doc, &yrs::StateVector::default()).unwrap();
+        let peer = Doc::new();
+        peer.transact_mut()
+            .apply_update(yrs::Update::decode_v1(&gap_free).unwrap())
+            .unwrap();
+        assert_eq!(
+            peer.get_or_insert_text("notepad")
+                .get_string(&peer.transact()),
+            "a",
+            "kept the integrated content"
+        );
+        assert!(!has_pending(&peer), "dropped the pending");
+    }
+
+    #[test]
+    fn integrated_update_diffs_against_a_peer_sv_and_excludes_pending() {
+        // The production signature: `handle_sync_message` calls
+        // integrated_update(doc, peer_sv). A peer already holding the integrated
+        // content should get a diff carrying no new content and no pending.
+        let (first, _dep) = gap_pair();
+        let server = Doc::new();
+        server
+            .transact_mut()
+            .apply_update(yrs::Update::decode_v1(&first).unwrap())
+            .unwrap();
+        server
+            .transact_mut()
+            .apply_update(yrs::Update::decode_v1(&independent_gappy_insert()).unwrap())
+            .unwrap();
+
+        let peer = Doc::new();
+        peer.transact_mut()
+            .apply_update(yrs::Update::decode_v1(&first).unwrap())
+            .unwrap();
+        let peer_sv = peer.transact().state_vector();
+
+        let diff = integrated_update(&server, &peer_sv).unwrap();
+        peer.transact_mut()
+            .apply_update(yrs::Update::decode_v1(&diff).unwrap())
+            .unwrap();
+        assert_eq!(
+            peer.get_or_insert_text("notepad")
+                .get_string(&peer.transact()),
+            "a"
+        );
+        assert!(!has_pending(&peer), "the diff carried no pending");
+    }
+
+    #[test]
+    fn integrated_update_never_serves_pending_under_concurrent_gappy_applies() {
+        // Invariant under contention: while a writer parks and heals a gappy
+        // update in a loop, every integrated_update encode must be pending-free
+        // for a fresh peer.
+        //
+        // Scope: this can't hit the original check-vs-encode race (its window
+        // is nanoseconds; never reproduced even at 20k iterations) — that fix
+        // is guaranteed by using a single transaction. What this catches is
+        // coarser: encoding outside the lock, or a fast path skipping the
+        // pending check.
+        use std::sync::atomic::{AtomicBool, Ordering};
+        use std::sync::Arc as StdArc;
+
+        let (first, dependent) = gap_pair();
+        let doc = StdArc::new(Doc::new());
+        let stop = StdArc::new(AtomicBool::new(false));
+
+        let writer = {
+            let doc = StdArc::clone(&doc);
+            let stop = StdArc::clone(&stop);
+            let dependent = dependent.clone();
+            let first = first.clone();
+            std::thread::spawn(move || {
+                while !stop.load(Ordering::Relaxed) {
+                    // Park a pending struct, then heal it, over and over — the
+                    // encode below keeps racing both transitions.
+                    doc.transact_mut()
+                        .apply_update(yrs::Update::decode_v1(&dependent).unwrap())
+                        .unwrap();
+                    doc.transact_mut()
+                        .apply_update(yrs::Update::decode_v1(&first).unwrap())
+                        .unwrap();
+                }
+            })
+        };
+
+        for _ in 0..500 {
+            let encoded = integrated_update(&doc, &yrs::StateVector::default()).unwrap();
+            let peer = Doc::new();
+            peer.transact_mut()
+                .apply_update(yrs::Update::decode_v1(&encoded).unwrap())
+                .unwrap();
+            assert!(
+                !has_pending(&peer),
+                "an integrated_update encode leaked pending to a peer"
+            );
+        }
+        stop.store(true, Ordering::Relaxed);
+        writer.join().unwrap();
+    }
+
+    #[test]
+    fn integrated_update_strips_a_pending_delete_set() {
+        // A deletion whose target struct is absent parks as a pending *delete
+        // set* -- the delete-side counterpart to a pending struct.
+        let src = Doc::new();
+        let txt = src.get_or_insert_text("notepad");
+        txt.insert(&mut src.transact_mut(), 0, "z");
+        let sv = src.transact().state_vector();
+        txt.remove_range(&mut src.transact_mut(), 0, 1);
+        let deletion = src.transact().encode_state_as_update_v1(&sv); // delete-only
+
+        let doc = Doc::new();
+        doc.transact_mut()
+            .apply_update(yrs::Update::decode_v1(&deletion).unwrap())
+            .unwrap();
+        assert!(
+            has_pending(&doc),
+            "the orphan deletion parked as a pending delete set"
+        );
+
+        let gap_free = integrated_update(&doc, &yrs::StateVector::default()).unwrap();
+        let peer = Doc::new();
+        peer.transact_mut()
+            .apply_update(yrs::Update::decode_v1(&gap_free).unwrap())
+            .unwrap();
+        assert!(!has_pending(&peer), "the pending delete set was not served");
+        assert!(
+            has_pending(&doc),
+            "non-destructive: source keeps its pending"
+        );
     }
 }