Project Chimera
Меню

Исходники

580 строк · 44 КиБ

DECISIONS.md

1# Решения
2
3Каждое решение: что выбрано, почему, что рассматривали вместо и чем за это
4платим. Записи не переписываются — если решение отменено, добавляется новая
5запись со ссылкой на старую.
6
7---
8
9## ADR-001. Не переписывать с нуля, а замещать подсистемы
10
11**2026-09-02 · принято**
12
13**Контекст.** 56 000 строк Python и 3 900 строк bash. Соблазн — снести всё и
14написать заново на Rust.
15
16**Решение.** Strangler fig: новое ядро с первого дня работает поверх
17существующей папки `data/` StartWine и читает старые конфиги. Подсистемы
18замещаются по одной, порядок задан зависимостями: рантайм запуска → хранилище →
19обновления → магазины → GUI.
20
21**Почему не переписывание с нуля.** Полгода без работающего лаунчера. Хуже
22того: значительная часть bash-логики — не мусор, а обходы реальных багов Wine,
23накопленные годами. При переписывании вслепую они теряются молча, и выясняется
24это через месяцы, когда уже не помнишь, что именно сломалось.
25
26**Почему GUI последним.** Интерфейс поверх старого bash-ядра пришлось бы
27переписывать дважды.
28
29**Цена.** Какое-то время в проекте живут два формата конфига и обвязка для
30чтения bash. Это принято сознательно и ограничено по времени: см. ADR-002.
31
32**Отменено в части каталога данных.** «Новое ядро с первого дня работает
33поверх существующей папки `data/` StartWine» больше не так: каталог свой,
34путь к нему — настройка. См. ADR-012. Всё остальное — порядок замещения
35подсистем, чтение старых конфигов, GUI последним — в силе.
36
37**Проверяемость.** `sw_runlib` собирает окружение перед запуском. Порт считается
38готовым, когда дамп итогового окружения и командной строки совпадает с
39bash-версией **побайтово** по всем 53 переменным на пяти разных играх (DX11,
40DX12, OpenGL, 32-битная, с внешним лончером). Это превращает «вроде работает» в
41проходящий тест.
42
43---
44
45## ADR-002. Конфиг — TOML со схемой, bash только для переноса
46
47**2026-09-02 · принято, реализовано**
48
49**Контекст.** Конфиг игры в StartWine — исполняемый bash-скрипт, подключаемый
50через `source`. Нет схемы, валидации, миграций; конфиг может выполнить
51произвольный код. Пока конфиг — bash, лаунчер обязан быть shell.
52
53**Решение.** TOML с типизированной схемой. Читалка bash-конфигов существует
54**только для миграции** и будет удалена, когда переносить станет нечего.
55
56**Почему не оставить совместимость навсегда.** Тогда замок останется навсегда:
57любая настройка должна была бы выражаться в bash, и это диктовало бы
58архитектуру вечно.
59
60**Почему TOML, а не JSON или YAML.** Конфиг правят руками, значит нужны
61комментарии — в JSON их нет. YAML отпадает из-за неоднозначной типизации
62(`no` как логическое ложь, ведущие нули) — ровно тот класс ошибок, от которого
63мы уходим.
64
65**Реализовано.** `chl-core/src/legacy.rs` и `chl-core/src/migrate.rs`.
66
67**Проверяемость.** Разбор обязан быть без потерь: каждый конфиг разбирается,
68собирается обратно и сравнивается с исходником побайтово (`chl legacy verify`).
69На реальной установке проверка проходит, все 53 настройки распознаны.
70
71**Побочная выгода.** Сгенерированный TOML самодокументирован: над каждой
72настройкой печатается объяснение из реестра.
73
74---
75
76## ADR-003. Хранилище префиксов — контентно-адресуемое, снапшоты через reflink
77
78**2026-09-02 · принято, не реализовано (фаза 1)**
79
80**Контекст.** Бэкап префикса в StartWine — полный образ squashfs. Бэкап
81сохранений — один общий образ, пересобираемый с нуля с `-noappend`, то есть
82затирающий предыдущий. Версий нет: испорченное сохранение вытеснит целое, если
83заметить позже пяти дней.
84
85**Решение.** Файлы префикса складываются в хранилище по хэшу содержимого,
86префикс собирается reflink-копиями. Снапшот — операция на миллисекунды.
87Одинаковые библиотеки в разных префиксах занимают место один раз. Снапшоты
88версионные, старые не затираются новыми.
89
90Поверх — транзакции: любое изменение префикса (установка библиотеки, смена
91версии Wine, применение `.reg`) снапшотится до, и откатывается одной кнопкой.
92
93**Почему reflink, а не btrfs-снапшоты подтомов.** Снапшот подтома работает
94только на btrfs и только для целого подтома. Reflink на уровне файлов
95(`FICLONE`) даёт то же на btrfs и xfs, и произвольную гранулярность. На `/home`
96здесь btrfs — проверено, работает.
97
98**Запасной вариант.** Файловые системы без reflink (ext4) — жёсткие ссылки с
99дедупликацией по хэшу. Медленнее и требует осторожности при записи, но
100работает.
101
102**Почему не restic или borg целиком.** Они дают дедуплицированные бэкапы, но не
103дают дешёвого *рабочего* префикса из хранилища: восстановление — это распаковка.
104Нам нужно и то и другое.
105
106**Цена.** Своё хранилище — код, который обязан быть безупречным: ошибка теряет
107данные. Поэтому фаза 1, а не фаза 0, и с проверкой целостности по хэшам.
108
109---
110
111## ADR-004. Обновления — подписанный манифест, версия закреплена за игрой
112
113**2026-09-02 · принято, не реализовано (фаза 2)**
114
115**Контекст.** `wine_version.json`: значение канала — одна строка с URL через
116пробел. Ни версий как данных, ни контрольных сумм, ни подписей, ни отката.
117Автообновлений нет — на такой структуре их безопасно не построить.
118
119**Решение.** Манифест с версиями Wine, DXVK, VKD3D и рантаймов, подписанный
120ed25519. У каждого артефакта хэш и подпись. Дифф-загрузка вместо перекачивания
121архива целиком.
122
123**Ключевое требование: обновление не может сломать работающую игру.** Версия
124закреплена за игрой; обновление добавляет новую, переключение — осознанное
125действие с откатом.
126
127**Почему подпись, а не только хэш.** Хэш защищает от повреждения при передаче,
128подпись — от подмены на зеркале. Артефакты качаются с трёх разных зеркал,
129включая сторонние.
130
131**Цена.** Нужно где-то держать приватный ключ и процедуру выпуска манифеста.
132Для личного проекта это несколько строк, но забыть про ротацию нельзя.
133
134---
135
136## ADR-005. Epic: библиотека нативно, магазин через webview
137
138**2026-09-02 · принято, не реализовано (фаза 3)**
139
140**Контекст.** В StartWine два несвязанных пути: код на основе legendary тянет
141только список игр, отдельно качается настоящий Windows-лончер Epic в свой
142префикс. Отсюда «показывает только список игр».
143
144**Решение.** Библиотека, установка и запуск — нативно, через тот же
145OAuth-поток, что у legendary и Heroic. Магазин и настройки аккаунта — webview
146на настоящий `store.epicgames.com`.
147
148**Почему не разбирать приватные API магазина.** Публичного API магазина Epic не
149существует. Разбор приватных эндпоинтов означает поломку при каждом их
150изменении и работу на стороне обхода их правил. Покупки на настоящем сайте —
151и легально, и безопасно.
152
153**Почему не оставить Windows-лончер Epic.** Это CEF-браузер внутри Wine:
154тяжёлый, медленный, и именно он делает интерфейс неотзывчивым. Webview на
155WebKitGTK даёт тот же магазин без Wine в цепочке.
156
157**Цена.** Две технологии вместо одной: нативный клиент плюс webview. Плюс
158webview тянет WebKitGTK в зависимости.
159
160---
161
162## ADR-006. Steam: поддержать оба режима, не обещать замену
163
164**2026-09-02 · принято, не реализовано (фаза 3)**
165
166**Контекст.** Желание — вшить Steam так, чтобы нативный Linux-клиент стал не
167нужен. Раньше через StartWine ставился Windows-Steam, и это работало.
168
169**Решение.** Оба режима первоклассны, выбор — на уровне игры. Windows-Steam в
170Wine устанавливается автоматически в свой префикс. Нативный Steam
171обнаруживается через `libraryfolders.vdf`, игры лаунчера добавляются в него
172ярлыками с артом, чтобы попадать в Game Mode на Steam Deck.
173
174**Чего не обещаем.** Полной замены нативного Steam. Игры с EAC и BattlEye
175работают только через нативный Steam с Proton — там задействованы Linux-сборки
176самих античитов, и никакая настройка Wine это не обходит. Обещать замену —
177обмануть пользователя, и это вернётся баг-репортами, на которые нечего
178ответить.
179
180**Отдельно.** Клиент Steam нельзя включить в поставку: Valve не разрешает
181распространение третьими лицами. Автоматизировать скачивание с официального
182адреса — можно, так делают все. «Вшитый Steam» на практике означает установку
183в один клик.
184
185---
186
187## ADR-007. GUI — GTK4 и libadwaita через gtk4-rs
188
189**2026-09-02 · принято, не реализовано (фаза 4)**
190
191**Решение.** GTK4 с libadwaita через `gtk4-rs`. Один тулкит, два режима
192компоновки: настольный и Big Picture с навигацией геймпадом.
193
194**Почему.** Текущий UI уже GTK4, значит сохраняется визуальная преемственность
195и переносятся CSS-темы. libadwaita даёт адаптивность «десктоп ↔ Deck». GTK4
196рендерит через Vulkan, что важно на Deck. Доступность, ввод и Wayland работают
197сразу, а не через год допиливания.
198
199**Почему не Iced или egui.** Геймпад-навигация в них проще, но настольная
200интеграция хуже: диалоги файлов, экранная клавиатура, IME, доступность. Для
201лаунчера, который должен «не вызывать вопросов», это важнее.
202
203**Почему не два тулкита.** Соблазн «GTK для десктопа, egui для Big Picture»
204кончается двумя недоделанными интерфейсами.
205
206**Цена.** Своя система навигации фокусом для геймпада: в GTK4 её придётся
207писать руками.
208
209---
210
211## ADR-008. Настройка не может существовать без объяснения
212
213**2026-09-02 · принято, реализовано**
214
215**Контекст.** Главная претензия к StartWine со стороны пользователя: «а зачем
216вот эта кнопка». Настройки есть, объяснений нет, и никакой процесс это не
217исправит — забывать документировать будут всегда.
218
219**Решение.** Реестр настроек в коде. Структура `Spec` требует `doc` («что
220делает»), `impact` («когда менять и что будет») и `tier` (уровень сложности).
221Пропустить поле нельзя — компилятор не примет неполный литерал. Из реестра
222генерируются UI, справка CLI и комментарии в конфиге.
223
224**Почему типами, а не соглашением.** Соглашение нарушается в первый же
225занятой вечер. Тип — нет.
226
227**Реализовано.** `chl-core/src/settings.rs`, 53 настройки. Тест
228`каждая_настройка_объяснена` не даст оставить объяснение пустым.
229
230**Дополнительно к реализации.** Провенанс значения: рядом с переключателем
231показывать, откуда взялось текущее значение — профиль сообщества, автоопределение
232или ручная правка с датой.
233
234---
235
236## ADR-009. Код живёт в репозитории project-chimera, пока недоступна gitea
237
238**2026-09-02 · принято, временное**
239
240**Контекст.** План — отдельный репозиторий `chimera-launcher` в
241`git.chimera.local`, по образцу `k8s-manifests`. Но на 2026-09-02
242`git.chimera.local` не резолвится, `/etc/hosts` пуст, `~/.ssh` не существует:
243свежая CachyOS ещё не подключена к кластеру.
244
245**Решение.** Пока код лежит в `13-chimera-launcher/` репозитория
246`project-chimera` и синхронизируется Яндекс.Диском. Когда доступ к кластеру
247появится, каталог выделяется в свой репозиторий (`git subtree split` сохранит
248историю).
249
250**Каталог сборки уведён за пределы Яндекс.Диска** — в
251`~/.cache/chimera-launcher/target` через `code/.cargo/config.toml`. Иначе
252гигабайты объектных файлов пойдут в синхронизацию.
253
254**Условие снятия.** Резолвится `git.chimera.local` — и это единственное, что
255осталось. Проверено 2026-09-02 вечером: доверие к `cluster-selfsigned-ca` на
256этой машине уже настроено (`curl` без `-k` отдаёт 200), а ключ SSH для git по
257HTTPS не нужен.
258
259Адрес для `/etc/hosts` — **`10.40.8.14`** (acer, ingress), а не
260`10.40.8.10` (master xeon, где 80 и 443 закрыты). Полный список хостов и
261готовая команда: `02-infrastructure/DNS и доступ к chimera.local.md`.
262
263---
264
265## ADR-010. Вольт — источник правды, gitea — зеркало через subtree
266
267**2026-09-02 · принято, ожидает первого push**
268
269**Контекст.** ADR-009 предполагал выделить каталог в отдельный репозиторий,
270когда появится доступ к gitea. Доступ появился: записи в `/etc/hosts` на
271`10.40.8.14` сделаны, `git.chimera.local` отдаёт 200, API Gitea 1.27.3
272отвечает. Возник вопрос, где после этого живёт источник правды.
273
274**Решение.** Каталог `13-chimera-launcher/` в репозитории `project-chimera`
275остаётся источником правды. Репозиторий `git.chimera.local/fanchji/chimera-launcher`
276— **зеркало**, обновляется командой `git subtree push`. Прямые коммиты в
277зеркало не делаются.
278
279**Почему не сделать зеркало рабочей копией.** Своя папка `.git` внутри
280Яндекс.Диска — это риск повреждения объектов git при синхронизации: клиент
281может синхронизировать файлы репозитория в момент записи, и получится
282рассогласованное состояние. Вольт уже один репозиторий на синхронизируемом
283диске, второй вложенный внутрь удваивает риск без выгоды.
284
285**Почему это согласуется с проектом.** Ровно тот же паттерн уже применён к
286`k8s-manifests`: вольт — источник правды по докам и истории, в отдельный
287репозиторий зеркалится только нужный подкаталог (`03-kubernetes/`). Одно
288правило вместо двух разных.
289
290**Как обновлять зеркало:**
291
292```
293git subtree push -P 13-chimera-launcher launcher master
294```
295
296Remote `launcher` уже прописан.
297
298**Цена и главный риск.** Если закоммитить прямо в зеркало — минуя вольт —
299истории разойдутся, и `subtree push` начнёт отвергать. Поэтому правило
300жёсткое: править только в вольте. Если понадобится работать с другой машины,
301правильный путь — клонировать зеркало, а изменения влить обратно в вольт
302через `git subtree pull`, а не пушить в зеркало напрямую.
303
304**Отменяет** часть ADR-009 про «выделяется в свой репозиторий»: репозиторий
305создаётся, но становится зеркалом, а не новым домом проекта.
306
307---
308
309## ADR-011. Свой репозиторий, а не каталог в вольте
310
311**2026-09-02 · принято, выполнено · отменяет ADR-010**
312
313**Контекст.** Распоряжение владельца: «Разделите свои проекты, не надо всё в
314кучу валить. Аналог Discord и CachyOS это не относящиеся к кластеру проекты,
315они просто будут исходники на моём git держать по сути.»
316
317**Решение.** Chimera-Launcher — самостоятельный проект в собственном
318репозитории `git.chimera.local/fanchji/chimera-launcher` (private,
319ветка `main`). Рабочая копия — `~/Projects/chimera-launcher`. Каталога
320`13-chimera-launcher/` в `project-chimera` больше нет.
321
322**Что это отменяет в ADR-010.** Там вольт был источником правды, а Gitea —
323зеркалом подкаталога через `git subtree push`, по образцу `k8s-manifests`.
324Теперь наоборот: источник правды — этот репозиторий, вольт к проекту
325отношения не имеет. Причина смены не техническая: модель зеркала была
326разумной, пока лаунчер считался частью хоумлаба. Владелец решил, что он
327частью хоумлаба не является — в кластер не деплоится ничего.
328
329**Что из ADR-010 осталось верным.** Довод против вложенной папки `.git`
330внутри Яндекс.Диска: клиент может синхронизировать файлы репозитория в
331момент записи и получить рассогласованное состояние. Поэтому рабочая копия
332живёт в `~/Projects`, а не на синхронизируемом диске.
333
334**Перенос.** `git subtree split --prefix=13-chimera-launcher`, 5 коммитов,
335push в `main`. Целостность проверена не на глаз: хэш дерева в Gitea
336(`0e38bb1d`) совпал с хэшем каталога в вольте, то есть содержимое перенесено
337побайтово. Тесты и clippy в отдельной копии проходят, CLI работает против
338реальной установки StartWine.
339
340**Цена: потеряна синхронизация через Яндекс.Диск.** Вольт был механизмом
341передачи между машинами и сессиями, и на машине без доступа к кластеру
342исходники теперь недоступны — ровно тот блокер, который решали утром
3432026-09-02. Смягчается тем, что рабочая копия лежит локально, а доступ к
344кластеру стал устойчивее (wildcard-DNS на Mikrotik вместо записей в
345`/etc/hosts`). Но если понадобится работать с машины вне этой сети — нужен
346либо доступ к кластеру, либо второе зеркало.
347
348**Аутентификация.** У Gitea два независимых входа: Dex и Keycloak работают
349только в браузере, а `git` умеет исключительно Basic Auth и OAuth-редирект
350пройти не может физически. Поэтому пароль от Dex для `git push` не
351срабатывает никогда, а ошибка выглядит как «неверные креды». Нужен токен
352(`chimera-automation`, скоуп `write:repository`); он лежит в Secret Service,
353поэтому push проходит без диалогов. Токен намеренно не умеет создавать
354репозитории — на `POST /user/repos` отдаёт 403, для этого нужен `write:user`,
355которого у него нет.
356
357
358---
359
360## ADR-012. Самообновление лаунчера: подписанный статический файл, подмена по `rename`, автооткат
361
362**2026-09-07 · принято, выполнено**
363
364**Контекст.** Пункт 4 фазы 2 (`ROADMAP.md`) — «атомарное обновление самого
365лаунчера с откатом» — был осознанно оставлен design-only:
366`chl-wine/WINE-UPDATES-DESIGN.md` объяснял, что ошибка в этом коде отключает
367**единственный работающий бинарник**, и оставлял три открытых вопроса,
368которые просил решить до кода, а не по ходу. Владелец попросил довести пункт
369до конца: «приложение должно обновляться атомарно, не надо никуда ходить,
370ничего качать», уведомление как в KDE, раздел с patch notes и выбор из трёх —
371поставить сейчас, потом, пропустить.
372
373**Решение.** Отдельный крейт `chl-selfupdate`; обёртками служат `chl update`
374и раздел «Обновления» в интерфейсе, оба зовут одни и те же функции.
375
3761. **Источник — статический подписанный файл по HTTPS**, адрес в настройке
377 `update_feed_url`. Никакого API, никакой авторизации, никакого состояния
378 на сервере.
3792. **Доверие — подпись ed25519 тем же ключом и тем же кодом
380 (`chl_wine::sign`), что у манифеста сборок Wine** (ADR-004). Второй модели
381 доверия проект не заводит. Плюс sha256 каждого файла из подписанного
382 манифеста — проверяется и сразу после скачивания, и второй раз перед
383 подменой.
3843. **Атомарность — staging рядом плюс `rename(2)`** в пределах одной
385 файловой системы. Прежний файл сохраняется как `<имя>.предыдущая`
386 переименованием, не копией.
3874. **Журнал `.chl-обновление.toml` рядом с бинарниками**, пишется **до**
388 каждого шага. Он и делает обрыв восстановимым.
3895. **Маркер здоровья с автооткатом.** `Applied { starts, confirmed }`: первый
390 запуск новой версии увеличивает `starts`, а подтверждает её только код,
391 дошедший до настоящей работы (в CLI — успешно выполненная команда, в GUI —
392 собранное и показанное окно плюс три секунды). Запуск, увидевший
393 неподтверждённую метку, выставленную прошлым запуском, откатывается сам,
394 без вопросов.
3956. **Проверка автоматическая, установка — никогда.** Настройка
396 `self_update_check`, включена по умолчанию; ставить всегда выбирает
397 человек, из трёх вариантов, и «пропустить» запоминается по версии.
398
399**Ответы на три открытых вопроса design-документа.**
400
401- *Где лежит `chl`* — каталог берётся из `current_exe()`, а не из зашитого
402 `~/.local/bin`: обновление пишет туда, где лаунчер работает сейчас, иначе
403 оно тихо создало бы вторую установку.
404- *Автоматически или по спросу* — см. пункт 6. Фоновое обновление без
405 спроса противоречило бы остальному проекту (`chl wine installed` тоже
406 только сообщает).
407- *Что с двумя бинарниками* — их два (`chl` и `chimera-launcher`), это одна
408 установка на двоих, и обновляются они одним манифестом за один проход.
409 Список заменяемых имён закрытый (`manifest::UPDATABLE`): подписанному
410 манифесту всё равно нельзя разрешать записать произвольный путь.
411
412**Почему не бэкенд совместимости как API.** `chl-compat` уже умеет говорить
413с `chimera-compat.chimera.local`, и соблазн был. Отвергнуто: у него своя
414задача (отчёты о совместимости игр), свой токен и свои коды ответа. Отдавать
415через него бинарники значило бы связать выпуск релиза с доступностью
416прикладного API и потребовать токен там, где он не нужен — подлинность
417держится на подписи, а не на том, кто спрашивает. Хост при этом взят тот же:
418он единственный в личной инфраструктуре, чей сертификат уже доверен
419системным хранилищем.
420
421**Почему не публичный git-хостинг.** Этого проекта там нет и по замыслу не
422будет (README: «публиковаться не планируется»). Завести зеркало ради канала
423обновлений — это решение о публикации проекта, а не о механизме обновления.
424
425**Цена, названная прямо.**
426
427- **Уже запущенный процесс продолжает работать на старом коде.** `rename` не
428 трогает открытый inode. Обойти это нельзя никакой схемой замены файла;
429 обёртки говорят «закрой и открой заново», а не «обновление применено».
430- **Два файла — это две операции `rename`, а не одна.** Существует момент,
431 когда на диске смесь версий. Скрыть его нельзя (в POSIX нет способа
432 переименовать два файла разом) — он сделан распознаваемым: журнал плюс
433 `recover`, который достраивает перенос, если staging цел, и откатывает
434 всё, если нет.
435- **Пока `keys/wine-manifest.pub` пуст, обновление не устанавливается
436 вообще.** Из вариантов «без ключа ставим по одному sha256» и «без ключа не
437 ставим ничего» выбран второй: хэш, лежащий в том же файле, что и ссылка,
438 защищает от повреждения при передаче, но не от подмены обоих сразу, то
439 есть от единственной угрозы, ради которой всё это делается, не защищает.
440 `chl update --status` и раздел «Обновления» говорят об этом вслух, а не
441 отказывают в последний момент.
442- **Проверка, включённая по умолчанию, — это запрос к серверу при каждом
443 запуске.** Отличие от `kb_fetch_enabled` (выключена по умолчанию) не в
444 последовательности: там уходят названия игр из библиотеки на сторонние
445 сайты, здесь — пустой GET к личной инфраструктуре владельца, уже
446 единственному адресу в `PRIVACY.md`, к которому лаунчер обращается без
447 нажатия кнопки. Настройка описана в реестре, названа в `PRIVACY.md` и
448 выключается в двух местах интерфейса.
449
450**Проверяемость.** Подмена, откат, обрыв посреди подмены (и когда его можно
451достроить, и когда нельзя), несовпадение хэша, порча подготовленного файла
452между «скачал» и «поставил», автооткат неподтверждённой версии — юнит-тесты
453`chl_selfupdate::apply` на настоящих файлах в tempdir. Плюс живой прогон
4542026-09-07 на выброшенном дереве установки: манифест собран `chl
455update-manifest` по настоящим sha256, подписан `chl wine manifest sign`,
456подделка манифеста отвергнута проверкой подписи, подменённый файл при верном
457манифесте отвергнут проверкой хэша.
458
459---
460
461## ADR-012. Каталог данных свой, а путь к нему — настройка · отменяет часть ADR-001
462
463**2026-09-07 · принято, реализовано**
464
465**Контекст.** ADR-001 сажал ядро поверх папки `data/` StartWine. Это
466кончилось 2026-09-03: StartWine обновил общий префикс сборкой GE-Proton11-6,
467конфиг игры остался на GE-Proton10-34, запуск встал с «wine client error:
468version mismatch 935/864». Тогда появился `chl migrate` и каталог
469`~/Games/Chimera`, но развязка вышла неполной. Путь был зашит в код. Из
470чужого каталога копировалась папка `scripts/` целиком — 9,6 МБ питона
471StartWine, который мы не запускаем, — и признаком «это каталог данных»
472служило именно её наличие, так что удалить StartWine всё ещё было нельзя.
473Абсолютные пути внутри префиксов не правились вовсе, кроме одного поля в
474библиотеке.
475
476**Решение.** Каталог данных — свой, опознаётся файлом-меткой
477`data/.chimera-каталог`, а не чужой папкой. Путь к нему — настройка
478`data_root`; пусто означает `~/Games/Chimera`. Из `scripts/` забираются два
479файла каталогов версий в свой `data/catalogs/`. Перенос — команда
480`chl move-root <путь>`: по умолчанию отчёт, действие по `--apply`.
481
482**Почему по умолчанию `~/Games/Chimera`, а не каталог по XDG.** Внутри —
483префиксы и сборки Wine, на этой машине 301 ГиБ логического объёма. Это
484данные, которые уносят на другой диск, когда на системном становится тесно,
485и каталог, на который предполагается показывать пальцем в файловом
486менеджере, не должен лежать в скрытой папке. Так же поступают соседи: Heroic
487ставит игры в `~/Games/Heroic`, Lutris предлагает `~/Games`. За XDG остаётся
488то, что мало и ценно: настройки, библиотека, журналы запусков.
489
490**Почему один общий префикс, а не по префиксу на игру.** Прямое требование
491владельца: «Основная задача — минимизировать потребление ресурсов и
492дискового пространства. Иначе у нас раздуется до террабайтов префиксы игр».
493Он держал общий префикс в StartWine годами, и это работало. Разные игры
494разводятся настройками, а не копиями Windows.
495
496**Почему `--reflink=always`, а не `auto`.** `auto` при отказе reflink молча
497копирует полностью. На 301 ГиБ это означает незамеченный расход диска
498вместо ошибки. `always` в том же случае падает, и способ переноса выбирается
499заранее — пробным reflink настоящего файла в целевом каталоге, а не по имени
500файловой системы: btrfs с `nodatacow` — это btrfs, у которого reflink на
501этом подтоме не работает.
502
503**Что переезд ломает внутри префиксов.** Это оказалось главной работой, а не
504деталью. Регистрация шрифтов в `system.reg`/`user.reg` записана абсолютными
505DOS-путями внутрь сборки Wine, и написаний два — через `H:` и через `Z:`,
506потому что буквы дисков ведут в разные места. Всё вне ASCII Wine пишет
507шестнадцатеричным экраном (`\x441\x442…`), так что поиск по тому, как путь
508выглядит, на каталоге с русским именем не находит ничего. Ярлыки
509`.desktop` в `drive_c` хранят unix-путь. Ссылка `dosdevices/e:`
510абсолютная. Ссылка `drive_c/Games` создаётся под условием «если её ещё нет»
511и битой остаётся навсегда. Подробный разбор с пометкой, что чинится само, а
512что нет, — в шапке `chl-wine/src/rebase.rs` и в вики проекта.
513
514**Почему старый каталог не удаляется.** Перенос заканчивается тем, что новый
515каталог рабочий, а старый лежит как лежал. Откат — вернуть настройку.
516Освободить место — отдельное решение владельца отдельной командой. На
517reflink это ничего не стоит: 301 ГиБ логических данных в двух каталогах
518занимают на диске 218 МиБ сверх исходного.
519
520**Цена.** Два способа опознать каталог данных (метка и `data/scripts`), пока
521жив `chl migrate`. Плюс сам `move-root` — код, который правит реестр
522работающих префиксов, то есть обязан быть точным: ошибка здесь ломает
523запуск. Отсюда журнал перед действием и проверка после — не «файлы
524скопированы», а «префикс открывается, сборка отвечает своей версией, игры
525находятся».
526
527**Проверяемость.** Живой прогон 2026-09-07 на 301,69 ГиБ данных владельца:
52832 правки путей в 3 префиксах, 12 снимках и шаблоне (173 вхождения в
529реестре), время копирования 5,8 с. `btrfs filesystem du -s` до: 7,57 ГиБ
530исключительных. После: 167 МиБ у старого и 51 МиБ у нового при 301 ГиБ
531логического объёма в каждом. Из перенесённого каталога запущена Gothic 1
532Remake — главное меню, VKD3D 60 fps, VRAM 9,1 ГиБ, `WINEPREFIX` и
533`WINEDLLPATH` процесса ведут в новый каталог, ни одного отображённого файла
534из старого.
535
536---
537
538## ADR-013. macOS не поддерживаем
539
540**Дата:** 2026-09-11. **Статус:** принято.
541
542### Контекст
543
544Разобрали GameHub — лаунчер Windows-игр для macOS — и возник вопрос, не сделать
545ли то же самое у себя: один лаунчер на Linux и macOS.
546
547### Решение
548
549Не делаем. Силы идут в качество продукта на Linux.
550
551### Почему
552
553Три независимых стены, каждая сама по себе — отдельный проект:
554
5551. **Интерфейс.** GTK4 на macOS второсортен, а WebKitGTK там просто нет —
556 витрины магазинов пришлось бы переписывать на WKWebView. Плюс `ksni` (трей
557 через D-Bus), `ashpd` (XDG-порталы), `evdev` в двух крейтах (геймпады и
558 хоткеи через `/dev/input`): четыре подсистемы заново.
5592. **Рантайм.** Мы стоим на Proton, Vulkan и DXVK/VKD3D. На macOS ничего этого
560 нет — там GPTK, MoltenVK, DXMT, то есть второй бэкенд запуска размером с
561 половину проекта. Отдельно открыт вопрос, что из этого вообще допустимо в
562 проекте под GPL-3.0-or-later.
5633. **Железо.** Apple Silicon — ARM, а игры x86. Нужен слой трансляции
564 (Rosetta, FEX), которого у нас нет вовсе.
565
566### Что это значит на практике
567
568- Разведка на MacBook отменена, задание снято.
569- Разбор GameHub не выброшен: его выводы — стабильный ключ игры, слои профилей,
570 рецепты зависимостей, метка процесса, исключения на `.exe` — про устройство
571 лаунчера вообще, а не про macOS. Они в фазе 6 `ROADMAP.md`.
572- Разрез «переносимое ядро / платформенный слой» остаётся полезным сам по себе
573 (тесты без GTK, Steam Deck), но делается по месту, а не кампанией под macOS.
574
575### Если решение будут пересматривать
576
577Пересматривать имеет смысл только вместе с ответом на три стены выше. Первым
578пунктом — лицензионный разбор графического слоя: без него порт упирается не в
579трудоёмкость, а в право.
580