# Phase 5: backups и восстановление

Phase 5 завершена для NeoForge 21.1.252 / Minecraft 1.21.1. Реализованы
`./mcpack backup`, `./mcpack restore` и обязательный gate `backupBeforeApply`
для будущего deployment. Контракт и проверенная инструкция: [backups.md](backups.md).

## Проверка с реальным Docker

Проверка 2026-10-03 выполнялась на отдельном root `.tools/phase4-server`,
project `minecraft-lab-phase4`, port 25566, full release 0.0.4. Основной
Phase 0 сервер на 25565 не останавливался и остался healthy.

- Запущенный сервер был корректно остановлен; backup всего runtime
  опубликован после tar/zstd listing и пробной распаковки.
- Snapshot содержит runtime archive, metadata, полную копию release 0.0.4
  и checksums всех файлов. Исключений нет.
- После backup сервер автоматически вернулся на исходный release в healthy;
  `mc-health` подтвердил Minecraft 1.21.1.
- Затем намеренно подставлена команда tar с exit 42. Backup вернул non-zero,
  оставил сервер остановленным, не создал дополнительный окончательный
  snapshot и удалил временный staging. Metadata операции фиксирует failed.
- Старый тестовый контейнер удалён через down. Snapshot восстановлен в новый
  `.tools/phase5-restored-server` без распаковки поверх существующего root.
- До запуска совпали все 416 inventory entries (160 файлов, включая 23 файла
  world): пути, bytes/SHA256, mode, UID и GID. В наборе есть владельцы
  1000:1000 и 0:0; обе группы сохранились.
- Подтверждены `mod-state/phase5.json` и unmanaged config вне world,
  server.properties, ops.json, whitelist.json. Локальный host `.env` не
  копировался: при запуске использован уже настроенный файл прежнего test root.
- Восстановленная копия запущена с собственным сохранённым `release/`:
  NeoForge 21.1.252, Minecraft 1.21.1, статус healthy и успешный `mc-health`.
- После проверки восстановленный контейнер/network удалены через down.
  Оба тестовых runtime и snapshot сохранены для дальнейших проверок.

Проверенный snapshot:

```text
.tools/phase4-server/backups/20261003T134409150Z-edd387d7-f947-4c3d-8ffc-bc02649cdfdc
archive bytes: 162695375
archive SHA256: e52c82adb379942ed2b63fb0cd361dd7d2cfd153314b26b026bafd942c87c9ce
release manifest SHA256: 5933ed34f35473026a32f0c3eab9a8b86b6fb484461bac2f670e0a74930aaa0c
```

Свидетельства: `.tools/phase5-evidence/backup.log`, `failed-backup.log`,
`failure-verification.txt`, `restore-verification.txt`, `resumed-health.txt`,
`restored-health.txt`, `restored-start.log`, `primary-server-status.txt`,
`integration.log`. Сценарий — `scripts/verify-phase5.sh`; он требует специально
подготовленного test root Phase 4 и ещё не существующего restore destination.
Его нельзя запускать как универсальную команду на primary сервере.

## Автоматические проверки

`npm test`: 37 tests pass. Backup/restore tests проверяют общий lifecycle lock,
stop/archive/verify/resume, stopped/absent state, разные snapshot ID,
восстановление bytes/modes/ownership и связанного release, запрет существующей
цели, повреждённый archive, неполное checksum coverage, ошибку tar/stop/resume,
unsupported links, проверку target до остановки и отказ применения до backup.

Gate test доказывает, что callback будущего apply не вызывается при ошибке
архива и вызывается только после verified snapshot под той же блокировкой.
При ошибке callback status учитывает текущее состояние контейнера и не
запускает старую сборку автоматически. SSH apply сам пока не реализован.
Build, mod commands и runtime regression tests также проходят. Node/Bash
syntax и `git diff --check` пройдены.

## Оставшиеся границы

Автоматическое удаление snapshot, off-host копии, retention, rollback и
переключение active release — последующие фазы. Пока runtime не поддерживает
links/special files в backup. Atomic publication защищает от обычной ошибки
процесса, но fsync для гарантии при отключении питания не реализован.
Primary старого spike wrapper не мигрирован на full-release binding.
Следующая Phase 6 — расширенная диагностика healthcheck, crash/restart-loop
и timeout с полезными logs.