@@ -661,6 +661,75 @@ describe('FileDocStore', () => {
     recovered.destroy()
   })
 
+  it.each(['headless', 'attached'] as const)(
+    'does not recount a replacement snapshot near the byte budget during %s replay',
+    async (mode) => {
+      const streamKey = `filedoc:stream:${NAME}`
+      const source = new Y.Doc()
+      source.getText('body').insert(0, 'x'.repeat(10 * 1024 * 1024))
+      const initial = Buffer.from(Y.encodeStateAsUpdate(source)).toString('base64')
+      const noop = Buffer.from(updateFor('')).toString('base64')
+      state.backing!.streams.set(
+        streamKey,
+        Array.from({ length: 8 }, (_, index) => ({
+          id: `${index + 1}-0`,
+          message: { u: index === 0 ? initial : noop },
+        }))
+      )
+      source.getText('body').insert(source.getText('body').length, ' joined')
+      const compacted = Buffer.from(Y.encodeStateAsUpdate(source)).toString('base64')
+      state.backing!.seq = 8
+      state.backing!.onRange = (_call, key, start) => {
+        if (key !== streamKey || start !== '(4-0') return
+        state.backing!.streams.set(streamKey, [{ id: '9-0', message: { u: compacted, s: '1' } }])
+        state.backing!.seq = 9
+        state.backing!.onRange = undefined
+      }
+      const store = await newStore()
+      const recovered = new Y.Doc()
+      try {
+        if (mode === 'attached') await store.attachRoom(NAME, recovered)
+        else Y.applyUpdate(recovered, (await store.getStreamState(NAME))!)
+        expect(recovered.getText('body').toString()).toBe(source.getText('body').toString())
+      } finally {
+        store.detachRoom(NAME)
+        recovered.destroy()
+        source.destroy()
+      }
+    }
+  )
+
+  it('does not recount retained entries when compaction meets the exact entry budget', async () => {
+    const streamKey = `filedoc:stream:${NAME}`
+    const noop = Buffer.from(updateFor('')).toString('base64')
+    const entries = Array.from({ length: 1_999 }, (_, index) => ({
+      id: `${index + 1}-0`,
+      message: { u: noop },
+    }))
+    state.backing!.streams.set(streamKey, entries)
+    state.backing!.seq = 1_999
+    state.backing!.onRange = (_call, key, start) => {
+      if (key !== streamKey || start !== '(1996-0') return
+      state.backing!.streams.set(streamKey, [
+        ...entries.slice(1_996),
+        {
+          id: '2000-0',
+          message: { u: Buffer.from(updateFor('complete')).toString('base64'), s: '1' },
+        },
+      ])
+      state.backing!.seq = 2_000
+      state.backing!.onRange = undefined
+    }
+    const store = await newStore()
+    const recovered = new Y.Doc()
+    try {
+      Y.applyUpdate(recovered, (await store.getStreamState(NAME))!)
+      expect(recovered.getText('body').toString()).toBe('complete')
+    } finally {
+      recovered.destroy()
+    }
+  })
+
   it('reads the replacement snapshot when peer deltas cross the old replay tail', async () => {
     const streamKey = `filedoc:stream:${NAME}`
     const source = new Y.Doc()
 
@@ -73,12 +73,7 @@ const INVALIDATE_DOCUMENT_SCRIPT =
 const ADOPT_GENERATION_SCRIPT =
   "local generation = redis.call('get', KEYS[2]); if generation then return generation end; if redis.call('xlen', KEYS[1]) == 0 then return false end; redis.call('set', KEYS[2], ARGV[1], 'EX', ARGV[2]); return ARGV[1]"
 
-/**
- * Append an ordinary update only while the live-document generation is valid. A durable replacement
- * that cannot be represented by the rich editor first sets the invalidation tombstone and then removes
- * the stream; keeping the guard and XADD in one script prevents an old room from recreating that stream.
- * Returns the new stream id, or `false` while invalidated.
- */
+/** Atomically fence XADD so stale rooms cannot recreate a replaced or expired stream. Returns false when fenced. */
 const APPEND_UPDATE_SCRIPT =
   "local generation = redis.call('get', KEYS[2]) or ''; if generation ~= ARGV[4] or redis.call('exists', KEYS[1]) == 0 then return false end; if ARGV[3] ~= '' then return redis.call('xadd', KEYS[1], '*', ARGV[1], ARGV[2], ARGV[3], '1') else return redis.call('xadd', KEYS[1], '*', ARGV[1], ARGV[2]) end"
 
@@ -403,13 +398,8 @@ export class FileDocStore {
   }
 
   /**
-   * PULL the shared state into a registered room: read the stream and apply every entry the doc has
-   * not integrated yet (origin {@link REDIS_ORIGIN}), advancing `lastId` so the tailer resumes exactly
-   * after it. This is the ONLY way a room loads shared state, so a caller that must not depend on the
-   * tailer's asynchronous push — the join, which may not serve a client a half-assembled document —
-   * can converge on demand. Idempotent and safe to call repeatedly; no-op when disabled or the room is
-   * not registered (a fast open→close detached it). Throws without applying partial state when replay
-   * cannot complete, so a join never serves a prefix of the shared document.
+   * Completes shared replay before applying entries, so joins never receive a partial document.
+   * Repeated calls skip integrated entries; detached rooms and disabled stores are ignored.
    */
   async catchUp(name: string): Promise<void> {
     if (!this.enabled) return
@@ -543,10 +533,8 @@ export class FileDocStore {
   }
 
   /**
-   * Append a user update exactly once within the stream's bounded deduplication window and return only
-   * after Redis has accepted it. The client keeps the batch in IndexedDB until this promise succeeds
-   * and its socket acknowledgement arrives, so a relay restart or lost acknowledgement is safe to
-   * retry throughout that window.
+   * Waits for Redis acceptance before the relay acknowledges the client. Retries are deduplicated
+   * within the bounded window; clients retain their journal until the acknowledgement arrives.
    */
   async publishClientUpdateAndWait(
     name: string,
@@ -656,10 +644,8 @@ export class FileDocStore {
   }
 
   /**
-   * Invalidate the current live-document generation after a durable replacement that the rich editor
-   * cannot represent. The invalid generation marker is written before deleting the stream, so stale
-   * room publishers cannot recreate it; the next authoritative seed atomically replaces the marker
-   * with its generation. The same TTL as the stream bounds abandoned markers.
+   * Fences an unsupported durable replacement before deleting its stream. The next authoritative
+   * seed replaces the tombstone; abandoned tombstones expire with the stream TTL.
    */
   async invalidateDocument(name: string, version: number): Promise<boolean> {
     if (!this.enabled) {
@@ -830,12 +816,11 @@ export class FileDocStore {
         }
       }
 
-      /** A moving head means compaction may have removed unread dependencies. Replay its snapshot. */
+      /** Compaction appends its snapshot before trimming; extend the barrier without rereading it. */
       const currentFirstId = (await this.write.xRange(key, '-', '+', { COUNT: 1 }))[0]?.id
       if (!currentFirstId) throw new FileDocInvalidatedError()
       if (currentFirstId === firstId) return entriesRead
       firstId = currentFirstId
-      cursor = '0-0'
       const currentTail = await this.write.xRevRange(key, '+', '-', { COUNT: 1 })
       if (currentTail.length === 0) throw new FileDocInvalidatedError()
       endId = currentTail[0].id
 
@@ -268,9 +268,8 @@ const AGENT_SYNC_ORIGIN = Symbol('file-doc-agent-sync')
 const MAX_LEGACY_FRAME_BYTES = FILE_DOC_LIMITS.updateBytes + 64
 
 /**
- * Preflight the update-bearing inner Yjs message before `readSyncMessage` can mutate the room. Legacy
- * clients use the unacknowledged sync channel, so the relay itself must ensure any applied update also
- * fits the durable Redis stream; checking only the outer frame leaves a small framing-sized gap.
+ * Checks the inner update before readSyncMessage mutates the room: the legacy outer-frame limit
+ * includes framing headroom, which must not allow an update too large for the shared stream.
  */
 function hasOversizedLegacyUpdate(bytes: Uint8Array): boolean {
   const decoder = decoding.createDecoder(bytes)
@@ -441,15 +440,11 @@ async function flushPersist(name: string, room: FileDocRoom, final: boolean): Pr
       await store.setSyncedVersion(name, result.version, generation)
       return
     }
-    // status === 'conflict': the durable file advanced out-of-band since our If-Match token. We do NOT
-    // re-persist against the current stream: an external write commits durable BEFORE its chokepoint merge
-    // (`applyEditToLiveFileDoc`) reaches the stream, so a re-persist landing in that window would CAS-pass
-    // with a stream that still lacks the external content and clobber the committed write. Instead leave the
-    // durable content authoritative — the chokepoint merges the change into the stream and, ONLY once it is
-    // actually there, advances the synced version (via the merge's own `recordVersion`); a later flush
-    // (a subsequent debounced persist, or the final flush) then projects the converged stream with a token
-    // that matches. The session's edits stay in the stream meanwhile. Deliberately do NOT advance the synced
-    // version here: before the stream reflects the durable content, that would let the next flush clobber it.
+    /**
+     * External writes commit before merging into the stream. Retrying or advancing the synced
+     * version here could overwrite content not yet merged; leave the durable file authoritative
+     * until the merge advances the version, then let a later flush persist the converged state.
+     */
     logger.warn(
       `Persist conflict for file ${room.fileId}; durable content advanced out-of-band, left authoritative`
     )
@@ -579,10 +574,8 @@ export async function flushAllFileDocRooms(): Promise<void> {
 }
 
 /**
- * Bring a room's document to its AUTHORITATIVE state — reflecting the file's shared stream and
- * carrying its seed — so the join can attach a client to a document that is already whole. Rejects
- * when hydration or seeding cannot complete; serving an unseeded or partial room would make a client
- * appear editable before the authoritative document exists.
+ * Waits for shared hydration and authoritative seeding before joining; failures must not expose
+ * an editable partial document.
  */
 async function ensureRoomReady(
   name: string,