docs: preserve Shacraft requirements and staged implementation plan

docs/PLAN.md

@@ -0,0 +1,79 @@
+# План разработки
+
+План составлен до реализации. Каждый этап заканчивается воспроизводимым результатом в локальном репозитории. `docs/STATUS.md` обновляется после проверок. Пункт не считается выполненным по наличию интерфейса, заглушки, каталога имён или успешной компиляции.
+
+## Этап 0. Сохранить контекст и проверить проектирование
+
+- Записать исходные требования, решения, контракты и критерии приёмки.
+- Зафиксировать источники данных совместимости и ограничения лицензий.
+- Разделить компоненты так, чтобы можно было независимо разрабатывать хранение, совместимость, сетевой сервер и клиент.
+- Согласовать обработку ошибок, координаты, ревизии, ограничения операций и формат диагностики.
+
+Выход: документы в `docs/`; список решений без молчаливого сокращения объёма.
+
+## Этап 1. Ядро и доказуемое управление памятью
+
+- Rust workspace; координаты с корректными отрицательными значениями; реестр канонических состояний блоков.
+- Секции 16×16×16: единообразное состояние или палитра и упакованные индексы. Отсутствие отдельного объекта на каждый блок.
+- Собственный версионированный формат хранения, ограниченный кэш, выгрузка на диск; операции чтения не изменяют мир.
+- Независимые экземпляры общей карты. Изменение/сброс одного экземпляра не влияет на другие; снимок основы имеет чёткую семантику.
+- Атомарные правки с журналом восстановления, ревизиями и идемпотентностью. История и undo хранятся на диске с ограниченным потреблением RAM.
+- Проверки границ секций, упаковки, изоляции миров, повторов, конфликтов, сохранения и восстановления после сбоя. Измерение хранения общей карты против копий.
+
+Выход: самостоятельная библиотека и воспроизводимые тесты/измерения. Это ещё не весь MVP.
+
+## Этап 2. Сервер и минимальный клиент — сквозной сценарий
+
+- Сервер владеет миром и симуляцией; фиксированный тик, серверные движение/столкновения и проверка взаимодействий.
+- Версионированный протокол: подключение, начальный снимок, изменения блоков, игроки, переход между мирами, ошибки и восстановление подключения.
+- Лимиты числа игроков, радиуса мира, сообщений, частоты действий и очередей. Медленный клиент не увеличивает память сервера без ограничения.
+- Тестовый клиент: собственный рендерер, камера, управление, блоки, простые сущности, состояния соединения. Сервер остаётся без графики.
+- Два независимых клиента видят одинаковые изменения. Перезапуск сохраняет мир. Подключение и выход не оставляют сущности и фоновые задачи.
+
+Выход: запускаемая локальная сетевая песочница. На первом проходе допустим небольшой набор материалов; это не выполнение требования полного каталога.
+
+## Этап 3. Control API и собственный MCP
+
+- Общий API чтения, редактирования, истории и диагностики; MCP — отдельный процесс с stdio.
+- Поиск материалов, чтение ограниченной области, пакетное строительство и шаблоны, preview/commit, undo с защитой от чужих изменений.
+- Ресурсы с системой координат и возможностями; структурированные ответы и понятные ошибки.
+- Визуальная обратная связь: снимок с явно указанными типом отображения и ревизией; топографический preview не объявляется снимком игрового клиента.
+- Тестовые миры, сущности, управление аренами и метрики. Авторизация управляющего API; токен не попадает в клиентский код и журнал.
+- Реальная MCP-сессия: initialize → list → build → inspect/capture → undo; параллельный клиент видит результат.
+
+Выход: законченный цикл автоматизированного строительства с проверкой результата.
+
+## Этап 4. Контент и двусторонняя совместимость
+
+- Проверить полный источник каталога именно Java 26.2; генерировать воспроизводимо, хранить происхождение и версию данных.
+- Реализовать формы, коллизии и отображение семейств блоков; отдельно учитывать неподдерживаемые особенности. Базовые определения сущностей и сохраняемые свойства.
+- Импорт Anvil/NBT по частям с ограниченным бюджетом памяти; обработка измерений и дополнительного NBT.
+- Экспорт мира в целевую версию; режим точности и явных замен, sidecar для неподдерживаемых данных, корректное инвалидирование происхождения после правок.
+- `.schem` import/export; тестовые fixtures; повторное открытие экспортированных данных независимым читателем и, при доступности целевой игры, самой игрой.
+
+Выход: проверенный обмен заявленными данными с отчётом покрытия. Полный каталог имён без форм/данных не закрывает этот этап.
+
+## Этап 5. Единые пакеты и законченная миниигра
+
+- Версионированный манифест с зависимостями, клиентскими/серверными частями, размерами, хешами, лицензиями и возможностями.
+- Небольшой собственный базовый набор ассетов. Проверяемая загрузка клиентских ресурсов и кэш; обязательные ресурсы отделены от необязательного качества.
+- Первое расширение через единый формат, работающий клиентский и серверный сценарий. Декларативная конфигурация не называется полноценной средой произвольных модулей.
+- Spleef: ожидание → отсчёт → игра → выбывание → победитель → сброс. Несколько независимых арен используют общую карту.
+- Повторные матчи, отключения, вход во время игры, переход в лобби, сохранение настроек после перезапуска.
+
+Выход: друзья могут сыграть законченный матч, а другой разработчик — добавить документированное расширение.
+
+## Этап 6. Приёмка, измерения и поставка
+
+- Проверить все критерии `ACCEPTANCE.md`; отдельный список фактического покрытия и ограничений.
+- Измерить RSS/пик памяти, хранение секций, кэши, сетевые очереди, p95/p99 тика, поведение после многократных матчей и перезапуска.
+- Сравнение с Paper проводить только при доступном сопоставимом стенде. До этого публиковать собственные числа без заявлений о кратности выигрыша.
+- Инструкции запуска, конфигурация MCP, описание API/формата пакетов, лицензии, контрольная сумма исходного архива, Git-коммит.
+- Продакшен-публикация и изменение лаунчера — отдельная интеграционная работа после локальной проверки.
+
+Выход: воспроизводимый локальный релиз MVP с честным отчётом, исходным архивом и известными ограничениями.
+
+## Рабочий порядок после планирования
+
+Сначала этап 1. Параллельно с ним можно готовить протокол и клиент по согласованному контракту, изучать каталог/конвертер. Подключение этих частей, изменения общих интерфейсов и проверки выполняются последовательно. После каждого этапа — сохранить результат; не оставлять единственную копию в одноразовой среде.
+