transcriber/openspec/specs/pipeline/spec.md

pipeline Specification

Purpose

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

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

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

Requirements

Requirement: Пустой прогон воркера — не отказ

Воркер SHALL отличать «пригодной к работе записи сейчас нет» от отказа шага. На пустом прогоне он MUST не считать прогон отказом: не увеличивать счётчик работы и не писать о нём на уровне владельца сервиса. Признак пустого прогона MUST узнаваться по смыслу значения, а не по его точной форме, и MUST переживать пояснения, добавленные к этому значению на любом промежуточном шаге пути.

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

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

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

Отказ шага, наоборот, MUST быть виден владельцу сервиса записью в журнале и MUST быть засчитан в счётчик работы с пометкой отказа и с меткой рубежа.

Сколько раз он записывается и каким уровнем — это требование не нормирует, и умолчанием тут считать нечего. Сегодня один отказ даёт две записи: пишет шаг конвейера и следом воркер, — а уровень стоит ERROR там, где конвенция просит WARN для повторяющегося сбоя фонового цикла. И то и другое записано долгом в docs/conventions/logging.md, раздел «Ошибки», строкой «Расхождение, и оно системное». Долгом оно и остаётся: требование, объявившее одиночную запись нормой, сделало бы недостижимое обязательным, а требование, объявившее нормой двойную, — закрыло бы долг контрактом. Задача, которая возьмётся за этот долг, дописывает норму сюда.

Scenario: Пригодной к работе записи нет

• GIVEN ни одной записи, пригодной к работе, нет ни на одном рубеже
• WHEN воркер делает свой прогон
• THEN на уровне владельца сервиса об этом прогоне не пишется ничего
• AND счётчик работы воркера не растёт

Scenario: Признак пустого прогона дошёл с пояснением

• GIVEN пригодной к работе записи нет
• AND промежуточный шаг добавил к этому признаку своё пояснение
• WHEN воркер делает свой прогон
• THEN прогон по-прежнему считается пустым: счётчик не растёт, записи на уровне владельца нет

Scenario: Шаг отказал

• GIVEN шаг конвейера вернул отказ
• WHEN воркер завершает прогон
• THEN отказ виден владельцу сервиса записью в журнале
• AND счётчик работы воркера растёт с пометкой отказа и меткой рубежа

Scenario: Шаг сделал работу

• GIVEN шаг конвейера отработал запись без отказа
• WHEN воркер завершает прогон
• THEN счётчик работы воркера растёт с пометкой успеха
• AND записи об отказе в журнале нет

Requirement: Захват задачи неделим

Захват записи воркером SHALL быть одним неделимым шагом хранилища: выбор подходящей записи и пометка её захваченной MUST происходить вместе.

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

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

Одна и та же запись MUST доставаться ровно одному захватившему. Двум вызывающим, пришедшим за работой одновременно, запись MUST достаться одному, а второй MUST получить признак «работы сейчас нет».

Срок протухания захвата MUST ехать с рубежом записи, а не с воркером: воркер не привязан к шагу и не знает заранее, что вытянет. Срок MUST записываться числом при самом захвате.

Порядок выборки MUST быть определён однозначно: сравнения по неуникальному значению для этого мало, и к нему MUST добавляться ключ записи. Иначе порядок обработки невоспроизводим, а проверка, опирающаяся на «следующую» запись, зелена через раз.

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

Признак «работы нет» этим требованием не переопределяется — его нормирует требование «Пустой прогон воркера — не отказ».

Scenario: За работой пришли трое разом

• GIVEN к работе пригодна ровно одна запись
• WHEN три захвата идут одновременно
• THEN запись получает ровно один из них
• AND двое остальных получают признак «работы сейчас нет»

Scenario: Захваченная запись не выдаётся второй раз

• GIVEN запись захвачена и срок захвата не истёк
• WHEN приходит следующий захват
• THEN эта запись ему не выдаётся

Scenario: Захват отдаёт идентификатор и свой признак

• GIVEN к работе пригодна запись
• WHEN воркер её захватывает
• THEN захват возвращает идентификатор записи и признак этого захвата
• AND колонки записи шаг читает отдельным чтением

Scenario: Признак перевыданного захвата отличается от прежнего

• GIVEN запись захвачена, и признак первого захвата известен
• WHEN человек снимает признак остановки, и запись захватывает другой воркер
• THEN признак нового захвата отличается от признака первого

Requirement: Результат пишет только держатель захвата

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

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

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

Scenario: Правка владельца пережила сохранение шага

• GIVEN шаг держит захваченную запись
• AND владелец за это время изменил в панели поле, которого шаг не касается
• WHEN шаг записывает свой результат
• THEN результат шага записан
• AND правка владельца на месте

Scenario: Захват ушёл под работающим шагом

• GIVEN шаг работает над захваченной записью
• AND за это время та же запись досталась другому захвату
• WHEN первый шаг доходит до записи результата
• THEN результат не записывается
• AND отправителю ничего не отправляется

Scenario: Человек снял остановку под работающим шагом

• GIVEN шаг работает над захваченной записью
• AND человек за это время снял с неё признак остановки, освободив захват
• AND запись досталась другому воркеру
• WHEN первый шаг доходит до записи результата
• THEN результат не записывается

Requirement: Брошенная задача возвращается в работу

Запись, захваченная и брошенная на середине, SHALL доставаться снова по истечении срока захвата. Срок MUST считаться от времени захвата, а истёкший захват MUST не мешать выдать запись следующему.

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

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

Scenario: Захват протух

• GIVEN запись захвачена, а время захвата отстоит дальше срока
• WHEN приходит захват
• THEN запись выдаётся ему

Scenario: Срок сравнивается с временем, записанным хранилищем

• GIVEN запись захвачена, и время захвата записано в том же виде, в каком хранилище пишет время изменения записи
• WHEN приходит захват до истечения срока
• THEN запись ему не выдаётся

Scenario: Срок протухания приехал с рубежом

• GIVEN записи двух рубежей с разными сроками захвата пригодны к работе
• WHEN их захватывает один и тот же воркер
• THEN у каждой записан срок её рубежа

Requirement: Пауза перед повтором нарастает

Перед повтором отказавшей записи сервис SHALL выдерживать паузу, и пауза MUST расти с числом её отказов до объявленного потолка. Запись MUST не выдаваться захвату, пока пауза не кончилась.

Ожидание чужой операции этой паузой MUST не выражаться. Шаг, увидевший, что внешняя операция ещё идёт, отработал без отказа: он откладывает работу своей задержкой, заданной числом, и отказов при этом не тратит. Пауза, выведенная из числа отказов, на таком шаге вырождается в наименьшее своё значение и учащает опрос внешнего сервиса во столько раз, во сколько задержка опроса длиннее секунды.

Scenario: Отказавшая запись ждёт

• GIVEN запись отказала на шаге конвейера
• WHEN захват приходит раньше конца её паузы
• THEN запись ему не выдаётся

Scenario: Вторая пауза длиннее первой

• GIVEN запись отказала дважды подряд
• WHEN сравнивают паузу после второго отказа с паузой после первого
• THEN вторая длиннее

Scenario: Ожидание операции не учащается и не тратит отказов

• GIVEN внешняя операция распознавания ещё идёт
• WHEN шаг опроса отрабатывает подряд несколько раз
• THEN задержка до следующей проверки каждый раз одна и та же
• AND число отказов записи не растёт

Requirement: Недоставленный ответ не роняет шаг

Шаг конвейера SHALL доводить запись до достигнутого рубежа, когда ответ отправителю доставить не удалось, и MUST не считать недоставку отказом шага. Недоставка MUST быть записана в журнал владельца, MUST нести идентификатор записи, MUST называть причину и MUST считаться отдельной метрикой с причиной меткой.

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

Уровень записи MUST различать эти причины. Неподнятый вход — объявленный режим, и его уровень «может стать проблемой». Неназванный адресат — симптом порчи записи: у записи из Telegram чат есть всегда, и пропасть он может только от дефекта, самый коварный источник которого назван инвариантом проекта про колонки очереди. Один уровень на обе причины утопил бы этот сигнал в потоке штатных записей о ненастроенном боте.

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

То же MUST относиться к недоставке сообщения об остановке: остановка уже сохранена, и недоставка её MUST не отменять.

Идентификатор записи в этой строке обязателен: без него владелец видит, что ответ не ушёл, но не может найти, чей. Текст расшифровки и сообщение отправителя в эту запись MUST не попадать — приватность содержимого записи требование не ослабляет.

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

Scenario: Вход отправителя не поднят

• GIVEN запись принята входом Telegram прошлым запуском сервиса
• AND сервис поднялся без этого входа
• WHEN шаг конвейера доходит до ответа отправителю
• THEN шаг завершается без отказа, и воркер не считает прогон сбоем
• AND запись остаётся на достигнутом рубеже, в повтор не уходит и признака остановки не получает
• AND в журнале есть запись уровня WARN о недоставке с идентификатором записи и причиной
• AND счётчик недоставленных ответов вырос с этой причиной меткой
• AND ни текста расшифровки, ни сообщения отправителя в этой записи нет

Scenario: Адресат у записи не назван

• GIVEN у записи источником значится Telegram, а чат не назван
• WHEN шаг конвейера доходит до ответа отправителю
• THEN шаг завершается без отказа, и воркер не считает прогон сбоем
• AND запись остаётся на достигнутом рубеже
• AND в журнале есть запись уровня ERROR о недоставке с идентификатором записи и причиной: неназванный адресат — симптом порчи записи

Scenario: Не доехало сообщение об остановке

• GIVEN запись остановлена признаком
• AND вход отправителя не поднят
• WHEN шаг доходит до ответа отправителю
• THEN признак остановки у записи остаётся
• AND в журнале есть запись о недоставке с идентификатором записи и причиной

Scenario: Отвечать некуда, потому что запись пришла не из Telegram

• GIVEN запись принята по HTTP
• WHEN шаг конвейера доходит до ответа отправителю
• THEN шаг завершается без отказа и без записи о недоставке

Requirement: Выборка воркера владельцем не сужается

Воркер SHALL брать записи всех владельцев подряд и MUST не учитывать владельца при выборе очередной записи. Запись без владельца — принятая ботом — MUST обрабатываться наравне с прочими.

Владелец решает, кому запись показывать, а не кому её считать. Сужение выборки владельцем остановило бы расшифровку записей бота вовсе, а записи остальных поставило бы в зависимость от того, кто первым завёл учётную запись.

Владелец записи MUST переживать работу конвейера: шаг, сохраняющий свой результат, владельца не трогает и не затирает.

Scenario: Записи двух владельцев проходят одним воркером

• GIVEN заведены записи двух разных владельцев на одном рубеже
• WHEN воркер забирает работу
• THEN ему достаются обе, в порядке заведения

Scenario: Запись без владельца обрабатывается

• GIVEN заведена запись, принятая ботом, — без владельца
• WHEN воркер забирает работу
• THEN она достаётся ему наравне с прочими

Scenario: Шаг конвейера владельца не затирает

• GIVEN запись с владельцем прошла шаг конвейера
• WHEN шаг сохраняет свой результат
• THEN владелец записи остаётся прежним

Requirement: Рубеж записи называет достигнутое

Аудиозапись SHALL нести рубеж — состояние, называющее достигнутое, а не предстоящее. Цепочка рубежей: uploaded, normalized, submitted, transcribed, done. Какой шаг делать дальше, сервис MUST выбирать по рубежу одним общим местом, а не тем, какой воркер пришёл за записью.

Прежние состояния называли предстоящую работу (created, converted, transcribe), и потому по состоянию нельзя было сказать, что с записью уже сделано: продолжить с места остановки было не с чего.

Конечный рубеж MUST зваться done. Доставка ответа отправителю в конвейер не входит, и слово описывает пройденный конвейер, а не полученный человеком текст.

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

Записи на конечном рубеже MUST не браться в работу и MUST не подпадать под предел времени в рубеже: done не ждёт работы, и стоять в нём запись будет вечно по построению.

Scenario: Рубеж называет сделанное

• GIVEN запись прошла приведение к рабочему формату
• WHEN смотрят её рубеж
• THEN он называет приведение сделанным, а не предстоящим

Scenario: Следующий шаг выбирается по рубежу

• GIVEN запись стоит на рубеже приведения
• WHEN её берёт воркер
• THEN идёт отправка на распознавание, а не повторное приведение

Scenario: Запись на конечном рубеже не берут и не останавливают

• GIVEN запись стоит на конечном рубеже дольше любого предела
• WHEN приходит захват
• THEN запись ему не выдаётся
• AND признака остановки у неё не появляется

Requirement: Остановка записи — признак, а не рубеж

Сервис SHALL останавливать запись отдельным признаком с причиной и MUST не стирать при этом достигнутый рубеж. Признак MUST нести время остановки, причину и машинный текст отказа.

Снятие признака SHALL возвращать запись в работу с того рубежа, где она стояла, и MUST сбрасывать число отказов, паузу и время входа в рубеж. Время входа сбрасывается по той же причине, что и остальные сторожа: запись, простоявшая остановленной дольше предела, иначе останавливалась бы снова первым же захватом, и перезапуск не работал бы вовсе.

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

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

Остановку MUST ставить тот, кто запись захватил. Перевод принадлежит одному месту: условие отбора, молча пропускающее запись мимо выборки, оставило бы её без следа.

Остановленная запись MUST не выдаваться захвату.

Scenario: Остановленная запись продолжает с места остановки

• GIVEN шаг остановил запись на рубеже приведения
• WHEN признак остановки снимают
• THEN следующим идёт отправка на распознавание, а не повторное приведение

Scenario: Остановленная запись не выдаётся захвату

• GIVEN у записи стоит признак остановки
• WHEN за её рубежом приходит захват
• THEN запись ему не выдаётся

Scenario: Снятие признака сбрасывает всех сторожей

• GIVEN запись остановлена с накопленными отказами и паузой
• AND остановленной она простояла дольше предела времени в рубеже
• WHEN признак остановки снимают
• THEN число отказов, пауза и время входа в рубеж сброшены
• AND ближайший захват выдаёт запись, а не останавливает её снова

Requirement: Всякая остановка сообщает отправителю

Остановка записи по любой причине SHALL сообщать отправителю о неудаче ровно так же, как сообщает о ней отказ шага, и MUST быть видна владельцу сервиса записью в журнале.

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

Причин остановки больше одной, и обязанность общая для всех: исчерпанные отказы, застревание в рубеже, приговор шага. Обязанность, записанная у одной причины, у остальных читалась бы как снятая.

Ответ уходит после того, как признак остановки сохранён, и недоставка этого ответа MUST не отменять остановку: её нормирует требование «Недоставленный ответ не роняет шаг».

Scenario: Остановка по отказам сообщает отправителю

• GIVEN запись остановлена по исчерпании отказов
• WHEN шаг доходит до ответа отправителю
• THEN отправитель получает сообщение о неудаче

Scenario: Остановка по времени сообщает отправителю

• GIVEN запись остановлена по пределу времени в рубеже
• WHEN шаг доходит до ответа отправителю
• THEN отправитель получает сообщение о неудаче
• AND в журнале владельца есть запись об остановке с причиной

Requirement: Время в рубеже ограничено

У аудиозаписи SHALL быть время входа в рубеж, и оно MUST ставиться только при смене рубежа и при возврате записи в работу. Запись, простоявшая в рубеже дольше предела, MUST останавливаться признаком с причиной «застряла».

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

Сторож этот ловит зависание, а не долгую работу, и час у своей работы меньше времени, которое многочасовая запись занимает на приведении. Цена решения названа прямо: длинная запись, отказавшая один раз и ждущая повтора дольше часа, будет остановлена как застрявшая. Цена ограничена тем, что остановка обратима — снятие признака возвращает запись на её рубеж, — и тем, что живой шаг проверяется по самому процессу. Решение владельца 2026-08-14.

Откладывание опроса MUST не двигать время входа в рубеж и MUST не сдвигать этот предел. Иначе запись, чью чужую операцию опрашивают раз в несколько секунд, никогда не достигнет предела, и застревание останется незамеченным.

Остановка по этому пределу MUST ничего не терять: идентификатор чужой операции остаётся в строке попытки распознавания, и снятие признака возобновляет опрос той же операции, а не заводит вторую.

Scenario: Сотня откладываний не двигает отсчёт

• GIVEN запись стоит на рубеже отправки, и чужая операция ещё идёт
• WHEN опрос откладывается сотню раз подряд
• THEN время входа в рубеж не изменилось
• AND отсчёт до предела не обнулился

Scenario: Предел достигнут

• GIVEN запись простояла в рубеже дольше своего предела
• WHEN за ней приходит захват
• THEN запись получает признак остановки с причиной «застряла»

Scenario: Возобновление опроса не заводит вторую операцию

• GIVEN запись остановлена по пределу на рубеже отправки
• WHEN признак остановки снимают
• THEN опрос идёт по прежнему идентификатору операции
• AND новая операция у провайдера не заводится

Requirement: Откладывание не является переходом

Сервис SHALL различать переход на новый рубеж и откладывание работы над записью. Откладывание MUST ставить паузу и снимать захват, MUST не трогать ни рубеж, ни время входа в него, и MUST не считаться отказом: ожидание чужой операции отказом не является, поэтому число отказов оно MUST обнулять.

Сегодня шаг опроса зовёт переход с тем же состоянием, и мнимость этого перехода обнуляет счётчик. Без разделения время входа в рубеж сбрасывалось бы на каждом опросе и повторило бы ровно тот промах, ради которого заводится.

Scenario: Откладывание не двигает рубеж

• GIVEN шаг опроса увидел, что чужая операция ещё идёт
• WHEN он откладывает работу
• THEN рубеж записи прежний, и время входа в него прежнее
• AND захват с записи снят, а пауза поставлена

Requirement: Шаг с внешней оплатой проверяет сделанное

Шаг, чьё повторение оплачивается наружу, SHALL проверять, не сделана ли работа уже, и MUST не делать её второй раз. Проверка MUST идти по наблюдаемому признаку присутствия результата, а не по сверке содержимого хешем: у составного объекта во внешнем хранилище признак целостности не равен отпечатку содержимого.

Признак MUST записываться прежде, чем оплачиваемое обращение считается состоявшимся: строка попытки распознавания заводится до обращения к провайдеру, и повторный шаг начинает с проверки, не заведена ли операция.

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

Scenario: Работа уже сделана

• GIVEN результат оплачиваемого шага уже на месте, и признак его записан
• WHEN шаг повторяется
• THEN внешнее обращение не повторяется

Requirement: Число воркеров задаётся настройкой

Сервис SHALL брать число рабочих потоков конвейера из настроек, а сами потоки MUST не быть привязаны к отдельному шагу: каждый берёт любую подходящую запись и выбирает шаг по её рубежу. Поведение записи MUST не зависеть от числа потоков.

Ноль MUST быть законным значением: сервис поднимается, записи принимаются и не двигаются. Это режим, а не поломка.

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

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

Scenario: Запись доходит при одном потоке и при нескольких

• GIVEN число потоков конвейера равно одному
• WHEN запись проходит конвейер
• THEN она доходит до конечного рубежа
• AND при числе потоков больше одного исход тот же

Scenario: Потоков нет вовсе

• GIVEN число потоков конвейера равно нулю
• WHEN запись принимают
• THEN сервис принимает её и не теряет
• AND запись остаётся на первом рубеже

Scenario: Отказ виден с разрезом по шагу

• GIVEN шаг приведения отказал
• WHEN наблюдатель читает счётчик работы воркера
• THEN отказ засчитан с меткой рубежа приведения

Requirement: Журнал событий записи пишется на смену рубежа

Сервис SHALL вести журнал событий аудиозаписи и MUST писать в него строку на смену рубежа, на остановку и на снятие остановки. Строка MUST называть источник события — шаг конвейера или человека, — сам шаг, исход и длительность.

Журнал MUST не писаться на каждое откладывание опроса: часовая запись дала бы сотни строк ни о чём.

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

Содержимое записи в журнал событий MUST не попадать — инвариант приватности действует здесь наравне с журналом сервиса.

Scenario: Смена рубежа записана

• GIVEN шаг конвейера довёл запись до нового рубежа
• WHEN смотрят журнал событий этой записи
• THEN в нём есть строка с шагом, исходом и длительностью

Scenario: Откладывание строки не пишет

• GIVEN опрос чужой операции откладывается многократно
• WHEN смотрят журнал событий записи
• THEN строк об откладываниях в нём нет

Scenario: Перезапуск человеком виден в журнале

• GIVEN запись остановлена признаком
• WHEN человек снимает признак
• THEN в журнале событий есть строка с указанием, что это сделал человек

Requirement: Число отказов ограничивает повторы шага

У аудиозаписи SHALL быть число отказов. Оно MUST расти при каждом захвате и MUST возвращаться к нулю, когда шаг завершился без отказа либо отложил работу. Рост при захвате, а не при отказе, засчитывает попытку и записи, брошенной на середине: шаг, уносящий с собой процесс, до объявления отказа не доходит никогда.

Остановка сервиса отказом не считается. Шаг, прерванный отменой по собственной остановке сервиса, MUST возвращать число отказов назад и MUST не выносить записи приговора: запись не виновата в том, что нас перезапустили, и несколько выкладок подряд иначе останавливают здоровую многочасовую запись с приговором «отказы исчерпаны». Всякая другая причина, по которой шаг не дошёл до объявления исхода, отказ тратит.

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

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

Scenario: Запись отказывает на каждой попытке

• GIVEN шаг конвейера отказывает на каждой попытке
• WHEN запись проходит заданное число отказов
• THEN у неё появляется признак остановки
• AND следующий захват её не выдаёт
• AND отправитель получает сообщение о неудаче

Scenario: Шаг уносит процесс, не объявив отказа

• GIVEN шаг конвейера обрывается вместе с процессом на каждой попытке
• WHEN запись захватывается снова заданное число раз
• THEN у неё появляется признак остановки

Scenario: Остановка сервиса отказа не тратит

• GIVEN шаг работает над записью
• WHEN сервис останавливают, и шаг прерывается отменой
• THEN число отказов записи прежнее
• AND признака остановки у записи не появляется

Scenario: Прошедшая запись отказов не копит

• GIVEN запись прошла подряд несколько рубежей без единого отказа
• WHEN смотрят её число отказов
• THEN оно не приблизилось к пределу