transcriber/openspec/changes/archive/2026-08-15-app-json-contract/design.md

Context

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

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

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

Goals / Non-Goals

Goals:

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

Non-Goals:

• экранов не делаем ни одного — их берут spa-skeleton и задачи экранов;
• признак повторного файла контракт называет местом в ответе, но не заполняет: хозяин — dedup-by-content-hash;
• поток аудио (GET /app/audiorecords/{id}/audio) и настройки человека (/app/me/settings) контракт не нормирует вовсе — ни адресом, ни местом в карточке. Их форму выбирают play-recording-in-app и settings-screen, и карточку они дополнят своим полем. Обещание «назвать, но не реализовать» снято: названным считается только то, что стоит требованием спеки;
• заголовок и темы, которые считает языковая модель, заполняет llm-insights-adapter; здесь только место под них;
• правка заголовка руками — колонка заведена, адрес принесёт audiorecord-actions;
• аутентификация и владелец не заводятся: это oidc-login и record-ownership, оба сделаны.

Decisions

Новая capability archive, а не расширение intake

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

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

Единая форма отказа и пределы сервера легли в archive, а не в intake, потому что они свойство всей поверхности приложения, а не приёма: у нормы, живущей в двух домах, дома нет.

Отображение доменной ошибки — одна функция, названная в архитектуре

Сегодня такой точки нет, и это записано расхождением в conventions/errors.md. Заводим её в слое транспорта: доменная ошибка на входе, код и человекочитаемое сообщение на выходе. Таблица соответствий — та, что уже стоит в конвенции; новая ветвь заводится sentinel'ом и добавляется туда же.

Отвергнуто: каждый обработчик решает сам — это сегодняшнее состояние, и именно оно даёт 404 на упавшую базу. Отвергнуто: отображение в доменном слое — код HTTP там не к месту, а второй транспорт (если появится) получил бы чужие коды.

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

Переезд в /app/, а слой сессии — на корень

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

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

Три новых колонки записи и один шаг схемы

original_filename, длительность и размер ложатся колонками записи. Длительность и размер лежат сегодня строкой файла, а список по норме storage читается без содержимого — доставать их строкой файла значит читать по строке на каждую запись списка.

Шаг схемы один на все три: применённый шаг не переписывается, и три шага вместо одного стоили бы трёх необратимых решений там, где хватает одного.

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

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

Отвергнуто на чекпоинте 2026-08-15: брать длительность и размер у строки файла батчем на страницу. Довод против колонок был в том, что обе величины уже лежат у файла и станут копиями, которые некому держать равными; решением владельца колонки остаются, а равенство объявлено ненужным прямо — на записи лежит снимок принятого, на файле величины сегодняшней копии, и это разные вопросы. Норма записана спекой storage, иначе два числа читались бы как копии одного.

Страница задаётся ключом, а не номером

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

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

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

Имя отправителя: предел длины и уборка управляющих знаков

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

Темы в списке — названиями, а не ссылками

Ничего сегодня темы не пишет: их посчитает llm-insights-adapter. Поле в ответе всё равно заполняется названиями, а не идентификаторами: отдай мы ссылки, экран не смог бы их показать, и форма ответа переделывалась бы задачей языковой модели — ровно то, ради чего контракт согласуется здесь.

Текст отдаётся по названному виду — одним закрытым перечнем

Видов три: transcript, literary, replicas. Перечень назван так, а не парой «вид текста плюс форма показа», потому что реплики со временем — не вид текста: они лежат структурой разбора и принадлежат записи. Пара из двух параметров обещала бы сочетания, которых не существует.

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

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

Отказ несёт машиночитаемый код, а не только фразу

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

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

Имена полей названы спекой, а не выбраны кодом

Контракт согласуется один раз ради того, чтобы экраны не переделывались. Имена полей — часть контракта наравне с адресами: выбранные кодом, они станут известны экранам, и переименование после этого стоит правки приложения. Форма страницы — items, next_cursor, total_items: собственные адреса хранилища приложению закрыты, и совпадать с его формой страницы не с чем.

Отбор списка различает три состояния, а не два

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

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

Отказ по превышению размера получает свою ветвь

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

Risks / Trade-offs

• Ломка публичного контракта необратима. → Стадия — стройка, данных на сервере нет, внешней программы на прежнем контракте не существует. Прежние адреса отвечают 404, а не отсутствуют молча.
• Шаг схемы применён — не переписать. → Три колонки заводятся одним шагом, и состав их сверен со спекой storage до написания кода.
• Правило ограничителя частоты можно забыть завести. → Проверяется тестом: настройки несут правило, чей адрес начинается корнем приложения.
• Отбор списка по владельцу — место, где утечка стоит дороже всего. → Сужение владельцем лежит в репозитории, а не в обработчике, и пустой владелец не совпадает ни с одной записью — норма access уже это держит.
• Место под признак повтора и под темы заполняется не здесь. → Форма зафиксирована спекой, и соседние задачи её не переписывают, а заполняют.

Migration Plan

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

Open Questions

Нет: четыре развилки контракта закрыты решением владельца 2026-08-15, состав адресов согласован там же.