RedBear-OS/local/docs/SCRIPT-BEHAVIOR-MATRIX.md

Red Bear OS Script Behavior Matrix

Purpose

This document centralizes what the main repository scripts do and do not handle under the Red Bear release fork model.

The goal is to remove guesswork from the sync/fetch/apply/build workflow.

SUPERSEDES: v5.x overlay model. As of v6.0, Red Bear OS is a full fork. The "release fork" in this document refers to Red Bear's owned code in local/sources/, local/recipes/, config/redbear-*.toml, and local/patches/<component>/ (Rule 2 external patches for big external projects). There is no overlay layer of apply-patches.sh-style symlinks between recipes/ and local/recipes/. See local/AGENTS.md "NO OVERLAY-STYLE PATCHES — SCOPED POLICY" for the two-rule model. Where this document references the historical apply-patches.sh script, that is legacy/archived behavior; the canonical build flow is local/scripts/build-redbear.sh <profile>, which never invokes apply-patches.sh.

Matrix

Script	Primary role	What it handles	What it does not guarantee
local/scripts/provision-release.sh	Refresh top-level upstream repo state	fetches upstream, reports conflict risk, rebases repo commits. Under v6.0 the "release fork reapplication" step is no longer needed because local/sources/, local/recipes/, and local/patches/<component>/ already live in the main repo (Rule 1 + Rule 2).	does not automatically solve every subsystem release fork conflict; does not by itself make upstream WIP recipes safe shipping inputs
local/scripts/apply-patches.sh	LEGACY / ARCHIVED — historical overlay only	under v5.x, applied build-system patches and relinked recipe patch symlinks; under v6.0 this is a no-op for in-tree components (Rule 1 direct edits) and is replaced by cookbook_apply_patches for big external projects (Rule 2). See local/AGENTS.md.	do not invoke during a v6.0 build. The local/scripts/build-redbear.sh <profile> canonical entry point never calls it.
local/scripts/build-redbear.sh	Canonical build entry point for Red Bear profiles	under v6.0 it does NOT call apply-patches.sh — the release fork is already in local/. It enforces: (1) local-over-WIP recipe priority, (2) overlay integrity verification, (3) submodule dirty-state stash, (4) firmware presence warning, (5) profile validation, (6) cookbook build if needed, (7) image build. --upstream triggers explicit source immutable archived for non-protected recipes.	does not guarantee every nested upstream source tree is fresh; does not replace explicit subsystem/runtime validation
scripts/fetch-all-sources.sh	Fetch mainline recipe source inputs for builds	downloads mainline/upstream recipe sources, reports status/preflight, and supports config-scoped fetches while leaving local release fork in place	does not mean fetched upstream WIP source is the durable shipping source of truth
local/scripts/fetch-sources.sh	Fetch mainline recipe sources for browsing and patching	when passed --upstream, fetches recipes/* source trees so the upstream-managed side is locally available for reading, editing, and patch preparation	does not decide whether upstream should replace the local release fork
local/scripts/build-redbear-wifictl-redox.sh	Build redbear-wifictl for the Redox target with the repo toolchain	prepends prefix/x86_64-unknown-redox/sysroot/bin to PATH and runs cargo build --target x86_64-unknown-redox in the redbear-wifictl crate	does not prove runtime Wi-Fi behavior; only closes the target-build environment gap for this crate
local/scripts/test-iwlwifi-driver-runtime.sh	Exercise the bounded Intel driver lifecycle inside a target runtime	validates bounded probe/prepare/init/activate/scan/connect/disconnect/retry surfaces for redbear-iwlwifi on a live target runtime	does not prove real AP association, packet flow, DHCP success over Wi-Fi, or end-to-end connectivity
local/scripts/test-wifi-control-runtime.sh	Exercise the bounded Wi-Fi control/profile lifecycle inside a target runtime	validates /scheme/wifictl control nodes, bounded connect/disconnect behavior, and profile-manager/runtime reporting surfaces on a live target runtime	does not prove real AP association or end-to-end connectivity
local/scripts/test-wifi-baremetal-runtime.sh	Exercise bounded Intel Wi-Fi runtime lifecycle on a target system	validates driver probe, control probe, bounded connect/disconnect, profile-manager start/stop via the wifi-open-bounded profile, Wi-Fi lifecycle reporting, and writes /tmp/redbear-phase5-wifi-capture.json on the target	does not prove real AP association, packet flow, DHCP success over Wi-Fi, or end-to-end hardware connectivity
local/scripts/test-wifi-passthrough-qemu.sh	Launch Red Bear with VFIO-passed Intel Wi-Fi hardware	boots a Red Bear guest with a passed-through Intel Wi-Fi PCI function, auto-runs the in-guest bounded Wi-Fi validation command, and can copy the packaged capture bundle back to a host-side file during --check	depends on host VFIO setup and still does not by itself guarantee real AP association or end-to-end Wi-Fi connectivity
local/scripts/test-bluetooth-runtime.sh	Compatibility guest entrypoint for the bounded Bluetooth Battery Level slice	runs the packaged redbear-bluetooth-battery-check helper inside a Redox guest or target runtime	does not run on the host and does not expand the Bluetooth support claim beyond the packaged checker’s bounded scope
local/scripts/test-bluetooth-qemu.sh	Launch or validate the bounded Bluetooth Battery Level slice in QEMU	boots redbear-bluetooth-experimental, auto-runs the packaged checker during --check, reruns it in one boot, and reruns it again after a clean reboot	does not by itself guarantee that the current QEMU proof passes; does not prove real controller bring-up, generic BLE/GATT maturity, write/notify support, or real hardware Bluetooth behavior
local/scripts/test-drm-display-runtime.sh	Run the bounded DRM/KMS display checker in a target runtime	invokes the packaged redbear-drm-display-check helper for AMD or Intel, proving scheme/card reachability, connector/mode enumeration, and bounded direct modeset proof over the Red Bear DRM ioctl surface when requested	does not prove render command submission, fence semantics, or hardware rendering
local/scripts/test-amd-gpu.sh	AMD wrapper for the bounded DRM/KMS display checker	runs test-drm-display-runtime.sh --vendor amd	still only display-path evidence
local/scripts/test-intel-gpu.sh	Intel wrapper for the bounded DRM/KMS display checker	runs test-drm-display-runtime.sh --vendor intel	still only display-path evidence
local/scripts/test-msix-qemu.sh	Bounded MSI-X proof in QEMU	validates that the current virtio-net guest path reaches MSI-X-capable interrupt delivery and emits normalized IRQ_DRIVER, IRQ_MODE, IRQ_REASON, and IRQ_LOG output for the bounded guest/runtime proof	does not prove broad hardware MSI-X reliability or per-device fallback behavior outside the bounded guest path
local/scripts/test-iommu-qemu.sh	Bounded IOMMU first-use proof in QEMU	validates guest-visible AMD-Vi initialization and bounded event/drain behavior through the current iommu runtime path	does not prove real-hardware interrupt remapping quality or full DMA-remapping correctness
local/scripts/test-xhci-irq-qemu.sh	Bounded xHCI interrupt-mode proof in QEMU	validates that the xHCI guest path reaches an interrupt-driven mode under the current bounded runtime checker and emits normalized IRQ_DRIVER, IRQ_MODE, IRQ_REASON, and IRQ_LOG output	does not prove full USB topology maturity or broad hardware interrupt robustness
local/scripts/test-lowlevel-controllers-qemu.sh	Aggregate bounded low-level controller proof wrapper	runs MSI-X, xHCI IRQ, IOMMU first-use, PS/2/serio, and monotonic timer proofs in one sequence, defaulting to redbear-mini while automatically upgrading only the IOMMU leg to redbear-full because that runtime currently ships /usr/bin/iommu; if the required redbear-full image is absent, that single IOMMU leg is explicitly skipped rather than aborting the rest of the bounded wrapper	does not replace the individual proof helpers and does not prove real-hardware controller quality
local/scripts/prepare-wifi-vfio.sh	Prepare or restore an Intel Wi-Fi PCI function for passthrough	binds a chosen PCI function to vfio-pci or restores it to a specified host driver	does not verify guest Wi-Fi functionality and must be used carefully on a host with a safe detachable target device
local/scripts/validate-wifi-vfio-host.sh	Check whether a host looks ready for Wi-Fi VFIO testing	validates PCI presence, current driver, UEFI firmware, Red Bear image presence, QEMU/expect availability, VFIO module state, and IOMMU group visibility; exits non-zero when blockers are found	does not bind devices or prove the guest Wi-Fi stack works
local/scripts/run-wifi-passthrough-validation.sh	End-to-end host-side passthrough validation wrapper	prepares VFIO, runs the packaged in-guest Wi-Fi validation path, captures the guest JSON artifact to the host, writes a host-side metadata sidecar, and restores the host driver afterwards	still depends on real VFIO/hardware support and does not itself guarantee end-to-end Wi-Fi connectivity
local/scripts/package-wifi-validation-artifacts.sh	Bundle Wi-Fi validation evidence into one archive	packages common capture/log artifacts from bare-metal or VFIO validation runs into a single tarball	does not create missing artifacts or validate their contents
local/scripts/summarize-wifi-validation-artifacts.sh	Summarize Wi-Fi validation evidence quickly	extracts key runtime signals from a capture JSON or packaged tarball for fast triage	does not replace full artifact review or prove runtime correctness
local/scripts/finalize-wifi-validation-run.sh	One-shot post-run Wi-Fi triage helper	runs the packaged analyzer on a capture JSON and then packages the chosen artifacts into a tarball	still depends on a real target run having produced the capture/artifacts first

The packaged companion command for those scripts is redbear-phase5-wifi-check, which performs the bounded in-target Wi-Fi lifecycle checks from inside the guest/runtime itself.

The packaged Bluetooth companion command is redbear-bluetooth-battery-check, which is intended to perform the bounded Bluetooth Battery Level checks from inside the guest/runtime itself, including repeated helper runs, daemon-restart coverage, failure-path honesty checks, and stale-state cleanup checks within the current slice boundary.

The packaged DRM display companion command is redbear-drm-display-check, which is intended to perform bounded DRM/KMS display-side checks from inside the guest/runtime itself. It now covers direct connector/mode enumeration and bounded direct modeset proof over the Red Bear DRM ioctl surface, and explicitly does not claim render or hardware-accelerated graphics completion.

The packaged evidence companion is redbear-phase5-wifi-capture, which collects the bounded driver, control, profile-manager, reporting, interface-listing, and scheme-state surfaces — plus lspci and active-profile contents — into a single JSON artifact.

The packaged link-oriented companion is redbear-phase5-wifi-link-check, which focuses on whether the target runtime is exposing interface/address/default-route signals in addition to the bounded Wi-Fi lifecycle state.

For Redox-target Rust builds of Wi-Fi components such as redbear-wifictl, a missing x86_64-unknown-redox-gcc on PATH should first be treated as a host toolchain/path issue if the repo already contains prefix/x86_64-unknown-redox/sysroot/bin/x86_64-unknown-redox-gcc.

Policy Mapping

Resilience / offline-first package sourcing

Default Red Bear behavior is local-first:

• use locally available package/source trees and release fork state for normal builds,
• treat upstream immutable archived as an explicit operator action only (--upstream, dedicated fetch/sync),
• do not fail policy-level expectations just because upstream network access is temporarily broken.

This is required so builds and recovery workflows remain operable during upstream outages or connectivity failures.

Upstream sync

Use local/scripts/provision-release.sh when the goal is to immutable archived the top-level upstream Redox base.

This is a repository sync operation, not a guarantee that every local subsystem release fork is already rebased cleanly.

Overlay reapplication

Use local/scripts/apply-patches.sh when the goal is to reconstruct Red Bear’s release fork on top of a fresh upstream tree.

This is the core durable-state recovery path.

Build execution

Use local/scripts/build-redbear.sh when the goal is to build a tracked Red Bear profile from the current upstream base plus local release fork. Add --upstream only when you explicitly want Redox/upstream recipe sources immutable archived during that build.

Source immutable archived

Use scripts/fetch-all-sources.sh and local/scripts/fetch-sources.sh --upstream when the goal is to immutable archived recipe source inputs, but do not confuse fetched upstream WIP source with a trusted shipping source.

WIP Rule in Script Terms

If a subsystem is still upstream WIP, the scripts should be interpreted this way:

• fetching upstream WIP source is allowed and useful through the explicit upstream fetch commands or --upstream where a wrapper requires it,
• syncing upstream WIP source is allowed and useful through the explicit upstream sync command,
• but shipping decisions should still prefer the local release fork until upstream promotion and reevaluation happen.

That means “script fetched it successfully” is not the same as “Red Bear should now ship upstream’s WIP version directly.”