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 + ФОРМА артефакта (пример вывода) · девиации с причинами · чего не сделал и почему. СТОП — приёмка оркестратора (адверсариальная, клеймы пере-проверяются исполнением).