pmaxhogan
diff --git a/‎Cargo.lock‎
Lines changed: 1 addition & 0 deletions b/‎Cargo.lock‎
Lines changed: 1 addition & 0 deletions
diff --git a/‎Cargo.toml‎
Lines changed: 5 additions & 0 deletions b/‎Cargo.toml‎
Lines changed: 5 additions & 0 deletions
diff --git a/‎crates/driven-core/Cargo.toml‎
Lines changed: 7 additions & 0 deletions b/‎crates/driven-core/Cargo.toml‎
Lines changed: 7 additions & 0 deletions
diff --git a/‎crates/driven-core/src/executor.rs‎
Lines changed: 34 additions & 1 deletion b/‎crates/driven-core/src/executor.rs‎
Lines changed: 34 additions & 1 deletion
diff --git a/‎crates/driven-core/src/lib.rs‎
Lines changed: 1 addition & 0 deletions b/‎crates/driven-core/src/lib.rs‎
Lines changed: 1 addition & 0 deletions
diff --git a/‎crates/driven-core/src/orchestrator.rs‎
Lines changed: 115 additions & 0 deletions b/‎crates/driven-core/src/orchestrator.rs‎
Lines changed: 115 additions & 0 deletions
@@ -120,6 +120,11 @@ clap = { version = "4", features = ["derive", "env"] }
 # reproducible cross-platform build; matches the app's no-native-deps posture).
 tar = "0.4"
 flate2 = { version = "1", default-features = false, features = ["rust_backend"] }
+# Raw POSIX calls the std library does not expose: `ioprio_set` / `setpriority`
+# for the below-normal backup-thread priority (`driven_core::priority`), and the
+# chaos harness's fault injection. Pulled per-crate under a `cfg(unix)` target
+# section - the Windows backends call kernel32 directly.
+libc = "0.2"
 
 [profile.dev]
 opt-level = 1
 
@@ -76,6 +76,13 @@ md5 = { workspace = true }
 tar = { workspace = true }
 flate2 = { workspace = true }
 
+# Below-normal CPU + I/O priority for backup threads (SPEC s22 `io_priority`,
+# `driven_core::priority`). Unix only: Linux needs the `ioprio_set` syscall
+# number and `setpriority`, macOS needs `setpriority` for the Darwin background
+# band. The Windows backend calls kernel32 directly, so no dependency there.
+[target.'cfg(unix)'.dependencies]
+libc = { workspace = true }
+
 [dev-dependencies]
 # `test-util` enables `#[tokio::test(start_paused = true)]` so the orchestrator
 # run-loop scheduled-tick test drives `tokio::time::interval` on virtual time
 
@@ -889,6 +889,14 @@ pub struct DefaultExecutor {
     /// `ensure_folder` per component instead of racing duplicate
     /// search+create calls (which manifest as duplicate folders on Drive).
     parent_walk: tokio::sync::Mutex<()>,
+    /// The live backup-work priority (SPEC s22 `io_priority`), written by the
+    /// orchestrator on every settings change when the app assembly wires the
+    /// SAME cell into both (via [`Self::with_priority_cell`]). Read at each
+    /// blocking-work site rather than captured once, so a settings save applies
+    /// without a restart. Defaults to a private cell holding
+    /// [`WorkPriority::Normal`], which is why every test and the chaos harness
+    /// run at normal priority unless they opt in.
+    priority: crate::priority::PriorityCell,
     /// Cooperative "stop dispatching new ops" flag (DESIGN s5.7 manual pause).
     /// Written by [`Executor::set_paused`], read by the `execute` dispatch loop
     /// before it starts each op. It is a dispatch gate, not a cancel: ops
@@ -975,6 +983,7 @@ impl DefaultExecutor {
             throughput: None,
             mem_gauge: None,
             latency: None,
+            priority: crate::priority::PriorityCell::default(),
             parent_dirs: std::sync::Mutex::new(HashMap::new()),
             parent_walk: tokio::sync::Mutex::new(()),
             paused: AtomicBool::new(false),
@@ -1021,6 +1030,22 @@ impl DefaultExecutor {
         self
     }
 
+    /// Share the backup-work priority cell (SPEC s22 `io_priority`) with the
+    /// orchestrator.
+    ///
+    /// Pass the SAME [`PriorityCell`](crate::priority::PriorityCell) given to
+    /// [`SyncOrchestrator::with_priority_cell`](crate::orchestrator::SyncOrchestrator::with_priority_cell),
+    /// the same one-cell-into-two-consumers wiring as
+    /// [`Self::with_upload_pool`]: the orchestrator writes it when settings
+    /// change, this executor reads it when it starts blocking work. Every other
+    /// construction path keeps a private cell pinned at
+    /// [`WorkPriority`](crate::priority::WorkPriority)`::Normal`.
+    #[must_use]
+    pub fn with_priority_cell(mut self, priority: crate::priority::PriorityCell) -> Self {
+        self.priority = priority;
+        self
+    }
+
     /// Resolve the crypto decision for one source (M5 GA-blocking surface).
     ///
     /// Consults the injected [`CryptoProvider`]; a `None` provider means every
@@ -1667,7 +1692,15 @@ impl DefaultExecutor {
                 )
             })
             .collect();
-        let built = match tokio::task::spawn_blocking(move || {
+        // SPEC s22 `io_priority`: this closure reads every member off disk and
+        // gzips it, so it is the executor's one genuinely blocking, genuinely
+        // heavy section - and being a `spawn_blocking` closure with no `.await`
+        // inside, it is somewhere a per-thread priority guard is actually SOUND
+        // (see `crate::priority` for why that distinction is load-bearing). The
+        // level is read HERE, per bundle, so a settings change applies to the
+        // next bundle without a restart.
+        let priority = self.priority.get();
+        let built = match crate::priority::spawn_blocking(priority, move || {
             crate::bundle::build_bundle(&inputs, crate::planner::BUNDLE_MAX_BYTES_CEILING)
         })
         .await
 
@@ -29,6 +29,7 @@ pub mod network;
 pub mod orchestrator;
 pub mod pacer;
 pub mod planner;
+pub mod priority;
 pub mod scanner;
 pub mod state;
 pub mod telemetry;
 
@@ -58,6 +58,7 @@ use crate::executor::{Executor, OpOutcome};
 use crate::hooks::{CommandRunner, HookKind, NoopCommandRunner};
 use crate::network::{NetworkProbe, NetworkState, ServiceHealth, ServiceName};
 use crate::pacer::{Pacer, PacerCeilings};
+use crate::priority::{PriorityCell, WorkPriority};
 use crate::state::{ActivityLevel, NewActivity, SourceRow, StateRepo};
 use crate::time::Clock;
 use crate::types::{
@@ -209,6 +210,15 @@ pub struct OrchestratorConfig {
     /// kill-switch - the pool stays FIXED at
     /// [`default_concurrent_uploads`](Self::default_concurrent_uploads).
     pub adaptive_parallelism_enabled: bool,
+    /// How far below normal the threads doing backup work run (SPEC s22
+    /// `global.io_priority`), so Driven yields to whatever the user has in the
+    /// foreground.
+    ///
+    /// [`Orchestrator::reconfigure`] publishes this into the
+    /// [`PriorityCell`](crate::priority::PriorityCell) shared with the
+    /// executor, so a settings save applies to work that STARTS after it; work
+    /// already in flight keeps the level it began with.
+    pub io_priority: WorkPriority,
 }
 
 /// What Driven does on a metered network when
@@ -258,6 +268,11 @@ impl Default for OrchestratorConfig {
             metered_bandwidth_cap_mbps: None,
             default_concurrent_uploads: None,
             adaptive_parallelism_enabled: true,
+            // Normal, not the settings seed of `low`: the code default is what
+            // a test / the chaos harness / a settings-load failure gets, and
+            // "behave exactly as before" is the right fallback there. The
+            // persisted setting is what demotes a real install.
+            io_priority: WorkPriority::Normal,
         }
     }
 }
@@ -428,6 +443,17 @@ pub struct SyncOrchestrator {
     /// network goes on / off metered. `None` (the default / tests) disables the
     /// runtime throttle; the cap then stays at its construction value.
     pacer: Option<Arc<dyn Pacer>>,
+    /// The live backup-work priority (SPEC s22 `io_priority`), shared with the
+    /// executor by the app assembly the same way [`Self::pacer`] is.
+    ///
+    /// The orchestrator is the WRITER: it publishes
+    /// [`OrchestratorConfig::io_priority`] here at construction and on every
+    /// [`Orchestrator::reconfigure`], because it is the only component that
+    /// sees a settings change. The executor is the reader, consulting it when
+    /// it starts a piece of blocking work. When the assembly does not wire a
+    /// shared cell (tests, the chaos harness) this is a private cell nobody
+    /// reads, and the executor stays at [`WorkPriority::Normal`].
+    priority: PriorityCell,
     /// Per-orchestrator record-at-create ledger (P1-A). The recorder hook wired
     /// into the provider by [`Self::with_vss`] pushes each freshly-created
     /// shadow GUID here synchronously; `record_vss_orphans` drains it into the
@@ -487,6 +513,7 @@ impl SyncOrchestrator {
         let (trigger_tx, trigger_rx) = mpsc::channel(1);
         let (watcher_tx, watcher_rx) = mpsc::channel(WATCHER_CHANNEL_CAPACITY);
         let (shutdown_tx, shutdown_rx) = watch::channel(false);
+        let priority = PriorityCell::new(config.io_priority);
         Self {
             account_id,
             state,
@@ -508,6 +535,7 @@ impl SyncOrchestrator {
             vss: None,
             command_runner: Arc::new(NoopCommandRunner),
             pacer: None,
+            priority,
             vss_create_ledger: Arc::new(std::sync::Mutex::new(std::collections::HashMap::new())),
             orphan_cleanup_done: Mutex::new(false),
             suspended: std::sync::atomic::AtomicBool::new(false),
@@ -533,6 +561,27 @@ impl SyncOrchestrator {
         self
     }
 
+    /// Share the backup-work priority cell (SPEC s22 `io_priority`) with the
+    /// executor.
+    ///
+    /// Pass the SAME [`PriorityCell`] given to
+    /// [`DefaultExecutor::with_priority_cell`](crate::executor::DefaultExecutor::with_priority_cell),
+    /// exactly like [`Self::with_pacer`]: this orchestrator is the only writer
+    /// (on construction and on every [`Orchestrator::reconfigure`]) and the
+    /// executor is the reader. Seeded immediately from the config this
+    /// orchestrator was built with, so the very first cycle already runs at the
+    /// user's configured level. Without this call the executor keeps its own
+    /// cell and every thread runs at [`WorkPriority::Normal`].
+    #[must_use]
+    pub fn with_priority_cell(mut self, priority: PriorityCell) -> Self {
+        // Carry over what `new` seeded from the config rather than reaching
+        // through the config lock - this builder runs inside the assembly's
+        // async fn, where a blocking lock acquisition would panic.
+        priority.set(self.priority.get());
+        self.priority = priority;
+        self
+    }
+
     /// Attach the app-global latency reservoir (DESIGN s13 telemetry) so each
     /// scan records per-file processing latency. Pass the SAME `Arc` given to the
     /// executor via
@@ -2443,6 +2492,12 @@ impl Orchestrator for SyncOrchestrator {
         if let Some(vss) = self.vss.as_ref() {
             vss.set_mode(config.vss_mode);
         }
+        // Publish the backup-work priority (SPEC s22 `io_priority`) into the
+        // cell the executor reads. Same reason as the VSS mode above: the
+        // setting would otherwise be frozen at whatever the orchestrator was
+        // built with. Work that has already started keeps its level; work that
+        // starts after this call picks the new one up.
+        self.priority.set(config.io_priority);
         *self.config.write().await = config;
     }
 
@@ -3456,6 +3511,66 @@ mod tests {
         );
     }
 
+    /// SPEC s22 `io_priority`: the app assembly hands ONE
+    /// [`PriorityCell`] to the orchestrator and the executor, and the
+    /// orchestrator is the writer. Construction must seed the shared cell from
+    /// the config, and `reconfigure` must republish it - otherwise a settings
+    /// save would be inert until the app restarted (exactly the bug that made
+    /// `vss_mode` inert before P1-5).
+    #[tokio::test]
+    async fn priority_cell_is_seeded_at_build_and_republished_on_reconfigure() {
+        let account = AccountId::new_v4();
+        let dir = tempfile::tempdir().unwrap();
+        let cell = PriorityCell::new(WorkPriority::Normal);
+        let (orch, _clock) = build(
+            account,
+            vec![source_in(account, dir.path())],
+            Arc::new(RecordingExecutor::default()),
+            power_on_ac(),
+            Arc::new(FakeNet::online()),
+            OrchestratorConfig {
+                io_priority: WorkPriority::Low,
+                ..OrchestratorConfig::default()
+            },
+        );
+        // The executor's view of the cell before any settings edit.
+        let orch = orch.with_priority_cell(cell.clone());
+        assert_eq!(
+            cell.get(),
+            WorkPriority::Low,
+            "the first cycle must already run at the configured level, with no settings edit"
+        );
+
+        orch.reconfigure(OrchestratorConfig {
+            io_priority: WorkPriority::Idle,
+            ..OrchestratorConfig::default()
+        })
+        .await;
+        assert_eq!(
+            cell.get(),
+            WorkPriority::Idle,
+            "a settings save must reach the executor's cell"
+        );
+
+        orch.reconfigure(OrchestratorConfig::default()).await;
+        assert_eq!(
+            cell.get(),
+            WorkPriority::Normal,
+            "turning the setting back to normal must un-demote future work"
+        );
+    }
+
+    /// The default config must not demote anything: a test, the chaos harness,
+    /// or a settings-load failure has to behave exactly as it did before this
+    /// feature existed.
+    #[test]
+    fn default_config_runs_backup_work_at_normal_priority() {
+        assert_eq!(
+            OrchestratorConfig::default().io_priority,
+            WorkPriority::Normal
+        );
+    }
+
     #[tokio::test]
     async fn ac_resumes_after_battery_pause() {
         // Power gate: pause on battery, resume on AC (the two-cycle path).