transcriber/tasks/items/record-centric-model.md

# ✨ Перестроить внутреннюю модель вокруг аудиозаписи

- **Тип:** feature
- **Категория:** Очередь — Модель — основание: поверх неё строятся экраны, уровни текста, учёт и метрики, и всякая задача, взятая раньше, будет переписана вместе с моделью. Решение владельца 2026-08-14.
- **Зачем:** Задача очереди и запись — одна строка: поля захвата лежат рядом с расшифровкой, указатель на файл переставляет каждый шаг, а перевод в failed стирает рубеж и делает перезапуск невозможным.

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

Замысел выработан в разговоре 2026-08-14, там же разобраны четыре развилки:
где живут темы, дробить ли задачу, как зовётся конечный рубеж и чем
ограничивается застревание. Ниже — принятые решения целиком; открытых вопросов
не осталось.

**Задача делается одним заходом и не дробится** — решение владельца 2026-08-14.
Швы у неё есть (сущности со схемой, цепочка рубежей, провайдерская таблица,
обобщение пула), но резать по ним значит платить четырьмя необратимыми шагами
схемы вместо одного и держать на сервере промежуточные раскладки. Один заход —
один шаг схемы и один перенос живых записей.

## Сущности

Разрез проведён по одной границе: **зависит ли вещь от провайдера
распознавания**.

```
audiorecords                             ← домен
  id, owner, title, brief
  state, state_entered_at                  рубеж конвейера
  halted_at, halt_reason, error_text       остановка
  acquisition_id, acquire_expires_at,      очередь
    delay_time, attempts
  original_file_id ────▶ files
  normalized_file_id ──▶ files
  structure_id ────────▶ structures
  transcript_text_id ──▶ texts
  literary_text_id ────▶ texts
  topics ──────────────▶ topics, до 5 значений
  recognition_id ──────▶ recognitions
  created, updated

files        location, size, format, duration_ms   ← только исходник и opus
texts        format, contents
structures   version, contents (реплики с временем, JSON)
topics       owner, name — уникально по паре
record_events  origin, step, outcome, duration, model, tokens, error_text

recognitions                             ← провайдерское
  record_id, provider, model, external_id,
  source_uri, payload (вложением), started_at, finished_at
```

Что следует из разреза:

- **копия в Object Storage — не файл записи.** Она существует только потому, что
  SpeechKit читает аудио по URI; другой провайдер её не потребует. Ключ объекта
  переезжает в `recognitions.source_uri`, и у `files` остаётся ровно двое членов
  на запись;
- **`recognition_op_id` уезжает с записи** туда же: идентификатор операции Yandex
  — самое провайдерское, что есть в модели, а сегодня он лежит колонкой в
  доменной сущности;
- **сырой ответ SpeechKit сохраняется целиком, вложением, а не колонкой.** Шаг
  опроса читает эту строку раз в пять секунд, а PocketBase читает запись целиком
  (`SELECT *`): восьмимегабайтный JSON в колонке ехал бы в память при каждом
  опросе — тот же промах, что `transcription_text` в `acquireColumns` сегодня.
  Хранится он затем, что **результат операции нельзя переспросить**: связь
  реплики с говорящим мы строить пока не умеем, и когда научимся, архив
  пересчитается из сохранённого без единого рубля;
- **разбор потока — обязанность адаптера, а не шага.** Контракт
  `AudioRecognizer` отдаёт доменный результат (реплики, говорящие, плоский текст,
  байты на хранение) вместо строки, и ни один шаг конвейера не знает формата
  провайдера.

Текст расщеплён по тому, **читается ли он вместе со списком**: `title` и `brief`
идут сотней штук разом и лежат колонками записи, `transcript` и `literary`
читаются по открытию и лежат строками `texts` со ссылкой с записи.

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

## Конвейер

Цепочка рубежей: состояние называет **достигнутое**, а следующий шаг выбирается
таблицей диспетчеризации. Конечный рубеж остаётся `done`: доставка вне
конвейера, и слово описывает пройденный конвейер, а не полученный человеком
текст, — плюс переносится с живых записей тождеством, не стоя ни строки в
необратимом шаге схемы.

```
uploaded ──▶ normalized ──▶ submitted ──▶ transcribed ──▶ done
                                │  ▲
                                └──┘ delay_time, опрос
```

- **остановка — признак, а не состояние.** `halted_at` + `halt_reason` +
  `error_text`; `state` при этом не стирается. Иначе рубеж теряется, и
  «продолжить с места остановки» становится невозможным. Перезапуск —
  снятие признака со сбросом попыток и паузы, доступен и владельцу записи;
  массовый после выкатки правки — одним `UPDATE`. Прежние `failed` и `dead`
  схлопываются в `halt_reason`: обе восстанавливаются одинаково, и различие
  перестаёт быть структурным;
- **шаг бывает обязательным и необязательным.** Отказ уровней текста не роняет
  запись: расшифровка уже есть, и отбирать её из-за надстройки нельзя — запись
  переходит к следующему рубежу, причина уходит в журнал;
- **сторожей два, и обязанности у них разные.** `attempts` считает **отказы** и
  ограничивает повторы внутри шага; `state_entered_at` считает **время** и
  ограничивает застревание. Сегодня обе роли навешаны на `attempts`, и потому он
  не справляется ни с одной: опрос, вернувший «ещё в работе», обнуляет его — и
  зависшая в SpeechKit операция опрашивается вечно, — а не обнулял бы, убивал бы
  здоровую запись;
- **предел времени — два числа, а не одно и не четыре.** Граница проходит не по
  рубежам, а по тому, чью работу ждём: своя (`uploaded`, `normalized`,
  `transcribed`) — **час**, чужая (`submitted`) — **сутки**. Одно общее число
  пришлось бы мерить по самому долгому, и застрявшая нормализация стояла бы
  сутки. Сколько идёт распознавание долгой записи, никто не мерил
  (`speechkit-limits`, `intake-limits-measure`), поэтому ошибаемся в сторону
  долгого: ложная остановка хуже поздней. Оба числа — в конфиг и строкой в
  `docs/database.md`. Достигнут предел — остановка признаком с причиной
  «застряла»; на `submitted` она ничего не теряет, операция в Yandex остаётся в
  `recognitions.external_id`, и перезапуск возобновляет опрос той же;
- **`MoveToState` и `Postpone` разводятся.** Сегодня опрос зовёт
  `MoveToStateAndDelay` с **тем же** состоянием — переходом это никогда не было,
  и именно фиктивность перехода обнуляет попытки. `Postpone(delay)` ставит паузу
  и снимает захват, а `state` и `state_entered_at` не трогает; попытки обнуляет
  по прежнему доводу — ожидание чужой операции отказом не является. Без этого
  разделения новая колонка сбрасывалась бы на каждом опросе и повторила бы
  ровно тот промах, ради которого заводится;
- **срок захвата едет с состоянием**, а не с воркером: обобщённый воркер не
  знает заранее, что вытянет. Пишется числом при захвате в
  `acquire_expires_at`;
- **захват возвращает `id`**, а не перечень колонок. Инвариант «колонки очереди
  правятся в четырёх местах» съёживается до трёх и перестаёт расти с моделью —
  иначе каждая новая колонка записи попадала бы под него;
- **шаг с внешней оплатой проверяет сделанное.** Объект в Object Storage есть
  нужного размера — не заливаем; строка текста для уровня есть — не считаем.
  Сверка по хешу ненадёжна: `ETag` у multipart-объекта не MD5 содержимого;
- **журнал событий пишется на смену рубежа**, не на каждую петлю опроса, и
  никто не читает его, чтобы решить, что делать. Строку пишет и человек —
  перезапуск виден в журнале с указанием, кто нажал.

## Воркеры

Специализация снимается, число уезжает в конфиг, `N = 0` — законное значение
(записи принимаются и не двигаются). Первые три условия масштабируемости в коде
уже есть — неделимый захват, запись только держателем, шаг не предполагает
единственности; недостающие два названы в «Рамках» и в «Вопросах».

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

## Затрагивает

- **шаг схемы**: коллекции `texts`, `structures`, `recognitions`,
  `record_events`, `topics`; переработка `transcribe_jobs` в `audiorecords`;
  правка `files`. Применённые шаги не переписываются — только новым файлом;
- **перенос живых записей на сервере**: `created→uploaded`,
  `converted→normalized`, `transcribe→submitted`, `done→done`; у `failed` и
  `dead` рубеж утрачен и восстанавливается по заполненности полей;
- `internal/entity/job.go` — сущность записи, перечень рубежей, переходы,
  `Fail`/`Die`/`MoveToState`, новый `Postpone`;
- `internal/contract/contract.go` — `AudioRecognizer` отдаёт доменный результат
  вместо строки; заливка и отправка разделены;
- `internal/contract/repository.go` — контракты репозиториев записи, файлов,
  текстов, структуры, попыток распознавания, журнала;
- `internal/adapter/recognizer/yandex/` — разбор потока `GetRecognition` в
  реплики, раздельные заливка и отправка, отдача сырых байтов;
- `internal/adapter/repo/pocketbase/` — запрос захвата, `acquireColumns` и
  `acquiredRow`, `applyToRecord`, `recordToJob`;
- `internal/service/transcribe.go` — шаги, таблица диспетчеризации по рубежу,
  остановка признаком;
- `internal/controller/worker/worker.go` и `main.go` — пул вместо трёх
  именованных воркеров;
- `config.example.toml` и `internal/config` — число воркеров, срок захвата по
  шагу, два предела времени в рубеже;
- **публичный контракт HTTP API** — перечень состояний в ответе о записи;
- `docs/architecture.md`, `docs/database.md`, `openspec/specs/`, инварианты
  `CLAUDE.md` о колонках очереди и о держателе захвата.

## Критерии приёмки

- Запись, остановленная на шаге, перезапускается снятием признака и продолжает
  с того рубежа, где стояла. Оракул — тест: шаг останавливает запись на
  `normalized`, снятие `halted_at` возвращает её в работу, и следующим идёт
  отправка на распознавание, а не повторная нормализация.
- У прошедшей конвейер записи ссылки на исходник и на opus ведут на разные
  существующие копии. Оракул — тест полного прохода: обе ссылки заполнены и обе
  открываются.
- Число воркеров задаётся конфигом, и поведение от него не зависит. Оракул —
  прогон теста конвейера при `N=1` и `N=4`: запись доходит до `done` в обоих; при
  `N=0` она остаётся в `uploaded` и не теряется.
- Структура реплик строится из сохранённого ответа провайдера без обращения к
  нему. Оракул — тест на сохранённом вложении: структура собрана, клиент
  SpeechKit не позван ни разу.
- Живые записи переносятся шагом схемы без потери. Оракул — тест шага на слепке
  прежних данных: у каждой задачи появляется запись с тем же рубежом, владельцем,
  файлом и текстом.
- Запись, застрявшая в рубеже дольше предела, останавливается, а откладывание
  опроса предела не сдвигает. Оракул — тест на подставных часах: сотня
  откладываний подряд не двигает `state_entered_at` и не обнуляет отсчёт, а по
  истечении предела запись получает признак остановки с причиной «застряла».

## Рамки

Резку длинной записи на фрагменты не делаем — конвейер остаётся цепочкой.
Доставку из конвейера не выносим и не переделываем: ответ в Telegram остаётся
хвостом последнего шага. Уровни текста модель готовит, но сам шаг обращения к
языковой модели делает `llm-insights-adapter`, а вычитанный текст —
`literary-text-level`. Говорящих в структуре сегодня не размечаем: связь реплики
с `SpeakerAnalysis` не выяснена. Таймауты внешним вызовам ставит
`external-call-timeouts`, и она этой задаче предшествует — без предела по времени
у шага срок захвата не может его превысить, и протухший захват даёт вторую
платную операцию в SpeechKit. Нарастающую паузу опроса и отступ на пустой
очереди не делаем: первое — `speechkit-callback-fit`, второе при единицах записей
в день не нужно. Экранов не трогаем.

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