@cuboapp/crdt 1.0.14 → 1.0.16

package/src/server/index.ts

@@ -3,8 +3,12 @@ import { WsServerSocket } from '@cuboapp/ws'
 import { applyAwarenessUpdate, encodeAwarenessUpdate, removeAwarenessStates } from 'y-protocols/awareness'
 
 import { CUBO_CRDT_EVENT } from '../constants'
-import { CuboCrdtAction } from '../types'
-import { checkRowIsSutable } from '../utils'
+import { CuboCrdtAction, CuboCrdtListSyncData, CuboCrdtMutation } from '../types'
+import {
+  areCrdtListIdsEqual,
+  areCrdtListTotalsEqual,
+  checkRowIsSutable
+} from '../utils'
 
 import { CuboCrdtClientDocOrigin } from '../client'
 import { CuboCrdtServerDocument } from './document'
@@ -14,6 +18,7 @@ import {
   CuboCrdtServerOptions,
   CuboCrdtServerSubscribe,
   CuboCrdtServerSubscribeDto,
+  CuboCrdtSubscribeRefreshState,
   CuboCrdtServerUnsubscribeDto,
   CuboCrdtSocketClient
 } from './types'
@@ -31,28 +36,40 @@ export class CuboCrdtServer<M, A = {}, E extends Extract<keyof M, string> = Extr
   private subscribes = new Map<string, CuboCrdtServerSubscribe>()
   private subscribesByClient = new Map<string, Set<string>>()
   private subscribesByEntity = new Map<E, Set<string>>()
-  private subscribesIniting = new Map<string, Promise<void>>()
-  private subscribesUpgrading = new Map<string, Promise<void>>()
+  private subscribeRefreshStates = new Map<string, CuboCrdtSubscribeRefreshState>()
+  private subscribeGenerations = new Map<string, number>()
 
   private documents = new Map<string, CuboCrdtServerDocument>()
   private subscribesByDocument = new Map<string, Set<string>>()
+  // обратный индекс: подписка -> имена документов, к которым она привязана.
+  // Нужен, чтобы отписка/очистка не сканировала ВСЕ документы сервера (O(subs x docs)).
+  private documentsBySubscribe = new Map<string, Set<string>>()
 
   public async init() {
     this.entities.forEach((e) => this.subscribesByEntity.set(e, new Set()))
 
     this.ws.registerHandler(CUBO_CRDT_EVENT.SUBSCRIBE, async ({ client, message }) => {
-      const { subscribe_id: id, entity, filters, awareness = false } = message.data as CuboCrdtServerSubscribeDto
+      const { subscribe_id: id, entity, filters, awareness = false, paginated } = message.data as CuboCrdtServerSubscribeDto
 
       if (this.debug) {
         console.log('[CRDT] subscribe', entity, filters)
       }
 
+      const existing = this.subscribes.get(id)
+      if (existing) {
+        this.cleanSubscribe(id)
+      }
+
       const subscribe = {
         id,
         client_id: client.id,
         entity,
-        filters,
-        awareness
+        filters: cloneDeep(filters || {}),
+        awareness,
+        paginated: this.resolvePaginated(filters, paginated),
+        row_ids: [],
+        totals: {},
+        revision: 0
       }
 
       this.subscribes.set(id, subscribe)
@@ -64,11 +81,13 @@ export class CuboCrdtServer<M, A = {}, E extends Extract<keyof M, string> = Extr
       this.subscribesByEntity.get(entity as E)?.add(id)
 
       // инициализируем подписку
-      this.initSubscribe(client, subscribe)
+      await this.initSubscribe(client, subscribe)
+
+      return { subscribe_id: id, revision: subscribe.revision }
     })
 
     this.ws.registerHandler(CUBO_CRDT_EVENT.UPGRADE, async ({ client, message }) => {
-      const { subscribe_id: id, entity, filters } = message.data as CuboCrdtServerSubscribeDto
+      const { subscribe_id: id, entity, filters, paginated } = message.data as CuboCrdtServerSubscribeDto
 
       if (this.debug) {
         console.log('[CRDT] upgrade', entity, filters)
@@ -80,7 +99,9 @@ export class CuboCrdtServer<M, A = {}, E extends Extract<keyof M, string> = Extr
       }
 
       // обновляем подписку
-      this.upgradeSubscribe(client, subscribe, { filters })
+      await this.upgradeSubscribe(client, subscribe, { filters, paginated })
+
+      return { subscribe_id: id, revision: subscribe.revision }
     })
 
     this.ws.registerHandler(CUBO_CRDT_EVENT.UNSUBSCRIBE, async ({ message }) => {
@@ -145,9 +166,14 @@ export class CuboCrdtServer<M, A = {}, E extends Extract<keyof M, string> = Extr
 
   public async destroy() {
     this.ws.deleteHandler(CUBO_CRDT_EVENT.SUBSCRIBE)
+    this.ws.deleteHandler(CUBO_CRDT_EVENT.UPGRADE)
     this.ws.deleteHandler(CUBO_CRDT_EVENT.UNSUBSCRIBE)
     this.ws.deleteHandler(CUBO_CRDT_EVENT.EVENT)
 
+    this.subscribeRefreshStates.forEach((state) => clearTimeout(state.timer))
+    this.subscribeRefreshStates.clear()
+    this.subscribeGenerations.clear()
+
     this.subscribes.forEach((sub) => this.ws.deleteHandler(sub.id))
   }
 
@@ -163,8 +189,9 @@ export class CuboCrdtServer<M, A = {}, E extends Extract<keyof M, string> = Extr
   }
 
   public removeClient(client: WsServerSocket) {
-    // удаляем все подписки по клиенту
-    this.subscribesByClient.get(client.id)?.forEach((subscribe_id) => this.cleanSubscribe(subscribe_id))
+    // удаляем все подписки по клиенту (но только те, что всё ещё принадлежат ЭТОМУ сокету —
+    // подписка могла быть переподвязана к новому сокету при reconnect с тем же subscribe_id)
+    this.subscribesByClient.get(client.id)?.forEach((subscribe_id) => this.cleanSubscribe(subscribe_id, client.id))
 
     // удаляем мапу подписок по клиенту
     this.subscribesByClient.delete(client.id)
@@ -188,6 +215,21 @@ export class CuboCrdtServer<M, A = {}, E extends Extract<keyof M, string> = Extr
     return this.options.batch?.debounce ?? 100
   }
 
+  private get paginationDebounce() {
+    return this.options.pagination?.debounce ?? 75
+  }
+
+  private resolvePaginated(filters?: Record<string, any>, explicit?: boolean) {
+    if (explicit !== undefined) {
+      return explicit
+    }
+
+    const page = Number(filters?.page)
+    const limit = Number(filters?.limit)
+
+    return Number.isFinite(page) && page > 0 && Number.isFinite(limit) && limit > 0
+  }
+
   private sendQueueToClient(client: CuboCrdtSocketClient<A>) {
     // снимаем запланированный флаш — мы отправляем прямо сейчас
     clearTimeout(this.sendTimeouts.get(client.id))
@@ -198,17 +240,17 @@ export class CuboCrdtServer<M, A = {}, E extends Extract<keyof M, string> = Extr
       return
     }
 
-    // дедупликация одинаковых событий внутри батча
-    const data = [...new Map(Array.from(queue).map((item) => [JSON.stringify(item), item])).values()]
+    // Дедупликация побайтово идентичных событий внутри батча + сборка кадра за ОДИН проход
+    // сериализации: сериализуем каждый элемент один раз (он же служит ключом дедупа) и
+    // склеиваем готовые JSON-строки, а не сериализуем весь массив повторно.
+    const items = new Set<string>()
+    for (const item of queue) {
+      items.add(JSON.stringify(item))
+    }
 
     queue.clear()
 
-    client.send(
-      JSON.stringify({
-        method: CUBO_CRDT_EVENT.EVENT,
-        data
-      })
-    )
+    client.send(`{"method":${JSON.stringify(CUBO_CRDT_EVENT.EVENT)},"data":[${Array.from(items).join(',')}]}`)
   }
 
   public sendToClient(client_id: string, data: any) {
@@ -241,6 +283,29 @@ export class CuboCrdtServer<M, A = {}, E extends Extract<keyof M, string> = Extr
     }
   }
 
+  // привязываем подписку к документу (в обоих индексах)
+  private linkSubscribeToDocument(subscribe_id: string, docName: string) {
+    let byDoc = this.subscribesByDocument.get(docName)
+    if (!byDoc) {
+      byDoc = new Set()
+      this.subscribesByDocument.set(docName, byDoc)
+    }
+    byDoc.add(subscribe_id)
+
+    let bySub = this.documentsBySubscribe.get(subscribe_id)
+    if (!bySub) {
+      bySub = new Set()
+      this.documentsBySubscribe.set(subscribe_id, bySub)
+    }
+    bySub.add(docName)
+  }
+
+  // отвязываем подписку от документа (в обоих индексах)
+  private unlinkSubscribeFromDocument(subscribe_id: string, docName: string) {
+    this.subscribesByDocument.get(docName)?.delete(subscribe_id)
+    this.documentsBySubscribe.get(subscribe_id)?.delete(docName)
+  }
+
   // если у документа нет подписок - сносим его
   private checkDocumentNeedRemove(name: string) {
     if (!this.subscribesByDocument.get(name)?.size) {
@@ -250,55 +315,67 @@ export class CuboCrdtServer<M, A = {}, E extends Extract<keyof M, string> = Extr
 
       this.documents.get(name)?.destroy()
       this.documents.delete(name)
+      // не оставляем пустой Set в индексе (иначе — медленная утечка записей мапы);
+      // getOrCreateDocument пересоздаст его при повторном появлении документа
+      this.subscribesByDocument.delete(name)
     }
   }
 
-  // очистка подписки (при отписке клиента - через emit-метод или options-хук)
-  private cleanSubscribe(subscribe_id: string) {
+  // очистка подписки (при отписке клиента - через emit-метод или options-хук).
+  // ownerClientId (опционально): при отключении сокета передаётся id этого сокета —
+  // если подписка уже переподвязана к НОВОМУ клиенту (reconnect с тем же subscribe_id),
+  // старый close-хендлер не должен её сносить.
+  private cleanSubscribe(subscribe_id: string, ownerClientId?: string) {
     const subscribe = this.subscribes.get(subscribe_id)
-    if (subscribe) {
+    if (!subscribe) {
+      return
+    }
+
+    // подписка была переподвязана к другому (более новому) клиенту — не трогаем
+    if (ownerClientId !== undefined && subscribe.client_id !== ownerClientId) {
       if (this.debug) {
-        console.log('[CRDT] unsubscribe', subscribe.entity, subscribe.filters)
+        console.log('[CRDT] cleanSubscribe skipped (rebound to newer client)', subscribe_id)
       }
+      return
+    }
 
-      if (subscribe.awareness) {
-        //убираем аварнесс стейт при отписке
-        this.subscribesByDocument.forEach((subs, docName) => {
-          if (!subs.has(subscribe_id)) {
-            return
-          }
+    if (this.debug) {
+      console.log('[CRDT] unsubscribe', subscribe.entity, subscribe.filters)
+    }
 
-          const doc = this.documents.get(docName)
-          if (!doc?.awareness) {
-            return
-          }
+    // документы этой подписки берём из обратного индекса, а не сканируем все
+    const docNames = this.documentsBySubscribe.get(subscribe_id)
 
-          const ids = Array.from(doc.awarenessBySubscribe.get(subscribe_id) || [])
-          if (!ids.length) {
-            return
+    if (docNames) {
+      for (const docName of docNames) {
+        if (subscribe.awareness) {
+          //убираем аварнесс стейт при отписке
+          const doc = this.documents.get(docName)
+          const ids = doc?.awareness ? Array.from(doc.awarenessBySubscribe.get(subscribe_id) || []) : []
+          if (doc?.awareness && ids.length) {
+            removeAwarenessStates(doc.awareness, ids, { subscribe_id, expose: 'all' })
+            doc.awarenessBySubscribe.delete(subscribe_id)
           }
+        }
 
-          removeAwarenessStates(doc.awareness, ids, { subscribe_id, expose: 'all' })
-
-          doc.awarenessBySubscribe.delete(subscribe_id)
-        })
+        // отписываем документ от подписки (только по одной стороне индекса — другую чистим ниже)
+        this.subscribesByDocument.get(docName)?.delete(subscribe_id)
+        this.checkDocumentNeedRemove(docName)
       }
+    }
 
-      // удаляем подписку по сущности
-      this.subscribesByEntity.get(subscribe.entity as E)?.delete(subscribe.id)
+    // удаляем обратный индекс
+    this.documentsBySubscribe.delete(subscribe_id)
 
-      // отписываем все документы от подписки
-      this.subscribesByDocument.forEach((subscribes, docName) => {
-        subscribes.delete(subscribe_id)
+    const refreshState = this.subscribeRefreshStates.get(subscribe_id)
+    clearTimeout(refreshState?.timer)
+    this.subscribeRefreshStates.delete(subscribe_id)
+    this.subscribeGenerations.delete(subscribe_id)
 
-        this.checkDocumentNeedRemove(docName)
-      })
-
-      // удаляем подписки
-      this.subscribes.delete(subscribe_id)
-      this.subscribesByClient.get(subscribe.client_id)?.delete(subscribe_id)
-      this.subscribesByEntity.get(subscribe.entity as E)?.delete(subscribe_id)
-    }
+    // удаляем подписки
+    this.subscribes.delete(subscribe_id)
+    this.subscribesByClient.get(subscribe.client_id)?.delete(subscribe_id)
+    this.subscribesByEntity.get(subscribe.entity as E)?.delete(subscribe_id)
   }
 
   public getDocument(entity: string, entity_id: number) {
@@ -321,60 +398,298 @@ export class CuboCrdtServer<M, A = {}, E extends Extract<keyof M, string> = Extr
     })
   }
 
-  public ensureDocument(entity: E, row: any, awareness?: boolean) {
-    // todo: врапнуть всё это в Promise
-    const entity_id = row.id
-    const documentName = `${entity}:${entity_id}`
+  private getSubscribeRefreshState(subscribe_id: string) {
+    let state = this.subscribeRefreshStates.get(subscribe_id)
+    if (!state) {
+      state = { dirty: false, forceSync: false }
+      this.subscribeRefreshStates.set(subscribe_id, state)
+    }
+    return state
+  }
 
-    // проверяем документ
-    let document = this.documents.get(documentName)
-    if (!document) {
-      document = new CuboCrdtServerDocument({
-        name: documentName,
-        initialState: row,
-        awareness: awareness,
-        onUpdate: (data: Uint8Array, origin?: CuboCrdtServerDocumentOrigin) => {
-          // пушим обновление документа
-          // console.log('push document update', document.name)
-
-          this.pushDocumentAction('update', entity, document!, data, origin)
-        },
-        onAwarenessUpdate: (data: Uint8Array, origin?: CuboCrdtServerDocumentOrigin) => {
-          // пушим обновление документа
-          // console.log('push document update', document.name)
+  private bumpSubscribeGeneration(subscribe_id: string) {
+    const generation = (this.subscribeGenerations.get(subscribe_id) || 0) + 1
+    this.subscribeGenerations.set(subscribe_id, generation)
+    return generation
+  }
 
-          this.pushDocumentAction('awareness', entity, document!, data, origin)
-        },
-        onStore: (item: object, origin: CuboCrdtServerDocumentOrigin) => {
-          const subscribe = origin.subscribe_id && this.subscribes.get(origin.subscribe_id)
-          const client = subscribe && this.clients.get(subscribe.client_id)
+  private runSubscribeRefresh(subscribe_id: string) {
+    const state = this.getSubscribeRefreshState(subscribe_id)
+    if (state.running) {
+      return state.running
+    }
 
-          if (client) {
-            return this.options?.storeRow?.(entity as any, entity_id, item as any, { document, client, origin })
+    state.running = (async () => {
+      while (state.dirty) {
+        state.dirty = false
+
+        const subscribe = this.subscribes.get(subscribe_id)
+        if (!subscribe) {
+          return
+        }
+
+        const client = this.clients.get(subscribe.client_id)
+        if (!client) {
+          return
+        }
+
+        const generation = this.subscribeGenerations.get(subscribe_id) || 0
+        const forceSync = state.forceSync
+        state.forceSync = false
+        const reconciled = await this.reconcileSubscribe(
+          client,
+          subscribe,
+          generation,
+          forceSync
+        )
+        if (!reconciled && forceSync) {
+          state.forceSync = true
+        }
+      }
+    })().finally(() => {
+      state.running = undefined
+    })
+
+    return state.running
+  }
+
+  private requestSubscribeRefresh(
+    subscribe_id: string,
+    immediate = false,
+    forceSync = immediate
+  ) {
+    const state = this.getSubscribeRefreshState(subscribe_id)
+    state.dirty = true
+    state.forceSync ||= forceSync
+    this.bumpSubscribeGeneration(subscribe_id)
+
+    if (immediate) {
+      clearTimeout(state.timer)
+      state.timer = undefined
+      return this.runSubscribeRefresh(subscribe_id)
+    }
+
+    if (!state.timer && !state.running) {
+      state.timer = setTimeout(() => {
+        state.timer = undefined
+        this.runSubscribeRefresh(subscribe_id).catch((e) => {
+          if (this.debug) {
+            console.error('[CRDT] refresh subscribe', subscribe_id, e)
           }
+        })
+      }, this.paginationDebounce)
+    }
+
+    return state.running ?? Promise.resolve()
+  }
+
+  private getSubscribeQueryKeys(filters?: Record<string, any>) {
+    const keys = new Set<string>()
+
+    Object.keys(filters || {}).forEach((key) => {
+      if (!['page', 'limit', 'sort', 'with'].includes(key)) {
+        keys.add(key)
+
+        const rangeKey = key.replace(/_(start|end)$/, '')
+        if (rangeKey !== key) {
+          keys.add(rangeKey)
         }
-      })
 
-      // создаём документ
-      this.documents.set(documentName, document)
+        if (key.endsWith('_ids')) {
+          keys.add(key.slice(0, -1))
+        }
+      }
+    })
+
+    const appendSort = (sort: unknown) => {
+      if (Array.isArray(sort)) {
+        sort.forEach(appendSort)
+        return
+      }
+      if (typeof sort !== 'string') {
+        return
+      }
+
+      sort
+        .split(',')
+        .map((item) => item.trim().replace(/^-/, '').split(':')[0])
+        .filter(Boolean)
+        .forEach((key) => keys.add(key))
+    }
+
+    appendSort(filters?.sort)
+
+    return keys
+  }
+
+  private shouldRefreshSubscribe(entity: E, subscribe: CuboCrdtServerSubscribe, mutation: CuboCrdtMutation<M[E]>) {
+    if (!subscribe.paginated) {
+      return false
+    }
+
+    if (this.options.shouldRefreshSubscribe) {
+      return this.options.shouldRefreshSubscribe({ entity, subscribe, mutation })
+    }
+
+    if (mutation.action !== 'update' || !mutation.changedKeys?.length) {
+      return true
+    }
+
+    if (mutation.previousRow) {
+      const previousSuitable = this.checkRowIsSutable(
+        mutation.previousRow,
+        subscribe,
+        entity
+      )
+      const currentSuitable = this.checkRowIsSutable(
+        mutation.row,
+        subscribe,
+        entity
+      )
+
+      if (previousSuitable !== currentSuitable) {
+        return true
+      }
+    }
+
+    if (subscribe.filters?.search) {
+      return true
+    }
+
+    const queryKeys = this.getSubscribeQueryKeys(subscribe.filters)
+    return mutation.changedKeys.some((key) => queryKeys.has(key))
+  }
+
+  /**
+   * Уведомляет пагинированные подписки о сохранённой мутации.
+   * Пересчитываются только реально открытые страницы; несколько мутаций
+   * схлопываются debounce-ом в один запрос на подписку.
+   */
+  public notifyMutation(entity: E, mutation: CuboCrdtMutation<M[E]>) {
+    for (const subscribe_id of this.subscribesByEntity.get(entity) || []) {
+      const subscribe = this.subscribes.get(subscribe_id)
+      if (subscribe && this.shouldRefreshSubscribe(entity, subscribe, mutation)) {
+        this.requestSubscribeRefresh(subscribe_id)
+      }
+    }
+  }
+
+  /**
+   * Принудительно инвалидирует все открытые пагинированные окна сущности.
+   * Используется для вычисляемых полей и зависимых сущностей, когда changedKeys
+   * исходной строки недостаточно для определения влияния на запрос.
+   */
+  public invalidate(entity: E) {
+    for (const subscribe_id of this.subscribesByEntity.get(entity) || []) {
+      const subscribe = this.subscribes.get(subscribe_id)
+      if (subscribe?.paginated) {
+        this.requestSubscribeRefresh(subscribe_id)
+      }
+    }
+  }
+
+  // создаёт (или возвращает существующий) серверный документ БЕЗ рассылки подписчикам.
+  // Используется как для рассылочного пути (ensureDocument), так и для точечной
+  // доставки на init подписки (pushSubscribeDocuments).
+  private getOrCreateDocument(entity: E, row: any, awareness?: boolean): CuboCrdtServerDocument {
+    const entity_id = row.id
+    const documentName = `${entity}:${entity_id}`
+
+    let document = this.documents.get(documentName)
+    if (document) {
+      return document
+    }
+
+    document = new CuboCrdtServerDocument({
+      name: documentName,
+      initialState: row,
+      awareness: awareness,
+      onUpdate: (data: Uint8Array, origin?: CuboCrdtServerDocumentOrigin) => {
+        this.pushDocumentAction('update', entity, document!, data, origin)
+      },
+      onAwarenessUpdate: (data: Uint8Array, origin?: CuboCrdtServerDocumentOrigin) => {
+        this.pushDocumentAction('awareness', entity, document!, data, origin)
+      },
+      onStore: (item: object, origin: CuboCrdtServerDocumentOrigin, store) => {
+        const subscribe = origin.subscribe_id && this.subscribes.get(origin.subscribe_id)
+        const client = subscribe && this.clients.get(subscribe.client_id)
+
+        if (client) {
+          return this.options?.storeRow?.(entity as any, entity_id, item as any, {
+            document,
+            client,
+            origin,
+            previousRow: store.previousRow as any,
+            row: store.row as any
+          })
+        }
+      }
+    })
 
-      // создаём пул подписок по документу
+    this.documents.set(documentName, document)
+    if (!this.subscribesByDocument.has(documentName)) {
       this.subscribesByDocument.set(documentName, new Set())
+    }
 
-      // пушим создание документа
-      this.pushDocumentAction('create', entity, document, document.stateAsUpdate)
+    return document
+  }
 
-      // console.log('create document', documentName)
+  // Рассылочный путь (хук onAfterCreate/onAfterUpdate из бэка): создаёт документ и
+  // раскатывает 'create'/'upsert' по ВСЕМ подходящим подпискам сущности.
+  public ensureDocument(entity: E, row: any, awareness?: boolean) {
+    if (row?.id == null) {
+      if (this.debug) {
+        console.warn('[CRDT] ensureDocument: row without id', entity, row)
+      }
+      return
+    }
+
+    const documentName = `${entity}:${row.id}`
+    const existed = this.documents.has(documentName)
+    const document = this.getOrCreateDocument(entity, row, awareness)
+
+    if (!existed) {
+      this.pushDocumentAction('create', entity, document, document.stateAsUpdate)
     } else {
-      // console.log('update document', documentName)
+      document.write(row, { expose: 'all', store: false })
+      document.setPersistedState(row)
+    }
 
-      // пушим обновление документа
-      this.pushDocumentAction('upsert', entity, document, document.stateAsUpdate)
+    if (!this.subscribesByDocument.get(documentName)?.size) {
+      this.checkDocumentNeedRemove(documentName)
     }
 
     return document
   }
 
+  // Точечная доставка документа ТОЛЬКО инициирующей подписке (init/upgrade/resubscribe).
+  // Раньше это шло через ensureDocument -> pushDocumentAction('upsert') с полным сканом
+  // всех подписок сущности — на каждый ряд из fetchRows. Теперь — один send на подписку.
+  private sendDocumentToSubscribe(subscribe: CuboCrdtServerSubscribe, document: CuboCrdtServerDocument, entity_id: number) {
+    this.linkSubscribeToDocument(subscribe.id, document.name)
+
+    this.sendToClient(subscribe.client_id, {
+      action: 'create',
+      entity: subscribe.entity,
+      entity_id,
+      data: Array.from(document.stateAsUpdate),
+      subscribe_id: subscribe.id
+    })
+
+    if (subscribe.awareness && document.awareness) {
+      const ids = Array.from(document.awareness.getStates().keys())
+      if (ids.length) {
+        this.sendToClient(subscribe.client_id, {
+          action: 'awareness',
+          entity: subscribe.entity,
+          entity_id,
+          data: Array.from(encodeAwarenessUpdate(document.awareness, ids)),
+          subscribe_id: subscribe.id
+        })
+      }
+    }
+  }
+
   public deleteDocument(entity: E, row: any, origin?: CuboCrdtClientDocOrigin) {
     if (this.debug) {
       console.log('[CRDT] delete document', entity, row.id, origin)
@@ -387,6 +702,15 @@ export class CuboCrdtServer<M, A = {}, E extends Extract<keyof M, string> = Extr
       // сначала пушим удаление документа
       this.pushDocumentAction('delete', entity, document, null, origin)
 
+      // чистим обратный индекс: убираем документ из documentsBySubscribe у всех его подписок
+      const subs = this.subscribesByDocument.get(documentName)
+      if (subs) {
+        for (const subscribe_id of subs) {
+          this.documentsBySubscribe.get(subscribe_id)?.delete(documentName)
+        }
+      }
+      this.subscribesByDocument.delete(documentName)
+
       // удаляем документ
       this.documents.delete(documentName)
 
@@ -402,11 +726,19 @@ export class CuboCrdtServer<M, A = {}, E extends Extract<keyof M, string> = Extr
   private onDocumentExternalUpdate(update: Uint8Array, action: CuboCrdtServerDocumentIncomingAction) {
     let document = this.getDocument(action.entity, action.entity_id)
     if (!document) {
+      // документ мог быть вытеснен (эвикция при отключении всех подписчиков), пока
+      // клиент ещё шлёт апдейты. Пересоздаём под ПРАВИЛЬНЫМ ключом ({ id }, а не число),
+      // без рассылки пустого 'create'. Раньше сюда передавался entity_id как row ->
+      // row.id === undefined -> общий документ-призрак `entity:undefined`.
+      if (action.entity_id == null) {
+        return
+      }
+
       if (this.debug) {
         console.warn('[CRDT] onDocumentExternalUpdate - document not found, creating:', action.entity, action.entity_id)
       }
 
-      document = this.ensureDocument(action.entity as E, action.entity_id, true)
+      document = this.getOrCreateDocument(action.entity as E, { id: action.entity_id }, true)
     }
 
     document.applyUpdate(new Uint8Array(update), action.origin)
@@ -468,12 +800,25 @@ export class CuboCrdtServer<M, A = {}, E extends Extract<keyof M, string> = Extr
     const sutableSubscribes = Array.from(this.subscribesByEntity.get(entity) || [])
       .map((subscribe_id) => {
         const subscribe = this.subscribes.get(subscribe_id)
+        if (!subscribe) {
+          return null
+        }
+
+        // аварнесс-события (курсоры/выделения) раскатываем ТОЛЬКО подпискам с awareness,
+        // а не всем спискам сущности, которым awareness не нужен
+        if (action === 'awareness' && !subscribe.awareness) {
+          return null
+        }
 
         const subscribeSutable = this.checkSubscribeIsSutable(origin, subscribe)
         const documentExistsInSubscribe = this.subscribesByDocument.get(document.name)?.has(subscribe.id)
-        const rowSutable = this.checkRowIsSutable(row, subscribe, entity)
+        const rowSutable = subscribe.paginated
+          ? documentExistsInSubscribe
+          : this.checkRowIsSutable(row, subscribe, entity)
 
-        const sutable = subscribeSutable && (rowSutable || documentExistsInSubscribe)
+        const sutable = subscribeSutable && (subscribe.paginated
+          ? documentExistsInSubscribe
+          : rowSutable || documentExistsInSubscribe)
 
         if (sutable) {
           if (this.debug && !rowSutable) {
@@ -534,8 +879,6 @@ export class CuboCrdtServer<M, A = {}, E extends Extract<keyof M, string> = Extr
       .filter((i) => !!i) as { subscribe: CuboCrdtServerSubscribe; action: CuboCrdtAction; data: undefined | number[] }[]
 
     if (sutableSubscribes.length) {
-      const documentSubscribes = this.subscribesByDocument.get(document.name)
-
       sutableSubscribes.forEach(({ subscribe, action, data }) => {
         this.sendToClient(subscribe.client_id, {
           action,
@@ -549,10 +892,10 @@ export class CuboCrdtServer<M, A = {}, E extends Extract<keyof M, string> = Extr
           case 'create':
           case 'upsert':
           case 'update':
-            documentSubscribes.add(subscribe.id)
+            this.linkSubscribeToDocument(subscribe.id, document.name)
             break
           case 'delete':
-            documentSubscribes.delete(subscribe.id)
+            this.unlinkSubscribeFromDocument(subscribe.id, document.name)
             this.checkDocumentNeedRemove(document.name)
             break
         }
@@ -576,87 +919,123 @@ export class CuboCrdtServer<M, A = {}, E extends Extract<keyof M, string> = Extr
     }
   }
 
-  private async pushSubscribeDocuments(client: WsServerSocket, subscribe: CuboCrdtServerSubscribe) {
-    // получаем список всех документов
-    const rows = await this.options.fetchRows?.(client, subscribe)
-
-    // пушим их в сокеты
-    for (const row of rows || []) {
-      // this.ensureDocument(subscribe.entity as E, row, { subscribes_ids: [subscribe.id] })
-      this.ensureDocument(subscribe.entity as E, row, subscribe.awareness)
-    }
-  }
-
-  // апгрейд подписки (фильтры поменялись например)
-  private async upgradeSubscribe(
+  private async reconcileSubscribe(
     client: WsServerSocket,
     subscribe: CuboCrdtServerSubscribe,
-    upgrade: Partial<Pick<CuboCrdtServerSubscribe, 'filters'>>
+    generation: number,
+    forceSync: boolean
   ) {
-    if (this.subscribesUpgrading.has(subscribe.id)) {
-      return this.subscribesUpgrading.get(subscribe.id)
+    const fetched = await this.options.fetchRows?.(client, subscribe)
+    const result = Array.isArray(fetched)
+      ? { rows: fetched, totals: subscribe.totals }
+      : { rows: fetched?.rows || [], totals: fetched?.totals || subscribe.totals }
+
+    if (
+      this.subscribes.get(subscribe.id) !== subscribe ||
+      this.subscribeGenerations.get(subscribe.id) !== generation
+    ) {
+      return false
     }
 
-    this.subscribesUpgrading.set(
-      subscribe.id,
-      new Promise<void>(async (resolve, reject) => {
-        try {
-          if (this.debug) {
-            console.log('[CRDT] upgrade subscribe ' + client.id, subscribe)
-          }
+    const rowsById = new Map<number, any>()
+    const nextIds: number[] = []
 
-          if (upgrade.filters) {
-            subscribe.filters = cloneDeep(upgrade.filters || {})
-          }
+    for (const row of result.rows) {
+      const id = Number((row as any)?.id)
+      if (!Number.isFinite(id) || rowsById.has(id)) {
+        continue
+      }
 
-          await this.pushSubscribeDocuments(client, subscribe)
+      rowsById.set(id, row)
+      nextIds.push(id)
+    }
 
-          resolve()
-        } catch (e) {
-          if (this.debug) {
-            console.error('[CRDT] upgrade subscribe', e)
-          }
+    const previousIds = new Set(subscribe.row_ids)
+    const nextIdsSet = new Set(nextIds)
 
-          reject(e)
-        } finally {
-          this.subscribesUpgrading.delete(subscribe.id)
-        }
-      })
+    for (const entity_id of subscribe.row_ids) {
+      if (nextIdsSet.has(entity_id)) {
+        continue
+      }
+
+      const documentName = `${subscribe.entity}:${entity_id}`
+      this.unlinkSubscribeFromDocument(subscribe.id, documentName)
+      this.checkDocumentNeedRemove(documentName)
+    }
+
+    for (const entity_id of nextIds) {
+      const row = rowsById.get(entity_id)
+      if (!row) {
+        continue
+      }
+
+      if (previousIds.has(entity_id)) {
+        this.linkSubscribeToDocument(subscribe.id, `${subscribe.entity}:${entity_id}`)
+        continue
+      }
+
+      const document = this.getOrCreateDocument(subscribe.entity as E, row, subscribe.awareness)
+      this.sendDocumentToSubscribe(subscribe, document, entity_id)
+    }
+
+    const idsChanged = !areCrdtListIdsEqual(subscribe.row_ids, nextIds)
+    const totalsChanged = !areCrdtListTotalsEqual(
+      subscribe.totals,
+      result.totals
     )
 
-    return this.subscribesUpgrading.get(subscribe.id)
-  }
+    subscribe.row_ids = nextIds
+    subscribe.totals = result.totals
 
-  // инциализация подписки
-  private async initSubscribe(client: WsServerSocket, subscribe: CuboCrdtServerSubscribe) {
-    if (this.subscribesIniting.has(subscribe.id)) {
-      return this.subscribesIniting.get(subscribe.id)
+    if (!forceSync && !idsChanged && !totalsChanged) {
+      return true
     }
 
-    this.subscribesIniting.set(
-      subscribe.id,
-      new Promise<void>(async (resolve, reject) => {
-        try {
-          if (this.debug) {
-            console.log('[CRDT] init subscribe ' + client.id, subscribe)
-          }
+    subscribe.revision += 1
+    const data: CuboCrdtListSyncData = {
+      ids: nextIds,
+      totals: subscribe.totals,
+      revision: subscribe.revision
+    }
 
-          await this.pushSubscribeDocuments(client, subscribe)
+    this.sendToClient(subscribe.client_id, {
+      action: 'sync',
+      entity: subscribe.entity,
+      subscribe_id: subscribe.id,
+      data
+    })
 
-          resolve()
-        } catch (e) {
-          if (this.debug) {
-            console.error('[CRDT] init subscribe', e)
-          }
+    return true
+  }
 
-          reject(e)
-        } finally {
-          this.subscribesIniting.delete(subscribe.id)
-        }
-      })
+  // апгрейд подписки (фильтры поменялись например)
+  private async upgradeSubscribe(
+    client: WsServerSocket,
+    subscribe: CuboCrdtServerSubscribe,
+    upgrade: Partial<Pick<CuboCrdtServerSubscribe, 'filters' | 'paginated'>>
+  ) {
+    if (this.debug) {
+      console.log('[CRDT] upgrade subscribe ' + client.id, subscribe)
+    }
+
+    if (upgrade.filters !== undefined) {
+      subscribe.filters = cloneDeep(upgrade.filters || {})
+    }
+    subscribe.paginated = this.resolvePaginated(
+      subscribe.filters,
+      upgrade.paginated
     )
 
-    return this.subscribesIniting.get(subscribe.id)
+    return this.requestSubscribeRefresh(subscribe.id, true)
+  }
+
+  // инциализация подписки
+  private async initSubscribe(client: WsServerSocket, subscribe: CuboCrdtServerSubscribe) {
+    if (this.debug) {
+      console.log('[CRDT] init subscribe ' + client.id, subscribe)
+    }
+
+    return this.requestSubscribeRefresh(subscribe.id, true)
   }
 
   private get debug() {