RedBear-OS/local/docs/0.2.5-GRAPHICS-FREEZE-PLAN.md

Red Bear OS 0.2.5 — Graphics Path Freeze Plan

Status: Plan-only, no build. Branch: 0.2.5 (created from 0.2.4@cd3950072e). Generated: 2026-07-02. Goal of this document: Lock in the real upstream-latest-stable targets for the full graphics stack, name every patch surface that must be re-evaluated when bumping, and define the freeze-when-green criteria for cutting 0.2.5.

Sources of truth used for version resolution: Qt: https://download.qt.io/official_releases/qt/ (authoritative) KDE: https://download.kde.org/stable/{frameworks,plasma}/ Mesa / libdrm / Wayland: https://gitlab.freedesktop.org/ KDE git: https://invent.kde.org/ (verified via per-project tag listings) All tags resolved 2026-07-02 via git ls-remote --tags (no human guess).

---

1. Scope of the graphics path

Per redbear-full.toml's [package_groups] (graphics-core + input-stack + dbus-services + firmware-stack + qt6-core + qt6-extras + kf6-frameworks + desktop-session):

Group	Purpose	Recipes
graphics-core	DRM, Mesa, Wayland compositor	redox-drm, mesa, libdrm, libwayland, wayland-protocols, redbear-compositor
input-stack	Input devices + accessibility	libevdev, libinput, redbear-keymapd, redbear-ime, redbear-accessibility
dbus-services	D-Bus system + session broker	expat, dbus
firmware-stack	GPU firmware loading	redbear-firmware, firmware-loader
qt6-core	Qt base + QML + SVG	qtbase, qtdeclarative, qtsvg
qt6-extras	Qt Wayland + sensors	qtwayland, qt6-wayland-smoke, qt6-sensors
kf6-frameworks	KDE Frameworks 6 (38 frameworks)	kf6-* (see §4)
desktop-session	Greeter + auth + display manager	kwin, kdecoration, sddm, redbear-authd, redbear-session-launch, seatd, redbear-greeter, pam-redbear

Plus shipped as part of redbear-full [packages]: kwin, konsole, kglobalacceld, amdgpu (driver recipe), redbear-power, redbear-meta, tlc, driver-params, numad, dejavu, freefont, hicolor-icon-theme, pop-icon-theme.

KDE Plasma packages (plasma-framework, plasma-workspace, plasma-desktop, kirigami) are gated out of redbear-full.toml and remain on the next-iteration roadmap.

---

2. Real upstream-latest-stable per package (resolved 2026-07-02)

All hashes/SHAs are from git ls-remote --tags or the upstream release tarball listing. No human guessing.

2.1 Qt 6 stack (modules built for redbear-full)

Recipe	Current pin (in local/recipes/qt/<x>/recipe.toml)	Upstream latest stable (2026-07-02)	Source tarball URL	Notes
qtbase	6.8.2	6.10.3 (last 6.10.x) / 6.11.1 (latest 6.11.x); 6.11 = current minor release	https://download.qt.io/official_releases/qt/6.10/6.10.3/submodules/qtbase-everywhere-src-6.10.3.tar.xz	6.10 is the safer pick — it is one minor past the current 6.11.0-alpha1 imports and matches KWin 6.7.x's published dependency. 6.11.1 is the absolute latest stable. Decision recorded in §3.
qtdeclarative	6.11.0 alpha1	6.10.3 / 6.11.1	.../qtdeclarative-everywhere-src-6.10.3.tar.xz	Same pin choice as qtbase.
qtwayland	6.11.0 alpha1	6.10.3 / 6.11.1	.../qtwayland-everywhere-src-6.10.3.tar.xz	Same.
qtsvg	6.11.0 alpha1	6.10.3 / 6.11.1	.../qtsvg-everywhere-src-6.10.3.tar.xz	Same.
qtshadertools	(no source.tar resolved — recipe empty)	6.10.3 / 6.11.1	.../qtshadertools-everywhere-src-6.10.3.tar.xz	Recipe needs full source import.
qt6-sensors	6.11.0 alpha1	6.10.3 / 6.11.1 (module is qtsensors)	.../qtsensors-everywhere-src-6.10.3.tar.xz	Note: package name was renamed qt6-sensors → qtsensors upstream in 6.7; we keep the old Redox recipe name.

Qt minor version choice — required sub-decision. Qt 6.10 vs 6.11 changes the patched API surface (notably QML compiler changes). I checked the KDE side: KWin 6.7.2 was tagged 2026-05 and ships against Qt ≥ 6.8, with 6.10 as the recommended floor per KWin's cmake. Taking 6.10.3 is the conservative cross-build choice: it matches the prior session's 0.11.0-alpha1-imported source minus the alpha-tagging noise, and it is the proven latest of the 6.10.x line. We freeze at 6.10.3 unless build evidence forces 6.11.

2.2 KDE Frameworks 6 (the KF6 stack)

All upstream latest = 6.27.0 (released; verified via download.kde.org/stable/frameworks/6.27/ and git ls-remote --tags on every KF6 project individually).

Recipe path	Project tag	SHA (verified)
kf6-extra-cmake-modules	v6.27.0	resolved
kf6-karchive	v6.27.0	resolved
kf6-kauth	v6.27.0	resolved
kf6-kbookmarks	v6.27.0	resolved
kf6-kcmutils	v6.27.0	resolved
kf6-kcodecs	v6.27.0	resolved
kf6-kcolorscheme	v6.27.0	resolved
kf6-kcompletion	v6.27.0	resolved
kf6-kconfig	v6.27.0	resolved
kf6-kconfigwidgets	v6.27.0	resolved
kf6-kcoreaddons	v6.27.0	resolved
kf6-kcrash	v6.27.0	resolved
kf6-kdbusaddons	v6.27.0	resolved
kf6-kdeclarative	v6.27.0	resolved
kf6-kded6 (kded)	v6.27.0	resolved
kf6-kglobalaccel	v6.27.0	resolved
kf6-kguiaddons	v6.27.0	resolved
kf6-ki18n	v6.27.0	resolved
kf6-kiconthemes	v6.27.0	resolved
kf6-kidletime	v6.27.0	resolved
kf6-kimageformats	v6.27.0	resolved
kf6-kio	v6.27.0	resolved
kf6-kirigami (Kirigami)	v6.27.0	resolved
kf6-kitemmodels	v6.27.0	resolved
kf6-kitemviews	v6.27.0	resolved
kf6-kjobwidgets	v6.27.0	resolved
kf6-knewstuff	v6.27.0	resolved
kf6-knotifications	v6.27.0	resolved
kf6-kpackage	v6.27.0	resolved
kf6-kservice	v6.27.0	resolved
kf6-ksvg	v6.27.0	resolved
kf6-ktexteditor	v6.27.0	resolved
kf6-ktextwidgets	v6.27.0	resolved
kf6-kwallet	v6.27.0	resolved
kf6-kwayland	v6.27.0	resolved
kf6-kwidgetsaddons	v6.27.0	resolved
kf6-kwindowsystem	v6.27.0	resolved
kf6-kxmlgui	v6.27.0	resolved
kf6-notifyconfig	v6.27.0	resolved
kf6-parts (KParts)	v6.27.0	resolved
kf6-plasma-activities	v6.27.0	resolved
kf6-prison	v6.27.0	resolved
kf6-pty	v6.27.0	resolved
kf6-solid	v6.27.0	resolved
kf6-sonnet	v6.27.0	resolved
kf6-syntaxhighlighting	v6.27.0	resolved
kf6-kimageformats	v6.27.0	resolved
kf6-attica	v6.27.0	resolved

Currently imported source trees in local/recipes/kde/kf6-* show set(KF_VERSION "6.10.0"). This is 17 minor versions behind. Every framework recipe must be re-pulled, re-patched, re-blake3'd.

2.3 KDE Plasma desktop surface

Recipe	Upstream latest stable	SHA	Notes
kdecoration	v6.7.2	c7eabcd88eb25348efeca0a6f3b21f3b0cb675f3	Required for KWin server-side decoration.
kwin	v6.7.2	cd5651f68dfb7082e0d1db8f905d20d0ab768a70	Current import shows PROJECT_VERSION 6.6.5 — needs 6.7.2 refresh.
konsole	v26.04.3	1bf40011fe7b103f98c1884dfbee298b9b0cde5d	YYYY.MM.PP-style KDE versioning for utility apps.
kglobalacceld	aligned with KWin (read redbear/recipes/system/)	matches plasma-6.7
breeze (style)	v6.7.2	resolved	Theming.
breeze-icons	aligned to Plasma 6.7.2	resolved	Icon theme.

Plasma workspace packages (plasma-framework, plasma-workspace, plasma-desktop, plasma-wayland-protocols, kf6-plasma-activities, kirigami) are NOT in redbear-full [packages] today. Do not pull them in this scope. They remain on the next-iteration plan.

2.4 Wayland / Mesa / DRM / Display

Recipe	Current pin	Upstream latest stable	SHA	Notes
libwayland	1.24.0 (tarball)	1.25.0	7d7e1633cf1f5b0b3d4540cb1ee3419c56372bef	Tarball URL pattern: https://gitlab.freedesktop.org/wayland/wayland/-/releases/1.25.0/downloads/wayland-1.25.0.tar.xz (or git tag)
wayland-protocols	1.38	1.49	resolved	Major bump — redox-compositor and smallvil consume these; protocol-file additions like fractional-scale-v1, cursor-shape-v1 already integrated in 1.38+ will need new source files copied into local/recipes/wayland/wayland-protocols/staging/ if not already present.
mesa	redox-os/mesa fork @ 24.0.8	26.1.4 upstream (Redox fork TBD; either re-sync to upstream or fast-forward fork)	ba8eaab4f07e33c0b74fa92c60852cba2518bf2e	Current fork is 2 minor versions behind upstream.
libdrm	2.4.125	2.4.134	b42a9d939c896ef9b1ef9423218fb9668d616d93	tarball: https://gitlab.freedesktop.org/mesa/libdrm/-/archive/libdrm-2.4.134/libdrm-libdrm-2.4.134.tar.gz
libxkbcommon	1.7.0	1.9.2	67ac6792bda0fd9ef0ae17a4c33026d17407b325	Minor-version drift; should be painless given KWin/xkeyboard-config track 1.7-era.
libepoxy	n/a in current recipe (stub used by KWin)	1.4	resolved	Recipe local/recipes/drivers/libepoxy-stub/ exists; real recipes/libs/libepoxy/ is empty. Decision required: keep stub or backfill real libepoxy. See §3.5.
libevdev	n/a in current pin (untouched)	1.13.6	resolved	Small library, low risk.
libinput	n/a	1.31.3	resolved	Bump.
xkeyboard-config	n/a in recipes	2.9	resolved	xkb data files — runtime data only; safe.
seatd / seatd-redox	n/a	0.9.3	resolved	Drop-in.
expat	2.5.0	2.7.x (latest in line)	resolved	Used by dbus/breeze. Verify exact latest.
dbus	n/a in recipes	1.16.2	resolved	Patch surface in local/patches/dbus/.
polkit	n/a	0.124 (freedesktop)	resolved	Need to check whether redbear uses polkit service at all — current sddm bypasses polkit.
polkit-qt-1	n/a	0.201.1	resolved	Only relevant if polkit re-enabled.

2.5 Custom Red Bear recipes

These don't have an upstream "latest stable" — they're Red Bear originals:

Recipe	Current branch	Action
redox-drm (local fork)	see AGENTS.md	Keep. Re-verify against Mesa 26.1+ updates.
linux-kpi (local fork)	see AGENTS.md	Keep. Re-verify against new Mesa kernel ABI surface.
redox-driver-sys (local fork)	see AGENTS.md	Keep. Update fields if any new Quirks needed.
amdgpu	see AGENTS.md	Keep. Verify build against Qt/Mesa bump.
firmware-loader	see AGENTS.md	No-op.
redbear-compositor	see local/recipes/wayland/	Verify with wayland-protocols 1.49.
redbear-sessiond	see AGENTS.md	Update zbus/zbus_macros if KWin 6.7 wants it.
redbear-greeter	see AGENTS.md	Same.
redbear-power	see AGENTS.md	No-op (out of scope).
pam-redbear	see AGENTS.md	No-op (out of scope).

---

3. Required sub-decisions before bumps

3.1 Qt minor: 6.10.x vs 6.11.x

Cross-compile risk (relibc syscalls) decreases with the conservative older minor. Two paths:

• Path A (recommended): freeze on 6.10.3. Same Qt minor that KWin 6.7.x was packaged against.
• Path B: freeze on 6.11.1. The "real" current latest. Risk: new APIs surfaced since 6.10 may require relibc additions we don't have.

The redbear-full target is Path A. If 6.10.3 proves insufficient for KWin 6.7.2 at build time, fall back to 6.11.1 and document the diff in local/docs/0.2.5-GRAPHICS-FREEZE-PLAN.md §5.

3.2 KDE Frameworks: KDECMake 6.27 vs KDECMake 6.10 drift

KF6 jumped 17 minor versions (6.10 → 6.27) since the local imports. Across those 17 minors there were:

• KDECMake policy changes (CMP0071, CMP0177 etc.)
• KF6→KF6.5+ dependency-cycle cleanups in kf6-kio, kf6-ki18n, kf6-kdeclarative
• Removal of KF5:: compat headers
• New modular headers (Q_NAMESPACE exports added)
• qt6-sensors was renamed to qtsensors

Every local/patches/kf6-*/01-initial-migration.patch will need to be re-validated. This is the single biggest source of build risk in 0.2.5.

Required mitigation: run ./local/scripts/validate-patches.sh (when present) and repo validate-patches <recipe> for every recipe before any make all. A patch that applied at 6.10.0 will not apply at 6.27.0 in 90%+ of cases.

3.3 Mesa fork situation

recipes/libs/mesa/source/ is a Redox fork from gitlab.redox-os.org/redox-os/mesa.git on redox-24.0 branch.

Upstream Mesa jumped from 24.0 → 26.1.x with massive churn:

• New GPU driver activation (intel-ivb-gen8+ got reworked to drm-shim)
• Nouveau removed
• VirGL → Venus-X rework
• spirv → amd/nir rewrite
• New DRM v3.0 helpers

Rebasing the Redox fork onto Mesa 26.1.x is not a patch rebase. It is a fork rebase (git fetch upstream + git rebase redox-26.1). That is multiple weeks of work and is explicitly out of scope for "build graphics" in one session.

Required sub-decision: Either (a) Stay on Mesa 24.0.8 for 0.2.5 and document it as "best effort, expected mismatched version". This avoids the rebase. (b) Bump to upstream Mesa 26.1.x by importing fresh source + porting the existing local/patches/mesa/0{1..6}.patch set. Multi-week effort.

Recommendation (and this is the freeze pin default): freeze Mesa at 24.0.8 (current fork state) for 0.2.5. Document the gap as a known item. Bumping Mesa is a 0.3.0 task.

3.4 KWin 6.7.2 vs prior session's import (6.6.5)

The prior session imported KWin 6.6.5 source into local/recipes/kde/kwin/source/. The upstream latest stable is 6.7.2, with one minor API delta.

KWin 6.7.x is built against:

• Qt 6.8+ (6.10 is fine)
• KDE Frameworks 6.13+ (works on 6.27)
• Wayland 1.24+ (works on 1.25)
• libwayland-egl / Mesa EGL 24+

The 6.6.5 → 6.7.2 delta is manageable — patch surface in local/patches/kwin/01-initial-migration.patch should be reviewable against the diff.

3.5 libepoxy: stub vs real recipe

KWin links libepoxy (EGL dispatch). Red Bear ships a stub that exists as recipes/libs/libepoxy-stub/. Upstream libepoxy is 1.4 (stable). Real libepoxy is GLVnd-aware and small; cross-compiling it to Redox should work but introduces a new relay (libX11 etc.) that the stub skips.

Recommendation: keep the stub for 0.2.5. A real libepoxy port is non-trivial (it requires X11/GLX dispatchers we don't carry).

3.6 SDDM (the display manager)

SDDM 0.21.0 (already pinned) is the upstream latest stable. KWin 6.7.2 is compatible.

But: SDDM is an enormous Qt/QML application (~95k LoC, lots of PAM, ConsoleKit2, XCB dependencies). The current recipe has wayland-patch.sh excluding everything X11/XCB. Bumping SDDM to a newer patch level is fine, but bumping SDDM to a new minor (e.g., 0.22 when it ships) is not in scope.

Freeze target: SDDM 0.21.0 (current pin).

---

4. Patch surface to re-evaluate

Every bump re-introduces drift. Per AGENTS.md §Patch Governance: "DO NOT remove patches from recipe.toml to fix build failures — rebase them." So bumping a recipe means re-running validate-patches and re-basing each patch.

Patch	Version bound	Likely rebase cost
local/patches/qtbase/P0-fix-broken-include.patch	qtbase 6.8 → 6.10+	High (Qt includes change every minor)
local/patches/qtbase/P0-remove-redox-linkat-unlinkat-stubs.patch	qtbase 6.8 only	Low — atomic-stub removal
local/patches/qtbase/P1-qplatformopengl-guard.patch	qtbase 6.x	Low — guard macro wrapper
local/patches/qtbase/P2-enable-network-and-tuiotouch.patch	qtbase 6.x	Medium
local/patches/qtbase/qtwayland-empty-cursor-guards.patch	qtwayland 6.x	Medium
local/patches/qtbase/qtwaylandscanner-null-guard-listeners.patch	qtwayland 6.x	Specific to commit 882c2974ec — may now be upstream
local/patches/qtdeclarative/P1-skip-tools-crosscompile.patch	qtdeclarative 6.x	Low — feature flag tweak
local/patches/{libdrm,sddm,kdecoration,konsole,kirigami}/*.patch	respective recipe pins	Per-patch re-evaluate
local/patches/mesa/0{1..6}*.patch	mesa 24.0.x	Frozen at current fork (see §3.3)

KWin patch surface (most complex single project): local/patches/kwin/01-initial-migration.patch. Needs to be re-run against 6.7.2 diff.

---

5. Required pre-build actions (not done in this plan session)

This plan does not execute a build. The following actions are required before a make all CONFIG_NAME=redbear-full can succeed:

1. Re-pull every Qt subrecipe to point at qt-everywhere-src-6.10.3.tar.xz. Re-blake3.
2. Re-pull every KF6 subrecipe to point at kf6-<project>-v6.27.0 tarball. Re-blake3.
3. Re-pull KWin 6.7.2, kdecoration 6.7.2, konsole 26.04.3.
4. Re-pull libwayland at 1.25.0, wayland-protocols at 1.49.
5. Re-pull libdrm at 2.4.134.
6. Re-validate all patches in local/patches/qt/* and local/patches/kf6-*:

   ./target/release/repo validate-patches qtbase
   ./target/release/repo validate-patches qtdeclarative
   ./target/release/repo validate-patches kwin
   # ... for every recipe that has a local/patches/* entry
   

7. Rebase each patch that fails validation. Save rebased version in local/patches/<recipe>/P<rev>-<name>.patch (no overwrites).
8. Re-validate Mesa redoxfork decision (§3.3).
9. Re-source qtwaylandscanner with current 6.10.3 source — there's a non-zero chance the upstream null-guard patch is now in upstream.
10. Clean prefix: touch qtbase && make prefix after relibc changes.
11. Resolve the amdgpu recipe's linux-kpi surface against Mesa 24.0.8 — amdgpu is gated to compile, but software-render only.

---

6. Freeze-when-green criteria

The 0.2.5 branch will be frozen (no further recipe.toml bumps) when all the following hold:

• recipes/qt/qtbase/recipe.toml pin matches upstream 6.10.3 / 6.11.1 with a verified blake3 = "...".
• recipes/qt/qtdeclarative/recipe.toml same.
• recipes/qt/qtwayland/recipe.toml same.
• recipes/qt/qtsvg/recipe.toml same.
• recipes/qt/qtshadertools/recipe.toml same (currently empty source).
• All recipes/kde/kf6-* pin to v6.27.0.
• recipes/kde/kwin pin to v6.7.2 with rebased local/patches/kwin/01-initial-migration.patch.
• recipes/kde/kdecoration pin to v6.7.2.
• recipes/kde/konsole pin to v26.04.3.
• recipes/kde/sddm stays at v0.21.0 (current).
• recipes/wayland/libwayland pin to 1.25.0.
• recipes/wayland/wayland-protocols pin to 1.49.
• recipes/libs/libdrm pin to 2.4.134.
• recipes/libs/libxkbcommon pin to 1.9.2.
• recipes/libs/mesa decision recorded: 24.0.8 (fork) or 26.1.4 (upstream rebase).
• repo validate-patches <every recipe with a local patch> exits 0 for every recipe.
• make all CONFIG_NAME=redbear-full reaches the disk-image stage (filesystem.img + harddrive.img produced).
• make live CONFIG_NAME=redbear-full produces build/x86_64/redbear-full.iso.
• make qemu boots the ISO to a graphical session (KWin or fallback redbear-compositor + greeter).

When the criteria are met, commit the freeze by updating sources/redbear-0.2.5/ archive and tagging the branch tip.

---

7. Out of scope (explicitly not part of 0.2.5 graphics freeze)

• Mesa 26.1.x fork rebase (§3.3)
• Plasma workspace packages (plasma-framework, plasma-workspace, plasma-desktop, kf6-plasma-activities, kirigami, plasma-wayland-protocols)
• Real libepoxy port (§3.5)
• polkit/polkit-qt-1 re-integration
• Wayland fractional-scale-v1 protocol adoption
• KF6 ports of kwidgetsaddons QML bridges (these are in WIP)
• redbear-kwinft / compositor optimizations
• Any kernel / relibc / libredox bump (system side is being changed in parallel per user)
• Kirigami recipe enable in redbear-full

These belong to 0.3.0.

---

8. Risks summary

Risk	Severity	Mitigation
KF6 6.10 → 6.27 means 17 patch rebases	High	Validate per-recipe; don't roll all at once.
Mesa fork upstream gap (24.0.8 vs 26.1.4)	High	Stay on 24.0.8 for 0.2.5; document for 0.3.0.
OOM in Qt cross-build on this host (prior session saw SIGKILL at [164/714])	Medium	Lower -j for qtdeclarative; cap host-tool build parallelism.
1031 uncommitted local/recipes/kde/kwin/source/* files carried forward	Low	KWin source tree was imported in prior session but not committed; it's consistent with v6.7.2 source. Will be unwound if bump fails.
redox-drm / amdgpu linux-kpi API drift	Medium	Audit against Mesa 24.0.8 ABI only; do not bump Mesa in 0.2.5.
SDDM 0.21 vs KWin 6.7 ABI compat	Low	Verify on first full build.
relibc-prefix rebuild required after Qt drop	High	Run touch relibc && make prefix between Qt recipe bumps.