From 2579cb82ae7dd38bbfede8619733ac53b1c169dc Mon Sep 17 00:00:00 2001 From: heaven Date: Sun, 16 Aug 2026 03:44:10 +0300 Subject: [PATCH] Issue the platform P7 session prompt: read surface on contract 0.3.0, machine error codes, forwards, grant zeroing, gated on the batch landing --- platform/docs/PLATFORM_P7_SESSION_PROMPT.md | 127 ++++++++++++++++++++ 1 file changed, 127 insertions(+) create mode 100644 platform/docs/PLATFORM_P7_SESSION_PROMPT.md diff --git a/platform/docs/PLATFORM_P7_SESSION_PROMPT.md b/platform/docs/PLATFORM_P7_SESSION_PROMPT.md new file mode 100644 index 00000000..57493b68 --- /dev/null +++ b/platform/docs/PLATFORM_P7_SESSION_PROMPT.md @@ -0,0 +1,127 @@ +# Промт: платформа, пак P7 — читающая поверхность по контракту 0.3.0 + модель ошибок + форварды (П-17, строка 169 единого) + +> Выдан оркестратором №17 16.08.2026 (очередь D39.133; входы — D39.134 п.4 · D39.135 п.2в · D39.138 · +> пинги №17 в зонном журнале). Запуск — по слову владельца, ПОСЛЕ лендинга батча 0.3.0 (§1). + +## 0. Какую проблему ты решаешь и что решит твой результат + +Платформа — control plane между веб-фронтом и движком перевода. К сегодняшнему дню построено всё +СТАТУСНОЕ и денежное: вход, кредиты с холдами, очередь и раннер, интейк книг, потребительская +половина шва с движком (события `events.jsonl` уже пишутся движком и материализуются в Postgres, +включая пер-юнитные разрешения). Чего нет — **читающей поверхности**: фронт не может прочитать ни +главы, ни юниты, ни замечания, ни банк, ни живой поток; из 16 операций контракта платформа отвечает +на 8. Из-за этого фронт живёт на моках и ЗАМОРОЖЕН, а центральный экран продукта (подпись банка) не +строится вовсе. Второе: причины отказов не существуют в машинном виде — сервер шлёт английскую фразу, +которую русский интерфейс печатает как есть. + +Твой пак делает платформу ЧИТАЕМОЙ и её отказы — машинными. Результат разблокирует разморозку фронта +и экран подписи. Контракт только что пере-согласован целостным ревью (research/28, принят D39.138) и +сломан минором 0.3.0 ровно для того, чтобы ты строил новые ручки СРАЗУ по правильной форме — не строй +по памяти о старой. + +## 1. ПРЕДУСЛОВИЕ — проверить до первой строки кода + +Нормативная спека — **канон `docs/architecture/14-api-contract/openapi.yaml`**, `info.version` +обязана быть **0.3.0**. Если там 0.2.3 — батч ещё не заленден: СТОП, пинг владельцу. ⚠ Зонное зеркало +`frontend/docs/api-contract/openapi.yaml` во фризе фронта может ОТСТАВАТЬ от канона — это известное +состояние; читать только канон. + +## 2. Зона и git (канон — CLAUDE.md; здесь напоминание) + +**Ты не коммитишь — лендит оркестратор.** Зона записи — только `platform/`. Прогресс, отчёт и +вопросы — ТОЛЬКО зонный журнал `platform/docs/platform-PROGRESS.md`. Чужие зоны read-only; чужие +незакоммиченные файлы (живой полигон: `eval/`, `docs/experiments/`) не трогать; `.env` не читать; +никаких `git add -A`/`reset`/`checkout`/переписывания истории. Ревью-гард D39.85: путь Go-модуля +платформы никогда не вкладывать под путь движка. + +## 3. Что читать (карта, ≤5 позиций) + +1. **Канон 0.3.0 + компаньон** (`docs/architecture/14-api-contract/`) — целиком: форма каждой новой + ручки уже решена там, не изобретай параллельную. +2. **`docs/research/28-contract-review.md`** §5 (состав правок и зачем) · §8/§8а (решения владельца: + классы конкретности отказов) · §5б (сеть: что строить, чего НЕ строить) · §9 (находки по твоей + зоне) + **D39.138 п.2** (ратификация; при конфликте побеждает нота). +3. **Свой журнал `platform-PROGRESS.md`** — три пинга №17 (15–16.08) и аддендум: там входы этого пака + (PD-104, форварды, протухшие тексты твоих доков) и попутные находки §9, которые ты судишь сам. +4. **Read-out поверхности движка** — пинг №15 в том же журнале (D39.122): манифест + `.manifest.json` (`tm-manifest-v2`), банк `.bank.json` + стоп-таблица `.bank-stop.json` + (пишутся атомарно, читать можно во время прогона); плюс твоя же таблица `unit_resolutions` + (миграция 00015) — источник юнитов/замечаний. +5. `CLAUDE.md` — гардрейлы; `docs/glossary.md` — жаргон. + +## 4. Состав пака — в этом порядке (что «РОВНО так», помечено; остальное — реши сам и аргументируй) + +**0. Рантбук деплоя живым `migrate` — end-to-end на дев-стенде ($0, первым шагом).** РОВНО так: +прогнать собственный `deploy/README.md` настоящим новым бинарём движка по каждой книге стенда +(`tmplatformctl books --migratable` → `tmctl migrate`) — это предусловие ПЕРВОГО выката (D39.134, +твой журнал честно фиксирует «живьём не гонялся»). Попутно починить мёртвый текст ошибки схемы в +`deploy/README.md:131` (движок теперь печатает токен `schema_mismatch found=N expected=M`, exit 13) +и комментарий-образец `cmd/tmplatformctl/runs.go:45` (зовёт голый `tmctl` из PATH — воспроизводит +тихий no-op старым бинарём); якорь П-1 в своём BACKLOG обновить. + +**1. Форварды 0.2.3 (РОВНО так, малые):** читать `BookIntake.title` (сегодня падает в «unknown field +is IGNORED» — `internal/httpapi/v0.go:369-376`, якорь-отправная точка, код первичен) · проецировать +`books.reject_reason` на провод (`v0.go:497` — «kept for an operator and never projected»). + +**2. PD-104 (РОВНО так, слово владельца 16.08):** `SignupGrantMicroUSD` дефолт → **0** (бета: +начисление руками через админ-CLI; возврат $5 — вместе с суточным потолком при появлении платежей) + +тест; регистр и протухшие «$5» в `PLATFORM_DIRECTION.md` §2 / BACKLOG П-7 — поправить. + +**3. Модель ошибок (Б-1/§8а) — ПЕРВОЙ из контрактной половины,** от неё зависят формы остальных ручек: +структура `Problem` по 0.3.0 (машинный `code` двухуровневый + `request_id` — значение уже штампуется, +`internal/reqid`), словарь причин класса 1 — из твоих же реальных веток `fail()` (конкретика +максимальная); класс 2 (прескрин/провайдер/фильтр) — ОДИН грубый код, без вариации между попытками. +`WWW-Authenticate` на 401; две причины 403 развести (нет `X-TM-Client` ≠ кросс-origin). + +**4. Читающая поверхность по 0.3.0 (ядро пака):** главы / юниты / замечания (с `id` и `created_at` — +форма 0.3.0) / банк (проекция сайдкаров движка + снимок стопа подписи `pending/complete`) / +`POST /bank/decisions` / **SSE-поток** в форме 0.3.0 (канал КНИГИ, кадры конца разбора и конца +прогона, `204` переподключению к завершённому, склейка ТОЛЬКО снимкам — `note`-класс не склеивать). +Сюда же сеть, шаги 1–2 §5б (строка 186): **gzip на текстовых ответах (НЕ на SSE)** и +`ETag`/`If-None-Match` → 304 на списочных GET. Совет-приор: ревизия у тебя уже читается одной +транзакцией со страницей (PD-163) — ETag из неё. + +**5. Правки построенного под 0.3.0:** `wireProgress` → один счётчик до остановки (Б-0; ⚠ колонки БД +и словарь шва с движком НЕ трогать — фазы остаются внутренним делом); `GET /capabilities` (Б-2: пары +из конфигурации · порог интейка · форматы · размеры страниц · версия контракта); подрезка `limit` до +максимума вместо сброса к дефолту (Б-10); трейлинг-части интейка → 400 вместо тихой потери + `Location` +на 201 + `Idempotency-Key` (Б-3); `blocked: {code, book_id}` на run-options/409 (В-6); отказ по +неподдерживаемой паре кодом на интейке (сегодня ja/en-книга умирает `failed`-ом на валидации движка +в конце пути); `Run.failure_reason` (Б-8 — словарь исхода у движка уже есть). + +**6. Свой регистр — судишь сам:** PD-201 (самолечение «поймал exit 13 → migrate → повтор» — движковая +половина ФИНАЛЬНА, можно строить); кандидаты PD-219 / PD-217 / PD-162; находки §9 research/28 +(незакрываемые расчёты — бюджет висения холда · флаг аккаунта сканом всех книг после PD-203 · +`ReadRunForSpawn` O(живых) · лимитер входа · сырой Go-текст в карантине) — каждой явную диспозицию: +берёшь / P8 с причиной / отклоняешь с причиной. Протухший баннер §3 `PLATFORM_DIRECTION.md` привести +к D39.132 п.2б (oapi-codegen — кандидат ПРИ ЭТОМ паке, sqlc — привязан к этому паку: **реши сам** по +обоим и аргументируй; для sqlc помни `overrides` на денежные типы). + +**Явно отложено в P8 (не тихо):** `PATCH /books/{id}` (title-only) + `DELETE` + `GET /runs/{id}` · +эскроу П-18 (денежный промт) · всё, что не влезло, — списком с причинами в отчёте. + +## 5. Нормы исполнения + +- **Самопроверка исполнением:** батарея `make check` + ОБА гейта (`TM_PLATFORM_TEST_DSN` + + `TM_PLATFORM_TEST_ENGINE_BIN`/`_BOOK_TEMPLATE`), скипов 0 — пропуски СПИСКОМ в отчёт; дифф + `^func Test` — исполнением, не памятью; живые пробы новых ручек против дев-стенда (сид P6). +- **Заявление = команда:** каждое число/категорическое утверждение отчёта — с командой; приёмка + пере-ранит. +- **Записка-план по §4** (D39.121): каждый пункт (0–6 и отложенные) — строка «исполнено, где / + отказ, почему»; сдача = все с диспозицией, комплектность против заказа механически. +- **Шов:** если касаешься ЛЮБОГО канала движка — сначала инвентарь ВСЕХ его каналов и кодов чтением + чужого кода, не по памяти (урок D39.132: `status --json` упустили все, кроме панели приёмки). +- **Предметная ось зоны:** индустриальный первоисточник прежде велосипеда — RFC 9457 (problem+json), + WHATWG SSE (204/переподключение), RFC 9110/9111 (условные запросы, `Vary` при gzip); stdlib/устоявшаяся + библиотека прежде своего. Право добавить свою ось или снять эту — с аргументом. +- **Деньги:** пак денег не двигает (PD-104 — константа гранта); если что-то денежное всё же затронул — + два независимых пути счёта из сырого леджера. +- **Obstacle reporting** — обязательная секция отчёта: что НЕ удалось, что не проверено. +- **Канал вопросов:** непонятно / промт конфликтует с кодом, спекой или доками → пинг оркестратору + через владельца, НЕ интерпретация. Право сказать «этого делать не надо» — с аргументом. + +## 6. Эхо-протокол и сдача + +Первый деливерабл — ≤10 строк «что я понял: скоуп / инварианты / не-делать». Сдача: отчёт в +`platform-PROGRESS.md` (записка-план · команды батареи · живые пробы · obstacle reporting · диспозиции +§4.6), дерево незакоммиченное, регистру дефектов — новые строки по находкам. Без саги.