diff --git a/platform/docs/PLATFORM_P5_SESSION_PROMPT.md b/platform/docs/PLATFORM_P5_SESSION_PROMPT.md new file mode 100644 index 00000000..5b4177df --- /dev/null +++ b/platform/docs/PLATFORM_P5_SESSION_PROMPT.md @@ -0,0 +1,141 @@ +# Промт: платформа-сессия P5 — `POST /books` (П-9) + стоп/резюм (PD-140) + наблюдаемость (П-11) + +Ты — платформа-сессия TextMachine. Зона записи — **только `platform/`**; сессия НЕ коммитит — +дерево готовит и передаёт на лендинг оркестратору. Онбординг по `CLAUDE.md`; итоги, вопросы и +предложения на ратификацию — ТОЛЬКО зонный журнал `platform/docs/platform-PROGRESS.md` +(в `docs/PROGRESS.md` платформа не пишет). В дереве живут незакоммиченные файлы ЧУЖИХ зон — +полигон (`eval/*`, ЖИВОЙ платный прогон: ничего там не запускать) и, возможно, фронт +(`frontend/*`) и бэкенд; начни с `git status`, чужое не трогать. Чужой код ЧИТАТЬ для сверки +можно и нужно (норма D39.115 п.3), писать — нельзя. LLM-провайдеров пак не зовёт, $0. + +> **Онбординг-блок (проблема).** Раннер P4 построен и принят (D39.123): транзиентные +> systemd-юниты, очередь River с холдом-до-спавна, реконсилятор, тейлер, пять ручек `/v0`. +> Но книги заводятся только дев-инструментом `tmplatformctl book add`, а единственная ручка +> контракта, которую P4 сознательно не взял, — `POST /books` (граница промта, П-9 зонного +> бэклога): это не «ещё один хендлер», а хранилище файла, статусы `uploading/parsing/rejected` +> (в схеме контракта есть, ни одним писателем не заполняются), каталог проекта движка и +> пер-маршрутный потолок тела (PD-72 закрывается ВМЕСТЕ с ручкой, не раньше). Вторая дыра: +> ручек стопа/резюма нет (PD-140, `Service.Stop` не подключён) — человек не может остановить +> прогон. Третья: наблюдаемости нет вовсе (П-11: ни метрик, ни трейсинга; глубина очереди и +> возраст холдов читаются только SQL-ем), и конфигурация из 27 env-переменных не печатается +> на старте (PD-114). Фронт ждёт `POST /books` для экрана загрузки S4 (Ф-26 его бэклога). + +## Обязательное чтение до кода (порядок; читать, не грепать) + +1. `platform/docs/platform-PROGRESS.md` — «Текущее состояние» + разделы P4 и дофикса целиком + (формы раннера: холд+прогон+попытка+очередь одной транзакцией · порядок `lockBook` · + `MaxAttempts:1` · ExecStopPost-маркер · `IsTransient` · PD-158/PD-159) + пинги оркестратора + в хвосте (формы артефактов движка: манифест `tm-manifest-v2`, `unit.id` с тегом разреза). +2. `platform/BACKLOG.md` (П-9 дословно — это заказ) + `platform/docs/DEFECT_REGISTER.md`: + PD-72 · PD-140 · PD-152 · PD-153 · PD-113 · PD-114 · PD-115 · PD-122 · PD-162 · PD-165 · + PD-169 — и все открытые строки по разу. +3. Контракт (канон): `docs/architecture/14-api-contract/openapi.yaml` — `POST /books` (multipart, + `BookIntake`), статусы `uploading/parsing/rejected/not_started`, `POST /runs/{id}/stop` / + `resume` (409 при неполной подписи банка), `503`-класс; компаньон-README §3. +4. `platform/docs/ENGINEERING_STANDARDS.md` (критерии приёмки зоны) + `STACK_DECISIONS.md` + (пины, linger-модель §15, рецепт стенда с живым PG без root, ставка §20). +5. Движок (read-only, для стыка): `backend/cmd/tmctl/main.go:30-52` (exit-контракт; SIGTERM + ловится и выходит кодом 1) · `tmctl manifest` ($0-команда, строит дерево до первого прогона, + первое касание создаёт БД проекта — D39.122) · D39.110 п.2(б) (потолки `book.yaml` платформа + НЕ правит). + +По всем задачам — прогон в отчёте; **молча пропустить задачу нельзя**: сделано / диспозиция / +вопрос в журнал. + +## Задачи + +### 1. `POST /books` — загрузка книги (П-9; закрывает PD-72) + +- Multipart-приём с **пер-маршрутным потолком тела** (отраслевой stdlib-путь прежде велосипеда: + `http.MaxBytesReader` и потоковый разбор, не буферизация всего в память) + тест потолка — + PD-72 закрывается этим же паком. +- **Хранилище:** куда ложится исходник, кто и когда его чистит при отказе разбора и при удалении + (смежно PD-162: удалённый каталог книги сегодня клинит прогон с открытым холдом — реши хотя бы + диспозицией); относительные пути и `StateDir`-дисциплина зоны в силе. +- **Статусы жизненного цикла:** `uploading → parsing → not_started | rejected` получают ПИСАТЕЛЕЙ; + разбор = вызов движка ($0-команда `tmctl manifest` — она и создаёт БД проекта); отказ разбора = + `rejected` с продуктовой причиной без протечки внутренностей (ПТ-33); read-model один — книга, + заведённая дев-интейком, и книга, загруженная ручкой, читаются одинаково. +- ⚠ **Развилка, ГЕЙЧЕНАЯ ратификацией: кто пишет `book.yaml` при интейке.** D39.110 п.2(б) — + «платформа `book.yaml` не правит» (контекст решения: потолок прогона не пишется в данные + движка). Создание НОВОГО каталога книги при аплоаде требует, чтобы кто-то положил стартовый + `book.yaml` (языки/жанр из `BookIntake`, потолки из деплой-шаблона). Спроектируй форму + (например: генерация из шаблона деплоя при интейке как отдельная операция, после которой файл + принадлежит оператору и платформа его больше не трогает), запиши варианты с ценой и **отправь + вопросом в журнал ДО стройки этой половины** — ратифицирует оркестратор. Остальное (приём, + потолок тела, хранилище, статусы, тесты) этой развилкой НЕ гейчено. +- `BookIntake.title` в спеке нет (черновик фронта ждёт ратификации) — поле НЕ выдумывать; + разбор даёт название, как даёт. + +### 2. Стоп и резюм прогона (PD-140) + +- Ручка стопа по контракту (точный путь и формы — ИЗ СПЕКИ, не отсюда): остановка юнита через + systemd (SIGTERM, graceful; движок дописывает чекпойнты и выходит), холд сеттлится штатным + реконсилятором. +- ⚠ Ограничение до эмиттера (строка 103 движка + 165): движок ловит SIGTERM и выходит кодом 1 ⇒ + ExecStopPost-маркер честно скажет `exited/1`, и по одному маркеру стоп неотличим от аварии + (PD-152). **Кандидат-дизайн, оцени и предложи:** платформа ЗНАЕТ, что стоп её — записать + намерение стопа (строкой в Postgres той же транзакцией, что команда стопа) ДО SIGTERM и + классифицировать исход маркера по нему; это дискриминатор своей стороны, не гадание по + exit-коду. Если берёшь — пин на гонку «стоп против самостоятельного финиша». Различение + «потолок vs авария» остаётся за эмиттером — на него не замахиваться. +- `resume` по контракту (после банк-стопа — 409 при неполной подписи; после стопа — новый прогон + с остатком бюджета, механика перезапуска реконсилятора уже есть — переиспользовать, не + дублировать). Семантика денег прежняя: PD-158/PD-159 не трогать. +- Обе ручки — в аллоулисте форм контракта, wire-проверки в духе приёмки P4. + +### 3. Наблюдаемость минимумом (П-11) + печать конфигурации (PD-114) + +- Метрики зоны: глубина очереди · возраст самого старого открытого холда · число прогонов в + карантине · отставание тейлера · длительность/бюджет свипа (PD-169 смежно). Форму выбрать по + отраслевой практике с обоснованием и точным пином в `STACK_DECISIONS` (stdlib `expvar` против + prometheus-клиента — сравнить, решить, записать; PD-115: внешний эталон на ось наблюдаемости + назвать). +- Печать эффективной конфигурации на старте с редакцией секретов (PD-114 — задача уже + переформулирована ратификацией; деньги и argv в INFO по-прежнему не текут, PD-99). + +### 4. Докс-минорка зоны: `DEFECT_REGISTER.md` секциями + +Пинг оркестратора №16 (хвост зонного журнала): разложить реестр на секции (open по весу · +accepted-risk · fixed по эрам паков), сохранив построчную форму `| PD-N | … |`; +`python3 docs/scripts/counts.py --check` обязан остаться зелёным (прогнать). + +## Что НЕ делать + +- Эскроу/`uncertain`/`closing` (строка 136 единого бэклога) — отдельный денежный промт; формулу + потолка (PD-158), SpendBound (PD-159) и ставку $0.03 не трогать. +- Эмиттер-сторону движка не строить и не ждать: тейлер уже умеет ждать файла; словарь `events.go` + не менять (движок ответит диффом со своей стороны). +- П-2 (брокер рейт-лимитов), платёжный провайдер, удаление аккаунта (PD-107 — гейт), счётчик + ревизии области (PD-122 — гейт «ручка удаления») — не в скоупе. +- Контракт не править: расхождение/нехватка — вопросом владельцу контракта через журнал + (прецедент 503/PD-112). +- Тесты и пины не подгонять под зелень (D39.121); `migrations.sha256` — только по правилам зоны. +- `git add`/`git commit` не делать — дерево передаёт на лендинг оркестратор. + +## Отчёт и приёмка + +- Батарея `make check` с живым PostgreSQL 18.4 под `-race`: 0 FAIL, линтер 0 issues, скипов 0, + `make vuln` чист; счётчик тестов — диффом `^func Test` исполнением, удалённых ноль. +- **Каждое новое свойство — с пином, каждый пин — с посадкой** (правило PD-83 зоны); посадки в + копии зоны вне репозитория, счёт «поймано/пережило» честно, пережившие не подчищать. +- **Живая проба на боевом бинаре** (фейковый движок как в P4): аплоад настоящего файла → + статусы `uploading/parsing/not_started` сменяются → книга видна в библиотеке и стартует прогон; + отказ разбора → `rejected` с продуктовой причиной; стоп живого прогона → юнит погашен, холд + сеттлится, статус по выбранному дизайну; метрики читаются; потолок тела отбивает большой файл + честным кодом ответа. +- Wire-сверка новых ручек с каноном спеки (форма ответов/ошибок problem+json, аллоулист полей). +- **Мандат самопроверки:** ревью ИСПОЛНЕНИЕМ + адверсариальное ревью диффа (author≠reviewer); + после тяжёлого ревью — записка-план «ID → статус → улика» (D39.121). Клеймы — с командой рядом; + перед сдачей перечитать последний абзац отчёта; комплектность против промта — механически. +- **Предметные оси самопроверки** (D39.120): (1) индустриальный первоисточник/stdlib прежде + велосипеда (multipart, метрики — назвать эталон); (2) деньги: ни один новый путь не создаёт + и не освобождает холд мимо ратифицированных форм; (3) жизненный цикл: каждая ветка нового + статуса достижима и покрыта (недостижимая ветка = дефект, класс PD-117…121). +- **Канал вопросов — зонный журнал, и у сессии есть право оспорить ПОСЫЛКУ** (D39.47 п.4): + замер или чтение кода, бьющие по основанию задачи (не по исполнению), обязывают остановиться + и поднять вопрос — а не выдать формально требуемый артефакт; тихая интерпретация запрещена. +- **Самоверификация интервально, не одним прогоном в конце:** после каждой задачи — сверка + с промтом и прогон гейтов; красное чинится до перехода к следующей. +- Отчёт — разделом в `platform-PROGRESS.md`: таблица задач · развилка book.yaml вопросом · + дизайн стопа · закрытые/заведённые PD-строки. Реестр и счёт — скриптом, не руками. diff --git a/platform/docs/platform-PROGRESS.md b/platform/docs/platform-PROGRESS.md index 40c1d757..59be3388 100644 --- a/platform/docs/platform-PROGRESS.md +++ b/platform/docs/platform-PROGRESS.md @@ -15,9 +15,12 @@ - **Регистр — 171 строка** (`python3 docs/scripts/counts.py`): 124 закрыто · 1 закрыт ратификацией (PD-59) · 3 риском · 43 открыто (**1 major — PD-113**: стоп по потолку отдаётся `failed` до эмиттера; после PD-158 его цена выросла — потолок срабатывает ровно на исчерпании холда). -- **АКТИВНОГО промта зоны НЕТ.** Следующий — по слову владельца; кандидаты: стоп/резюм-ручки - (PD-140, закроют и половину «failed»-лжи вместе со строкой 165 движка) · эскроу/uncertain - (строка 136 единого бэклога) · POST /books (П-9). +- **Промт P5 ВЫДАН оркестратором 10.08** (`PLATFORM_P5_SESSION_PROMPT.md`, D39.128): П-9 + `POST /books` (+PD-72 потолок тела; развилка «кто пишет book.yaml при интейке» — вопросом в этот + журнал ДО стройки той половины) · стоп/резюм-ручки PD-140 (различение «потолок vs авария» — + за эмиттером движка, строки 103/165, его промт выдан параллельно) · наблюдаемость П-11 + + печать конфигурации PD-114 · DEFECT_REGISTER секциями (пинг №16). Запуск — по слову владельца. + Эскроу/uncertain (строка 136) — следующим денежным промтом, НЕ в P5. - Эры P0–P3 (вход OIDC · кредиты · админ-CLI · деплой · фикс-паки) — исполнены и залендены (D39.107/109/112/114); разделы — в [archive/platform-PROGRESS-P0-P3.md](archive/platform-PROGRESS-P0-P3.md). Стек и рецепт стенда — `STACK_DECISIONS.md`; критерии приёмки — `ENGINEERING_STANDARDS.md`.