agentik/SYNC-SYSTEM.md

ТЗ: Синхронизация клиент-сервер для чат-приложения с локальными и удалёнными ассистентами

0. Контекст и цель

Есть приложение-чат. В чатах пользователь общается с ассистентами. Ассистенты бывают:

• удалённые — работают на сервере;
• локальные — работают прямо на устройстве клиента.

Приложение должно:

• работать офлайн (пользователь может читать и писать, пока нет сети);
• отрисовывать UI мгновенно, не дожидаясь сети;
• бесшовно синхронизироваться, когда сеть появляется;
• использовать один и тот же код для клиента и сервера там, где это возможно;
• не хранить события вечно — журнал событий компактится.

Ключевая архитектурная идея: клиент рисует UI исключительно из своей локальной базы. Сетевые запросы нужны только для синхронизации, а не для отрисовки.

---

1. Основные понятия (глоссарий)

Термин	Определение
Событие (Event)	Атомарный факт изменения состояния. Append-only. Имеет монотонный курсор seq.
Журнал событий (Event Log)	Упорядоченная по seq последовательность событий. Append-only. Подвергается компакции.
Материализованное состояние (Materialized State)	Текущее состояние домена (чаты, сообщения), полученное применением событий. Изменяемое. Каждая строка имеет last_seq — курсор последнего события, которое её изменило.
Курсор (seq)	Монотонно возрастающее целое число. Глобально уникальное. Присваивается сервером при записи события.
Состояние на курсоре N	Множество строк материализованного состояния, у которых last_seq <= N. Это «снимок» состояния на момент N.
Апдейты после N	Множество событий из журнала, у которых seq > N.
Full resync	Полная замена локального состояния клиента состоянием с сервера. Не merge, а replace.
Live sync	Инкрементальная догрузка событий после известного курсора.
Компакция	Удаление старых событий из журнала, которые уже «схлопнуты» в материализованное состояние.

---

2. Инварианты системы

Эти инварианты должны соблюдаться всегда. Если хоть один нарушен — система некорректна.

1. Курсор монотонен. seq строго возрастает. Никаких дыр, никаких сбросов.
2. Журнал append-only. События не изменяются и не удаляются, кроме как через компакцию.
3. Материализация консистентна журналу. Для любого N: apply(events where seq <= N) == SELECT * FROM state WHERE last_seq <= N. Это значит, что материализованное состояние — это не «что-то отдельное», а результат применения журнала.
4. События самодостаточны. Каждое событие несёт полный payload изменённой сущности, а не дельту. Это нужно, чтобы клиент мог применить событие к незнакомой сущности.
5. Full resync = replace. При полной синхронизации клиент заменяет своё локальное состояние, а не мержит.
6. Клиент отрисовывает только из локальной базы. Никакой запрос к серверу не блокирует UI.
7. Компакция не удаляет события, которые ещё нужны активным клиентам. Либо удаляет, но тогда клиент обязан сделать full resync.

---

3. Модель данных

3.1. На сервере

3.1.1. Журнал событий

EventLog:
  seq          : int64, PK, монотонный
  event_id     : UUID, уникальный идентификатор события
  type         : enum (ChatCreated, MessageAppended, MessageEdited, MessageDeleted,
                        ToolCallRequested, ToolCallSucceeded, ToolCallFailed, ...)
  payload      : JSON / бинарный blob с полным состоянием изменённой сущности
  created_at   : timestamp
  origin       : device_id / user_id / assistant_id (кто породил)

Индексы: PK(seq), INDEX(created_at).

3.1.2. Материализованное состояние

Отдельные таблицы под каждую сущность. Примеры:

Chat:
  id           : UUID, PK
  title        : string
  created_at   : timestamp
  deleted      : bool
  last_seq     : int64   -- курсор последнего события, изменившего строку

Message:
  id           : UUID, PK
  chat_id      : UUID, FK -> Chat.id
  role         : enum (user, assistant, tool_call, tool_result, error)
  content      : blob
  parent_id    : UUID, nullable (для ветвлений)
  deleted      : bool
  last_seq     : int64
  created_at   : timestamp

Индексы: PK(id), INDEX(chat_id, last_seq), INDEX(last_seq).

Важно: поле last_seq — это не «версия строки» в смысле MVCC. Это «на каком событии строка стала такой, какая она сейчас». Строка всегда хранит только актуальную версию.

3.1.3. Метаданные компакции

CompactionState:
  min_available_seq : int64   -- самый старый курсор, который ещё можно запросить
  last_compacted_at : timestamp

Если клиент запрашивает курсор < min_available_seq — сервер отвечает «курсор протух, делай full resync».

3.2. На клиенте

Клиент хранит те же таблицы, что и сервер (материализованное состояние), плюс дополнительно:

SyncState:
  last_seq         : int64   -- курсор, до которого клиент синхронизирован
  last_sync_at     : timestamp

PendingEvent:
  local_id         : UUID, PK
  type             : enum
  payload          : JSON
  created_at       : timestamp
  status           : enum (pending, sent, failed)

PendingEvent — это события, которые клиент сгенерировал локально (пользователь написал сообщение, локальный ассистент ответил), но которые ещё не подтверждены сервером.

Важно: PendingEvent не имеет seq — он появится только после подтверждения сервером.

---

4. Абстракции кода

4.1. Общие для клиента и сервера

// Доменные события — общие
sealed interface DomainEvent {
    val eventId: UUID
    val type: EventType
    val payload: EventPayload
}

// Материализованное состояние — общее
interface StateStore {
    fun readState(upToSeq: Long): StateSnapshot
    fun applyEvent(event: LoggedEvent)  // применяет событие к состоянию
    fun lastSeq(): Long
}

// Журнал — общий интерфейс чтения
interface EventLog {
    fun readUpdates(afterSeq: Long, limit: Int): List<LoggedEvent>
    fun lastSeq(): Long
}

// Событие с назначенным курсором
data class LoggedEvent(
    val seq: Long,
    val eventId: UUID,
    val type: EventType,
    val payload: EventPayload,
    val createdAt: Instant,
)

4.2. Только сервер

interface EventLogWriter : EventLog {
    // Атомарно: назначает seq, пишет в журнал, применяет к материализации
    fun append(event: DomainEvent): LoggedEvent
    // Компакция
    fun compact(upToSeq: Long)
}

4.3. Только клиент

interface EventLogReplica : EventLog {
    // Применить событие от сервера к локальному состоянию
    fun applyRemote(event: LoggedEvent)
    // Заменить всё локальное состояние состоянием с сервера
    fun replaceState(snapshot: StateSnapshot, upToSeq: Long)
    // Локальные (ещё не подтверждённые) события
    fun pendingEvents(): List<PendingEvent>
    fun markPendingAsSent(localId: UUID, seq: Long)
    fun markPendingAsFailed(localId: UUID)
}

4.4. Ассистент — общая абстракция

Ключевая идея прозрачности: ассистент — это просто генератор событий. Клиент не знает, локальный он или удалённый.

interface Assistant {
    // Запускает генерацию, возвращает поток событий
    fun run(input: RunInput): Flow<DomainEvent>
}

class RemoteAssistant(...) : Assistant {
    override fun run(input: RunInput): Flow<DomainEvent> {
        // Стримит события от сервера через WebSocket
    }
}

class LocalAssistant(...) : Assistant {
    override fun run(input: RunInput): Flow<DomainEvent> {
        // Генерирует события локально (например, вызывает локальную LLM)
    }
}

Клиент подписывается на поток событий и применяет их так же, как события от сервера. Локальный ассистент порождает PendingEvent, который потом уходит на сервер и подтверждается.

---

5. Протокол синхронизации

5.1. Точки входа (API)

GET /sync/state?upToSeq=N

• Возвращает материализованное состояние на момент N: SELECT * FROM state WHERE last_seq <= N.
• Если N не указан — возвращает актуальное состояние.
• Если N < min_available_seq — возвращает ошибку cursor_expired с указанием актуального last_seq.
• Ответ: { snapshot: StateSnapshot, upToSeq: N, currentSeq: M }, где M — текущий максимальный курсор.

GET /sync/updates?afterSeq=N&limit=K

• Возвращает события WHERE seq > N ORDER BY seq LIMIT K.
• Если N < min_available_seq — ошибка cursor_expired.
• Ответ: { events: [LoggedEvent], hasMore: bool, currentSeq: M }.

WS /sync/live?afterSeq=N

• WebSocket. Сервер пушит события seq > N в реальном времени.
• Если N < min_available_seq — сервер закрывает соединение с кодом cursor_expired.

POST /sync/events

• Клиент отправляет PendingEvent(ы) на сервер.
• Сервер валидирует, назначает seq, применяет, возвращает LoggedEvent(ы).
• Идемпотентность: eventId (UUID). Повторная отправка того же eventId — no-op, возвращается уже назначенный seq.

5.2. Алгоритм синхронизации на клиенте

sync():
  1. Прочитать local lastSeq.
  2. Попробовать GET /sync/updates?afterSeq=lastSeq&limit=K.
  3. Если ответ cursor_expired:
       3.1. GET /sync/state (без upToSeq) → получить актуальное состояние и currentSeq.
       3.2. replaceState(snapshot, currentSeq).
       3.3. lastSeq = currentSeq.
       3.4. Перейти к шагу 5.
  4. Если ответ ок:
       4.1. Для каждого события в ответе: applyRemote(event).
       4.2. lastSeq = max(seq в ответе).
       4.3. Если hasMore — повторить с шага 2.
  5. Отправить все PendingEvent через POST /sync/events.
       5.1. Для каждого подтверждённого: markPendingAsSent(localId, seq).
       5.2. Для каждого неподтверждённого: markPendingAsFailed(localId).
  6. Открыть WS /sync/live?afterSeq=lastSeq.
       6.1. При получении события: applyRemote(event), lastSeq = event.seq.
       6.2. При разрыве: вернуться к шагу 2.

Важно: шаг 3 (full resync) заменяет состояние, а не мержит. Все локальные данные, которых нет в снапшоте, удаляются. Pending-события при этом сохраняются и отправляются после resync (шаг 5).

5.3. Обработка локальных событий (пользователь пишет сообщение)

userSendsMessage(chatId, content):
  1. Создать DomainEvent(MessageAppended, {chatId, content, role: user, ...}).
  2. Сохранить в PendingEvent со status = pending.
  3. Применить событие к локальному состоянию (оптимистично), чтобы UI сразу показал сообщение.
  4. Запустить sync() в фоне.
  5. Когда сервер подтвердит — markPendingAsSent(localId, seq).
     Если сервер вернул ошибку — markPendingAsFailed(localId), откатить состояние.

5.4. Обработка локального ассистента

localAssistantRuns(chatId, input):
  1. Запустить Assistant.run(input), получить Flow<DomainEvent>.
  2. Для каждого события в потоке:
       2.1. Сохранить в PendingEvent со status = pending.
       2.2. Применить к локальному состоянию.
  3. Запустить sync() — события уйдут на сервер, получат seq, станут частью журнала.

Клиент не различает события от пользователя, от локального ассистента и от удалённого. Все они идут через PendingEvent → сервер → LoggedEvent.

---

6. Компакция журнала

6.1. Зачем

Журнал растёт бесконечно. Старые события уже «схлопнуты» в материализованное состояние. Их можно удалить.

6.2. Как

Периодический фоновый процесс на сервере:

1. Определить compaction_seq = минимальный курсор, который ещё нужен активным клиентам. Если неизвестно — использовать current_seq - safety_margin.
2. Удалить события WHERE seq <= compaction_seq.
3. Обновить CompactionState.min_available_seq = compaction_seq + 1.

6.3. Что делать клиенту с протухшим курсором

Если lastSeq < min_available_seq:

• Не пытаться догрузить апдейты (их нет).
• Сделать full resync: GET /sync/state → replaceState → продолжить live sync.

Это не ошибка, это штатный сценарий. Клиент просто получает актуальное состояние и продолжает жить.

6.4. Ключевое правило

Full resync = replace, не merge. Если клиент мержит, удалённые и отредактированные сущности останутся в старом виде. Если заменяет — всё консистентно.

---

7. Обработка редактирования и удаления

7.1. Редактирование

Событие MessageEdited несёт полный новый content сообщения.

• В журнал пишется событие с seq = S.
• В материализации строка обновляется на месте: content = newContent, last_seq = S.

Клиент на живом курсоре N < S:

• Получает событие MessageEdited из журнала.
• Применяет: обновляет content у себя, ставит last_seq = S.

Клиент на протухшем курсоре, resync на M > S:

• В снапшоте видит сообщение уже с новым content.
• Событие S не приходит (оно ≤ M).
• Всё консистентно.

7.2. Удаление

Событие MessageDeleted. В материализации строка либо физически удаляется, либо помечается deleted = true с last_seq = S.

Рекомендуется физическое удаление, потому что replace при resync всё равно уберёт строку. Tombstones нужны только если требуется показывать «сообщение удалено» в UI.

Клиент на живом курсоре N < S:

• Получает событие MessageDeleted.
• Удаляет строку у себя.

Клиент на протухшем курсоре, resync на M > S:

• В снапшоте строки нет.
• replace убирает её у клиента.
• Событие S не приходит.
• Всё консистентно.

---

8. Гарантии и краевые случаи

8.1. Идемпотентность

Каждое событие имеет eventId (UUID). Применение события с уже известным eventId — no-op. Это защищает от:

• повторной отправки PendingEvent;
• повторного применения события при реконнекте;
• дублирования в live sync.

8.2. Порядок событий

Клиент применяет события в порядке seq. Если пришло событие с seq > lastSeq + 1, значит есть пропуск — клиент должен догрузить пропущенные через GET /sync/updates?afterSeq=lastSeq.

8.3. Конфликты

Конфликты не разрешаются «в общем виде». Правила:

• Сообщения append-only (редактирование = новое событие, не мутация).
• Правки от разных устройств одного пользователя — сервер применяет в порядке поступления, последняя побеждает (last-write-wins по seq).
• Ветвления (regenerate) — через parent_id, а не через мутацию.

8.4. Офлайн-запись

Пользователь пишет офлайн → событие в PendingEvent → применяется локально → UI показывает. При появлении сети → sync → сервер назначает seq → markPendingAsSent.

Если сервер отверг событие (валидация не прошла) → markPendingAsFailed → клиент откатывает локальное изменение.

8.5. Мультиустройство

У каждого клиента есть device_id. События помечаются origin. При синке клиент не применяет свои же события повторно (идемпотентность по eventId решает это автоматически).

8.6. Большие снапшоты

GET /sync/state может вернуть много данных. Решения:

• Пагинация: GET /sync/state?upToSeq=N&chatId=X — по одному чату.
• Стриминг: HTTP chunked / gRPC streaming.
• Сжатие (gzip / zstd).

Для чата с ассистентом обычно достаточно per-chat снапшотов.

---

9. Что должен реализовать кодовый агент

9.1. Сервер

1. Хранилище журнала событий (EventLog): append-only, монотонный seq, компакция.
2. Хранилище материализованного состояния (StateStore): таблицы Chat, Message, поле last_seq.
3. Логика применения события (applyEvent): обновляет материализацию, ставит last_seq.
4. Атомарная операция append: в одной транзакции назначает seq, пишет в журнал, применяет к материализации.
5. HTTP API: /sync/state, /sync/updates, /sync/events.
6. WebSocket: /sync/live.
7. Фоновый компактор: периодически удаляет старые события, обновляет min_available_seq.
8. Идемпотентность: таблица processed_event_ids или проверка по eventId.

9.2. Клиент

1. Локальное хранилище состояния (StateStore): те же таблицы, что на сервере.
2. Локальное хранилище PendingEvent: очередь несинхронизированных событий.
3. Логика применения события (applyEvent): общая с сервером (один код).
4. Логика replaceState: полная замена локального состояния.
5. Sync-клиент: реализует алгоритм из раздела 5.2.
6. WebSocket-клиент: live sync.
7. UI: рисует исключительно из локального StateStore. Никогда не ждёт сеть.
8. Ассистенты: LocalAssistant и RemoteAssistant через общий интерфейс Assistant, возвращающий Flow<DomainEvent>.

9.3. Общее

1. Модель DomainEvent с самодостаточным payload.
2. Интерфейсы EventLog, StateStore, Assistant.
3. Логика сериализации/десериализации событий.
4. UUID-генерация для eventId.
5. Логика идемпотентности по eventId.

---

10. Чего делать НЕ надо

1. Не делать MVCC. Строки хранят только текущую версию. История — в журнале, но она компактится.
2. Не делать tombstones, если не нужно показывать «удалено». Физическое удаление + replace при resync решают всё.
3. Не мержить при full resync. Только replace.
4. Не запрашивать сервер для отрисовки. UI читает только локальную базу.
5. Не различать локального и удалённого ассистента на уровне клиента. Оба — Assistant, возвращающий Flow<DomainEvent>.
6. Не хранить счётчик в БД отдельно. seq — это либо sequence в БД, либо ULID в событии. Отдельный «счётчик» — лишняя сущность.
7. Не бояться, что «старый курсор протух». Это штатный сценарий: full resync.

---

11. Критерии готовности

1. Пользователь может писать офлайн, UI обновляется мгновенно.
2. При появлении сети события уходят на сервер, получают seq, синхронизируются.
3. Второй клиент видит изменения в реальном времени.
4. Локальный ассистент работает так же, как удалённый, с точки зрения клиента.
5. Компакция журнала не ломает синхронизацию: клиент с протухшим курсором делает full resync и продолжает.
6. Редактирование и удаление сообщений обрабатываются консистентно во всех сценариях.
7. Full resync заменяет состояние, не оставляя «фантомных» строк.
8. Идемпотентность: повторная отправка события не создаёт дублей.

---

12. Резюме идеи в одном абзаце

Есть журнал событий с монотонным курсором и материализованное состояние, где каждая строка помечена курсором последнего изменившего её события. Состояние на курсоре N — это строки с last_seq <= N. Апдейты после N — это события с seq > N. Клиент хранит локальную копию состояния и свой lastSeq. Для синхронизации он либо догружает апдейты (если курсор жив), либо заменяет состояние целиком (если курсор протух из-за компакции). В обоих случаях результат консистентен: клиент видит актуальные данные, не видит «шума» про отредактированные/удалённые сущности, которые были до его курсора, и продолжает live sync с нового курсора. Локальный и удалённый ассистенты — просто генераторы событий, неотличимые для клиента.