[2026-10-06] eagle: work/notes/webkit-macos-version-mapping.md

2026-10-06 14:46:28 +06:00
1 parent a233e6e5dc
commit 5356d932a3
@@ -1,80 +1,291 @@
 ---
-title: WebKit release → macOS version mapping
-tags: [webkit, safari, macos, reference]
+title: WebKit release ↔ macOS build mapping
+tags: [webkit, safari, macos, crash, ravel, reference]
 created: 2026-10-06
-source: ~/Downloads/WebKit_sparse (git checkout of github.com/WebKit/WebKit, main @ 99051d5d08)
+updated: 2026-10-06
+sources:
+  - ~/Downloads/WebKit_sparse
+  - https://ravel.dbg.re
+  - https://github.com/mdn/browser-compat-data/blob/main/browsers/safari.json
 ---

-# WebKit release → macOS version mapping
+# WebKit release ↔ macOS build mapping

-## TL;DR
-Готовой опубликованной таблицы «релиз WebKit → macOS-релиз» не существует.
-Маппинг **выводится из исходников** — он в самом дереве WebKit, а не на сайте.
+## Коротко

-## Механизм (ground truth)
+DuckDuckGo поддерживает macOS **12.3+** (`main/macOS/Configuration/Common.xcconfig`).

-AppleWebKit-версия в User-Agent собирается из двух частей:
+Точное соответствие строится для **конкретного macOS build**, а не только для major/minor:

-```
-AppleWebKit = SYSTEM_VERSION_PREFIX (зависит от macOS) + FULL_VERSION WebKit
+```text
+macOS version + build
+  → UUID WebKit из crash log
+  → тот же UUID в Ravel
+  → CFBundleVersion системного WebKit
+  → убрать macOS SYSTEM_VERSION_PREFIX
+  → FULL_VERSION WebKit
+  → найти WebKit source tag/branch
+  → проверить нужный commit или изменение кода
 ```

-### 1. macOS → SYSTEM_VERSION_PREFIX
+Если точный source tag ещё не опубликован, соответствие заканчивается на версии бинарника. Наличие конкретного source fix тогда нельзя доказать одним номером версии.

-Файл: `Configurations/Version.xcconfig`, строки 35–53.
+## Не путать версии

-| macOS | SYSTEM_VERSION_PREFIX |
-|---|---|
-| 15 Sequoia | 20 |
-| 16 | 21 |
-| 26 Tahoe | 21 |
-| 27 Golden Gate | 22 |
-| 28 | 23 |
-| 29 | 24 |
-| 30 | 25 |
-| (default) | 22 |
+| Значение | Пример | Назначение |
+|---|---:|---|
+| macOS version | `27.0.1` | Marketing version |
+| macOS build | `26A434` | Точная сборка ОС; ключ для Ravel |
+| Mach-O UUID | `70BEE322-…` | Точная идентичность бинарника WebKit |
+| WebKit `CFBundleVersion` | `22625.1.29.11.28` | Версия системного framework |
+| `SYSTEM_VERSION_PREFIX` | `22` | Префикс, зависящий от macOS major |
+| WebKit `FULL_VERSION` | `625.1.29.11.28` | Версия release train без системного префикса |
+| WebKit source tag | `WebKit-7625.1.29.11.28` | Ожидаемое имя тега исходников |
+| HTTP User-Agent | `AppleWebKit/605.1.15` | Заморожен; для маппинга непригоден |

-### 2. FULL_VERSION WebKit (текущий main)
+## Базовые release-линейки macOS 12+

-`Configurations/Version.xcconfig`:
- MAJOR = 627, MINOR = 1, TINY = 2 → FULL_VERSION = `627.1.2`
+Это соответствие **GA macOS major → Safari major → базовая WebKit-линейка**. Оно не заменяет проверку конкретного macOS build: Safari/WebKit обновляется внутри одного macOS major.

-### Пример сборки UA-токена
+| macOS | Минимум DDG | Prefix | Safari GA | WebKit base | Production bundle base | Expected source-tag family |
+|---|---:|---:|---:|---:|---:|---|
+| 12 Monterey | 12.3 | `17` | 15 | `612.1.27` | `17612.1.27` | `WebKit-7612.1.27.*` |
+| 13 Ventura | да | `18` | 16 | `614.1.25` | `18614.1.25` | `WebKit-7614.1.25.*` |
+| 14 Sonoma | да | `19` | 17 | `616.1.27` | `19616.1.27` | `WebKit-7616.1.27.*` |
+| 15 Sequoia | да | `20` | 18 | `619.1.26` | `20619.1.26` | `WebKit-7619.1.26.*` |
+| 26 Tahoe | да | `21` | 26 | `622.1.22` | `21622.1.22` | `WebKit-7622.1.22.*` |
+| 27 Golden Gate | да | `22` | 27 | `625.1.29` | `22625.1.29` | `WebKit-7625.1.29.*` |
+| 27.2 beta | да | `22` | 27.2 | `625.2.4` | `22625.2.4` | ожидается `WebKit-7625.2.4.*` |

-| macOS | prefix | AppleWebKit/… |
-|---|---|---|
-| 15 Sequoia | 20 | `20627.1.2` |
-| 16 | 21 | `21627.1.2` |
-| 26 Tahoe | 21 | `21627.1.2` |
-| 27 Golden Gate | 22 | `22627.1.2` |
-| 30 | 25 | `25627.1.2` |
+Источники базовых версий: MDN `browsers/safari.json` и Apple Safari release notes. Prefix 12–14 подтверждается `Configurations/Version.xcconfig` в `WebKit-7616.1.27`; prefix 15–30 — текущим `Configurations/Version.xcconfig`.

-> Примечание: префиксы 21 у macOS 16 и 26 — это одно и то же системное поколение нумерации, отсюда совпадение.
+## Точные сборки, проверенные через Ravel

-## Что есть в дереве
+Ravel сейчас индексирует не все исторические macOS. Отсутствие записи означает пробел покрытия Ravel, а не отсутствие WebKit в macOS.

-| Что | Путь | Содержимое |
-|---|---|---|
-| macOS → prefix + текущая версия | `Configurations/Version.xcconfig` | таблица префиксов + MAJOR/MINOR/TINY |
-| macOS ↔ кодовые имена | `Tools/Scripts/webkitpy/common/version_name_map.py` | Leopard … Tahoe, Golden Gate |
-| таймлайн релизов WebKit | `git log Configurations/Version.xcconfig` | коммиты «Versioning. WebKit-XXXX.Y.Z» |
-| отгруженные релизы | `git ls-remote --heads origin` | 498 веток `safari-XXXX-branch` |
-| генератор deployment target | `Configurations/Scripts/generate-deployment-target-xcconfig.py` | 6-значные minor-версии → semver |
+| macOS | Build | WebKit UUID | CFBundleVersion | FULL_VERSION |
+|---|---|---|---:|---:|
+| 26.5.2 | `25F84` | `49B21D99-8716-31B8-8686-71B287325F1D` | `21624.2.5.11.8` | `624.2.5.11.8` |
+| 26.6 | `25G72` | `B090AABF-9A3B-3110-9DA9-F0F40FCEC972` | `21624.4.5.11.5` | `624.4.5.11.5` |
+| 26.6.1 | `25G76` | `B090AABF-9A3B-3110-9DA9-F0F40FCEC972` | `21624.4.5.11.5` | `624.4.5.11.5` |
+| 26.6.2 | `25G83` | `844AF253-CAF6-3623-9DAD-A055C5274E62` | `21624.5.1.11.3` | `624.5.1.11.3` |
+| 27.0.1 | `26A434` | `70BEE322-37EE-3B22-8012-4F76BA105C29` | `22625.1.29.11.28` | `625.1.29.11.28` |
+| 27.2 beta | `26B5086k` | `6F6AB57E-1492-3950-9962-85B6AFD430A3` | `22625.2.4.1` | `625.2.4.1` |
+| 27.2 beta 2 | `26B5091g` | `56B4AA44-CB66-3641-8B22-723C39B5BC6E` | `22625.2.5.11.1` | `625.2.5.11.1` |
+| 27.2 beta 3 | `26B5101f` | `B32D7081-AE42-3A2E-ACBB-CF4D4BE4F296` | `22625.2.7.1` | `625.2.7.1` |

-## Чего в дереве НЕТ
-Готовой таблицы «релиз WebKit → macOS-релиз». Она собирается из трёх источников:
-1. prefix-таблица (в дереве, `Version.xcconfig`);
-2. Apple Safari/iOS release notes — какая версия вошла в какой macOS;
-3. `git log Configurations/Version.xcconfig` — таймлайн бампов версии.
+Пример показывает, почему нужен UUID: macOS 26.6 и 26.6.1 используют один и тот же WebKit binary — совпадают и UUID, и `CFBundleVersion`.

-## Источники (проверено)
- Файл: `~/Downloads/WebKit_sparse/Configurations/Version.xcconfig` — 76 строк, 3640 байт.
- Строки 35–53 — таблица префиксов и `SYSTEM_VERSION_PREFIX_macosx_*`.
- Строки 24–29 — MAJOR/MINOR/TINY/FULL.
- Источник: рабочий чекаут Alex (`WebKit_sparse`), не внешний сайт.
+## Полная методика

-## Pitfalls
- Префикс `SYSTEM_VERSION_PREFIX_macosx_` (пустой) = `22` — это default для неизвестного macOS; не путать с реальным.
- `Version.xcconfig` есть **только** в `Configurations/` (один файл); вложенных копий в `Source/` нет.
- Sparse/shallow клоны содержат лишь ~10 последних бампов версии — полная история требует полного клона.
- Ветки `origin` содержат `integration/...safari-XXX-branch` (мусор от CI) — фильтровать по чистому `^safari-[0-9.]*-branch$`.
+### 1. Извлечь macOS build и UUID из crash log
+
+```bash
+rg 'OS Version:|WebKit \(arm64e\)' <file.crash>
+```
+
+Нужны:
+
+```text
+OS Version: macOS 27.0.1 (26A434)
+WebKit (arm64e) <70BEE322-37EE-3B22-8012-4F76BA105C29>
+```
+
+UUID сравнивать без учёта регистра и дефисов. Для Intel и Apple Silicon UUID могут различаться; архитектура должна совпадать.
+
+### 2. Найти тот же бинарник в Ravel
+
+Искать путь:
+
+```text
+/System/Library/Frameworks/WebKit.framework/Versions/A/WebKit
+```
+
+URL-шаблон:
+
+```text
+https://ravel.dbg.re/binary?build=<MACOS_BUILD>&domain=dyld_cache&path=%2FSystem%2FLibrary%2FFrameworks%2FWebKit.framework%2FVersions%2FA%2FWebKit
+```
+
+Проверить в `Binary metadata and fingerprint`:
+
+1. macOS build;
+2. архитектуру;
+3. UUID — должен совпасть с crash log.
+
+В `Quick search` искать начало bundle version: `17`, `18`, `19`, `20`, `21` или `22`. В restricted strings находится полный номер вроде `22625.1.29.11.28`.
+
+### 3. Получить версию непосредственно на Mac
+
+```bash
+sw_vers
+defaults read /System/Library/Frameworks/WebKit.framework/Resources/Info CFBundleVersion
+```
+
+Из приложения:
+
+```swift
+let webKitBundleVersion = Bundle(for: WKWebView.self)
+    .object(forInfoDictionaryKey: "CFBundleVersion") as? String
+```
+
+Это проверено на macOS 26.7.1: возвращается `21624.5.1.11.3`.
+
+### 4. Убрать системный prefix
+
+Production WebKit собирает номер так:
+
+```text
+CFBundleVersion = SYSTEM_VERSION_PREFIX + FULL_VERSION
+```
+
+| macOS | Prefix |
+|---|---:|
+| 12 | `17` |
+| 13 | `18` |
+| 14 | `19` |
+| 15 | `20` |
+| 16 / 26 | `21` |
+| 27 | `22` |
+| 28 | `23` |
+| 29 | `24` |
+| 30 | `25` |
+
+Пример:
+
+```text
+22625.1.29.11.28 - prefix 22 = 625.1.29.11.28
+```
+
+### 5. Построить имя source tag
+
+Современные Apple release tags обычно называются:
+
+```text
+WebKit-7<FULL_VERSION>
+```
+
+Пример:
+
+```text
+FULL_VERSION: 625.1.29.11.28
+candidate tag: WebKit-7625.1.29.11.28
+```
+
+Проверить точный тег:
+
+```bash
+git ls-remote --tags origin \
+  'WebKit-7625.1.29.11.28' \
+  'WebKit-7625.1.29.11.28^{}'
+```
+
+Если точного тега нет, найти опубликованную семью:
+
+```bash
+git ls-remote --tags origin 'WebKit-7625.1.29*'
+git ls-remote --heads origin 'safari-7625*'
+```
+
+Отсутствующий exact tag нельзя заменять ближайшим и считать точным соответствием. Ближайший тег даёт только нижнюю или верхнюю границу.
+
+### 6. Проверить наличие fix в source release
+
+Надёжнее проверять изменённый код, а не только ancestry: Apple может cherry-pick fix с другим commit SHA.
+
+Для текущего бага:
+
+```bash
+git show <TAG>:Source/WebKit/UIProcess/WebFrameProxy.h \
+  | rg 'commitCertificateInfo'
+```
+
+Старая версия:
+
+```cpp
+void commitCertificateInfo(const URL&);
+```
+
+Исправленная версия (`318982@main`):
+
+```cpp
+void commitCertificateInfo(const URL&, bool hasCertificateInfo);
+```
+
+Дополнительно искать bug id и commit message:
+
+```bash
+git log <TAG> --grep='321456'
+git log <TAG> --grep='Send bool indicating presence of CertificateInfo'
+```
+
+### 7. Если exact source tag отсутствует
+
+Остаются три уровня доказательства:
+
+1. точный UUID + `CFBundleVersion` — доказана версия бинарника;
+2. символ crash stack или disassembly — можно доказать конкретную сигнатуру/поведение бинарника;
+3. воспроизведение теста на нужном macOS build — можно доказать наличие или отсутствие бага.
+
+Версия STP не доказывает версию системного WebKit: Safari Technology Preview — отдельная сборка.
+
+## Текущий баг: результат сопоставления
+
+### macOS 27.0.1
+
+```text
+macOS:           27.0.1 (26A434)
+Crash UUID:      70BEE322-37EE-3B22-8012-4F76BA105C29
+Ravel UUID:      70BEE322-37EE-3B22-8012-4F76BA105C29
+CFBundleVersion: 22625.1.29.11.28
+Prefix:          22
+FULL_VERSION:    625.1.29.11.28
+Expected tag:    WebKit-7625.1.29.11.28
+```
+
+Exact tag `.11.28` публично не найден; опубликована `.11.27`. Базовая ветка `WebKit-7625.1.29` содержит старую одноаргументную сигнатуру. Crash stack также показывает:
+
+```text
+WebKit::WebFrameProxy::commitCertificateInfo(WTF::URL const&)
+```
+
+Вывод: **в macOS 27.0.1 fix отсутствует**.
+
+### macOS 27.2 beta
+
+Ravel подтверждает бинарные версии `625.2.4.1`, `625.2.5.11.1` и `625.2.7.1` для beta 1–3. Публичных `WebKit-7625.2.*` tags/branches пока нет.
+
+Fix `318982@main` вошёл в STP 251, но это не доказывает его inclusion в системный WebKit macOS 27.2.
+
+Вывод: **macOS 27.2 — сильный кандидат на первую исправленную версию, но source inclusion пока не доказан**.
+
+## Телеметрия DuckDuckGo
+
+Текущие pixels не отправляют точный `CFBundleVersion` WebKit. HTTP UA использовать нельзя: WebKit намеренно возвращает замороженный `AppleWebKit/605.1.15`.
+
+Для корреляции crash/pixel с таблицей выше нужен параметр:
+
+```text
+webkit_build=22625.1.29.11.28
+```
+
+Получать его через `Bundle(for: WKWebView.self).CFBundleVersion`, а не через `WebKitVersionProvider`, который парсит замороженный UA.
+
+## Источники
+
+- `~/Downloads/WebKit_sparse/Configurations/Version.xcconfig`
+- `~/Downloads/WebKit_sparse/Source/WebCore/platform/mac/UserAgentMac.mm`
+- `main/macOS/Configuration/Common.xcconfig`
+- [Ravel binary catalogue](https://ravel.dbg.re/browse)
+- [MDN Safari → WebKit versions](https://github.com/mdn/browser-compat-data/blob/main/browsers/safari.json)
+- [Safari release notes](https://developer.apple.com/documentation/safari-release-notes)
+- [WebKit commit 318982@main](https://commits.webkit.org/318982@main)
+- [Safari Technology Preview 251](https://webkit.org/blog/18194/release-notes-for-safari-technology-preview-251/)
+
+## Ограничения
+
+- Ravel находится в beta и имеет неполное покрытие.
+- Один macOS major содержит много Safari/WebKit updates; базовая таблица не заменяет lookup конкретного build.
+- Совпадение версии без UUID слабее, чем совпадение версии и UUID.
+- Exact tag может быть опубликован позже бинарника Apple.
+- Cherry-pick может иметь другой SHA; проверять итоговый код в release tag.