1 files changed, 69 insertions, 9 deletions

diff --git a/src/features/conversation-cache/cache.ts b/src/features/conversation-cache/cache.ts
index 4953944..600a6e6 100644
--- a/src/features/conversation-cache/cache.ts
+++ b/src/features/conversation-cache/cache.ts
@@ -3,6 +3,22 @@ import { nextSinceSeq, reconcileCache, selectEvictions } from "./logic";
 import type { ConversationChunkStore } from "./types";
 
 export interface ConversationCache {
+  historyEpoch(conversationId: string): Promise<number | undefined>;
+  reset(conversationId: string, historyEpoch: number): Promise<void>;
+
+  /**
+   * Replace from a fresh full-history response, including an epoch decrease.
+   * Only succeeds if the cache still has the epoch observed BEFORE that request.
+   * Unlike monotonic reset/commit, this is for confirmed server authority, not
+   * broadcasts or cursor/backfill responses. False means the response is stale.
+   */
+  replace(
+    conversationId: string,
+    incoming: readonly StoredChunk[],
+    historyEpoch: number,
+    expectedEpoch: number | undefined,
+  ): Promise<boolean>;
+
   /** Load all cached chunks for a conversation. */
   load(conversationId: string): Promise<readonly StoredChunk[]>;
 
@@ -10,7 +26,11 @@ export interface ConversationCache {
    * Load + reconcile + append new chunks.
    * Returns the merged cache (the new authoritative cache for this conversation).
    */
-  commit(conversationId: string, incoming: readonly StoredChunk[]): Promise<readonly StoredChunk[]>;
+  commit(
+    conversationId: string,
+    incoming: readonly StoredChunk[],
+    historyEpoch?: number,
+  ): Promise<readonly StoredChunk[]>;
 
   /** Return the `?sinceSeq=` cursor for the next incremental sync. */
   sinceSeq(conversationId: string): Promise<number>;
@@ -43,21 +63,61 @@ export function createConversationCache(
 ): ConversationCache {
   const maxChunks = opts?.maxChunks ?? DEFAULT_MAX_CHUNKS;
 
+  // Serialize mutation per conversation, including invalidation, so an old fetch
+  // cannot resurrect rows after a compaction broadcast has invalidated them.
+  const pending = new Map<string, Promise<unknown>>();
+  function exclusive<T>(id: string, run: () => Promise<T>): Promise<T> {
+    const next = (pending.get(id) ?? Promise.resolve()).catch(() => {}).then(run);
+    pending.set(id, next);
+    void next
+      .finally(() => {
+        if (pending.get(id) === next) pending.delete(id);
+      })
+      .catch(() => {});
+    return next;
+  }
   return {
+    historyEpoch: async (id) => {
+      await pending.get(id);
+      return store.historyEpoch(id);
+    },
+    reset: (id, epoch) =>
+      exclusive(id, async () => {
+        const current = await store.historyEpoch(id);
+        if (current === undefined || current < epoch) await store.reset(id, epoch);
+      }),
+    replace: (id, incoming, epoch, expectedEpoch) =>
+      exclusive(id, async () => {
+        if ((await store.historyEpoch(id)) !== expectedEpoch) return false;
+        await store.reset(id, epoch);
+        if (incoming.length > 0) await store.append(id, incoming);
+        return true;
+      }),
     async load(conversationId) {
+      await pending.get(conversationId);
       return store.load(conversationId);
     },
 
-    async commit(conversationId, incoming) {
-      const cached = await store.load(conversationId);
-      const { merged, toAppend } = reconcileCache(cached, incoming);
-      if (toAppend.length > 0) {
-        await store.append(conversationId, toAppend);
-      }
-      return merged;
+    commit(conversationId, incoming, epoch) {
+      return exclusive(conversationId, async () => {
+        if (epoch !== undefined) {
+          const current = await store.historyEpoch(conversationId);
+          // Once an epoch is known, only explicit invalidation or guarded
+          // full-history replacement may change it (in either direction).
+          if (current !== undefined && current !== epoch) return store.load(conversationId);
+          if (current !== epoch) await store.reset(conversationId, epoch);
+        }
+        const cached = await store.load(conversationId);
+        const { merged, toAppend } = reconcileCache(cached, incoming);
+        if (toAppend.length > 0) {
+          await store.append(conversationId, toAppend);
+        }
+        return merged;
+      });
     },
 
     async sinceSeq(conversationId) {
+      await pending.get(conversationId);
       const cached = await store.load(conversationId);
       return nextSinceSeq(cached);
     },
@@ -72,7 +132,7 @@ export function createConversationCache(
     },
 
     async delete(conversationId) {
-      await store.delete(conversationId);
+      await exclusive(conversationId, () => store.delete(conversationId));
     },
   };
 }