Project Chimera
Меню

Исходники

377 строк · 33 КиБ

code/crates/chl-wine/CAS-DESIGN.md

1# Контентно-адресуемое хранилище: замер и план (код почти не двигался)
2
3> **Обновление 2026-09-03.** Владелец рассмотрел этот документ и явно сузил
4> scope: CAS реализуется **только для установленных сборок Wine/Proton**
5> (`data/wine/*`), не для живых префиксов и не для их снимков — они этим
6> модулем не затрагиваются вообще, ни на чтение, ни на запись. В рамках
7> этого сужения объектный пул, `adopt`, `materialize` и сборка мусора
8> (mark-and-sweep, dry-run по умолчанию, `--delete` явным флагом) —
9> **реализованы**, в `chl_wine::cas` и команде `chl cas`. Раздел «Что
10> сделано в этом проходе, а что осталось только дизайном» ниже описывает
11> состояние *до* этого обновления и оставлен как есть — историческая
12> точка отсчёта, а не текущий статус. Текущий статус — в `ROADMAP.md`.
13
14Это ответ на пункт фазы 1 «контентно-адресуемое хранилище, дедупликация по
15хэшу» ([ADR-003](../../../DECISIONS.md)) — самый архитектурно тяжёлый
16оставшийся пункт фазы: свой формат хранения, ошибка в котором теряет
17пользовательские данные. Ниже — не implementation-план, а design-документ,
18который стоит сверить с владельцем перед тем, как писать сам объектный пул
19и сборку мусора. В рамках этого прохода реализована только измерительная
20часть: `chl_wine::dedup` (только чтение, ничего не переименовывает и не
21удаляет) и команда `chl dedup-report`. Формат и тон — как у
22[`MODULARIZATION-PLAN.md`](../../../../startwine-optimize/MODULARIZATION-PLAN.md)
23из соседнего трека StartWine-optimize: план для большого рискованного куска
24работы, а не код.
25
26## Главная находка, которая меняет весь план
27
28Гипотеза из `AUDIT-STARTWINE.md` («двадцать префиксов с одинаковыми vcrun и
29DXVK занимают место двадцати») на **реальных данных этой машины не
30подтверждается в том виде, в каком её можно было ожидать** — по простой
31причине: сейчас в Chimera два префикса, а не двадцать (`pfx_default` на
32три игры и `pfx_steam_windows`), потому что в этом проекте общий префикс —
33уже осознанный приём, а не то, что предстоит починить дедупликацией.
34Замер `chl dedup-report` по всем префиксам и всем установленным сборкам
35Wine/Proton (2025-09-03, реальная установка, `~/Games/Chimera`):
36
37```
38сканирую 6 каталогов:
39 data/pfx/pfx_default
40 data/pfx/pfx_steam_windows
41 data/wine/GE-Proton10-34
42 data/wine/GE-Proton11-6
43 data/wine/steam-proton-11.0.2
44 data/wine/wine-11.16-staging-amd64
45
46просканировано файлов: 43958 (15.8 ГиБ)
47групп с одинаковым содержимым: 6621
48освободилось бы при полной дедупликации: 3.0 ГиБ
49из них требует межкаталожной связи: 2.7 ГиБ
50```
51
52То есть **19% просканированных данных дублируется**, и **90% этого дубля**
53(2.7 из 3.0 ГиБ) — это то, чего существующая reflink-цепочка снимков
54никогда не даст сама по себе, потому что связывает только историю одного
55префикса, а не байтово одинаковое содержимое в разных деревьях. Но
56источник дубля оказался не тот, что предполагался: не «vcrun и DXVK в
57двадцати префиксах игр», а **сами сборки Wine/Proton, которые тащат
58одинаковые бандлы**:
59
60| Файл | Размер | Копий | Где |
61|---|---|---|---|
62| `wine-gecko-2.47.4-x86/xul.dll` | 136.9 МиБ | 3 | во всех трёх сборках Proton (GE-Proton10-34, GE-Proton11-6, steam-proton-11.0.2) |
63| `wine-gecko-2.47.4-x86_64/xul.dll` | 134.5 МиБ | 3 | те же три |
64| `icudt68.dll` (x86_64 и x86) | 81.7 МиБ ×2 | 4 каждый | все три сборки Proton + `pfx_default` |
65| `pfx_default.iso`-класс: `Installer/*.msi` | 79.5 МиБ | 2 | `pfx_default` и `pfx_steam_windows` — один и тот же MSI-кэш Windows Installer |
66| `libonnxruntime.so.1.14.1` | 31.1 МиБ | 3 | все три сборки Proton |
67| `Microsoft.CodeAnalysis.CSharp.dll` (Mono) | 23.0 МиБ | 5 | оба префикса + все три сборки Proton |
68| `browser/omni.ja` (Gecko, x86 и x86_64) | 22.9 МиБ ×2 | 3 каждый | все три сборки Proton |
69
70Полный список — `chl dedup-report --top 999` на реальной установке.
71
72**Следствие для приоритета.** Межпрефиксный дубль (два реальных префикса,
73`pfx_default` и `pfx_steam_windows`) даёт всего **≈98 МиБ** экономии — из-за
74общих system32 DLL Wine, а не игровых редистрибутивов (DXVK в установке ещё
75нет ни у одной игры). Межсборочный дубль **сборок Wine/Proton** даёт на
76порядок больше — потому что GE-Proton, steam-proton и upstream-Wine
77перевозят один и тот же Gecko/Mono/ICU/ONNX бандл заново при каждой
78установке, и он не меняется версия от версии, пока апстрим сам его не
79обновит. Именно это, а не игровые префиксы, и есть первая цель с наилучшим
80отношением пользы к риску (см. «Что сделано» ниже).
81
82## Что уже даёт reflink бесплатно — и чего не даёт никогда
83
84Проверено эмпирически `btrfs filesystem du -s`, а не предположением:
85
86- Все 7 реальных версионных снимков `pfx_default` (взятых за сегодняшнюю
87 сессию — перед сменой Wine и т.п.) показывают **`Exclusive: 0.00B`
88 каждый**. Это значит: ни один байт ни в одном снимке не принадлежит
89 только ему — все данные всех снимков до сих пор общие с живым префиксом.
90 Удаление всех семи снимков прямо сейчас освободило бы **буквально ноль**
91 байт. Причина — `snapshot::create()` всегда делает
92 `cp -a --reflink=auto` **от живого префикса**, а не от предыдущего
93 снимка (`crates/chl-wine/src/snapshot.rs:126-131`): раз между снимками
94 почти ничего в префиксе не изменилось, COW и не создал новых экстентов.
95 **Это и есть причина, по которой версионные снимки в этом проекте почти
96 бесплатны уже сейчас**, без всякого CAS — но только для истории *одного*
97 префикса.
98- Все 4 установленные сборки Wine (`data/wine/*`, 5 ГиБ суммарно) тоже
99 показывают `Exclusive: 0.00B`. Причина другая и одноразовая: они
100 перенесены из `~/Games/StartWine` через `migrate_root::migrate()`
101 (`--reflink=auto`, `crates/chl-wine/src/migrate_root.rs:144`), и до тех
102 пор пока референсная установка StartWine жива, каждый байт формально
103 «общий» с ней. Это исчезнет, как только референсная копия будет удалена
104 или когда следующая сборка будет скачана заново — новая сборка ни с чем
105 не reflink-ится, потому что взялась не копированием, а распаковкой
106 архива.
107- **Ни reflink-снимки, ни reflink-перенос не дают ничего для дубля между
108 `data/wine/GE-Proton10-34` и `data/wine/GE-Proton11-6`** — это два
109 независимо распакованных архива, между ними никогда не было операции
110 копирования, значит COW нечего было разделить. Именно эти 2.7 ГиБ
111 межкаталожного дубля (Gecko/Mono/ICU/ONNX) reflink принципиально не
112 видит — здесь нужен инструмент, который сравнивает по содержимому, а не
113 по происхождению. Это и есть весь смысл CAS: `AUDIT-STARTWINE.md`
114 формулирует это как «одинаковые библиотеки в разных префиксах», но на
115 практике первой и самой крупной такой парой оказались не префиксы, а
116 сами сборки Wine.
117
118## Гранулярность: целый файл, не чанки
119
120**Рекомендация: хэшировать файл целиком (sha256), не резать на
121content-defined chunks casync-стиля.**
122
123Довод из находок: все крупные дубли выше — это файлы, которые **побайтово
124идентичны целиком**, не «почти одинаковые с парой изменённых байт».
125`xul.dll` в GE-Proton10-34 и в GE-Proton11-6 — это один и тот же файл из
126одного и того же апстримного Gecko-релиза, перевезённый как есть, а не
127пересобранная версия с точечными правками. Content-defined chunking решает
128другую задачу — дедупликацию *похожих, но не идентичных* больших файлов
129(классика — VM-образы, куда дописали несколько мегабайт). Ни один
130найденный дубль в этой установке такой не является.
131
132**Цена, если ошибиться в эту сторону, — небольшая и обратимая.** Если
133позже найдётся реальный случай почти-дубля (например, два соседних патча
134Proton, отличающихся парой файлов на пару байт внутри общего движка) —
135whole-file-схема просто не дедуплицирует именно этот файл, деградация
136плавная, не отказ. Чанкинг же сразу означает: свой формат чанков, rolling
137hash, чанковый индекс, сборка файла из чанков при материализации — вся эта
138сложность добавляется один раз и живёт в хранилище навсегда. Начинать с
139простого и переходить к чанкам только если появятся факты, а не
140предположения — тот же принцип, что уже применён к отказу от переписывания
141`sw_shaders.py` построчно.
142
143**Что это означает для будущего манифеста.** Манифест префикса/сборки/
144снимка — плоский список `(относительный путь, права, sha256, размер)` на
145файл. Никаких смещений внутри объекта не нужно — один хэш это и есть один
146объект в пуле.
147
148## Устройство хранилища
149
150Пул объектов — рядом с существующими данными, не вместо них:
151
152```
153data/cas/
154 objects/
155 <первые 2 hex sha256>/<остальные 62 hex> # сам файл, неизменяемый
156 manifests/
157 <тип>/<имя>/<версия>.json # список (путь, режим, hash, размер)
158```
159
160Шардирование по первым двум hex-символам — стандартный приём (git делает
161то же самое), нужен не сейчас (6621 объект прекрасно живёт и в одной
162директории), а на масштаб, к которому библиотека дорастёт: тысячи снимков
163за годы использования.
164
165**Объект в пуле пишется один раз и больше не меняется** (сам смысл
166content-addressing: изменившийся файл — это уже другой хэш, то есть другой
167объект). Значит запись объекта не требует блокировок против параллельного
168читателя — читатель либо видит целый файл под конечным именем, либо не
169видит имени вообще. Тот же приём, что уже есть в этом крейте:
170запись во временный путь (`objects/.tmp-<pid>-<uuid>`) и `rename` на
171финальное имя только после того, как содержимое дописано и хэш
172перепроверен — тем же способом, что `snapshot::create()` уже переносит
173готовый снимок через staging-каталог, и `write_atomically` в
174`chl_core::paths`.
175
176**Материализация** (превратить манифест в рабочий каталог) — тот же
177`cp --reflink=auto`, только по одному файлу за раз, из
178`objects/<hash>` в целевой путь, вместо целого дерева разом. На файловых
179системах без reflink — обычная копия, тот же честный запасной путь, что у
180`snapshot::supports_reflink()` уже сегодня. Жёсткие ссылки (hardlink)
181вместо reflink рассматривались и отклонены как основной механизм: hardlink
182на объект пула означает, что запись в «свою копию» файла из живого
183префикса **на самом деле правит объект в пуле**, и любой другой снимок,
184ссылающийся на тот же хэш, молча получает чужие правки. Reflink этого не
185делает — запись всегда идёт через COW, у изменённой копии сразу свой
186экстент. На ext4 без reflink hardlink уже был запасным вариантом в
187ADR-003 — там его придётся защищать через `chmod 444` на объекты пула
188(частично снижает риск, не убирает целиком), это отдельное обсуждение с
189владельцем, а не решение с ходу.
190
191## Сборка мусора
192
193**Рекомендация: mark-and-sweep, не подсчёт ссылок (reference counting).**
194
195Довод — тот же, что уже написан в `CLAUDE.md` про `postgres.yaml`: код,
196который поддерживает счётчик инкрементами и декрементами при каждой
197операции, накапливает рассинхронизацию молча — забытый декремент при
198удалении снимка через `rm -rf` в обход `chl snapshot remove`, забытый
199инкремент при ручном добавлении манифеста, гонка при параллельном
200запуске — и цена ошибки здесь **потеря данных**, а не лишняя строка в
201логе. Mark-and-sweep не хранит состояние между запусками вообще: он
202каждый раз честно проходит все манифесты (снимки всех префиксов, сами
203префиксы, установленные сборки Wine) заново, помечает все хэши, на
204которые есть хоть одна живая ссылка, и всё остальное в пуле — кандидат на
205удаление. Дороже по времени, но `chl dedup-report` на реальной установке
206уже показал: полное сканирование и хэширование 15.8 ГиБ занимает **~5
207секунд** в release-сборке (`~/.cache/chimera-launcher/target/release/chl`,
2082026-09-03). Цена полного прохода тут smaller, чем цена бага в
209инкрементальной схеме.
210
211**Обязательный порядок, если/когда GC будет реализован** (сейчас — не
212реализован, ниже описание, а не код):
213
2141. `chl cas gc --dry-run` (или это же поведение по умолчанию без флага) —
215 печатает список объектов-кандидатов на удаление и суммарный размер,
216 **не удаляет ничего**. Это ровно то, что `dedup::scan` уже умеет — GC
217 переиспользует его для построения множества «живых» хэшей.
2182. Явное подтверждение — второй отдельный флаг, например `--delete`,
219 никогда не подразумеваемый по умолчанию. Тот же принцип, что уже
220 применяется к `chl snapshot remove` (по одному явно названному
221 снимку, не «очистить всё старое»).
2223. Не удалять объект, если с момента mark-прохода до удаления манифест мог
223 измениться (например, если `chl snapshot create` шёл параллельно) —
224 решение: GC берёт файловую блокировку на каталог `data/cas/` на время
225 всего прохода mark+sweep, а не только sweep. Пока это не гарантировано
226 реализацией — GC не должен запускаться параллельно с любой операцией,
227 создающей снимок.
228
229Из ограничений задания: если к моменту фактической реализации не будет
230полной уверенности в безопасности этой схемы — GC остаётся описанием
231здесь, а не кодом. В этом проходе он и остался только описанием.
232
233## Отношение к версионным снимкам: слой снизу, не замена
234
235**Решение: CAS — это новый слой хранения *под* существующим
236`chl_wine::snapshot`, а не его замена.** Публичный API (`create`, `list`,
237`restore`, `remove`, кнопки на странице игры) не меняется ни на йоту.
238Меняется только то, что происходит внутри `create()`: вместо
239`cp -a --reflink=auto` дерева целиком — для каждого файла посчитать хэш,
240убедиться, что объект с этим хэшем уже есть в пуле (иначе положить его
241туда), и материализовать снимок из пула теми же reflink-путями. Манифест
242снимка (список хэшей) занимает килобайты вместо мегабайт апажного
243`cp`.
244
245**Почему не замена.** Три причины:
246
2471. **`restore()` обязан оставаться настолько же надёжным, насколько сейчас.**
248 Текущая реализация — простое, читаемое copy-and-rename, которое легко
249 проверить целиком за один присест (что и сделано: 5 юнит-тестов,
250 реальный откат на боевой установке). Переписывание `restore()` поверх
251 CAS означает: за каждым файлом в целевом дереве нужно сходить в пул,
252 создать reflink, обработать нехватку объекта (испорченный пул —
253 отдельный failure mode, которого сегодня физически не существует).
254 Это тот код, ошибка в котором **теряет данные**, — ровно то, из-за чего
255 ADR-003 сам себя относит к фазе 1, а не к фазе 0. Трогать его стоит
256 отдельным, тщательно проверенным проходом, не заодно с CAS.
2572. **CAS окупается там, где reflink не работает — а это в основном не
258 снимки одного префикса.** Уже показано выше: reflink-цепочка снимков
259 `pfx_default` и так уже почти бесплатна (`Exclusive: 0.00B`). Самая
260 большая находка этого прохода — 2.7 ГиБ дубля **между сборками Wine**,
261 которые снимками вообще не являются. Если ограничить первый проход CAS
262 именно этой осью (сборки Wine, доступные на чтение и не входящие в
263 «живые изменяемые данные пользователя»), риск для реальных данных
264 игрока не возникает вообще — см. «Что сделано» ниже.
2653. **Слоями проще откатываться.** Если CAS-слой для сборок Wine окажется
266 удачным, следующий проход может распространить его на префиксы и
267 снимки без переписывания их публичного API — расширение того же
268 манифестного формата. Если что-то в конструкции CAS окажется неверным,
269 откат — просто не расширять его дальше, а не отменять фичу, от которой
270 уже зависит `restore()`.
271
272## Миграция
273
274**Существующие `.iso` (StartWine, `mksquashfs`).** На этой машине это
275`~/Games/StartWine/data/pfx_backup/pfx_default.iso` (357 МиБ) и
276`saves_backup.iso` (4.1 КиБ, почти пуст) — референсная установка,
277трогать нельзя, но именно по её виду видно́, что реально придётся
278переносить, когда у Chimera появятся свои `.iso`-бэкапы. `chl doctor` уже
279умеет **обнаруживать** их (`crates/chl-doctor/src/lib.rs:700-715`,
280проверка «Бэкапы StartWine», использует опциональный `unsquashfs`), но
281ничего с ними не делает — это и есть недостающий кусок. План:
282
2831. `unsquashfs -d <tmp> <файл>.iso` — распаковать во временный каталог
284 (тот же принцип staging, что у `snapshot::create`: работать в сторонке,
285 переносить на место только после успеха).
2862. Прогнать `dedup::scan` (или прямой аналог) по распакованному дереву,
287 чтобы получить хэши, и **сравнить содержимое с текущим живым
288 префиксом**, если он есть — это не просто перенос в новый формат, а
289 возможность увидеть, чем старый бэкап отличается от того, что есть
290 сейчас, прежде чем считать его лишним.
2913. Зарегистрировать как обычный версионный снимок с меткой
292 `label = "перенесено из <имя>.iso"`, датой из мтайм самого `.iso`, а не
293 временем миграции — иначе «Машина времени» (следующий пункт ROADMAP)
294 покажет неверный порядок событий.
2954. Только после того как манифест снимка подтверждён (например, случайная
296 выборка файлов сверена по хэшу с распакованным деревом) — предложить
297 удалить `.iso`. Не удалять автоматически никогда: тот же принцип, что
298 и у GC — подтверждение и удаление обязаны быть раздельными шагами,
299 инициированными человеком.
300
301**Существующие reflink-снимки** (те самые 7 штук `pfx_default`, которые
302сегодня уже есть). Их не нужно физически копировать в пул — они уже
303занимают почти ноль места сверх живого префикса. Миграция для них — это
304просто «посчитать хэши всех файлов в каждом снимке и зарегистрировать
305объекты в пуле, если их там ещё нет» (ровно то, что делает
306`dedup::scan`, только с записью результата, а не только с отчётом), при
307этом **сами каталоги снимков не трогаются и не удаляются**, пока новые
308объекты пула не подтверждены полностью. `chl snapshot list/restore`
309продолжают читать из тех же каталогов, что и сейчас — переезд на
310материализацию из пула вместо прямого чтения каталога снимка сам по себе
311отдельный, более поздний шаг (см. предыдущий раздел про то, почему
312`restore()` не переписывается заодно).
313
314## Что сделано в этом проходе, а что осталось только дизайном
315
316**Сделано:** `chl_wine::dedup` — сканирование произвольного набора
317каталогов, группировка файлов по совпадающему sha256, отчёт о том, сколько
318байт освободится при полной дедупликации и сколько из этого требует
319именно межкаталожной связи. Только чтение: не переименовывает, не
320связывает, не удаляет ничего ни на одном из просканированных путей — можно
321безопасно натравить и на живой префикс, и на снимок, и на сборку Wine.
322Команда `chl dedup-report [--root ...] [пути...] [--top N]`: без явных
323путей сравнивает все установленные префиксы и все установленные сборки
324Wine. Реализовано и проверено на реальной установке — числа в этом
325документе получены именно так, не оценкой на глаз.
326
327**Не сделано, осталось дизайном:** сам объектный пул (`data/cas/objects`),
328запись в него, материализация из него, манифесты снимков/префиксов/сборок
329поверх пула, сборка мусора, перенос `.iso`. Все они не реализованы
330намеренно — задание прямо требует не строить производственный CAS за один
331проход без ревью владельца, и это тот самый случай: ошибка в объектном
332пуле или в GC способна необратимо повредить префиксы, которыми реально
333пользуются (`pfx_default`, `pfx_steam_windows`), а цена ошибки такого рода
334уже дважды материализовывалась в этом проекте на базе Plane
335(`CLAUDE.md`, про `postgres.yaml`).
336
337## Рекомендация
338
339**Стоит показать этот документ владельцу до того, как дальше писать
340объектный пул, материализацию или GC.** Не потому, что план спорный сам
341по себе — целиком новых открытых вопросов, требующих обязательно живого
342решения владельца, немного (whole-file против чанкинга обосновано
343находками; mark-and-sweep против reference counting обосновано тем же
344принципом, что уже записан в `CLAUDE.md`). Причина другая: это ровно тот
345класс кода — свой формат хранения данных, которыми реально пользуется
346владелец, — про который ADR-003 сам говорит `«ошибка теряет данные»` и
347именно поэтому вынесен в отдельную фазу. Разумный первый шаг после
348чтения этого документа — не «начинай писать пул», а согласовать: **стоит
349ли вообще распространять CAS на живые префиксы** (риск), или ограничиться
350только сборками Wine (данные, которые в любой момент можно перекачать
351заново, и именно там нашлась основная экономия — 2.7 из 3.0 ГиБ дубля).
352Если владелец согласен с этим сужением scope — следующий проход может
353писать код для оси «сборки Wine» с существенно меньшим риском, чем то,
354что описано здесь для префиксов и снимков.
355
356## Как перепроверить
357
358```bash
359cd ~/Projects/chimera-launcher/code
360cargo build --release
361~/.cache/chimera-launcher/target/release/chl dedup-report --top 20
362
363# reflink-цепочка снимков уже почти бесплатна — эксклюзивных байт нет:
364btrfs filesystem du -s ~/Games/Chimera/data/pfx_snapshots/pfx_default/*/
365
366# сборки Wine тоже нулевые по эксклюзивности — но по другой причине
367# (перенесены reflink-ом из ~/Games/StartWine, читать без изменений):
368btrfs filesystem du -s ~/Games/Chimera/data/wine/*/
369
370# откуда взялась причина «Exclusive: 0.00B» у снимков — create() всегда
371# копирует от живого префикса, не от предыдущего снимка:
372sed -n '98,135p' crates/chl-wine/src/snapshot.rs
373
374# обнаружение старых .iso уже есть, переноса — ещё нет:
375grep -n "Бэкапы StartWine" crates/chl-doctor/src/lib.rs
376```
377