textmachine/docs/BACKEND_CONTRACT_BLOCKERS_SESSION_PROMPT.md

# Промт бэкенд-сессии: ДВИЖКОВЫЕ БЛОКЕРЫ КОНТРАКТА API (строки 99 · 100 · 101 · 125 · 145)

**Выдан 08.08.2026, оркестратор №15, по слову владельца 08.08 (D39.119).** Ты — бэкенд-сессия. Зона записи: `backend/` (код+тесты+puml тем же паком) + отчёт `docs/archive/reports/CONTRACT_BLOCKERS_2026-08-XX.md` (дату проставь сам) + пинг в `docs/PROGRESS.md` секция «Бэкенд» (ТОЛЬКО append своей секции; CURRENT-STATE и чужие секции не касаться; `git status` до и после). «Строка N» = ID строки ЕДИНОГО БЭКЛОГА (таблица «Бэклог» в `docs/PROGRESS.md`). **НЕ коммитишь** — дерево готовишь, лендит оркестратор. **Деньги: $0** — платных вызовов нет вообще. ⚠ Живую параллельную зону определяй `git status` + CURRENT-STATE в начале сессии; на выдачу промта живой сосед — полигон эксп-22 (`eval/tenant_panel/`, `docs/experiments/22-tenant-panel.md`, секция «Полигон»). Чужого не трогать и не «прибирать» (инцидент D39.113 стоил семи файлов).

**Первый деливерабл — эхо-блок ≤10 строк ПЕРВЫМ СООБЩЕНИЕМ сессии** (как понял: пять работ · инварианты · что вне скоупа; подтверждения не жди — работай дальше).

## Онбординг: какую проблему решаем и что решит твой результат

TextMachine — движок художественного перевода больших книг (Go, `backend/`), поверх которого строятся платформа (SaaS control plane, `platform/`, отдельный процесс — движок дёргается процессами, D39.81) и веб-фронт (ридер-IDE). Контракт API фронт↔платформа ратифицирован (OpenAPI 0.2.0, `docs/architecture/14-api-contract/`), но пять поверхностей ДВИЖКА, из которых платформа должна собирать ответы, не существуют — и это гейтит первые реальные экраны фронта (библиотека/прогресс/подпись банка) и управляемый потолок прогона. Твой пак строит ровно эти пять поверхностей. Всё — файлы/CLI движка, которые платформа ЧИТАЕТ: **сетевых поверхностей в движке НЕ появляется** (сервер не пишется — инвариант D39.81, строка 96).

Карта чтения (≤5, СВЕРХ стандартного онбординга роли по CLAUDE.md — `backend/README.md` + `03-implementation-notes.md` через баннер): CURRENT-STATE → строки 99/100/101/125/145 бэклога (тела строк несут замеры и якоря; этот промт их не дублирует) → `docs/architecture/14-api-contract/openapi.yaml` + компаньон-README (какие ответы платформа собирает из твоих поверхностей) → `12-go-style-notes.md` §0. Жаргон — `docs/glossary.md`. **Стенд:** описание и книги — `backend/README.md`; замер строки 100 — на большой книге стенда (та же, что в замере строки: 23 МБ, ~2284 раздела); `~/books/gu-zhenren/coldrun-a/` — замороженный эталон, ТОЛЬКО чтение.

## Работы (форму КАЖДОГО артефакта фиксируешь в отчёте; «реши сам» = реши и аргументируй; ⚠ все `file:line` ниже — ОТПРАВНЫЕ ТОЧКИ, код первичен: протухший якорь — сверка, не блокер)

1. **Строка 99 — пофазный прогресс.** Индикатор «готово N/M» стоит 0% всю черновую волну: unit=done только при всех draft-строках + edit-строке. Данные уже есть (`chunk_status` — строка-на-стадию; status уже делит стадии по волнам). Вывести пофазные счётчики — ДВА отдельных: draft N/M и edit N/M (текстовая форма вывода — реши сам) — в StatusReport И в `tmctl status --json`, БЕЗ миграции схемы. Форма JSON-полей — реши сам, но так, чтобы платформа могла собрать `progress` контракта без домыслов; назови её в отчёте явно.
2. **Строка 100 — персист манифеста глав/чанков.** Сейчас каждый read-вызов заново ингестит и режет книгу (`status.go` `bookChunks`, ~1.4–1.5 с CPU на книге 23 МБ; redrive — дважды за вызов). Нужен персист манифеста (главы/чанки + `chunker_version` из снапшота + хеш источника) со СТАБИЛЬНЫМ id главы — фундамент дерева глав фронта (книга ~2284 раздела). Дизайн реши сам с двумя жёсткими требованиями: (а) манифест обязан пережить смену чанкера — `--resnapshot` его пере-строит, а стабильность id главы через пере-чанковку либо гарантируется, либо ЧЕСТНО объявляется границей (что именно инвалидируется — в отчёт); (б) read-пути (`status`/`report`) перестают резать книгу заново.
3. **Строка 101 — машиночитаемая таблица подписи банка.** Сейчас: кап-20 в stdout (`bankStopStdoutCap`, `cmd/tmctl/render.go`) + текстовый сайдкар `.bank-stop.txt`. Нужен машиночитаемый сайдкар ПОЛНОЙ таблицы (JSON; поля = те же, что текстовая, включая новые Signals/Invented/Conf/Conventions/Contradicts из D39.118). ⚠ Ловушка «подпись ≠ UPDATE»: контракт подписи пишет в файлы-источники, банк пересобирается (`seeding.go`, `glossary.go`) — сайдкар это ЧТЕНИЕ, семантику подписи не менять.
4. **Строка 125 — экспорт-артефакт банка.** Банк живёт в приватном SQLite движка, платформе он закрыт (D39.85). Нужен экспорт-файл ПОЛНОГО банка тремя статусами (approved/draft/auto) в каталоге книги — источник канала `/bank` контракта. Момент записи: МИНИМУМ — на каждом банк-стопе и на завершении прогона; чаще (границы стадий) — реши сам по цене. Форму (один файл/пер-статус, поля) реши сам по контракту 14; отличие от п.3 держи явным: 101 — таблица ПОДПИСИ (решения владельцу), 125 — экспорт СОСТОЯНИЯ банка.
5. **Строка 145 — потолок НА ПРОГОН аргументом.** Сегодня потолок приходит только из `book.yaml` (`Ceilings.BookUSD` → `stagerun.go:480`); платформа для управляемого потолка (D39.110) была бы вынуждена править конфиг книги — смешение зон против D39.81. Сделай приём потолка аргументом запуска (флаг `tmctl translate` и/или ENV — реши сам; вход через `parseInvocation`), семантика: значение в USD, действует ТОЛЬКО на этот прогон, `book.yaml` НЕ пишется, аргумент ПЕРЕКРЫВАЕТ книжный `book_usd`. Валидатор Р7 (`internal/config/book.go:251`) не правится — ноль/отрицательное аргументом = отказ запуска. Цена нулевая: `Ceilings` в BriefHash не входит — предъяви это тестом/грепом в отчёте (снапшоты и ре-билл не двигаются). Приор (опровергается кодом): resume после ceiling-стопа с БОЛЬШИМ аргументом = штатное «поднятие потолка» (`stagerun.go` ждёт ровно этого) — проверь, что путь работает, отдельной правки не жди.

**Вне скоупа:** строка 49 (annot-v1 экспорт замечаний — следующий пак) · строка 102 (внешний TraceID) · любые сетевые поверхности · правки семантики подписи/банка. **Инварианты:** движок = процесс-на-прогон, EXCLUSIVE flock; голден без пере-захвата (эти работы wire не двигают — если что-то захотело двинуть снапшот/RequestHash, это СТОП и пинг, не решение).

## Самопроверка и СТОП

Гардрейлы: `backend/.env` НЕ читать · PUML не рендерить. Мандат 12.07: ревью ИСПОЛНЕНИЕМ кода+артефактов — каждый новый файл-артефакт открой и прочитай глазами. **Генерация артефактов — только $0-путями:** read-пути (`status`/`report`) на стенд-книге · тесты с mock-провайдером (образец — e2e-тесты банк-пака) · реплей существующих чекпойнтов; платный прогон ЗАПРЕЩЁН, `coldrun-a` — только чтение. Дифф `^func Test` до/после — ИСПОЛНЕНИЕМ (grep), не памятью; список в отчёт. `make battery` зелёная ЦЕЛИКОМ (вкл. lint — урок D39.118). Перф-клейм строки 100 — замером до (HEAD-поведение в начале сессии) / после, на стенд-книге. Каждое ЧИСЛО отчёта — с командой, которой оно получено (приёмка пере-ранит). **Канал вопросов:** непонятно / промт противоречит коду-докам / форма артефакта не однозначна по контракту 14 → СТОП по ЭТОМУ пункту (остальные работы продолжай) и вопрос — строкой в свой пинг PROGRESS «Бэкенд» плюс устно владельцу (он релеит оркестратору); НЕ тихая интерпретация. Отчёт: по каждой работе — что сделано с `file:line` + ФОРМА артефакта (пример вывода) · девиации с причинами · чего не сделал и почему. **СТОП — приёмка оркестратора** (адверсариальная, клеймы пере-проверяются исполнением).