@cuboapp/crdt 1.0.24 → 1.0.26

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cuboapp/crdt",
-  "version": "1.0.24",
+  "version": "1.0.26",
   "description": "CRDT for CUBO",
   "main": "src/index.ts",
   "repository": {

package/src/client/index.ts

@@ -25,6 +25,8 @@ export * from './types'
 
 export class CuboCrdtClient<M> {
   public store: CuboCrdtClientStore<M> = {}
+  // Реактивен только реестр: Vue отслеживает set/delete и повторно вычисляет
+  // computed(useDoc). Сами Y.Doc/Awareness остаются исходными объектами без proxy.
   public docs = new Map<string, CuboCrdtClientDoc>()
 
   private listeners: Map<string, Map<string, (ctx: CuboCrdtClientSubscribeEvent) => void | Promise<void>>> = new Map()
@@ -108,6 +110,11 @@ export class CuboCrdtClient<M> {
 
     this.ws.deleteHandler(CUBO_CRDT_EVENT.EVENT)
 
+    for (const document of this.docs.values()) {
+      document.awareness?.destroy()
+      document.doc.destroy()
+    }
+    this.docs.clear()
     this.listeners.clear()
     this.subscriptions.clear()
   }
@@ -231,8 +238,7 @@ export class CuboCrdtClient<M> {
       })
 
       this.store[storeKey] = {
-        state,
-        awarenesses: new Map()
+        state
       }
     }
 
@@ -343,31 +349,13 @@ export class CuboCrdtClient<M> {
       this.store[storeKey]!.state.status = 'idle'
       this.store[storeKey]!.state.error = undefined
 
+      const item = this.store[storeKey]
+      item?.state.rows.forEach((row) => {
+        this.detachDocument(`${entity}`, (row as any).id, subscribe_id, storeKey)
+      })
+
       // очищаем стор
       if (clear !== false) {
-        const item = this.store[storeKey]
-        if (item) {
-          item.awarenesses?.forEach((a) => {
-            removeAwarenessStates(a, [a.doc.clientID], 'unsubscribe')
-
-            a.setLocalState(null)
-            a.destroy()
-          })
-          item.awarenesses?.clear()
-
-          item.state.rows?.map((row) => {
-            const doc = this.docs.get(`${entity}:${(row as any).id}`)
-            if (doc) {
-              doc.subscribes.delete(subscribe_id)
-
-              if (doc.subscribes?.size === 0) {
-                doc.doc.destroy()
-                this.docs.delete(`${entity}:${(row as any).id}`)
-              }
-            }
-          })
-        }
-
         this.store[storeKey] = undefined
       }
     }
@@ -389,7 +377,6 @@ export class CuboCrdtClient<M> {
       subscribe,
       upgrade,
       unsubscribe,
-      awarenesses: opts?.awareness ? computed(() => this.store[storeKey]?.awarenesses) : undefined,
       subscribed: () => computed(() => this.store[storeKey]?.state.subscribed || false),
       loading: () => computed(() => this.store[storeKey]?.state.loading || false),
       ready: () => computed(() => this.store[storeKey]?.state.status === 'ready'),
@@ -402,6 +389,10 @@ export class CuboCrdtClient<M> {
     }
   }
 
+  public useDoc<K extends Extract<keyof M, string>>(entity: K, id: number) {
+    return this.docs.get(`${entity}:${id}`)
+  }
+
   public useRow<K extends Extract<keyof M, string>, T = CuboCrdtKey<K, M>>(
     entity: K | string,
     id: number,
@@ -409,18 +400,15 @@ export class CuboCrdtClient<M> {
   ): CuboCrdtClientRow<T> {
     // console.log('store key', opts?.storeKey ?? `${entity}:${id}`)
 
-    const { subscribe_id, storeKey, awarenesses, subscribe, upgrade, unsubscribe, subscribed, loading, ready, status, error } =
-      this.useList(entity, {
-        ...opts,
-        filters: opts?.filters ?? { id },
-        storeKey: opts?.storeKey ?? `${entity}:${id}`
-      })
+    const { subscribe_id, storeKey, subscribe, upgrade, unsubscribe, subscribed, loading, ready, status, error } = this.useList(entity, {
+      ...opts,
+      filters: opts?.filters ?? { id },
+      storeKey: opts?.storeKey ?? `${entity}:${id}`
+    })
 
     return {
       subscribe_id,
       storeKey,
-      doc: this.docs.get(`${entity}:${id}`)?.doc,
-      awareness: computed(() => awarenesses?.value?.get(id)),
       subscribe,
       upgrade,
       unsubscribe,
@@ -437,54 +425,34 @@ export class CuboCrdtClient<M> {
     }
   }
 
-  public update<K extends string>(
+  public update<K extends Extract<keyof M, string>>(
     entity: K,
     entity_id: number,
     dto: K extends Extract<keyof M, string> ? Partial<M[K]> : object,
     opts?: CuboCrdtClientDocOrigin
   ) {
-    const storeKey = `${entity}:${entity_id}`
-
-    const cardRow = this.store[storeKey]?.state.rows?.[0]
-    const listRow = this.store[entity]?.state?.rows.find((r: any) => r.id === entity_id)
-    const doc = this.docs.get(storeKey)
+    const document = this.docs.get(`${entity}:${entity_id}`)
 
-    // обновляем документ
-    if (doc) {
-      const map = doc.doc.getMap()
-
-      // "или" - потому что они синхронизированы (без разницы какой брать)
-      const row = (cardRow || listRow) as any
-      const toUpdate = Object.fromEntries(Object.entries(dto).filter(([key, value]) => row[key] !== value))
+    if (document) {
+      const map = document.doc.getMap()
+      const toUpdate = Object.fromEntries(Object.entries(dto).filter(([key, value]) => map.get(key) !== value))
 
       if (Object.keys(toUpdate).length) {
         const origin: CuboCrdtClientDocOrigin = {
           store: opts?.store ?? true,
           expose: opts?.expose ?? 'other',
           keys: opts?.keys ?? Object.keys(toUpdate),
-          react: true // отправляем на бэк
+          react: true,
+          subscribe_id: opts?.subscribe_id ?? document.subscribes.values().next().value
         }
 
-        doc.doc.transact(() => {
+        document.doc.transact(() => {
           Object.entries(toUpdate).forEach(([key, value]) => {
             map.set(key, value)
           })
         }, origin)
       }
     }
-
-    // обновляем реактивку
-    for (const row of [cardRow, listRow]) {
-      if (row) {
-        const toUpdate = Object.fromEntries(Object.entries(dto).filter(([key, value]) => row[key as keyof typeof row] !== value))
-
-        if (Object.keys(toUpdate).length) {
-          Object.entries(toUpdate).forEach(([key, value]) => {
-            row[key as keyof typeof row] = value
-          })
-        }
-      }
-    }
   }
 
   public upgrade(subscribe_id: string, filters?: Record<string, any>) {
@@ -528,6 +496,80 @@ export class CuboCrdtClient<M> {
       })
   }
 
+  private applyDocumentRows(entity_id: number, document: CuboCrdtClientDoc) {
+    for (const subscribe_id of document.subscribes) {
+      const subscription = this.subscriptions.get(subscribe_id)
+      if (subscription) {
+        this.applyRowJson(subscription.storeKey, entity_id, document.doc)
+      }
+    }
+  }
+
+  private attachDocument(entity: string, entity_id: number, document: CuboCrdtClientDoc, opts: CuboCrdtClientDocUpdateOptions) {
+    document.subscribes.add(opts.subscribe_id)
+
+    if (!opts.awareness) {
+      return
+    }
+
+    document.awarenessSubscribes.add(opts.subscribe_id)
+
+    if (!document.awareness) {
+      const awareness = new Awareness(document.doc)
+
+      awareness.on('update', ({ added, updated, removed }, origin) => {
+        if (origin === 'remote') {
+          return
+        }
+
+        const subscribe_id = document.awarenessSubscribes.values().next().value
+        if (!subscribe_id) {
+          return
+        }
+
+        const changed = added.concat(updated).concat(removed)
+        const update = encodeAwarenessUpdate(awareness, changed)
+
+        void this.ws
+          .request({
+            method: CUBO_CRDT_EVENT.EVENT,
+            data: {
+              action: 'awareness',
+              entity,
+              entity_id,
+              data: Array.from(update),
+              origin: { expose: 'other', subscribe_id }
+            }
+          })
+          .catch((error) => console.error('[CRDT] awareness request failed', error))
+      })
+      document.awareness = awareness
+    }
+  }
+
+  private detachDocument(entity: string, entity_id: number, subscribe_id: string, storeKey: string) {
+    const key = `${entity}:${entity_id}`
+    const document = this.docs.get(key)
+    if (!document) {
+      return
+    }
+
+    document.subscribes.delete(subscribe_id)
+    document.awarenessSubscribes.delete(subscribe_id)
+
+    if (!document.awarenessSubscribes.size && document.awareness) {
+      removeAwarenessStates(document.awareness, [document.awareness.doc.clientID], 'unsubscribe')
+      document.awareness.setLocalState(null)
+      document.awareness.destroy()
+      document.awareness = undefined
+    }
+
+    if (!document.subscribes.size) {
+      document.doc.destroy()
+      this.docs.delete(key)
+    }
+  }
+
   // апсертит строку в реактивное хранилище из текущего состояния yjs-документа
   private applyRowJson(storeKey: string, entity_id: number, doc: Doc) {
     const json: any = doc.getMap().toJSON()
@@ -559,6 +601,7 @@ export class CuboCrdtClient<M> {
         console.log('[CRDT] onDocumentCreate: doc already exists, merging state', { ctx, opts })
       }
 
+      this.attachDocument(ctx.entity, entity_id, existing, opts)
       applyUpdate(existing.doc, new Uint8Array(ctx.data as any), { react: false })
       this.applyRowJson(opts.storeKey, entity_id, existing.doc)
       return
@@ -577,8 +620,20 @@ export class CuboCrdtClient<M> {
 
     applyUpdate(yjsDoc, update, { react: false })
 
+    const document: CuboCrdtClientDoc = {
+      doc: yjsDoc,
+      subscribes: new Set(),
+      awarenessSubscribes: new Set()
+    }
+    this.attachDocument(ctx.entity, entity_id, document, opts)
+    // Публикуем контейнер реактивному реестру только после полной инициализации.
+    // Тогда первый computed(useDoc) не увидит промежуточный doc без Awareness.
+    this.docs.set(`${ctx.entity}:${ctx.entity_id}`, document)
+
     // подписываемся на обновления документа
     yjsDoc.on('update', (update, origin: CuboCrdtClientDocOrigin) => {
+      this.applyDocumentRows(entity_id, document)
+
       // react = false, если это апдейт с бэка
       if (origin?.react !== false) {
         const data: CuboCrdtServerDocumentIncomingAction = {
@@ -592,21 +647,19 @@ export class CuboCrdtClient<M> {
             // приходят без expose и сервер эхом шлёт их обратно самому автору.
             expose: 'other',
             ...pick(origin || {}, ['store', 'keys', 'expose']),
-            subscribe_id: opts?.subscribe_id
+            subscribe_id: origin?.subscribe_id ?? document.subscribes.values().next().value
           }
         }
 
-        this.ws.request({
-          method: CUBO_CRDT_EVENT.EVENT,
-          data
-        })
+        void this.ws
+          .request({
+            method: CUBO_CRDT_EVENT.EVENT,
+            data
+          })
+          .catch((error) => console.error('[CRDT] update request failed', error))
       }
     })
 
-    // добавляем документ в хранилище документов
-    const doc: CuboCrdtClientDoc = { doc: yjsDoc, subscribes: new Set() }
-    this.docs.set(`${ctx.entity}:${ctx.entity_id}`, doc)
-
     // добавляем документ в реактивное хранилище
     const json: any = yjsDoc.getMap().toJSON()
     const index = this.store[opts.storeKey]?.state.rows.findIndex((r: any) => r.id === entity_id)
@@ -623,39 +676,6 @@ export class CuboCrdtClient<M> {
     if (opts?.onAfterCreate) {
       await opts.onAfterCreate(yjsDoc, update, ctx, opts)
     }
-
-    if (opts?.awareness) {
-      let awareness = this.store[opts.storeKey]?.awarenesses.get(entity_id)
-
-      if (!awareness) {
-        awareness = new Awareness(yjsDoc)
-
-        awareness.on('update', ({ added, updated, removed }, origin) => {
-          // console.log('[CRDT] awarness update', origin)
-
-          if (origin === 'remote') {
-            return
-          }
-
-          const changed = added.concat(updated).concat(removed)
-          const update = encodeAwarenessUpdate(awareness, changed)
-
-          this.ws.request({
-            method: CUBO_CRDT_EVENT.EVENT,
-            data: {
-              action: 'awareness',
-              entity: ctx.entity,
-              entity_id,
-              data: Array.from(update),
-              // 'other' — не шлём свой же курсор обратно исходной подписке
-              origin: { expose: 'other', subscribe_id: opts.subscribe_id }
-            }
-          })
-        })
-
-        this.store[opts.storeKey]?.awarenesses.set(entity_id, awareness)
-      }
-    }
   }
 
   private async onDocumentUpdate(ctx: CuboCrdtClientSubscribeEvent, opts: CuboCrdtClientDocUpdateOptions) {
@@ -682,8 +702,8 @@ export class CuboCrdtClient<M> {
     // обновляем yjs-ный документ
     applyUpdate(doc.doc, update, { react: false })
 
-    // обновляем документ в реактивном хранилище
-    this.applyRowJson(opts.storeKey, entity_id, doc.doc)
+    // один канонический документ обновляет проекции всех активных подписок
+    this.applyDocumentRows(entity_id, doc)
 
     if (opts?.onAfterUpdate) {
       await opts.onAfterUpdate(doc.doc, update, ctx, opts)
@@ -709,25 +729,18 @@ export class CuboCrdtClient<M> {
       }
     }
 
-    doc.doc.destroy()
-    this.docs.delete(`${ctx.entity}:${ctx.entity_id}`)
-
-    const index = this.store[opts.storeKey]?.state.rows.findIndex((r: any) => r.id === entity_id)
-    if (index !== undefined && index >= 0) {
-      this.store[opts.storeKey]?.state.rows.splice(index, 1)
-    } else {
-      if (this.debug) {
-        console.log('[CRDT] row not found', index, ctx, opts)
+    for (const subscribe_id of doc.subscribes) {
+      const subscription = this.subscriptions.get(subscribe_id)
+      const item = subscription && this.store[subscription.storeKey]
+      const index = item?.state.rows.findIndex((row: any) => row.id === entity_id) ?? -1
+      if (item && index >= 0) {
+        item.state.rows.splice(index, 1)
       }
     }
 
-    const awareness = this.store[opts.storeKey]?.awarenesses.get(entity_id)
-    if (awareness) {
-      removeAwarenessStates(awareness, [awareness.doc.clientID], 'unsubscribe')
-
-      awareness.destroy()
-      this.store[opts.storeKey]?.awarenesses?.delete(entity_id)
-    }
+    doc.awareness?.destroy()
+    doc.doc.destroy()
+    this.docs.delete(`${ctx.entity}:${ctx.entity_id}`)
 
     if (opts?.onAfterDelete) {
       await opts.onAfterDelete(doc.doc, ctx, opts)
@@ -772,19 +785,7 @@ export class CuboCrdtClient<M> {
         continue
       }
 
-      const awareness = item.awarenesses.get(entity_id)
-      if (awareness) {
-        removeAwarenessStates(awareness, [awareness.doc.clientID], 'sync')
-        awareness.setLocalState(null)
-        awareness.destroy()
-        item.awarenesses.delete(entity_id)
-      }
-
-      const doc = this.docs.get(`${ctx.entity}:${entity_id}`)
-      if (doc) {
-        doc.doc.destroy()
-        this.docs.delete(`${ctx.entity}:${entity_id}`)
-      }
+      this.detachDocument(ctx.entity, entity_id, opts.subscribe_id, opts.storeKey)
     }
 
     const rowsById = new Map(item.state.rows.map((row: any) => [Number(row.id), row]))
@@ -805,15 +806,15 @@ export class CuboCrdtClient<M> {
       return
     }
 
-    const awareness = this.store[opts.storeKey]?.awarenesses?.get(entity_id)
-    if (!awareness) {
+    const doc = this.docs.get(`${ctx.entity}:${ctx.entity_id}`)
+    if (!doc?.awareness) {
       return
     }
 
     const update = new Uint8Array(ctx.data as any)
 
     try {
-      applyAwarenessUpdate(awareness, update, 'remote')
+      applyAwarenessUpdate(doc.awareness, update, 'remote')
     } catch (e) {
       console.warn('[CRDT] applyAwarenessUpdate failed ', e)
     }

package/src/client/types/document.ts

@@ -1,4 +1,6 @@
+import { Awareness } from 'y-protocols/awareness'
 import { Doc } from 'yjs'
+
 import { CuboCrdtClientUseOptions } from '..'
 import { CuboCrdtExposeStrategy } from '../../types'
 
@@ -7,6 +9,8 @@ import { CuboCrdtClientBaseOptions } from './utils'
 export type CuboCrdtClientDoc = {
   doc: Doc
   subscribes: Set<string>
+  awareness?: Awareness
+  awarenessSubscribes: Set<string>
 }
 
 export type CuboCrdtClientDocOrigin = {
@@ -21,6 +25,9 @@ export type CuboCrdtClientDocOrigin = {
 
   // куда раскатывать обновления - всем или всем кроме себя
   expose?: CuboCrdtExposeStrategy
+
+  // подписка, из которой инициировано локальное изменение
+  subscribe_id?: string
 }
 
 export type CuboCrdtClientDocUpdateOptions = { subscribe_id: string; storeKey: string } & Pick<

package/src/client/types/index.ts

@@ -4,7 +4,6 @@ import { Awareness } from 'y-protocols/awareness'
 
 import { CuboCrdtAction, CuboCrdtListSyncData, CuboCrdtListTotals, CuboCrdtSubscriptionStatus } from '../../types'
 
-import { Doc } from 'yjs'
 import { CuboCrdtClientBaseOptions } from './utils'
 
 export * from './document'
@@ -58,8 +57,6 @@ export type CuboCrdtClientList<T> = {
 export type CuboCrdtClientRow<T> = {
   subscribe_id: string
   storeKey: string
-  doc: Doc
-  awareness?: ComputedRef<Awareness | undefined>
   subscribe: () => void
   upgrade: (filters?: any) => void
   unsubscribe: (clear?: boolean) => void

package/src/client/types/store.ts

@@ -1,5 +1,4 @@
 import { Reactive } from 'vue'
-import { Awareness } from 'y-protocols/awareness'
 
 import { CuboCrdtKey, CuboCrdtListTotals, CuboCrdtSubscriptionStatus } from '../../types'
 
@@ -13,7 +12,6 @@ export type CuboCrdtClientStoreItem<T> = {
     totals: CuboCrdtListTotals
     revision: number
   }>
-  awarenesses: Map<number, Awareness>
 }
 export type CuboCrdtClientStore<M> = Partial<{
   [K in string]: CuboCrdtClientStoreItem<CuboCrdtKey<K, M>>

package/src/server/document/index.ts

@@ -1,12 +1,23 @@
-import { cloneDeep, debounce, pick } from '@cuboapp/utils'
+import { cloneDeep, pick } from '@cuboapp/utils'
 import { applyUpdate, Doc, encodeStateAsUpdate } from 'yjs'
 import { Awareness, encodeAwarenessUpdate } from 'y-protocols/awareness'
 
-import { CuboCrdtServerDocumentOptions, CuboCrdtServerDocumentOrigin } from '../types'
+import {
+  CuboCrdtServerDocumentOptions,
+  CuboCrdtServerDocumentOrigin,
+  CuboCrdtServerDocumentPendingStore
+} from '../types'
+import { getCrdtStoreChangeKey } from '../utils'
+
+const STORE_DEBOUNCE_MS = 300
 
 export class CuboCrdtServerDocument {
   private ydoc: Doc
   private persistedState: object = {}
+  private observedState: object = {}
+  private storeQueue?: Promise<void>
+  private pendingStore?: CuboCrdtServerDocumentPendingStore
+  private storeTimeout?: ReturnType<typeof setTimeout>
   public awareness: Awareness
   public awarenessBySubscribe = new Map<string, Set<number>>()
 
@@ -19,31 +30,11 @@ export class CuboCrdtServerDocument {
     })
 
     if (opts.awareness) {
-      this.awareness = new Awareness(this.ydoc)
-      this.awareness.setLocalState(null)
-
-      this.awareness.on('update', ({ added, updated, removed }, origin: CuboCrdtServerDocumentOrigin) => {
-        const subId = origin?.subscribe_id
-
-        if (subId) {
-          let set = this.awarenessBySubscribe.get(subId)
-          if (!set) {
-            set = new Set()
-            this.awarenessBySubscribe.set(subId, set)
-          }
-
-          added.concat(updated).forEach((id) => set!.add(id))
-          removed.forEach((id) => set!.delete(id))
-        }
-
-        const changed = added.concat(updated).concat(removed)
-        const update = encodeAwarenessUpdate(this.awareness!, changed)
-
-        this.opts?.onAwarenessUpdate?.(update, origin)
-      })
+      this.enableAwareness()
     }
 
     this.persistedState = cloneDeep(opts.initialState ?? {})
+    this.observedState = cloneDeep(opts.initialState ?? {})
 
     // записываем исходное состояние
     this.write(opts.initialState ?? {})
@@ -58,7 +49,8 @@ export class CuboCrdtServerDocument {
       this.opts?.onUpdate?.(data, origin)
       // }
 
-      // если нужно сохранять стейт документа - вызываем store по дебаунсу
+      // Состояние отслеживается синхронно с Y.Doc. Для клиентских изменений
+      // debounceStore сам обновит observedState после вычисления leaf-diff.
       if (origin?.store) {
         const row = this.getJson()
         const body = pick(row, origin.keys ?? Object.keys(row))
@@ -68,10 +60,41 @@ export class CuboCrdtServerDocument {
             console.error('[CRDT] store document', this.name, error)
           })
         }
+      } else {
+        this.observedState = cloneDeep(this.getJson())
       }
     })
   }
 
+  public enableAwareness() {
+    if (this.awareness) {
+      return
+    }
+
+    this.awareness = new Awareness(this.ydoc)
+    this.awareness.setLocalState(null)
+
+    this.awareness.on('update', ({ added, updated, removed }, origin: CuboCrdtServerDocumentOrigin) => {
+      const subId = origin?.subscribe_id
+
+      if (subId) {
+        let set = this.awarenessBySubscribe.get(subId)
+        if (!set) {
+          set = new Set()
+          this.awarenessBySubscribe.set(subId, set)
+        }
+
+        added.concat(updated).forEach((id) => set!.add(id))
+        removed.forEach((id) => set!.delete(id))
+      }
+
+      const changed = added.concat(updated).concat(removed)
+      const update = encodeAwarenessUpdate(this.awareness!, changed)
+
+      this.opts?.onAwarenessUpdate?.(update, origin)
+    })
+  }
+
   public get name() {
     return this.opts.name
   }
@@ -133,13 +156,138 @@ export class CuboCrdtServerDocument {
     this.ydoc.destroy()
   }
 
-  public async store(body: object, origin: CuboCrdtServerDocumentOrigin) {
-    const previousRow = this.getPersistedState()
-    const row = this.getJson()
+  /**
+   * Немедленно передаёт trailing-пакет в очередь и ждёт все уже принятые
+   * сохранения документа. Используется перед вытеснением Y.Doc из серверного
+   * кэша, чтобы refresh последнего клиента не потерял его update.
+   */
+  public async flushStoreQueue() {
+    this.flushPendingStore()
+
+    while (this.storeQueue) {
+      await this.storeQueue
+      this.flushPendingStore()
+    }
+  }
+
+  /** Есть ли принятое клиентское изменение в debounce или очереди записи. */
+  public hasPendingStore() {
+    return !!this.pendingStore || !!this.storeQueue
+  }
+
+  public store(body: object, origin: CuboCrdtServerDocumentOrigin, row = this.getJson()) {
+    const queuedBody = cloneDeep(body)
+    const queuedRow = cloneDeep(row)
+    // debounce ограничивает частоту вызовов, но не сериализует async store.
+    // Без очереди следующий PATCH мог завершиться раньше предыдущего и затем
+    // быть затёрт старым полным снимком составного поля (например case.extra).
+    const previous = this.storeQueue?.catch(() => undefined) ?? Promise.resolve()
+    const current = previous
+      .then(async () => {
+        const previousRow = this.getPersistedState()
+
+        await this.opts?.onStore?.(queuedBody, origin, {
+          previousRow,
+          row: queuedRow
+        })
+        this.setPersistedState(queuedRow)
+      })
+
+    const queued = current.finally(() => {
+      // Если после этой записи не добавилась следующая, очередь опустела.
+      // Сама Promise-цепочка является источником истины — отдельный счётчик не нужен.
+      if (this.storeQueue === queued) {
+        this.storeQueue = undefined
+      }
+    })
+    this.storeQueue = queued
+
+    return queued
+  }
+
+  /**
+   * Схлопывает только соседние изменения одного origin и одного набора
+   * leaf-путей. Смена пользователя или поля немедленно фиксирует предыдущий
+   * пакет, сохраняя фактический порядок collaborative-обновлений.
+   */
+  public debounceStore(body: object, origin: CuboCrdtServerDocumentOrigin) {
+    const row = cloneDeep(this.getJson())
+    const bodyKeys = Object.keys(body)
+    const previousBody = pick(this.observedState, bodyKeys)
+    const changeKey = getCrdtStoreChangeKey(previousBody, body)
+    const originKey = `${origin.client_id || ''}:${origin.subscribe_id || ''}`
+
+    this.observedState = cloneDeep(row)
+
+    if (!changeKey) {
+      return Promise.resolve()
+    }
+
+    return new Promise<void>((resolve, reject) => {
+      const sameBatch = this.pendingStore?.originKey === originKey &&
+        this.pendingStore.changeKey === changeKey
+
+      if (this.pendingStore && !sameBatch) {
+        this.flushPendingStore()
+      }
 
-    await this.opts?.onStore?.(body, origin, { previousRow, row })
-    this.setPersistedState(row)
+      if (!this.pendingStore) {
+        this.pendingStore = {
+          body: cloneDeep(body),
+          changeKey,
+          origin: cloneDeep(origin),
+          originKey,
+          row,
+          waiters: []
+        }
+      } else {
+        const keys = new Set([
+          ...(this.pendingStore.origin.keys || []),
+          ...(origin.keys || [])
+        ])
+
+        this.pendingStore.body = {
+          ...this.pendingStore.body,
+          ...cloneDeep(body)
+        }
+        this.pendingStore.origin = {
+          ...cloneDeep(origin),
+          keys: [...keys]
+        }
+        this.pendingStore.row = row
+      }
+
+      this.pendingStore.waiters.push({ resolve, reject })
+      this.schedulePendingStore()
+    })
   }
 
-  public debounceStore = debounce(this.store.bind(this), 300)
+  /** Перезапускает trailing debounce для текущего однородного пакета. */
+  private schedulePendingStore() {
+    if (this.storeTimeout) {
+      clearTimeout(this.storeTimeout)
+    }
+
+    this.storeTimeout = setTimeout(() => this.flushPendingStore(), STORE_DEBOUNCE_MS)
+  }
+
+  /** Передаёт накопленный пакет в общую последовательную очередь записи. */
+  private flushPendingStore() {
+    if (!this.pendingStore) {
+      return
+    }
+
+    if (this.storeTimeout) {
+      clearTimeout(this.storeTimeout)
+      this.storeTimeout = undefined
+    }
+
+    const pending = this.pendingStore
+    this.pendingStore = undefined
+
+    this.store(pending.body, pending.origin, pending.row).then(
+      () => pending.waiters.forEach(({ resolve }) => resolve()),
+      (error) => pending.waiters.forEach(({ reject }) => reject(error))
+    )
+  }
 }

package/src/server/index.ts

@@ -36,6 +36,7 @@ export class CuboCrdtServer<M, A = {}, E extends Extract<keyof M, string> = Extr
   private subscribeGenerations = new Map<string, number>()
 
   private documents = new Map<string, CuboCrdtServerDocument>()
+  private documentEvictions = new Map<string, object>()
   private subscribesByDocument = new Map<string, Set<string>>()
   // обратный индекс: подписка -> имена документов, к которым она привязана.
   // Нужен, чтобы отписка/очистка не сканировала ВСЕ документы сервера (O(subs x docs)).
@@ -107,34 +108,76 @@ export class CuboCrdtServer<M, A = {}, E extends Extract<keyof M, string> = Extr
       this.cleanSubscribe(subscribe_id)
     })
 
-    this.ws.registerHandler(CUBO_CRDT_EVENT.EVENT, async ({ message }) => {
+    this.ws.registerHandler(CUBO_CRDT_EVENT.EVENT, async ({ client, message }) => {
       let data = message.data as any
       if (!Array.isArray(data)) {
         data = [data]
       }
 
       if (this.debug) {
-        console.log('[CRDT] incoming event', data)
+        console.log('[CRDT] incoming event', data.map((row: any) => ({
+          action: row.action,
+          entity: row.entity,
+          entity_id: row.entity_id,
+          keys: row.origin?.keys,
+          subscribe_id: row.origin?.subscribe_id
+        })))
       }
 
       for (const row of data) {
+        const subscribe_id = row.origin?.subscribe_id
+        const subscribe = subscribe_id && this.subscribes.get(subscribe_id)
+        const documentName = `${row.entity}:${row.entity_id}`
+        const requiresActiveSubscription = row.action === 'update' || row.action === 'awareness'
+
+        if (
+          requiresActiveSubscription &&
+          (!subscribe ||
+            subscribe.client_id !== client.id ||
+            subscribe.entity !== row.entity ||
+            !this.documentsBySubscribe.get(subscribe_id)?.has(documentName))
+        ) {
+          if (this.debug) {
+            console.warn('[CRDT] ignored update from inactive subscription', {
+              action: row.action,
+              entity: row.entity,
+              entity_id: row.entity_id,
+              subscribe_id
+            })
+          }
+          continue
+        }
+
         const update = new Uint8Array(row.data)
+        const origin: CuboCrdtServerDocumentOrigin = {
+          ...(row.origin || {}),
+          client_id: client.id,
+          store_context: {
+            client_id: client.id,
+            auth: cloneDeep(client.auth)
+          }
+        }
+        const action = { ...row, origin }
 
         switch (row.action) {
           case 'create':
-            this.onDocumentExternalCreate(update, row)
+            this.onDocumentExternalCreate(update, action)
             break
           case 'update':
-            this.onDocumentExternalUpdate(update, row)
+            this.onDocumentExternalUpdate(update, action)
             break
           case 'delete':
-            this.onDocumentExternalDelete(update, row)
+            this.onDocumentExternalDelete(update, action)
             break
           case 'awareness':
-            this.onAwarenessExternalUpdate(update, row)
+            this.onAwarenessExternalUpdate(update, action)
             break
         }
       }
+
+      // Ответ означает только «update применён к живому серверному Y.Doc».
+      // Debounce и последовательная запись в БД продолжаются независимо.
+      return { accepted: true }
     })
 
     this.ws.registerHttpHandler('GET', '/stats', () => {
@@ -170,8 +213,20 @@ export class CuboCrdtServer<M, A = {}, E extends Extract<keyof M, string> = Extr
     this.subscribeRefreshStates.forEach((state) => clearTimeout(state.timer))
     this.subscribeRefreshStates.clear()
     this.subscribeGenerations.clear()
+    this.documentEvictions.clear()
 
     this.subscribes.forEach((sub) => this.ws.deleteHandler(sub.id))
+
+    const documents = [...this.documents.values()]
+    const results = await Promise.allSettled(documents.map((document) => document.flushStoreQueue()))
+    results.forEach((result, index) => {
+      if (result.status === 'rejected') {
+        console.error('[CRDT] flush document on destroy', documents[index]?.name, result.reason)
+      }
+    })
+    documents.forEach((document) => document.destroy())
+    this.documents.clear()
+    this.subscribesByDocument.clear()
   }
 
   public addClient(client: WsServerSocket<{ auth?: A }>) {
@@ -282,6 +337,10 @@ export class CuboCrdtServer<M, A = {}, E extends Extract<keyof M, string> = Extr
 
   // привязываем подписку к документу (в обоих индексах)
   private linkSubscribeToDocument(subscribe_id: string, docName: string) {
+    // Новая подписка снова использует живой Y.Doc. Асинхронный flush может
+    // продолжаться, но больше не имеет права уничтожить этот документ.
+    this.documentEvictions.delete(docName)
+
     let byDoc = this.subscribesByDocument.get(docName)
     if (!byDoc) {
       byDoc = new Set()
@@ -305,17 +364,56 @@ export class CuboCrdtServer<M, A = {}, E extends Extract<keyof M, string> = Extr
 
   // если у документа нет подписок - сносим его
   private checkDocumentNeedRemove(name: string) {
-    if (!this.subscribesByDocument.get(name)?.size) {
-      if (this.debug) {
-        console.log('[CRDT] delete document', name)
-      }
+    if (this.subscribesByDocument.get(name)?.size || this.documentEvictions.has(name)) {
+      return
+    }
 
-      this.documents.get(name)?.destroy()
-      this.documents.delete(name)
-      // не оставляем пустой Set в индексе (иначе — медленная утечка записей мапы);
-      // getOrCreateDocument пересоздаст его при повторном появлении документа
+    const document = this.documents.get(name)
+    if (!document) {
       this.subscribesByDocument.delete(name)
+      return
+    }
+
+    // Последний клиент мог закрыться сразу после update (обычный refresh).
+    // Сначала сохраняем всю принятую очередь, а до её завершения оставляем Y.Doc
+    // доступным повторной подписке. Никакого фиксированного ожидания здесь нет.
+    const eviction = {}
+    this.documentEvictions.set(name, eviction)
+
+    if (this.debug) {
+      console.log('[CRDT] flush document before eviction', name)
     }
+
+    void document.flushStoreQueue()
+      .then(() => {
+        if (
+          this.documentEvictions.get(name) !== eviction ||
+          this.subscribesByDocument.get(name)?.size ||
+          this.documents.get(name) !== document
+        ) {
+          return
+        }
+
+        this.documentEvictions.delete(name)
+
+        if (this.debug) {
+          console.log('[CRDT] delete document', name)
+        }
+
+        document.destroy()
+        this.documents.delete(name)
+        this.subscribesByDocument.delete(name)
+      })
+      .catch((error) => {
+        // Не уничтожаем единственную живую копию документа, если запись в БД
+        // не завершилась. Снимаем eviction, чтобы следующая отписка или явная
+        // проверка могла повторно инициировать flush.
+        if (this.documentEvictions.get(name) === eviction) {
+          this.documentEvictions.delete(name)
+        }
+
+        console.error('[CRDT] flush document before eviction', name, error)
+      })
   }
 
   // очистка подписки (при отписке клиента - через emit-метод или options-хук).
@@ -584,20 +682,9 @@ export class CuboCrdtServer<M, A = {}, E extends Extract<keyof M, string> = Extr
 
     let document = this.documents.get(documentName)
     if (document) {
-      // Освежаем существующий документ строкой из БД.
-      //
-      // Раньше документ возвращался как есть, а подписка отправляла клиенту его
-      // stateAsUpdate — то есть КЭШ документа, а не только что прочитанную строку.
-      // Документ, проспавший мутацию, оставался устаревшим навсегда: даже перезагрузка
-      // страницы отдавала старое значение, потому что reconcile брал его же.
-      //
-      // Стало заметно после того, как документы без подписчиков начали удаляться:
-      // документ может быть создан, остаться без подписок, пропустить мутации и
-      // «воскреснуть» на новой подписке уже неактуальным.
-      //
-      // store: false — это не правка от клиента, а синхронизация с БД, писать обратно нечего.
-      document.write(row, { expose: 'all', store: false })
-      document.setPersistedState(row)
+      if (awareness) {
+        document.enableAwareness()
+      }
 
       return document
     }
@@ -614,7 +701,13 @@ export class CuboCrdtServer<M, A = {}, E extends Extract<keyof M, string> = Extr
       },
       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)
+        const liveClient = subscribe && this.clients.get(subscribe.client_id)
+        const client = liveClient || (origin.store_context
+          ? ({
+              id: origin.store_context.client_id,
+              auth: origin.store_context.auth
+            } as CuboCrdtSocketClient<A>)
+          : undefined)
 
         if (client) {
           return this.options?.storeRow?.(entity as any, entity_id, item as any, {
@@ -650,7 +743,13 @@ export class CuboCrdtServer<M, A = {}, E extends Extract<keyof M, string> = Extr
     const existed = this.documents.has(documentName)
     const document = this.getOrCreateDocument(entity, row, awareness)
 
-    if (!existed) {
+    if (existed && !document.hasPendingStore()) {
+      // Только внешний CRUD является подтверждённым источником из БД.
+      // Обычная повторная подписка не должна применять потенциально старую строку
+      // поверх живого документа с ещё не сохранённым collaborative update.
+      document.write(row, { expose: 'all', store: false })
+      document.setPersistedState(row)
+    } else {
       this.pushDocumentAction('create', entity, document, document.stateAsUpdate)
     }
 

package/src/server/types/document.ts

@@ -5,6 +5,20 @@ export type CuboCrdtServerDocumentStoreContext = {
   row: object
 }
 
+export type CuboCrdtServerDocumentStoreWaiter = {
+  resolve: () => void
+  reject: (reason?: unknown) => void
+}
+
+export type CuboCrdtServerDocumentPendingStore = {
+  body: object
+  changeKey: string
+  origin: CuboCrdtServerDocumentOrigin
+  originKey: string
+  row: object
+  waiters: CuboCrdtServerDocumentStoreWaiter[]
+}
+
 export type CuboCrdtServerDocumentOptions = {
   name: string
   onStore?: (
@@ -63,4 +77,16 @@ export type CuboCrdtServerDocumentOrigin = {
 
   // id клиента
   client_id?: string
+
+  /**
+   * Снимок серверного контекста автора в момент получения update.
+   *
+   * Он нужен только для отложенного сохранения: исходная подписка и сокет могут
+   * закрыться при refresh раньше, чем сработает debounce. Клиентское значение
+   * этого поля сервер всегда перезаписывает собственными данными.
+   */
+  store_context?: {
+    client_id: string
+    auth?: unknown
+  }
 }

package/src/server/utils/index.ts

@@ -0,0 +1,41 @@
+const isObject = (value: unknown): value is Record<string, unknown> => {
+  return value !== null && typeof value === 'object'
+}
+
+const collectChangedPaths = (
+  previous: unknown,
+  current: unknown,
+  path: string,
+  result: string[]
+) => {
+  if (Object.is(previous, current)) {
+    return
+  }
+
+  if (!isObject(previous) || !isObject(current)) {
+    result.push(path || '$')
+    return
+  }
+
+  const keys = new Set([
+    ...Object.keys(previous),
+    ...Object.keys(current)
+  ])
+
+  for (const key of [...keys].sort()) {
+    const nextPath = Array.isArray(previous) || Array.isArray(current)
+      ? `${path}[${key}]`
+      : path ? `${path}.${key}` : key
+
+    collectChangedPaths(previous[key], current[key], nextPath, result)
+  }
+}
+
+/** Возвращает стабильный ключ фактически изменённых leaf-путей объекта. */
+export const getCrdtStoreChangeKey = (previous: object, current: object) => {
+  const paths: string[] = []
+
+  collectChangedPaths(previous, current, '', paths)
+
+  return paths.join('|')
+}