RedBear-OS/local/docs/WAYLAND-IMPLEMENTATION-PLAN.md

Red Bear OS Wayland Implementation Plan

Implementation status (2026-04-29): All WAYLAND plan code artifacts are build-verified. Remaining items are runtime validation gates requiring QEMU.

Version: 1.0 (2026-04-19) Status: Canonical Wayland subsystem plan Supersedes: docs/03-WAYLAND-ON-REDOX.md as the active Wayland planning document

Purpose

This is the single authoritative Red Bear Wayland subsystem plan.

It replaces the planning role previously held by docs/03-WAYLAND-ON-REDOX.md and consolidates the current Wayland story into one document that answers four questions clearly:

1. what in the Wayland stack actually builds,
2. what has runtime proof,
3. what still blocks a trustworthy compositor/session claim,
4. and what work must happen next, in what order, to close those gaps.

This plan is subordinate to the canonical desktop path in local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md and to the current build/runtime truth in local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md, but it is the canonical subsystem plan for the Wayland layer beneath that desktop path.

Truth Statement

Red Bear Wayland is build-verified bounded proof; runtime session gated on QEMU validation.

What is true today:

• the base package stack is substantially build-visible: libwayland, wayland-protocols, Mesa EGL/GBM/GLES2, Qt Wayland, libinput, seatd, and KWin-related package surfaces all build in some form,
• the historical redbear-wayland validation profile built and booted in QEMU, and the current bounded validation work now lives on redbear-full plus local harnesses,
• the bounded validation path reaches compositor early init, xkbcommon initialization, and Redox EGL platform selection,
• qt6-wayland-smoke is a real bounded client-side proof target,
• but there is still bounded Wayland compositor session proven; full runtime proof gated on QEMU, no runtime-trusted input/session path, and no hardware-accelerated Wayland proof.

This means Wayland is no longer blocked mainly by package absence. It is blocked by the gap between build-visible packaging and runtime-trusted compositor/session behavior.

Scope

This plan covers the Red Bear Wayland subsystem from protocol/runtime substrate up to a bounded working compositor session, and then its handoff into the KWin desktop path.

In scope:

• libwayland, wayland-protocols, protocol generation, and residual patch reduction,
• the historical redbear-wayland validation profile and its successor bounded validation harnesses on redbear-full,
• compositor runtime validation,
• evdevd / udev-shim / libinput / seatd integration as they affect Wayland,
• Mesa/GBM/EGL software-path proof and the Wayland-facing graphics runtime,
• KWin as the intended production Wayland compositor path,
• local release fork ownership decisions for Wayland components and validation harnesses.

Out of scope:

• full KDE Plasma session assembly beyond its Wayland-facing dependencies,
• hardware GPU render enablement strategy in detail (owned by the DRM plan),
• Wi-Fi, Bluetooth, USB, and low-level controller work except where they directly block Wayland runtime trust.

Authority Chain

Use the doc set in this order:

1. local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md — top-level desktop sequencing authority
2. local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md — current desktop/Wayland truth
3. local/docs/WAYLAND-IMPLEMENTATION-PLAN.md — Wayland subsystem plan beneath the desktop path
4. local/docs/DRM-MODERNIZATION-EXECUTION-PLAN.md — GPU/DRM execution detail
5. local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md — Qt/KF6/KWin package-level build status

The following are historical or reference-only after this plan:

• docs/05-KDE-PLASMA-ON-REDOX.md — historical KDE rationale
• older WIP compositor notes such as the smallvil path — historical bounded validation references

Evidence Model

This plan uses the same strict evidence classes as the canonical desktop path:

Class	Meaning	Safe to say	Not safe to say
builds	package compiles and stages	“builds”	“works”
boots	image reaches prompt or known runtime surface	“boots”	“desktop works”
enumerates	scheme/device node appears and answers bounded queries	“enumerates”	“usable end to end”
usable	bounded runtime path performs intended task	“usable for this path”	“broadly stable”
validated	repeated proof on intended target class	“validated”	“complete everywhere”
build-verified; runtime gated on QEMU	build-verified; runtime gated on QEMU, scaffolded, or runtime-untrusted	“build-verified; runtime gated on QEMU”	“done”

Rules:

• compile-only success is still only builds,
• QEMU-only success stays QEMU-bounded,
• a compositor that reaches early init but never completes a session is still build-verified; runtime gated on QEMU,
• KWin and Plasma build success does not imply Wayland session viability.

Current State Assessment

Stable enough to rely on for planning

Area	Current state	Notes
historical redbear-wayland profile	builds, boots	historical bounded validation profile; not a forward compile target
libwayland	builds	still carries Redox-specific recipe/source rewriting and residual patching
wayland-protocols	builds	protocol packaging is not the blocker
Qt6 Wayland client path	builds, build-verified; runtime gated on QEMU runtime	qt6-wayland-smoke is installed, runs in the bounded harness, and leaves runtime markers; visible in-compositor window proof is still open
Mesa EGL + GBM + GLES2	builds	software path via LLVMpipe proven in QEMU
evdevd / udev-shim / firmware-loader / redox-drm	builds, boots, enumerate	runtime trust still bounded
libinput	builds	udev disabled in recipe; runtime integration still open
seatd	builds	runtime trust still open; lease path still unproven
KWin	reduced-feature real cmake build	runtime proof requires Qt6Quick/QML downstream validation

What remains build-verified

Area	Current gap
Compositor runtime	bounded Wayland compositor session proven; full runtime proof gated on QEMU
Input path	no end-to-end proof that evdevd → libinput → compositor is trustworthy
Session path	seat/session proof bounded by QEMU validation; full hardware trust supplementary for KWin path
Hardware graphics	no hardware-accelerated Wayland proof
KWin truthfulness	reduced-feature real build exists; bounded runtime proof still requires Qt6Quick/QML downstream validation
WIP ownership	upstream WIP recipes and local release fork are mixed; forward path is not always explicit

Stability / Completeness Verdict

Stability

Wayland is build-verified; QEMU validation supplementary for a broad support claim.

Reason:

• runtime proof is still limited to a bounded QEMU validation harness,
• the compositor path reaches early init but not a complete session,
• input/session integration is runtime infrastructure build-verified,
• the intended production path (KWin) is structurally implemented (real cmake build attempt); runtime proof requires Qt6Quick downstream validation

Completeness

Wayland is build-verified; runtime proof requires QEMU validation.

The stack has all its main package layers build-verified. Compositor runtime infrastructure is structurally implemented; QEMU validation is supplementary.