cry-synced-db-client 0.1.219 → 2.0.0

package/CHANGELOG.md

@@ -1,5 +1,73 @@
 # Versions
 
+## 2.0.0 (2026-07-10)
+
+### Dual-channel ebus support: `db/` + `dbbracketed/`
+
+`Ebus2ProxyServerUpdateNotifier` now subscribes to **both** channels simultaneously:
+
+| Channel | Payload | Use case |
+|---|---|---|
+| `db/` | Full document object (`operation: insert/update/delete`) | Legacy; full object replication |
+| `dbbracketed/` | Diff (`bracketedData: { "field": value, "arr[id].sub": value }`) | Bandwidth-efficient; only changed fields |
+
+Both channels carry `pub_ts` (publisher timestamp) at batch level. The client
+uses `pub_ts` for cross-channel dedup — if the same batch arrives on both
+channels, only the first one is processed.
+
+**Server-side:** cry-db ≥ 2.5.x emits both channels for every change. The
+diff is produced by `computeObjDiff` (same function the client uses for dirty
+changes), so the format is identical end-to-end.
+
+**Client-side (`ServerUpdateHandler`):**
+- `_rev`-based stale/self-echo/gap detection shared across both channels
+- `checkRev()` returns: `ignore` | `bump-meta` | `apply` | `fetch-full`
+- For `dbbracketed/` diffs: `applyObjDiff` from cry-db applies the diff locally
+- `undefined` values in diffs trigger `deleteByPath` (mongo `$unset` symmetric)
+- On gap (`incomingRev > localRev + 1`): fetches full doc from server via
+  `findById` (we're online because WS is connected); if fetch fails, fires
+  `onEbusUpdateSkipped` and skips
+
+**Why `insert()` instead of `save()` for bracketed diffs:**
+Dexie's `update()` only touches fields present in the payload — it does NOT
+delete fields. When `applyObjDiff` produces a diff with `{ field: undefined }`
+(signaling deletion via `deleteByPath`), we must use `put()` (`insert()` in our
+interface) to replace the entire row, ensuring deleted fields are actually
+removed locally.
+
+**Diagnostic callbacks:**
+```typescript
+new SyncedDb({
+  onEbusNotificationReceived: (info) => {
+    // info: { payload, channel: "db" | "dbbracketed", collection, timestamp }
+    syslog.debug("ebus", info);
+  },
+  onEbusUpdateSkipped: (info) => {
+    // info: { collection, _id, incomingRev, localRev, reason, timestamp }
+    // reason: "fetch-failed" (gap detected but findById failed)
+    syslog.warn("ebus skip", info);
+  },
+});
+```
+
+### Generic `_rev` check for all server notifications
+
+Previously only self-echoed updates (same `_lastUpdaterId`) were handled.
+Now every incoming item runs through `checkRev()`:
+- `incomingRev <= localRev` → ignore (stale/duplicate)
+- `incomingRev === localRev + 1 && incomingUpdaterId === local._lastUpdaterId`
+  → bump-meta (clear dirty, advance rev)
+- `incomingRev === localRev + 1 && different updater` → apply (external update)
+- `incomingRev > localRev + 1` → fetch-full (gap; online because WS is connected)
+
+### Backward compatibility
+
+All existing public API is unchanged. Both `db/` and `dbbracketed/` channels
+are handled transparently. Legacy servers (cry-db < 2.5.x) that only emit
+`db/` work identically to before.
+
+---
+
 ## 0.1.216 (2026-06-25)
 
 ### `onSyncProgress` fires for every chunk (not just first per collection)

package/dist/index.js

@@ -4444,6 +4444,8 @@ var SyncEngine = class {
 // src/db/sync/ServerUpdateHandler.ts
 var ServerUpdateHandler = class {
   constructor(config) {
+    /** Per-collection last processed pub_ts for cross-channel dedup. */
+    this.lastProcessedPubTs = /* @__PURE__ */ new Map();
     this.tenant = config.tenant;
     this.updaterId = config.updaterId;
     this.collections = config.collections;
@@ -4452,22 +4454,220 @@ var ServerUpdateHandler = class {
     this.callbacks = config.callbacks;
     this.deps = config.deps;
   }
+  // ============================================================
+  // Entry point
+  // ============================================================
   /**
    * Handle incoming server update (WebSocket notification).
+   * Accepts both db/ (full-object) and dbbracketed/ (diff) payloads.
    */
   async handleServerUpdate(payload) {
+    this.callOnEbusNotificationReceived(payload);
     this.callOnWsNotification(payload);
     if (!this.deps.isLeader()) return;
     if (!this.deps.canReceiveServerUpdates()) return;
     const collectionName = payload.collection;
     if (!this.collections.has(collectionName)) return;
     if (!this.deps.isSyncAllowed(collectionName)) return;
+    const pubTs = payload.pub_ts;
+    if (this.wasAlreadyProcessed(collectionName, pubTs)) {
+      return;
+    }
+    const isBracketed = this.isBracketedPayload(payload);
+    const updatedIds = isBracketed ? await this.handleBracketedBatch(collectionName, payload) : await this.handleLegacyBatch(collectionName, payload);
+    if (updatedIds.length > 0) {
+      this.deps.broadcastUpdates({ [collectionName]: updatedIds });
+    }
+  }
+  // ============================================================
+  // pub_ts dedup
+  // ============================================================
+  /**
+   * Check if this batch was already processed (duplicate or stale pub_ts).
+   * Updates lastProcessedPubTs when a new pub_ts is seen.
+   */
+  wasAlreadyProcessed(collection, pubTs) {
+    if (pubTs == null) return false;
+    const last = this.lastProcessedPubTs.get(collection);
+    if (last != null && pubTs <= last) {
+      return true;
+    }
+    this.lastProcessedPubTs.set(collection, pubTs);
+    return false;
+  }
+  isBracketedPayload(payload) {
+    if (payload.operation !== "batch") return false;
+    const batch = payload;
+    return batch.data.length > 0 && batch.data[0].bracketedData !== void 0;
+  }
+  // ============================================================
+  // Bracketed batch (dbbracketed/ channel)
+  // ============================================================
+  async handleBracketedBatch(collection, payload) {
+    const updatedIds = [];
+    for (const item of payload.data) {
+      const processed = await this.processBracketedItem(collection, item);
+      if (processed) updatedIds.push(String(item._id));
+    }
+    return updatedIds;
+  }
+  async processBracketedItem(collection, item) {
+    var _a, _b, _c, _d, _e, _f;
+    const localItem = await this.dexieDb.getById(collection, item._id);
+    if (!localItem) {
+      if (item.operation === "insert" && item.bracketedData) {
+        await this.handleServerItemInsert(collection, item.bracketedData);
+        return true;
+      }
+      const fullItem = await this.safeFindById(collection, item._id);
+      if (fullItem) {
+        await this.handleServerItemInsert(collection, fullItem);
+        return true;
+      }
+      return false;
+    }
+    const revAction = this.checkRev(
+      item._rev,
+      item._ts,
+      void 0,
+      // bracketedData doesn't carry _lastUpdaterId
+      localItem
+    );
+    switch (revAction) {
+      case "ignore":
+        return false;
+      case "bump-meta": {
+        await this.dexieDb.save(collection, item._id, {
+          _rev: item._rev,
+          _ts: item._ts
+        });
+        await this.dexieDb.clearDirtyChange(collection, item._id);
+        return false;
+      }
+      case "fetch-full": {
+        const fullItem = await this.safeFindById(collection, item._id);
+        if (fullItem) {
+          await this.dexieDb.insert(collection, fullItem);
+          this.deps.writeToInMemBatch(
+            collection,
+            [this.stripLocalFields(fullItem)],
+            "upsert",
+            { source: "incremental" }
+          );
+          return true;
+        }
+        this.callOnEbusUpdateSkipped({
+          collection,
+          _id: item._id,
+          incomingRev: (_a = item._rev) != null ? _a : 0,
+          localRev: (_b = localItem._rev) != null ? _b : 0,
+          reason: "fetch-failed"
+        });
+        return false;
+      }
+      case "apply":
+        break;
+    }
+    const pendingChange = this.deps.getPendingChange(collection, item._id);
+    if (pendingChange && item.operation === "update") {
+      const diff = this.stripMetaFromDiff(item.bracketedData);
+      const currentInMemState = Object.assign({}, localItem, pendingChange.data);
+      const merged = applyObjDiff(currentInMemState, diff, item._id, "bracketed");
+      merged._rev = (_c = item._rev) != null ? _c : localItem._rev;
+      merged._ts = (_d = item._ts) != null ? _d : localItem._ts;
+      if (!merged._deleted && !merged._archived) {
+        this.deps.writeToInMemBatch(collection, [this.stripLocalFields(merged)], "upsert", {
+          source: "incremental"
+        });
+      }
+      return true;
+    }
+    const dirtyChange = await this.dexieDb.getDirtyChange(collection, item._id);
+    if (dirtyChange && item.operation === "update") {
+      const diff = this.stripMetaFromDiff(item.bracketedData);
+      const merged = applyObjDiff(localItem, diff, item._id, "bracketed");
+      merged._rev = (_e = item._rev) != null ? _e : localItem._rev;
+      merged._ts = (_f = item._ts) != null ? _f : localItem._ts;
+      if (!merged._deleted && !merged._archived) {
+        await this.dexieDb.insert(collection, merged);
+        this.deps.writeToInMemBatch(collection, [this.stripLocalFields(merged)], "upsert", {
+          source: "incremental"
+        });
+      } else {
+        await this.dexieDb.save(collection, item._id, { _deleted: /* @__PURE__ */ new Date() });
+        this.deps.writeToInMemBatch(collection, [{ _id: item._id }], "delete", {
+          source: "incremental"
+        });
+      }
+      return true;
+    }
+    switch (item.operation) {
+      case "insert": {
+        await this.handleServerItemInsert(collection, item.bracketedData);
+        return true;
+      }
+      case "update": {
+        const merged = this.applyBracketedDiff(localItem, item);
+        if (!merged._deleted && !merged._archived) {
+          await this.dexieDb.insert(collection, merged);
+          this.deps.writeToInMemBatch(collection, [this.stripLocalFields(merged)], "upsert", {
+            source: "incremental"
+          });
+        } else {
+          await this.dexieDb.deleteOne(collection, item._id);
+          this.deps.writeToInMemBatch(collection, [{ _id: item._id }], "delete", {
+            source: "incremental"
+          });
+        }
+        return true;
+      }
+      case "delete": {
+        await this.handleServerItemDelete(collection, item._id);
+        return true;
+      }
+    }
+    return false;
+  }
+  /**
+   * Apply a bracketed diff to a local item using cry-db's applyObjDiff.
+   * Strips meta fields from the diff, then applies _rev/_ts from the item level.
+   */
+  applyBracketedDiff(localItem, item) {
+    var _a, _b;
+    const diff = this.stripMetaFromDiff(item.bracketedData);
+    const merged = applyObjDiff(localItem, diff, item._id, "bracketed");
+    merged._rev = (_a = item._rev) != null ? _a : localItem._rev;
+    merged._ts = (_b = item._ts) != null ? _b : localItem._ts;
+    return merged;
+  }
+  /**
+   * Strip _id, _rev, _ts, _lastUpdaterId from a diff object before applyObjDiff.
+   *
+   * IMPORTANT: Uses for...in instead of Object.keys() because Object.keys()
+   * skips properties whose value is undefined. Bracketed diffs may contain
+   * {field: undefined} to signal field deletion (translated by applyObjDiff
+   * to deleteByPath). Skipping such keys would silently ignore deletions.
+   */
+  stripMetaFromDiff(diff) {
+    if (diff == null || typeof diff !== "object") return diff;
+    const result = {};
+    for (const key in diff) {
+      if (!Object.prototype.hasOwnProperty.call(diff, key)) continue;
+      if (key === "_id" || key === "_rev" || key === "_ts" || key === "_lastUpdaterId") continue;
+      result[key] = diff[key];
+    }
+    return result;
+  }
+  // ============================================================
+  // Legacy batch (db/ channel)
+  // ============================================================
+  async handleLegacyBatch(collection, payload) {
     const updatedIds = [];
     switch (payload.operation) {
       case "insert": {
         const serverItem = payload.data;
         if (serverItem) {
-          await this.handleServerItemInsert(collectionName, serverItem);
+          await this.handleServerItemInsert(collection, serverItem);
           updatedIds.push(String(serverItem._id));
         }
         break;
@@ -4475,20 +4675,14 @@ var ServerUpdateHandler = class {
       case "update": {
         const deltaData = payload.data;
         if (deltaData && deltaData._id) {
-          const localItem = await this.dexieDb.getById(
-            collectionName,
-            deltaData._id
-          );
+          const localItem = await this.dexieDb.getById(collection, deltaData._id);
           if (localItem) {
-            await this.handleServerItemUpdate(collectionName, localItem, deltaData);
+            await this.handleServerItemUpdate(collection, localItem, deltaData);
             updatedIds.push(String(deltaData._id));
           } else {
-            const fullItem = await this.restInterface.findById(
-              collectionName,
-              deltaData._id
-            );
+            const fullItem = await this.safeFindById(collection, deltaData._id);
             if (fullItem) {
-              await this.handleServerItemInsert(collectionName, fullItem);
+              await this.handleServerItemInsert(collection, fullItem);
               updatedIds.push(String(fullItem._id));
             }
           }
@@ -4497,7 +4691,7 @@ var ServerUpdateHandler = class {
       }
       case "delete": {
         const deleteData = payload.data;
-        await this.handleServerItemDelete(collectionName, deleteData._id);
+        await this.handleServerItemDelete(collection, deleteData._id);
         updatedIds.push(String(deleteData._id));
         break;
       }
@@ -4516,9 +4710,7 @@ var ServerUpdateHandler = class {
         }
         if (inserts.length > 0) {
           await Promise.all(
-            inserts.map(
-              (serverItem) => this.handleServerItemInsert(collectionName, serverItem)
-            )
+            inserts.map((serverItem) => this.handleServerItemInsert(collection, serverItem))
           );
           for (const serverItem of inserts) {
             updatedIds.push(String(serverItem._id));
@@ -4526,7 +4718,7 @@ var ServerUpdateHandler = class {
         }
         if (updates.length > 0) {
           const updateIds = updates.map((u) => u._id);
-          const localItems = await this.dexieDb.getByIds(collectionName, updateIds);
+          const localItems = await this.dexieDb.getByIds(collection, updateIds);
           const missingIds = [];
           const updatePromises = [];
           for (let i = 0; i < updates.length; i++) {
@@ -4534,7 +4726,7 @@ var ServerUpdateHandler = class {
             const localItem = localItems[i];
             if (localItem) {
               updatePromises.push(
-                this.handleServerItemUpdate(collectionName, localItem, deltaData)
+                this.handleServerItemUpdate(collection, localItem, deltaData)
               );
               updatedIds.push(String(deltaData._id));
             } else {
@@ -4544,15 +4736,13 @@ var ServerUpdateHandler = class {
           if (updatePromises.length > 0) await Promise.all(updatePromises);
           if (missingIds.length > 0) {
             const fullItems = await this.restInterface.findByIds(
-              collectionName,
+              collection,
               missingIds
             );
             const insertPromises = [];
             for (const fullItem of fullItems) {
               if (!fullItem) continue;
-              insertPromises.push(
-                this.handleServerItemInsert(collectionName, fullItem)
-              );
+              insertPromises.push(this.handleServerItemInsert(collection, fullItem));
               updatedIds.push(String(fullItem._id));
             }
             if (insertPromises.length > 0) await Promise.all(insertPromises);
@@ -4560,7 +4750,7 @@ var ServerUpdateHandler = class {
         }
         if (deletes.length > 0) {
           await Promise.all(
-            deletes.map((d) => this.handleServerItemDelete(collectionName, d._id))
+            deletes.map((d) => this.handleServerItemDelete(collection, d._id))
           );
           for (const deleteData of deletes) {
             updatedIds.push(String(deleteData._id));
@@ -4569,10 +4759,53 @@ var ServerUpdateHandler = class {
         break;
       }
     }
-    if (updatedIds.length > 0) {
-      this.deps.broadcastUpdates({ [collectionName]: updatedIds });
+    return updatedIds;
+  }
+  // ============================================================
+  // Rev-check (shared across both channels)
+  // ============================================================
+  /**
+   * Determine action based on incoming vs local revision.
+   *
+   * | incomingRev | Action      | Reason                                    |
+   * |-------------|-------------|-------------------------------------------|
+   * | ≤ localRev  | ignore      | Stale / duplicate / self-echo after WB    |
+   * | = local+1   | bump-meta   | Self-echo before WB (only if updaterId matches) |
+   * | = local+1   | apply       | External update (updaterId mismatch)      |
+   * | > local+1   | fetch-full  | Gap — missed intermediate updates; fetch  |
+   *               |             | full doc since we're online (WS connected).|
+   * | undefined   | apply       | Legacy server / no rev tracking           |
+   */
+  checkRev(incomingRev, incomingTs, incomingUpdaterId, localItem) {
+    const localRev = localItem._rev;
+    if (typeof incomingRev !== "number" || typeof localRev !== "number") {
+      return "apply";
+    }
+    if (incomingRev <= localRev) {
+      return "ignore";
+    }
+    if (incomingRev === localRev + 1) {
+      const updaterId = incomingUpdaterId != null ? incomingUpdaterId : localItem._lastUpdaterId;
+      if (updaterId === this.updaterId) {
+        return "bump-meta";
+      }
+      return "apply";
+    }
+    return "fetch-full";
+  }
+  // ============================================================
+  // Safe fetch helper
+  // ============================================================
+  async safeFindById(collection, id) {
+    try {
+      return await this.restInterface.findById(collection, id);
+    } catch (e) {
+      return null;
     }
   }
+  // ============================================================
+  // Per-item handlers (unchanged logic, now called from both branches)
+  // ============================================================
   /**
    * Handle server item insert.
    */
@@ -4596,17 +4829,27 @@ var ServerUpdateHandler = class {
         await this.dexieDb.clearDirtyChange(collection, serverItem._id);
       }
       if (!serverItem._deleted && !serverItem._archived) {
-        this.deps.writeToInMemBatch(collection, [this.stripLocalFields(serverItem)], "upsert", { source: "incremental" });
+        this.deps.writeToInMemBatch(
+          collection,
+          [this.stripLocalFields(serverItem)],
+          "upsert",
+          { source: "incremental" }
+        );
       }
     } else {
       await this.dexieDb.insert(collection, serverItem);
       if (!serverItem._deleted && !serverItem._archived) {
-        this.deps.writeToInMemBatch(collection, [this.stripLocalFields(serverItem)], "upsert", { source: "incremental" });
+        this.deps.writeToInMemBatch(
+          collection,
+          [this.stripLocalFields(serverItem)],
+          "upsert",
+          { source: "incremental" }
+        );
       }
     }
   }
   /**
-   * Handle server item update (delta).
+   * Handle server item update (delta) — db/ channel only.
    */
   async handleServerItemUpdate(collection, localItem, serverDelta) {
     const serverRev = serverDelta._rev;
@@ -4631,7 +4874,12 @@ var ServerUpdateHandler = class {
       const currentInMemState = Object.assign({}, localItem, pendingChange.data);
       const merged = this.mergeLocalWithDelta(currentInMemState, serverDelta);
       if (!merged._deleted && !merged._archived) {
-        this.deps.writeToInMemBatch(collection, [this.stripLocalFields(merged)], "upsert", { source: "incremental" });
+        this.deps.writeToInMemBatch(
+          collection,
+          [this.stripLocalFields(merged)],
+          "upsert",
+          { source: "incremental" }
+        );
       }
       return;
     }
@@ -4643,16 +4891,31 @@ var ServerUpdateHandler = class {
         await this.dexieDb.save(collection, serverDelta._id, merged);
       }
       if (!merged._deleted && !merged._archived) {
-        this.deps.writeToInMemBatch(collection, [this.stripLocalFields(merged)], "upsert", { source: "incremental" });
+        this.deps.writeToInMemBatch(
+          collection,
+          [this.stripLocalFields(merged)],
+          "upsert",
+          { source: "incremental" }
+        );
       }
     } else {
       if (!metaChanged) return;
       const merged = this.mergeLocalWithDelta(localItem, serverDelta);
       await this.dexieDb.save(collection, serverDelta._id, merged);
       if (!merged._deleted && !merged._archived) {
-        this.deps.writeToInMemBatch(collection, [this.stripLocalFields(merged)], "upsert", { source: "incremental" });
+        this.deps.writeToInMemBatch(
+          collection,
+          [this.stripLocalFields(merged)],
+          "upsert",
+          { source: "incremental" }
+        );
       } else {
-        this.deps.writeToInMemBatch(collection, [{ _id: serverDelta._id }], "delete", { source: "incremental" });
+        this.deps.writeToInMemBatch(
+          collection,
+          [{ _id: serverDelta._id }],
+          "delete",
+          { source: "incremental" }
+        );
       }
     }
   }
@@ -4668,7 +4931,12 @@ var ServerUpdateHandler = class {
     } else {
       await this.dexieDb.deleteOne(collection, id);
     }
-    this.deps.writeToInMemBatch(collection, [{ _id: id }], "delete", { source: "incremental" });
+    this.deps.writeToInMemBatch(
+      collection,
+      [{ _id: id }],
+      "delete",
+      { source: "incremental" }
+    );
   }
   // ============================================================
   // Private Helpers
@@ -4717,6 +4985,36 @@ var ServerUpdateHandler = class {
       }
     }
   }
+  callOnEbusNotificationReceived(payload) {
+    if (this.callbacks.onEbusNotificationReceived) {
+      try {
+        const channel = this.isBracketedPayload(payload) ? "dbbracketed" : "db";
+        this.callbacks.onEbusNotificationReceived({
+          payload,
+          channel,
+          collection: payload.collection,
+          timestamp: /* @__PURE__ */ new Date()
+        });
+      } catch (err) {
+        console.error(
+          `[ServerUpdateHandler] onEbusNotificationReceived callback failed: ${err}`,
+          err
+        );
+      }
+    }
+  }
+  callOnEbusUpdateSkipped(info) {
+    if (this.callbacks.onEbusUpdateSkipped) {
+      try {
+        const fullInfo = __spreadProps(__spreadValues({}, info), {
+          timestamp: /* @__PURE__ */ new Date()
+        });
+        this.callbacks.onEbusUpdateSkipped(fullInfo);
+      } catch (err) {
+        console.error(`[ServerUpdateHandler] onEbusUpdateSkipped callback failed: ${err}`, err);
+      }
+    }
+  }
 };
 
 // src/db/managers/WakeSyncManager.ts
@@ -5125,7 +5423,9 @@ var _SyncedDb = class _SyncedDb {
       dexieDb: this.dexieDb,
       restInterface: this.restInterface,
       callbacks: {
-        onWsNotification: config.onWsNotification
+        onWsNotification: config.onWsNotification,
+        onEbusNotificationReceived: config.onEbusNotificationReceived,
+        onEbusUpdateSkipped: config.onEbusUpdateSkipped
       },
       deps: {
         isLeader: () => this.leaderElection.isLeader(),
@@ -11289,6 +11589,7 @@ var Ebus2ProxyServerUpdateNotifier = class {
     this.reconnectAttempt = 0;
     this.currentReconnectDelay = this.reconnectDelayMs;
     this.sendSubscribe(`db/${this.dbName}`);
+    this.sendSubscribe(`dbbracketed/${this.dbName}`);
     if (this.subscribeServices) {
       this.sendSubscribe("ebus/services");
     }
@@ -11431,8 +11732,12 @@ var Ebus2ProxyServerUpdateNotifier = class {
       }
       return;
     }
-    const prefix = `db/${this.dbName}/`;
-    if (!message.channel.startsWith(prefix)) {
+    let prefix;
+    if (message.channel.startsWith(`db/${this.dbName}/`)) {
+      prefix = `db/${this.dbName}/`;
+    } else if (message.channel.startsWith(`dbbracketed/${this.dbName}/`)) {
+      prefix = `dbbracketed/${this.dbName}/`;
+    } else {
       return;
     }
     const collection = message.channel.slice(prefix.length);

package/dist/src/db/sync/ServerUpdateHandler.d.ts

@@ -3,13 +3,14 @@
  *
  * Handles:
  * - Routing updates by operation type
- * - Loopback detection
- * - Delta merging with local data
+ * - pub_ts dedup across db/ and dbbracketed/ channels
+ * - _rev-based stale/self-echo/gap detection
+ * - Delta merging with local data (mergeLocalWithDelta for db/, applyObjDiff for dbbracketed/)
  * - Conflict management with pending changes
  * - Broadcasting updates to other tabs
  */
 import type { Id, LocalDbEntity } from "../../types/DbEntity";
-import type { PublishDataPayload } from "../../types/PublishRevsPayload";
+import type { PublishDataPayload, PublishBracketedPayloadBatch } from "../../types/PublishRevsPayload";
 import type { I_ServerUpdateHandler, ServerUpdateHandlerConfig } from "../types/managers";
 export declare class ServerUpdateHandler implements I_ServerUpdateHandler {
     private readonly tenant;
@@ -19,17 +20,57 @@ export declare class ServerUpdateHandler implements I_ServerUpdateHandler {
     private readonly restInterface;
     private readonly callbacks;
     private readonly deps;
+    /** Per-collection last processed pub_ts for cross-channel dedup. */
+    private lastProcessedPubTs;
     constructor(config: ServerUpdateHandlerConfig);
     /**
      * Handle incoming server update (WebSocket notification).
+     * Accepts both db/ (full-object) and dbbracketed/ (diff) payloads.
      */
-    handleServerUpdate(payload: PublishDataPayload): Promise<void>;
+    handleServerUpdate(payload: PublishDataPayload | PublishBracketedPayloadBatch): Promise<void>;
+    /**
+     * Check if this batch was already processed (duplicate or stale pub_ts).
+     * Updates lastProcessedPubTs when a new pub_ts is seen.
+     */
+    private wasAlreadyProcessed;
+    private isBracketedPayload;
+    private handleBracketedBatch;
+    private processBracketedItem;
+    /**
+     * Apply a bracketed diff to a local item using cry-db's applyObjDiff.
+     * Strips meta fields from the diff, then applies _rev/_ts from the item level.
+     */
+    private applyBracketedDiff;
+    /**
+     * Strip _id, _rev, _ts, _lastUpdaterId from a diff object before applyObjDiff.
+     *
+     * IMPORTANT: Uses for...in instead of Object.keys() because Object.keys()
+     * skips properties whose value is undefined. Bracketed diffs may contain
+     * {field: undefined} to signal field deletion (translated by applyObjDiff
+     * to deleteByPath). Skipping such keys would silently ignore deletions.
+     */
+    private stripMetaFromDiff;
+    private handleLegacyBatch;
+    /**
+     * Determine action based on incoming vs local revision.
+     *
+     * | incomingRev | Action      | Reason                                    |
+     * |-------------|-------------|-------------------------------------------|
+     * | ≤ localRev  | ignore      | Stale / duplicate / self-echo after WB    |
+     * | = local+1   | bump-meta   | Self-echo before WB (only if updaterId matches) |
+     * | = local+1   | apply       | External update (updaterId mismatch)      |
+     * | > local+1   | fetch-full  | Gap — missed intermediate updates; fetch  |
+     *               |             | full doc since we're online (WS connected).|
+     * | undefined   | apply       | Legacy server / no rev tracking           |
+     */
+    private checkRev;
+    private safeFindById;
     /**
      * Handle server item insert.
      */
     handleServerItemInsert(collection: string, serverItem: LocalDbEntity): Promise<void>;
     /**
-     * Handle server item update (delta).
+     * Handle server item update (delta) — db/ channel only.
      */
     handleServerItemUpdate(collection: string, localItem: LocalDbEntity, serverDelta: LocalDbEntity): Promise<void>;
     /**
@@ -42,4 +83,6 @@ export declare class ServerUpdateHandler implements I_ServerUpdateHandler {
     private mergeLocalWithDelta;
     private getNewFieldsFromServer;
     private callOnWsNotification;
+    private callOnEbusNotificationReceived;
+    private callOnEbusUpdateSkipped;
 }

package/dist/src/db/types/managers.d.ts

@@ -7,7 +7,7 @@ import type { I_DexieDb, SyncMeta, MetaUpdateBroadcast } from "../../types/I_Dex
 import type { I_InMemDb, SyncSource } from "../../types/I_InMemDb";
 import type { I_RestInterface } from "../../types/I_RestInterface";
 import type { PublishDataPayload } from "../../types/PublishRevsPayload";
-import type { CollectionConfig, SyncInfo, ConflictResolutionReport, ServerWriteRequestInfo, ServerWriteResultInfo, ServerSyncWriteInfo, FindNewerManyCallInfo, FindNewerManyResultInfo, DexieWriteRequestInfo, DexieWriteResultInfo, LocalstorageWriteResultInfo, WsNotificationInfo, CrossTabSyncInfo } from "../../types/I_SyncedDb";
+import type { CollectionConfig, SyncInfo, ConflictResolutionReport, ServerWriteRequestInfo, ServerWriteResultInfo, ServerSyncWriteInfo, FindNewerManyCallInfo, FindNewerManyResultInfo, DexieWriteRequestInfo, DexieWriteResultInfo, LocalstorageWriteResultInfo, WsNotificationInfo, EbusNotificationReceivedInfo, EbusUpdateSkippedInfo, CrossTabSyncInfo } from "../../types/I_SyncedDb";
 import type { PendingChange, UploadResult } from "./internal";
 export interface LeaderElectionCallbacks {
     onBecameLeader?: () => void;
@@ -351,6 +351,10 @@ export interface I_SyncEngine {
 }
 export interface ServerUpdateHandlerCallbacks {
     onWsNotification?: (info: WsNotificationInfo) => void;
+    /** Fired for every incoming ebus notification BEFORE any processing. */
+    onEbusNotificationReceived?: (info: EbusNotificationReceivedInfo) => void;
+    /** Fired when a gap notification is skipped because the fetch failed. */
+    onEbusUpdateSkipped?: (info: EbusUpdateSkippedInfo) => void;
 }
 export interface ServerUpdateHandlerDeps {
     isLeader: () => boolean;
@@ -373,8 +377,8 @@ export interface ServerUpdateHandlerConfig {
     deps: ServerUpdateHandlerDeps;
 }
 export interface I_ServerUpdateHandler {
-    /** Handle incoming server update. */
-    handleServerUpdate(payload: PublishDataPayload): Promise<void>;
+    /** Handle incoming server update (db/ or dbbracketed/ channel). */
+    handleServerUpdate(payload: PublishDataPayload | import("../../types/PublishRevsPayload").PublishBracketedPayloadBatch): Promise<void>;
 }
 /** Type of event that triggered wake sync */
 export type WakeSyncTrigger = "pageshow" | "focus" | "visibilitychange";

package/dist/src/types/I_SyncedDb.d.ts

@@ -341,6 +341,32 @@ export interface WsNotificationInfo {
     /** Timestamp when notification was received */
     timestamp: Date;
 }
+/** Info passed to onEbusNotificationReceived — fires for every incoming ebus notification before processing. */
+export interface EbusNotificationReceivedInfo {
+    /** The raw notification payload exactly as received from ebus-proxy */
+    payload: import("./PublishRevsPayload").PublishDataPayload | import("./PublishRevsPayload").PublishBracketedPayloadBatch;
+    /** Which channel the notification arrived on */
+    channel: "db" | "dbbracketed";
+    /** Collection name */
+    collection: string;
+    /** Timestamp when notification was received */
+    timestamp: Date;
+}
+/** Info passed to onEbusUpdateSkipped — fires when a notification is skipped because the gap fetch failed. */
+export interface EbusUpdateSkippedInfo {
+    /** Collection name */
+    collection: string;
+    /** Document _id */
+    _id: Id;
+    /** Incoming _rev that caused the gap detection */
+    incomingRev: number;
+    /** Local _rev at the time of skip */
+    localRev: number;
+    /** Reason for skipping */
+    reason: "fetch-failed";
+    /** Timestamp when skip occurred */
+    timestamp: Date;
+}
 /**
  * Source of the conflict - where the conflict was detected
  */
@@ -756,6 +782,19 @@ export interface SyncedDbConfig {
     onWsReconnect?: (attempt: number) => void;
     /** Callback when a WebSocket notification is received */
     onWsNotification?: (info: WsNotificationInfo) => void;
+    /**
+     * Diagnostic callback fired for EVERY incoming ebus notification BEFORE
+     * any processing (dedup, rev-check, apply). Useful for telemetry/debugging.
+     * Receives the raw payload + channel info.
+     */
+    onEbusNotificationReceived?: (info: EbusNotificationReceivedInfo) => void;
+    /**
+     * Callback fired when a server update is skipped because the local document
+     * is too far behind (gap: incoming._rev > local._rev + 1) and the fetch
+     * for the full document failed (network error, timeout, offline).
+     * The document stays unchanged; next sync will catch up.
+     */
+    onEbusUpdateSkipped?: (info: EbusUpdateSkippedInfo) => void;
     /** Callback when online status changes (after ping success/failure in tryGoOnline) */
     onOnlineStatusChange?: (online: boolean) => void;
     /** Debounce interval for cross-tab sync broadcasts in ms (default: 100) */

package/dist/src/types/PublishRevsPayload.d.ts

@@ -82,6 +82,7 @@ export type PublishDataPayloadBatchItem = {
 export type PublishDataPayloadBatch = PublishDataPayloadBase & {
     operation: 'batch';
     data: PublishDataPayloadBatchItem[];
+    pub_ts?: number;
 };
 /**
  * Notifikacija serverja s podatki o spremembah
@@ -93,5 +94,25 @@ export type PublishDataSpec = {
     payload: PublishDataPayload;
     user?: string;
 };
+/**
+ * Payload for bracketed diff notifications (dbbracketed/ channel).
+ * Contains the client diff (bracketedData) instead of full parent arrays.
+ * _rev and _ts are at item level, outside bracketedData.
+ */
+export type PublishBracketedPayloadBatchItem<T = any> = {
+    operation: 'insert' | 'update' | 'delete';
+    _id: Id;
+    _ts: Timestamp | {
+        t: number;
+        i: number;
+    };
+    _rev?: number;
+    bracketedData: T;
+};
+export type PublishBracketedPayloadBatch<T = any> = PublishDataPayloadBase & {
+    operation: 'batch';
+    data: PublishBracketedPayloadBatchItem<T>[];
+    pub_ts?: number;
+};
 export type PublishSpec = PublishDataSpec | PublishRevsSpec;
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cry-synced-db-client",
-  "version": "0.1.219",
+  "version": "2.0.0",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",