pyrogram-bridge/plans/cache-optimization-spec.md

# Спецификация: рефакторинг и оптимизация кешей pyrogram-bridge

Статус: **принята владельцем 2026-07-05. Адверсарное ревью — 4 раунда, возражений не осталось.**
История ревью — раздел 12. Реализация разбита на ишью в gitea (по PR-юнитам: A+B+F, C, D, E).

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

В проекте три слоя кеша:

1. **История сообщений и инфо о канале** — pickle-файлы в `data/tgcache/` (`tg_cache.py`).
2. **Медиафайлы** — файлы в `data/cache/<channel>/<post_id>/<file_unique_id>` + метаданные в SQLite `data/media_file_ids.db` (`api_server.py`, `file_io.py`).
3. **Runtime-структуры** — `_access_updates`, `_inflight`, `download_queue` в `api_server.py`.

Проблемы, которые закрывает спецификация (по результатам аудита):

| # | Проблема | Пакет |
|---|---|---|
| 1 | Pickle полных `Message` — формат привязан к версии pyrogram/kurigram, тихий дрейф схемы, opaque-формат | A |
| 2 | Строгое `cached_limit == limit` + разные limit у RSS (`limit*2`) и HTML (`limit`) → кеш истории фактически не работает | B |
| 3 | Один канал живёт под ключами разного регистра/формы записи (`Durov`/`durov`, `@name`/`name`) в трёх слоях → дубли кеша. Унификация ID↔username — сознательная НЕ-цель (см. раздел 8) | C |
| 4 | Два почти идентичных pickle-кеша в `tg_cache.py` (история/chatinfo) — дублирование кода | A |
| 5 | Legacy-мусор (`*_history.cache`, двойной pickle, `data/media_file_ids.json`); чистка `data/tgcache` вводится как стартовая + периодический age-sweep (мгновенной GC по событию не будет — файлы мёртвых каналов живут до 7 суток) | A, F |
| 6 | Свипер медиа-кеша: полный проход таблицы + `os.walk` каждые 60 с при политиках «20 дней»/«1 час» | D |
| 7 | Баг: чистка «мёртвых» строк SQLite выполняется только при `files_removed > 0` | D |
| 8 | Чтение MIME из SQLite (новое соединение + threadpool-hop) на каждом хите `/media` | E |
| 9 | Джиттер TTL перебрасывается на каждом чтении → недетерминированное поведение у границы TTL (усложняет рассуждения и тесты) | F |
| 10 | Очередь фоновых загрузок без дедупа — повторная постановка одного файла каждым проходом свипа | D |
| 11 | Путь медиа-кеша (`./data/cache` + join) собирается вручную в 7 местах | E |

## 1. Состав пакетов и порядок

| Пакет | Задания | Что | Зависимости | Файлы |
|---|---|---|---|---|
| **A** | 1–5 | Снапшот-словари вместо pickle + generic JSON-store + чистка legacy tgcache | — | `message_snapshot.py` (новый), `tg_cache.py`, `api_server.py` (1 строка), тесты |
| **B** | 6–7 | Префиксная выдача истории вместо строгого `limit` | после A | `tg_cache.py`, тесты |
| **C** | 8–11 | Единая канонизация ключа канала + one-shot миграция | **после A** (задание 9.1 канонизирует ключ внутри `_cache_file_path`, который создаётся заданием 2) | `channel_key.py` (новый), `tg_cache.py`, `post_parser.py`, `api_server.py` |
| **D** | 12–14 | Фиксы свипера медиа-кеша + дедуп очереди | независим | `api_server.py`, `config.py` |
| **E** | 15–16 | Хелпер путей медиа-кеша + in-memory MIME-кеш | независим | `api_server.py` |
| **F** | 17–18 | Джиттер TTL при записи + age-sweep tgcache + добить legacy | после A | `tg_cache.py`, `api_server.py` |

Рекомендуемая сборка: A → B → F одним PR (все правят `tg_cache.py`); C — отдельный PR (меняет генерацию URL и содержит миграцию); D и E — параллельно с любым.

---

## 2. Пакет A — кеш истории на извлечённых словарях

### 2.1. Принцип

Кеш истории перестаёт хранить pickle живых объектов pyrogram. При записи из `Message`
извлекается JSON-словарь по явному allowlist полей (снапшот); при чтении из него
восстанавливается лёгкий duck-typed объект `CachedMessage`, неотличимый для конвейера
рендеринга (`rss_generator.py`, `post_parser.py`) от настоящего `Message`.
**Конвейер не меняется вообще** — главный инвариант дизайна.

Выгоды: формат на диске отвязан от версии pyrogram/kurigram; версионирование схемы
(несовпадение → честный miss вместо тихого дрейфа); JSON читаем при отладке;
явный документированный контракт «от каких полей Message зависит рендер»
(сейчас он размазан по ~2000 строк); файл меньше и парсится быстрее полного графа объектов.
Отклонённая альтернатива — раздел 11.

### 2.2. Ключевые проектные решения

| # | Решение | Обоснование |
|---|---|---|
| Р1 | Новый модуль `message_snapshot.py`: `snapshot_message()` / `restore_message()` | Схема сериализации отделена от механики кеша; меняются независимо |
| Р2 | `text`/`caption` хранятся парой `{plain, html}`; `.html` вычисляется **при записи** через pyrogram `Str.html` | Конвертация entities→HTML требует машинерии pyrogram, доступной на живом объекте (`post_parser.py:674-675`). Проверено: `Str.html` работает офлайн, без клиента |
| Р3 | При восстановлении `text`/`caption` — `CachedStr(str)` с атрибутом `.html` | Потребители используют и строковые операции (`len`, `strip`, regex, `or`), и `.text.html`; str-подкласс покрывает всё. Это паттерн pyrogram `Str` |
| Р4 | `media` восстанавливается в настоящий `MessageMediaType[name]`; `KeyError` → `None` + warning | 31 место сравнивает с enum и использует его ключом dict (`post_parser.py:1004-1017`) |
| Р5 | `service` хранится и восстанавливается **строкой-именем** (`"PINNED_MESSAGE"`) | Все потребители — truthiness и `'X' in str(service)` (`rss_generator.py:112-121`, `post_parser.py:305`). Строка версионно-устойчива |
| Р6 | `date` — `isoformat()` туда, `fromisoformat()` обратно | Сохраняет naive/aware ровно как у pyrogram; `strftime`, `timestamp()`, сортировки работают |
| Р7 | Вложенные объекты восстанавливаются с **полным набором ключей схемы, None-дефолты** — «как живые». **Единственное исключение — `forward_origin`**: у него присутствие ключа зеркалит присутствие атрибута на исходном объекте | Живые pyrogram-объекты всегда имеют все атрибуты (ставятся в `__init__`, напр. `Reaction`: `emoji=None, custom_emoji_id=None, is_paid=None`) — код обращается к вложенным полям и напрямую (`rss_generator.py:131` — `message.chat.username` в except-хендлере; `post_parser.py:1087-1090` — `u.username`/`u.active` без getattr), omit-None дал бы там `AttributeError` → 500 на фид. А вот живые `MessageOrigin*`-классы имеют РАЗНЫЕ наборы атрибутов, и `_format_forward_info` ветвится по `hasattr` (Case 1–5, `post_parser.py:629-669`) — для forward_origin присутствие ключей семантично |
| Р8 | `CachedMessage` — мутабельный, полный набор top-level атрибутов с дефолтами `None`/`False` | `_reply_enrichment` присваивает `message.reply_to_message` (`rss_generator.py:574`); доступ к атрибутам не должен кидать `AttributeError`; `copy.deepcopy` (`rss_generator.py:43`) должен работать |
| Р9 | Файл: JSON `{"version", "timestamp", "limit", "messages"}`, имена `<key>.history.json` / `<key>.chatinfo.json`. Атомарная запись: **уникальный tmp `<path>.tmp.<uuid4().hex>`** → `os.replace`, в `finally` — удаление своего tmp (образец: `_download_atomic`, `api_server.py:460-479`) | Версия отсекает старые схемы; новые расширения игнорируют старые pickle; уникальный tmp исключает перемешивание байтов при конкурентных miss'ах одного канала (RSS+HTML параллельно пишут через `asyncio.to_thread`); rename чинит порчу при падении посреди записи |
| Р10 | TTL / джиттер / строгий `limit` в пакете A — **без изменений** | Behavior-neutral рефакторинг; limit меняет пакет B, джиттер — пакет F |
| Р11 | Миграции старых pickle нет: старые файлы = miss; стартовая чистка удаляет legacy | Кеш самовосстанавливается за ≤ TTL (история 8 ч; chatinfo 12 ч по умолчанию, настраивается `TG_CHAT_CACHE_TTL_HOURS`) |

### 2.3. Схема снапшота v1 (контракт)

Выведена из фактического потребления полей конвейером (инвентарь по `rss_generator.py`
и `post_parser.py`, включая `hasattr`-семантику и enum-сравнения) и сверена с типами
kurigram 2.2.23 (`.venv`).

```jsonc
{
  "id": 123,                          // message.id
  "date": "2026-07-05T12:00:00",      // isoformat or null
  "text":    {"plain": "...", "html": "..."},   // null if absent
  "caption": {"plain": "...", "html": "..."},   // null if absent
  "media": "PHOTO",                   // MessageMediaType.name or null
  "service": "PINNED_MESSAGE",        // MessageServiceType.name or null
  "media_group_id": 456,              // or null
  "views": 789,                       // or null
  "show_caption_above_media": false,
  "reply_to_message_id": 42,          // needed by _reply_enrichment
  "empty": false,
  "chat": {"id": -100123, "username": "durov", "title": "...",
           "usernames": [{"username": "x", "active": true}]},
  "sender_chat": {"id": 1, "title": "...", "username": "..."},
  "from_user": {"first_name": "...", "last_name": "...", "username": "..."},
  "forward_origin": {                 // ONLY keys present on the live object (hasattr semantics!)
      "type": "channel",
      "chat": {"id": 1, "title": "...", "username": "..."},
      "sender_user_name": "...",
      "sender_user": {"first_name": "...", "last_name": "...", "username": "..."},
      "chat_id": 1, "title": "..."
  },
  "reactions": [                      // from message.reactions.reactions; null if none
      {"emoji": "👍", "count": 5, "is_paid": null, "custom_emoji_id": null},
      // custom-emoji reaction: emoji is null, custom_emoji_id is a STRING (kurigram
      // builds it as str(document_id)) — restored with the FULL key set, like live objects
      // (live kurigram sets is_paid=None unless it is a paid reaction):
      {"emoji": null, "count": 2, "is_paid": null, "custom_emoji_id": "987..."}
  ],
  "poll": {"question": "...",         // plain string — FormattedText unwrapped at snapshot time
           "options": [{"text": "..."}]},   // text unwrapped to plain string; see 2.4.1
  "web_page": {"type": "...", "url": "...", "display_url": "...", "site_name": "...",
               "title": "...", "description": "...", "has_large_media": false,
               "photo": {"file_unique_id": "..."}},
  // media payloads — per-type allowlist:
  "photo":      {"file_unique_id": "..."},
  "video":      {"file_unique_id": "...", "file_size": 123},   // file_size: large-video rule
  "document":   {"file_unique_id": "...", "mime_type": "..."},  // mime_type: PDF branch
  "audio":      {"file_unique_id": "...", "mime_type": "..."},
  "voice":      {"file_unique_id": "...", "mime_type": "..."},
  "video_note": {"file_unique_id": "..."},
  "animation":  {"file_unique_id": "..."},
  "sticker":    {"file_unique_id": "...", "emoji": "...", "is_video": false}
}
```

### 2.4. Критические тонкости (обязательны к учёту)

1. **`poll.question` и КАЖДЫЙ `poll.options[].text` в kurigram 2.2.23 — всегда объекты
   `FormattedText`** (проверено: `poll.py:105,220`, `poll_option.py:72,84` в `.venv`), не строки.
   Снапшот обязан разворачивать оба в plain-строку правилом
   `v.text if hasattr(v, 'text') else str(v)` (правило корректно и для `Str`, и для голой
   строки). Если положить `FormattedText` в словарь как есть — `json.dump` кинет `TypeError`,
   `_save_history_to_cache` проглотит её, и **кеш молча перестанет сохраняться для любого
   канала с опросом в выборке**. Восстановление: `question` → str,
   `options` → namespace с `.text` (голая строка в options дала бы
   `getattr(option, 'text', '') == ''` → пустые опции, `post_parser.py:992`).
2. **Реакции восстанавливаются с полным набором ключей** (`emoji`, `custom_emoji_id`,
   `count`, `is_paid`; отсутствующие значения — `None`) — ровно как живой `Reaction`,
   у которого `__init__` всегда ставит все атрибуты. Ветвление в
   `post_parser.py:399-410` и `:928-934` на живых объектах работает через truthiness,
   а не через отсутствие атрибута — восстановленный объект обязан вести себя так же.
   `custom_emoji_id` — **строка** (kurigram: `str(reaction.document_id)`).
3. **`forward_origin`** — единственный объект с presence-семантикой: Case 4 различается по
   `hasattr(forward_origin, "chat_id") and hasattr(..., "title")`; при снапшоте пишутся
   только реально присутствующие (non-None) поля-кандидаты, при восстановлении — только
   записанные ключи.
4. **`video.file_size` обязателен** — правило «не кешировать видео >100 МБ» в
   `_save_media_file_ids` (`post_parser.py:1058`).
5. **`chat.usernames`** — список объектов с `.username`/`.active`
   (`post_parser.py:1087-1090`, прямой доступ без getattr — оба ключа всегда присутствуют).
6. **`CachedMessage.__str__`** — читаемый JSON-дамп: попадает в error-логи
   (`post_parser.py:980`).

### 2.5. Задание 1 — новый модуль `message_snapshot.py`

```python
SNAPSHOT_VERSION = 1

class CachedStr(str):
    """str subclass carrying a precomputed .html rendering, mirroring pyrogram's Str.
    deepcopy/pickle preserve the instance __dict__, so .html survives copying."""
    # factory: CachedStr.build(plain, html)

class CachedMessage:
    """Duck-typed stand-in for pyrogram Message, restored from a snapshot dict.
    Mutable (reply enrichment assigns .reply_to_message). All pipeline-consumed
    top-level attributes exist with None/False defaults, so getattr never raises."""
    # __str__/__repr__: json.dumps of the snapshot dict, default=str

def snapshot_message(message) -> dict: ...
def restore_message(data: dict) -> CachedMessage: ...
def snapshot_messages(messages) -> list[dict]: ...
def restore_messages(items: list[dict]) -> list[CachedMessage]: ...
```

Требования:
- `snapshot_message` извлекает строго по схеме 2.3; каждое поле через `getattr(..., None)`.
- Styled-text (`FormattedText`/`Str`/str) разворачивается правилом
  `v.text if hasattr(v, 'text') else str(v)` — применяется к `poll.question` и каждому
  `poll.options[].text` (см. 2.4.1).
- `text`/`caption`: `{"plain": str(value), "html": value.html}`; если `.html` недоступен —
  `html = plain`.
- `media`: `message.media.name`; `service`: `message.service.name`
  (оба через безопасный `getattr(x, 'name', str(x))`).
- Восстановление: помощник `_ns(d: dict, keys: tuple) -> SimpleNamespace` — ставит ВСЕ
  перечисленные ключи схемы (None-дефолт для отсутствующих); для `forward_origin` — режим
  «только записанные ключи». Спец-обработка: `text/caption → CachedStr`,
  `media → MessageMediaType[name]` (при `KeyError` — warning + `None`),
  `date → datetime.fromisoformat`, `reactions → SimpleNamespace(reactions=[...])`
  (обёртка-контейнер, как у pyrogram).
- Дефолты `CachedMessage`: `id, date, text, caption, media, service, media_group_id, views,
  show_caption_above_media, reply_to_message_id, reply_to_message=None, empty=False, chat,
  sender_chat, from_user, forward_origin, reactions, poll, web_page, photo, video, document,
  audio, voice, video_note, animation, sticker`.
- Комментарии в коде — только английские.

### 2.6. Задание 2 — переписать `tg_cache.py` на generic JSON-store

1. Убрать `import pickle` полностью. Удалить ветку double-pickle (`tg_cache.py:111-116`).
2. Generic-пара (заменяет обе дублирующиеся тройки функций):

```python
def _store_entry(path: str, payload: dict) -> None:
    """Atomically write {'version', 'timestamp', **payload} as JSON.
    Writes to a unique '<path>.tmp.<uuid4hex>' and os.replace()s it into place;
    the finally block always removes this writer's own tmp file."""

def _load_entry(path: str, max_age_hours: float) -> Optional[dict]:
    """Return payload dict, or None on: missing file, version mismatch,
    expired TTL (keep the existing up-to-20% read-time jitter as-is in package A;
    package F moves it to write time), JSON error."""
```

3. Пути: `<safe_key>.history.json` и `<safe_key>.chatinfo.json`
   (общий помощник `_cache_file_path(key, suffix)` вместо двух копий).
4. `_save_history_to_cache`: `payload = {'limit': limit, 'messages': snapshot_messages(messages)}`.
   `_get_history_from_cache`: проверка `limit` как сейчас (пакет A не меняет), возврат
   `restore_messages(...)`.
5. `_save_chat_to_cache` / `_get_chat_from_cache`: тот же store, `payload = {'data': {...}}`.
6. Новая функция `cleanup_legacy_cache_files() -> int` — удаляет из `CACHE_DIR` файлы
   `*.cache` и `*.chatinfo` (старые pickle-форматы, включая `*_history.cache`), возвращает
   число удалённых. Ошибки удаления — warning, не исключение.
7. Сигнатуры и поведение `cached_get_chat_history` / `cached_get_chat` не меняются:
   на miss возвращаются живые `Message`, на hit — `CachedMessage`; обе формы duck-совместимы
   (как сегодня pickle-копия vs живой объект).

### 2.7. Задание 3 — стартовая чистка в `api_server.py`

В `lifespan` после `init_db_sync`, **до** запуска фоновых задач:

```python
# One-shot cleanup of legacy pickle cache files (pre-JSON formats)
await asyncio.to_thread(cleanup_legacy_cache_files)
```

Больше в `api_server.py` в рамках пакета A ничего не трогать.

### 2.8. Задание 4 — тесты `tests/test_message_snapshot.py`

Фейковые `Message` — на `SimpleNamespace` (паттерн существующих тестов); `text` — мини-класс
`str` с атрибутом `.html`. Обязательные кейсы:

1. Round-trip основных полей: id, date (naive и aware — оба сохраняют tz-ность), text.html,
   caption.html, media enum (`is MessageMediaType.PHOTO`), views, media_group_id.
2. **Poll с FormattedText-подобными объектами**: фейк `question = SimpleNamespace(text="Q?",
   entities=[])`, каждый option — `SimpleNamespace(text=SimpleNamespace(text="Opt",
   entities=[]))`. Проверить: снапшот JSON-сериализуем (`json.dumps` не падает);
   восстановленный `poll.question` — строка; `getattr(option, 'text', '') == "Opt"`.
   Тест обязан ПАДАТЬ, если снапшот кладёт FormattedText как есть.
3. Реакции: обычная / paid / custom-emoji. У восстановленной custom-реакции:
   `hasattr(r, 'emoji') is True`, `r.emoji is None`, `r.custom_emoji_id` — строка;
   ветка в `_reactions_views_links`-подобной логике выбирается по truthiness, как у живой.
4. forward_origin Case 1–5: `hasattr`-ветвление выбирает правильный case
   (проверять именно наличие/отсутствие атрибутов — здесь presence-семантика сохраняется).
5. service: `'PINNED_MESSAGE' in str(restored.service)`.
6. Мутабельность + deepcopy: присвоение `msg.reply_to_message = X`;
   `copy.deepcopy(restored)` сохраняет `.text.html`.
7. Неизвестный media name (`"FUTURE_TYPE"`) → `media is None`, без исключения.
8. Store: `_store_entry`/`_load_entry` — round-trip, TTL-протухание, version mismatch → None,
   битый JSON → None; уникальность tmp-путей: перехватить `os.replace` (или замокать
   `uuid.uuid4`) и проверить, что два вызова `_store_entry` в один path использовали
   РАЗНЫЕ tmp-имена, а итоговый файл валиден — одиночный «конкурентный» прогон окно
   гонки не ловит и сломанную реализацию с фиксированным tmp пропустит;
   `cleanup_legacy_cache_files` удаляет `*.cache`/`*.chatinfo`, не трогает
   `*.history.json` (использовать `tmp_path`).
9. `_save_media_file_ids` на восстановленном сообщении с `video.file_size` > 100 МБ ничего
   не добавляет в `_pending_media_ids`.
10. Восстановленный `chat` для канала без username: `message.chat.username` — `None`
    (не `AttributeError`) — регресс-тест на правило Р7 (сценарий `rss_generator.py:131`).

### 2.9. Задание 5 — верификация пакета A

- `pytest` — весь существующий набор зелёный.
- `grep pickle tg_cache.py` — пусто; `post_parser.py` и `rss_generator.py` не изменены.

---

## 3. Пакет B — история: префикс вместо строгого равенства `limit`

**Проблема:** `tg_cache.py:106-109` требует `cached_limit == limit`; RSS просит `limit*2`
(`rss_generator.py:419`), HTML — `limit` (`rss_generator.py:639`), оба пишут в один файл.
Чередование запросов превращает кеш в решето.

### 3.1. Задание 6 — логика префикса в `_get_history_from_cache`

Сообщения в кеше лежат от новых к старым (порядок `get_chat_history`), поэтому запрос
с меньшим `limit` — это префикс:

```python
cached_limit = payload.get('limit', 0)
raw_messages = payload['messages']
# Serve from cache when it was fetched with an equal-or-larger limit, OR when the
# channel is exhausted (fewer messages exist than were asked for at fetch time —
# the cache then holds the channel's entire recent history and satisfies ANY limit).
if cached_limit < limit and len(raw_messages) >= cached_limit:
    log("history_cache_limit_insufficient: cached %s < requested %s", cached_limit, limit)
    return None
return restore_messages(raw_messages[:limit])
```

- `_save_history_to_cache` не меняется: хранит `limit`, с которым делался fetch.
- Лог хита дополнить: `served {limit} of cached {cached_limit}`.
- Сходимость: первый запрос с большим `limit` после протухания перезапишет кеш «широкой»
  версией, дальше меньшие запросы — хиты.

### 3.2. Задание 7 — тесты

1. Кеш `limit=100` (100 сообщений) → запрос `limit=50` — хит, ровно 50 первых, порядок сохранён.
2. Кеш `limit=50` → запрос `limit=100` — промах.
3. Исчерпанный канал: кеш `limit=100`, 37 сообщений → запрос `limit=200` — хит, 37 сообщений.
4. TTL работает независимо от limit.

---

## 4. Пакет C — единая канонизация ключа канала

**Проблема:** один канал живёт под ключами `Durov` / `durov` / `@name` в tgcache-файлах,
каталогах `data/cache/` и строках SQLite → дубли кеша, двойные походы в Telegram,
осиротевшие деревья при смене регистра/формы. (Унификация ID↔username — не-цель, раздел 8.)

### 4.1. Задание 8 — новый модуль `channel_key.py`

Отдельный модуль без зависимостей (его импортируют `tg_cache`, `post_parser`, `api_server` —
отдельность исключает циклические импорты):

```python
def canonical_channel_key(channel: str | int) -> str:
    """Canonical cache/DB key for a channel.

    Telegram usernames are case-insensitive -> lowercase them.
    Numeric '-100...' ids keep their exact string form.
    The '@' prefix is stripped.

    The canonical form is also SAFE to pass to Telegram API calls (usernames are
    case-insensitive on the API side; the numeric form is unchanged) — callers that
    thread one value through both filesystem paths and API calls may use it for both.
    """
    s = str(channel).strip().lstrip('@')
    if s.startswith('-100') and s[4:].isdigit():
        return s
    return s.lower()
```

### 4.2. Задание 9 — применить ключ во всех трёх слоях

1. **`tg_cache.py`**: в `_cache_file_path(key, suffix)` прогонять ключ через
   `canonical_channel_key`.
2. **`post_parser.get_channel_username`** (`post_parser.py:1081-1097`): возвращать username
   в нижнем регистре (обе ветки — `usernames`-список и одиночный `username`). Это
   канонизирует записи SQLite (`_save_media_file_ids`), генерируемые media-URL и `t.me`-ссылки
   (t.me к регистру нечувствителен).
3. **`api_server.get_media`** (`api_server.py:1153-1183`): после проверки digest вычислить
   `fs_channel = canonical_channel_key(channel)` и использовать вместо `str(channel)` везде
   ниже: pre-semaphore путь, ключ `_access_updates`, `media_key`, аргумент `_download_deduped`
   (протекает в `download_media_file` → каталоги, API-вызов и удаление из SQLite — для API
   канонический идентификатор безопасен, см. docstring 4.1).
   **Digest проверять по исходной строке URL** — иначе сломаются все выданные ссылки.

### 4.3. Задание 10 — one-shot миграция существующих данных

Без миграции каждый ранее закешированный медиафайл канала с не-lowercase username даёт
после деплоя cache-miss → повторную загрузку из Telegram (шторм ограничен такими каналами
и фактически запрашиваемыми файлами, но страховка дешёвая — делаем).

Новая функция `migrate_channel_keys_sync(db_path: str, cache_dir: str) -> None`. Вызов —
в `lifespan` **после `init_db_sync`, ДО `client.start()` и до запуска фоновых задач**,
строго через `await asyncio.to_thread(migrate_channel_keys_sync, ...)` — функция
синхронная (FS-rename + SQLite), голый вызов заблокировал бы event loop на время
миграции; размещение до `client.start()` дополнительно исключает влияние на сетевые
таски pyrogram и гонки со свипером/access-flush.

Единица работы — **канал целиком, сначала FS, потом SQL** (порядок принципиален:
при провале FS-части SQL-строки канала остаются старорегистровыми, и старое дерево
по-прежнему видно свиперу через строки БД — вечных orphan-каталогов не возникает):

1. Найти каналы-кандидаты: имена каталогов первого уровня в `cache_dir` с не-lowercase
   именем (кроме `-100...`) ∪ `SELECT DISTINCT channel ... WHERE channel != lower(channel)
   AND channel NOT LIKE '-100%'`.
2. Для каждого канала — **FS-шаг**:
   - **ОБЯЗАТЕЛЬНЫЙ guard до любых действий**: если `os.path.exists(dst)` и
     `os.path.samefile(src, dst)` — **no-op FS-шага, перейти к SQL-шагу**. На
     case-insensitive FS (macOS/APFS, Docker Desktop for Mac — том `./data` наследует
     семантику хоста) `Durov/` и `durov/` — один и тот же каталог; merge без guard'а
     удалил бы весь кеш канала.
   - `dst` не существует → `os.rename(src, dst)`.
   - `dst` существует и это другой каталог (case-sensitive FS, обе формы реально есть) →
     пофайловый merge: существующий файл в `dst` выигрывает; затем удалить пустые
     остатки `src`.
   - FS-шаг упал (EACCES и т.п.) → log error с пометкой orphan-кандидата, **SQL-шаг
     канала пропустить**, перейти к следующему каналу.
3. **SQL-шаг** (только после успешного FS-шага): для каждой строки канала:
   - lowercase-строки с тем же `(post_id, file_unique_id)` нет — просто `UPDATE` канала;
   - есть — merge: `added = max(added)` из двух, `mime_type` — предпочесть non-NULL;
     затем `DELETE` старорегистровой строки. Голый `UPDATE ... SET channel=lower(channel)`
     запрещён — ловит PK-конфликт при наличии обеих форм.
4. Ошибки миграции — log error + продолжить работу (миграция не должна уронить старт);
   повторный запуск функции — идемпотентный no-op.
5. **Итоговая сводка одной строкой лога** (сигнал оператору, что деплой C прошёл штатно):
   `migration_summary: rows merged N, dirs renamed M, samefile no-ops K, failures F`.

### 4.4. Задание 11 — тесты + заметка о миграции

- Юнит: `'Durov'→'durov'`, `'@durov'→'durov'`, `-1001…` (int и str) → `'-1001…'`.
- Интеграция: путь tgcache-файла одинаков для `Durov`/`durov`; `get_channel_username`
  на фейковом chat с `username='MixedCase'` → `'mixedcase'`.
- Миграция: (а) SQL-merge обеих форм — остаётся одна строка с `max(added)` и non-NULL
  `mime_type`; (б) guard: вызов с `src`/`dst`, резолвящимися в один каталог (samefile), —
  no-op, данные целы; (в) merge на двух реально разных каталогах — файлы объединены,
  target выигрывает; (г) повторный запуск — no-op.
- В PR: (а) остаточные старорегистровые строки/каталоги, не покрытые миграцией (например,
  появившиеся между бэкапом и деплоем), доживают до 20-дневного вытеснения сами;
  (б) **миграция односторонняя** — reverse-миграции нет; откат пакета C после её
  выполнения возвращает код со старорегистровыми ключами на lowercase-данные и повторяет
  re-download-сценарий зеркально (ограниченный, самоизлечивается за 20 дней) — это
  ожидаемый признак отката, не авария.

---

## 5. Пакет D — свипер медиа-кеша

### 5.1. Задание 12 — фикс чистки БД (баг)

`api_server.py:820-836`: diff и удаление из SQLite выполняются только `if files_removed > 0`.
Запись старше 20 дней **без файла на диске** выпадает из списка без инкремента счётчика
(`api_server.py:663-687`) — и остаётся в БД навсегда, если в том же проходе не удалился
ни один реальный файл. Исправление:

```python
# Compute the DB diff unconditionally: entries dropped from the list because the
# file was already gone must still be purged from SQLite.
updated_set = {...}
removed_entries = [...]
if removed_entries:
    await asyncio.to_thread(remove_media_file_ids_sync, DB_PATH, removed_entries)
    logger.info(f"cache_sweep: purged {len(removed_entries)} entries "
                f"({files_removed} files removed from disk)")
```

### 5.2. Задание 13 — интервал свипа в конфиг

Сейчас `delay = 60` (`api_server.py:811`). Добавить в `config.py` по существующему паттерну
ключ `cache_sweep_interval` (env `CACHE_SWEEP_INTERVAL`, дефолт `900`, минимум `60`),
использовать в `cache_media_files`.

### 5.3. Задание 14 — дедуп очереди фоновых загрузок

Module-level `_queued_media: set[tuple[str, int, str]]`:
- в `download_new_files`: ключ в set'е → skip; иначе `add` + `put_nowait`
  (при `QueueFull` — `discard` и `break` как сейчас);
- в `background_download_worker`: в `finally` рядом с `task_done()` — `discard(key)`.

Event loop однопоточный, обе точки — корутины без await между проверкой и мутацией → гонок нет.
Тест: два подряд вызова `download_new_files` с одним списком кладут в очередь один элемент.

---

## 6. Пакет E — горячий путь `/media`

### 6.1. Задание 15 — константа и хелпер путей

`os.path.abspath("./data/cache")` + ручной `join` собираются в **семи** местах
(`api_server.py:207, 532-536, 667, 757-766, 817, 851, 1172-1175`). Ввести на уровне модуля:

```python
MEDIA_CACHE_DIR = os.path.abspath(os.path.join("data", "cache"))  # resolved once at import

def media_cache_path(channel: str, post_id: int, file_unique_id: str | None = None) -> str:
    """Single source of truth for the on-disk layout: <root>/<channel>/<post_id>[/<fid>]."""
```

Заменить все семь мест. `remove_old_cached_files_sync`/`download_new_files` сохраняют
параметр `cache_dir` (тестируемость), вызыватели передают константу.

### 6.2. Задание 16 — in-memory кеш MIME

Запись access-time уже вынесена с горячего пути в аккумулятор, а чтение MIME до сих пор
делает threadpool-hop + новое SQLite-соединение на каждый хит (`api_server.py:389-404`).
MIME по ключу `file_unique_id` иммутабелен.

```python
# MIME types are immutable per file_unique_id, so a process-lifetime dict in front of
# SQLite removes a to_thread + connect from every cache-hit response.
_mime_types: dict[tuple[str, int, str], str] = {}
_MIME_CACHE_MAX = 50_000  # crude bound; clear-all on overflow is fine at this size
```

Порядок в `prepare_file_response`: dict → (miss) SQLite → (miss) python-magic → записать
и в SQLite, и в dict. При успешном чтении из SQLite — заполнить dict. При переполнении —
`clear()`. Тест: замокать `get_mime_type_sync`, два запроса подряд — второй его не вызывает.

---

## 7. Пакет F — довесок к новому store

### 7.1. Задание 17 — джиттер TTL при записи

Сейчас `random_factor` перебрасывается на каждом чтении (`tg_cache.py:98, 192`) — срок жизни
записи недетерминирован, что усложняет рассуждения о поведении и тесты (одна и та же запись
у границы TTL может дать разный результат в соседних чтениях; устойчивого «мигания» нет —
первый же miss ведёт к перезаписи со свежим timestamp). В generic-store пакета A:
- `_store_entry` дополнительно пишет `'jitter': random.uniform(0.8, 1.0)`;
- `_load_entry` считает `adjusted_max_age = max_age_hours * 3600 * entry.get('jitter', 1.0)`
  и не дёргает `random` при чтении.

Срок жизни записи детерминирован после записи, разброс между инстансами/каналами сохраняется.
Тест: одна и та же запись около границы TTL даёт стабильный результат при повторных чтениях.

### 7.2. Задание 18 — age-sweep tgcache + добить legacy-данные

1. Новая функция `sweep_tgcache(max_age_days: int = 7) -> int` в `tg_cache.py`: удаляет из
   `CACHE_DIR` любые файлы с mtime старше порога. Живые файлы перезаписываются каждые ≤12 ч,
   поэтому mtime > 7 суток — гарантированно мёртвый файл (умерший/переименованный канал,
   неканоничный ключ, осиротевший uuid-tmp от упавшего писателя). Гонка с писателем
   ВОЗМОЖНА (stat→unlink не атомарен против `os.replace`: sweep может удалить файл,
   обновлённый между stat и unlink), но безвредна — худший исход один лишний miss-refetch;
   гонка с читателем так же самоизлечивается как miss. Не выдавать это за инвариант
   атомарности в комментариях кода.
2. Вызовы: (а) один раз при старте — рядом с `cleanup_legacy_cache_files` (задание 3);
   (б) из цикла `cache_media_files` раз в проход, **обязательно через `asyncio.to_thread`**
   (listdir+stat+unlink — синхронный FS I/O; инвариант кодовой базы — ничего блокирующего
   на event loop). Каталог плоский, стоимость — миллисекунды.
3. Стартовая legacy-чистка (задание 3) остаётся: sweep покрывает legacy-файлы сам, но
   с задержкой до 7 суток; чистка по расширениям делает это мгновенно.
4. Расширить стартовую чистку: удалить `data/media_file_ids.json` (наследие до-SQLite
   хранилища, кодом не читается — проверено grep). Лог — одной строкой с перечнем удалённого.

---

## 8. Границы (сознательно НЕ входит)

- **Унификация ID↔username** (`/rss/-100…` и `/rss/durov` одного канала остаются разными
  ключами во всех слоях): потребовала бы резолва через `get_chat` (лишний RPC, свои отказы
  и кеш-инвалидация). Канонизация пакета C устраняет только дубли регистра/формы записи.
- Переезд метаданных медиа с SQLite куда-либо ещё — SQLite остаётся.
- Кеширование результатов рендеринга (processed dicts / готовый HTML фида) — отдельная
  большая тема с инвалидацией по параметрам запроса.
- Оптимизация `calculate_cache_stats` (полный walk на `/health`) — низкий приоритет.
- `SimpleNamespace` → dataclass в `cached_get_chat` — косметика.

## 9. Сквозные критерии приёмки

1. `pytest` зелёный; `post_parser.py`/`rss_generator.py` изменены только в объёме
   задания 9.2 (lowercase в `get_channel_username`).
2. `grep pickle tg_cache.py` — пусто.
3. Сценарий «RSS(limit=100) → HTML(limit=50) → RSS(100)» порождает **один** поход в Telegram
   (сейчас — три).
4. `/rss/Durov` и `/rss/durov` используют один tgcache-файл; `/media/Durov/...` и
   `/media/durov/...` — один файл на диске.
5. Повторный `/media`-хит не создаёт SQLite-соединений (ни на чтение MIME, ни на запись
   access-time). Рецепт проверки: monkeypatch `file_io._open_db` счётчиком соединений;
   два последовательных запроса TestClient к одному файлу — на втором счётчик не растёт.
6. Строка SQLite с `added` старше 20 дней и отсутствующим файлом исчезает из БД за один
   проход свипа.
7. Кеш истории сохраняется и для каналов с опросами в выборке (снапшот JSON-сериализуем).
8. Миграция ключей на case-insensitive FS — no-op без потери данных (samefile-guard).

## 10. Риски

| Риск | Закрытие / статус |
|---|---|
| Пропущенное поле allowlist → тихая деградация рендера | **Живой риск, не закрыт полностью.** Инвентарь снят по всем потребителям (2.3–2.4) и сверен с kurigram 2.2.23; ревью нашло и закрыло два пропуска (FormattedText в poll, omit-None семантика) — но гарантии полноты ручного инвентаря нет. Митигция: тесты 2.8, деградация проявляется как выпадение конкретного элемента рендера, не крэш; TTL 8 ч ограничивает окно |
| Смешение живых `Message` (miss) и `CachedMessage` (hit) | Так работает и текущий pickle-кеш; живой объект — надмножество контракта |
| Порча файла при падении посреди записи / конкурентная запись | Уникальный tmp + `os.replace` + finally-очистка (Р9) |
| Старые pickle после деплоя | Игнорируются новыми именами + `cleanup_legacy_cache_files()` |
| Канонизация: существующие данные со старым регистром | One-shot миграция (задание 10) с samefile-guard; остатки доживают до 20-дневного LRU |
| Миграция на case-insensitive FS | Обязательный `os.path.samefile`-guard → no-op (критерий 9.8) |

## 11. Рассмотренные альтернативы

**Version-stamped pickle** (минимальный вариант): оставить pickle, дописать в конверт
`pyrogram.__version__` + версию схемы, несовпадение считать miss'ом (~5 строк). Закрывает
«тихий дрейф» и стоимость апгрейда библиотеки (один TTL-эквивалентный miss на канал —
пренебрежимо при TTL 8 ч). **Отклонена решением владельца проекта** (альтернатива
предлагалась явно на этапе аудита как «рекомендация-минимум»; выбран стратегический
вариант) по причинам: (а) исходная цель — «проще и поддерживаемее»: JSON читаем глазами
при отладке, pickle — нет; (б) снапшот делает зависимость рендера от полей `Message`
явным документированным контрактом (схема 2.3) вместо размазанной по ~2000 строк;
(в) меньший файл и дешёвый parse вместо unpickle графа объектов в threadpool.
Цена: ручной инвентарь полей с остаточным риском пропуска (раздел 10, первый пункт).

## 12. История ревью

Спецификация прошла два раунда адверсарного ревью (субагент-критик с доступом к кодовой
базе и установленному kurigram 2.2.23). Итоги:

- **C1 (BLOCKER, принято)**: исходная схема не разворачивала `FormattedText` в
  `poll.options[].text` → `json.dump` падал бы, кеш молча переставал сохраняться для
  каналов с опросами; исходные тест-фикстуры дефект не ловили. Исправлено: 2.4.1, тест 2.8.2.
- **C2 (MAJOR, принято с усилением)**: blanket omit-None ломал эквивалентность с живыми
  объектами (у которых все атрибуты всегда присутствуют) и давал крэш-пути
  (`rss_generator.py:131`, `post_parser.py:1087`). Итог: правило Р7 «полные ключи, кроме
  forward_origin».
- **C3 (MAJOR, принято)**: канонизация без миграции → повторные загрузки медиа после деплоя.
  Добавлено задание 10. Встречное возражение критика к первой версии миграции
  (**потеря кеша на case-insensitive FS**) принято: обязательный samefile-guard.
- **C4 (MAJOR → MINOR)**: критик требовал обосновать отказ от version-stamped pickle.
  Закрыто разделом 11; довод «холодный кеш на каждый бамп библиотеки» в обоснование
  сознательно НЕ включён (стоимость — один miss на канал, пренебрежимо). Остаточный MINOR:
  риск ручного инвентаря остаётся живым (раздел 10).
- **C5–C12 (MINOR, приняты)**: уникальный tmp; docstring `canonical_channel_key`;
  сужение проблемы #3; седьмое место сборки пути (`:817`); TTL 8–12 ч; `custom_emoji_id: str`;
  честная мотивация джиттера; age-sweep tgcache (+`to_thread` из фонового цикла).
- **Раунд 4 (новые векторы: атака на собственные правки критика, межпакетные
  взаимодействия, реализуемость, рантайм-семантика, операционка): 6 MINOR, все приняты.**
  D1 — `to_thread` + размещение миграции до `client.start()`; D2 — порядок «FS → SQL
  per-channel», чтобы частичный отказ FS не рождал orphan-деревья, невидимые свиперу;
  D3 — гонка sweep/писатель честно названа возможной-но-безвредной; D4 — зависимость
  «C после A» зафиксирована в таблице (задание 9.1 опирается на `_cache_file_path` из
  задания 2); D5 — тест 2.8.8 переписан на дискриминирующий (уникальность tmp-путей),
  критерий 9.5 получил рецепт проверки; D6 — итоговая сводка миграции в лог + пометка
  об односторонности миграции при откате. По направлениям «откаты A/B/F», «смешение
  живых и восстановленных объектов», «json.dumps(CachedStr)», «deepcopy», «exclude_*»
  критик существенных находок не нашёл (с доказательствами по коду: hit/miss атомарен
  на весь список, `/json`-эндпоинт идёт мимо кеша истории, tz-гомогенность гарантирована Р6).