transcriber/openspec/specs/recognition/spec.md

# recognition Specification

## Purpose

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

Движение записи по рубежам нормирует `pipeline`, хранение текста и структуры —
`storage`, закрытость содержимого — `storage` же.

Сознательно не описан формат ответа конкретного провайдера: он живёт в адаптере
и в записках разведки, а не в норме поведения.
## Requirements

### Requirement: Попытка распознавания хранится отдельно от записи

Сервис SHALL держать всё, что принадлежит внешнему распознавателю, отдельной
строкой, связанной с аудиозаписью, и MUST не хранить это колонками самой записи.
К попытке относятся имя провайдера, имя модели, идентификатор операции у
провайдера, адрес, по которому провайдер читал аудио, время начала и время
завершения.

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

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

#### Scenario: Идентификатор операции лежит в попытке

- **GIVEN** запись отправлена на распознавание
- **WHEN** смотрят, где лежит идентификатор операции у провайдера
- **THEN** он лежит в строке попытки распознавания
- **AND** колонки с ним у самой записи нет

#### Scenario: Копия во внешнем хранилище не подменяет файл записи

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

### Requirement: Сырой ответ провайдера сохраняется целиком

Сервис SHALL сохранять ответ распознавателя целиком, в том виде, в каком он
пришёл, и MUST хранить его **отдельным файлом в каталоге данных**, а не колонкой
строки попытки.

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

Файлом, а не колонкой, — потому что шаг опроса читает строку попытки часто, а
репозиторий читает строку целиком: ответ на многочасовую запись, положенный
колонкой, ехал бы в память при каждом опросе. Где именно этот файл лежит,
нормирует capability `storage`, требование «Файл записи живёт в хранилище»:
третьим файлом в подкаталоге записи, наравне с копиями аудио. Копией аудио он при
этом не считается — их у записи по-прежнему две.

Чтение строки попытки шагом опроса MUST не тянуть за собой сохранённый ответ.

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

Путь к файлу сохранённого ответа MUST не попадать ни в журнал, ни в метку
метрики, ни в ответ отправителю.

Норму держит capability `storage`, требование «Содержимое записи закрыто везде,
где лежит»; здесь она названа потому, что попытка распознавания — то место, куда
содержимое приезжает впервые.

#### Scenario: Ответ сохранён и читается позже

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

#### Scenario: Опрос не тянет сохранённый ответ

- **GIVEN** у попытки распознавания есть сохранённый ответ
- **WHEN** шаг опроса читает строку попытки
- **THEN** сохранённый ответ в память при этом не читается

#### Scenario: Адреса чтения сохранённого ответа у сервиса нет

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

### Requirement: Структура реплик строится из сохранённого ответа

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

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

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

#### Scenario: Структура собрана без обращения к провайдеру

- **GIVEN** ответ провайдера сохранён
- **WHEN** сервис строит структуру реплик
- **THEN** структура собрана с временем каждой реплики
- **AND** к провайдеру не уходит ни одного обращения

### Requirement: Разбор формата провайдера не выходит за адаптер

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

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

#### Scenario: Шаг получает реплики, а не поток провайдера

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

### Requirement: Заливка и отправка на распознавание разделены

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

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

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

#### Scenario: Объект уже лежит, а операции ещё нет

- **GIVEN** аудио уже уложено туда, откуда провайдер его читает, и размер совпадает
- **AND** идентификатора операции в строке попытки нет
- **WHEN** шаг повторяется
- **THEN** укладка не повторяется
- **AND** операция отправляется

#### Scenario: Операция уже заведена

- **GIVEN** в строке попытки есть идентификатор операции
- **WHEN** шаг повторяется
- **THEN** отправка не повторяется
- **AND** шаг переходит к опросу этой операции

#### Scenario: Операция принята, а сервис мягко останавливают

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