Project Chimera
Меню

Исходники

487 строк · 44 КиБ

code/crates/chl-wine/WINE-UPDATES-DESIGN.md

1# Обновления Wine и лаунчера: что исследовано, что спроектировано, что сделано
2
3Фаза 2 ([ROADMAP.md](../../../ROADMAP.md), обоснование — [ADR-004](../../../DECISIONS.md)).
4Формат и тон — как у [`CAS-DESIGN.md`](CAS-DESIGN.md) из фазы 1: исследование
5на реальных данных, план для рискованных частей, код — только там, где после
6исследования есть настоящая уверенность.
7
8У фазы пять пунктов в ROADMAP. Ниже — по каждому: что выяснилось, что решено,
9что сделано в этом проходе и что осознанно оставлено дизайном.
10
11## Как сейчас на самом деле устроена установка Wine (до этого прохода)
12
13Прочитано целиком: `crates/chl-wine/src/catalog.rs`, `crates/chl-wine/src/install.rs`.
14
15**Источник каталога.** `catalog::Catalog::load` читает `data/scripts/
16wine_version.json` — тот же файл, что писал bash StartWine
17(`sw_runlib:658`). Формат неудачный: значение канала — одна строка со
18ссылками через пробел, не список JSON, версии не выделены как данные. Своего
19источника каталога у Chimera до этого прохода не было вообще — читался
20чужой формат ради совместимости, с оговоркой в заголовке модуля «свой
21манифест — задача фазы 2».
22
23**Установка.** `Installer::install` качает архив (`ureq`, потоково, в
24`.частично`-файл, атомарный `rename` только после того, как размер совпал с
25`Content-Length`), распаковывает системным `tar` в соседний временный
26каталог и переносит его на место одним `rename`. Устойчиво к обрыву на
27середине — но **до этого прохода не проверяло контрольную сумму или подпись
28вообще**. Собственный комментарий модуля говорил об этом прямо: «в каталоге
29StartWine их просто нет — есть только ссылки. Пока это честно отмечено, а не
30выдано за безопасную загрузку». Скачанный архив от источника, который сам
31себя не проверяет, распаковывался и становился тем, чем запускаются игры —
32Wine-сборка исполняется с полными правами пользователя, порченый или
33подменённый архив это не абстрактный риск.
34
35## Что реально публикуют апстримные источники (проверено `curl`, 2026-09-03)
36
37`wine_version.json` реальной установки (`~/Games/Chimera/data/scripts/
38wine_version.json`) ссылается на три источника:
39
40| Канал | Источник | Контрольная сумма | Формат |
41|---|---|---|---|
42| `wine_staging`, `wine_staging_tkg` | `github.com/Kron4ek/Wine-Builds` | **да** | `sha256sums.txt`, один файл на релиз, формат `sha256sum` |
43| `wine_proton_ge` (91 сборка — самый ходовой канал, см. `catalog::channel_hint`) | `github.com/GloriousEggroll/proton-ge-custom` | **да, но sha512** | `<имя-без-расширения>.sha512sum`, отдельный файл на архив |
44| `wine_steam_proton` | `github.com/RusNor/Wine-Steam-Proton` | **нет** | ничего не публикуется |
45
46Проверено не по документации, а запросами к настоящим релизам:
47
48```bash
49curl -sL https://github.com/GloriousEggroll/proton-ge-custom/releases/download/GE-Proton11-6/GE-Proton11-6-x86_64.sha512sum
50# 543e3af5...cb5fcb GE-Proton11-6-x86_64.tar.gz (128 hex = sha512)
51
52curl -sL https://github.com/Kron4ek/Wine-Builds/releases/download/11.16/sha256sums.txt
53# bb4d0eba... wine-11.16-amd64.tar.xz (64 hex = sha256, несколько файлов сразу)
54
55curl -s https://api.github.com/repos/RusNor/Wine-Steam-Proton/releases/tags/steam-proton-11.0.2
56# assets: только steam-proton-11.0.2.tar.xz, ни одного checksum-файла рядом
57```
58
59**Первая находка, которая меняет план.** Ни GitHub Releases GE-Proton, ни
60Kron4ek не подписаны PGP/ключом — только контрольная сумма, лежащая в том же
61релизе, что и архив. Это не «подпись от источника», а тот же самый уровень
62доверия, что и сам архив: тот, кто может подменить релиз на GitHub, может
63подменить и сумму рядом с ним. Расчёт на «апстрим уже всё подписал» был бы
64неверным.
65
66**Вторая находка.** Алгоритмы не совпадают между источниками. GE-Proton —
67самый часто используемый канал в этом проекте — публикует **sha512**, а не
68sha256, которым уже пользуются `chl_wine::dedup`/CAS. Притворяться, что
69везде sha256, означало бы либо не проверять GE-Proton вовсе (худший канал
70для такого пропуска — он самый ходовой), либо переврать данные апстрима.
71
72**Третья находка.** У `wine_steam_proton` (RusNor — репак бинарников Valve,
73не сам Valve) нет ни одного проверяемого источника. Единственный способ
74получить хэш для этого канала — скачать архив самим и посчитать (TOFU:
75доверяем первому скачиванию, дальше проверяем по нему).
76
77**Вывод для дизайна.** «Подписанный манифест» из ADR-004 не может означать
78«просто скопировать хэш апстрима» — апстрим либо не публикует ничего
79проверяемого (треть каналов), либо публикует его тем же способом, что и
80архив (остальные две трети), не давая независимого канала доверия. Значит
81манифест — это **свой** список, который Chimera составляет сама (забирая то,
82что публикуют источники, где это есть) и подписывает **своим** ключом. Сама
83подпись — это то новое звено доверия, которого у апстрима нет вообще.
84
85## Пункт 1 — манифест с хэшами, подписанный ed25519
86
87### Формат
88
89`chl_wine::manifest::Manifest`: список записей `(имя, канал, url, архитектура,
90имя файла, размер, sha256 ИЛИ sha512)`. Сериализуется как JSON, поле
91`checksum` намеренно несёт алгоритм (`catalog::Checksum::Sha256`/`Sha512`),
92а не голый хэш — ровно из-за находки про GE-Proton выше. Записи
93отсортированы `(канал, имя)` перед подписью — без этого один и тот же набор
94сборок давал бы разные байты на подпись в зависимости от порядка сборки
95манифеста, и подпись пришлось бы сверять не по содержимому.
96
97### Модель доверия (см. `crates/chl-wine/src/sign.rs`, там же развёрнутое обоснование в doc-комментариях)
98
99**У проекта один поддерживающий и один подписывающий ключ** — то же
100допущение, которое ADR-004 сам называет условием задачи. Открытый ключ
101закоммичен как обычный текстовый файл (`keys/wine-manifest.pub`, не секрет)
102и зашивается в бинарник `chl` через `include_str!` на этапе сборки —
103подменить доверенный ключ значит собрать другой бинарник `chl`, а не
104подложить файл рядом с установленным. Секретный ключ никогда не попадает в
105git ни в каком виде — `chl wine manifest keygen` печатает его один раз в
106stdout, дальше сохранить (и куда) решает тот, кто запускает команду.
107
108**Почему подпись, а не только хэш** (тот вопрос, который задание прямо
109просило продумать, а не проскочить). Хэш в манифесте защищает архив от
110повреждения и от подмены на зеркале — если сам список хэшей достоверен.
111Манифест тоже откуда-то доставляется, и если он попадёт к пользователю не с
112исходного хоста, а через кэш, старую копию на диске или чей-то мирроринг,
113вопрос повторяется этажом выше: откуда мы знаем, что список хэшей — тот, что
114на самом деле собрал владелец проекта? Подпись сужает это до одного
115проверяемого факта: «манифест подписан тем же ключом, чей открытый ключ
116вшит в этот бинарник при сборке». Это не более сильное доверие, чем то,
117что пользователь и так оказывает бинарнику `chl` (тот же человек собирает
118оба), но оно **явное и проверяемое кодом**, а не «раз запускаю бинарник,
119доверяю всему, что он скажет».
120
121**Чего эта схема осознанно не даёт**, и это стоит держать в виду, а не
122скрывать: она не защищает от компрометации машины с секретным ключом (как
123любая single-signer схема), и не проверяет содержимое сборки Wine на
124вредоносность — только то, что список (имя, хэш) ровно тот, что подписал
125владелец. Достоверность того, что архив по URL в момент составления
126манифеста был подлинным апстримным релизом, — ответственность владельца в
127момент выпуска манифеста, не свойство самого кода.
128
129### Что сделано и проверено
130
131- `chl_wine::catalog::Checksum` — тип с алгоритмом (`Sha256`/`Sha512`), не
132 голый `Option<String>`.
133- `chl_wine::sign` — генерация пары, подпись, проверка, hex-кодирование.
134 6 юнит-тестов: круговой обмен через hex, подпись/проверка тем же ключом,
135 провал при подмене байта сообщения, провал при чужом ключе, отсутствие
136 паники на битых hex-строках.
137- `chl_wine::manifest` — сборка манифеста из существующего каталога
138 StartWine, подтяжка контрольных сумм у источников, которые их публикуют,
139 сохранение/загрузка/проверка подписи. 11 юнит-тестов, часть — на
140 **настоящих** данных, полученных `curl` (см. таблицу выше), не на
141 выдуманных фикстурах.
142- `Installer::install` теперь проверяет `checksum` архива **до**
143 распаковки, если он есть в `Build`; несовпадение стирает файл из кэша
144 (иначе следующая попытка молча нашла бы тот же испорченный файл) и
145 останавливает установку с объясняющей ошибкой. Архив без хэша (сегодняшний
146 `wine_version.json`) ставится как раньше — без проверки, но честно, без
147 претензии на безопасность, которой нет.
148- `chl wine manifest {build,keygen,sign,verify}` — CLI поверх всего этого.
149- `chl wine install` теперь сначала ищет подписанный манифест
150 (`$XDG_DATA_HOME/chimera-launcher/wine-manifest.json` + `.sig`), проверяет
151 его против вшитого ключа, и только при отсутствии файла или провале
152 проверки откатывается на `wine_version.json` — с явным сообщением о
153 причине отката, не молча.
154
155### Проверено на реальных данных, не только юнит-тестами
156
157```
158$ chl wine manifest keygen
159публичный ключ: 13e8f39a... секретный ключ: 2ef7e0ea...
160
161$ chl wine manifest build --out manifest.json --root ~/Games/Chimera --fetch-checksums
162собираю манифест из 268 сборок, подтягиваю контрольные суммы...
163манифест записан: manifest.json
164сборок: 268, с проверяемой контрольной суммой: 243, без неё: 25
165
166$ chl wine manifest sign --manifest manifest.json --key secret.key
167$ chl wine manifest verify --manifest manifest.json --pubkey 13e8f39a...
168подпись верна: manifest.json
169```
170
171По каналам: `wine_proton_ge` 91/91, `wine_staging` 76/76, `wine_staging_tkg`
17276/76, `wine_steam_proton` 0/25 — ровно то, что предсказывает таблица
173источников выше. Подмена содержимого манифеста после подписи (проверено:
174поменял `url` одной записи) даёт `подпись не совпадает — манифест подделан
175или испорчен`, как и должно.
176
177**Регрессия, найденная этим же прогоном, а не воображением.** Первая версия
178строила адрес сайдкара GE-Proton как `<url-архива>.sha512sum», что даёт
179`GE-Proton11-6-x86_64.tar.gz.sha512sum` — реальный сервер отвечает на такой
180путь `404`. Настоящий сайдкар назван по имени сборки **без** расширения
181архива: `GE-Proton11-6-x86_64.sha512sum`. Из-за этого первый прогон дал
182`wine_proton_ge: 0/91` — молчаливый ноль, не ошибка сборки. Исправлено
183(`ge_proton_sidecar_url`), закреплено регрессионным тестом на настоящем URL,
184и после исправления прогон дал `91/91`. Урок: недостаточно, что код
185компилируется и «правдоподобно» строит URL — реальный ответ сервера — это
186то, что решает, а не структура строки.
187
188### Осознанно не сделано в этом проходе
189
190Реальный производственный ключ (`keys/wine-manifest.pub`) **не сгенерирован
191и не закоммичен** — файл оставлен пустым, `verify_trusted` при этом честно
192отказывает («в этой сборке chl не зашит доверенный ключ») вместо того чтобы
193тихо считать всё непроверенным доверенным. Генерация настоящего ключа,
194решение, где хранить секретную половину, и процедура его ротации — то самое
195решение владельца, о котором прямо предупреждает ADR-004 («забыть про
196ротацию нельзя»), и которое агент не должен принимать в одиночку — тот же
197принцип, что у CAS-DESIGN.md («показать документ владельцу до того, как
198писать пул»). Когда владелец решит опубликовать первый манифест:
199`chl wine manifest keygen` → секретный ключ туда, где он реально его хранит
200(вне git) → публичный ключ в `crates/chl-wine/keys/wine-manifest.pub` →
201`chl wine manifest build --fetch-checksums` → `chl wine manifest sign` →
202получившийся `.json`/`.json.sig` в `$XDG_DATA_HOME/chimera-launcher/`.
203
204`wine_steam_proton` (25 сборок) остаётся без проверяемого хэша: у источника
205его нет, а массово перекачивать 25 архивов ради хэша одним автоматическим
206проходом (десятки гигабайт) в эту итерацию не входило — см. `hash_downloaded`
207в `manifest.rs`, функция есть и работает, но `manifest build` её не
208вызывает по всему каталогу автоматически.
209
210## Пункт 2 — дифф-загрузка вместо перекачивания архива целиком
211
212**Рекомендация: не строить в этот проход, и, вероятно, не строить вообще без
213новых фактов.** То же правило, что уже применено в CAS-DESIGN.md к
214content-defined chunking: измерить, прежде чем выбирать сложную схему, а не
215проектировать её на веру.
216
217**Что доступно у источников.** Все три апстримных источника (GE-Proton,
218Kron4ek, RusNor) — это одиночные архивы GitHub Releases, `tar.gz`/`tar.xz`
219целиком, без чанкованного или файл-адресуемого формата. Ни один из них не
220даёт способа скачать «только изменившиеся файлы» без либо (а) собственного
221пересборки/повторного хостинга контента в другом формате, либо (б)
222предвычисленного бинарного диффа (bsdiff-стиля) между двумя конкретными
223версиями.
224
225**Оба пути дорогие для проекта с одним поддерживающим и без CDN.** (а)
226означает содержать зеркало, которое переупаковывает архивы каждого канала в
227файл-адресуемый вид — постоянная инфраструктура, которой у проекта нет и не
228предполагается (манифест по дизайну — статический файл, не сервис). (б)
229означает считать и хранить дифф на каждую пару соседних версий каждого
230канала — работа, которая растёт с каждым новым релизом апстрима, а
231пользуется ею только тот, кто обновляется именно с непосредственно
232предыдущей версии в узкое окно, пока дифф ещё актуален.
233
234**Реальные числа, а не оценка на глаз** (проверено `curl`/GitHub API,
2352026-09-03):
236
237| Канал | Размер архива | Cadence релизов |
238|---|---|---|
239| `wine_proton_ge` (x86_64) | 533,7 МБ | ~2–3 недели (GE-Proton11-6 → 11-5 → 11-4 за 17 дней) |
240| `wine_staging` (amd64) | 103,7 МБ | ~2 недели (Kron4ek 11.16 → 11.15 за 11 дней) |
241| `wine_steam_proton` | 355,9 МБ | нерегулярно |
242
243**Почему это низкий приоритет именно в этом проекте, а не только «дорого
244вообще».** Пункт 3 (закрепление версии за игрой) уже сделан — не этим
245проходом, а существующей инфраструктурой фаз 0–1 (см. ниже): обновление
246Wine-сборки **не автоматическое и не фоновое**, это осознанное разовое
247действие «поставь мне вот эту конкретную новую сборку» через `chl wine
248install <build>`, за которым следует явная смена `wine` в конфиге игры. Это
249не поток одного и того же пользователя, качающего дельту раз в несколько
250дней, — это редкое, штучное решение. Экономия дифф-загрузки окупает
251сложность там, где обновления частые и автоматические; здесь они редкие и
252ручные по дизайну самого проекта.
253
254**Что вместо этого уже даёт реальную экономию — CAS, а не сетевой дифф.**
255`CAS-DESIGN.md` (фаза 1) показал: 2,7 из 3,0 ГиБ дубля в реальной установке
256— это одинаковые файлы (Gecko/Mono/ICU/ONNX-бандлы) **между уже
257установленными** сборками Wine/Proton. `chl cas adopt` уже дедуплицирует их
258**на диске** после установки. Это не уменьшает объём скачивания, но снимает
259значительную часть реальной боли (место на диске) более простым и уже
260реализованным механизмом — задача, для которой изначально предполагалась
261дифф-загрузка, отчасti уже решена другим, более дешёвым способом.
262
263**Вывод: design-only, с честной рекомендацией не браться, пока не появится
264новый факт** (например: источник начнёт публиковать патчи официально, или у
265проекта появится собственный CDN-хостинг манифеста, меняющий экономику).
266Если наблюдение когда-нибудь изменится — держатель канала начнёт публиковать
267собственные дельты, или у одного и того же пользователя обновления станут
268частыми и автоматическими — стоит пересчитать заново, а не переносить вывод
269по умолчанию.
270
271## Пункт 3 — закрепление версии Wine за игрой
272
273**Находка: этот пункт уже решён существующей инфраструктурой фаз 0–1, новый
274код не требуется.** Проверено чтением и трассировкой реального пути кода,
275не предположением:
276
2771. **Конфиг игры хранит `wine` явным полем** (`crates/chl-core/src/
278 settings.rs`, `Spec { key: "wine", ... }`, `impact`: «Здесь версия
279 закреплена за игрой: обновление лаунчера её не меняет, поэтому работающая
280 игра не ломается сама по себе» — формулировка уже была в реестре
281 настроек до этого прохода).
2822. **Ничего не пишет в это поле автоматически.** `resolve_launch`
283 (`crates/chl-cli/src/main.rs:2431`) читает `cfg.text("wine")`, и только
284 если оно **пусто** — падает на `Prefix::built_with()` (метка `.chl-wine`
285 внутри префикса, чем он реально собран) или на единственную установленную
286 сборку. Ни один из вызовов `cfg.set("wine", ...)` в `main.rs`
287 (строки ~774, ~1118, ~2678) не сопровождается `cfg.save()` — все три
288 меняют только локальную копию перед сборкой окружения для текущего
289 запуска, ни один не трогает файл на диске. Проверено `grep`: во всём
290 `chl-cli` нет ни одного `cfg.save`/`GameConfig::save` для этих мест.
2913. **`chl wine installed` только сообщает о более новой сборке**
292 («есть новее: …»), ничего не переключает — тот самый механизм, который
293 уже печатает сравнение с каталогом, не трогает ни один конфиг игры.
2944. **GUI пишет `wine` в конфиг только явным действием пользователя**
295 (`crates/chl-gui/src/game_page.rs:611`, `save_setting(&game, "wine",
296 &value)` — вызывается из обработчика выбора сборки на странице игры, а
297 не откуда-либо ещё).
2985. **Смена сборки уже защищена снимком.** `chl_core::state::SnapshotReason
299 ::WineChanged` — снимок делается автоматически перед тем, как
300 применится изменившаяся сборка, независимо от того, что именно её
301 изменило.
302
303Ровно то, что просит ADR-004 («обновление не может сломать работающую игру
304… версия закреплена за игрой; обновление добавляет новую, переключение —
305осознанное действие с откатом») — уже так и работает. Единственное, что этот
306проход добавляет к этой картине — сам манифест (пункт 1): раньше «версия»
307была именем без проверяемого содержимого, теперь у неё есть привязанный
308хэш, и переключение версии в конфиге игры остаётся тем же осознанным
309действием, что и раньше, только теперь ещё и с проверкой того, что
310установленная сборка — действительно та, что называется этим именем.
311
312**Что не сделано и не нужно** — отдельная команда `chl wine pin <игра>
313<сборка>`. Рассмотрена и отклонена: она добавила бы второй путь к тому же
314результату, которого уже достигает `chl settings`/GUI/ручная правка TOML,
315не решая ничего, чего сейчас не решить. Если появится конкретный сценарий,
316где явной команды не хватает, — отдельный проход, не эта итерация.
317
318## Пункт 4 — атомарное обновление самого лаунчера с откатом
319
320> **Сделано 2026-09-07** — крейт `chl-selfupdate`, обёртки `chl update` и
321> раздел «Обновления» в интерфейсе. Решение и полный список того, чего эта
322> схема **не** даёт, — [ADR-012](../../../DECISIONS.md); ход работы —
323> запись 2026-09-07 в `DEVLOG.md`.
324>
325> Набросок ниже оставлен как есть, не переписан задним числом: реализация
326> пошла по нему почти дословно, и полезнее видеть, что́ было спроектировано
327> до кода, чем задним числом привести описание в соответствие с результатом.
328> Три открытых вопроса в конце этого раздела **закрыты** — ответы в ADR-012,
329> коротко: каталог берётся из `current_exe()`, а не из зашитого
330> `~/.local/bin`; проверка автоматическая, а установка никогда; бинарника
331> два, это одна установка на двоих, и обновляются они одним манифестом за
332> один проход (список заменяемых имён закрытый).
333>
334> Единственное, чего в наброске не было и что добавилось при реализации, —
335> **журнал** (`.chl-обновление.toml`, пишется до каждого шага). Он понадобился
336> ровно потому, что бинарника оказалось два: `rename` атомарен, но два
337> `rename` подряд — уже нет, и момент, когда на диске смесь версий, скрыть
338> нельзя, можно только сделать распознаваемым.
339
340**Почему это было design-only** (сохранено для истории): это код, ошибка в
341котором **отключает единственный работающий бинарник** — если
342самообновление сломает `chl`, у пользователя не останется рабочего лаунчера
343чем это чинить, кроме переустановки руками. Задание того прохода прямо
344предлагало рассмотреть, стоит ли вообще браться за код, — тогда стоило не
345браться.
346
347### Набросок дизайна (написан до реализации; реализовано 2026-09-07)
348
349**Что уже переиспользуется без изменений:** тот же манифест и та же подпись,
350что у сборок Wine (пункт 1) — запись о самом бинарнике `chl` (версия, hash,
351URL) может жить в том же подписанном файле или в соседнем с тем же форматом.
352Ключ и модель доверия те же, второй схемы заводить не нужно.
353
354**Схема замены файла.** На Linux заменить исполняемый файл работающего
355процесса безопасно: `rename()` на месте `chl` не трогает уже открытый
356inode запущенного процесса — текущий запуск доработает со старым кодом,
357следующий запуск возьмёт новый файл. Порядок:
358
3591. Скачать новую версию во временный файл **рядом** с текущим `chl`
360 (та же файловая система — важно для атомарности `rename`), тем же кодом
361 скачивания и проверки, что уже есть в `install.rs`.
3622. Проверить hash из манифеста **и** подпись манифеста — то же самое, что
363 пункт 1 уже делает для сборок Wine.
3643. Сохранить текущий бинарник как `chl.previous` рядом (для отката) —
365 `rename`, не копия: то же самое, что `install.rs` уже делает с
366 `staging`-каталогом сборки Wine.
3674. `rename` нового файла на место текущего `chl`. Атомарно на уровне
368 файловой системы.
3695. **Проверка здоровья при следующем запуске**, не при самом обновлении:
370 пишем маркер «обновился, ещё не подтверждён» перед тем, как отдать
371 управление новому коду; новый процесс стирает маркер после того, как
372 успешно дошёл до места, откуда обычно начинается реальная работа (не
373 сразу при старте — на старте ещё нельзя отличить «работает» от «упал бы
374 через секунду»). Если `chl` при следующем запуске видит маркер **уже
375 выставленным** прошлым запуском — предыдущий запуск не дожил до
376 подтверждения, откатываем `chl.previous` обратно на место автоматически,
377 без вопроса пользователю: рабочий лаунчер важнее последней версии.
378
379**Открытые вопросы, которые нужно решить с владельцем до кода, не по ходу
380реализации** (все три закрыты 2026-09-07, ответы — в ADR-012):
381
382- Где физически лежит `chl` на реальной установке (`~/.local/bin`?
383 системный путь через пакет?) — `packaging/install.sh` уже решает это для
384 первой установки, самообновление обязано писать туда же, а не изобретать
385 второй путь.
386- Автоматическое обновление или только «есть новее, накатить?» — учитывая,
387 что GUI уже сейчас ничего не обновляет автоматически нигде (сравни с
388 `chl wine installed`, которое только сообщает), фоновое самообновление без
389 спроса было бы architectural-несоответствием остальному проекту.
390- Что происходит с GUI-процессом (`chl-gui`), если он запущен в момент
391 обновления CLI-бинарника — они разные исполняемые файлы или одна установка
392 на двоих? (Сейчас не проверялось — отдельный вопрос для дизайна, не для
393 этого прохода.)
394
395## Пункт 5 — patch notes из истории коммитов, с фильтром по используемым функциям
396
397**Сделано.** Источник — не `git log` напрямую, а уже существующий
398`DEVLOG.md`: он и так пишется по правилу «дата — что сделано — что
399выяснилось — что дальше» на каждую сессию, human-readable, содержательнее
400сырых сообщений коммитов. Задание в ROADMAP говорит «из истории коммитов» —
401`DEVLOG.md` и есть человекочитаемая история коммитов этого проекта, просто
402уже курируемая, а не сырая.
403
404`chl_core::devlog`:
405- `parse()` — разбор по заголовкам `## `, с настоящим текстом настоящего
406 `DEVLOG.md`, зашитым в бинарник через `include_str!` на этапе сборки (тот
407 же приём, что и вшитый публичный ключ манифеста) — patch notes читаются в
408 установленном лаунчере, не только рядом с исходниками.
409- `relevant_to()` — фильтр по «используемым функциям»: настройки, заданные
410 в конфиге игры **не по умолчанию** (`Origin::User`/`Origin::Migrated`),
411 сверяются подстрочным совпадением человеческого названия настройки
412 (`Spec::title`) с текстом записи.
413
414**Честно про качество фильтра**, а не по умолчанию «работает точно»: это
415эвристика по подстроке, не разбор смысла. `DEVLOG.md` — свободный текст,
416написанный людьми задолго до появления этого фильтра, никакой структурной
417связи с реестром настроек в нём никогда не было. Один из юнит-тестов
418(`известное_ограничение_падеж_ломает_подстрочное_совпадение`) фиксирует
419конкретный, настоящий пробел: «Сборку Wine» (винительный падеж, как реально
420пишут в прозе) не совпадёт с «Сборка Wine» (именительный, как хранится в
421реестре) при обычном поиске подстроки. Это не баг, который стоит чинить
422здесь морфологическим анализом — если точность когда-нибудь понадобится,
423придётся заводить теги в самом `DEVLOG.md` начиная с этого дня, не
424разбирать прошлое эвристикой.
425
426Команда `chl changelog [--game <игра>] [--limit N]`. Без `--game` — просто
427показ записей (проверено на настоящем `DEVLOG.md` — 5 записей на
4282026-09-03). С `--game` — фильтр по нестандартным настройкам этой игры,
429проверено на реальном конфиге (`bananarfo.toml`: `wine`, `dxvk_version`,
430`mangohud`, `vkbasalt`, … — нашёл релевантные записи про Wine, MangoHud,
431изоляцию). Игра без единой нестандартной настройки честно получает пустой
432список с объяснением, а не «всё подряд».
433
4349 юнит-тестов в `chl_core::devlog`, включая разбор настоящего `DEVLOG.md`
435без падения (`встроенный_devlog_разбирается_без_паники`) — единственное
436свойство, которое проверяется у живого, растущего файла, а не конкретное
437число записей.
438
439## Итог: что сделано, что design-only, и почему
440
441| Пункт ROADMAP | Статус | Где |
442|---|---|---|
443| 1. Манифест с хэшами, подписанный ed25519 | **Реализовано и проверено на реальных апстримных данных** (без реального продакшн-ключа — см. выше) | `chl_wine::{catalog,install,manifest,sign}`, `chl wine manifest *` |
444| 2. Дифф-загрузка | Design-only, рекомендация — не строить без новых фактов | этот документ |
445| 3. Закрепление версии за игрой | **Уже было сделано фазами 0–1** — новый код не требовался, только верификация | `chl_core::config`, `chl_core::state`, `chl_wine::prefix::Prefix::{remember_build,built_with}`, `chl-gui/src/game_page.rs` |
446| 4. Атомарное самообновление с откатом | **Реализовано 2026-09-07** (без реального продакшн-ключа установка отказывает намеренно — см. ADR-012) | `chl-selfupdate`, `chl update`, `chl update-manifest`, раздел «Обновления» |
447| 5. Patch notes с фильтром | **Реализовано и проверено на реальном `DEVLOG.md`** | `chl_core::devlog`, `chl changelog` |
448
449**Что стоит отметить в ROADMAP.md как готово** — консервативно, тем же
450стандартом, что CAS/dedup-проход: пункт 3 (уже было сделано и теперь
451верифицировано, а не «почти»), пункт 5 (сделано и проверено на реальных
452данных). Пункт 1 — **не отмечать как полностью готовый**: сама
453инфраструктура готова и проверена сквозным прогоном на реальных
454апстримных данных, но без настоящего продакшн-ключа система не защищает ни
455одну реальную установку — до `chl wine manifest keygen` от владельца это
456готовый, но не включённый механизм. Пункт 2 остаётся открытым — по плану,
457design-only. Пункт 4 закрыт 2026-09-07 отдельным проходом, с той же
458оговоркой, что у пункта 1: механизм готов и проверен сквозным прогоном, но
459без настоящего ключа владельца он ничего не устанавливает — и говорит об этом
460вслух, а не отказывает в конце.
461
462## Как перепроверить
463
464```bash
465cd ~/Projects/chimera-launcher/code
466cargo build --release --workspace
467cargo clippy --workspace --all-targets # 0 предупреждений
468cargo test --workspace # 316 тестов, было 286 до этого прохода
469
470BIN=~/.cache/chimera-launcher/target/release/chl
471
472# сквозной прогон манифеста на реальных данных
473"$BIN" wine manifest keygen > /tmp/keys.txt
474"$BIN" wine manifest build --out /tmp/manifest.json --root ~/Games/Chimera --fetch-checksums
475"$BIN" wine manifest sign --manifest /tmp/manifest.json --key <(tail -1 /tmp/keys.txt)
476"$BIN" wine manifest verify --manifest /tmp/manifest.json --pubkey <(sed -n 2p /tmp/keys.txt)
477
478# patch notes на реальном DEVLOG.md
479"$BIN" changelog --limit 3
480"$BIN" changelog --game bananarfo # или любая игра с реальным конфигом
481
482# откуда взялась таблица источников выше — не выдумана
483curl -sL https://github.com/GloriousEggroll/proton-ge-custom/releases/download/GE-Proton11-6/GE-Proton11-6-x86_64.sha512sum
484curl -sL https://github.com/Kron4ek/Wine-Builds/releases/download/11.16/sha256sums.txt
485curl -s https://api.github.com/repos/RusNor/Wine-Steam-Proton/releases/tags/steam-proton-11.0.2
486```
487