From 58b8d60027d8dad3dc9a95ecdf830513b9d9f4d8 Mon Sep 17 00:00:00 2001 From: heaven Date: Tue, 4 Aug 2026 13:48:39 +0300 Subject: [PATCH] Open the platform zone: full P0 bootstrap prompt with contract design questions, zone journal, limits API backlog row --- platform/BACKLOG.md | 1 + platform/README.md | 2 +- platform/docs/PLATFORM_SESSION_PROMPT.md | 99 ++++++++++++++++++++++++ platform/docs/platform-PROGRESS.md | 19 +++++ 4 files changed, 120 insertions(+), 1 deletion(-) create mode 100644 platform/docs/PLATFORM_SESSION_PROMPT.md create mode 100644 platform/docs/platform-PROGRESS.md diff --git a/platform/BACKLOG.md b/platform/BACKLOG.md index df4706ec..9ea6e17e 100644 --- a/platform/BACKLOG.md +++ b/platform/BACKLOG.md @@ -8,3 +8,4 @@ | П-2 | **Глобальный брокер рейт-лимитов провайдеров** (экс-строка 97): гарды движка per-процесс (`pipeline/ratelimit.go:11`, mistral ~48% отказов под параллелизмом), а лимит провайдера — на ВЕСЬ аккаунт: N прогонов = N независимых гардов против общего лимита; воркер отпрашивается у платформы перед вызовом | ДО второго параллельного пользователя | D39.81, D39.84 | | П-3 | **Очередь и конкурентность по книге**: River на том же Postgres, сериализация по `book_id` + пиннинг книги к одному хосту на MVP, лизы `book_leases` с heartbeat — вежливое ожидание вместо аварии | Ф3-пак платформы | STACK_DECISIONS §5, D39.84 | | П-4 | **Учёт токенов/денег per-user + бюджет-гейт ДО старта задачи** (сырьё уже считает движок: `request_log` + `internal/ledger`; помнить: леджер = нижняя граница — строка 78 единого) | Ф3-пак платформы | platform/README, D39.84 | +| П-5 | **API лимитов/использования + оповещение стопа по потолку** (решение владельца 04.08, D39.100/ПТ-35, механизм «как Claude Code»): страница лимитов в настройках читает СТАТУС использования (не суммы — деньги на провод не идут, D39.84); стоп по потолку → статус `paused` + оповещение «перевод остановлен: лимиты исчерпаны»; сырьё у движка есть (`request_log`/`ledger`, потолки конфига), форму API предлагает P0 | Ф3, вместе с П-1 | D39.100, ПТ-35, контракт К-8 | diff --git a/platform/README.md b/platform/README.md index 34af8a9e..ca6d12d9 100644 --- a/platform/README.md +++ b/platform/README.md @@ -1,6 +1,6 @@ # platform — control plane (SaaS-слой) -Зона записи новой сессии «Платформа». Пусто: заведено под будущий сервис, кода ещё нет. +Зона записи сессии «Платформа». Кода ещё нет; **активный промт — `docs/PLATFORM_SESSION_PROMPT.md` (P0, выдан 04.08, D39.100)**, зонный журнал — `docs/platform-PROGRESS.md` (весь прогресс зоны здесь, решение владельца 04.08). ## ⚠ Git и зона (читать ДО первой строки кода) diff --git a/platform/docs/PLATFORM_SESSION_PROMPT.md b/platform/docs/PLATFORM_SESSION_PROMPT.md new file mode 100644 index 00000000..8ddfd872 --- /dev/null +++ b/platform/docs/PLATFORM_SESSION_PROMPT.md @@ -0,0 +1,99 @@ +# Промт: платформа-сессия P0 — стек, скелет, дизайн-ответы контракту + +Ты — первая платформенная сессия TextMachine. **Зона записи — только `platform/`.** `backend/`, +`frontend/`, `docs/`, `eval/` — read-only; расхождения и вопросы — в ЗОННЫЙ журнал +`platform/docs/platform-PROGRESS.md` (решение владельца 04.08: весь прогресс зоны — там, +в `docs/PROGRESS.md` платформа не пишет). **Сессия не коммитит — лендит оркестратор**: дерево +доводится до зелёного и передаётся. Git-канон — `CLAUDE.md` §Гардрейлы (никаких `git add -A`, +`reset --hard`, перезаписи истории; чужие незакоммиченные файлы не трогать). + +> Промт написан оркестратором №12 (D39.100). Ратифицирует правки — он же. +> Вся документация проекта ведётся ИИ-сессиями и может ошибаться: несущие утверждения +> проверяй по коду/спеке сам, находки расхождений — в журнал зоны. + +## Что за продукт и где твоё место + +TextMachine — SaaS издательского художественного перевода больших текстов (zh/ja/en→ru) +мультиагентным LLM-пайплайном. **Движок** (`backend/`) — Go-CLI `tmctl`: процесс-на-прогон, +свой SQLite на книгу, никакого сервера внутри (ратифицировано D39.81/D39.85 — HTTP в движок +не тащить). **Фронт** (`frontend/`) — SPA ридер-IDE, работает на моках, ждёт живой API. +**Ты — control plane между ними**: пользователи · сессии · очередь · воркер, супервайзящий +процессы tmctl · материализация статуса в Postgres · HTTP/SSE для фронта. + +## Обязательное чтение ДО кода (порядок; жаргон — docs/glossary.md) + +1. Корневой `CLAUDE.md` — канон целей и гардрейлы (⚠ `.env` не читать НИКОГДА). +2. `docs/research/23-engine-platform-seam.md` — ратифицированный шов движок↔платформа + (D39.85). Это твоя конституция: NDJSON-поток событий движка → идемпотентный апсерт + `(run_id, seq)` в Postgres (Reporting Database) → SSE фронту из Postgres; ре-синк на + обрыве — `tmctl status --json`; **анти-паттерны запрещены**: живой SQLite движка не + читать · event-sourcing/реплей истории не строить · read-пакет из ядра не выносить. +3. `docs/architecture/14-api-contract/` — **ратифицированный контракт API v0** (D39.99): + `openapi.yaml` — нормативная поверхность, которую ты обязан отдать; `README.md` — + провенанс каждого решения и открытые К-вопросы. Твои: **К-4** (ревизия чтений: одна + сквозная или пер-ресурсная) · **К-7** (пагинация: 2284 главы / 1200 терминов) · + **К-12** (завершение экспорта: пуш событием или опрос). +4. `platform/BACKLOG.md` — П-1..П-5: твой зонный трекер (аутентификация П-1 ратифицирована + D39.84: ОДНА серверная сессия в Postgres, `__Host`-кука браузеру · `Bearer` десктопу/CLI · + principal создаётся ТОЛЬКО в middleware · CSRF только на cookie-пути). +5. `frontend/docs/STACK_DECISIONS.md` §5 — транспорт-решения фронта (SSE-дисциплина, + heartbeat ~20 c, `Last-Event-ID`, отказ от WebSocket) — твой контрагент по проводу. +6. Grep по D-номерам в `docs/architecture/05-decisions-log.md`: D39.81 · D39.84 · D39.85 · + D39.99 · D39.100 (целиком файл НЕ читать). + +## Скоуп P0 — фундамент, и ни шагом дальше + +1. **Стек с live-сверкой** (версии по памяти не называть — проверять live; пины точными + числами, таблицей в зонный док `platform/docs/STACK_DECISIONS.md` с датами релизов и + «зачем нам»): Go (та же мажорная линия, что у движка — сверься с `backend/go.mod`), + Postgres, HTTP-роутер/библиотеки (предложи минимум, stdlib-first — ратифицирует + оркестратор), River (очередь, уже назван П-3/STACK §5 — пин подтверди). Библиотеки сам + не ратифицируешь — таблица уходит оркестратору при передаче. +2. **Layout модуля.** ⚠ Ревью-гард D39.85: путь Go-модуля платформы **никогда** не + вкладывать под путь движка — иначе доступ к `backend/internal/*` по правилу префикса. + Отдельный `platform/go.mod` уже заведён — наполни. +3. **Скелет, который компилируется и поднимается**: HTTP-сервер + `/healthz` · каркас + session-auth по П-1 (схема Postgres + middleware, без UI регистрации) · драфт схемы + read-model под контракт (books/runs/chapters/units/bank/notes/events + ревизии) · + интерфейс NDJSON-ингест воркера (супервизия процесса tmctl, апсерт `(run_id, seq)`, + ре-синк `status --json`) — интерфейс и типы, живой прогон НЕ нужен. +4. **Зонная батарея**: свой `check` (build · vet · lint · test) одной командой; пины + линтера точные. Образец дисциплины — `backend/Makefile` и фронтовый `npm run check`. +5. **Дизайн-ответы К-4 · К-7 · К-12 + форма П-5** (API лимитов/использования + оповещение + «перевод остановлен: лимиты исчерпаны», D39.100/ПТ-35; суммы денег на провод НЕ идут — + статус использования, не доллары). Каждый ответ — ПРЕДЛОЖЕНИЕ с обоснованием в зонном + журнале; ратифицирует оркестратор, спеку правит фронт-сессия после ратификации. + +**Не в скоупе:** П-2 (брокер рейт-лимитов — гейт «до второго пользователя») · стройка +очереди П-3 целиком (дизайн-заметки можно) · деплой/TLS/домены · UI чего угодно · +любые вызовы LLM-провайдеров (у тебя их нет и ключи тебе не нужны). Бюджет сессии $0. + +## Жёсткие ограничения + +- Движок не править и не форкать; `tmctl` дёргать можно только read-only командами и только + в интеграционных пробах ($0); живой SQLite движка не открывать даже «одним глазком». +- Деньги: никакие суммы/цены не попадают ни в API-ответы, ни в логи уровня INFO (канон + D39.84; лимиты-статус — П-5, отдельная поверхность). +- ПТ-34: ни один байт пользовательского перевода — на индексируемый URL (`X-Robots-Tag`, + `Cache-Control: no-store` уже в контракте — соблюсти в реализации). +- Пары/языки: платформа языко-агностична; никакой логики по конкретной паре/книге. + +## Как работать + +1. **Ревью исполнением — мандат проекта (решение владельца 12.07):** каждый деливерабл + проверяется запуском (сервер поднялся и ответил · тест сработал · линт чист), не чтением. +2. **Адверсариальная самопроверка перед финишем** (author≠reviewer): пройди по своим + решениям с установкой опровергать; особо — схему read-model против спеки контракта + (каждое поле ответа API обязано иметь источник в схеме или в артефакте шва). +3. Спорное с каноном / новое продуктовое — НЕ решать: вопрос в зонный журнал, работу + продолжать там, где вопроса не требуется. +4. Комментарии в коде — «почему», не «что»; файлы малые; stdlib-first. + +## Готово — это когда + +- Дерево компилируется, зонная батарея зелёная, `/healthz` отвечает живым запуском. +- `platform/docs/STACK_DECISIONS.md` — пины live-сверены, таблица полная. +- Дизайн-ответы К-4/К-7/К-12/П-5 лежат в `platform/docs/platform-PROGRESS.md` с обоснованиями. +- Журнал зоны обновлён: что построено · что предложено · что спрошено; BACKLOG-строки + получили диспозиции. +- Ничего не закоммичено — дерево передано оркестратору. diff --git a/platform/docs/platform-PROGRESS.md b/platform/docs/platform-PROGRESS.md new file mode 100644 index 00000000..b50a1ead --- /dev/null +++ b/platform/docs/platform-PROGRESS.md @@ -0,0 +1,19 @@ +# Журнал зоны «Платформа» + +> Весь прогресс платформы — ЗДЕСЬ (решение владельца 04.08): пинги, итоги сессий, открытые +> вопросы, предложения на ратификацию. В `docs/PROGRESS.md` платформа не пишет; оркестратор +> читает этот журнал при каждом лендинге зоны (свип «решений владельца» — норма D39.99 п.4). + +## Текущее состояние + +- Кода нет. `go.mod` заведён. Промт P0 выдан 04.08 (`PLATFORM_SESSION_PROMPT.md`, D39.100). +- Контракт API v0 ратифицирован (D39.99, `docs/architecture/14-api-contract/`) — на платформе + дизайн-ответы К-4 (ревизия) · К-7 (пагинация) · К-12 (пуш экспорта) · форма П-5 (лимиты). + +## Открытые вопросы к владельцу/оркестратору + +_(пусто)_ + +## Хроника + +_(записи сессий — сверху новые)_