voiceroute.py 0.1.0.dev0__tar.gz

voiceroute_py-0.1.0.dev0/.editorconfig

@@ -0,0 +1,13 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+indent_style = space
+indent_size = 4
+trim_trailing_whitespace = true
+
+[*.{md,yml,yaml}]
+indent_size = 2
+

voiceroute_py-0.1.0.dev0/.env.example

@@ -0,0 +1,6 @@
+VOICEROUTE_URL=https://dev.voiceroute.cc
+VOICEROUTE_BOT_TOKEN=vrb_replace_me
+# Необязательные ограничения для бота, слушающего только один канал:
+# VOICEROUTE_COMMUNITY_ID=00000000-0000-4000-8000-000000000000
+# VOICEROUTE_CHANNEL_ID=00000000-0000-4000-8000-000000000000
+

voiceroute_py-0.1.0.dev0/.github/workflows/ci.yml

@@ -0,0 +1,39 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  quality:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+          cache: pip
+      - run: python -m pip install -e '.[dev]'
+      - run: ruff check .
+      - run: ruff format --check .
+      - run: mypy src
+
+  tests:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+      - run: python -m pip install -e '.[dev]'
+      - run: pytest --cov=voiceroute --cov-report=term-missing
+

voiceroute_py-0.1.0.dev0/.gitignore

@@ -0,0 +1,16 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.coverage
+.env
+.idea/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.venv/
+.voiceroute/
+.vscode/
+build/
+dist/
+htmlcov/
+

voiceroute_py-0.1.0.dev0/CHANGELOG.md

@@ -0,0 +1,26 @@
+# История изменений
+
+Проект следует [Semantic Versioning](https://semver.org/) и рекомендациям
+[Keep a Changelog](https://keepachangelog.com/).
+
+## [Unreleased]
+
+### Added
+
+- Начальная структура Python-пакета.
+- Асинхронный HTTP transport и bot-аутентификация.
+- Базовые модели и API профиля текущего бота.
+- Восстанавливаемые SSE-потоки с checkpoint после успешной обработки.
+- Атомарное файловое и process-local хранилища cursor.
+- Общий sliding-window rate limiter и безопасные retry с учётом `Retry-After`.
+- Постраничное восстановление backlog перед переходом к live SSE.
+- Публичный `EventTransport` и `LegacySSETransport`, отделяющие runtime от сетевого
+  протокола событий.
+- Независимые `Command`, `CommandRegistry`, `CommandInvocation` и
+  `PrefixCommandAdapter` с aliases, группами, типизированными аргументами и command
+  lifecycle events.
+- Command pipeline с async middleware, checks, cooldowns и concurrency limits.
+- Расширения с декларативными командами/listeners, атомарной регистрацией и module
+  load/unload/reload lifecycle.
+- Явный runtime lifecycle, graceful shutdown и независимый supervision channel consumers.
+

voiceroute_py-0.1.0.dev0/CONTRIBUTING.md

@@ -0,0 +1,45 @@
+# Участие в разработке
+
+## Ветки
+
+Используйте общепринятые префиксы:
+
+- `feature/` — новая функциональность;
+- `fix/` — исправление ошибки;
+- `docs/` — документация;
+- `refactor/` — внутреннее изменение без нового поведения;
+- `test/` — тесты;
+- `chore/` — инфраструктура и обслуживание;
+- `release/` — подготовка выпуска;
+- `hotfix/` — срочное исправление стабильной версии.
+
+Ветки с префиксом `codex/` запрещены.
+
+## Коммиты
+
+Сообщения пишутся на английском языке в формате Conventional Commits со scope:
+
+```text
+feat(events): add resumable channel stream
+fix(http): preserve idempotency key across retries
+docs(readme): document development setup
+```
+
+## Слияния
+
+- изменения попадают в `main` через pull request;
+- fast-forward merge запрещён;
+- используйте merge commit (`git merge --no-ff`);
+- перед слиянием должны пройти lint, format, type check и tests;
+- публичное поведение сопровождается тестами и документацией;
+- несовместимые изменения до `1.0.0` явно отмечаются в changelog.
+
+## Локальная проверка
+
+```bash
+ruff check .
+ruff format --check .
+mypy src
+pytest
+```
+

voiceroute_py-0.1.0.dev0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 dog-bobik
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

voiceroute_py-0.1.0.dev0/PKG-INFO

@@ -0,0 +1,170 @@
+Metadata-Version: 2.5
+Name: voiceroute.py
+Version: 0.1.0.dev0
+Summary: Async Python SDK and bot framework for the VoiceRoute HTTP and SSE APIs.
+Project-URL: Homepage, https://github.com/dog-bobik/voiceroute.py
+Project-URL: Documentation, https://github.com/dog-bobik/voiceroute.py#readme
+Project-URL: Issues, https://github.com/dog-bobik/voiceroute.py/issues
+Project-URL: Repository, https://github.com/dog-bobik/voiceroute.py.git
+Author: dog-bobik
+License-Expression: MIT
+License-File: LICENSE
+Keywords: asyncio,bot,sdk,sse,voiceroute
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.11
+Requires-Dist: httpx<1,>=0.27
+Provides-Extra: dev
+Requires-Dist: mypy>=1.13; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest-cov>=6; extra == 'dev'
+Requires-Dist: pytest>=8.3; extra == 'dev'
+Requires-Dist: python-dotenv<2,>=1.0; extra == 'dev'
+Requires-Dist: respx>=0.22; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
+Requires-Dist: mkdocstrings[python]>=0.27; extra == 'docs'
+Provides-Extra: examples
+Requires-Dist: python-dotenv<2,>=1.0; extra == 'examples'
+Provides-Extra: redis
+Requires-Dist: redis<8,>=5; extra == 'redis'
+Description-Content-Type: text/markdown
+
+# voiceroute.py
+
+Асинхронный Python SDK и фреймворк для разработки ботов в
+[VoiceRoute](https://voiceroute.cc).
+
+> [!WARNING]
+> Проект находится на ранней стадии разработки. Публичный API может меняться до
+> выпуска версии `1.0.0`.
+
+## Цели проекта
+
+- типизированный асинхронный клиент HTTP API;
+- надёжная обработка SSE с восстановлением курсора;
+- идемпотентная отправка сообщений;
+- удобная событийная модель и команды в стиле современных bot-фреймворков;
+- расширяемая архитектура без смешивания bot token и пользовательской сессии;
+- безопасная работа с лимитами запросов, повторными попытками и секретами.
+
+## Установка для разработки
+
+Требуется Python 3.11 или новее.
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+python -m pip install -e '.[dev]'
+```
+
+Примеры автоматически читают локальный `.env` из корня репозитория. В нём
+достаточно указать `VOICEROUTE_BOT_TOKEN`; production используется по умолчанию.
+
+Полноценный демонстрационный пример: [Community Assistant Bot](examples/community_assistant/README.md).
+
+## Минимальный бот
+
+```python
+import os
+
+from voiceroute import Bot, Context, FileCursorStore
+
+bot = Bot(
+    token=os.environ["VOICEROUTE_BOT_TOKEN"],
+    cursor_store=FileCursorStore(".voiceroute/cursors.json"),
+)
+
+
+@bot.command()
+async def ping(context: Context) -> None:
+    await context.reply("Pong!")
+
+
+bot.run()
+```
+
+Ответ использует стабильный UUID, производный от исходного сообщения. Повторная
+доставка SSE-события поэтому не создаст дубликат ответа.
+
+По умолчанию команды принимают оба привычных префикса: `/ping` и `!ping`.
+Собственный префикс задаётся через `Bot(..., command_prefix="?")`.
+
+Команды поддерживают aliases, группы и типизированные позиционные аргументы. Метаданные и
+вызов не зависят от prefix transport, поэтому будущие server-native interactions можно
+будет подключить отдельным адаптером. Подробнее: [командный фреймворк](docs/commands.md).
+
+Команды и listeners больших ботов можно объединять в расширения с атомарной загрузкой,
+выгрузкой и reload. Подробнее: [расширения](docs/extensions.md).
+
+Runtime поддерживает явные состояния, graceful shutdown и изоляцию channel consumers с
+ограниченным backoff. Подробнее: [жизненный цикл runtime](docs/runtime.md).
+
+Клиент умеет редактировать и удалять сообщения, управлять закреплением и реакцией,
+читать pins и выполнять поиск. Подробнее: [контентный API](docs/content-api.md).
+
+По умолчанию бот обнаруживает все доступные ему сообщества и текстовые каналы.
+Для ограничения одним каналом можно явно передать `community_id` и `channel_id`.
+При первом подключении он запрашивает историю после `seq=0`, чтобы не пропустить
+команды, отправленные незадолго до запуска. Идемпотентные ответы защищают от
+дубликатов при повторном получении тех же сообщений.
+
+`FileCursorStore` атомарно сохраняет обработанную позицию с правами `0600`.
+Cursor обновляется только после успешного завершения обработчика, поэтому после
+сбоя событие будет доставлено повторно. Для нескольких процессов доступны SQLite и
+Redis. Подробнее: [события и восстановление](docs/events.md).
+
+Все HTTP-операции одного клиента используют общий лимитер 50 запросов в секунду.
+Безопасные запросы и идемпотентная отправка сообщений повторяются после временных
+сетевых ошибок; `429` соблюдает `Retry-After`. Подробнее: [сеть и повторы](docs/network.md).
+
+## Состояние реализации
+
+| Возможность | Состояние |
+| --- | --- |
+| Bot-аутентификация | Основа готова |
+| Профиль текущего бота | Основа готова |
+| Сообщества и каналы | Базовое чтение готово |
+| Сообщения | История, отправка и изменение готовы |
+| Реакции, закрепления и поиск | Основа готова |
+| SSE и восстановление курсора | Основа готова |
+| Prefix-команды | Основа готова |
+| Middleware | Основа готова |
+| Треды и вложения | Запланировано |
+| Роли и модерация | Запланировано |
+| Голос для сторонних ботов | Не поддерживается API [VoiceRoute](https://voiceroute.cc) |
+
+Подробная последовательность работ находится в [дорожной карте](docs/roadmap.md),
+текущее покрытие — в [матрице API](docs/api-coverage.md), а принятые границы проекта —
+в [описании архитектуры](docs/architecture.md).
+
+## Разработка
+
+```bash
+ruff check .
+ruff format --check .
+mypy src
+pytest --cov=voiceroute --cov-report=term-missing
+```
+
+Правила веток, коммитов и слияний описаны в [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## Безопасность
+
+Не добавляйте bot token в исходный код, URL, query-параметры или логи. Используйте
+переменные окружения и передавайте токен только через официальный заголовок
+авторизации. Инструкции по сообщению об уязвимостях находятся в
+[SECURITY.md](SECURITY.md).
+
+## Лицензия
+
+[MIT](LICENSE)
+

voiceroute_py-0.1.0.dev0/README.md

@@ -0,0 +1,130 @@
+# voiceroute.py
+
+Асинхронный Python SDK и фреймворк для разработки ботов в
+[VoiceRoute](https://voiceroute.cc).
+
+> [!WARNING]
+> Проект находится на ранней стадии разработки. Публичный API может меняться до
+> выпуска версии `1.0.0`.
+
+## Цели проекта
+
+- типизированный асинхронный клиент HTTP API;
+- надёжная обработка SSE с восстановлением курсора;
+- идемпотентная отправка сообщений;
+- удобная событийная модель и команды в стиле современных bot-фреймворков;
+- расширяемая архитектура без смешивания bot token и пользовательской сессии;
+- безопасная работа с лимитами запросов, повторными попытками и секретами.
+
+## Установка для разработки
+
+Требуется Python 3.11 или новее.
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+python -m pip install -e '.[dev]'
+```
+
+Примеры автоматически читают локальный `.env` из корня репозитория. В нём
+достаточно указать `VOICEROUTE_BOT_TOKEN`; production используется по умолчанию.
+
+Полноценный демонстрационный пример: [Community Assistant Bot](examples/community_assistant/README.md).
+
+## Минимальный бот
+
+```python
+import os
+
+from voiceroute import Bot, Context, FileCursorStore
+
+bot = Bot(
+    token=os.environ["VOICEROUTE_BOT_TOKEN"],
+    cursor_store=FileCursorStore(".voiceroute/cursors.json"),
+)
+
+
+@bot.command()
+async def ping(context: Context) -> None:
+    await context.reply("Pong!")
+
+
+bot.run()
+```
+
+Ответ использует стабильный UUID, производный от исходного сообщения. Повторная
+доставка SSE-события поэтому не создаст дубликат ответа.
+
+По умолчанию команды принимают оба привычных префикса: `/ping` и `!ping`.
+Собственный префикс задаётся через `Bot(..., command_prefix="?")`.
+
+Команды поддерживают aliases, группы и типизированные позиционные аргументы. Метаданные и
+вызов не зависят от prefix transport, поэтому будущие server-native interactions можно
+будет подключить отдельным адаптером. Подробнее: [командный фреймворк](docs/commands.md).
+
+Команды и listeners больших ботов можно объединять в расширения с атомарной загрузкой,
+выгрузкой и reload. Подробнее: [расширения](docs/extensions.md).
+
+Runtime поддерживает явные состояния, graceful shutdown и изоляцию channel consumers с
+ограниченным backoff. Подробнее: [жизненный цикл runtime](docs/runtime.md).
+
+Клиент умеет редактировать и удалять сообщения, управлять закреплением и реакцией,
+читать pins и выполнять поиск. Подробнее: [контентный API](docs/content-api.md).
+
+По умолчанию бот обнаруживает все доступные ему сообщества и текстовые каналы.
+Для ограничения одним каналом можно явно передать `community_id` и `channel_id`.
+При первом подключении он запрашивает историю после `seq=0`, чтобы не пропустить
+команды, отправленные незадолго до запуска. Идемпотентные ответы защищают от
+дубликатов при повторном получении тех же сообщений.
+
+`FileCursorStore` атомарно сохраняет обработанную позицию с правами `0600`.
+Cursor обновляется только после успешного завершения обработчика, поэтому после
+сбоя событие будет доставлено повторно. Для нескольких процессов доступны SQLite и
+Redis. Подробнее: [события и восстановление](docs/events.md).
+
+Все HTTP-операции одного клиента используют общий лимитер 50 запросов в секунду.
+Безопасные запросы и идемпотентная отправка сообщений повторяются после временных
+сетевых ошибок; `429` соблюдает `Retry-After`. Подробнее: [сеть и повторы](docs/network.md).
+
+## Состояние реализации
+
+| Возможность | Состояние |
+| --- | --- |
+| Bot-аутентификация | Основа готова |
+| Профиль текущего бота | Основа готова |
+| Сообщества и каналы | Базовое чтение готово |
+| Сообщения | История, отправка и изменение готовы |
+| Реакции, закрепления и поиск | Основа готова |
+| SSE и восстановление курсора | Основа готова |
+| Prefix-команды | Основа готова |
+| Middleware | Основа готова |
+| Треды и вложения | Запланировано |
+| Роли и модерация | Запланировано |
+| Голос для сторонних ботов | Не поддерживается API [VoiceRoute](https://voiceroute.cc) |
+
+Подробная последовательность работ находится в [дорожной карте](docs/roadmap.md),
+текущее покрытие — в [матрице API](docs/api-coverage.md), а принятые границы проекта —
+в [описании архитектуры](docs/architecture.md).
+
+## Разработка
+
+```bash
+ruff check .
+ruff format --check .
+mypy src
+pytest --cov=voiceroute --cov-report=term-missing
+```
+
+Правила веток, коммитов и слияний описаны в [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## Безопасность
+
+Не добавляйте bot token в исходный код, URL, query-параметры или логи. Используйте
+переменные окружения и передавайте токен только через официальный заголовок
+авторизации. Инструкции по сообщению об уязвимостях находятся в
+[SECURITY.md](SECURITY.md).
+
+## Лицензия
+
+[MIT](LICENSE)
+

voiceroute_py-0.1.0.dev0/SECURITY.md

@@ -0,0 +1,11 @@
+# Политика безопасности
+
+Не публикуйте сведения об уязвимости в открытом issue до согласования исправления.
+Свяжитесь с владельцем репозитория через приватный канал GitHub.
+
+Никогда не прикладывайте к отчёту действующие bot token, cookie, пароль,
+recovery code или полный секретный URL вебхука. Перед отправкой логов удалите из
+них все секреты.
+
+Поддерживаемые версии будут перечислены здесь после первого стабильного релиза.
+

voiceroute_py-0.1.0.dev0/docs/api-coverage.md

@@ -0,0 +1,34 @@
+# Покрытие API VoiceRoute
+
+Покрытие кода тестами и покрытие API — разные метрики. Процент из `pytest-cov`
+показывает, сколько веток Python-кода выполнили тесты. Эта матрица показывает, какие
+bot-compatible ресурсы [VoiceRoute](https://voiceroute.cc) представлены публичным API
+библиотеки.
+
+В знаменатель не входят пользовательские сессии, пароль, MFA, друзья, личные и
+групповые чаты, управление bot applications/installations и создание сообщества: по
+предоставленному контракту bot token получает для них `403`. Голос также не считается
+реализуемым ресурсом, пока сервер не выдаёт сторонним ботам WebRTC token.
+
+| Домен | Реализовано | Контрактные тесты | Статус |
+| --- | --- | --- | --- |
+| Текущий бот | профиль и совместимый `/auth/me` | частично | базовый |
+| Сообщества | список, одно сообщество | да | базовый |
+| Каналы | список доступных каналов | да | базовый |
+| События | channel SSE, catch-up, checkpoint | да | готово |
+| Сообщения | история, отправка, edit, delete | да | готово |
+| Контент сообщений | pins, reactions, search | да | готово |
+| Вложения | — | — | следующий домен |
+| Треды и форумы | — | — | следующий домен |
+| Участники, роли, permissions | — | — | запланировано |
+| Баны, timeout, AutoMod, audit | — | — | запланировано |
+| Categories и управление channels | — | — | запланировано |
+| Expressions, sounds, soundboard | — | — | запланировано |
+| Webhooks | — | — | запланировано |
+| Stage и music | — | — | требует отдельного контракта |
+
+Матрица ведётся по доменам, а не одним вводящим в заблуждение процентом. Некоторые
+маршруты в реестре являются alias одного обработчика, а отдельные маршруты формально
+находятся под `/api/communities/:id/...`, но требуют внешнего сервиса или недоступного
+ботам транспорта. Числовой процент появится после машиночитаемого OpenAPI со
+стабильными operation ID и признаками bot compatibility.

voiceroute_py-0.1.0.dev0/docs/architecture.md

@@ -0,0 +1,80 @@
+# Архитектура
+
+Библиотека строится слоями и не связывает пользовательский API с деталями сети.
+
+```text
+Bot framework
+    -> Resource APIs
+        -> HTTP and SSE transports
+            -> VoiceRoute API
+```
+
+## Transport
+
+Transport отвечает за авторизацию, URL, JSON, таймауты, rate limits, retries и
+преобразование HTTP-ошибок. Он не содержит бизнес-объектов и команд.
+
+Один `VoiceRouteClient` разделяет sliding-window limiter между resource API и
+открытием SSE. Retry разрешён по умолчанию только безопасным HTTP-методам.
+Изменяющая операция обязана явно подтвердить идемпотентность; отправка сообщения
+делает это благодаря стабильному `clientMessageId`.
+
+## Resource API
+
+Модули `api` группируют endpoint-ы по предметной области. Сырые ответы
+преобразуются в типизированные DTO из `models`.
+
+## Events
+
+Runtime получает события через протокол `EventTransport` и не зависит от сетевого
+формата. Текущий `LegacySSETransport` объединяет постраничное восстановление истории и
+канальный SSE в поток `EventDelivery`. Каждая доставка содержит нормализованное событие,
+источник и checkpoint, который runtime сохраняет только после успешной обработки.
+
+Пользовательский transport можно передать через `Bot(..., event_transport=...)`. Это
+позволяет тестировать runtime без сети и позже добавить Gateway-адаптер без изменения
+команд и обработчиков бота.
+
+SSE-потоки используют отдельные курсоры. События сообщений применяются как
+upsert, пока серверный контракт не позволяет достоверно различить создание и
+изменение без локального состояния.
+
+Runtime сохраняет составной checkpoint: `message_seq` закрывает начальную выдачу,
+у которой ещё нет SSE ID, а `change_cursor` восстанавливает поток изменений.
+Checkpoint фиксируется только после успешной обработки события. Хранилище
+задаётся через протокол `CursorStore`; встроены process-local и атомарный файловый
+адаптеры. Файловый адаптер предназначен для одного процесса.
+
+## Commands
+
+Команды являются клиентской абстракцией поверх обычных сообщений. Библиотека не
+имитирует отсутствующие на сервере interactions, intents или gateway.
+
+`CommandRegistry` хранит метаданные, aliases и многоуровневые пути, а `Command` отвечает
+за типизированное преобразование аргументов и вызов callback. `PrefixCommandAdapter`
+только преобразует текст сообщения в независимый `CommandInvocation`. Будущий adapter
+interactions сможет использовать тот же registry и pipeline.
+
+`CommandPipeline` последовательно выполняет checks, cooldown, concurrency gate и
+middleware. Состояние встроенных ограничителей локально процессу; распределённые
+адаптеры хранения будут добавлены отдельно и не должны менять публичные декораторы.
+
+## Extensions
+
+`Extension` группирует bound commands и event listeners. Подключение атомарно: конфликт
+регистрации откатывает уже добавленные handlers и вызывает teardown. Модульная загрузка
+требует `async setup(bot) -> Extension`; unload удаляет exact handlers экземпляра, а reload
+восстанавливает предыдущий экземпляр при ошибке новой версии.
+
+## Границы безопасности
+
+Runtime-клиент принимает только bot token. Управление приложениями через cookie,
+пароль и MFA не входит в него и при необходимости будет реализовано отдельно.
+
+## Runtime lifecycle
+
+`Bot` имеет явные состояния от `CREATED` до `CLOSED`. Channel consumers изолированы
+supervisor-ами: необработанная ошибка одного канала запускает bounded backoff и чтение с
+последнего подтверждённого checkpoint, не отменяя остальные каналы. `stop()` сериализует
+конкурирующие остановки, отменяет consumers и освобождает extensions и HTTP transport.
+