# Передача оркестратору: контракт 0.2.0 — что применить в каноне

> **Это не носитель состояния, а патч.** Файл существует ровно до лендинга S3: оркестратор
> переносит правку спеки и вписывает блоки §2–§4 в компаньон канона, после чего файл удаляется.
> Сессия фронта канон (`docs/architecture/14-api-contract/`) не правит — это чужая зона.
>
> Написано фронт-сессией S3, 08.08.2026.

## 1. Спека: зонная копия впереди канона

| Что | Где |
|---|---|
| Правленая копия | `frontend/docs/api-contract/openapi.yaml` — **version `0.2.0`** |
| Канон | `docs/architecture/14-api-contract/openapi.yaml` — всё ещё `0.1.0-draft` |

Байт-сверка (пункт Д промта) **даёт расхождение, и это ожидаемо**: правки заказаны промтом S3,
а канон правит оркестратор. Диффом:

```
diff -u docs/architecture/14-api-contract/openapi.yaml frontend/docs/api-contract/openapi.yaml
```

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

**Что сделано по списку промта** (каждый пункт — в спеке, а не в намерении):

| Пункт | Исполнено |
|---|---|
| А-нуль | `version: 0.2.0`. ⚠ **Отступление, называю вслух:** промт говорил «твоё там одно — бампнуть version», но в шапке стояла фраза «version всё ещё `-draft` — S3 бампнет первым действием», которая после бампа становилась ложной. Заменил её на правду о том, что копия сейчас впереди канона. Баннер «DRAFT … not a ratified contract» НЕ возвращён |
| А.1 К-1 | статусы не тронуты |
| А.2 К-8 | `BookStatus` += `paused`; в описании прямо: стоп по потолку это `paused`, не `failed` |
| А.3 К-5 | `Progress.eta_seconds`, опциональное и nullable |
| А.4 К-3 | `Chapter.number` и `Chapter.heading` — оба обязательны и оба допускают `null`; запрет синтеза «Глава {n}» записан нормативом. Фикстуры проверены и правлены (см. §5) |
| Б.5 К-4 | ревизия пер-книжная; правила «монотонна в скоупе», «отбрасывание — обязанность клиента», «докачка `>= R`, не `>`», «полная замена ⇒ `resync_required`» — прозой в `Revision` |
| Б.6 К-7 | `?limit=&cursor=` и `next_cursor` на ВСЕХ пяти списочных ответах; дефолты 5000/1000/500; курсор привязан к структурной эпохе, отклонение протухшего — MUST сервера, ответ `400` |
| Б.7 К-12 | `202` + обязательный `Location`; `Retry-After` объявлен ЯВНО заголовком 200-ответа со ссылкой на то, почему RFC 9110 сам этого не даёт |
| Б.8 CSRF | `X-TM-Client` в описании `sessionCookie`: несёт ПРИСУТСТВИЕ, значение любое, обязателен и на same-origin |
| Б.9 | `PausedReason` = `credit_exhausted`, `Run.paused_reason` обязателен и nullable |
| В.10–11 | `GET /usage` + схема `Usage`. ⚠ Форма из промта записана в 3.0-синтаксисе (`nullable: true`), в 3.1 он невалиден — выражено через `oneOf` с `type: 'null'`, как везде в этой спеке |
| В-бис | в `openapi.yaml` НЕ потащено, как и велено; текст для компаньона — §2 ниже |
| Г.12–15 | пер-главное чтение юнитов с запретом пер-книжной ручки · экспорт-артефакт с явным запретом сборки текста на клиенте · право сервера склеивать кадры + обязанность клиента терпеть скачки · `maxLength` у `heading` |
| В-трис.16–18 | `GET /books/{bookId}/run-options` → `CeilingBounds`; `RunRequest.ceiling_chapters`; `Run.ceiling_chapters`. Обоснование формы — §3 |
| В-кватер | раздел «Transport» в шапке: тот же origin как факт, CORS-слоя нет, кросс-origin не проектируется. В коде — прокси dev-сервера (`vite.config.ts`, включается `TM_PLATFORM`) |

## 2. Для компаньона: поверхность входа (пункт 15-бис)

Вставить в компаньон канона (`docs/architecture/14-api-contract/README.md`) новым разделом.

> ### 2.14. Поверхность входа — вне версионного префикса
>
> Платформа построила вход через OIDC (P1). Четыре ручки живут ВНЕ `/v0`, как `/healthz`, потому
> что это механика сессии, а не контрактная поверхность, и в `openapi.yaml` они намеренно не
> тащатся (решение оркестратора как владельца контракта).
>
> | Ручка | Метод | Что делает |
> |---|---|---|
> | `/auth/login` | GET | начинает вход, редиректит к провайдеру; принимает `?return_to=<путь на этом сайте>` |
> | `/auth/callback` | GET | завершает вход, ставит сессионную куку, редиректит на `return_to` либо на дефолт |
> | `/auth/logout` | POST | завершает ЭТУ сессию |
> | `/auth/logout-all` | POST | завершает ВСЕ сессии пользователя |
>
> Клиенту нужно знать три вещи, и только три. Куда вести на вход. Что `return_to` принимает
> **только путь этого сайта** — чужой сервер молча заменит на дефолт, открытый редирект закрыт.
> И что обе `POST`-ручки лежат на cookie-пути, то есть требуют `X-TM-Client` (§2.8 спеки).
> Отказ входа — `problem+json`, как везде; различать причины отказа клиент не может и не должен.

## 3. Для компаньона: управляемый потолок прогона — форма и обоснование

Единственное место списка правок, где решение было за сессией. Форма и почему именно она:

> ### 2.15. Потолок прогона — ◆ предложено фронтом
>
> Ратифицировано владельцем 07.08: шкала в интерфейсе от минимума до максимума, ноль выбрать
> нельзя, единица — ГЛАВЫ, максимум — доступный остаток (баланс минус холды), потолок принадлежит
> ПРОГОНУ. Ручки, отдающей границы шкалы, в контракте не было; она объявлена этой правкой.
>
> **Отдельный ресурс `GET /books/{bookId}/run-options`, а не поле карточки книги.** Два довода, и
> оба про правду на экране. Максимум зависит от АККАУНТА — баланс минус открытые холды — и
> двигается, когда книга не меняется: холд, взятый под другую книгу, опускает остаток. Карточка
> книги кэшируется и переиспользуется библиотекой, то есть назвала бы максимум, которого уже нет,
> ровно в тот момент, когда пользователь двигает ползунок. Второй довод дешевле, но тоже
> настоящий: граница нужна один раз, перед стартом, а поле на карточке заставило бы КАЖДОЕ чтение
> библиотеки нести состояние счёта.
>
> **Три числа, а не два.** `min_chapters` объясняет себя единицей — одна глава. `max_chapters`
> отдаётся уже подрезанным и по остатку, и по тому, сколько в книге осталось непереведённого:
> клиенту запрещено подрезать второй раз, иначе правило живёт в двух местах и расходится.
> `default_chapters` отдаёт платформа, потому что выбор предустановленного значения — это
> продуктовая политика («потратить всё» ↔ «одна глава»), а не презентация; клиент, выбравший его
> сам, принял бы это решение молча.
>
> **`max_chapters: 0` — легальный ответ** и значит «прогон начать нельзя вовсе». Клиент показывает
> исчерпанное состояние вместо шкалы. Это единственный случай, когда `default_chapters` тоже `0`.
>
> **Пересчёта «главы → деньги» на проводе нет ни в каком виде** (D39.84). Он живёт на платформе по
> оценке движка.
>
> **`ceiling_chapters` — обязательное поле старта и поле прогона.** Обязательное, потому что прогон
> без объявленного потолка тратит мимо той границы, которую человек вправе поставить ДО, а не
> узнавать после. Поле на `Run` — чтобы перезагруженный экран мог назвать выбранный колпак, а не
> забыть его.
>
> **409 на старте** отвечает и на «потолок больше не помещается»: границы читаются отдельным
> вызовом и могут сдвинуться между чтением и стартом.

## 4. К-таблица компаньона: статусы после этой правки

Заменить таблицу §4 компаньона на эту (изменения — колонка «Статус»):

| # | Кому | Статус после 0.2.0 |
|---|---|---|
| К-1 | владелец | **ЗАКРЫТ** (D39.100) — десять статусов приняты; одиннадцатым добавлен `paused` по К-8 |
| К-2 | автор контракта + бэкенд | **ОТКРЫТ** — кто ПОРОЖДАЕТ титул, по-прежнему не решено; К-3 закрыл продуктовую половину (метка из данных), механическая осталась |
| К-3 | владелец | **ЗАКРЫТ** (D39.100) — метка из данных книги; спека запрещает синтез «Глава {n}», `number` и `heading` оба nullable |
| К-4 | платформа | **ЗАКРЫТ** — счётчик пер-книжный, одно число на все книго-скоупные чтения и кадр потока; выражено прозой в `Revision` |
| К-5 | владелец | **ЗАКРЫТ** (D39.100) — `Progress.eta_seconds`, опциональное |
| К-6 | владелец | **ОТКРЫТ** — принцип принят (две ступени), карта «причина → фраза» ждёт В-3 |
| К-7 | платформа | **ЗАКРЫТ** — keyset-курсор на всех списках, дефолты 5000/1000/500, привязка к структурной эпохе |
| К-8 | владелец | **ЗАКРЫТ** (D39.100) — `paused` + `Run.paused_reason: credit_exhausted` |
| К-9 | владелец + автор контракта | **ОТКРЫТ** — отказ прескрина по-прежнему не выразим ни одним статусом |
| К-10 | автор контракта + бэкенд | **ОТКРЫТ** — `Chapter.units_done` так и не разведён по фазам; дерево глав показывает ноль всю черновую волну |
| К-11 | автор контракта | **ОТКРЫТ**, и половина стала фактом: `Note` по-прежнему не требует ни `chapter_id`, ни `unit_id`; сужение `BankDecision` для экрана — работа S5 |
| К-12 | платформа | **ЗАКРЫТ** — опрос, `202` + `Location`, `Retry-After` объявлен явно |
| **К-13** | **владелец + платформа** | **НОВЫЙ.** Достижение СОБСТВЕННОГО потолка прогона (`ceiling_chapters`) и исчерпание кредита аккаунта — это одно `paused_reason` или два? Сегодня значение ровно одно, `credit_exhausted`, и оно про кредит. Платформа берёт холд на сумму потолка до спавна, поэтому механически они могут совпасть — но это надо СКАЗАТЬ, а не вывести: пользователь, упершийся в собственный колпак, и пользователь, у которого кончились деньги, находятся в разных положениях, и фраза у них разная. Записано пометкой в `EventCeiling` |

## 5. Что фронт исправил в фикстурах и почему это надо знать автору контракта

- **Снят неснятый маркер `第二节：` из колонки оригинала.** Компаньон §2.3 фиксирует замером: чанкер
  ВЫРЕЗАЕТ маркер из текста, который видит модель. Формы, которую рисовала прежняя фикстура,
  движок для zh→ru не порождает — это был четвёртый экземпляр класса «фикстура выдумала форму».
- **Титул больше не вклеен в текст первого юнита фикстуры.** Метка живёт в `Chapter.heading`.
  Это НЕ решение К-2: фикстура просто перестала утверждать что-либо про открытый вопрос.
- **Ключ строки банка — непрозрачный `id` контракта.** Прежняя заплата из (`src`,`dst`,`kind`)
  роняла вторую строку полисемичного термина; в фикстуре теперь есть настоящая пара таких строк
  (青茅 в двух смыслах с разными окнами), и без `id` она видна как дефект сразу.

## 5-бис. Три правки спеки СВЕРХ списка промта — с основанием на каждую

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

1. **`Problem.title` получил то же ограничение, что и `detail`.** Было: запрет движкового текста
   стоял только на `detail`. Но клиенту при отказе нечего показать, кроме этих двух полей, и
   `title`, написанный для разработчика, становится фразой, которую читает человек. Теперь оба поля
   объявлены продуктовым языком: `title` — класс отказа, `detail` — конкретная фраза.
2. **«vocabulary of version 0.1» → «of THIS version».** Предложение осталось от 0.1.0 и после бампа
   стало враньём о собственном файле.
3. **`servers.description` перестал называть базовый путь непроверенным предложением фронта.**
   Платформа заехала, и её собственная ручка в промте записана как `GET /v0/usage`, то есть префикс
   подтверждён. Заодно сказано главное: фиксирован только префикс версии, хост — тот origin, что
   отдал приложение, и клиент, зашивший конкретный хост, никуда не разворачивается.

⚠ Пункт 3 — единственное место, где я опираюсь на промт, а не на код платформы: в её зону мне
ходить не велено. Если префикс на самом деле другой, это правится одной строкой.

## 6. Зависимости, которые эта правка НЕ закрыла

Прежний §3 компаньона в силе целиком, плюс одно уточнение:

- **Механизма поднятия потолка по-прежнему нет,** и теперь это записано в спеке жёстче:
  `ceiling_chapters` едет со СТАРТОМ прогона, изменить его контракт не умеет вовсе. Значит
  `resume` после стопа по потолку возвращает прогон в то же состояние, и спека прямо запрещает
  клиенту предлагать `resume` как лекарство от `paused`. Строка единого бэклога (126) остаётся
  открытой и становится блокером экрана S4.