приём и чтение записей сведены к одному контракту приложения

- адреса приложения переехали в своё пространство `/app/`, опрос готовности
  убран целиком: рубеж и причину остановки владелец узнаёт карточкой записи,
  текст — отдельным адресом названного вида
- заведена единая точка отображения доменной ошибки и слой, приводящий к той же
  форме отказы библиотеки: тело несёт машиночитаемый код рядом с сообщением
- у записи появились имя файла отправителя, длительность и размер своими
  колонками, а у ленты владельца — свой индекс: без него страница сканировала
  весь архив сервиса

openspec/specs/archive/spec.md

@@ -0,0 +1,470 @@
+# archive Specification
+
+## Purpose
+TBD - created by archiving change app-json-contract. Update Purpose after archive.
+## Requirements
+### Requirement: Адреса приложения живут своим пространством
+
+Сервис SHALL вешать собственные адреса приложения под корнем `/app/` и MUST не
+занимать имён в пространстве `/api/`: последнее принадлежит хранилищу, оно
+вешает туда собственные наборы адресов, и поменять этот префикс нельзя — он
+литерал библиотеки, а не настройка.
+
+Свободных имён в чужом пространстве сегодня хватает, но соседство остаётся:
+обновление библиотеки вправе занять новое имя рядом с нашим, и разойдутся они
+молча — тем же адресом начнёт отвечать не тот обработчик.
+
+Цена переезда называется здесь же. Правило неизвестного пути, по которому
+приложение отдаётся вместо отказа, MUST перечислять **все** корни сервиса, а не
+один: путь внутри любого корня в приложение не проваливается никогда. Ограничитель
+частоты хранилища настроен на чужой корень и наших адресов больше не покрывает,
+поэтому сервис MUST заводить своё правило под корень приложения.
+
+Цена этого названа здесь же: ограничитель у хранилища один на всю его поверхность
+и выключен умолчанием, поэтому включение нашего правила вводит в действие и его
+собственные — на входе, на заведении записей и на его адресах. Принимается
+сознательно: без включения наше правило не значит ничего.
+
+Пространство `/api/settings` принадлежит хранилищу и остаётся ему: настройки
+человека живут под корнем приложения.
+
+#### Scenario: Адрес приложения отвечает под своим корнем
+
+- **GIVEN** человек вошёл и предъявил сессию
+- **WHEN** он спрашивает список своих записей под корнем приложения
+- **THEN** ответ приходит от сервиса, а не от хранилища
+
+#### Scenario: Прежние адреса приложения не отвечают
+
+- **GIVEN** заведена запись
+- **WHEN** её спрашивают прежними адресами в чужом пространстве
+- **THEN** ответ имеет код `404`
+
+#### Scenario: Ограничитель частоты покрывает адреса приложения
+
+- **WHEN** сервис поднялся
+- **THEN** настройки ограничителя несут правило, чей адрес начинается корнем
+  приложения
+
+### Requirement: Отказ называет причину, а не место
+
+Сервис SHALL отвечать на адресах приложения кодом, который отвечает **причине**
+отказа, а не месту, где он случился. Перечень закрыт и назван поимённо:
+
+- отсутствие сессии — `401`, и он MUST наступать **до всякого чтения записи**,
+  одинаково для заведённой записи и для неизвестного идентификатора: иначе по
+  разнице кодов перебирается список заведённых записей;
+- узнанный предъявитель без учётной записи пользователя — `403`;
+- неизвестный идентификатор — `404`, и **тем же кодом с тем же телом** MUST
+  отвечать чужая и ничья запись;
+- негодный ввод — `400`: нечитаемая запись, неизвестное значение параметра,
+  негодный размер страницы;
+- запись сверх потолка размера — `413`, и тело MUST нести предел числом;
+- состояние, в котором действие недоступно, — `409`: текста запрошенного вида у
+  записи ещё нет;
+- отказ хранилища и всякая неназванная причина — `500`.
+
+Отображение доменной ошибки в код и сообщение MUST жить **одним местом** на все
+адреса, и у него MUST быть определённая ветвь по умолчанию. Сегодня такого места
+нет вовсе, и каждый обработчик решает сам: опрос отвечает «записи нет» на упавшую
+базу, а приём — «внутренняя ошибка» на негодный файл. Человек читает первое как
+«моя запись пропала», а второе не говорит ему ничего.
+
+Тело отказа MUST быть одной формы на всех адресах приложения и MUST нести **два**
+поля: машиночитаемый код отказа из закрытого перечня и сообщение, пригодное
+человеку, на русском языке. Одного сообщения мало: кода HTTP не хватает, чтобы
+различить «файл негоден», «поля записи нет» и «неизвестное значение параметра» —
+все три `400`, — а приложению надо решать, предлагать ли повтор и что показать
+человеку. Разбор русской фразы был бы единственным оставшимся путём, и первая же
+задача экрана переписала бы контракт, согласованный здесь один раз.
+
+Имена полей и перечень кодов нормативны — их разбирает каждый экран, и
+выбранные кодом они стали бы контрактом молча:
+
+- поля тела: `error_code` и `message`;
+- перечень `error_code`: `unauthorized`, `forbidden`, `not_found`,
+  `bad_request`, `too_large`, `too_many_requests`, `not_ready`, `internal`.
+
+Часть отказов рождается **не в обработчике** — предел тела, ограничитель частоты,
+неизвестный путь под корнем приложения, — и до отображения доменной ошибки не
+доходит вовсе. Такие отказы MUST приводиться к той же форме: иначе форм на
+адресах приложения две, а самый частый отказ у человека на мобильной сети —
+«запись больше потолка» — приходит телом библиотеки, без кода и без предела
+числом.
+
+Перечень закрыт и объявляется **одним местом**. Новая штатная ветвь отказа
+заводится добавлением в него, а не строкой в обработчике: иначе ветвь по
+умолчанию отдаст `internal` на обычный конфликт, и владелец сервиса увидит в
+журнале аварию там, где её нет.
+
+Сырой текст ошибки MUST в тело не попадать — ни `err.Error()`, ни детали
+устройства: имена внешних сервисов, пути на диске, ключи файлов. Полная ошибка
+остаётся в журнале владельца сервиса.
+
+#### Scenario: Сбой хранилища виден как сбой
+
+- **GIVEN** хранилище отвечает отказом драйвера на чтение записи
+- **WHEN** владелец спрашивает свою запись
+- **THEN** ответ имеет код `500`
+- **AND** тела записи в ответе нет
+
+#### Scenario: Негодная запись видна как негодная
+
+- **GIVEN** источник метаданных не может прочитать присланную запись
+- **WHEN** отправитель шлёт её приёмом
+- **THEN** ответ имеет код `400` и несёт сообщение, пригодное человеку
+- **AND** причина отказа в тело ответа не попадает
+
+#### Scenario: Отказ по пустому владельцу
+
+- **GIVEN** предъявитель узнан, но учётной записи пользователя у него нет
+- **WHEN** он шлёт запись приёмом
+- **THEN** ответ имеет код `403`
+
+#### Scenario: Форма тела одна на всех ветвях отказа
+
+- **WHEN** сервис отказывает по ненайденной записи, по негодному вводу, по
+  отсутствию учётной записи и по сбою хранилища
+- **THEN** тело каждого ответа несёт код отказа и сообщение одними и теми же
+  полями
+- **AND** код отказа принадлежит закрытому перечню
+- **AND** ни одно из них не содержит сырого текста ошибки
+
+#### Scenario: Без сессии неизвестная запись неотличима от заведённой
+
+- **GIVEN** заведена запись
+- **WHEN** её карточку спрашивают без сессии, а затем спрашивают карточку по
+  неизвестному идентификатору
+- **THEN** оба ответа имеют код `401` и одно тело
+
+#### Scenario: Запись сверх потолка размера
+
+- **GIVEN** отправитель предъявил сессию
+- **WHEN** он шлёт запись длиннее потолка размера
+- **THEN** ответ имеет код `413`, а тело несёт предел числом
+- **AND** ни файла, ни аудиозаписи не заводится
+
+### Requirement: Сервис объявляет свои пределы
+
+Сервис SHALL отдавать свои пределы отдельным адресом — `GET /app/config` — и
+MUST называть в нём потолок размера одной записи, потолок размера страницы,
+частоту опроса карточки, перечень известных расширений и потолок числа тем у
+записи.
+
+Предел зовётся частотой опроса **карточки**, а не готовности: адрес опроса
+готовности это же изменение убирает целиком, и читатель через месяц искал бы то,
+чего нет.
+
+Имена полей ответа нормативны: `max_record_size_bytes`, `max_page_size`,
+`poll_interval_ms`, `known_extensions`, `max_topics_per_record`.
+
+**Каждый объявленный предел MUST быть тем же значением, которое сервис
+применяет, а не его копией.** Правило общее, а не про один потолок размера:
+приложение, знающее предел своей константой, расходится с сервером молча — до
+первого отказа на записи, которую человек уже успел отправить по мобильной сети.
+Ровно то же случается, когда предел объявлен сервером, но взят из второй
+константы рядом с применяемой.
+
+Отсюда источник у каждого:
+
+- потолок размера записи — то число, которым сервис ограничивает тело запроса
+  приёма и отвергает запись кодом `413`;
+- потолок числа тем у записи — то число, которым его ограничивает схема
+  хранилища; норму держит capability `storage`;
+- потолок размера страницы — то число, до которого сервис усекает запрошенный
+  размер страницы;
+- частота опроса — выводится из **доли** бюджета ограничителя частоты под корнем
+  приложения и MUST не задаваться своей константой. Доля, а не весь бюджет:
+  опрос идёт не один — в ту же секунду приложение листает список, открывает
+  соседнюю карточку и грузит новую запись, а бюджет один на все адреса
+  приложения и считается по адресу спрашивающего, а не по учётной записи.
+  Объявленная частота, равная всему бюджету, отдавала бы отказ на любом втором
+  запросе — тот самый, которого объявление обещает избежать. Иначе приложение,
+  честно опрашивающее карточку с объявленной частотой, упирается в собственный
+  ограничитель сервиса — и получает отказ, которого сервис сам же ему и обещал
+  избежать;
+- перечень известных расширений — тот же, что сужает метку метрики, за вычетом
+  собственного умолчания сервиса `audio`: оно не формат, и подсказкой человеку
+  выходить не должно. Второй перечень рядом с первым разошёлся бы с ним молча.
+
+**Перечень известных расширений — исключение в другом: сервис по нему не
+судит.** Приём о годности записи не судит сам — расширение он берёт из
+имени файла, а пригодность содержимого узнаёт у источника метаданных, — и
+перечень служит приложению подсказкой для диалога выбора файла, не более.
+Умолчать об этом нельзя: приложение прочитало бы перечень как «что можно
+загружать» и отвергало бы запись, которую сервис принял бы и расшифровал.
+
+Адрес MUST быть доступен тому же, кому доступны прочие адреса приложения:
+пределы не тайна, но отдельного открытого адреса ради них не заводится.
+
+#### Scenario: Потолок размера равен тому, которым сервис отвергает
+
+- **GIVEN** человек вошёл и предъявил сессию
+- **WHEN** он спрашивает пределы сервиса
+- **THEN** потолок размера в ответе равен потолку, которым сервис ограничивает
+  тело запроса приёма
+
+#### Scenario: Потолок страницы равен применяемому
+
+- **WHEN** человек спрашивает пределы сервиса, а затем просит страницу размером
+  сверх объявленного потолка
+- **THEN** размер отданной страницы не превышает объявленного потолка
+
+### Requirement: Страница своих записей
+
+Сервис SHALL отдавать владельцу страницу его записей — `GET /app/audiorecords` —
+новыми сверху, и MUST не показывать в ней ни одной чужой записи. Спрашивающий с
+пустым именем MUST не получать ни одной записи.
+
+Ответ MUST нести страницу, ключ следующей страницы и общее число записей. Число
+записей одного человека растёт годами — сервис объявлен архивом, — и ответ без
+страниц перестал бы помещаться в память телефона.
+
+**Страница задаётся ключом, а не номером.** Приём пишет в голову той же ленты,
+которую читает список, и человек, загрузивший запись и листающий свой архив, —
+штатный сценарий, а не редкость. Номер страницы сдвинул бы окно на единицу:
+последний элемент первой страницы пришёл бы вторым разом первым элементом второй,
+а один элемент между ними не пришёл бы никогда. Отказ молчаливый — ни кода, ни
+строки в журнале, — и человек видел бы архив, в котором записи нет.
+
+Ключ MUST быть непрозрачным для спрашивающего и MUST задавать положение
+**полным** ключом сортировки — парой «время заведения и идентификатор». Одного
+времени мало: у записей, принятых одним запросом, оно совпадает, и порядок между
+ними иначе не определён вовсе.
+
+Ключа следующей страницы нет — страница последняя; пустая страница MUST отвечать
+успехом, а не отказом: отсутствие записей не есть ошибка.
+
+Ключ, который сервис не может прочитать — протухший, обрезанный, подделанный, —
+MUST давать отказ по негодному вводу. Молчаливая отдача первой страницы вместо
+этого дала бы человеку архив, листающийся по кругу, и ни строки в журнале.
+
+**Сторона запроса нормируется наравне со стороной ответа.** У размера страницы
+MUST быть умолчание и потолок; размер сверх потолка MUST усекаться до него, а не
+отвергаться, а негодное значение — ноль, отрицательное, нечисловое — MUST давать
+отказ по негодному вводу. Незаданный потолок был бы способом попросить весь архив
+одним запросом, то есть обойти постраничность тем самым параметром, ради которого
+она заведена.
+
+Имена полей ответа и элемента нормативны: экраны строятся на них, и
+переименование после того, как экран написан, стоит правки приложения.
+
+- параметры запроса: `cursor`, `limit`, `filter`;
+- страница: `items`, `next_cursor`, `total_items`;
+- элемент: `id`, `title`, `original_filename`, `brief`, `topics`, `state`,
+  `halted`, `halt_reason`, `duration_ms`, `size_bytes`, `created_at`.
+
+Значение `state` MUST принадлежать перечню рубежей конвейера, а `halt_reason` —
+перечню причин остановки. Оба перечня объявлены одним местом, и перечислять их
+порознь в потребителе нельзя: рубеж, добавленный конвейером, иначе разошёлся бы
+с ответом молча.
+
+Чтение страницы MUST не читать ни расшифровки, ни структуры реплик: обе лежат
+порознь от записи ровно затем, чтобы список их не тянул. Длительность и размер
+MUST браться колонками самой записи, а не строкой её файла.
+
+Машинный текст отказа MUST в элемент страницы не попадать: он принадлежит
+журналу владельца сервиса. Причина остановки — значение из закрытого перечня, и
+она не он.
+
+Значения причины остановки этим требованием впервые выходят в публичный ответ, и
+это осознанно: без причины признак остановки не говорит человеку, чего ждать —
+повтора, своего действия или ничего. Превращает значение в русскую фразу
+**приложение**, а не сервис: сервис отдаёт значение перечня, и второй словарь
+фраз на стороне сервера разошёлся бы с тем, что показывает экран.
+
+**Отбор MUST различать три состояния, а не два:** запись в работе (`working`),
+запись остановлена (`halted`), запись прошла конвейер (`done`). Незаданный отбор
+значит «все». Двух значений не хватает: остановленная
+запись не в работе и не завершена, и при отборе надвое она выпала бы из обеих
+половин — то есть исчезла бы из списка при любом значении отбора, хотя ради неё
+человек список и открывает. Предикат каждого состояния MUST выводиться из
+дескриптора рубежа и признака остановки, а не перечислять рубежи строкой запроса:
+рубеж, добавленный конвейером, иначе молча поменял бы состав всех трёх.
+
+#### Scenario: Страница отдаётся новыми сверху
+
+- **GIVEN** владелец завёл записей больше, чем помещается на страницу
+- **WHEN** он спрашивает первую страницу
+- **THEN** в ней лежит ровно столько записей, сколько вмещает страница
+- **AND** первой стоит заведённая последней
+- **AND** ответ несёт общее число его записей и ключ следующей страницы
+
+#### Scenario: Запись, заведённая между страницами, окна не сдвигает
+
+- **GIVEN** владелец прочитал первую страницу и взял ключ следующей
+- **WHEN** он заводит новую запись и спрашивает следующую страницу этим ключом
+- **THEN** ни один элемент первой страницы в ней не повторяется
+- **AND** ни одна запись между страницами не пропущена
+
+#### Scenario: Записи с одним временем заведения идут в устойчивом порядке
+
+- **GIVEN** две записи заведены одним запросом и время заведения у них совпадает
+- **WHEN** владелец читает страницу дважды
+- **THEN** порядок этих записей в обоих ответах один и тот же
+
+#### Scenario: Последняя страница
+
+- **WHEN** владелец дочитал архив до конца
+- **THEN** ответ имеет код `200`, а ключа следующей страницы в нём нет
+
+#### Scenario: Чужих записей в странице нет
+
+- **GIVEN** записи заведены двумя вошедшими
+- **WHEN** страницу спрашивает один из них
+- **THEN** в ней лежат только его записи
+
+#### Scenario: Список не тянет расшифровку
+
+- **GIVEN** у записи есть расшифровка
+- **WHEN** владелец спрашивает страницу своих записей
+- **THEN** текста расшифровки в ответе нет
+- **AND** чтение страницы строку текста не трогает
+
+#### Scenario: Размер страницы сверх потолка усекается
+
+- **WHEN** владелец просит страницу размером больше объявленного потолка
+- **THEN** ответ имеет код `200`, а размер страницы равен потолку
+
+#### Scenario: Негодный размер страницы отвергается
+
+- **WHEN** владелец просит страницу размером ноль либо нечисловым значением
+- **THEN** ответ имеет код `400`
+
+#### Scenario: Остановленная запись видна отбором
+
+- **GIVEN** у владельца есть запись в работе, остановленная запись и прошедшая
+  конвейер
+- **WHEN** он спрашивает каждое из трёх состояний отбором
+- **THEN** каждая запись приходит ровно в одном из них
+- **AND** остановленная приходит с признаком остановки и её причиной
+
+### Requirement: Карточка записи отдаётся без текста
+
+Сервис SHALL отдавать владельцу карточку одной записи — `GET
+/app/audiorecords/{id}` — и MUST не класть в неё текста расшифровки.
+
+**Карточка несёт те же поля, что и элемент страницы, плюс перечень доступных
+видов текста** — полем `available_views`. Две формы одной вещи разошлись бы
+молча, поэтому состав задан одной нормой, а не двумя.
+
+Отсюда обязанность, которой держится инвариант проекта «принятая запись не
+теряется молча»: карточка MUST нести рубеж, признак остановки и её причину.
+Прежде исход своей записи владелец узнавал опросом готовности; опрос убран, и
+единственным местом, где отправитель узнаёт о неудаче, становится карточка. Норма
+эта переехала сюда целиком — capability `pipeline` называет держателем её этот
+адрес.
+
+Вид считается доступным по **содержимому**, а не по наличию ссылки на текст.
+Ссылка без содержимого — состояние штатное: пустой ответ распознавания сервис
+признаёт нормой и записывает его в журнал. Строй мы перечень по ссылкам,
+карточка объявляла бы вид доступным, а адрес текста отвечал бы «ещё не готов»
+вечно — приложение опрашивало бы его без конца, а человек видел бы завершённую
+запись, из которой текст «вот-вот появится».
+
+Перечень MUST присутствовать в ответе **всегда**, в том числе пустым: отсутствие
+поля и пустой перечень приложение не различит, а значат они разное.
+
+Перечень доступных видов MUST быть **перечнем**, а не признаком «текст есть».
+Видов больше одного, и шаг завершения пишет их несколькими операциями: состояние
+«сплошной текст есть, реплик ещё нет» достижимо. Один признак на несколько видов
+отправил бы приложение за репликами, которых нет, — и исход стал бы функцией
+того, в каком месте прервался шаг, а не состояния записи. Пустой перечень значит
+«текста ещё нет».
+
+Шестичасовая расшифровка, приехавшая вместе с шапкой записи, задерживает показ
+на мобильной сети на то время, которое человеку не нужно ждать: шапку он читает
+сразу, а текст — если решил читать.
+
+Запись, принадлежащая другому, MUST отвечать тем же, чем отвечает неизвестный
+идентификатор.
+
+#### Scenario: Карточка без текста
+
+- **GIVEN** у записи есть расшифровка
+- **WHEN** владелец спрашивает её карточку
+- **THEN** поля с текстом в ответе нет
+- **AND** перечень доступных видов несёт сырую расшифровку
+
+#### Scenario: Остановленная запись видна карточкой
+
+- **GIVEN** запись остановлена признаком по исчерпании отказов
+- **WHEN** владелец спрашивает её карточку
+- **THEN** карточка несёт достигнутый рубеж, признак остановки и её причину
+- **AND** машинного текста отказа в ответе нет
+
+#### Scenario: Текста ещё нет
+
+- **GIVEN** запись не дошла до расшифровки
+- **WHEN** владелец спрашивает её карточку
+- **THEN** перечень доступных видов пуст
+
+#### Scenario: Чужая карточка неотличима от неизвестной
+
+- **GIVEN** запись заведена одним вошедшим
+- **WHEN** её карточку спрашивает другой вошедший
+- **THEN** ответ тот же, что и на неизвестный идентификатор, — и кодом, и телом
+
+### Requirement: Текст записи отдаётся названным видом
+
+Сервис SHALL отдавать текст записи отдельным адресом — `GET
+/app/audiorecords/{id}/text` — и MUST отдавать **вид, названный спрашивающим**.
+Отдача «последнего записанного» сделала бы ответ функцией порядка записи, а не
+состояния записи.
+
+**Перечень видов закрыт, и каждое его значение называет ровно одну хранимую
+вещь:**
+
+- `transcript` — сырая расшифровка сплошным текстом;
+- `literary` — вычитанный текст сплошным;
+- `replicas` — реплики со временем.
+
+Перечень назван так, а не парой «вид текста плюс форма показа», потому что
+реплики со временем — не вид текста: они лежат структурой разбора и принадлежат
+записи, а не тексту. Пара из двух параметров обещала бы сочетания, которых не
+существует.
+
+Вычитанный текст назван здесь, хотя считает его отдельная задача: перечень,
+заведённый без него, пришлось бы расширять правкой публичного контракта — того
+самого, который согласуется здесь один раз. До появления вычитанного текста
+значение просто не встречается в перечне доступных видов у карточки.
+
+Значения `transcript` и `literary` MUST совпадать с видами текста, объявленными
+хранилищем: два словаря об одном разошлись бы молча.
+
+Текста запрошенного вида нет — сервис MUST отвечать кодом `409`, а не пустой
+строкой и не `404`. Пустая строка читается как «расшифровка пуста»; `404` слился
+бы с ответом на чужую и неизвестную запись, и человек увидел бы «не найдено» на
+своей записи, загруженной минуту назад, — ровно тот отказ, ради устранения
+которого заводится весь контракт.
+
+Вид, которого сервис не знает, и незаданный вид MUST давать отказ по негодному
+вводу: умолчание сделало бы ответ функцией того, что успел записать конвейер.
+
+Текст чужой записи MUST быть недоступен наравне с её карточкой.
+
+#### Scenario: Сырая расшифровка сплошным текстом
+
+- **GIVEN** у записи есть сырая расшифровка
+- **WHEN** владелец спрашивает её текст видом `transcript`
+- **THEN** ответ несёт содержимое сырой расшифровки
+
+#### Scenario: Реплики со временем
+
+- **GIVEN** у записи есть структура реплик
+- **WHEN** владелец спрашивает её текст видом `replicas`
+- **THEN** ответ несёт реплики, и у каждой стоит её время
+
+#### Scenario: Текста этого вида ещё нет
+
+- **GIVEN** у записи есть сырая расшифровка и нет структуры реплик
+- **WHEN** владелец спрашивает её текст видом `replicas`
+- **THEN** ответ имеет код `409`
+- **AND** он отличается от ответа на неизвестный идентификатор
+
+#### Scenario: Вид неизвестен или не назван
+
+- **WHEN** владелец спрашивает текст видом, которого сервис не знает, либо не
+  называет вида вовсе
+- **THEN** ответ имеет код `400`
+