transcriber/openspec/changes/archive/2026-08-13-start-without-telegram-token/design.md

Context

Сегодня старт роняет отсутствующий токен бота: сборка отправителя ответов возвращает «токен не задан», и процесс заканчивается раньше, чем встаёт HTTP-сервер. Соседний путь того же старта — сборка транспорта бота — тот же отказ уже терпит и сервис не роняет. Два пути одного старта решают одно и то же по-разному, и побеждает тот, что стоит выше.

Ограничение, из-за которого это дорого: боевым токеном запускаться запрещено, а другого действующего токена у разработчика нет. Значит, живой прогон недоступен никому, и всякая задача проверяется одними тестами.

Отправитель ответов уходит в ядро расшифровки обязательной зависимостью, и ядро зовёт его без проверки. Убрать отправителя, ничего не решив, — значит уронить процесс на первой же задаче из Telegram, лежащей в базе с прошлого запуска.

Goals / Non-Goals

Goals:

• сервис поднимается без токена бота и работает оставшимся входом;
• отсутствие бота видно в журнале, а не выводится читателем из тишины;
• задача из Telegram, которой некому ответить, не роняет процесс и не теряется молча;
• ошибка в токене остаётся заметной.

Non-Goals:

• приём из Telegram по существу — кто допущен, как забирается запись — не нормируется; оговорка спеки intake остаётся;
• запрет запускаться боевым токеном не снимается и не смягчается;
• второй вход не становится необязательным «вообще»: сервис без обоих входов бессмыслен, но проверять это изменение не берётся;
• отправка отложенных ответов, когда бот появится позже, не заводится.

Decisions

Решение 1: пустой токен — отказ от входа, негодный непустой — ошибка настройки

Разрез проходит по пустому значению, а не по отказу сборки бота.

Что человек увидит иначе: разработчик стирает токен в своём файле настроек и поднимает сервис; владелец сервиса, опечатавшийся в токене при ротации, получает отказ старта вместо сервиса, молча работающего без бота.

Правка после ревью кода, решение владельца 2026-08-13. Разрез перенесён с «пусто / непусто» на «ответил ли Telegram»: недоступность Telegram на подъём сервиса не влияет. Довод — тот же, что у паспорта: основной вход не Telegram, и класть его целиком из-за чужой аварии нельзя. Ровно этого и требовал прежний разрез: перезапуск в минуту аварии Bot API оставил бы без работы приём по HTTP, панель и конвейер, которому Telegram не нужен вовсе.

Отдельно снят довод, оказавшийся ложным. Дизайн утверждал, что «Telegram не признал бота» и «до Telegram не дошли» различать нечем. Различать есть чем: ответ Bot API приезжает своим типом с кодом, транспортный отказ — нашим после чистки, и одно от другого отделяется проверкой типа. Утверждение держалось на незнании библиотеки, а не на её устройстве.

Из решения следует второе, без которого оно невыполнимо: ожидание при сборке ограничивается сроком. Пока срока не было, недоступность не отличалась от подъёма — молчащий Telegram вешал старт бессрочно, без записи, без порта и без пробы здоровья. Срок стоит только на сборке; длинный опрос им не ограничен, и клиент подменяется сразу после.

Рассмотрено и отвергнуто:

• терпеть любой отказ сборки бота — отвергнуто: опечатка в боевом токене дала бы работающий сервис без бота, и отправители перестали бы получать ответы. Ответ «такого бота нет» опознаётся точно, ждать по нему нечего, и он остаётся единственным отказом старта;
• ронять старт на любом отказе — отвергнуто владельцем: авария третьей стороны не должна класть основной вход;
• отдельный ключ настройки «работать без Telegram» — явное объявление намерения. Отвергнуто: имя ключа конфига объявлено необратимым, а пустое значение уже несёт ровно этот смысл. Второй способ сказать одно и то же разъезжается — останется решить, что делать с пустым токеном при выключенном ключе.

Разрез стоит в одном месте, потому что клиент бота собирается один раз. Сегодня его собирают дважды — под отправителя ответов и под транспорт бота, — и именно поэтому два пути разошлись. Вместо того чтобы согласовывать их вручную, изменение сводит сборку к одной: клиент заводится в сборке при старте и отдаётся обоим. Транспорт уже принимает готового клиента, так что менять надо только отправителя — он перестаёт принимать токен и начинает принимать клиента.

Что это даёт сверх опрятности: разрез «пусто / непусто» существует ровно один, запись о неподнятом боте по построению одна, обращение к Telegram при старте одно вместо двух, и подмена журнала библиотеки тоже одна. Проверять «согласованы ли два пути» больше не надо — второго пути нет.

Цена решения: сборка бота перестаёт терпеть негодный токен и начинает ронять старт. Наблюдаемо это почти ничего не меняет: сборка отправителя роняет старт на том же токене и сегодня, а стоит она раньше — до терпимости транспорта очередь попросту не доходит.

Решение 2: заглушка отвечает «канала нет», а запись делает шаг

Когда токена нет, ядро получает отправителя-заглушку. Она ничего не отправляет и на всякий ответ возвращает особое значение отказа — «канал доставки не поднят». Шаг конвейера узнаёт это значение, пишет недоставку в журнал с идентификатором задачи и завершается без отказа.

Что человек увидит иначе: владелец сервиса находит в журнале строку «ответ не доставлен» с идентификатором задачи и забирает расшифровку там же, где лежат остальные.

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

Почему это не заводит в ядре ветки «а есть ли бот»: ядро ветвится не на устройстве сборки, а на исходе доставки — ровно так же, как оно уже ветвится на «работы нет» и «захват потерян». Особое значение отказа живёт там же, где эти два, и узнаётся тем же способом. Знания о том, как собран сервис, у ядра не появляется.

Источник задачи ядро при этом уже различает: ответ отправителю начинается с проверки источника и на задаче, пришедшей по HTTP, кончается раньше обращения к отправителю. Заглушка задач основного входа не увидит, и ложных строк о недоставке в журнале не будет.

Рассмотрено и отвергнуто:

• ронять задачу в failed — отвергнуто: расшифровка к этому моменту уже получена и сохранена, а «не удалось» сообщить всё равно некому. Пометка отказа на удавшейся работе врёт и панели, и метрике;
• оставлять задачу пригодной к повтору — отвергнуто: смысл повтора в том, чтобы работа однажды удалась, а недоставка сама не пройдёт — бот не появится оттого, что задачу подождали;
• немая заглушка, возвращающая успех — отвергнуто находкой ревью дизайна: недоставку тогда некому записать, и норма «принятая запись не теряется молча» оказывается нарушена именно тем решением, которое её и обслуживало;
• отпустить отказ заглушки наверх, не разбирая — отвергнуто: шаг объявил бы отказ там, где работа сделана. Задачу это в повтор не отправит — воркеры опрашивают только незавершённые состояния, — но воркеру засчитается сбой, которого не было, и владельцу уедет запись отказа. Соврала бы и метрика, и журнал.

Решение 3: заглушка живёт рядом с настоящим отправителем

Место — тот же пакет, что и отправитель Telegram: заглушка знает ровно то же, что и он, и подставляется в сборке при старте, как и все прочие адаптеры. Направление зависимостей это не нарушает, и тесты-сканеры остаются зелёными. Само значение отказа живёт среди контрактов — там же, где «работы нет» и «захват потерян»: узнаёт его ядро, а порождает адаптер, и ни один из них не зависит от другого.

Форма значения — сентинел, а не тип с полями. Соседи по ряду несут поле (состояние, идентификатор задачи) и потому объявлены типами; этому нести нечего — заглушка не знает ни задачи, ни чата. Прецедент сентинела в проекте есть: им же объявлено «токен не задан».

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

Решение 4: живой прогон требует заполнить ещё две секции, и это говорится вслух

Пустого токена мало. Настройки входа проверяются на старте и роняют процесс, называя незаполненные ключи; конструкторы Yandex так же роняют его на пустых регионе, ключах Object Storage, ключе SpeechKit и папке. Ни один из них при старте наружу не ходит, поэтому выдуманных непустых значений достаточно — живой прогон получается, а денег не стоит.

Этой задачей разрез «пустое значение — отказ от возможности» на другие секции не переносится: распознавание без Yandex не работает по существу, и отказ от него — отдельное решение с отдельной ценой. Здесь только называется, что заполнить, чтобы сервис поднялся.

Отсюда же граница правки документов: строка «живой прогон недоступен» не снимается, а сужается с остатком — стал доступен подъём и осмотр, а прогон с по-настоящему пустыми ключами Yandex по-прежнему невозможен.

Risks / Trade-offs

• Сервис молча работает без бота, потому что токен забыли стереть или забыли вписать → строка журнала при старте называет это прямо, а не оставляет читателю вывод из тишины. Дальше — дело того, кто выкладывает;
• Отказ старта на негодном токене останавливает выкладку, которая прежде проходила → это и есть цель решения 1; чинится правкой настройки, и отказ называет, какой ключ виноват, не называя значения;
• Сборка бота ходит в Telegram, и без сети старт с непустым токеном упадёт → поведение не новое и не ухудшается. Сегодня сборка отправителя зовётся первой и роняет старт на любом отказе, так что терпимость соседнего пути на негодном токене всё равно не срабатывает: до неё не доходит очередь. Изменение делает два пути согласованными и снимает сеть с законного пути — пустой токен не ходит наружу вовсе. Срока ожидания у обращения к Telegram при этом нет, и задача его не заводит: таймауты у трёх внешних собеседников — известный недостаток проекта и предмет отдельной работы;
• Недоставленный ответ пропадает навсегда → отложенной доставки нет и не заводится: расшифровка лежит в хранилище и достаётся через панель и HTTP API;
• Остановка идёт по пути, которым прежде не ходили → останов зеркален сборке: чего не собрали, того не закрывают и не ждут. Проверяется прогоном сигнала остановки на конфиге с пустым токеном.

Migration Plan

Схемы хранилища изменение не трогает, миграции нет, откат — обычный откат образа. Выкладка с заполненным токеном ведёт себя ровно как прежде.

Open Questions

Нет.