​
Каналы

  • stdout — одна итоговая JSON-строка;
  • stderr — JSON Lines событий прогресса, предупреждений и fatal;
  • exit code 0 — успешная операция;
  • ненулевой exit code — launcher не продолжает критичный flow.
Electron запускает процессы с windowsHide: true, закрывает stdin, ограничивает размер буфера и разбирает JSON-события построчно.

​
Пути

Все пути к файлам клиента должны быть относительными, использовать / в JSON и не содержать .., абсолютный root или Windows drive prefix. Root передаётся отдельным CLI-параметром.

​
Символические ссылки

Scanner и Downloader не должны следовать через symlink/reparse-point за пределы root. Перед записью Downloader проверяет всю цепочку родительских каталогов.

​
Версионирование

JSON-контракты содержат schemaVersion. Несовместимое изменение требует увеличения версии и одновременного обновления Electron-контракта.

​
Protobuf control-plane

Между launcher-server, админ-панелью и новым bootstrap client используются контракты из корневого каталога proto/wraithbound. .proto — единственный source of truth; сгенерированные Rust-файлы вручную не редактируются. Подписываемые сообщения не используют protobuf map: одинаковые данные должны кодироваться в одинаковой последовательности. Номер удалённого поля никогда не переиспользуется для нового смысла. JSON stdout/stderr native-процессов сохраняется как локальный IPC-контракт: scanner и downloader не работают с сетью control-plane. Main process сначала проверяет signed protobuf, включая BuildManifest.resources для assets и Java, и только затем создаёт локальные JSON manifest/plan для native-процессов. Таким образом формат IPC остаётся простым, а его вход уже ограничен доверенным release envelope. Публичные GetBootstrap, ListBuilds и GetMaintenance требуют заполненный ClientContext: версию лаунчера, поддерживаемую платформу и локаль. Сервер отбрасывает пустой или UNSPECIFIED контекст до чтения каталога и S3; это помогает видеть несовместимые клиенты явно, не маскируя проблему ответом 500.

​
События операций

Общие прогресс и диагностические данные находятся в wraithbound.events.v1. OperationProgress передаёт фазу, выполненное и общее значение, а также единицу измерения: шаги, файлы или байты. Диагностические атрибуты представлены повторяемыми парами key/value, а не map. Admin stream сохраняет прежние поля phase/completed/total и одновременно добавляет progress новым field number. Старые клиенты продолжают читать поток, а новые могут перейти на общий тип без синхронного обновления всей системы.