git_admin/obsidian-vault
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
Alexey Martemyanov committed 2026-10-06 15:01:39 +06:00
1 parent 5356d932a3
commit 307aba7cf1
1 file changed
+167 -159
Download Patch File Download Diff File Expand all files Collapse all files
work/notes/webkit-macos-version-mapping.md
+167 -159
View File
@@ -1,69 +1,91 @@
---
title: WebKit release ↔ macOS build mapping
tags: [webkit, safari, macos, crash, ravel, reference]
title: Mapping Apple OS builds to WebKit source releases
tags: [webkit, safari, macos, ios, crash, ravel, reference]
created: 2026-10-06
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 build mapping
# Mapping Apple OS builds to WebKit source releases
## Коротко
## Purpose
DuckDuckGo поддерживает macOS **12.3+** (`main/macOS/Configuration/Common.xcconfig`).
This document explains how to map a WebKit crash on macOS or iOS to:
Точное соответствие строится для **конкретного macOS build**, а не только для major/minor:
1. the exact Apple OS build;
2. the exact system WebKit binary by Mach-O UUID;
3. its `CFBundleVersion` and WebKit `FULL_VERSION`;
4. the closest public WebKit source tag;
5. the presence or absence of a source change.
The DuckDuckGo Apple browsers currently support macOS **12.3+** and iOS **15.0+**. The deployment targets are defined in `macOS/Configuration/Common.xcconfig` and `iOS/DuckDuckGo-iOS.xcodeproj/project.pbxproj` in the Apple browsers repository.
## Short answer
Use this chain for an exact mapping:
```text
macOS version + build
→ UUID WebKit из crash log
→ тот же UUID в Ravel
→ CFBundleVersion системного WebKit
→ убрать macOS SYSTEM_VERSION_PREFIX
→ FULL_VERSION WebKit
→ найти WebKit source tag/branch
→ проверить нужный commit или изменение кода
OS version + OS build
-> WebKit Mach-O UUID from the crash report
-> matching binary and UUID in Ravel
-> WebKit CFBundleVersion from the OS or app telemetry
-> remove the platform SYSTEM_VERSION_PREFIX
-> WebKit FULL_VERSION
-> public source tag or release branch
-> inspect the released code for the fix
```
Если точный source tag ещё не опубликован, соответствие заканчивается на версии бинарника. Наличие конкретного source fix тогда нельзя доказать одним номером версии.
An OS major version identifies only a **WebKit release train**. It does not identify the exact WebKit revision because Apple updates WebKit in OS point and security releases.
## Не путать версии
## Version fields
| Значение | Пример | Назначение |
| Field | Example | Meaning |
|---|---:|---|
| 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` | Заморожен; для маппинга непригоден |
| OS version | `macOS 27.0.1` | Marketing version |
| OS build | `26A434` | Exact Apple OS build; use this in Ravel |
| Mach-O UUID | `70BEE322-...` | Exact WebKit binary identity for one architecture |
| `CFBundleVersion` | `22625.1.29.11.28` | System framework build version |
| `SYSTEM_VERSION_PREFIX` | `22` | Platform/OS prefix added by Apple's production build |
| WebKit `FULL_VERSION` | `625.1.29.11.28` | Release version without the system prefix |
| Source tag | `WebKit-7625.1.29.11.28` | Candidate public source release |
| HTTP User-Agent | `AppleWebKit/605.1.15` | Frozen compatibility token; not usable for this mapping |
## Базовые release-линейки macOS 12+
## Supported OS release trains
Это соответствие **GA macOS major → Safari major → базовая WebKit-линейка**. Оно не заменяет проверку конкретного macOS build: Safari/WebKit обновляется внутри одного macOS major.
These tables map each supported OS major to its initial Safari/WebKit release train. Always use the exact-build workflow for a crash or API-availability decision.
| macOS | Минимум DDG | Prefix | Safari GA | WebKit base | Production bundle base | Expected source-tag family |
### macOS 12.3+
| macOS | DDG support | Safari release | WebKit base `FULL_VERSION` | macOS prefix | Production bundle base | Public 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.*` |
| 12 Monterey | 12.3+ | 15 | `612.1.27` | `17` | `17612.1.27` | `Safari-612.1.27.*` |
| 13 Ventura | Yes | 16 | `614.1.25` | `18` | `18614.1.25` | `WebKit-7614.1.25.*` |
| 14 Sonoma | Yes | 17 | `616.1.27` | `19` | `19616.1.27` | `WebKit-7616.1.27.*` |
| 15 Sequoia | Yes | 18 | `619.1.26` | `20` | `20619.1.26` | `WebKit-7619.1.26.*` |
| 26 Tahoe | Yes | 26 | `622.1.22` | `21` | `21622.1.22` | `WebKit-7622.1.22.*` |
| 27 Golden Gate | Yes | 27 | `625.1.29` | `22` | `22625.1.29` | `WebKit-7625.1.29.*` |
Источники базовых версий: MDN `browsers/safari.json` и Apple Safari release notes. Prefix 12–14 подтверждается `Configurations/Version.xcconfig` в `WebKit-7616.1.27`; prefix 15–30 — текущим `Configurations/Version.xcconfig`.
### iOS 15.0+
## Точные сборки, проверенные через Ravel
WebKit uses `SYSTEM_VERSION_PREFIX = 8` for iPhone-family SDKs. Therefore the iOS production bundle version is `8` concatenated with `FULL_VERSION`.
Ravel сейчас индексирует не все исторические macOS. Отсутствие записи означает пробел покрытия Ravel, а не отсутствие WebKit в macOS.
| iOS | DDG support | Safari release | WebKit base `FULL_VERSION` | iOS prefix | Production bundle base | Public source-tag family |
|---|---:|---:|---:|---:|---:|---|
| 15 | 15.0+ | 15 | `612.1.27` | `8` | `8612.1.27` | `Safari-612.1.27.*` |
| 16 | Yes | 16 | `614.1.25` | `8` | `8614.1.25` | `WebKit-7614.1.25.*` |
| 17 | Yes | 17 | `616.1.27` | `8` | `8616.1.27` | `WebKit-7616.1.27.*` |
| 18 | Yes | 18 | `619.1.26` | `8` | `8619.1.26` | `WebKit-7619.1.26.*` |
| 26 | Yes | 26 | `622.1.22` | `8` | `8622.1.22` | `WebKit-7622.1.22.*` |
| 27 | Yes | 27 | `625.1.29` | `8` | `8625.1.29` | `WebKit-7625.1.29.*` |
| macOS | Build | WebKit UUID | CFBundleVersion | FULL_VERSION |
iOS versions 19–25 do not exist; Apple changed the public version number from 18 to 26.
## Exact builds verified in Ravel
Ravel is currently incomplete. A missing build means that Ravel does not index it, not that the OS lacks WebKit.
### macOS examples
| 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` |
@@ -74,164 +96,159 @@ Ravel сейчас индексирует не все исторические m
| 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` |
Пример показывает, почему нужен UUID: macOS 26.6 и 26.6.1 используют один и тот же WebKit binary — совпадают и UUID, и `CFBundleVersion`.
macOS 26.6 and 26.6.1 contain the same WebKit binary: both UUID and `CFBundleVersion` match.
## Полная методика
### iOS examples
### 1. Извлечь macOS build и UUID из crash log
Ravel identifies iOS WebKit binaries and UUIDs, but its dyld-cache page does not expose the framework `Info.plist` value. Read `CFBundleVersion` at runtime or from an extracted IPSW before claiming an exact source release.
| iOS | Build | WebKit UUID |
|---|---|---|
| 26.6 | `23G71` | `7627FDAB-129E-32BB-A2AC-F0DC02853D4E` |
| 26.6.1 | `23G83` | `C39BD22C-3475-38AF-91BD-0B7574081011` |
| 26.6.2 | `23G90` | `C39BD22C-3475-38AF-91BD-0B7574081011` |
| 27.0.1 | `24A446` | `D12A79A6-98CB-323C-8F72-613AD0983BBC` |
| 27.2 beta | `24B5084k` | `1FD67A57-D91B-3B26-9F4F-91AB8299B6E7` |
| 27.2 beta 2 | `24B5089g` | `509D51AD-2CF9-3982-BFD5-81221D1B903D` |
| 27.2 beta 3 | `24B5099f` | `0566BF55-2DC4-34F6-B211-96FFAA0A37A4` |
iOS 26.6.1 and 26.6.2 contain the same WebKit binary UUID.
## Exact mapping procedure
### 1. Read the OS build and WebKit UUID
From an Apple crash report, record the OS version/build and the WebKit image UUID. Compare UUIDs without case or dashes, and match the architecture.
```bash
rg 'OS Version:|WebKit \(arm64e\)' <file.crash>
rg 'OS Version:|WebKit.*<' crash-report.crash
```
Нужны:
### 2. Find the binary in Ravel
Use the OS build and the correct binary path:
```text
OS Version: macOS 27.0.1 (26A434)
WebKit (arm64e) <70BEE322-37EE-3B22-8012-4F76BA105C29>
macOS: /System/Library/Frameworks/WebKit.framework/Versions/A/WebKit
iOS: /System/Library/Frameworks/WebKit.framework/WebKit
```
UUID сравнивать без учёта регистра и дефисов. Для Intel и Apple Silicon UUID могут различаться; архитектура должна совпадать.
### 2. Найти тот же бинарник в Ravel
Искать путь:
Ravel URL pattern:
```text
/System/Library/Frameworks/WebKit.framework/Versions/A/WebKit
https://ravel.dbg.re/binary?build=<OS_BUILD>&domain=dyld_cache&path=<URL_ENCODED_BINARY_PATH>
```
URL-шаблон:
The Ravel UUID must equal the crash-report UUID. A matching version string without a matching UUID is weaker evidence.
```text
https://ravel.dbg.re/binary?build=<MACOS_BUILD>&domain=dyld_cache&path=%2FSystem%2FLibrary%2FFrameworks%2FWebKit.framework%2FVersions%2FA%2FWebKit
```
### 3. Read `CFBundleVersion`
Проверить в `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
```
Из приложения:
From app code on either platform:
```swift
import WebKit
let webKitBundleVersion = Bundle(for: WKWebView.self)
.object(forInfoDictionaryKey: "CFBundleVersion") as? String
```
Это проверено на macOS 26.7.1: возвращается `21624.5.1.11.3`.
On macOS, it can also be read without app changes:
### 4. Убрать системный prefix
```bash
defaults read /System/Library/Frameworks/WebKit.framework/Resources/Info CFBundleVersion
```
Production WebKit собирает номер так:
For iOS, log the runtime value on a test device or include it in crash/pixel metadata. Do not infer an exact iOS value from the same-numbered macOS release.
### 4. Remove `SYSTEM_VERSION_PREFIX`
Apple production builds concatenate the prefix and the WebKit version:
```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` |
| Platform | OS | Prefix |
|---|---|---:|
| iOS | All supported versions | `8` |
| macOS | 12 | `17` |
| macOS | 13 | `18` |
| macOS | 14 | `19` |
| macOS | 15 | `20` |
| macOS | 26 | `21` |
| macOS | 27 | `22` |
Пример:
Example:
```text
22625.1.29.11.28 - prefix 22 = 625.1.29.11.28
22625.1.29.11.28 - prefix 22 -> 625.1.29.11.28
```
### 5. Построить имя source tag
### 5. Resolve the public source release
Современные Apple release tags обычно называются:
For modern release trains, candidate tags use:
```text
WebKit-7<FULL_VERSION>
```
Пример:
Example:
```text
FULL_VERSION: 625.1.29.11.28
candidate tag: WebKit-7625.1.29.11.28
625.1.29.11.28 -> WebKit-7625.1.29.11.28
```
Проверить точный тег:
The 612 train is an older naming exception:
```text
612.1.27.* -> Safari-612.1.27.*
```
Check exact public tags and release branches:
```bash
git ls-remote --tags origin \
'WebKit-7625.1.29.11.28' \
'WebKit-7625.1.29.11.28^{}'
git ls-remote --tags https://github.com/WebKit/WebKit.git 'WebKit-7625.1.29*'
git ls-remote --heads https://github.com/WebKit/WebKit.git 'safari-7625*'
```
Если точного тега нет, найти опубликованную семью:
An adjacent tag is only a bound, not an exact match. Apple may publish a binary before publishing the corresponding source tag.
```bash
git ls-remote --tags origin 'WebKit-7625.1.29*'
git ls-remote --heads origin 'safari-7625*'
```
### 6. Verify the fix in released source
Отсутствующий exact tag нельзя заменять ближайшим и считать точным соответствием. Ближайший тег даёт только нижнюю или верхнюю границу.
Inspect the changed code in the candidate tag. This is stronger than checking one commit SHA because Apple may cherry-pick the change under a different SHA.
### 6. Проверить наличие fix в source release
Надёжнее проверять изменённый код, а не только ancestry: Apple может cherry-pick fix с другим commit SHA.
Для текущего бага:
For the certificate-info crash discussed below:
```bash
git show <TAG>:Source/WebKit/UIProcess/WebFrameProxy.h \
| rg 'commitCertificateInfo'
```
Старая версия:
Old signature:
```cpp
void commitCertificateInfo(const URL&);
```
Исправленная версия (`318982@main`):
Fixed signature from `318982@main`:
```cpp
void commitCertificateInfo(const URL&, bool hasCertificateInfo);
```
Дополнительно искать bug id и commit message:
### 7. When the exact source tag is unavailable
```bash
git log <TAG> --grep='321456'
git log <TAG> --grep='Send bool indicating presence of CertificateInfo'
```
Record the evidence level explicitly:
### 7. Если exact source tag отсутствует
1. UUID + `CFBundleVersion`: exact binary and release version are known.
2. Symbols or disassembly: a specific ABI or behavior can be proven in the binary.
3. Reproduction on the exact OS build: the bug can be proven present or absent.
Остаются три уровня доказательства:
Safari Technology Preview is a separate build. Its version does not prove the version of system WebKit.
1. точный UUID + `CFBundleVersion` — доказана версия бинарника;
2. символ crash stack или disassembly — можно доказать конкретную сигнатуру/поведение бинарника;
3. воспроизведение теста на нужном macOS build — можно доказать наличие или отсутствие бага.
## Current certificate-info crash
Версия STP не доказывает версию системного WebKit: Safari Technology Preview — отдельная сборка.
## Текущий баг: результат сопоставления
### macOS 27.0.1
The crash on macOS 27.0.1 maps as follows:
```text
macOS: 27.0.1 (26A434)
@@ -240,52 +257,43 @@ 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
Candidate tag: WebKit-7625.1.29.11.28
```
Exact tag `.11.28` публично не найден; опубликована `.11.27`. Базовая ветка `WebKit-7625.1.29` содержит старую одноаргументную сигнатуру. Crash stack также показывает:
The exact `.11.28` source tag is not public as of 2026-10-06; `.11.27` is public. The crash symbol and the `WebKit-7625.1.29` source family both show the old one-argument signature. Therefore the fix is absent from macOS 27.0.1.
```text
WebKit::WebFrameProxy::commitCertificateInfo(WTF::URL const&)
```
Ravel identifies macOS 27.2 beta binaries as `625.2.4.1`, `625.2.5.11.1`, and `625.2.7.1`. Public `WebKit-7625.2.*` tags are not available as of 2026-10-06. The fix landed in `318982@main` and Safari Technology Preview 251, so macOS 27.2 is a candidate for the first fixed system release, but source inclusion is not yet proven.
Вывод: **в macOS 27.0.1 fix отсутствует**.
## DuckDuckGo telemetry gap
### macOS 27.2 beta
Current pixels do not include the exact system WebKit `CFBundleVersion`. The HTTP User-Agent cannot fill this gap because Apple returns the frozen `AppleWebKit/605.1.15` compatibility token.
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 с таблицей выше нужен параметр:
Add one field to relevant crash and WebKit failure telemetry:
```text
webkit_build=22625.1.29.11.28
```
Получать его через `Bundle(for: WKWebView.self).CFBundleVersion`, а не через `WebKitVersionProvider`, который парсит замороженный UA.
Populate it from `Bundle(for: WKWebView.self).CFBundleVersion`. This makes OS-build-to-WebKit correlation deterministic on both macOS and iOS.
## Источники
## Sources
- `~/Downloads/WebKit_sparse/Configurations/Version.xcconfig`
- `~/Downloads/WebKit_sparse/Source/WebCore/platform/mac/UserAgentMac.mm`
- `main/macOS/Configuration/Common.xcconfig`
- [WebKit source repository](https://github.com/WebKit/WebKit)
- [Current WebKit version configuration](https://github.com/WebKit/WebKit/blob/main/Configurations/Version.xcconfig)
- [Safari 15 / WebKit 612 version configuration](https://chromium.googlesource.com/external/github.com/WebKit/webkit/+/refs/tags/Safari-612.1.27/Source/WebKit/Configurations/Version.xcconfig)
- [Safari 16 / WebKit 614 version configuration](https://chromium.googlesource.com/external/github.com/WebKit/webkit/+/refs/tags/WebKit-7614.1.25/Source/WebKit/Configurations/Version.xcconfig)
- [Safari 17 / WebKit 616 version configuration](https://github.com/WebKit/WebKit/blob/WebKit-7616.1.27/Configurations/Version.xcconfig)
- [Safari 27 / WebKit 625 version configuration](https://github.com/WebKit/WebKit/blob/WebKit-7625.1.29/Configurations/Version.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)
- [MDN Safari release metadata](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/)
## Ограничения
## Limits
- Ravel находится в beta и имеет неполное покрытие.
- Один macOS major содержит много Safari/WebKit updates; базовая таблица не заменяет lookup конкретного build.
- Совпадение версии без UUID слабее, чем совпадение версии и UUID.
- Exact tag может быть опубликован позже бинарника Apple.
- Cherry-pick может иметь другой SHA; проверять итоговый код в release tag.
- One OS major contains multiple WebKit updates; use the exact OS build for conclusions.
- Ravel is in beta and does not index every historical Apple build.
- Intel and Apple Silicon binaries may have different UUIDs.
- An exact public tag may appear after Apple ships the binary.
- Verify released code, not only commit ancestry, because fixes can be cherry-picked.