Documents 8 concrete improvements to build-redbear.sh and the cookbook
tool, derived from the redbear-mini boot crash debug session:
1. Trap-based stash-and-restore for ALL fork sources (eliminates the
'where did my edits go?' pain)
2. Source content-hashing to replace mtime-only cache invalidation
3. Cookbook binary freshness check (currently existence-only)
4. Strict-by-default uncommitted-edit gate
5. Stash-all-forks consistency
6. Failure-cleanup trap with diagnostics
7. Pre-cook offline/upstream consistency
8. Cookbook protection against out-of-band invocations
Each improvement has a file:line location, implementation sketch,
and impact/complexity rating. Implementation order suggested.
Problem motivation: the user has repeatedly hit silent stash-loss,
stale cookbook binaries, and mtime-based cache staleness while
debugging kernel/relibc/base forks. The build pipeline should
make these mistakes impossible, not require users to remember
workarounds.
Documents the project-wide rule that Red Bear OS local forks are the
complete, authoritative source of truth for every component they cover.
Key points:
- A fork that delegates to upstream/crates.io is not a fork — it's a wrapper.
- Missing fork functionality is implemented in the fork, not papered over.
- Path deps + [patch.crates-io] everywhere; no version strings for forks.
- Adapt to upstream at the same pace — never pin back.
Adds a cross-reference from local/AGENTS.md DESIGN PRINCIPLE section.
Updated desktop/GPU section: all code fixes complete for both
VirGL and Intel GPU drivers. Qt6 Wayland crash fixed, SDDM wired,
KWin builds, Mesa virgl builds.
Next phase: runtime validation on QEMU virtio-vga-gl and real
Intel hardware.
Comprehensive documentation of the current networking stack state
including architecture diagram, transport/network/firewall/virtual
device/traffic control/monitoring/management feature checklists,
known limitations, and testing status.
Generated from 66 implementation rounds across the netstack codebase.
Removed archived audit snapshots and superseded plans:
- BOOT-PROCESS-* (3 audit files from 2026-05)
- COMPREHENSIVE-FIX-AND-IMPROVEMENT + FINAL (superseded by IMPROVEMENT-PLAN)
- DEVICE-INIT, GRAPHICAL-BOOT, GREETER-LOGIN (old assessments)
- IOMMU-SPEC, SCHEDULER-REVIEW, BUILD-TOOLS, VFAT, ZSH (superseded)
Active plans remain in local/docs/. Archived dir now has 10 files.
Removed from archived/:
- USB v1/v2 (superseded by active v3 plan)
- GRUB, KERNEL-IPC, RELIBC-IPC, SCRIPT-BEHAVIOR (duplicates of active plans)
- BOOT-PROCESS-AUDIT, COMPREHENSIVE-DRIVER-AUDIT (outdated 2026-05 snapshots)
- C7-STATUS, 0.2.5-GRAPHICS, CHANGELOG-DRIVER, PROFILE-MATRIX (obsolete status docs)
Active copies remain in local/docs/ for all plans.
WIFI-IMPLEMENTATION-PLAN: iwlwifi driver complete (3,368 LOC).
MVM, Minstrel, thermal, WoWLAN, TLV, power mgmt all done.
Hardware validation pending.
WAYLAND-IMPLEMENTATION-PLAN: Wayland subsystem builds.
Qt6 Wayland, Mesa EGL+GBM+GLES2, KWin building.
Compositor validation pending.
IMPROVEMENT-PLAN already marked resolved (38/38 done).
MASTER plan updated earlier with status tables.
Three resolved plans now marked as historical records with
resolution banners. Plans retained for context — not deleted
per project policy.
All quality audit items from 2026-07-07 have been verified or
implemented. P0 (6 items), P1 (8 items), P2 (8 items),
P3 (5 items), P4+ (9 items) all done. Total 38/38 (100%).
Remaining Section 6 items marked done:
- 6.3 rate scaling, 6.4 5/6GHz scan, 6.5 power mgmt, 6.6 AMPDU
- 6.7 wifictl unwrap audit: all .unwrap() in #[cfg(test)]
- 6.8 linux-kpi transmute audit: verified
- 6.9 linux-kpi unsafe count: 273 FFI-bound, acceptable technical debt
IMPROVEMENT-PLAN now serves as a historical record of the audit
and remediation conducted 2026-07-07 through 2026-07-08.
Verified all P0-P2 items complete (2026-07-08 review).
Linux 7.1 reference at local/reference/linux-7.1/ confirmed at
version 7.1.0 (Makefile: VERSION=7, PATCHLEVEL=1, SUBLEVEL=0).
P3 status: 9/14 items done or deferred.
All directly-implementable plan items exhausted. Remaining items
require operator intervention (upstream fork sync) or subsystem
expertise (USB/Wi-Fi/kernel drivers).
SYSCALL-MIGRATION-PLAN.md:
- Detailed analysis of upstream 0.9.0 BREAKING changes (FD reservation refactor,
removed syscalls, new *_into variants)
- Complete consumer impact catalog: 2 bootstrap call sites, 7 kernel/relibc
constant references, 26 recipes (no impact)
- 5-phase migration plan: bootstrap→kernel→relibc→syscall sync→full build
- Risk assessment with rollback procedure
- Clear migration table: old API → new API for each deprecated function/constant
- Execution order with time estimates (~1-2 days total)
NETWORKING-IMPROVEMENT-PLAN.md:
- Phase 0 updated from 'workstreams' to COMPLETE with verified upstream commits
- Added fork state table (8 components, HEADs, upstream HEADs, gaps)
- All 7 required upstream commits verified present in local forks
- syscall flagged as BREAKING (removed syscalls, FD reservation refactor)
IMPLEMENTATION-MASTER-PLAN.md:
- Added section 11: Upstream Sync Status (2026-07-07)
- Fork state table with gap analysis per component
- Key upstream changes to track: syscall breaking refactor, kernel NUMA, libredox fcntl
- Renumbered sections 11-15
Findings:
- All 8 forks at +rb0.3.0 with Red Bear changes intact
- Gaps are minor (2-3 commits each) except syscall (BREAKING)
- UPSTREAM-SYNC-PROCEDURE.md (770 lines) is comprehensive and current
- No stale plan parts to remove — all docs are active and referenced
Update the master implementation plan to reference the new
IMPROVEMENT-PLAN.md which contains the comprehensive quality
gaps found during the 2026-07-07 USB/Wi-Fi/Bluetooth audits.
Key changes:
- Added IMPROVEMENT-PLAN.md to the authoritative plans table
- Added §10 Quality Gaps section with USB/Wi-Fi/Bluetooth audit findings
- Updated §11 Execution Priority with P0/P1/P2/P3 tiers
- Cross-references Linux 7.1 source files for each improvement task
- The IMPROVEMENT-PLAN.md has detailed file:line references for every gap
This establishes the two-plan architecture:
- IMPLEMENTATION-MASTER-PLAN.md: feature work, P0 from build
- IMPROVEMENT-PLAN.md: quality work, P0 from safety
No new repositories or submodules created.
v3 USB-IMPLEMENTATION-PLAN supersedes v2 (archived). Comprehensive
audit-driven roadmap with 9 phases (P1–P9) to make USB a first-class
citizen in Red Bear OS:
P1: Trait unification (all 4 controllers implement UsbHostController)
+ panic hardening (usbscsid 0 panics, xhcid <20 unwraps)
+ remove 3 empty stubs (usbaudiod, acmd, ecmd)
P2: xHCI core — 51-quirk table, HCCPARAMS2 parsing, 36-code error
recovery (babble, transaction error, stall, split)
P3: Hub driver — full enumeration (wHubDelay, power timing, USB 3 SS)
+ interrupt-driven change detection + port LED
P4: Storage — UAS protocol, multi-LUN, SYNCHRONIZE_CACHE, UNMAP, mass-storage
quirks applied at runtime
P5: HID — report descriptor parser, usage→evdev mapping, LED sync, quirks,
multi-touch
P6: Class driver completeness — CDC ACM, CDC NCM, USB Audio, USB-serial
(FTDI/CP210x/PL2303/CH341), compliance test driver
P7: Power management — USB 2.0 LPM, USB 3.0 U1/U2/U3, runtime PM autosuspend
P8: Validation — hardware matrix ≥10 rows + 6 new QEMU scripts
+ error-injection tests
P9: Modern USB scope ADR (host-only; already written in v2 §12)
Linux 7.1 is the implementation of excellence — every feature has a
concrete cross-reference (file:line) and a 'port line-by-line' strategy
when implementation detail is in doubt.
USB-VALIDATION-RUNBOOK v3 replaces v2 (archived): test matrix with
per-phase exit gates, operator runbook for failures.
Stale items cleared:
- v2 active plan archived as USB-IMPLEMENTATION-PLAN-v2-2026-07.md
- v2 active runbook archived as USB-VALIDATION-RUNBOOK-2026-07.md
- archived/README.md supersession table extended
P1 USB 3.x hub correctness verified against codebase:
- packet-size handling (bytes vs shift exponent) in baseline
- HubDescriptorV2/V3 separate reading paths in usbhubd
- Slot context hub bit + port count correctly set
- SET_HUB_DEPTH issued for USB 3 hubs
- TTT not applicable to USB 3 (TT is USB 2.0 split-transaction)
- TODOs about interface_desc/alternate_setting on USB 3 hubs
are safe — passing None matches upstream behavior
P5 Modern USB Scope Decision (ADR):
- Host-only for foreseeable future
- Explicitly excluded: device mode, OTG, USB-C PD, alt-modes,
USB4, Thunderbolt, xHCI DbC
- Reviewed per release branch cut
Update all active (non-archived) doc references from Linux 7.0 to
Linux 7.1. The reference tree at local/reference/linux-7.1/ already
exists; the docs were lagging behind.
Files touched:
AGENTS.md — reference path and git fetch command
CHANGELOG.md — device ID source note
local/docs/IMPLEMENTATION-MASTER-PLAN.md — source-of-truth path x2
local/docs/CPU-DMA-IRQ-MSI-SCHEDULER-FIX-PLAN.md — source-of-truth
local/docs/DRM-MODERNIZATION-EXECUTION-PLAN.md — quirk extraction note
local/docs/QUIRKS-AUDIT.md — storage quirk table note
local/docs/QUIRKS-SYSTEM.md — storage quirk mining note
Archived docs (local/docs/archived/*) are preserved as-is — they
represent historical state and are not the planning authority.
Update §5 phases table: P0-A1 ✅ committed (base fork cbd40e0d, parent
a2998c2d).
Update §6 validation table: test-xhci-irq-qemu.sh now greps for actual
reactor log lines (not fictitious strings).
Update §7 durability log: base fork now has two USB commits (one from
P0-A1), not one. The "first USB-focused commit since dd08b76" is
now cbd40e0d.
Add §11 — implementation handoff appendix with per-phase concrete
targets: upstream commit SHAs, files to touch per phase, git-landing
rules, validation scripts to write, and dependency graph (P0-B2 depends
on P0-B1; P0-A2 through P0-A4 are independent of B; P0-B1 is unblocked).
Replace v1 (now archived/USB-IMPLEMENTATION-PLAN-v1-2026-04.md) with a
comprehensive v2 that re-audits every daemon against local/sources/base/
HEAD, aligns with Redox 0.x USB HEAD (Jan-Jul 2026), and reorganizes
phases around bare-metal correctness gaps.
Key v1→v2 corrections:
- xHCI interrupts are *not* restored in production (main.rs:141 hardcodes
Polling). This was the biggest v1 overstatement. P0-A1 now fixes it.
- uhcid/ohcid are 35-line stubs, not "ownership-grade". P0-B2 gives them
real enumeration over usb-core.
- ehcid does not auto-spawn class drivers. P0-B1 adds that.
- The base fork carries only one USB commit. The 88-fix claim lived in
patch carriers that path-sourced recipes don't apply. v2 records this
honestly and recommends per-feature commits on submodule/base.
Also:
- USB-VALIDATION-RUNBOOK.md restored from archived/ (operationally current).
- local/AGENTS.md: operator override allowing agents to create submodules
when really necessary (2026-07-07), with a 4-point necessity test.
- archived/README.md supersession table updated with v1 plan and XHCID plan.
Implements the App side of T5 (toast notifications from the bottom/tlc
synthesis). render_toast() overlay can be wired in a follow-up pass.
- App.toast: Option<String> field
- App.toast_expires: Option<Instant> field
- App.flash_toast(msg): sets toast with 3s auto-dismiss
- App.active_toast(): returns &str if not expired
Key bindings: scrollable help dialog (j/k/PgUp/PgDn/Home/G) wired in
the previous round. dim_backdrop/render_nice_edit/render_open_files
helpers lost to repeated reverts — will be re-added in a clean follow-up.
- Update AGENTS.md single-repo rule to explicitly forbid creating any new
Gitea repositories and to require deleting per-component repos.
- Change version suffix policy from pre-release -rb to build-metadata +rb
in AGENTS.md, sync-versions.sh, apply-rb-suffix.sh, verify-fork-versions.sh.
- Update migration instructions to push to existing submodule/<component>
branches inside RedBear-OS, not create new repos.
- Update BUILD-SYSTEM-IMPROVEMENTS.md and SLEEP-IMPLEMENTATION-PLAN.md to
reference submodule/* branches instead of defunct per-component repos.
- Fix delete-per-component-repos.sh example to use a real historical repo.
Replace all non-canonical build invocations (bare 'make all/live
CONFIG_NAME=', 'scripts/build-iso.sh', 'scripts/run.sh') with the
canonical './local/scripts/build-redbear.sh' wrapper.
Updated: AGENTS.md, local/AGENTS.md, README.md, docs/README.md,
docs/06-BUILD-SYSTEM-SETUP.md, and 6 active local/docs plan files.
Archived docs and frozen boot-logs left as-is (historical evidence).
Records actual recipes bumped in 0.2.5 on 2026-07-02:
- Qt stack 6.8.2/6.11.0a1 -> 6.11.1 (all 6 sub-recipes, verified BLAKE3)
- Wayland/DRM/Input/expat/seatd to upstream latest stable (8 recipes,
verified BLAKE3)
- KWin 6.3.4 -> 6.7.2 + kdecoration 6.3.4 -> 6.7.2 + konsole 24.08.3
-> 26.04.3
Plus structural fix: created the missing qtshadertools recipe so the
qtdeclarative dependency chain resolves.
Documents what was deliberately NOT done:
- KF6 6.10 -> 6.27.0: 38 frameworks, 17-minor delta. Per AGENTS.md
patch-governance, no commit that bumps recipe.toml URLs without
first rebasing the local patches can be made honestly. Rebase
work (17-minor * 38 recipes) is multi-day and recorded as open.
- Mesa 24.0.8 -> 26.1.4: blocked on redox-os/mesa fork rebase
(0.3.0 work).
Includes the rebase order for the next session that plans to run
'make all CONFIG_NAME=redbear-full' against the bumped pins.
Plan-only artifact for the 0.2.5 graphics path. No recipe.toml changes,
no build attempted. Documents:
- Per-recipe upstream-latest-stable versions resolved via download.qt.io,
download.kde.org, gitlab.freedesktop.org, and git ls-remote on
invent.kde.org projects (no human guessing).
- Pre-build actions required (re-pull, re-blake3, validate-patches).
- Patch surface to re-evaluate across 17-minor KF6 bump and 1-minor
KWin bump.
- Mesa fork situation (24.0.8 vs 26.1.4): freeze at current fork,
rebase is 0.3.0 work.
- Freeze-when-green criteria for cutting 0.2.5.
- Out-of-scope items (Plasma workspace, real libepoxy, etc.).
Decisions in this plan are reversible; no recipe.toml field has been
modified. All work-in-progress from prior session is preserved as
uncommitted files in the working tree.
Prepend an UPDATE block at the top of the plan document recording:
- The 8 commits that landed Phase 0c (futex sharding, per-CPU run
queues, vruntime, work stealing, load balancing, cache-affine,
initial placement, NUMA topology, proc scheme handles, fadt fix)
- The upstream-redox kernel audit finding (upstream has none of
these features; local fork is sole implementation)
- A plan-vs-actual state table showing which claimed 'missing'
features are now present
- The kernel-side Phase 0c is complete; remaining work is
relibc-side (Phase 0e) and futex-REQUEUE/PI/robust (Phase 1)
The detailed §1–§9 analysis is preserved unchanged as historical
record. The status column 'Missing' in §1 should be re-read as
'now present in local kernel fork, pending relibc userspace wiring.'
cargo check now exits 0 with 0 errors in the local kernel fork.
vasilito
Red Bear Build System