tests: конкурентный стресс-гарнесс ClientPool/lease + контракт lease lifecycle

[axisrow]

Мотивация (замер по истории проекта)

Гонки/локи/lease — 18 фиксов за 4 месяца, самый дорогой класс багов: дизайн-уровень, линтером не ловится, сейчас единственная защита — dual-review (причём Codex стабильно ловит глубже: #1188 use-after-disconnect в pool, #1189 race-окно в acquire-пути / late reservation, #1145 TOCTOU phone+session из разных await). Каждый такой баг находится только на ревью или в проде — направленных тестов на конкурентность нет.

Что сделать

1. Направленный конкурентный стресс-гарнесс для ClientPool/lease и DB write-lock:
   • N корутин через asyncio.gather с барьерами (asyncio.Event/asyncio.Barrier) на критических путях: acquire/release lease, disconnect во время использования, ротация flood_wait, параллельные записи через db.transaction()/execute_write.
   • Каждый исторический race (fix(agent): keep resolve_entity lease alive for caller (#1187) #1188 use-after-disconnect, fix(pool): make release_client pop+discard atomic (close #1181 race) #1189 late reservation, REST: POST /api/accounts/{id}/export-session #1145 TOCTOU phone+session, Connection-wide write lock for shared aiosqlite connection (delete_channel atomicity) #569 interleaved writes) → постоянный регресс-гард.
   • Мутационная верификация каждого гарда: тест обязан быть красным на до-фиксной версии кода (revert фикса локально → тест падает).
2. Контракт lease lifecycle: зафиксировать инварианты (кто владеет клиентом между await-точками; что запрещено после disconnect; когда phone и session обязаны читаться атомарно) в докстрингах pool/lease + контракт-тест, чтобы новые правки сверялись с контрактом, а не с интуицией.
3. Закрепить процесс в CLAUDE.md: pool/lease/security PR → обязательно оба ревьюера (Claude + Codex); при расхождении вердиктов — своя сверка, верить более глубокому.

Ограничения

• Тесты fake/harness-first, без реального Telegram (политика real-TG не меняется).
• Гарнесс не должен быть флейковым под -n auto: детерминированные барьеры вместо sleep-таймингов.

Verification

• Каждый регресс-гард мутационно проверен (красный на до-фиксном коде).
• Полный прогон (parallel + serial) зелёный, без новых флейков.
• Контракт-тест lease lifecycle существует и падает при нарушении инварианта.

Связано

• Related: bug-hunt: новый раунд поиска багов и опасного говнокода после #879 #1127 (bug-hunt umbrella — этот гарнесс закрывает главный класс находок системно).
• Исторические race-фиксы как источник сценариев: fix(agent): keep resolve_entity lease alive for caller (#1187) #1188, fix(pool): make release_client pop+discard atomic (close #1181 race) #1189, REST: POST /api/accounts/{id}/export-session #1145, Connection-wide write lock for shared aiosqlite connection (delete_channel atomicity) #569.

[axisrow]

План реализации (для агента-исполнителя)

Состояние на main (проверено по git, 2026-07-02): все 4 исторических race-фикса уже смержены вместе с регресс-гардами — #1181/#1189 (атомарный pop+discard в release_client; тесты в tests/test_client_pool_lifecycle.py), #1187/#1188 (ResolvedEntityLease; TestResolveEntityLease в tests/test_agent_tools_registry.py, инвариант total_acquired == len(released)), #1145 (get_session_export один row; tests/routes/test_export_session_1145.py), #569/#570 (write-lock; tests/test_database_write_lock.py). Их НЕ пересоздавать. Скоуп issue — обобщение: класс lease-leak повторялся минимум трижды (#1179 resolve_photo_target, #1183, #1187 resolve_entity), а точечные гарды ловят только уже известные сценарии.

Карта кода (композиция миксинов #1046): src/telegram/client_pool.py (состояние: _lock, _in_use — set, разделяемый по ссылке с AccountLeasePool, _active_leases LIFO-стеки), src/telegram/account_lease_pool.py (acquire_available/acquire_by_phone/release, свой _lock, две фазы exclusive/shared), src/telegram/pool_lifecycle.py (get_available_client:191, release_client:243 — единственная точка релиза, _acquire_phone_lease:428 — TOCTOU-окно между lease-pool-lock и pool-lock fallback, _acquire_from_lease:452), src/telegram/pool_flood.py, src/telegram/pool_dialogs.py (warm_all_dialogs acquire→try/finally), src/database/facade.py (transaction():264, execute_write:293, _write_lock:102).

Этап 1 — статический контракт lease-баланса

Новый файл tests/test_lease_lifecycle_contract.py; жанр — tests/test_sql_conventions.py и test_facade_passthrough_surface_does_not_grow.

1. AST-скан src/: каждый call-site get_available_client/get_client_by_phone/get_native_client_by_phone обязан либо (а) иметь парный release_client/.release() в finally внутри той же функции, либо (б) возвращать lease-объект наружу (владение передано; допустимый список таких функций-владельцев зафиксировать явно в тесте как allow-list с комментарием почему).
2. Мутационная верификация: временно убрать finally-release в одном call-site (например, warm_all_dialogs) → тест обязан покраснеть; вернуть. НЕ использовать git checkout незакоммиченного для отката (грабли из CLI argparse→Typer: Волна 4 — сложные вложенные (analytics/channel/dialogs/pipeline) #1124) — мутацию откатывать руками.
3. Это ловит будущие утечки класса fix(photo): lease leak в resolve_photo_target (target=me не освобождает клиент) #1179/fix(photo): release client lease in resolve_photo_target #1183/fix(agent): resolve_entity в _registry.py не освобождает client lease (HIGH, тот же класс что #1179) #1187 на этапе PR, а не в проде.

Этап 2 — докстринг-контракт lease lifecycle

1. Модульный докстринг client_pool.py (строки 1–37 уже описывают распределение состояния): дописать инварианты — (а) телефон не может одновременно держать shared и exclusive lease; (б) discard из _in_use атомарен с pop из _active_leases (внутри одного критического сечения ClientPool._lock; вложенный порядок ClientPool._lock → AccountLeasePool._lock, обратный порядок запрещён — deadlock); (в) каждый acquire имеет парный release (баланс, этап 1); (г) после disconnect_all использование клиента запрещено.
2. Продублировать по месту: докстринги release_client (pool_lifecycle.py:243 — там уже есть развёрнутый докстринг про LIFO/fix(pool): two-phase release_client race (shared+exclusive на одной session) #1181, дополнить), _acquire_phone_lease, acquire_available/release в account_lease_pool.py.

Этап 3 — детерминированные тесты критических окон

Новый файл tests/test_client_pool_lease_stress.py (рядом с #1181-тестами); строить пул ТОЛЬКО через real_pool_harness_factory — fake-pool shortcuts запрещены гардом tests/test_pool_harness_guardrails.py.

Правило анти-флейк: НИКАКИХ sleep-таймингов; порядок фиксировать asyncio.Event/asyncio.Barrier/spy-хуками (образец — #1181-тесты: спай на _lease_pool.release, проверяющий pool._lock.locked()).

1. Окно _acquire_phone_lease:428 — между acquire_by_phone (lease-pool lock) и fallback-веткой (pool lock): два конкурента на один телефон через Barrier; инвариант (а) не нарушается ни в одном interleaving.
2. Exception-путь _acquire_from_lease:452 — исключение бэкенда при not shared: lease освобождён, _in_use чист.
3. disconnect_all при живых лизах: клиент не используется после disconnect (спай на методы клиента после disconnect → 0 вызовов).
4. Storm-тест (seeded): N корутин × M операций (get_available_client/get_client_by_phone/release_client/report_flood) с random.Random(seed), одновременный старт через Barrier; ассерты — только инварианты состояния (в конце: _in_use пуст, _active_leases пусты; в чекпоинтах: нет shared+exclusive на одном телефоне), НЕ тайминги. Инварианты обязаны держаться при ЛЮБОМ interleaving — такой тест не флейкает по построению; если упал — это реальный баг.
5. Write-lock storm в tests/test_database_write_lock.py или соседнем файле: gather писателей через db.transaction()+execute_write на :memory: db-фикстуре; инвариант — нет interleaved-коммитов (маркер порядка через Event, не sleep). Опционально (отдельным коммитом): перевести существующие sleep-based тесты этого файла (0.005–0.02s) на Event-примитивы — они кандидаты во флейк под 4 xdist-воркерами.

Этап 4 — процесс

В CLAUDE.md (раздел Conventions) добавить строку: PR, затрагивающий pool/lease/session/security-слои, проходит dual-review (Claude + Codex) обязательно; при расхождении вердиктов — своя сверка по коду, приоритет более глубокому анализу.

Ограничения

• Тесты fake/harness-first: real_pool_harness_factory + FakeCliTelethonClient (tests/helpers.py), никакого реального Telegram; native transport — только с маркером native_backend_allowed.
• Параллельность: db-фикстура :memory: — тесты остаются в -n auto; raw aiosqlite.connect() не использовать (иначе авто-aiosqlite_serial); уровень (integration) выведется автоматически.
• filterwarnings = ["error"] — ни одного нового ворнинга; глобальный timeout = 120.
• ci.yml не трогать.

Критерии приёмки (по ним будет ревью)

• Контракт-тест этапа 1 мутационно доказан (в описании PR — какая мутация, как покраснел).
• Каждый тест этапов 3.1–3.3 детерминирован (нет sleep-таймингов в ассертах) и проверяет объявленный инвариант из докстринг-контракта этапа 2.
• Storm-тесты ассертят только инварианты состояния.
• Существующие fix(pool): two-phase release_client race (shared+exclusive на одной session) #1181/fix(agent): keep resolve_entity lease alive for caller (#1187) #1188/REST: POST /api/accounts/{id}/export-session #1145/Connection-wide write lock for shared aiosqlite connection (delete_channel atomicity) #569-гарды не тронуты и зелёные.
• Полный прогон (parallel + serial) зелёный; PR ревьюят оба ревьюера (это pool/lease-слой — правило этапа 4 применяется к самому этому PR).