diff --git a/local/docs/DRIVER-MANAGER.md b/local/docs/DRIVER-MANAGER.md index f11867f64a..145f32caf9 100644 --- a/local/docs/DRIVER-MANAGER.md +++ b/local/docs/DRIVER-MANAGER.md @@ -793,6 +793,38 @@ left as known follow-ups: done in parallel by other agents; no new source change is needed for this round. +### 5.10.3 Round-4 (N13–N15) summary + +N13–N15 closed three stale-documentation and stale-comment gaps +that the earlier rounds left as known follow-ups: + +- **N13 — `policy.rs` module docstring update**: the module-level + docstring documented only the blacklist surface ("extracts a + blacklist") and carried a stale "before v1.4 the policy was + dormant" reference. Round-1 and Round-2 added three more + surfaces (DriverOptions, AutoloadList, InitfsManifest) and + activated the redbear-driver-policy package. The docstring now + documents all four surfaces, the per-surface semantics, the + SIGHUP `replace()` contract, and the `/etc/driver-manager.d/disabled` + kill-switch — matching the actual code path. +- **N14 — Stale source comment cleanup**: the only remaining + "previously marked as dormant" reference in the + driver-manager source was a one-line comment in `main.rs` + describing the policy-surface summary log. The comment is + updated to describe the current state (the four counts confirm + the redbear-driver-policy package's curated config files are + wired into the manager). The redbear-driver-policy package + README's dormant-Phase-C3 historical note is also simplified + to a single "the package is the canonical source of policy + data from the 2026-07-23 cutover" sentence. +- **N15 — Stale-doc inventory**: the local/docs/ tree is current. + The prior doc-consolidation (Round 5 of the 2026-07-27 cycle, + recorded in `local/docs/SUPERSEDED-DOC-LOG.md`) removed all the + known-stale docs. The 3D-DESKTOP-COMPREHENSIVE-PLAN explicitly + designates the two remaining NETWORKING assessment files as + "operator-authored authoritative docs... left as-is", so this + round does not delete them. + **Test count:** 164 (driver-manager) + 35 (redox-driver-core unit) + 5 (dynid integration) = 204, all green. **Audit gate:** 46 files scanned, 0 violations. diff --git a/local/recipes/system/driver-manager/source/src/main.rs b/local/recipes/system/driver-manager/source/src/main.rs index 8c76917d28..6fb79a2fea 100644 --- a/local/recipes/system/driver-manager/source/src/main.rs +++ b/local/recipes/system/driver-manager/source/src/main.rs @@ -452,8 +452,8 @@ fn main() { // N4: log a structured summary of the active policy surface so // operators can verify the policy is live at a glance. The four - // booleans encode the "everything is wired" invariant that - // redbear-driver-policy README previously marked as dormant. + // surface counts confirm the redbear-driver-policy package's + // curated config files are wired into the manager. log::info!( "policy-surface: disabled={} blacklist={} options={} \ autoload={} initfs_manifest={} (N4 active)", diff --git a/local/recipes/system/driver-manager/source/src/policy.rs b/local/recipes/system/driver-manager/source/src/policy.rs index 044848e674..44ca7a8871 100644 --- a/local/recipes/system/driver-manager/source/src/policy.rs +++ b/local/recipes/system/driver-manager/source/src/policy.rs @@ -1,13 +1,36 @@ //! `/etc/driver-manager.d/` policy loader. //! -//! Reads TOML files from the manager's policy directory at startup and -//! extracts a blacklist. Each entry's `[[blacklist]]` table is matched -//! against a `DriverConfig.name` or a `command[0]` value (basename) at -//! probe time. +//! Reads TOML files from the manager's policy directory at startup +//! and extracts four policy surfaces: +//! +//! 1. `[[blacklist]]` — driver-name blacklist. Each entry is matched +//! against a `DriverConfig.name` or a `command[0]` value (basename) +//! at probe time. Used to suppress drivers that conflict with +//! hardware quirks or operator policy. +//! 2. `[[options]]` — per-driver parameter overrides (modprobe.d +//! equivalent). Each `(name, value)` pair is emitted to the spawned +//! child as `REDBEAR_DRIVER_PARAM_=`. The driver +//! daemon interprets the param per its own schema. +//! 3. `autoload.d/*.conf` — modules-load.d equivalent. Each file +//! declares a `module = ""` line; the initfs manager +//! pre-probes listed modules early in the boot sequence so that +//! dependent drivers (audio, GPU submission threads) find the +//! relevant scheme/devnode available before their probe runs. +//! 4. `initfs.manifest` — boot-stage driver ordering for initfs mode. +//! The `[kms] / [block] / [filesystems] / [boot]` sections drive the +//! enumeration order; each stage is one `enumerate()` pass with a +//! final fallback pass for any driver not in the manifest. +//! +//! Each surface has its own `Shared` (Arc>) that +//! the manager can consult under read lock and that the SIGHUP worker +//! can `replace()` under write lock. A failure on one surface during +//! reload does not block the others. //! //! The companion package `local/recipes/system/redbear-driver-policy/` -//! ships the curated config files. This loader makes the manager actually -//! read them; before v1.4 the policy was dormant. +//! ships the curated config files. The `redbear-driver-policy` package +//! is the active source of policy data; the `/etc/driver-manager.d/disabled` +//! file is honoured as a kill-switch that suppresses all four surfaces +//! in observe-only mode for live A/B comparison. extern crate alloc; diff --git a/local/recipes/system/redbear-driver-policy/source/policy/README.md b/local/recipes/system/redbear-driver-policy/source/policy/README.md index 345b217863..1da4673b38 100644 --- a/local/recipes/system/redbear-driver-policy/source/policy/README.md +++ b/local/recipes/system/redbear-driver-policy/source/policy/README.md @@ -2,9 +2,9 @@ Curated driver-policy file set for the Red Bear OS driver-manager. This package is **active**: its contents are loaded by `driver-manager` at -startup (see `local/docs/DRIVER-MANAGER.md` § 5 for the activation -context; historical "dormant until Phase C3" status was resolved at -the 2026-07-23 operator-ratified cutover). +startup (see `local/docs/DRIVER-MANAGER.md` for the activation +context). The package was the canonical source of policy data +from the 2026-07-23 operator-ratified cutover onward. Files staged to `/etc/driver-manager.d/` once the package is installed: