@multiplatform.one/frappe 6.1.0 → 6.4.0

package/src/sync/debug.spec.ts

@@ -93,6 +93,42 @@ describe("SyncModule.__debug()", () => {
     expect(typeof debug.connection.socketConnected).toBe("boolean");
   });
 
+  it("treats missing navigator.onLine as online (React Native)", () => {
+    // RN has a navigator object but no onLine property — the old ternary
+    // surfaced `undefined`, rendering as "offline" in devtools.
+    const originalNavigator = globalThis.navigator;
+    Object.defineProperty(globalThis, "navigator", {
+      value: { product: "ReactNative" },
+      writable: true,
+      configurable: true,
+    });
+
+    expect(syncModule.__debug().connection.isOnline).toBe(true);
+
+    Object.defineProperty(globalThis, "navigator", {
+      value: originalNavigator,
+      writable: true,
+      configurable: true,
+    });
+  });
+
+  it("still reports offline when navigator.onLine is explicitly false (web)", () => {
+    const originalNavigator = globalThis.navigator;
+    Object.defineProperty(globalThis, "navigator", {
+      value: { onLine: false },
+      writable: true,
+      configurable: true,
+    });
+
+    expect(syncModule.__debug().connection.isOnline).toBe(false);
+
+    Object.defineProperty(globalThis, "navigator", {
+      value: originalNavigator,
+      writable: true,
+      configurable: true,
+    });
+  });
+
   it("mutation journal has correct structure", async () => {
     await syncModule.subscribe({
       doctype: "ToDo",

package/src/sync/filterValidation.spec.ts

@@ -0,0 +1,197 @@
+/**
+ * Filter toolkit contracts beyond matchesFilters (covered in filters.spec):
+ * schema validation (validateFilters strict/lenient), normalization of
+ * object filters to tuples, filter-field extraction, display formatting,
+ * getDoc fast-path extraction (extractSingleName), and the tree-operator
+ * client/server evaluation gate the sync engine keys off.
+ */
+
+import { describe, expect, it } from "vitest";
+import {
+  canEvaluateClientSide,
+  extractFilterFields,
+  extractSingleName,
+  FilterOperator,
+  formatFilter,
+  getClientEvaluationBlockers,
+  hasServerOnlyOperators,
+  isTreeOperator,
+  normalizeFilters,
+  validateFilters,
+  type FilterTuple,
+} from "./filters";
+
+const schema = [
+  { fieldname: "title", fieldtype: "Data" },
+  { fieldname: "amount", fieldtype: "Currency" },
+  { fieldname: "status", fieldtype: "Select" },
+  { fieldname: "attachment", fieldtype: "Attach" },
+];
+
+describe("validateFilters", () => {
+  it("passes valid filters against the schema", () => {
+    const result = validateFilters(
+      [
+        ["title", "like", "%report%"],
+        ["amount", ">", 100],
+        ["status", "in", ["Open", "Closed"]],
+      ],
+      schema,
+    );
+    expect(result.valid).toBe(true);
+    expect(result.errors).toEqual([]);
+    expect(result.warnings).toEqual([]);
+  });
+
+  it("treats empty filters as valid", () => {
+    expect(validateFilters(null, schema).valid).toBe(true);
+    expect(validateFilters(undefined, schema).valid).toBe(true);
+  });
+
+  it("accepts standard fields that are not in the schema", () => {
+    const result = validateFilters([["modified", ">", "2024-01-01"]], schema);
+    expect(result.valid).toBe(true);
+    expect(result.warnings).toEqual([]);
+  });
+
+  it("warns about unknown fields by default but errors in strict mode", () => {
+    const lenient = validateFilters([["custom_field", "=", 1]], schema);
+    expect(lenient.valid).toBe(true);
+    expect(lenient.warnings[0]).toContain("custom_field");
+
+    const strict = validateFilters([["custom_field", "=", 1]], schema, { strict: true });
+    expect(strict.valid).toBe(false);
+    expect(strict.errors[0]).toMatchObject({ field: "custom_field", code: "unknown_field" });
+  });
+
+  it("rejects invalid operators", () => {
+    const result = validateFilters([["title", "resembles", "x"]], schema);
+    expect(result.valid).toBe(false);
+    expect(result.errors[0]).toMatchObject({ field: "title", code: "invalid_operator" });
+  });
+
+  it("warns when LIKE is used on non-text fields", () => {
+    const result = validateFilters([["amount", "like", "%5%"]], schema);
+    expect(result.valid).toBe(true);
+    expect(result.warnings[0]).toContain("LIKE operator on non-text field");
+  });
+
+  it("warns when comparisons hit non-comparable fields", () => {
+    const result = validateFilters([["attachment", ">", 3]], schema);
+    expect(result.valid).toBe(true);
+    expect(result.warnings[0]).toContain("Comparison operator on non-numeric/date field");
+  });
+
+  it("requires arrays for IN and exactly two values for BETWEEN", () => {
+    const inResult = validateFilters([["status", "in", "Open"]], schema);
+    expect(inResult.valid).toBe(false);
+    expect(inResult.errors[0].code).toBe("invalid_value");
+
+    const betweenResult = validateFilters([["amount", "between", [1]]], schema);
+    expect(betweenResult.valid).toBe(false);
+    expect(betweenResult.errors[0].code).toBe("invalid_value");
+
+    const ok = validateFilters([["amount", "between", [1, 10]]], schema);
+    expect(ok.valid).toBe(true);
+  });
+
+  it("validates object-format filters for unknown fields", () => {
+    const lenient = validateFilters({ ghost: 1, title: "x" }, schema);
+    expect(lenient.valid).toBe(true);
+    expect(lenient.warnings).toHaveLength(1);
+
+    const strict = validateFilters({ ghost: 1 }, schema, { strict: true });
+    expect(strict.valid).toBe(false);
+    expect(strict.errors[0].field).toBe("ghost");
+  });
+});
+
+describe("normalizeFilters / extractFilterFields", () => {
+  it("passes tuple filters through and converts object filters to equality tuples", () => {
+    const tuples: FilterTuple[] = [["title", "like", "%x%"]];
+    expect(normalizeFilters(tuples)).toBe(tuples);
+    expect(normalizeFilters({ status: "Open", amount: 5 })).toEqual([
+      ["status", FilterOperator.Equals, "Open"],
+      ["amount", FilterOperator.Equals, 5],
+    ]);
+    expect(normalizeFilters(null)).toEqual([]);
+  });
+
+  it("extracts unique filter field names", () => {
+    expect(
+      extractFilterFields([
+        ["title", "like", "%a%"],
+        ["title", "!=", "b"],
+        ["amount", ">", 1],
+      ]),
+    ).toEqual(["title", "amount"]);
+    expect(extractFilterFields(null)).toEqual([]);
+  });
+});
+
+describe("formatFilter", () => {
+  it("formats scalar, string, array, and null values", () => {
+    expect(formatFilter(["amount", ">", 5])).toBe("amount > 5");
+    expect(formatFilter(["title", "like", "%x%"])).toBe('title like "%x%"');
+    expect(formatFilter(["status", "in", ["a", "b"]])).toBe('status in ["a", "b"]');
+    expect(formatFilter(["parent", "is", null])).toBe("parent is null");
+  });
+});
+
+describe("extractSingleName (getDoc fast path)", () => {
+  it("extracts the name from a single name-equality tuple", () => {
+    expect(extractSingleName([["name", "=", "DOC-001"]])).toBe("DOC-001");
+    expect(extractSingleName([["name", "==", "DOC-002"]])).toBe("DOC-002");
+  });
+
+  it("extracts the name from an object filter", () => {
+    expect(extractSingleName({ name: "DOC-003" })).toBe("DOC-003");
+  });
+
+  it("refuses multi-filter, non-name, non-equality, and non-string cases", () => {
+    expect(
+      extractSingleName([
+        ["name", "=", "DOC-001"],
+        ["status", "=", "Open"],
+      ]),
+    ).toBeUndefined();
+    expect(extractSingleName([["title", "=", "DOC-001"]])).toBeUndefined();
+    expect(extractSingleName([["name", "like", "DOC-%"]])).toBeUndefined();
+    expect(extractSingleName([["name", "=", 42]])).toBeUndefined();
+    expect(extractSingleName(null)).toBeUndefined();
+  });
+});
+
+describe("tree-operator evaluation gate", () => {
+  it("classifies tree operators as server-only", () => {
+    expect(isTreeOperator("ancestors of")).toBe(true);
+    expect(isTreeOperator("DESCENDANTS OF")).toBe(true);
+    expect(isTreeOperator("not ancestors of")).toBe(true);
+    expect(isTreeOperator("not descendants of")).toBe(true);
+    expect(isTreeOperator("=")).toBe(false);
+    expect(isTreeOperator("like")).toBe(false);
+  });
+
+  it("detects server-only operators inside filters", () => {
+    expect(hasServerOnlyOperators([["parent", "ancestors of", "Root"]])).toBe(true);
+    expect(hasServerOnlyOperators([["title", "like", "%x%"]])).toBe(false);
+    expect(hasServerOnlyOperators(null)).toBe(false);
+    expect(hasServerOnlyOperators({ status: "Open" })).toBe(false);
+  });
+
+  it("canEvaluateClientSide is the inverse gate", () => {
+    expect(canEvaluateClientSide([["parent", "descendants of", "Root"]])).toBe(false);
+    expect(canEvaluateClientSide([["status", "=", "Open"]])).toBe(true);
+  });
+
+  it("explains exactly which fields block client evaluation", () => {
+    const blockers = getClientEvaluationBlockers([
+      ["parent", "ancestors of", "Root"],
+      ["status", "=", "Open"],
+    ]);
+    expect(blockers).toHaveLength(1);
+    expect(blockers[0]).toContain('"parent"');
+    expect(blockers[0]).toContain("ancestors of");
+    expect(getClientEvaluationBlockers(null)).toEqual([]);
+  });
+});

package/src/sync/index.ts

@@ -17,9 +17,16 @@ import type {
   SyncOptions,
   FrappeDebugState,
   Mutation,
+  RealtimeEventType,
   SubscriptionQuery,
 } from "./types";
 
+/** Realtime event forwarded to `subscribeRealtimeEvents` listeners. */
+export interface SyncRealtimeEvent {
+  type: RealtimeEventType;
+  payload?: unknown;
+}
+
 /**
  * Synchronization engine that provides Zero-style UX on top of Frappe's REST API.
  *
@@ -70,6 +77,8 @@ export class SyncModule {
   private normalizedCache: NormalizedCache;
   private mutationJournal: MutationJournal;
   private storeListeners = new Set<() => void>();
+  /** Listeners registered via `subscribeRealtimeEvents`. */
+  private realtimeEventListeners = new Set<(event: SyncRealtimeEvent) => void>();
   private subscriptionManager: SubscriptionManager;
   /** Mutation engine for optimistic updates and conflict resolution. */
   private mutationEngine: MutationEngine;
@@ -81,16 +90,19 @@ export class SyncModule {
   private rehydrationManager: RehydrationManager;
   /** Cleanup functions returned by lifecycle subscriptions. */
   private cleanupFocus?: () => void;
+  private cleanupFocusReplay?: () => void;
   private cleanupOnlineBackfill?: () => void;
   private cleanupOnlineReplay?: () => void;
   /** Timer handle for periodic CDC polling. */
   private cdcIntervalHandle?: ReturnType<typeof setInterval>;
-
-  constructor(
-    private readonly db: DbModule,
-    private readonly realtime?: RealtimeModule,
-    private readonly options: SyncOptions = {},
-  ) {
+  private readonly db: DbModule;
+  private readonly realtime?: RealtimeModule;
+  private readonly options: SyncOptions;
+
+  constructor(db: DbModule, realtime?: RealtimeModule, options: SyncOptions = {}) {
+    this.db = db;
+    this.realtime = realtime;
+    this.options = options;
     // Initialize normalized cache with LRU eviction if maxCacheSize is set
     this.normalizedCache = new NormalizedCache({
       maxSize: this.options.maxCacheSize,
@@ -108,6 +120,7 @@ export class SyncModule {
       this.normalizedCache,
       this.subscriptionManager,
       this.mutationJournal,
+      () => this.emit(),
     );
 
     this.mutationEngine = new MutationEngine(
@@ -125,6 +138,13 @@ export class SyncModule {
       ...this.options,
       onResetCache: () => this.resetCache(),
       onBackfillAll: () => this.backfill({ scope: BackfillScope.All }),
+      // Realtime reconciliation mutates cache/membership outside the public
+      // mutate/backfill entry points — bridge those changes to store listeners.
+      onStoreChange: () => this.emit(),
+      onRealtimeEvent: (event) => {
+        this.options.onRealtimeEvent?.(event);
+        for (const listener of this.realtimeEventListeners) listener(event);
+      },
     };
 
     this.realtimeHandler = new RealtimeHandler(
@@ -153,6 +173,13 @@ export class SyncModule {
    */
   private setupWindowEvents() {
     this.cleanupFocus = onAppFocus(() => this.backfill({ scope: BackfillScope.All }));
+    // Journal replay on foreground: React Native never fires `online`
+    // (AppState is its only lifecycle signal), and on web this recovers
+    // server-restart cases where connectivity never flipped. Guarded so it
+    // is a strict no-op unless mutations are actually queued.
+    this.cleanupFocusReplay = onAppFocus(() => {
+      if (this.mutationJournal.listPending().length > 0) void this.replayPending();
+    });
     this.cleanupOnlineBackfill = onOnline(() => this.backfill({ scope: BackfillScope.All }));
     this.cleanupOnlineReplay = onOnline(() => this.replayPending());
 
@@ -166,10 +193,25 @@ export class SyncModule {
 
   /**
    * Creates a subscription, seeds cache with initial rows, and stores a backfill checkpoint.
+   *
+   * With persistence enabled, a query matching a subscription restored from
+   * the snapshot is re-adopted cache-first: the returned rows come from the
+   * restored cache and a background network refresh follows (`result.refresh`).
+   * If that refresh fails (offline), the cached membership keeps serving and
+   * the subscription is marked stale until the next successful backfill.
    */
   async subscribe<Data extends FrappeDocData>(query: SubscriptionQuery) {
+    // Wait for any persisted snapshot restore so a matching restored
+    // subscription can be adopted instead of racing the async load.
+    await this.persistenceManager.whenReady();
     const result = await this.subscriptionManager.subscribe<Data>(query);
+    // Join the doctype's realtime room so doc_update/list_update hints arrive
+    // for this subscription (refcounted; survives reconnects).
+    this.realtimeHandler.watchDoctype(query.doctype);
     this.emit();
+    // Adopted subscriptions refresh in the background; notify store listeners
+    // when the refresh lands (or marks the subscription stale). Never rejects.
+    if (result.refresh) void result.refresh.then(() => this.emit());
     return result;
   }
 
@@ -177,7 +219,9 @@ export class SyncModule {
    * Removes a subscription by id.
    */
   unsubscribe(subscriptionId: string) {
+    const subscription = this.subscriptionManager.getSubscription(subscriptionId);
     this.subscriptionManager.unsubscribe(subscriptionId);
+    if (subscription) this.realtimeHandler.unwatchDoctype(subscription.query.doctype);
     this.emit();
   }
 
@@ -279,6 +323,44 @@ export class SyncModule {
     };
   }
 
+  /**
+   * Registers a listener for raw realtime events (doc_update, list_update,
+   * doc_deleted, connected, …). Useful for consumers that manage their own
+   * fetching (e.g. server-side paginated tables) but still want live
+   * invalidation hints. Returns an unsubscribe function.
+   */
+  subscribeRealtimeEvents(listener: (event: SyncRealtimeEvent) => void): () => void {
+    this.realtimeEventListeners.add(listener);
+    return () => {
+      this.realtimeEventListeners.delete(listener);
+    };
+  }
+
+  /**
+   * Joins the realtime doctype room without creating a data subscription
+   * (refcounted). Pair with `unwatchDoctype` on cleanup. Used by consumers
+   * that fetch their own data but need the doctype's realtime hints.
+   */
+  watchDoctype(doctype: string): void {
+    this.realtimeHandler.watchDoctype(doctype);
+  }
+
+  /** Releases one `watchDoctype` reference. */
+  unwatchDoctype(doctype: string): void {
+    this.realtimeHandler.unwatchDoctype(doctype);
+  }
+
+  /**
+   * Live socket connection snapshot. `connected` is the state right now;
+   * `everConnected` distinguishes "reconnecting" from "realtime never up"
+   * (fixture mode, SSR, or no realtime module). Store listeners are
+   * notified on every flip, so read this inside a `subscribeStore` callback
+   * for a reactive indicator.
+   */
+  getConnectionState(): { connected: boolean; everConnected: boolean } {
+    return this.realtimeHandler.getConnectionState();
+  }
+
   /** Notifies listeners, schedules persistence, and broadcasts cross-tab changes. */
   private emit() {
     // Fan out local state changes to all subscribers
@@ -291,6 +373,8 @@ export class SyncModule {
 
   /** Clears subscriptions, cache, journal, and temp id mappings. */
   resetCache() {
+    // Leave all realtime doctype rooms alongside dropping the subscriptions
+    this.realtimeHandler.unwatchAll();
     // Drop all live subs, in-memory cache, journal, and temp mappings
     this.subscriptionManager.clear();
     this.normalizedCache.clear();
@@ -304,6 +388,7 @@ export class SyncModule {
   async dispose() {
     // Clear all listeners
     this.storeListeners.clear();
+    this.realtimeEventListeners.clear();
 
     // Clear subscriptions and cache
     this.resetCache();
@@ -317,9 +402,11 @@ export class SyncModule {
 
     // Remove lifecycle event listeners
     this.cleanupFocus?.();
+    this.cleanupFocusReplay?.();
     this.cleanupOnlineBackfill?.();
     this.cleanupOnlineReplay?.();
     this.cleanupFocus = undefined;
+    this.cleanupFocusReplay = undefined;
     this.cleanupOnlineBackfill = undefined;
     this.cleanupOnlineReplay = undefined;
 
@@ -350,6 +437,8 @@ export class SyncModule {
         tombstoneCount: sub.tombstones?.size ?? 0,
         checkpoint: sub.checkpoint,
         cursor: sub.cursor,
+        stale: sub.stale,
+        restored: this.subscriptionManager.isRestoredSubscription(sub.id),
         pageInfo,
       };
 
@@ -398,7 +487,9 @@ export class SyncModule {
       connection: {
         socketConnected: this.realtimeHandler.getIsConnected(),
         isLeader: this.persistenceManager.getIsLeader(),
-        isOnline: typeof navigator !== "undefined" ? navigator.onLine : true,
+        // React Native has navigator but no onLine (undefined) — treat
+        // anything other than an explicit false as online.
+        isOnline: typeof navigator === "undefined" || navigator.onLine !== false,
       },
     };
   }

package/src/sync/merge.ts

@@ -32,7 +32,7 @@ export function isObject(value: FrappeDocValue): value is Record<string, FrappeD
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
-export function isFrappeDoc(value: unknown): value is FrappeDoc<FrappeDocData> {
+function isFrappeDoc(value: unknown): value is FrappeDoc<FrappeDocData> {
   return (
     typeof value === "object" &&
     value !== null &&
@@ -290,7 +290,7 @@ export function merge<Data extends FrappeDocData = FrappeDocData>(
   };
 }
 
-export function mergeObject(
+function mergeObject(
   base: Record<string, FrappeDocValue>,
   client: Record<string, FrappeDocValue>,
   server: Record<string, FrappeDocValue>,
@@ -416,7 +416,7 @@ export function mergeChildTable(
   return sortChildTableByIdx(result);
 }
 
-export function sortChildTableByIdx(value: FrappeDocValue[]): FrappeDocValue[] {
+function sortChildTableByIdx(value: FrappeDocValue[]): FrappeDocValue[] {
   const hasIndexField = value.some(
     (row) => isChildTableRow(row) && row.idx !== null && typeof row.idx === "number",
   );

package/src/sync/mutationEngine.spec.ts

@@ -603,6 +603,38 @@ describe("MutationEngine", () => {
         // Should not fetch the document after successful mutation
         expect(mockDb.getDoc).not.toHaveBeenCalled();
       });
+
+      it("should not refetch the deleted doc itself on delete when realtime is unhealthy", async () => {
+        // Regression: the post-mutation refetch used to include the DELETED
+        // doc — the server 404s, routing a confirmed delete into the
+        // error/rollback path (surfaced by FrappeTreeView's live delete spec
+        // running against a realtime-less fixture sync module).
+        mockRealtime.isHealthy.mockReturnValue(false);
+        mockDb.getDoc.mockClear();
+        mockDb.getDoc.mockImplementation(async (doctype: string, name: string) => {
+          if (doctype === "TestDoc" && name === "test-doc") {
+            throw new Error(`Document ${doctype}/${name} not found`);
+          }
+          return { ...mockDoc, doctype, name };
+        });
+
+        const mutation: DeleteMutation<FrappeDocData> = {
+          mutationId: "mut-del-refetch",
+          operation: Operation.Delete,
+          doc: { doctype: "TestDoc", name: "test-doc" },
+          version: undefined,
+          affected: [{ doctype: "RelatedDoc", name: "related-doc" }],
+        };
+
+        await mutationEngine.mutate(mutation);
+
+        // The tombstoned doc is never refetched…
+        expect(mockDb.getDoc).not.toHaveBeenCalledWith("TestDoc", "test-doc");
+        // …while related docs still refresh.
+        expect(mockDb.getDoc).toHaveBeenCalledWith("RelatedDoc", "related-doc");
+        expect(mockMutationJournal.confirm).toHaveBeenCalledWith("mut-del-refetch");
+        expect(mockMutationJournal.fail).not.toHaveBeenCalled();
+      });
     });
   });
 
@@ -680,8 +712,8 @@ describe("MutationEngine", () => {
 
       await expect(mutationEngine.mutate(mutation)).rejects.toThrow("Update failed");
 
-      // Should restore snapshot
-      expect(mockNormalizedCache.upsert).toHaveBeenCalledWith(mockDoc);
+      // Should restore snapshot wholesale (replace, not merge)
+      expect(mockNormalizedCache.upsert).toHaveBeenCalledWith(mockDoc, { replace: true });
     });
 
     it("should not rollback when offline", async () => {
@@ -1022,8 +1054,8 @@ describe("MutationEngine", () => {
 
       // Should still attempt snapshot rollback (upsert is called twice: once for optimistic update, once for rollback)
       expect(mockNormalizedCache.upsert).toHaveBeenCalledTimes(2);
-      // Last call should be the rollback with original snapshot
-      expect(mockNormalizedCache.upsert).toHaveBeenLastCalledWith(mockDoc);
+      // Last call should be the rollback with original snapshot (wholesale replace)
+      expect(mockNormalizedCache.upsert).toHaveBeenLastCalledWith(mockDoc, { replace: true });
     });
 
     it("should handle custom version fields", async () => {

package/src/sync/mutationEngine.ts

@@ -47,16 +47,30 @@ export class MutationEngine {
   private pendingBatch: PendingBatchMutation<FrappeDocData>[] = [];
   /** Debouncer for batch processing */
   private batchDebouncer: Debouncer<() => Promise<void>>;
+  private readonly db: DbModule;
+  private readonly realtime: RealtimeModule | undefined;
+  private readonly normalizedCache: NormalizedCache;
+  private readonly mutationJournal: MutationJournal;
+  private readonly subscriptionManager: SubscriptionManager;
+  private readonly rehydrationManager: RehydrationManager;
+  private readonly options: SyncOptions;
 
   constructor(
-    private readonly db: DbModule,
-    private readonly realtime: RealtimeModule | undefined,
-    private readonly normalizedCache: NormalizedCache,
-    private readonly mutationJournal: MutationJournal,
-    private readonly subscriptionManager: SubscriptionManager,
-    private readonly rehydrationManager: RehydrationManager,
-    private readonly options: SyncOptions = {},
+    db: DbModule,
+    realtime: RealtimeModule | undefined,
+    normalizedCache: NormalizedCache,
+    mutationJournal: MutationJournal,
+    subscriptionManager: SubscriptionManager,
+    rehydrationManager: RehydrationManager,
+    options: SyncOptions = {},
   ) {
+    this.db = db;
+    this.realtime = realtime;
+    this.normalizedCache = normalizedCache;
+    this.mutationJournal = mutationJournal;
+    this.subscriptionManager = subscriptionManager;
+    this.rehydrationManager = rehydrationManager;
+    this.options = options;
     // Initialize batch debouncer
     const batchDelay = options.batchDelay ?? 100;
     this.batchDebouncer = new Debouncer(() => this.flushBatch(), { wait: batchDelay });
@@ -434,7 +448,11 @@ export class MutationEngine {
     const docname = mutation.doc.name;
     const doctype = mutation.doc.doctype;
     const realName = (docname && this.temporaryIdToRealNameMap.get(docname)) || docname;
-    if (realName) targets.push({ doctype, name: realName });
+    // A deleted doc no longer exists server-side — refetching it would 404
+    // and route a server-confirmed delete into the error/rollback path.
+    if (realName && mutation.operation !== Operation.Delete) {
+      targets.push({ doctype, name: realName });
+    }
     if (mutation.affected?.length) targets.push(...mutation.affected);
     // Fetch each target with user context to respect permissions and hidden fields
     for (const target of targets) {
@@ -493,9 +511,10 @@ export class MutationEngine {
         break;
 
       case Operation.Update:
-        // Restore the original document from snapshot
+        // Restore the original document from snapshot (wholesale: an
+        // optimistic update may have added keys the snapshot never had)
         if (entry?.snapshot && docname) {
-          this.normalizedCache.upsert(entry.snapshot);
+          this.normalizedCache.upsert(entry.snapshot, { replace: true });
           // Also update subscription memberships in case filters changed
           this.subscriptionManager.updateSubscriptionMembership(
             entry.snapshot as FrappeDoc<FrappeDocData>,
@@ -506,7 +525,7 @@ export class MutationEngine {
       case Operation.Delete:
         // Restore the deleted document from snapshot
         if (entry?.snapshot && docname) {
-          this.normalizedCache.upsert(entry.snapshot);
+          this.normalizedCache.upsert(entry.snapshot, { replace: true });
           // Re-add to subscription memberships
           const restoredDoc = entry.snapshot as FrappeDoc<FrappeDocData>;
           for (const subscription of this.subscriptionManager.getAllSubscriptions().values()) {

package/src/sync/mutationJournal.ts

@@ -27,6 +27,7 @@ export interface MutationJournalOptions {
 
 export class MutationJournal {
   private cleanupTimer?: ReturnType<typeof setInterval>;
+  private autoCleanupEnabled: boolean;
   private ttl = 24 * 60 * 60 * 1000;
   private pending = new Map<string, Pending>();
   private sequenceNumber = 0;
@@ -40,9 +41,12 @@ export class MutationJournal {
       this.storage = options.storage;
       this.loadSequenceNumber();
     }
-    if (options?.enableAutoCleanup !== false) {
-      this.startAutoCleanup();
-    }
+    // Auto-cleanup is armed lazily on the first add() rather than at
+    // construction: an empty journal has nothing to expire, and an
+    // unconditional interval was a leaked handle for every SyncModule that
+    // never mutated (one per fixture set in tests/stories — the pending
+    // hour-long timers helped wedge vitest forks-worker teardown).
+    this.autoCleanupEnabled = options?.enableAutoCleanup !== false;
   }
 
   add(id: string, entry: Pending) {
@@ -51,6 +55,7 @@ export class MutationJournal {
     if (entry.ttl === undefined) entry.ttl = this.ttl;
     if (entry.retryCount === undefined) entry.retryCount = 0;
     this.pending.set(id, entry);
+    if (this.autoCleanupEnabled) this.startAutoCleanup();
     this.persistSequenceNumber();
   }
 
@@ -124,6 +129,7 @@ export class MutationJournal {
 
   clear() {
     this.pending.clear();
+    this.stopAutoCleanup();
   }
 
   dispose() {
@@ -141,7 +147,15 @@ export class MutationJournal {
   }
 
   private startAutoCleanup() {
-    this.cleanupTimer = setInterval(() => this.cleanupExpired(), 60 * 60 * 1000);
+    if (this.cleanupTimer) return;
+    this.cleanupTimer = setInterval(
+      () => {
+        this.cleanupExpired();
+        // Disarm once drained; the next add() re-arms.
+        if (this.pending.size === 0) this.stopAutoCleanup();
+      },
+      60 * 60 * 1000,
+    );
   }
 
   private loadSequenceNumber() {