# ADR-0001: Vendored gbrain через git mirror

**Дата:** 2026-05-20
**Статус:** Принято

## Контекст

gbrain (https://github.com/garrytan/gbrain) — активно развивающийся проект:
- 60+ коммитов за последние 2 месяца
- v0.26 (текущая) ввела breaking change: переход с bearer tokens на OAuth 2.1
- Public API субпакетов (`gbrain/operations`, `gbrain/pglite-engine`) меняется

Дополнительные факторы:
- GitHub аккаунт zuevav был ограничен в апреле 2026, доступ к публичным репозиториям через `bun install -g github:garrytan/gbrain` может неожиданно ломаться
- ZBrain зависит от стабильности gbrain в production
- При следующей блокировке аккаунта мы не сможем переустановить или обновить gbrain

## Решение

Не зависеть от GitHub в runtime/install path. Зеркалить gbrain в свой git:

```bash
# Однократно, на чистом ноуте с работающим GitHub доступом:
git clone --mirror https://github.com/garrytan/gbrain.git
cd gbrain.git
git remote set-url --push origin git@git.zetit.ru:zuevav/gbrain-mirror.git
git push --mirror
```

Bootstrap-скрипт клонит из git.zetit.ru:

```bash
GBRAIN_REPO="https://git.zetit.ru/zuevav/gbrain-mirror.git" \
GBRAIN_VERSION="v0.26.5" \
bash scripts/bootstrap-vm.sh
```

## Последствия

### Плюсы
- Независимость от GitHub доступности и блокировок аккаунтов
- Управляемое обновление gbrain (через `git fetch upstream && review && push to mirror`)
- Возможность hotfix'ов локально, если upstream сломан (как форк, но в общем git)
- Защита от supply chain атак (мы видим diff перед обновлением)

### Минусы
- Нужно вручную обновлять mirror (раз в месяц-два)
- Лишний шаг в setup
- Расхождение с upstream если хотфикс не запушим обратно

### Митигация
- Раз в месяц: проверка upstream'а, review diff, push to mirror
- Все наши изменения (если потребуются) — в отдельной ветке `zetit/*`, чтобы не мерджились с upstream
- Tag'ируем версии в нашем mirror'е (`v0.26.5-zetit-1`, если есть наши патчи)

## Альтернативы рассмотренные

1. **Прямая зависимость от github:garrytan/gbrain** — отвергнуто из-за рисков блокировки и breaking changes
2. **Свой fork на git.zetit.ru с активной разработкой** — overkill, мы не планируем существенно дорабатывать gbrain
3. **npm-publish gbrain в свой private npm registry** — gbrain не публикуется в npm как пакет; нужен install via bun + workspace