funora 0.0.1.dev2__py3-none-any.whl

funora/_diff.py

@@ -0,0 +1,752 @@
+"""Порождение событий из двух снимков состояния.
+
+Модуль чистый: два снимка на входе, события на выходе. Ни сети, ни часов, ни
+состояния между вызовами. Это не про стиль - без такого разделения проверить
+поведение на неполном снимке было бы нечем, а именно там оно и опаснее всего.
+
+Три правила объясняют почти весь код, и все три про то, чего модуль **не**
+делает.
+
+Сравнение идёт не со вторым снимком, а с курсором - набором того, что уже
+известно. Разница не в оформлении. Сравнение снимка со снимком давало ложное
+событие: строка, выпавшая из прошлого чтения из-за поломки разметки, при
+следующем чтении выглядела новым заказом, и бот выдавал товар по заказу, который
+существовал и раньше. Курсор хранит известное и не теряет его от одной
+испорченной строки.
+
+Пустой курсор событий не порождает. Не с чем сравнивать, и объявить все
+двенадцать существующих заказов новыми означало бы разослать двенадцать
+уведомлений об оплате при первом же запуске бота.
+
+Событий об исчезновении не порождается вовсе. Запись, не попавшая в частично
+прочитанную страницу, не исчезла - её не прочитали, и отличить одно от другого
+по странице нечем. Разница между этими случаями есть разница между «заказ
+отменён» и «мы не смогли его увидеть», а обработчик по первому вернёт деньги.
+
+События об изменении состояния порождаются только когда обе стороны сравнения
+прочитаны. Переход из непрочитанного состояния в прочитанное событием не
+считается: он говорит о том, что мы научились читать, а не о том, что заказ
+изменился. Обработчик, получивший такое событие, выдал бы товар по заказу, с
+которым ничего не происходило.
+"""
+
+from __future__ import annotations
+
+import hashlib
+from collections.abc import Callable, Iterable
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Any, Final
+
+from ._canonical import canonical_normalize
+from ._chats import ChatsPage
+from ._observed import Observed
+from ._orders import OrdersPage
+from ._thread import Message, Thread
+from .errors import ConfigurationError, ValidationError
+from .events import (
+    FINGERPRINT_DIGEST_BYTES,
+    FINGERPRINT_FIELDS,
+    FINGERPRINT_HASH,
+    FINGERPRINT_LENGTH,
+    FINGERPRINT_SEPARATOR,
+    ORDERING_KEY,
+    REVISION_APPEARED,
+    REVISION_SEPARATOR,
+    EventType,
+)
+
+__all__ = [
+    "Delivery",
+    "make_event",
+    "UNREAD_STATUS",
+    "UNKNOWN_UNREAD",
+    "Event",
+    "diff_orders",
+    "diff_chats",
+    "diff_thread",
+    "orders_cursor",
+    "chats_cursor",
+    "thread_cursor",
+]
+
+#: Как имя алгоритма из спецификации превращается в готовый хэшер.
+#:
+#: Таблица, а не hashlib.new: длину хэша blake2 задают аргументом конструктора,
+#: и через new её не передать. Таблица заодно делает громким тот случай, ради
+#: которого всё и затевалось - спецификация назвала алгоритм, которого
+#: реализация не умеет. Молча взять другой значило бы разойтись отпечатками с
+#: остальными SDK, а отпечаток - это ключ идемпотентности.
+_HASHERS: Final[dict[str, Callable[[], Any]]] = {
+    "blake2s": lambda: hashlib.blake2s(digest_size=FINGERPRINT_DIGEST_BYTES),
+    "blake2b": lambda: hashlib.blake2b(digest_size=FINGERPRINT_DIGEST_BYTES),
+}
+
+
+#: Происхождение события: выведено из разметки, а не из текста.
+_STRUCTURAL: Final[str] = "structural"
+
+
+@dataclass(frozen=True, slots=True)
+class Delivery:
+    """Метаданные доставки события.
+
+    Доставка объявлена как минимум однократной: событие, на котором обработчик
+    упал, приходит снова. Без этих полей обработчик не отличает вторую доставку
+    от нового события - а это ровно тот случай, ради которого гарантию и
+    формулируют: выдать товар дважды дешевле не становится оттого, что второй
+    раз был повтором.
+
+    Attributes:
+        attempt (int): Номер попытки доставки, с единицы. Больше единицы
+            означает повтор после отказа обработчика.
+        coalesced (bool): Собрано ли событие сжатием нескольких наблюдений.
+            Эта реализация не сжимает: опрос читает состояние целиком, и
+            промежуточные состояния между чтениями не наблюдаются вовсе, так
+            что сжимать нечего. Поле всегда False и стоит здесь потому, что
+            получателю нужен ответ, а не отсутствие поля.
+    """
+
+    attempt: int = 1
+    coalesced: bool = False
+
+
+@dataclass(frozen=True, slots=True)
+class Event:
+    """Событие в конверте, описанном спецификацией.
+
+    Attributes:
+        id (str): Идентификатор события. Отпечаток от полей, перечисленных в
+            спецификации; момента наблюдения и версии адаптера среди них нет.
+        type (EventType): Тип события.
+        account_id (str): Аккаунт, в контексте которого наблюдено событие.
+            Обязателен по конверту: получатель, разбирающий события нескольких
+            аккаунтов из одной очереди, иначе не различит их - а отпечаток,
+            куда аккаунт входит, непрозрачен и разбору не подлежит.
+        ordering_key (str): Ключ упорядочивания. Порядок сохраняется внутри
+            одного ключа, между разными ключами порядка нет.
+        entity_id (str): Идентификатор сущности, к которой относится событие.
+        observed_at (datetime): Момент наблюдения. В отпечаток не входит.
+        origin (str): Как получено: структурно либо по тексту.
+        delivery (Delivery): Метаданные доставки. По ним обработчик отличает
+            повтор от нового события.
+        payload (dict[str, Any]): Полезная нагрузка. Персональных данных в ней
+            нет: содержимое сообщений и имена сюда не кладутся.
+    """
+
+    id: str
+    type: EventType
+    account_id: str
+    ordering_key: str
+    entity_id: str
+    observed_at: datetime
+    origin: str
+    payload: dict[str, Any]
+    delivery: Delivery = Delivery()
+
+
+def _fingerprint(*, account_id: str, event_type: EventType, entity_id: str, revision: str) -> str:
+    """Строит устойчивый идентификатор события.
+
+    В отпечаток не входят ни момент наблюдения, ни версия адаптера, и это
+    запрет из спецификации, а не выбор реализации. Момент меняется от запуска к
+    запуску, версия - при каждом исправлении разметки; включение любого из них
+    обнулило бы дедупликацию ровно после перезапуска, то есть там, где она
+    нужнее всего.
+
+    Args:
+        account_id (str): Идентификатор аккаунта.
+        event_type (EventType): Тип события.
+        entity_id (str): Идентификатор сущности.
+        revision (str): Версия сущности - то, что отличает одно её состояние от
+            другого.
+
+    Returns:
+        str: Отпечаток в шестнадцатеричном виде.
+    """
+    parts = {
+        "account_id": account_id,
+        "type": str(event_type),
+        "entity_id": entity_id,
+        "entity_revision": revision,
+    }
+    # NFC до склейки. Одна и та же буква записывается по-разному: «ё» бывает
+    # одним знаком и парой «е» с диакритикой. Глазами не отличить, байтами -
+    # разные строки, и отпечаток от них разный. Форму задаёт не площадка, а
+    # то, через какой стек HTTP и какой разборщик разметки прошла страница, -
+    # то есть у двух реализаций она может отличаться на одних и тех же данных.
+    # Отпечаток при этом обязан совпасть: он ключ идемпотентности.
+    pieces = [canonical_normalize(parts[name]) for name in FINGERPRINT_FIELDS]
+
+    # Разделитель внутри части ломает склейку. Спецификация выбрала U+001F
+    # именно потому, что «любой печатный разделитель рано или поздно
+    # встретится внутри части, и две разные четвёрки склеятся в одну строку» -
+    # но не запретила его в самих частях, и запрета не хватило: реализация
+    # собирала версию диалога тем же знаком и клала пять частей туда, где
+    # объявлено четыре.
+    #
+    # Отвергать вслух, а не подменять. Подмена дала бы два разных события с
+    # одним отпечатком, и второе исчезло бы молча.
+    for name, piece in zip(FINGERPRINT_FIELDS, pieces, strict=True):
+        if FINGERPRINT_SEPARATOR in piece:
+            raise ValidationError(
+                f"часть отпечатка {name} содержит разделитель U+001F: {piece!r}. "
+                "Склейка перестала бы различать четвёрки полей, и два разных "
+                "события получили бы один отпечаток - молча"
+            )
+
+    material = FINGERPRINT_SEPARATOR.join(pieces)
+    # Алгоритм, длина хэша и длина отпечатка берутся из порождённого файла, а
+    # не пишутся здесь. Отпечаток - это ключ идемпотентности, и он обязан
+    # совпасть у шести реализаций; литерал в коде разошёлся бы со
+    # спецификацией молча, а разойдясь, обнулил бы гашение повторов у всех,
+    # кто подключил две реализации сразу.
+    make_digest = _HASHERS.get(FINGERPRINT_HASH)
+    if make_digest is None:
+        raise ConfigurationError(
+            f"спецификация требует отпечаток алгоритмом {FINGERPRINT_HASH}, "
+            f"а эта реализация умеет {sorted(_HASHERS)}. Взять другой значило бы "
+            "разойтись идентификаторами событий с остальными SDK"
+        )
+    digest = make_digest()
+    digest.update(material.encode("utf-8"))
+    fingerprint: str = digest.hexdigest()[:FINGERPRINT_LENGTH]
+    return fingerprint
+
+
+def make_event(
+    *,
+    account_id: str,
+    event_type: EventType,
+    entity_id: str,
+    revision: str,
+    observed_at: datetime,
+    key_field: str,
+    payload: dict[str, Any],
+    key_value: str | None = None,
+) -> Event:
+    """Собирает событие с отпечатком и ключом упорядочивания из спецификации.
+
+    Через эту функцию проходят ВСЕ события пакета, включая события о самом
+    наблюдении. Прежде их было два рода: события данных строились здесь, а
+    watch.primed и snapshot.incomplete собирали идентификатор вручную строкой
+    вида «primed:{account_id}:{ordering_key}» и подставляли ключ
+    упорядочивания «account:...» мимо порождённой таблицы.
+
+    Стоило это трёх нарушений разом. Ключ упорядочивания расходился с
+    нормативным «watch:{watch_id}» - то есть второй SDK делил бы поток на
+    другие группы. Идентификатор строился не из полей, перечисленных
+    спецификацией, и у одного из двух не было версии сущности вовсе. И
+    сосуществовали два формата идентификатора: отпечаток в шестнадцатеричном
+    виде и человекочитаемая строка с двоеточиями.
+
+    Args:
+        account_id (str): Идентификатор аккаунта.
+        event_type (EventType): Тип события.
+        entity_id (str): Идентификатор сущности.
+        revision (str): Версия сущности для отпечатка.
+        observed_at (datetime): Момент наблюдения.
+        key_field (str): Имя подстановки в шаблоне ключа упорядочивания.
+        payload (dict[str, Any]): Полезная нагрузка.
+
+    Returns:
+        Event: Готовое событие.
+    """
+    return Event(
+        id=_fingerprint(
+            account_id=account_id,
+            event_type=event_type,
+            entity_id=entity_id,
+            revision=revision,
+        ),
+        type=event_type,
+        ordering_key=ORDERING_KEY[event_type].format(
+            **{key_field: entity_id if key_value is None else key_value}
+        ),
+        entity_id=entity_id,
+        observed_at=observed_at,
+        origin=_STRUCTURAL,
+        account_id=account_id,
+        payload=payload,
+    )
+
+
+#: Чем отмечается заказ, состояние которого прочитать не удалось.
+#:
+#: Метка нужна затем, чтобы отличить «состояние было другим» от «состояния мы не
+#: знали». Событие об изменении порождается только когда обе стороны прочитаны:
+#: переход из непрочитанного в прочитанное - это про нас, а не про заказ.
+UNREAD_STATUS: Final[str] = "?"
+
+
+def diff_orders(
+    known: dict[str, str] | None,
+    page: OrdersPage,
+    *,
+    account_id: str,
+) -> tuple[Event, ...]:
+    """Порождает события по списку заказов и курсору.
+
+    Событий два вида. Заказ, которого нет в курсоре, - новый. Заказ, состояние
+    которого прочитано сейчас, прочитано было и отличается, - изменившийся.
+
+    Второе условие строгое намеренно. Переход из непрочитанного состояния в
+    прочитанное событием не считается: он говорит о том, что мы научились
+    читать, а не о том, что заказ изменился. Обработчик, получивший такое
+    событие, выдал бы товар по заказу, с которым ничего не происходило.
+
+    Args:
+        known (dict[str, str] | None): Известные заказы и их состояния. None при
+            первом запуске, когда курсора ещё нет.
+        page (OrdersPage): Прочитанная страница. Может быть неполной: заказ,
+            которого нет в курсоре, новый независимо от полноты чтения.
+        account_id (str): Идентификатор аккаунта.
+
+    Returns:
+        tuple[Event, ...]: События. Пустой набор при отсутствии курсора:
+        сравнивать не с чем, а объявить все существующие заказы новыми означало
+        бы разослать уведомления обо всех сразу при первом запуске.
+    """
+    if known is None:
+        return ()
+
+    events: list[Event] = []
+    for entry in page.rows(accept_incomplete=True):
+        now = entry.status.value if entry.status.is_observed else UNREAD_STATUS
+
+        if entry.order_id not in known:
+            events.append(
+                make_event(
+                    account_id=account_id,
+                    event_type=EventType.ORDER_CREATED,
+                    entity_id=entry.order_id,
+                    # Версией служит сам факт появления: заказ появляется в
+                    # списке однажды, и различать разные появления одного и того
+                    # же заказа не требуется. Значение берётся из порождённого
+                    # файла: отпечаток обязан совпасть у всех реализаций, а
+                    # литерал здесь разошёлся бы со спецификацией молча.
+                    revision=REVISION_APPEARED,
+                    observed_at=page.observed_at,
+                    key_field="order_id",
+                    payload={
+                        # Идентификатор лежит и в нагрузке, и в конверте. Нагрузку
+                        # принято передавать дальше отдельно от конверта - в
+                        # очередь, в журнал, - и там она обязана оставаться
+                        # самодостаточной.
+                        "order_id": entry.order_id,
+                        "href": entry.href,
+                        "row_index": entry.row_index,
+                        # В нагрузке отсутствие значения - None, а не метка "?".
+                        # Метка живёт в курсоре, где нужна строка, и наружу ей
+                        # выходить незачем: получатель, увидевший "?", решил бы,
+                        # что это состояние заказа. Отсутствие типизируется само.
+                        "status": entry.status.or_none(),
+                    },
+                )
+            )
+            continue
+
+        before = known[entry.order_id]
+        if before == now or UNREAD_STATUS in (before, now):
+            continue
+
+        events.append(
+            make_event(
+                account_id=account_id,
+                event_type=EventType.ORDER_STATUS_CHANGED,
+                entity_id=entry.order_id,
+                # Версия - новое состояние. Повторное чтение того же состояния
+                # даёт тот же отпечаток, и гашение повторов срабатывает само.
+                revision=now,
+                observed_at=page.observed_at,
+                key_field="order_id",
+                payload={
+                    "order_id": entry.order_id,
+                    "href": entry.href,
+                    # previous и current, а не from и to: валидатор спецификации
+                    # сам предупредил, что from - ключевое слово в Python и
+                    # порождённый код получил бы from_. Ключ нагрузки читают
+                    # шесть языков, и имя, которое в одном из них приходится
+                    # экранировать, плохое имя.
+                    "previous": before,
+                    "current": now,
+                },
+            )
+        )
+
+    return tuple(events)
+
+
+def orders_cursor(page: OrdersPage) -> dict[str, str]:
+    """Собирает курсор по прочитанной странице заказов.
+
+    Курсор снимается только с полного чтения, и решает это вызывающий. Снятый с
+    неполного, он потерял бы выпавшие строки - и при следующем чтении они
+    выглядели бы новыми заказами.
+
+    Хранится не множество идентификаторов, а соответствие «заказ - состояние».
+    Множества хватало ровно до тех пор, пока состояние было ненаблюдаемым:
+    сравнивать было нечего, и событие об изменении породить было не из чего.
+
+    Args:
+        page (OrdersPage): Прочитанная страница.
+
+    Returns:
+        dict[str, str]: Идентификаторы заказов и их состояния. Непрочитанное
+        состояние отмечается UNREAD_STATUS.
+    """
+    return {
+        entry.order_id: (entry.status.value if entry.status.is_observed else UNREAD_STATUS)
+        for entry in page.rows(accept_incomplete=True)
+    }
+
+
+#: Разделитель между позицией и флагом в составе версии диалога.
+#:
+#: Не двоеточие и не любой печатный знак: позиция непрозрачна, и в снимках она
+#: сама содержит двоеточие - подпись вида T10:d#1. Разделитель, встречающийся
+#: внутри значения, разрезал бы состояние не там, и сравнение сравнивало бы
+#: обрубки.
+#:
+#: И НЕ U+001F, которым склеивается отпечаток. Это была настоящая ошибка, а не
+#: придирка. Спецификация выбрала U+001F для отпечатка ровно потому, что
+#: печатный разделитель рано или поздно встретится внутри части - и тогда две
+#: разные четвёрки склеятся в одну строку, а два разных события получат один
+#: отпечаток. Реализация взяла тот же знак для вложенной склейки и своими
+#: руками положила его внутрь части: материал отпечатка получал пять кусков
+#: там, где объявлено четыре.
+#:
+#: Следствие важнее самой коллизии. Спецификация НЕ называла этот разделитель
+#: вовсе - только «знак, который не встречается внутри значений». Вторая
+#: реализация взяла бы двоеточие или вертикальную черту и получила бы другой
+#: отпечаток на каждое событие chat.unread_changed. Теперь знак назван
+#: нормативно: spec/events/delivery.yaml -> revision_source.part_separator.
+#:
+#: U+001E - разделитель записей, U+001F - разделитель полей внутри записи.
+#: Порядок обратен привычному по ASCII: внешняя склейка была зафиксирована
+#: спецификацией первой, и менять её значило бы обнулить все сохранённые
+#: отпечатки ради красоты.
+#: Величина берётся из порождённого файла, а не пишется здесь: она входит
+#: в отпечаток и обязана совпасть у всех реализаций.
+_STATE_SEP: Final[str] = REVISION_SEPARATOR
+
+#: Чем отмечается диалог, признак непрочитанного которого не выведен.
+#:
+#: Метка нужна затем же, зачем UNREAD_STATUS у заказов: отличить «было иначе» от
+#: «мы не знали». Переход из неизвестного в известное событием не считается - он
+#: про нас, а не про диалог.
+UNKNOWN_UNREAD: Final[str] = "?"
+
+
+def _chat_state(position: str, unread: Observed[bool]) -> str:
+    """Собирает состояние диалога, по которому решается, было ли изменение.
+
+    Состояний два, и позиции одной мало. Событие называется «изменилось
+    непрочитанное», а сравнивалась только позиция последнего сообщения - то
+    есть прочтение диалога события не давало вовсе. Признак прочтения живёт в
+    другой позиции, и её никто не смотрел.
+
+    Отпечаток строится из этой же строки, и это вторая половина той же починки.
+    Сравнивай мы флаг, но оставь версией одну позицию - событие о прочтении
+    получило бы отпечаток уже доставленного и было бы съедено гашением повторов.
+    Снова молча.
+
+    Args:
+        position (str): Позиция последнего сообщения диалога.
+        unread (Observed[bool]): Выведенный признак непрочитанного.
+
+    Returns:
+        str: Состояние - позиция и флаг через разделитель. Флаг: 1, 0 либо знак
+        неизвестного.
+    """
+    flag = UNKNOWN_UNREAD if not unread.is_observed else ("1" if unread.value else "0")
+    return f"{position}{_STATE_SEP}{flag}"
+
+
+def _split_state(state: str) -> tuple[str, str]:
+    """Разбирает состояние диалога на позицию и флаг.
+
+    Разбирает и прежнюю форму - голую позицию без флага. Курсор переживает
+    перезапуск, и сохранённый прежней редакцией читается как «позиция известна,
+    флаг нет»: иначе первое же чтение после обновления выдало бы по событию на
+    каждый диалог.
+
+    Args:
+        state (str): Сохранённое состояние.
+
+    Returns:
+        tuple[str, str]: Позиция и флаг.
+    """
+    position, _, flag = state.partition(_STATE_SEP)
+    return position, (flag or UNKNOWN_UNREAD)
+
+
+def _changed(stored: str, state: str) -> bool:
+    """Решает, переменился ли диалог.
+
+    Args:
+        stored (str): Состояние из курсора.
+        state (str): Состояние из свежего чтения.
+
+    Returns:
+        bool: True, если сдвинулась позиция либо переменился выведенный признак
+        непрочитанного. Переход признака из невыведенного в выведенный
+        изменением не считается.
+    """
+    was_position, was_flag = _split_state(stored)
+    now_position, now_flag = _split_state(state)
+
+    if was_position != now_position:
+        return True
+    if UNKNOWN_UNREAD in (was_flag, now_flag):
+        return False
+    return was_flag != now_flag
+
+
+def diff_chats(
+    known: dict[str, str] | None,
+    page: ChatsPage,
+    *,
+    account_id: str,
+) -> tuple[Event, ...]:
+    """Порождает события по списку диалогов и курсору.
+
+    Событие даёт любое из двух изменений: сдвинулась позиция последнего
+    сообщения либо переменился выведенный признак непрочитанного. Второе
+    добавлено потому, что событие называется «изменилось непрочитанное», а
+    замечало только первое - прочтение диалога не давало события вовсе.
+
+    Переход признака из невыведенного в выведенный событием не считается: он
+    говорит, что мы научились выводить, а не что диалог переменился. То же
+    правило, что у состояния заказа.
+
+    Args:
+        known (dict[str, str] | None): Состояние по каждому известному диалогу.
+            None при первом запуске. Прежняя форма - голая позиция - читается
+            как «флаг неизвестен».
+        page (ChatsPage): Прочитанная страница.
+        account_id (str): Идентификатор аккаунта.
+
+    Returns:
+        tuple[Event, ...]: События об изменении диалогов.
+    """
+    if known is None:
+        return ()
+
+    events: list[Event] = []
+    for entry in page.rows(accept_incomplete=True):
+        position = entry.last_message_position.or_none()
+        if position is None:
+            continue
+
+        state = _chat_state(position, entry.unread)
+        stored = known.get(entry.node_id)
+        if stored is not None and not _changed(stored, state):
+            continue
+
+        events.append(
+            make_event(
+                account_id=account_id,
+                event_type=EventType.CHAT_UNREAD_CHANGED,
+                entity_id=entry.node_id,
+                # Версия - позиция вместе с флагом. Позиция непрозрачна и при
+                # изменении диалога меняется; сравнивается она только на
+                # равенство, арифметика над ней запрещена спецификацией. Флаг
+                # добавлен к версии затем, чтобы событие о прочтении не получало
+                # отпечаток уже доставленного.
+                revision=state,
+                observed_at=page.observed_at,
+                key_field="chat_id",
+                payload={
+                    "chat_id": entry.node_id,
+                    "unread": entry.unread.or_none(),
+                    "unread_confidence": (
+                        str(entry.unread.confidence) if entry.unread.confidence else None
+                    ),
+                },
+            )
+        )
+
+    return tuple(events)
+
+
+def chats_cursor(page: ChatsPage) -> dict[str, str]:
+    """Собирает курсор по прочитанной странице диалогов.
+
+    Курсор снимается только с полного чтения, и решает это вызывающий - правило
+    то же, что у списка заказов, и записано здесь потому, что функция публичная.
+    Снятый с неполного, он потерял бы выпавшие диалоги, и при следующем чтении
+    каждый из них дал бы по ложному событию, которое гашение повторов не
+    поймает: отпечатка такого события в кэше никогда не было.
+
+    Хранится не позиция, а состояние: позиция вместе с выведенным признаком
+    непрочитанного. Одной позиции не хватало - прочтение диалога её не двигает,
+    и событие о прочтении не порождалось вовсе.
+
+    Внутри вызывается rows(accept_incomplete=True): неполнота здесь не ошибка, а
+    решение вызывающего, и глушить её исключением функция не вправе.
+
+    Args:
+        page (ChatsPage): Прочитанная страница.
+
+    Returns:
+        dict[str, str]: Состояние по каждому диалогу: позиция и признак
+        непрочитанного через разделитель.
+    """
+    cursor: dict[str, str] = {}
+    for entry in page.rows(accept_incomplete=True):
+        position = entry.last_message_position.or_none()
+        if position is None:
+            continue
+        cursor[entry.node_id] = _chat_state(position, entry.unread)
+    return cursor
+
+
+def direction_of(message: Message, own_href: str) -> str:
+    """Определяет, кто написал сообщение по отношению к владельцу сессии.
+
+    СТРУКТУРНО, сравнением адресов профилей, а не по имени. Имя меняется, и
+    совпадение имён подделывается собеседником, назвавшимся как продавец;
+    адрес профиля подделать нельзя, не заведя аккаунт с тем же номером.
+
+    Оба адреса нормализуются: площадка отдаёт их и с завершающей косой чертой,
+    и без неё, и сравнение как есть объявило бы разными один и тот же профиль.
+
+    Аргументы:
+        message (Message): Сообщение переписки.
+        own_href (str): Адрес собственного профиля. Пустая строка означает, что
+            снять его со страницы не удалось.
+
+    Возвращает:
+        str: inbound, outbound либо unknown.
+    """
+    if not own_href or not message.author_href.is_observed:
+        # Сравнивать нечего. Незнание объявляется значением, а не пустотой, - и
+        # греть переписку оно не вправе: тепло требует положительного
+        # свидетельства, а не отсутствия опровержения.
+        return "unknown"
+    if _normalized_href(message.author_href.value) == _normalized_href(own_href):
+        return "outbound"
+    return "inbound"
+
+
+def _normalized_href(href: str) -> str:
+    """Приводит адрес профиля к сравнимому виду.
+
+    Аргументы:
+        href (str): Адрес.
+
+    Возвращает:
+        str: Адрес без завершающей косой черты и краевых пробелов.
+    """
+    return href.strip().rstrip("/")
+
+
+def diff_thread(
+    known: frozenset[str] | None,
+    thread: Thread,
+    *,
+    account_id: str,
+    chat_id: str,
+    own_href: str = "",
+) -> tuple[Event, ...]:
+    """Порождает события по переписке и курсору.
+
+    Args:
+        known (frozenset[str] | None): Идентификаторы уже известных сообщений.
+            None при первом чтении переписки.
+        thread (Thread): Прочитанная переписка.
+        account_id (str): Идентификатор аккаунта.
+        chat_id (str): Идентификатор диалога.
+        own_href (str): Адрес собственного профиля, снятый с той же страницы.
+            Пустая строка означает, что снять не удалось, и тогда направление у
+            всех сообщений выходит unknown.
+
+            Умолчание пустое НАРОЧНО, а не для удобства: функция публичная, и
+            вызывающий, у которого адреса нет, обязан получить честное незнание,
+            а не молчаливое «это писал не я».
+
+    Returns:
+        tuple[Event, ...]: События о новых сообщениях.
+    """
+    if known is None:
+        return ()
+
+    events: list[Event] = []
+    for message in thread.messages(accept_incomplete=True):
+        if not message.message_id.is_observed:
+            continue
+        if message.message_id.value in known:
+            continue
+
+        events.append(
+            make_event(
+                account_id=account_id,
+                event_type=EventType.MESSAGE_CREATED,
+                entity_id=chat_id,
+                revision=message.message_id.value,
+                observed_at=thread.observed_at,
+                key_field="chat_id",
+                payload={
+                    "chat_id": chat_id,
+                    "message_id": message.message_id.value,
+                    # Происхождение кладётся в нагрузку намеренно: обработчик
+                    # обязан видеть его, не разбирая текст. Но даже origin равный
+                    # system не является подтверждением оплаты - об этом сказано
+                    # в spec/extraction/chats.yaml и в docstring разбора.
+                    "origin": str(message.origin),
+                    # Число, а не адреса: адреса пишет собеседник, и класть
+                    # чужой ввод в нагрузку события незачем. Ненаблюдённое поле
+                    # даёт None, а не ноль: ноль означал бы «ссылок не было».
+                    "external_links": (
+                        len(message.external_links.value)
+                        if message.external_links.is_observed
+                        else None
+                    ),
+                    # Направление. Без него получатель отвечает на собственный
+                    # ответ, а ограничитель исходящих считает холодной ту
+                    # переписку, где собеседник только что написал сам.
+                    "direction": direction_of(message, own_href),
+                },
+            )
+        )
+
+    return tuple(events)
+
+
+def thread_cursor(thread: Thread) -> frozenset[str]:
+    """Собирает курсор по прочитанной переписке.
+
+    В отличие от курсоров списков, этот снимается и с неполного чтения - так
+    делает цикл наблюдения, и вот почему. Сообщение, выпавшее из неполного
+    чтения и попавшее в следующее, действительно новое для получателя: событий о
+    нём никто не выдавал. Заказ в той же ситуации выглядел бы новым заказом, и
+    это было бы ложью о мире.
+
+    Обратное правило стоило дорого: пустой курсор молчит по правилу первого
+    чтения, а неполное первое чтение оставляло его пустым навсегда - диалог
+    замолкал совсем.
+
+    Args:
+        thread (Thread): Прочитанная переписка.
+
+    Returns:
+        frozenset[str]: Идентификаторы наблюдённых сообщений.
+    """
+    return frozenset(
+        message.message_id.value
+        for message in thread.messages(accept_incomplete=True)
+        if message.message_id.is_observed
+    )
+
+
+def ordering_keys(events: Iterable[Event]) -> set[str]:
+    """Собирает ключи упорядочивания набора событий.
+
+    Args:
+        events (Iterable[Event]): События.
+
+    Returns:
+        set[str]: Ключи. События с разными ключами обрабатываются параллельно.
+    """
+    return {event.ordering_key for event in events}