diff --git a/docs/07-RED-BEAR-OS-IMPLEMENTATION-PLAN.md b/docs/07-RED-BEAR-OS-IMPLEMENTATION-PLAN.md index deb29f5eba..784ce11354 100644 --- a/docs/07-RED-BEAR-OS-IMPLEMENTATION-PLAN.md +++ b/docs/07-RED-BEAR-OS-IMPLEMENTATION-PLAN.md @@ -418,7 +418,7 @@ The current subsystem plans to treat as first-class are: - `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/archived/RELIBC-IPC-ASSESSMENT-AND-IMPROVEMENT-PLAN.md` + (supersedes the former `archived/RELIBC-IPC-ASSESSMENT-AND-IMPROVEMENT-PLAN.md`, removed 2026-07-27) - `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 diff --git a/docs/README.md b/docs/README.md index 71afd71d12..fa6dd67a9a 100644 --- a/docs/README.md +++ b/docs/README.md @@ -66,7 +66,7 @@ console-to-KDE plan. - `../local/docs/ACPI-IMPROVEMENT-PLAN.md` — ACPI ownership, robustness, validation - `../local/docs/IRQ-AND-LOWLEVEL-CONTROLLERS-ENHANCEMENT-PLAN.md` — PCI/IRQ quality, MSI/MSI-X (restored to top-level from legacy-obsolete dir 2026-07-27) - `../local/docs/3D-DESKTOP-COMPREHENSIVE-PLAN.md` — DRM/KMS + Wayland + 3D userland (subsystem detail; formerly `DRM-MODERNIZATION-EXECUTION-PLAN.md`, deleted 2026-07-27) -- `../local/docs/DRIVER-MANAGER.md` (consolidated 2026-07-27, post-v5.9 systematic assessment) — canonical current-state doc for `driver-manager` (`../local/recipes/system/driver-manager/`). **CUTOVER COMPLETE (2026-07-23, operator-ratified):** driver-manager owns the boot-time PCI match/claim/spawn path in every `redbear-*` config; pcid-spawner is retired from configs and gated behind `/etc/driver-manager.d/disabled` as the operator fallback (never deleted). See `../local/docs/evidence/driver-manager/ASSESSMENT-2026-07-22.md` (major assessment, findings B1–G10 + § 11 services integration) and `../local/docs/archived/DRIVER-MANAGER-MIGRATION-PLAN.md` (round-by-round v1.0 → v5.9 history). Delivered: claim-via-channel collapse (pcid `ENOLCK` exclusivity — the pcid-spawner model); init `ConditionPathExists` gate (systemd-style, `!` negation); spawned-mode `pci_register_driver` in linux-kpi (honors `PCID_CLIENT_CHANNEL` — single ownership of match-claim-spawn for native and Linux-port daemons); linux-kpi real MSI/MSI-X via pcid_interface + `pci_request_regions` + `pcie_capability_*` + PM state; redbear-iwlwifi `--daemon` onboarding + `70-wifi.toml`; `--import-linux-ids` Linux id_table→TOML pipeline; scheme operator surface (`bind`/`unbind`/`new_id`/`remove_id`/`driver_override`/`rescan`); Tier-1 driver_override; success-triggered deferred retry; concurrent probes with real `Driver::probe()`; real SIGCHLD/SIGHUP handlers; heartbeat counters; AER `route_to_driver`; `exclusive_with` mutual exclusion; `pci=nomsi` env var; PciQuirkFlags spawn env hints + `REDBEAR_DRIVER_{IOMMU_GROUP,NUMA_NODE,MSIX_VECTORS}`; driver-params bridge live; D-Bus correctly absent (bridge-on-demand). Gate: PASSED in QEMU q35 (initfs ahcid bind, rootfs e1000d concurrent bind, scheme live, resident hotplug). Platform finding: `thread::scope` hangs on Redox (spawn+join used instead). Cookbook now hashes Cargo path-dep sources (staleness hole closed). 148 tests pass; 0 audit-no-stubs violations; zero crate-local warnings on host and redox target. +- `../local/docs/DRIVER-MANAGER.md` (consolidated 2026-07-27, post-v5.9 systematic assessment) — canonical current-state doc for `driver-manager` (`../local/recipes/system/driver-manager/`). **CUTOVER COMPLETE (2026-07-23, operator-ratified):** driver-manager owns the boot-time PCI match/claim/spawn path in every `redbear-*` config; pcid-spawner is retired from configs and gated behind `/etc/driver-manager.d/disabled` as the operator fallback (never deleted). See the Round-22 driver-manager assessment (removed in the 2026-07-27 consolidation; see `local/docs/SUPERSEDED-DOC-LOG.md`) (major assessment, findings B1–G10 + § 11 services integration) and the v1.0-v5.9 migration history (removed in the 2026-07-27 consolidation; see `local/docs/SUPERSEDED-DOC-LOG.md`) (round-by-round v1.0 → v5.9 history). Delivered: claim-via-channel collapse (pcid `ENOLCK` exclusivity — the pcid-spawner model); init `ConditionPathExists` gate (systemd-style, `!` negation); spawned-mode `pci_register_driver` in linux-kpi (honors `PCID_CLIENT_CHANNEL` — single ownership of match-claim-spawn for native and Linux-port daemons); linux-kpi real MSI/MSI-X via pcid_interface + `pci_request_regions` + `pcie_capability_*` + PM state; redbear-iwlwifi `--daemon` onboarding + `70-wifi.toml`; `--import-linux-ids` Linux id_table→TOML pipeline; scheme operator surface (`bind`/`unbind`/`new_id`/`remove_id`/`driver_override`/`rescan`); Tier-1 driver_override; success-triggered deferred retry; concurrent probes with real `Driver::probe()`; real SIGCHLD/SIGHUP handlers; heartbeat counters; AER `route_to_driver`; `exclusive_with` mutual exclusion; `pci=nomsi` env var; PciQuirkFlags spawn env hints + `REDBEAR_DRIVER_{IOMMU_GROUP,NUMA_NODE,MSIX_VECTORS}`; driver-params bridge live; D-Bus correctly absent (bridge-on-demand). Gate: PASSED in QEMU q35 (initfs ahcid bind, rootfs e1000d concurrent bind, scheme live, resident hotplug). Platform finding: `thread::scope` hangs on Redox (spawn+join used instead). Cookbook now hashes Cargo path-dep sources (staleness hole closed). 148 tests pass; 0 audit-no-stubs violations; zero crate-local warnings on host and redox target. - `../local/docs/3D-DESKTOP-COMPREHENSIVE-PLAN.md` — Wayland compositor subsystem detail (formerly `WAYLAND-IMPLEMENTATION-PLAN.md`, deleted 2026-07-27) - `../local/docs/KERNEL-IPC-CREDENTIAL-PLAN.md` — relibc IPC surface (formerly `archived/RELIBC-IPC-ASSESSMENT-AND-IMPROVEMENT-PLAN.md`, deleted 2026-07-27) - `../local/docs/GREETER-LOGIN-IMPLEMENTATION-PLAN.md` — greeter/login design diff --git a/local/docs/3D-DESKTOP-COMPREHENSIVE-PLAN.md b/local/docs/3D-DESKTOP-COMPREHENSIVE-PLAN.md index b352175393..497a2d3964 100644 --- a/local/docs/3D-DESKTOP-COMPREHENSIVE-PLAN.md +++ b/local/docs/3D-DESKTOP-COMPREHENSIVE-PLAN.md @@ -1003,7 +1003,7 @@ that followed) were deleted in commit `092d1b39c3` ("docs: consolidate | `local/docs/legacy-obsolete-2026-07-25/WAYLAND-IMPLEMENTATION-PLAN.md` | 186 | Diagnostic §§1-2 accurate; execution plan superseded by this doc | | `local/docs/archived/ACPI-I2C-HID-IMPLEMENTATION-PLAN.md` | 339 | Deferred; USB HID is primary input path | | `local/docs/archived/BUILD-SYSTEM-IMPROVEMENTS.md` | 621 | Historical post-mortem | -| `local/docs/archived/DRIVER-MANAGER-MIGRATION-PLAN.md` | 2,861 | Round-by-round history (182 KB) superseded by `DRIVER-MANAGER.md` | +| the v1.0-v5.9 migration history (removed in the 2026-07-27 consolidation; see `local/docs/SUPERSEDED-DOC-LOG.md`) | 2,861 | Round-by-round history (182 KB) superseded by `DRIVER-MANAGER.md` | | `local/docs/archived/IMPLEMENTATION-MASTER-PLAN.md` | 129 | Completion report superseded by `CONSOLE-TO-KDE` | | `local/docs/archived/IMPROVEMENT-PLAN.md` | 575 | RESOLVED quality audit | | `local/docs/archived/INTEL-HDA-IMPLEMENTATION-PLAN.md` | 417 | Deferred audio plan | @@ -1017,8 +1017,8 @@ that followed) were deleted in commit `092d1b39c3` ("docs: consolidate | `local/docs/archived/USB-BOOT-INPUT-PLAN.md` | 169 | Superseded | | `local/docs/archived/USB-VALIDATION-RUNBOOK-2026-07.md` | 137 | Older version; canonical `USB-VALIDATION-RUNBOOK.md` at top-level | | `local/docs/archived/XHCID-DEVICE-IMPROVEMENT-PLAN.md` | 360 | Superseded | -| `local/docs/evidence/driver-manager/ASSESSMENT-2026-07-22.md` | 368 | Pre-cutover; superseded by `DRIVER-MANAGER.md` | -| `local/docs/evidence/driver-manager/D5-AUDIT.md` | 390 | Pre-cutover D5 gate audit; superseded | +| the Round-22 driver-manager assessment (removed in the 2026-07-27 consolidation; see `local/docs/SUPERSEDED-DOC-LOG.md`) | 368 | Pre-cutover; superseded by `DRIVER-MANAGER.md` | +| the D5 capability audit (removed in the 2026-07-27 consolidation; see `local/docs/SUPERSEDED-DOC-LOG.md`) | 390 | Pre-cutover D5 gate audit; superseded | | `local/docs/fork-push-status/2026-07-12-Round-9-phase-8.3.md` | 83 | Point-in-time push log | | `local/docs/boot-logs/README.md` | 57 | Keep as directory index only if whole dir is kept; otherwise delete | | `local/docs/boot-logs/cachyos-boot-20260629-0520.md` | 52 | Reference log from CachyOS | diff --git a/local/docs/BLUETOOTH-IMPLEMENTATION-PLAN.md b/local/docs/BLUETOOTH-IMPLEMENTATION-PLAN.md new file mode 100644 index 0000000000..09a8481000 --- /dev/null +++ b/local/docs/BLUETOOTH-IMPLEMENTATION-PLAN.md @@ -0,0 +1,703 @@ +# Red Bear OS Bluetooth Implementation Plan + +## Purpose + +This document defines the current Bluetooth state in Red Bear OS, assesses what the repo now proves +through its bounded first slice, and lays out the conservative roadmap beyond that slice. + +The goal is to describe what the repo currently proves, what it does not prove, what parts of the +Bluetooth stack are credible versus not credible today, and how Red Bear can grow from **one +bounded experimental Bluetooth slice** toward broader support without overstating current runtime +validation. + +## Validation States + +- **builds** — code exists in-tree and is expected to compile +- **boots** — image or service path reaches a usable runtime state +- **validated** — behavior has been exercised with real evidence for the claimed scope +- **experimental** — available for bring-up, but not support-promised +- **missing** — no in-tree implementation path is currently present + +This repo should not treat planned scope as equivalent to implemented support. + +## Current Repo State + +### Summary + +Broad Bluetooth support is still **missing** in Red Bear OS, but the repo now carries one bounded +experimental first slice. + +That bounded slice now has a packaged in-guest checker (`redbear-bluetooth-battery-check`) and a +host-side QEMU harness (`./local/scripts/test-bluetooth-qemu.sh --check`). That QEMU validation +path is still being stabilized, so it should currently be described as **QEMU validation in +progress**, not as already validated for its claimed scope. + +That first in-tree slice is deliberately narrow: + +- standalone profile: `config/redbear-bluetooth-experimental.toml` +- transport daemon: `local/recipes/drivers/redbear-btusb/` +- host/control daemon: `local/recipes/system/redbear-btctl/` +- packaged in-guest checker: `redbear-bluetooth-battery-check` +- host QEMU harness: `local/scripts/test-bluetooth-qemu.sh` +- startup model: explicit startup only +- transport model: USB-attached only +- protocol scope: BLE-first only +- autospawn model: **not** wired to USB-class autospawn yet + +This does **not** mean Red Bear has broad Bluetooth support. It means the repo now has one +experimental, profile-scoped bring-up surface instead of zero in-tree Bluetooth components. + +What the repo *does* have is enough adjacent infrastructure to make a Bluetooth port plausible: + +- userspace drivers and schemes as the standard architectural model +- USB and PCI hardware access patterns +- runtime diagnostics discipline +- D-Bus plumbing for later desktop compatibility work +- an evolving input and hotplug model that could later absorb Bluetooth HID devices + +### Feasibility Summary + +Implementing Bluetooth from scratch in Red Bear is **possible**, but only in a narrow, staged +sense. + +The currently credible interpretation is: + +- **feasible**: one experimental USB-attached controller path, one native host daemon, one BLE-first + workload, one CLI/control surface, one hardware-specific validation slice +- **not yet credible**: broad controller coverage, full classic-Bluetooth parity, Bluetooth audio, + or a desktop-equivalent BlueZ replacement in the first pass + +So the answer is not “Bluetooth from scratch is unrealistic,” but it is also not “Bluetooth is just +one more driver.” The feasible first target is a deliberately small subsystem slice. + +### Current Status Matrix + +| Area | State | Notes | +|---|---|---| +| Bluetooth controller support | **experimental, scheme interface live** | `redbear-btusb` now probes USB for Bluetooth class devices, parses descriptors, runs HCI init sequence (Reset → Read BD Addr → Read Local Version), and serves `scheme:hciN` with full SchemeSync implementation (status, info, command, events, ACL, LE scan/connect/disconnect, GATT discover services/chars, GATT read char). 151 tests pass including scheme, transport, and GATT tests. | +| Bluetooth host stack | **experimental, scheme-backed backend with GATT** | `redbear-btctl` now has `HciBackend` that implements the Backend trait by reading/writing `scheme:hciN` files, including full GATT workflow (discover services → discover characteristics → read char value). Backend selection via `REDBEAR_BTCTL_BACKEND=hci` env var. `StubBackend` remains default. 56 tests pass. | +| Pairing / bond database | **experimental bounded slice** | `redbear-btctl` now persists conservative stub bond records under `/var/lib/bluetooth//bonds/`; connect/disconnect control targets those records, and the checker now verifies cleanup honesty, but this is still storage/control plumbing only, not real pairing or generic reconnect validation | +| Desktop Bluetooth API | **missing** | D-Bus exists generally, but no Bluetooth API/service exists | +| Bluetooth HID | **missing** | Could later build on input modernization work | +| Bluetooth audio | **missing** | Also blocked by broader desktop audio compatibility work | +| Runtime diagnostics | **partial implemented** | `redbear-info` now reports the bounded Bluetooth transport/control surfaces conservatively | + +## Evidence Already In Tree + +### Direct negative evidence + +- `HARDWARE.md` says broad Wi-Fi and Bluetooth support is still incomplete even though bounded + in-tree scaffolding now exists +- `local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md` historical appendix treats `Wi-Fi/BT` as in progress with bounded wireless + scaffolding present but validated connectivity still incomplete + +### Positive architectural prerequisites + +- `docs/01-REDOX-ARCHITECTURE.md` describes the userspace-daemon and scheme model Red Bear must + follow for any new hardware subsystem +- `docs/07-RED-BEAR-OS-IMPLEMENTATION-PLAN.md` sets the repo-wide rule that support claims must be + profile-scoped and evidence-backed +- `local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md` defines the validation-language model and the + consolidated desktop/runtime context a future Bluetooth path must use +- `local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md` shows the direction of travel for per-device, + hotplug, named input sources, which is relevant to later Bluetooth HID support +- `config/redbear-full.toml` and related profile wiring already show D-Bus and desktop-session + plumbing that later Bluetooth desktop integration might rely on + +## Feasibility Constraints + +### 1. Bluetooth is not one driver + +Bluetooth in Red Bear cannot be treated as a single device daemon. + +At minimum, Red Bear would need: + +- controller transport handling +- adapter state management +- scanning and connection management +- pairing / bonding persistence +- higher protocol layers +- some user-facing control surface + +This makes Bluetooth more like networking than like a single peripheral driver. + +### 1.1 From-Scratch Scope Reality + +Starting from zero, the minimum Red Bear-native Bluetooth stack is still several layers: + +- controller transport +- HCI command/event handling +- adapter management +- LE scanning and connection lifecycle +- pairing / bonding policy and persistence +- ATT/GATT client work for the first useful BLE workload +- some observable user control/reporting surface + +That means “from scratch” should be read as “new native subsystem assembly from several bounded +components,” not as “write a single daemon and call Bluetooth done.” + +### 1.2 Minimum Native Subsystem Shape + +The smallest Red Bear-native Bluetooth subsystem should be split into these pieces: + +- one **controller transport daemon** for the first supported controller family +- one **host daemon** for adapter state, discovery, connection state, and higher protocol work +- one **user-facing control path** (CLI first, compatibility shim later if needed) +- one **pairing/bond persistence path** with a documented storage location and lifecycle + +This should be treated as the minimum subsystem shape, not as optional later cleanup. + +### 2. The correct architectural fit is native userspace daemons + +The repo's existing system model strongly favors: + +- userspace controller daemons +- explicit runtime services +- narrow compatibility shims when desktop software expects them +- profile-scoped support language + +That means Bluetooth should be implemented as a native Red Bear subsystem, not described as a +wholesale Linux/BlueZ drop-in. + +### 2.1 BlueZ-equivalent replacement is not the first feasible target + +Red Bear should not frame the initial work as “reimplement BlueZ.” + +That would pull in a much larger surface: + +- broad controller/transport coverage +- full classic + BLE host functionality +- stable D-Bus compatibility shape +- profile breadth beyond the first bounded use case +- much more policy and persistence behavior than the repo currently needs for an initial milestone + +The first feasible target is instead: + +- native Red Bear controller transport daemon +- native Red Bear host daemon +- small native CLI/control path +- later compatibility shim only if real desktop consumers require one + +### 2.2 Repo Placement Guidance + +Unless upstream Redox grows a first-class Bluetooth path first, the initial Red Bear work should +live under `local/`: + +- controller transport daemon recipes under `local/recipes/drivers/` +- host daemon, CLI, and compatibility-surface recipes under `local/recipes/system/` +- Red Bear-specific profile and service wiring under `config/redbear-*.toml` +- validation helpers under `local/scripts/` +- support-language and roadmap updates under `local/docs/` + +That keeps the first implementation pass aligned with Red Bear's release fork model and rebase strategy. + +### 3. Desktop parity is not the first milestone + +The current repo does not justify claiming a full desktop Bluetooth user experience early. + +The first realistic milestone is much smaller: + +- one controller family +- one transport path +- one limited workload +- experimental support language only + +### 3.1 BLE-first is materially more feasible than classic-first + +The repo should treat **BLE-first** as the credible from-scratch path. + +Why: + +- it keeps the first useful workload smaller +- it avoids early pressure for classic-audio and broader profile parity +- it matches the repo's current “bounded experimental slice first” discipline +- it reduces the amount of early compatibility behavior that must be correct before any user value + appears + +Classic Bluetooth should therefore be treated as a later expansion, not as the first milestone. + +### 3.2 First-Milestone Dependency + +If the first supported controller is USB-attached, then Bluetooth Phase B1 depends directly on the +USB plan's controller and hotplug baseline work. + +In practice that means Bluetooth should not claim a validated first controller path until the USB +stack can already support that controller family with stable enumeration, attach/detach behavior, +and honest runtime diagnostics. + +### 3.3 Most credible first controller family + +The most credible first controller family is: + +- one **USB-attached BLE-capable adapter family** with simple host-facing initialization behavior + +The least credible early targets are: + +- UART-attached laptop-integrated controllers that require new board-specific transport bring-up +- broad “internal laptop Bluetooth” claims across mixed Intel/Realtek/MediaTek controller families +- controller families that immediately force a large firmware and vendor-protocol surface + +### 4. Bluetooth scope depends on adjacent subsystems + +Bluetooth HID depends on the modernized input path. + +Bluetooth audio depends on the broader audio compatibility story that the repo already treats as +unfinished for desktop use. + +That means the Bluetooth roadmap must stay sequenced and should not over-promise audio or broad +desktop integration early. + +### 4.1 Native host-side Bluetooth is still required even if transport uses compatibility glue + +The Wi-Fi plan already establishes an important repo rule: a compatibility layer can be useful below +the subsystem boundary, but it does not remove the need for a native Red Bear control plane. + +Bluetooth should follow the same rule. + +That means: + +- transport-side glue or borrowed implementation ideas are acceptable +- but adapter management, support language, diagnostics, persistence, and user-visible control + should still be modeled as native Red Bear runtime services + +### 4.2 Bluetooth is gated more by USB maturity than by D-Bus presence + +The repo already has D-Bus packages, but that does **not** make Bluetooth close to done. + +The more important blockers are still: + +- low-level controller/runtime trust +- USB controller correctness and hotplug quality +- a first real transport path +- native host-daemon correctness + +So Bluetooth feasibility should be tied to controller/runtime credibility first, and only later to +desktop compatibility. + +## Recommended From-Scratch Interpretation + +The currently recommended interpretation of “implement Bluetooth from scratch” in this repo is: + +1. do **not** start by chasing broad desktop Bluetooth parity +2. do **not** start by promising internal laptop Bluetooth across all machines +3. do start with one USB-attached adapter family +4. do build one native controller transport daemon plus one native host daemon +5. do target one BLE-first workflow +6. do keep all support language experimental and hardware-specific until real runtime proof exists + +This is the narrowest version of “from scratch” that is still technically meaningful and worth +shipping. + +## Recommended First Deliverable + +The first deliverable Red Bear should actually target is: + +- one standalone `redbear-bluetooth-experimental` profile slice +- one USB Bluetooth transport daemon +- one host/control daemon with bounded scan/status reporting +- one CLI-oriented control path +- one BLE-first workflow boundary +- one validation helper script plus one named runtime surface contract + +That is small enough to be plausible and large enough to count as real Bluetooth work. + +## Implementation Plan + +### Repo-fit note + +Some of the implementation targets below refer to upstream-managed trees such as +`recipes/core/base/source/...`. + +In Red Bear, changes against those paths should be carried through the relevant patch carrier under +`local/patches/` until intentionally upstreamed. This plan names the technical integration point, +not a recommendation to edit upstream-managed trees outside Red Bear's normal release fork model. + +### Phase B0 — Scope Freeze and Support Model + +**Goal**: Decide what the first Bluetooth milestone actually is. + +**What to do**: + +- declare broad Bluetooth support as incomplete today while one bounded experimental slice exists +- define validation labels and support language for future Bluetooth work +- freeze the first milestone as **host-side, experimental, one controller family, one limited use + case** +- keep desktop parity explicitly out of the first support claim + +**Where**: + +- `local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md` +- `docs/07-RED-BEAR-OS-IMPLEMENTATION-PLAN.md` +- this document + +**Exit criteria**: + +- Bluetooth scope is documented without vague “future wireless” wording + +--- + +### Phase B1 — Controller Transport Baseline + +**Goal**: Establish one real Bluetooth controller path. + +**Recommended first target**: + +- one USB-attached Bluetooth controller family, BLE-first + +**Why**: + +- Red Bear already has a USB hardware path +- USB diagnostics and controller visibility already exist +- it is the narrowest realistic controller baseline before considering broader wireless scope + +**What to do**: + +- implement one controller transport daemon +- expose adapter presence and basic control through a Red Bear-native runtime surface +- ensure the daemon fits the userspace service/scheme model +- keep the first daemon/controller contract narrow enough that the host daemon can be built around + one stable transport instead of a generic multi-transport abstraction from day one + +**Where**: + +- `local/recipes/drivers/` for the first Red Bear Bluetooth transport daemon recipe +- `config/redbear-*.toml` for profile/package wiring +- `config/redbear-device-services.toml` or a sibling shared fragment if the daemon becomes a common + service prerequisite +- `local/scripts/` for controller bring-up validation helpers + +**Initial launch path**: + +- for a USB-attached first controller, the long-term attach path should be through + `recipes/core/base/source/drivers/usb/xhcid/drivers.toml` or its eventual Red Bear equivalent + once a Bluetooth USB class match is ready +- before that exists, the first milestone may use explicit Red Bear service startup so the transport + daemon can be validated without pretending that USB class autospawn is already solved +- the first in-tree slice now follows exactly that bounded rule: explicit startup only, with no + claim that `xhcid` or another USB class matcher autospawns Bluetooth yet +- if Red Bear adds that xHCI class match before it exists upstream, it should be carried as a Red + Bear base patch rather than as an unqualified direct tree edit + +**Firmware note**: + +- if the first supported controller family requires firmware upload, reuse the existing + `firmware-loader` / shared device-service pattern instead of inventing a separate firmware path +- if that complexity is too high for the first milestone, choose a controller family that can be + initialized without introducing a second firmware-loading architecture + +**Dependency**: + +- if the first controller is USB-attached, this phase is blocked on the USB plan's U1-U2 baseline + being sufficiently stable for that controller family + +**Exit criteria**: + +- one supported Bluetooth controller can be detected and initialized repeatedly +- controller presence can be reported honestly at runtime +- attach/detach behavior is good enough that controller disappearance does not require reboot to + recover the service path + +**B1 COMPLETION EVIDENCE (2026-04-24)**: +- `local/recipes/drivers/redbear-btusb/source/src/hci.rs` — HCI protocol types (55+ constants), command builders (Reset, Read BD Addr, Read Local Version, LE scan, LE create connection, disconnect), event parsers, structured result types +- `local/recipes/drivers/redbear-btusb/source/src/usb_transport.rs` — UsbHciTransport trait, StubTransport, UsbTransportConfig +- `local/recipes/drivers/redbear-btusb/source/src/main.rs` — USB descriptor parsing, HCI init sequence, ControllerState state machine, daemon_main with scheme server +- 125 tests passing (hci, transport, scheme, endpoint parsing, state machine) +- Commit: `f392c7bf7` + +--- + +### Phase B2 — Minimal Host Daemon + +**Goal**: Create the first Red Bear-native Bluetooth service layer. + +**What to do**: + +- add one host daemon that owns adapter state +- support scanning and connect/disconnect for one limited workload +- add persistent pairing/bond storage only once the storage path is explicitly defined +- keep the control surface small and Red Bear-native +- keep classic-Bluetooth scope and audio/profile breadth explicitly out of this phase + +**Where**: + +- `local/recipes/system/` for the host-daemon recipe +- `config/redbear-*.toml` and init-service wiring for runtime startup +- `/var/lib/bluetooth/` as the first Red Bear-owned bond/state directory, created by profile or + service wiring in the same style used for other runtime-state directories + +**Minimum native surface**: + +- adapter presence/state +- discovery / scan state +- connect / disconnect control +- bond database lifecycle rooted at `/var/lib/bluetooth/` +- failure reporting suitable for later `redbear-info` integration + +**Current in-tree bounded slice**: + +- `redbear-btctl` now ships a minimal file-backed bond store rooted at `/var/lib/bluetooth//bonds/` +- the CLI can add/list/remove **stub** bond records and reload them across process restarts +- the btctl scheme now exposes bounded connect/disconnect control plus read surfaces for connection state and last connect/disconnect results +- the bounded connect path only targets existing stub bond records and keeps connected bond IDs in daemon memory per adapter +- `redbear-info` now reports the bond-store path/count plus bounded connection/result metadata conservatively +- this is explicitly **not** real pairing, link-key exchange, trusted-device policy, validated reconnect behavior, real device traffic, or B3 BLE workload support + +**B2 COMPLETION EVIDENCE (2026-04-24)**: +- `local/recipes/drivers/redbear-btusb/source/src/scheme.rs` — Full SchemeSync implementation serving `scheme:hciN`. 12 handle kinds: status, info, command, events, acl-in, acl-out, le-scan, le-scan-results, connect, disconnect, connections. 34 scheme tests. +- `local/recipes/system/redbear-btctl/source/src/hci_backend.rs` — HciBackend implementing Backend trait via scheme filesystem I/O. SchemeFs trait with StdFs (tests) and RedoxSchemeFs (production). 18 backend tests. +- Backend selection: `REDBEAR_BTCTL_BACKEND=hci` env var, StubBackend remains default +- daemon_main fixed to use correct redox-scheme 0.11 API +- 172 total tests passing (125 btusb + 45 btctl + 2 wifictl) +- Commit: `8ff8c084f` + +**B2 exit criteria assessment**: +- ✅ one host daemon now owns adapter state through the scheme interface +- ✅ scanning and connect/disconnect control is wired through the scheme (scan writes to le-scan, connect writes addr to connect, disconnect resolves handle from connections) +- ✅ bond storage is persistent via BondStore +- ✅ the control surface is small and Red Bear-native +- 🚧 "daemon can rediscover and reconnect to at least one target device class across repeated runs" — not yet runtime-validated with real hardware + +**Exit criteria**: + +- the daemon can rediscover and reconnect to at least one target device class across repeated runs +- the daemon's runtime state is observable enough that future `redbear-info` integration is + straightforward rather than guesswork + +--- + +### Phase B3 — BLE-First User Value + +**Goal**: Deliver the first actually useful Bluetooth capability without overreaching. + +**Recommended first workload**: + +- BLE-first rather than full classic Bluetooth parity +- specifically, one experimental **battery-sensor Battery Level read** using Battery Service + `0000180f-0000-1000-8000-00805f9b34fb` and Battery Level characteristic + `00002a19-0000-1000-8000-00805f9b34fb` + +**Examples of acceptable first workloads**: + +- one BLE sensor/control workflow +- one bounded BLE peripheral interaction that needs scan/connect/read/write/notify + +**Examples of bad first-workload choices**: + +- generic “all BLE works” +- Bluetooth audio +- broad HID support before the input plan matures + +**What to do**: + +- add scan/connect support for one BLE device type +- expose only the minimal behavior the chosen workload needs +- for the current B3 slice, that means **read only** for the experimental battery-sensor workload; + this slice does **not** claim write support or notify support +- keep support language experimental and hardware-specific + +**Where**: + +- host-daemon implementation under `local/recipes/system/` +- tracked profile wiring in one explicitly experimental Red Bear profile slice named + `redbear-bluetooth-experimental` +- validation helper in `local/scripts/` + +**Recommended support slice**: + +- start as one explicitly experimental tracked profile named `redbear-bluetooth-experimental` + rather than claiming Bluetooth generically across all Red Bear images + +**Exit criteria**: + +- one real BLE device type works reliably on the chosen controller family + +**B3 COMPLETION EVIDENCE (2026-04-25)**: +- `local/recipes/drivers/redbear-btusb/source/src/hci.rs` — ATT/GATT types added: AttPdu with 8 builder methods (Read By Group Type Req/Rsp, Read By Type Req/Rsp, Read Req/Rsp, Error Rsp), GattService/GattCharacteristic structs, ATT-over-ACL L2CAP helpers (att_to_acl, acl_to_att), ATT/GATT response parsers, 12 new ATT/GATT tests (~1900 lines total) +- `local/recipes/drivers/redbear-btusb/source/src/scheme.rs` — 5 new GATT handle kinds: GattDiscoverServices, GattDiscoverChars, GattReadChar, GattServices, GattCharacteristics. Write handlers send ATT requests via ACL transport, read handlers return formatted results. 14 new GATT scheme tests (151 total) +- `local/recipes/system/redbear-btctl/source/src/hci_backend.rs` — HciBackend::read_char now performs real GATT workflow: resolve connection handle → discover services → find Battery Service handle range → discover characteristics → find Battery Level value handle → read characteristic value → format as gatt-value with hex/percent. 11 new GATT workflow tests (56 total) +- 209 total tests passing (151 btusb + 56 btctl + 2 wifictl) +- GATT protocol flow: ATT Read By Group Type Request (UUID 0x1800 primary service) → parse service entries → ATT Read By Type Request (UUID 0x2803 characteristic) → parse characteristic entries → ATT Read Request → parse raw bytes +- Result format changes from `stub-value` to `gatt-value` when real GATT data is obtained + +**B3 exit criteria assessment**: +- ✅ ATT/GATT types and parsers cover the Battery Service workload (Read By Group Type, Read By Type, Read, Error Response) +- ✅ GATT scheme endpoints fully wired in btusb scheme (discover services, discover chars, read char, cached results) +- ✅ btctl HciBackend performs end-to-end GATT workflow through scheme filesystem +- ✅ 209 tests passing with comprehensive GATT coverage +- 🚧 "one real BLE device type works reliably on the chosen controller family" — not yet runtime-validated with real hardware; code path is software-complete and testable with USB BT adapter + +--- + +### Phase B4 — Input Integration + +**Goal**: Prepare for Bluetooth HID in a way that matches Red Bear's planned input model. + +**What to do**: + +- build Bluetooth HID integration on top of the named-producer / per-device / hotplug-aware input + direction already documented for `inputd` +- avoid introducing a second incompatible input plumbing path + +**Where**: + +- `recipes/core/base/source/drivers/inputd/` +- `local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md` + +**Exit criteria**: + +- Bluetooth input devices can appear as distinct recoverable input sources rather than as an opaque + special case + +--- + +### Phase B5 — Desktop Control Surface + +**Goal**: Add higher-level control only after the native substrate exists. + +**What to do**: + +- start with a small Red Bear-native control path +- add a compatibility shim only if actual desktop consumers require it +- keep desktop integration explicitly separate from core Bluetooth correctness + +**Where**: + +- Red Bear-native CLI/tooling under `local/recipes/system/` +- any compatibility shim under `local/recipes/` with profile-specific wiring in desktop-oriented + Red Bear configs +- later runtime reporting hooks in `local/recipes/system/redbear-info/` + +**Why**: + +Red Bear already uses the pattern of adding narrow compatibility surfaces where desktop software +expects them instead of importing a whole foreign subsystem model blindly. + +**Exit criteria**: + +- one desktop or user-facing consumer can manage the limited supported Bluetooth path without + changing the underlying native architecture + +--- + +### Phase B6 — Audio and Broader Class Expansion + +**Goal**: Widen Bluetooth scope only after the substrate and adjacent stacks justify it. + +**What to do**: + +- defer Bluetooth audio until the broader Red Bear desktop-audio compatibility path is stronger +- defer broad classic Bluetooth parity until controller and host-daemon maturity are no longer the + main risk +- decide later whether Bluetooth networking or additional classes are worth supporting + +**Where**: + +- later profile/package-group expansion in `config/redbear-*.toml` +- later runtime diagnostics and support-language updates in `local/docs/` and `redbear-info` + +**Exit criteria**: + +- later Bluetooth classes are added only after the repo can name real prerequisites and evidence + +--- + +### Phase B7 — Validation Slice and Support Claims + +**Goal**: Turn Bluetooth from an experimental prototype into a supportable Red Bear feature slice. + +**What to do**: + +- create a Bluetooth-focused validation path tied to a specific profile or package-group slice +- extend runtime diagnostics conservatively once Bluetooth runtime surfaces actually exist +- add hardware-target guidance and support labels + +**Recommended first support language**: + +- one explicitly experimental Red Bear profile named `redbear-bluetooth-experimental` for the first + supported controller + workload combination + +**Where**: + +- `local/scripts/` +- `local/recipes/system/redbear-info/` +- `local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md` +- `HARDWARE.md` + +**Exit criteria**: + +- at least one profile can honestly claim validated experimental Bluetooth support for named + hardware and named workload scope + +**Current in-tree interpretation**: + +- the repo now has the packaged checker and QEMU harness needed to satisfy the narrower + QEMU-scoped version of this exit criterion for one stub-backed Battery Level workload on + `redbear-bluetooth-experimental`, but that QEMU proof is still in progress +- it does **not** satisfy a broader real-hardware or generic BLE exit criterion yet + +## Support-Language Guidance + +Until B1 through B3 exist, Red Bear should use language such as: + +- “Bluetooth is not broadly supported yet” +- “only the bounded experimental Bluetooth slice exists in-tree” +- “Bluetooth remains a future implementation workstream beyond the documented first slice” + +Once B1 and B2 have landed: +- "experimental Bluetooth bring-up exists for one controller family, with a scheme-based transport bridge" +- "Bluetooth support is limited to the documented workload and profile; host daemon communicates via scheme:hciN" + +Once B1 through B3 begin to land, prefer: + +- “experimental Bluetooth bring-up exists for one controller family” +- “Bluetooth support is limited to the documented workload and profile” + +Avoid language such as: + +- “Bluetooth works” +- “desktop Bluetooth is supported” +- “wireless support is complete” + +unless the repo has profile-scoped validation evidence to justify those claims. + +## Summary + +Bluetooth in Red Bear today is still not broad support. + +What now exists is one bounded experimental first slice: explicit-startup, USB-attached, +BLE-first, profile-scoped to `redbear-bluetooth-experimental`, with conservative stub bond-store +persistence rooted at `/var/lib/bluetooth//bonds/` plus bounded connect/disconnect control +that only targets those stored stub bond IDs, plus one experimental battery-sensor Battery Level +read result for the exact Battery Service / Battery Level UUID pair above. That slice can now be +built, booted in QEMU, and exercised by the packaged `redbear-bluetooth-battery-check` helper; the +repeated end-to-end QEMU proof is still being stabilized before it should be described as validated. + +B0 scope freeze is now **complete**. B1 controller transport baseline is **complete** with full scheme +interface live and 151 tests passing. B2 minimal host daemon with scheme transport bridge is +**complete** with scheme-backed backend and bond storage (172 tests). B3 BLE-first user value is +**software-complete** with full GATT client workflow (discover services → discover characteristics → +read value) through the scheme filesystem, 209 tests passing, but awaits runtime validation with +real Bluetooth hardware. + +What makes it feasible is not any existing Bluetooth stack, but the surrounding Red Bear +architecture: userspace daemons, runtime services, diagnostic discipline, profile-scoped support +language, firmware/runtime-service patterns, and an evolving per-device input model. + +The practical feasibility judgment is: + +- **yes**, Bluetooth from scratch is possible in Red Bear +- **but only** as a bounded BLE-first, transport-constrained, experimental subsystem slice +- **and no**, the current repo does not justify treating broad Bluetooth or desktop Bluetooth parity + as a near-term from-scratch target + +That means the right Bluetooth implementation plan is conservative and staged: + +1. freeze scope and support language +2. bring up one controller transport path +3. add one native host daemon +4. deliver one BLE-first workload +5. integrate input and desktop control only after the substrate exists +6. widen class coverage only when adjacent subsystems are ready + +That is the most credible path to Bluetooth in Red Bear without over-claiming support that the repo +does not yet have. diff --git a/local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md b/local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md index e6a6e2fdd1..fbdb4379ec 100644 --- a/local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md +++ b/local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md @@ -33,7 +33,7 @@ delta between v5.9 and v6.0. The following milestones from the `local/docs/DRIVER-MANAGER.md` v5.x consolidation are **DONE** and reflected in this plan's status tables -(per-round history archived in `local/docs/archived/DRIVER-MANAGER-MIGRATION-PLAN.md`): +(per-round history archived in the v1.0-v5.9 migration history (removed in the 2026-07-27 consolidation; see `local/docs/SUPERSEDED-DOC-LOG.md`)): | Milestone | Version | Date | Key commits | Summary | |-----------|---------|------|-------------|---------| diff --git a/local/docs/CUB-PACKAGE-MANAGER.md b/local/docs/CUB-PACKAGE-MANAGER.md new file mode 100644 index 0000000000..390d31a6f6 --- /dev/null +++ b/local/docs/CUB-PACKAGE-MANAGER.md @@ -0,0 +1,366 @@ +# Cub — Red Bear OS Package Manager + +**Status:** Active (redesign complete 2026-05) +**Location:** `local/recipes/system/cub/` +**Type:** Runtime package manager (runs inside Red Bear OS) +**Dependencies:** `pkgutils` (redox-pkg), `pkgar` + +## Overview + +Cub is the Red Bear OS package manager — an AUR-inspired tool for searching, fetching, +building, installing, and managing packages. It serves as the bridge between Red Bear OS +and the Arch Linux AUR ecosystem, converting PKGBUILD recipes into Red Bear OS recipe.toml +files and producing pkgar packages. + +Cub runs as a regular user inside Red Bear OS, managing packages in `~/.cub/` and +installing them via the `pkgar` system. + +## Architecture + +``` +cub (workspace) +├── cub-lib/ ← Core library (13 modules) +│ ├── aur.rs ← AUR RPC v5 client (search, info) +│ ├── storage.rs ← ~/.cub/ user-local storage manager +│ ├── cook.rs ← recipe cooking (shells out to repo cook) +│ ├── pkgbuild.rs ← Enhanced AUR PKGBUILD parser +│ ├── recipe.rs ← Unified recipe.toml generation +│ ├── converter.rs ← Legacy PKGBUILD converter (preserved) +│ ├── cookbook.rs ← recipe.toml generation from RBPKGBUILD +│ ├── rbpkgbuild.rs ← RBPKGBUILD TOML type definitions +│ ├── package.rs ← pkgar archive creation +│ ├── sandbox.rs ← Build sandbox environment +│ ├── deps.rs ← Arch Linux → Redox dependency name mapping +│ ├── rbsrcinfo.rs ← .RBSRCINFO metadata format +│ └── error.rs ← CubError enum (11 variants) +├── cub-tui/ ← Terminal UI (ratatui 0.30 + termion) +│ ├── app.rs ← TUI app struct and event loop +│ ├── theme.rs ← Red Bear color theme +│ ├── views/ ← search, info, install, build, query +│ └── widgets/ ← Reusable TUI components +└── cub-cli/ ← CLI binary entry point + └── main.rs ← 14 Arch-style switches + TUI launcher +``` + +## CLI Reference + +### Operation Modes + +Cub supports three operation modes mirroring pacman: + +| Mode | Flag | Description | +|------|------|-------------| +| Sync | `-S` | Install, search, refresh, upgrade packages | +| Query | `-Q` | Manage locally installed packages | +| Remove | `-R` | Uninstall packages | + +### Sync Operations (`-S`) + +```bash +cub -S # Install from official repo or BUR/AUR +cub -Ss # Search official repo + cached BUR + AUR +cub -Si # Show AUR package info (description, deps, votes) +cub -Sy # Refresh BUR cache + verify AUR connectivity +cub -Syu # Full system upgrade (sync + update all) +cub -Sua # Update AUR packages only +cub -Sc # Clean package caches +``` + +### Build Operations (`-B`, `-G`) + +```bash +cub -B # Build local RBPKGBUILD directory → pkgar + install +cub -G # Fetch AUR PKGBUILD, convert to recipe, save to ~/.cub/ +``` + +### Query Operations (`-Q`) + +```bash +cub -Q # List all installed packages +cub -Qi # Show installed package details (version, deps, size) +cub -Ql # List files installed by a package +``` + +### Remove Operations (`-R`) + +```bash +cub -R # Uninstall a package +``` + +### Other Commands + +```bash +cub -Pi # Inspect installed package or local RBPKGBUILD +cub --import-aur # Import AUR package (clone + convert PKGBUILD) +cub -T, --no-tui # Disable TUI mode (use CLI directly) +cub # No subcommand: launch TUI +``` + +## User Storage (`~/.cub/`) + +Cub maintains all user-local data in `~/.cub/` with four subdirectories: + +``` +~/.cub/ +├── recipes/ # Converted recipe.toml + RBPKGBUILD + patches +│ └── / +│ ├── recipe.toml ← Generated cookbook recipe +│ ├── RBPKGBUILD ← Red Bear PKGBUILD (TOML format) +│ ├── .RBSRCINFO ← Metadata for dependency resolution +│ └── patches/ ← Local patches +├── sources/ # Cached source tarballs and git clones +├── repo/ # Built pkgar packages organized by target +│ └── x86_64-unknown-redox/ +│ ├── .pkgar ← Signed package archive +│ └── .toml ← Package metadata +└── config/ # Cub configuration and keyring +``` + +## AUR Integration + +Cub accesses the Arch User Repository via the AUR RPC v5 API: + +| Endpoint | Method | Cub Function | +|----------|--------|-------------| +| `/rpc?v=5&type=search&arg=` | GET | `AurClient::search(query)` | +| `/rpc?v=5&type=info&arg[]=` | GET | `AurClient::info(pkgs)` | +| `https://aur.archlinux.org/.git` | git clone | `-G ` (import) | + +### PKGBUILD Conversion + +When importing from AUR (`-G` or `--import-aur`): + +1. Clone the AUR git repository +2. Parse `PKGBUILD` bash script — extracts `pkgname`, `pkgver`, `pkgrel`, + `depends`, `makedepends`, `source`, `sha256sums`, `optdepends` +3. Detect build template (cargo, cmake, meson, configure, custom) +4. Map Arch dependencies to Redox equivalents (glibc→relibc, openssl→openssl3, + systemd→removed, etc.) +5. Generate `RBPKGBUILD` (TOML format) and `.RBSRCINFO` +6. Generate `recipe.toml` compatible with the Red Bear cookbook +7. Save all files to `~/.cub/recipes//` + +### Dependency Mapping + +Cub maintains a 44-entry mapping table (`deps.rs`) translating Arch Linux +package names to their Redox/Red Bear equivalents: + +| Arch Package | Redox Mapping | Notes | +|---|---|---| +| `glibc` | `relibc` | Redox uses relibc instead of glibc | +| `openssl` | `openssl3` | Version-specific mapping | +| `gcc`, `make` | `build-base` | Meta-package for build tools | +| `systemd` | *(removed)* | Unavailable on Redox — warning issued | +| `libx11`, `libxcb` | *(mapped)* | X11 unavailable — manual port needed | +| `linux-api-headers` | *(removed)* | Linux-specific — not applicable | +| `wayland` | `wayland` | Direct 1:1 mapping when available | +| `qt6-base` | `qtbase` | Qt 6 base libraries | +| `dbus` | `dbus` | Direct 1:1 mapping | + +Unknown dependencies are passed through unchanged with a warning. + +## Build Flow + +``` +cub -B # Build local RBPKGBUILD + │ + ├─ 1. Parse RBPKGBUILD ← Validate TOML format + ├─ 2. Create sandbox ← .cub-sandbox/{build,stage,sysroot} + ├─ 3. Generate recipe.toml ← cookbook::generate_recipe() + ├─ 4. repo cook ← Shell out to cookbook (cook.rs) + ├─ 5. Locate stage directory ← Find populated stage dir + ├─ 6. Create pkgar archive ← pkgar::create_with_flags() + ├─ 7. Generate .toml metadata ← Package name, version, deps + └─ 8. Install via pkgutils ← library.install() + apply() +``` + +### Sandbox Environment + +The build sandbox sets these environment variables for `repo cook`: + +| Variable | Value | +|----------|-------| +| `COOKBOOK_SOURCE` | Source directory path | +| `COOKBOOK_STAGE` | Stage (install) directory | +| `COOKBOOK_SYSROOT` | Sysroot with built dependencies | +| `COOKBOOK_TARGET` | `x86_64-unknown-redox` | +| `COOKBOOK_HOST_TARGET` | `x86_64-unknown-linux-gnu` | +| `COOKBOOK_MAKE_JOBS` | CPU core count | +| `DESTDIR` | Alias for COOKBOOK_STAGE | +| `TARGET` | `x86_64-unknown-redox` | +| `GNU_TARGET` | `x86_64-redox` | + +## TUI (Terminal UI) + +Cub launches a ratatui-based TUI by default when run without a subcommand. +Use `--no-tui` / `-T` for direct CLI operation. + +### Views + +| View | Description | Key Bindings | +|------|-------------|-------------| +| **Search** | Search AUR by name/description | Type query, Enter to search | +| **Info** | Detailed package view | Shows deps, version, votes, description | +| **Install** | Install progress with log output | Shows command output in real-time | +| **Build** | Build progress for local recipes | Shows stage/progress indicators | +| **Query** | Browse locally installed packages | Arrows to navigate, Enter for details | + +### Global Keys + +| Key | Action | +|-----|--------| +| `q` / `Esc` | Quit TUI | +| `/` | Focus search bar | +| `Tab` | Cycle between views | +| `↑` `↓` | Navigate lists | +| `Enter` | Select / confirm | + +### Theme + +Red Bear color theme: +- Background: dark (terminal default) +- Accent: red (#CC0000) +- Text: white +- Selected: red highlight on white text +- Borders: gray + +## Configuration + +### Environment Variables + +| Variable | Default | Description | +|----------|---------|-------------| +| `CUB_BUR_REPO_URL` | `https://gitlab.redox-os.org/redox-os/bur.git` | BUR repository URL | +| `CUB_PKGAR_SECRET_KEY` | *(auto-detected)* | Path to pkgar secret key | +| `CUB_PKGAR_PUBKEY_DIR` | *(auto-detected)* | Directory containing public key | + +### Key Locations + +| Path | Purpose | +|------|---------| +| `~/.pkg/id_ed25519.toml` | Secret key (pkgar signing) | +| `/etc/pkg/id_ed25519.toml` | System secret key fallback | +| `/pkg/id_ed25519.toml` | System secret key fallback 2 | +| `~/.cub/config/` | Cub-specific configuration | + +## Recipe Format + +Cub generates standard Red Bear OS recipe.toml files compatible with the +`repo cook` command: + +```toml +[source] +git = "https://github.com/user/repo.git" +branch = "main" +rev = "abc123" + +[build] +template = "cargo" +dependencies = ["cargo", "pkg-config"] + +[package] +dependencies = ["relibc", "openssl3"] +version = "1.0.0-1" +description = "Example package converted from AUR" +``` + +### Template Detection + +Cub auto-detects the correct build template from PKGBUILD `build()` contents: + +| PKGBUILD pattern | recipe.toml template | +|---|---| +| `cargo build`, `cargo install` | `cargo` | +| `cmake` | `cmake` | +| `meson setup`, ` meson ` | `meson` | +| `./configure`, ` configure ` | `configure` | +| Other | `custom` | + +## Linuxism Detection + +During PKGBUILD conversion, cub detects Linux-specific patterns and issues +warnings for manual intervention: + +| Pattern | Warning | +|---------|---------| +| `systemctl` | systemctl not available on Redox | +| `/usr/lib/systemd` | Linux-specific paths | +| `systemd` as dependency | Dependency removed (unavailable) | +| `/proc` references | May require Redox-specific adaptation | + +## Build Recipe + +Cub is built as a standard Cargo workspace: + +```toml +# local/recipes/system/cub/recipe.toml +[source] +path = "source" + +[build] +template = "cargo" +cargopath = "cub-cli" + +[package] +dependencies = ["pkgutils"] +``` + +The recipe builds `cub-cli` which depends on `cub-lib` and optionally `cub-tui`. +The `default-members` of the workspace is `cub-cli` (the binary). + +## Protected Recipe + +Cub is listed as a **protected recipe** in `src/cook/fetch.rs` — it cannot be +re-fetched online. For current development, sources are pulled from local/sources/ forks; the legacy release archive `sources/redbear-0.1.0/` is from the original 0.1.0 snapshot. + +## Error Handling + +Cub uses an 11-variant `CubError` enum via `thiserror`: + +| Variant | Description | +|---------|-------------| +| `Io` | Filesystem errors | +| `TomlParse` | recipe.toml parse failures | +| `TomlSerialize` | recipe.toml serialization failures | +| `InvalidPkgbuild` | Malformed RBPKGBUILD | +| `BuildFailed` | `repo cook` or build failures | +| `PackageNotFound` | Missing package in repo/BUR | +| `Conversion` | PKGBUILD conversion errors | +| `Dependency` | Dependency resolution failures | +| `Aur` | AUR RPC errors (HTTP, parse, rate limit) | +| `Storage` | `~/.cub/` storage errors | +| `Network` | General network failures | +| `Sandbox` | Build sandbox errors | + +## Limitations + +1. **Build tools required**: `repo cook` requires the build toolchain + (cross-compiler, host tools) which is not yet available inside Red Bear OS. + Until build tools are ported, `cub build` (cooking) only works on build + hosts. Runtime-only operations (search, install, query, remove) work inside + Red Bear OS. + +2. **Single source support**: recipe.toml generation currently supports only one + primary source per recipe (AUR packages with multiple sources need manual + adjustment). + +3. **No binary repository**: cub currently fetches from AUR (source-based) and + BUR (Red Bear package recipes). There is no binary package repository — all + packages must be built from source. + +4. **AUR JSON parsing**: The AUR module uses a hand-written JSON parser to avoid + adding `serde_json` as a dependency. This works for the AUR RPC response + format but is less robust than `serde_json`. + +5. **TUI test coverage**: The `cub-tui` crate has no unit tests. Views are + rendering-only and verified via `cargo build`. + +## Future Work + +- Port build tools inside Red Bear OS to enable full cooking at runtime +- Add binary package repository support for pre-built packages +- Implement `serde_json` dependency for robust AUR JSON parsing +- Add TUI unit tests for view rendering +- Support multi-source PKGBUILDs in recipe.toml generation +- Add package signing verification on install +- Implement delta updates for large packages diff --git a/local/docs/DRIVER-MANAGER.md b/local/docs/DRIVER-MANAGER.md index 7b6ea003aa..5ac1c7bf52 100644 --- a/local/docs/DRIVER-MANAGER.md +++ b/local/docs/DRIVER-MANAGER.md @@ -12,7 +12,7 @@ and the actionable fix/improvement plan. `ab9de95c9`), CachyOS (`local/reference/cachyos/`). > **Historical material:** the v1.0 → v5.9 migration plan was archived at -> `local/docs/archived/DRIVER-MANAGER-MIGRATION-PLAN.md` (deleted 2026-07-27 — +> the v1.0-v5.9 migration history (removed in the 2026-07-27 consolidation; see `local/docs/SUPERSEDED-DOC-LOG.md`) (deleted 2026-07-27 — > see `local/docs/legacy-obsolete-2026-07-25/SUPERSEDED.md` audit log). > Round-by-round history lives in this document's "Per-fix summary" table and > in the git history of `local/recipes/system/driver-manager/source/`. @@ -860,8 +860,18 @@ three stale docs that had been left behind from earlier rounds. - **N22 — Stale-doc removal**: deleted `local/docs/BLUETOOTH-IMPLEMENTATION-PLAN.md`, `local/docs/CUB-PACKAGE-MANAGER.md`, - `local/docs/USB-VALIDATION-RUNBOOK.md` — three orphaned docs - with no references anywhere in the repo and last-modified + `local/docs/USB-VALIDATION-RUNBOOK.md` — three docs believed + orphaned. + **CORRECTION 2026-08-03:** the "no references anywhere in the repo" + premise was wrong for two of the three. `README.md` linked + CUB-PACKAGE-MANAGER.md from its Documentation list and names cub in + six places; BLUETOOTH-IMPLEMENTATION-PLAN.md was listed as a + first-class subsystem plan by `local/AGENTS.md`, `docs/README.md` and + `docs/07-RED-BEAR-OS-IMPLEMENTATION-PLAN.md`. Both have been restored + and their SUPERSEDED-DOC-LOG entries retracted; the claimed absorption + destinations did not exist. Only USB-VALIDATION-RUNBOOK.md was a real + supersession (into USB-IMPLEMENTATION-PLAN.md § 6.x) and stays removed. + Original note follows: last-modified Jul 10–14 (vs every other doc Jul 26–27). Backup tarball at `/tmp/opencode/stale-doc-backup-2026-07-27-round18.tar.gz`; audit trail recorded in `local/docs/SUPERSEDED-DOC-LOG.md` @@ -940,11 +950,11 @@ referencing absent binaries per "honest absence" policy). - `local/docs/DRIVER-MANAGER-CODE-AUDIT-2026-07-27.md` — Round-5 code-level audit (2 CRITICAL + 3 HIGH + ~10 MEDIUM + ~11 LOW issues; 2 CRITICAL + 3 HIGH fixed in Round 5; 6 test gaps deferred to next round). -- `local/docs/archived/DRIVER-MANAGER-MIGRATION-PLAN.md` — full v1.0 → v5.9 +- the v1.0-v5.9 migration history (removed in the 2026-07-27 consolidation; see `local/docs/SUPERSEDED-DOC-LOG.md`) — full v1.0 → v5.9 history (2861 lines, 182 KB). Read for round-by-round context. -- `local/docs/evidence/driver-manager/ASSESSMENT-2026-07-22.md` — v3.0 +- the Round-22 driver-manager assessment (removed in the 2026-07-27 consolidation; see `local/docs/SUPERSEDED-DOC-LOG.md`) — v3.0 assessment (findings B1–G10, services integration, QEMU gate). -- `local/docs/evidence/driver-manager/D5-AUDIT.md` — D5 feature-complete +- the D5 capability audit (removed in the 2026-07-27 consolidation; see `local/docs/SUPERSEDED-DOC-LOG.md`) — D5 feature-complete gate audit (capability matrix + test totals + audit output). - `local/docs/HARDWARE-VALIDATION-MATRIX.md` — D5 hardware validation matrix (operator-only gate). diff --git a/local/docs/HARDWARE-VALIDATION-MATRIX.md b/local/docs/HARDWARE-VALIDATION-MATRIX.md index eae28e8db7..085c7a2cae 100644 --- a/local/docs/HARDWARE-VALIDATION-MATRIX.md +++ b/local/docs/HARDWARE-VALIDATION-MATRIX.md @@ -36,7 +36,7 @@ | **SMP** | | | | | | x2APIC/SMP | ✅ | ✅ | [AVAILABLE] (Threadripper 128-thread + LG Gram 16-core hybrid) | Multi-core works. AMD Threadripper 128-thread bare-metal proven. Intel Arrow Lake-H 16-core hybrid (P/E/LP-E) expected. | | **Driver Manager (driver-manager vs pcid-spawner)** | | | | | -| D1 P0 capabilities (C1 dynids + C2 remove + C3 enable + C4 BAR) | ✅ | 🔲 | N/A (code) | Code complete; 52 tests pass; see `local/docs/evidence/driver-manager/D5-AUDIT.md` | +| D1 P0 capabilities (C1 dynids + C2 remove + C3 enable + C4 BAR) | ✅ | 🔲 | N/A (code) | Code complete; 52 tests pass; see the D5 capability audit (removed in the 2026-07-27 consolidation; see `local/docs/SUPERSEDED-DOC-LOG.md`) | | D1 P1 SpawnDecision + format coexistence + policy blacklist | ✅ | 🔲 | N/A (code) | `spawn_decision_gate()` consults env/CLI/blacklist; `convert_legacy` reads legacy pcid.d format | | D1 P1 PciQuirkFlags wired into spawn | ✅ | 🔲 | N/A (code) | `driver-manager/src/quirks.rs` consumes `redox-driver-sys`; NEED_FIRMWARE defers probe; NO_MSIX/NO_MSI/FORCE_LEGACY_IRQ signal intx-fallback via env; DISABLE_ACCEL signals accel-disable | | D1 P1 `/etc/driver-manager.d/` policy loader | ✅ | 🔲 | N/A (code) | `local/recipes/system/driver-manager/source/src/policy.rs`; reads TOML blacklist; consulted at probe | diff --git a/local/docs/IRQ-AND-LOWLEVEL-CONTROLLERS-ENHANCEMENT-PLAN.md b/local/docs/IRQ-AND-LOWLEVEL-CONTROLLERS-ENHANCEMENT-PLAN.md index 3d5ef82237..84ba4bfad7 100644 --- a/local/docs/IRQ-AND-LOWLEVEL-CONTROLLERS-ENHANCEMENT-PLAN.md +++ b/local/docs/IRQ-AND-LOWLEVEL-CONTROLLERS-ENHANCEMENT-PLAN.md @@ -4,7 +4,7 @@ > for IRQ/MSI/MSI-X/IOMMU runtime-proof sequencing. Its old `pcid-spawner` Wave 1 tasks are no > longer live: `pcid-spawner` was retired/removed in the driver-manager cutover (v5.0, 2026-07-24), > and those responsibilities now live in `local/docs/DRIVER-MANAGER.md` (current state). The -> archived `local/docs/archived/DRIVER-MANAGER-MIGRATION-PLAN.md` was deleted 2026-07-27 as part +> archived the v1.0-v5.9 migration history (removed in the 2026-07-27 consolidation; see `local/docs/SUPERSEDED-DOC-LOG.md`) was deleted 2026-07-27 as part > of the Round 9 doc cleanup; see `local/docs/legacy-obsolete-2026-07-25/SUPERSEDED.md` for the > audit log. Round-by-round history remains accessible via `git log` on `local/recipes/system/driver-manager/source/`. @@ -693,7 +693,7 @@ driver-manager cutover (v5.0, 2026-07-24). Treat this wave as: - **completed historical work** for `pcid` daemon hardening, - **obsoleted historical work** for `pcid-spawner`, and - **redistributed remaining orchestration work** to `local/docs/DRIVER-MANAGER.md` (current state) / - `local/docs/archived/DRIVER-MANAGER-MIGRATION-PLAN.md` (round-by-round history). + the v1.0-v5.9 migration history (removed in the 2026-07-27 consolidation; see `local/docs/SUPERSEDED-DOC-LOG.md`) (round-by-round history). **Primary targets** diff --git a/local/docs/SUPERSEDED-DOC-LOG.md b/local/docs/SUPERSEDED-DOC-LOG.md index 5a0d6d91a9..28a239f2cf 100644 --- a/local/docs/SUPERSEDED-DOC-LOG.md +++ b/local/docs/SUPERSEDED-DOC-LOG.md @@ -256,6 +256,6 @@ Three orphaned docs deleted from `local/docs/`. None referenced anywhere in the | File | Lines | Last modified | Reason | |------|-------|---------------|--------| -| `local/docs/BLUETOOTH-IMPLEMENTATION-PLAN.md` | 770 | 2026-07-14 06:52 | Round 15 audit flagged as **partial**; all Bluetooth work merged into `NETWORKING-IMPROVEMENT-PLAN.md` § 3.x (BT stack) and `NETWORKING-AND-DRIVERS-CODE-ASSESSMENT-2026-07-27.md` § BTR (Bluetooth kernel gaps). | -| `local/docs/CUB-PACKAGE-MANAGER.md` | 308 | 2026-07-12 07:45 | Round 15 audit noted cub's redesign completed 2026-05; content absorbed into `redbear-cub` recipe `README.md` and `NETWORKING-IMPROVEMENT-PLAN.md` § 8.2 (package-manager status). | -| `local/docs/USB-VALIDATION-RUNBOOK.md` | 130 | 2026-07-10 22:47 | Outdated by Round 16 USB P0-A3 CSZ cleanup commit `7cfed158` (stale TODO removed) and `USB-IMPLEMENTATION-PLAN.md` Round-17 update which absorbed the runbook's content as § 6.x test procedures. | +| `local/docs/BLUETOOTH-IMPLEMENTATION-PLAN.md` | 770 | 2026-07-14 06:52 | ~~Merged into `NETWORKING-IMPROVEMENT-PLAN.md` § 3.x and `NETWORKING-AND-DRIVERS-CODE-ASSESSMENT-2026-07-27.md` § BTR.~~ **RETRACTED 2026-08-03 — RESTORED.** The claimed merge did not happen: `NETWORKING-IMPROVEMENT-PLAN.md` contains 3 passing mentions of Bluetooth, not a 703-line plan. `local/AGENTS.md` and `docs/README.md` still list this as a first-class subsystem plan, and `AGENTS.md` § SUBSYSTEM PRIORITY forbids treating Bluetooth as secondary. Restored from `aa480f7ca3^`. | +| `local/docs/CUB-PACKAGE-MANAGER.md` | 308 | 2026-07-12 07:45 | ~~Absorbed into `redbear-cub` recipe `README.md` and `NETWORKING-IMPROVEMENT-PLAN.md` § 8.2.~~ **RETRACTED 2026-08-03 — RESTORED.** Neither destination exists: there is no cub `README.md` under `local/recipes/system/cub/`, and `NETWORKING-IMPROVEMENT-PLAN.md` has no package-manager section (its `cubic` matches are TCP congestion control). This left cub — a headline component named 6 times in `README.md` — with no documentation at all. Restored from `aa480f7ca3^`. | +| `local/docs/USB-VALIDATION-RUNBOOK.md` | 130 | 2026-07-10 22:47 | Outdated by Round 16 USB P0-A3 CSZ cleanup commit `7cfed158` and `USB-IMPLEMENTATION-PLAN.md` Round-17, which absorbed the runbook as § 6.x test procedures. **Verified 2026-08-03:** absorption is real (15 validation/procedure sections present), so this deletion stands. | diff --git a/local/docs/networking-validation-log.md b/local/docs/networking-validation-log.md index 7980fd5874..bff56cb184 100644 --- a/local/docs/networking-validation-log.md +++ b/local/docs/networking-validation-log.md @@ -59,7 +59,7 @@ Each run entry should follow this structure (Markdown): - [FIREWALL-VALIDATION-LOG.md](./FIREWALL-VALIDATION-LOG.md) — netfilter rule validation (specific to the `netfilter:` scheme, six scenario design documented in §Scenario A–F). -- [USB-VALIDATION-RUNBOOK.md](./USB-VALIDATION-RUNBOOK.md) — USB controller validation matrix and +- [USB-IMPLEMENTATION-PLAN.md](./USB-IMPLEMENTATION-PLAN.md) § 6.x — USB controller validation matrix and QEMU scripts. - [HARDWARE-VALIDATION-MATRIX.md](./HARDWARE-VALIDATION-MATRIX.md) — cross-component validation status (this log updates it).