docs: document hourly investment reads

domains/income/upcoming-events.md

@@ -40,10 +40,10 @@
 ## Период и список
 
 Без фильтра период начинается сегодня в UTC и заканчивается через 30 дней
-после начала, обе даты включены. Поля «С» и «По» позволяют изменить период:
-«Применить» сохраняет выбранные календарные даты в URL и запрашивает результат,
-«Сбросить» возвращает период по умолчанию. Обзор счёта сохраняет прогноз
-на текущую дату и следующие 30 дней.
+после начала, обе даты включены. `from` и `to` принимают только строгие даты
+`YYYY-MM-DD`; без `from` используется текущая дата UTC, без `to` — `from + 30`
+календарных дней. Поля «С» и «По» сохраняют выбранные календарные даты в URL,
+а «Сбросить» возвращает период по умолчанию.
 
 События упорядочены по календарной дате. У каждой строки видны тип,
 инструмент, дата и доступная сумма в исходной валюте. Список не имеет
@@ -52,10 +52,13 @@
 отсутствия всех будущих выплат. Инструмент без поддерживаемых данных
 не получает искусственную строку «нет данных».
 
-API принимает необязательные `from` и `to` в формате `YYYY-MM-DD` для
-отдельного и общего счёта. Без `from` используется сегодня в UTC,
-без `to` — 30 дней после начала. Неверный формат или несуществующая дата
-дают `400`; обратный период — `400 INVALID_EVENTS_PERIOD`.
+Сохранённый forecast сохраняет свой `calculatedAt` и исходное включительное
+окно. GET для отдельного счёта или `all` возвращает только пересечение этого
+окна и запрошенного UTC-периода, не меняя ни `calculatedAt`, ни исходное окно.
+Пустое пересечение или отсутствие событий в пересечении — успешный пустой
+список с теми же metadata; это не отсутствие forecast. Неверный формат или
+несуществующая дата дают `400`; обратный период — `400 INVALID_EVENTS_PERIOD`
+без замены периода и без запуска личной работы.
 Фильтрация на сервере предшествует сортировке и вычислению
 `incomeTotalsByCurrency`, включающего только купоны и дивиденды.
 Итоги остаются в ответе API; полный экран показывает список без общего итога.
@@ -63,26 +66,30 @@ API принимает необязательные `from` и `to` в форма
 ## Получение и отказы
 
 Запрос требует сессии, подключения и локально подтверждённого membership.
-Прогноз строится из личного сохранённого portfolio и общих календарей: T-Bank для
-дивидендов, MOEX для bond events. Отдельного синхронного получения portfolio
-нет. Личные оценки сохраняются отдельно от общих календарей.
+Он читает сохранённый forecast и не запускает личную синхронизацию. Часовой
+обход строит forecast из полного личного portfolio и общих календарей: T-Bank
+для дивидендов, MOEX для bond events. Личные оценки сохраняются отдельно от
+общих календарей.
 
-Последний полный forecast привязан к scope, периоду и membership.
-Если новый portfolio требует ещё недоступного календаря, прежний полный
-прогноз и его source times остаются, в том числе после рестарта. Новый
-полный результат заменяет его атомарно. Без fallback показывается
-missing/partial, а не подтверждённое отсутствие выплат. Другой период или
-изменившийся membership не получают старый прогноз под новым названием.
-Source failure сообщается в metadata и не изменяет успешное время.
+Последний полный forecast привязан к scope, исходному окну и membership. Если
+часовой обход не может получить полный новый forecast, прежний полный прогноз,
+его `calculatedAt` и исходное окно остаются читаемыми, в том числе после
+рестарта; `meta.lastAttempt` отдельно сообщает об ошибке обновления. Без
+полного forecast `data: null` и metadata обозначает initial loading либо
+временную недоступность, а не подтверждённое отсутствие выплат. В режиме `all`
+результат complete только при полном вкладе каждого включённого счёта. Другой
+scope или изменившийся membership не получают старый forecast под новым
+названием.
 Успешный ответ MOEX без запрошенного блока означает отсутствие поддерживаемых
 событий этого источника; это отличается от transport failure и повреждённого
 формата ответа.
 
-При первом открытии показан каркас заголовка и строк, без интерактивных
-заглушек. Пустой ответ сохраняет возможность изменить период.
-При обычном фоновом обновлении уже полученные данные остаются на экране,
-ошибка получает предупреждение и повторную попытку. Без выбранного счёта
-запрос не выполняется. Смена сессии и подключения следует
+При первом открытии без complete forecast показан каркас заголовка и строк,
+без интерактивных заглушек. Пустой успешный ответ сохраняет возможность
+изменить период. При failed HTTP reread уже полученный Client Cached Snapshot
+остаётся на экране; это отличается от server-side failed hourly attempt.
+Повторная попытка перечитывает только HTTP-ответ. Без выбранного счёта запрос
+не выполняется. Смена сессии и подключения следует
 [общим правилам финансовых данных](../../architecture/cross-cutting/data-freshness.md).
 
 Внешние границы объясняют интеграции [T-Bank](../../integrations/tbank.md)