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/ |
| 16 | wine_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 | вообще**. Собственный комментарий модуля говорил об этом прямо: «в каталоге |
| 29 | StartWine их просто нет — есть только ссылки. Пока это честно отмечено, а не |
| 30 | выдано за безопасную загрузку». Скачанный архив от источника, который сам |
| 31 | себя не проверяет, распаковывался и становился тем, чем запускаются игры — |
| 32 | Wine-сборка исполняется с полными правами пользователя, порченый или |
| 33 | подменённый архив это не абстрактный риск. |
| 34 | |
| 35 | ## Что реально публикуют апстримные источники (проверено `curl`, 2026-09-03) |
| 36 | |
| 37 | `wine_version.json` реальной установки (`~/Games/Chimera/data/scripts/ |
| 38 | wine_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 |
| 49 | curl -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 | |
| 52 | curl -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 | |
| 55 | curl -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, ни |
| 60 | Kron4ek не подписаны PGP/ключом — только контрольная сумма, лежащая в том же |
| 61 | релизе, что и архив. Это не «подпись от источника», а тот же самый уровень |
| 62 | доверия, что и сам архив: тот, кто может подменить релиз на GitHub, может |
| 63 | подменить и сумму рядом с ним. Расчёт на «апстрим уже всё подписал» был бы |
| 64 | неверным. |
| 65 | |
| 66 | **Вторая находка.** Алгоритмы не совпадают между источниками. GE-Proton — |
| 67 | самый часто используемый канал в этом проекте — публикует **sha512**, а не |
| 68 | sha256, которым уже пользуются `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 | подложить файл рядом с установленным. Секретный ключ никогда не попадает в |
| 105 | git ни в каком виде — `chl wine manifest keygen` печатает его один раз в |
| 106 | stdout, дальше сохранить (и куда) решает тот, кто запускает команду. |
| 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` |
| 172 | 76/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 к |
| 214 | content-defined chunking: измерить, прежде чем выбирать сложную схему, а не |
| 215 | проектировать её на веру. |
| 216 | |
| 217 | **Что доступно у источников.** Все три апстримных источника (GE-Proton, |
| 218 | Kron4ek, 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, |
| 235 | 2026-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 (см. ниже): обновление |
| 246 | Wine-сборки **не автоматическое и не фоновое**, это осознанное разовое |
| 247 | действие «поставь мне вот эту конкретную новую сборку» через `chl wine |
| 248 | install <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 | |
| 277 | 1. **Конфиг игры хранит `wine` явным полем** (`crates/chl-core/src/ |
| 278 | settings.rs`, `Spec { key: "wine", ... }`, `impact`: «Здесь версия |
| 279 | закреплена за игрой: обновление лаунчера её не меняет, поэтому работающая |
| 280 | игра не ломается сама по себе» — формулировка уже была в реестре |
| 281 | настроек до этого прохода). |
| 282 | 2. **Ничего не пишет в это поле автоматически.** `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` для этих мест. |
| 291 | 3. **`chl wine installed` только сообщает о более новой сборке** |
| 292 | («есть новее: …»), ничего не переключает — тот самый механизм, который |
| 293 | уже печатает сравнение с каталогом, не трогает ни один конфиг игры. |
| 294 | 4. **GUI пишет `wine` в конфиг только явным действием пользователя** |
| 295 | (`crates/chl-gui/src/game_page.rs:611`, `save_setting(&game, "wine", |
| 296 | &value)` — вызывается из обработчика выбора сборки на странице игры, а |
| 297 | не откуда-либо ещё). |
| 298 | 5. **Смена сборки уже защищена снимком.** `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, |
| 351 | URL) может жить в том же подписанном файле или в соседнем с тем же форматом. |
| 352 | Ключ и модель доверия те же, второй схемы заводить не нужно. |
| 353 | |
| 354 | **Схема замены файла.** На Linux заменить исполняемый файл работающего |
| 355 | процесса безопасно: `rename()` на месте `chl` не трогает уже открытый |
| 356 | inode запущенного процесса — текущий запуск доработает со старым кодом, |
| 357 | следующий запуск возьмёт новый файл. Порядок: |
| 358 | |
| 359 | 1. Скачать новую версию во временный файл **рядом** с текущим `chl` |
| 360 | (та же файловая система — важно для атомарности `rename`), тем же кодом |
| 361 | скачивания и проверки, что уже есть в `install.rs`. |
| 362 | 2. Проверить hash из манифеста **и** подпись манифеста — то же самое, что |
| 363 | пункт 1 уже делает для сборок Wine. |
| 364 | 3. Сохранить текущий бинарник как `chl.previous` рядом (для отката) — |
| 365 | `rename`, не копия: то же самое, что `install.rs` уже делает с |
| 366 | `staging`-каталогом сборки Wine. |
| 367 | 4. `rename` нового файла на место текущего `chl`. Атомарно на уровне |
| 368 | файловой системы. |
| 369 | 5. **Проверка здоровья при следующем запуске**, не при самом обновлении: |
| 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 записей на |
| 428 | 2026-09-03). С `--game` — фильтр по нестандартным настройкам этой игры, |
| 429 | проверено на реальном конфиге (`bananarfo.toml`: `wine`, `dxvk_version`, |
| 430 | `mangohud`, `vkbasalt`, … — нашёл релевантные записи про Wine, MangoHud, |
| 431 | изоляцию). Игра без единой нестандартной настройки честно получает пустой |
| 432 | список с объяснением, а не «всё подряд». |
| 433 | |
| 434 | 9 юнит-тестов в `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 остаётся открытым — по плану, |
| 457 | design-only. Пункт 4 закрыт 2026-09-07 отдельным проходом, с той же |
| 458 | оговоркой, что у пункта 1: механизм готов и проверен сквозным прогоном, но |
| 459 | без настоящего ключа владельца он ничего не устанавливает — и говорит об этом |
| 460 | вслух, а не отказывает в конце. |
| 461 | |
| 462 | ## Как перепроверить |
| 463 | |
| 464 | ```bash |
| 465 | cd ~/Projects/chimera-launcher/code |
| 466 | cargo build --release --workspace |
| 467 | cargo clippy --workspace --all-targets # 0 предупреждений |
| 468 | cargo test --workspace # 316 тестов, было 286 до этого прохода |
| 469 | |
| 470 | BIN=~/.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 | # откуда взялась таблица источников выше — не выдумана |
| 483 | curl -sL https://github.com/GloriousEggroll/proton-ge-custom/releases/download/GE-Proton11-6/GE-Proton11-6-x86_64.sha512sum |
| 484 | curl -sL https://github.com/Kron4ek/Wine-Builds/releases/download/11.16/sha256sums.txt |
| 485 | curl -s https://api.github.com/repos/RusNor/Wine-Steam-Proton/releases/tags/steam-proton-11.0.2 |
| 486 | ``` |
| 487 |