diff --git a/work/notes/webkit-macos-version-mapping.md b/work/notes/webkit-macos-version-mapping.md index be02b5c8..ce4e869f 100755 --- a/work/notes/webkit-macos-version-mapping.md +++ b/work/notes/webkit-macos-version-mapping.md @@ -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\)' +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=&domain=dyld_cache&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=&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 ``` -Пример: +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 :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 --grep='321456' -git log --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.