RedBear-OS/docs/07-RED-BEAR-OS-IMPLEMENTATION-PLAN.md

07 — Red Bear OS Implementation Plan

Purpose

This is the canonical repository-level implementation plan for Red Bear OS.

It is not a historical phase diary and it is not a subsystem deep dive. Its job is to define:

• what Red Bear OS is trying to become,
• how Red Bear relates to upstream Redox,
• which profiles are real product surfaces,
• which workstreams are first-class,
• what the current state is,
• and what order of work best improves the project from here.

Detailed subsystem planning remains in focused documents under local/docs/.

Repository Model

RedBearOS should be understood as an full fork on top of Redox in the same way Ubuntu relates to Debian.

• Redox is upstream.
• Red Bear carries integration, packaging, validation, and subsystem release fork on top.
• Upstream-owned source trees are immutable archived release snapshot.
• Durable Red Bear state belongs in local/patches/, local/recipes/, local/docs/, and tracked Red Bear configs.

The project is in the right long-term shape only when immutable archived upstream sources can be fetched, Red Bear release fork can be apply, and the project still rebuilds successfully.

Ownership Rules

Upstream-owned layer

These are immutable archived release sources, not durable Red Bear storage:

• recipes/*/source/
• most of recipes/ outside local release fork symlinks
• mainline configs such as config/desktop.toml and config/minimal.toml
• generated build outputs under target/, build/, repo/, and recipe-local target/*

Red Bear-owned layer

These are the durable Red Bear source-of-truth paths:

• local/patches/
• local/recipes/
• local/docs/
• tracked Red Bear configs such as config/redbear-*.toml

Upstream-first rule

For fast-moving upstream components, prefer upstream whenever upstream already solves the same problem adequately.

Keep Red Bear patches only while they still provide unique value.

WIP rule

If an upstream recipe or subsystem is still marked WIP, Red Bear treats it as a local project.

That means:

1. upstream WIP can be used as an input and reference,
2. but Red Bear should fix and ship from the local release fork while the work is still WIP,
3. and once upstream promotes that work to first-class supported status, Red Bear should reevaluate and prefer upstream where appropriate.

Core Principles

Preserve Redox architecture

• drivers and services remain userspace-first,
• system boundaries remain explicit,
• capability-oriented design remains intact,
• compatibility shims are acceptable when bounded and well-documented.

Packaging is the integration layer

• functionality is delivered as packages,
• profiles are composed from packages and package groups,
• integration should prefer packaging, configuration, and release fork over invasive upstream rewrites.

Validation over claims

• “builds” is not the same as “supported”,
• every user-visible claim should map to a profile,
• every support claim should be reproducible and evidence-backed.

Product Surfaces

The tracked Red Bear compile targets are:

• redbear-mini
• redbear-full
• redbear-grub

These are the only supported compile targets. Older names such as redbear-minimal, redbear-desktop, redbear-wayland, redbear-kde, redbear-live, redbear-live-mini, and redbear-live-full may still appear in historical notes or legacy implementation details, but they are not the current compile-target surface.

redbear-mini

Primary reproducible baseline.

Scope:

• boot,
• package management,
• native wired networking,
• diagnostics,
• minimal service baseline.

redbear-full

Broader desktop/network/session plumbing profile.

Scope:

• desktop/runtime plumbing,
• D-Bus presence,
• Qt base integration,
• the active desktop-capable target surface.

redbear-grub

Text-only console/recovery target with GRUB boot manager for real bare metal.

Scope:

• diagnostics,
• recovery workflows,
• multi-boot bare-metal install with GRUB chainload.

Desktop policy

• Desktop/graphics are available only on redbear-full.
• Validation work that does not require graphics should prefer redbear-mini or redbear-grub.
• Live .iso outputs are for real bare-metal boot/install workflows, not for VM/QEMU execution; virtualization should use the harddrive.img-based target surface.

Current State Baseline

Repository state summary

The current repo is no longer at a greenfield or “missing everything” stage.

The current evidence-backed baseline is:

• the Red Bear release fork model is documented and in active use,
• major local subsystem plans exist under local/docs/,
• native wired networking is present,
• Qt6 and major downstream desktop dependencies build,
• Wayland-facing relibc compatibility surfaces now rebuild from a immutable archived upstream relibc source tree via local patch carriers,
• libwayland and qtbase build successfully from the reconstructed relibc state,
• the Red Bear-native greeter/login path now has a bounded passing runtime proof, while broader KDE/KWin session stability is still not yet a general runtime claim,
• USB, Wi-Fi, Bluetooth, and low-level controller quality remain first-class unfinished workstreams.

What is current versus historical

Older P0–P6 wording remains useful for continuity, but it is not the canonical current execution model anymore.

Use this document plus current local/docs/ subsystem plans as the source of truth for current work ordering.

Workstream Order

The current repository-wide work order is:

1. repository discipline and release fork hygiene
2. reproducible profiles and validation surfaces
3. low-level controller and IRQ quality
4. USB maturity
5. Wi-Fi native control plane and first driver family
6. Bluetooth controller/host path
7. desktop/session compatibility on top of those runtime services
8. hardware validation and support labeling

These are all first-class targets, but they do not all have the same dependency weight.

Blocker chain

The current blocker structure is:

low-level controller / IRQ quality
  -> USB maturity
      -> realistic Bluetooth transport path

low-level controller / IRQ quality
  -> Wi-Fi driver bring-up
      -> native wireless control plane
          -> desktop-facing compatibility later

This means Red Bear should not present USB, Wi-Fi, Bluetooth, or low-level controller work as optional polish. They are first-class subsystem targets, but they must be executed in dependency order.

Workstreams

1. Repository discipline and release fork hygiene

Goal:

• keep Red Bear-specific work identifiable,
• keep release provisioning predictable,
• ensure durable release fork exist for active Red Bear-owned deltas,
• keep WIP migration logic explicit.

Current state:

• release fork model is documented,
• relibc preservation and patch application proof exists,
• WIP ownership policy is documented,
• documentation still needs cleaner indexing and some historical pruning.

Acceptance:

• sources are provisioned via provision-release.sh and rebuilt predictably,
• the canonical/current-vs-historical split is visible in docs,
• active Red Bear-owned deltas are preserved in local/patches and local/recipes.

2. Profiles and packaging

Goal:

• keep profiles reproducible,
• keep support surfaces obvious,
• keep package-group composition intentional.

Current state:

• tracked Red Bear profiles exist,
• profile roles are clearer than before,
• some older profile wording still overlaps with historical phase language.

Acceptance:

• each tracked profile has a documented role,
• profile behavior is reproducible,
• support labels are tied to profile-specific evidence.

3. Low-level controllers and IRQ quality

Goal:

• improve runtime trust in IRQ delivery, MSI/MSI-X, and IOMMU-adjacent infrastructure,
• turn compile-oriented infrastructure into runtime-proven substrate.

Current state (2026-04-29):

• 5 IRQ/low-level check binaries exist: PCI IRQ, IOMMU, DMA, PS/2, timer validation
• 6 test scripts: test-msix-qemu.sh, test-iommu-qemu.sh, test-xhci-irq-qemu.sh, test-ps2-qemu.sh, test-timer-qemu.sh, test-lowlevel-controllers-qemu.sh (aggregate)
• redox-driver-sys: typed PCI/IRQ userspace substrate with host-runnable unit tests, quirk-aware interrupt-support reporting, MSI-X table helpers, affinity helpers
• redox-drm: shared interrupt abstraction with MSI-X-first and legacy-IRQ fallback
• iommu daemon: specification-rich IOMMU/interrupt-remapping direction
• Kernel: PIC, IOAPIC, LAPIC/x2APIC, IDT reservation, masking, EOI, spurious IRQ accounting
• Weakness: runtime validation thinner than desired, controller-specific characterization uneven, this remains a blocker for USB/Wi-Fi/Bluetooth reliability claims

Canonical plan:

• local/docs/IRQ-AND-LOWLEVEL-CONTROLLERS-ENHANCEMENT-PLAN.md

Acceptance:

• runtime evidence exists for the claimed controller/IRQ scope,
• subsystem docs stop overstating compile-oriented proof.

4. USB maturity

Goal:

• mature the existing USB host/controller path into a more reliable subsystem,
• improve topology, hotplug, HID, storage, and observability confidence.

Current state (2026-04-29):

• Enhanced USB checker (redbear-usb-check): xHCI controller detection, device enumeration, HID/storage class detection, JSON output, proper cfg-gating, zero warnings
• Unified test harness (test-usb-runtime.sh): guest + QEMU modes, exit-code-based
• Legacy scripts preserved: test-usb-qemu.sh, test-usb-storage-qemu.sh, test-usb-maturity-qemu.sh
• xhcid driver exists, usbscsid for storage, USB HID support via usbhidd
• Controller/runtime maturity still needs hardware validation

Canonical plan:

• local/docs/USB-IMPLEMENTATION-PLAN.md

Acceptance:

• USB support is described honestly by validation state,
• controller/runtime quality is no longer the main blocker for first Bluetooth transport work.

5. Wi-Fi

Goal:

• add one bounded experimental Wi-Fi path that fits Red Bear’s native architecture.

Current state:

• one bounded experimental Intel Wi-Fi path is now in-tree,
• the corresponding tracked validation profile is redbear-wifi-experimental,
• linux-kpi now carries early wireless-subsystem compatibility scaffolding in addition to the earlier low-level helper layer,
• the native control-plane/profile/reporting stack now has bounded scan/connect/disconnect flows, including profile-manager start/stop wiring for the current Wi-Fi path,
• packaged in-target Wi-Fi validation/capture commands now exist for the current bounded Intel path (redbear-phase5-wifi-check, redbear-phase5-wifi-link-check, redbear-phase5-wifi-capture, redbear-phase5-wifi-run, redbear-phase5-wifi-analyze),
• unified Wi-Fi runtime harness (test-wifi-runtime.sh): guest + QEMU modes, exit-code-based, runs wifi-check and wifi-link-check in sequence
• the separate redbear-phase5-network-check / test-phase5-network-qemu.sh path on redbear-full now proves bounded desktop/network plumbing in QEMU and should not be confused with the Wi-Fi plan's later real-hardware Phase W5 completion criteria,
• real hardware scan/auth/association/data-path proof is still missing,
• linux-kpi is still not the Wi-Fi architecture by itself.

Canonical plan:

• local/docs/WIFI-IMPLEMENTATION-PLAN.md

Acceptance:

• one experimental Wi-Fi family is packaged and evidence-backed,
• post-association handoff to the existing network stack is real,
• the bounded station-mode lifecycle is visible through driver, control-daemon, profile-manager, and runtime-reporting surfaces,
• desktop-facing Wi-Fi claims remain honest and bounded.

6. Bluetooth

Goal:

• add a bounded host-side Bluetooth path after its transport/runtime dependencies are credible.

Current state:

• one bounded in-tree BLE-first experimental slice now exists,
• architecture direction is documented,
• redbear-bluetooth-battery-check (666 lines, comprehensive BLE battery level checker),
• unified BT runtime harness (test-bt-runtime.sh): guest + QEMU modes, exit-code-based,
• transport dependency on USB maturity remains explicit.

Canonical plan:

• local/docs/BLUETOOTH-IMPLEMENTATION-PLAN.md

Acceptance:

• one controller path, one host path, and one bounded BLE-first user-facing workflow exist with experimental support language.

7. Graphics, Wayland, and desktop/session compatibility

Goal:

• turn the current build-visible desktop stack into runtime-trusted session surfaces.

Current state (2026-04-29):

• Phase 1 (Runtime Substrate): build-verified complete. Zero warnings, zero test failures, zero LSP errors. Four Phase 1 check binaries (evdev, udev, firmware, DRM) + redbear-info --probe + automated QEMU test harness exist. Runtime validation pending (requires QEMU/bare metal).
• Phase 2 (Wayland Compositor): bounded proof scaffold exists. redbear-compositor (788-line Rust compositor) builds with zero warnings and self-consistent protocol dispatch (3/3 tests pass). Known limitations: SHM fd passing uses payload bytes (not Unix SCM_RIGHTS), framebuffer compositing uses private heap memory, wire encoding uses NUL-terminated strings. Phase 2 check binary + test harness exist. Not yet a real client-compatible compositor runtime proof.
• Phase 3 (KWin Session): KWin recipe attempts real cmake build with QML/Quick disabled. Blocked by QML gate. Redbear-compositor serves as the Wayland compositor. Phase 3 preflight check binary + test harness exist.
• Phase 4 (KDE Plasma): 36/48 KDE recipes build. 12 blocked by QML gate (kirigami → plasma-framework → plasma-workspace → plasma-desktop). Real builds gated on QML resolution. Legacy test scripts exist.
• Phase 5 (Hardware GPU): redox-drm with Intel Gen8-Gen12 + AMD + virtio-gpu. Mesa builds with llvmpipe + virgl (virtio_gpu_dri.so). GPU CS ioctl protocol exists, backend pending. DRM display check binary exists. Hardware validation pending.

Canonical references:

• local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md — canonical desktop path from console to hardware-accelerated KDE Plasma on Wayland
• local/docs/WAYLAND-IMPLEMENTATION-PLAN.md — canonical Wayland subsystem plan beneath the desktop path
• local/docs/GREETER-LOGIN-IMPLEMENTATION-PLAN.md — canonical greeter/login plan beneath the desktop path
• local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md — canonical comprehensive plan (supersedes other status docs)
• docs/05-KDE-PLASMA-ON-REDOX.md — historical KDE implementation rationale

Acceptance:

• redbear-full remains the broader desktop/session plumbing slice (the Wayland validation slice is handled within redbear-full),
• the active desktop-capable tracked targets keep honest session-viability language tied to redbear-full, not older historical target names.

8. Hardware validation and support labeling

Goal:

• convert “builds” and “boots” into explicit support claims with evidence.

Current state:

• validation language is better than before,
• runtime support labeling still needs more consistent central presentation.

Acceptance:

• support claims are profile-scoped,
• evidence is reproducible,
• the project has a clearer matrix of current, experimental, and validated surfaces.

Canonical Subsystem Documents

The current subsystem plans to treat as first-class are:

• local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md — canonical desktop path plan
• local/docs/WAYLAND-IMPLEMENTATION-PLAN.md — canonical Wayland subsystem plan
• local/docs/GREETER-LOGIN-IMPLEMENTATION-PLAN.md — canonical greeter/login plan
• local/docs/IRQ-AND-LOWLEVEL-CONTROLLERS-ENHANCEMENT-PLAN.md
• local/docs/USB-IMPLEMENTATION-PLAN.md
• local/docs/WIFI-IMPLEMENTATION-PLAN.md
• local/docs/BLUETOOTH-IMPLEMENTATION-PLAN.md
• local/docs/KERNEL-IPC-CREDENTIAL-PLAN.md — implemented credential syscalls + kernel robustness
• local/docs/RELIBC-IPC-ASSESSMENT-AND-IMPROVEMENT-PLAN.md
• local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md — canonical comprehensive plan

The older architecture/roadmap docs under docs/01–docs/05 remain useful, but they should be read together with status notes and the newer local subsystem docs.

Acceptance Model

Red Bear should use simple evidence language consistently:

• builds
• boots
• enumerates
• usable
• validated
• experimental

Do not compress these into a single “supported” claim.

Immediate Documentation Priorities

The highest-value documentation follow-ups from the current state are:

1. add a clearer document-status matrix in docs/README.md,
2. add a WIP migration ledger for major upstream-WIP-to-local-release fork transitions,
3. add a concise script behavior matrix for sync/fetch/apply/build helper scripts,
4. continue pruning obsolete local release fork only after release provisioning proofs confirm upstream coverage is sufficient.

Bottom Line

Red Bear OS is no longer at the stage where the main question is “can we start?”.

The current state is a transition from compile-oriented subsystem accumulation toward a stricter, profile-driven, release fork-disciplined, evidence-backed system project. The implementation plan must now optimize for:

• predictable release provisioning,
• durable local release fork,
• honest support language,
• and execution order that respects the real blocker chain.

That is the current master plan.