# Разработка и воспроизведение первого этапа

Это инструменты проверки хранилища. Здесь ещё нет игрового сервера, графического клиента или MCP. Локальный JSON-lines интерфейс CLI не является MCP.

## Сборка и проверки

Нужны Rust/Cargo 1.96.0, C-компилятор для bundled SQLite, Python 3 для проверки аварийного завершения. После загрузки зависимостей `Cargo.lock` фиксирует их версии.

```bash
cd /home/emil/Desktop/shacraft-core
bash scripts/verify.sh
```

Проверка запускает форматирование, Clippy, Rust-тесты, сборку CLI и отдельные процессы. `check_storage.py` создаёт только временные миры и принудительно завершает только собственный дочерний процесс.

## Демонстрация хранения

```bash
cargo run -p shacraft-tools -- --data data/demo demo
cargo run -p shacraft-tools -- --data data/demo stats
```

`demo` требует пустое хранилище. Создаёт карту пола и два независимых экземпляра, изменяет один, проверяет изоляцию, выполняет undo и reset. Повторный запуск в непустой каталог отклоняется. Для нового прогона укажите другое имя каталога.

## Измерение

```bash
cargo build --release -p shacraft-tools
target/release/shacraft-tools --data data/bench-001 --cache 8 benchmark --sections 256 --worlds 100
```

`benchmark` также требует пустое хранилище. Он создаёт 256 различных секций, 100 экземпляров, проходит по данным сверх вместимости кэша и изменяет/сбрасывает каждый экземпляр. В JSON выводятся отдельные измерения RSS/пика всего процесса (на Linux), метрики хранения, длительности и размеры файлов. Данные теста синтетические; игроков, сетевого тика и фоновой симуляции нет. Эти числа не доказывают выигрыш относительно Paper.

## JSON-lines сессия

```bash
target/debug/shacraft-tools --data data/manual --cache 8 session
```

По одной JSON-команде на строку:

```json
{"op":"register","state":"shacraft:stone"}
{"op":"create","name":"world"}
{"op":"registry"}
{"op":"revision","world":"world"}
{"op":"get","world":"world","pos":[-1,0,0]}
{"op":"stats"}
```

Сначала получите реальный ID блока и текущую ревизию, затем передайте их в `edit`:

```json
{"op":"edit","world":"world","expected_revision":0,"operation_id":"first-stone","changes":[{"pos":[-1,0,0],"block":1}]}
{"op":"undo","world":"world","expected_revision":1,"operation_id":"undo-first","target_operation":"first-stone"}
{"op":"reset","world":"world","expected_revision":2,"operation_id":"reset-world"}
```

ID 1 в этом примере допустим только если ответ регистрации действительно вернул 1. Ответ каждой команды имеет `ok` и `result` либо `error`. Успешный ответ записи выдаётся после возврата долговечного API. Максимальная входная строка — 8 MiB; ограничения на число блоков и объём области действуют дополнительно.

## Продолжение разработки

Прочитайте STATUS и PLAN. Новые компоненты добавляйте в workspace только вместе с реализацией и командами проверки. Не создавайте пустые исполняемые файлы, которые лишь выводят «готово». Публичный протокол пока проектируется в CONTRACT; окончание первого этапа хранения не закрывает последующие этапы.

Для живого SQLite-хранилища нельзя считать копию одного `worlds.sqlite3` полной резервной копией: актуальные данные могут быть в WAL. Перед ручным копированием остановите владеющий процесс либо используйте будущий согласованный backup API. Исходный архив проекта намеренно не содержит рабочие миры.