epic: атомарный collector.py — разбить перегруженные функции и области обработки ошибок

[axisrow]

Проблема

За время работы над #38 (PR #39) одна и та же правка прошла четыре итерации ревью, и три из них нашли новый дефект в том же куске кода:

1. except DownloadTimeoutError глотал и «скачалось больше одного CSV», и настоящие сбои ретрая → введён отдельный DownloadNoNewPathError;
2. при перезаписи файла на месте старый распарсенный dataset соединялся с новым raw-файлом → parquet и manifest расходились с CSV → добавлено сохранение копии до ретрая;
3. область очистки временной копии начиналась после её создания → при падении copy2 копия оставалась в output_root → try расширен на создание файла.

Каждый раз код был локально верным, а дефект был на границе области действия: проверка или защита стояла рядом с настоящим местом риска, а не на нём. Это не серия случайных промахов, а свойство формы кода.

Измерения

src/wordstat/collector.py — 1420 строк, 31 функция.

Функция	Строк	try	Ветвлений	Вложенность
_collect_one	324	4	26	8
collect_many	157	4	7	7
_assert_contiguous_dynamics_rows	102	1	10	5
_download_current_view	99	0	4	4
_select_view	47	1	4	7

Вложенные try в _collect_one (строки 403–726):

for view in enumerate(pending_views)        :564-706
  try (AuthenticationRequiredError, Exception)   :565-706  142 строки
    try (Exception)                              :583-669   87 строк
      try ... finally                            :600-633   34 строки
        try (DownloadNoNewPathError)             :609-630   22 строки

Четыре уровня обработки ошибок в одной функции. Ни одна проверка на такой глубине не читается целиком — именно поэтому три ревью подряд находили новое.

Цель

Разбить крупные функции collector.py на атомарные единицы с явными результатами и одним владельцем жизненного цикла у каждого ресурса. Поведение сохранить полностью: 180 тестов должны остаться зелёными без правок, кроме случаев, где тест обращается к приватному имени, которое переехало.

Подзадачи

1. Ретрай пустого экспорта (первоочередное, блокирует PR #39)
Вынести в отдельный helper, возвращающий явный результат: success(source, dataset) / no_new_path / проброс прочих ошибок. Жизненный цикл временной копии — один внешний try/finally, охватывающий создание, копирование, использование и удаление. Ни одной ветки, где source и dataset происходят из разных файлов.

2. _collect_one (324 → цель ≤ 80 строк)
Выделить: подготовку вида, скачивание с ретраем (п. 1), запись датасета и финализацию raw, обработку сбоя одного вида. Каждый вложенный try должен стать try внутри своей маленькой функции.

3. collect_many (157 строк, 4 try)
Отделить жизненный цикл общего временного каталога загрузок от обхода фраз и от обработки ошибок отдельной фразы.

4. _assert_contiguous_dynamics_rows (102 строки, 10 ветвлений)
Разделить на проверку вхождения в окно и проверку непрерывности; они сейчас переплетены.

5. _download_current_view (99 строк)
Отделить снапшот-диффинг от поллинга и от проверки «файл не убежал за пределы каталога».

Правила

• Чистый рефакторинг: никаких изменений поведения, никаких новых возможностей.
• После каждой подзадачи — все тесты зелёные, ruff check . чист.
• Каждая подзадача — отдельный PR, чтобы ревью было обозримым.
• Все инварианты из комментариев (порядок «скачать → распарсить → записать parquet → убрать raw», зона безопасности finalize_raw, fail-closed для dynamics) сохранить и не растерять по дороге — они документируют реальные баги.
• Мутационная проверка на каждый PR, включая границы областей try/finally, а не только ветвления.

Порядок

Подзадача 1 делается первой и вливается в PR #39 — он сейчас на ней и заблокирован. Остальные — после.

[axisrow]

Декомпозиция

Эпик разбит на пять нативных sub-issues. Оценки откалиброваны по истории этого репозитория: fix-PR в среднем ~306 LOC (n=10), крупные фичи 1000–1300 LOC (#5, #10, #21, #28), чистые рефакторинги 100–150 LOC (#30, #35).

#	Подзадача	LOC	Размер	Код	Review	Итого	Приоритет
#44	Подготовка прогона из _collect_one	150–250	M	30–45	20–30	50–75	high
#45	Цикл видов _collect_one (293 → ≤80)	250–400	L	60–90	40–60	100–150	high
#46	Обязанности collect_many	200–300	M–L	45–70	30–45	75–115	medium
#47	Проверки dynamics (вхождение / непрерывность)	120–200	M	25–45	15–25	40–70	medium
#48	Снапшот / поллинг / escape в _download_current_view	150–250	M	35–55	25–40	60–95	low

Суммарно: 325–505 минут (5.5–8.5 часов агентной работы), ~870–1400 LOC суммарно по всем PR.

Ни одна подзадача не даёт PR больше 1000 строк — дробить дальше не требуется.

Рекомендованный порядок

1. refactor: вынести подготовку прогона из _collect_one #44 — фундамент: убирает из _collect_one подготовительные блоки (53 + 35 строк), после чего цикл видов становится обозримым.
2. refactor: разбить цикл видов в _collect_one (293 -> <=80 строк) #45 — главная цель эпика. Зависит от refactor: вынести подготовку прогона из _collect_one #44.
3. refactor: разделить обязанности collect_many #46, refactor: разделить проверки вхождения и непрерывности dynamics #47 — независимы от _collect_one, можно вести параллельно с refactor: разбить цикл видов в _collect_one (293 -> <=80 строк) #45 (разные функции, конфликтов по коду немного).
4. refactor: разделить снапшот, поллинг и escape-проверку в _download_current_view #48 — последней: функция сложная, но стабильная; трогать её стоит, когда остальное устоится.

Что уже сделано

Подзадача 1 исходного плана (вынести ретрай пустого экспорта в helper с явными результатами) выполнена в PR #39: появился _retry_empty_export (48 строк), _RetryExportResult как согласованная пара source+dataset, жизненный цикл временной копии — в одном внешнем try/finally. _collect_one уменьшился с 324 до 293 строк, вложенных try стало 2 вместо 4. Отдельная sub-issue на неё не заводилась.

Замечание по методу

Все дефекты, найденные в ходе этого эпика (три раунда ревью в PR #39, плюс #41), — один класс: проверка смотрит на соседний сигнал вместо искомого, и потому проходит вхолостую. Поэтому в каждой подзадаче требование гонять мутации по границам областей try/finally, а не только по ветвлениям: именно там прошли все пропущенные дефекты.

[axisrow]

Все ветки эпика влиты (последними — #59 диагностика живых сбоев и #60 --strict-exit). Закрываю.