feat(core): shape bundle-build file reads with the io_priority setting (#179)

Closes the asymmetry I flagged in #176.

## The gap

After #176, `io_priority` shaped large-file upload reads through the
per-handle
hint. Bundled small-file reads were still not shaped: they go through
`build_bundle`'s own opens, covered only by the *thread* guard from #170
- and
on Windows `low` maps to `THREAD_PRIORITY_BELOW_NORMAL`, which is
CPU-only. So a
`low` backup of a folder full of small files still read at normal I/O
priority,
which is exactly the workload someone is most likely to reach for when
testing
the setting.

(At `idle` this was already covered: `THREAD_MODE_BACKGROUND_BEGIN`
lowers I/O
and memory priority alongside CPU. The gap was `low`-only.)

## The change

`build_bundle` takes a `WorkPriority` and hints each member's file
handle as it
opens it. The executor passes the same value it already reads for the
thread
guard, so both levers run at one level and a settings change still takes
effect
per bundle with no restart.

The bundle path is the one place that visibly needs **both** levers,
which is
what makes the two-lever split concrete: the thread guard covers the
gzip CPU,
the handle hint covers the reads.

## Why `std::fs::read` had to go

`std::fs::read` opens and reads in one call and never exposes the
`File`, so
there is no handle to hint - and the hint has to land on the handle
*before* the
reads it is meant to shape. It is now split into a small `read_member`
helper
that opens, hints, then reads. Behaviour is deliberately identical:

- **Same share mode.** `std::fs::read` uses `File::open` internally, so
the
open's sharing/locking semantics are unchanged - which matters because
the
  locked-file/VSS logic elsewhere depends on those semantics.
- **Same allocation.** The buffer is still sized from a stat, reusing
the `pre`
  stat the loop already took instead of re-statting.
- **The size argument is a capacity hint, never a read bound.** It
deliberately
  does not short-circuit the read. Treating it as a bound would hide a
grew-mid-read member from the caller's post-read coherency stat, which
remains
  the sole judge of whether the bytes are a usable snapshot.

Nothing else in the build loop moved: the pre-stat size re-validation,
the
accumulated-bytes ceiling, the post-read coherency check, and the skip
bookkeeping are untouched.

## Tests

- `priority_does_not_change_the_archive_or_the_members` - builds the
same inputs
(including one member that must be skipped) at all three levels and
asserts
the `.tar.gz` bytes, the packed members, and the skip list are
identical.
Byte-equality is a meaningful assertion here because the gzip layer is
written
with a zeroed mtime for reproducibility, so two builds over the same
inputs
  are bit-identical. This is the guard that `io_priority` stays a pure
  scheduling hint.
- `read_member_matches_fs_read_and_ignores_a_wrong_size_hint` - all
bytes come
back at size hints of 0, exact, and oversized, and a missing file errors
  rather than returning short, matching `std::fs::read` exactly.

## Gates

- `cargo fmt --all -- --check` clean
- `cargo clippy --workspace --all-targets -- -D warnings` clean
- `cargo test -p driven-core`: 461 passed, 0 failed
- `cargo test -p driven-app`: 296 passed; `driven-chaos`: 44 passed
- LF endings, ASCII dashes only. No `ui/` changes.

Unlike #176, this diff contains **no `cfg`-gated code** - `read_member`
is plain
`std`, and the per-OS branching all lives inside the
already-cross-checked
`apply_to_file_handle`. So there is no platform-divergent surface for
the
Windows-only local run to have missed; CI's ubuntu and macos legs are
the
confirmation.

## Platform reality, unchanged from #176

This is a Windows-only win. Linux and macOS have no per-descriptor I/O
priority
- both scope it to the thread - so `apply_to_file_handle` is a no-op
there and
bundle reads keep whatever the thread guard gives them.

## Docs

`design/DESIGN.md` s11.2 previously named `open_shared` as the single
hint site.
Updated: both `open_shared` and `build_bundle` hint handles now, with a
note on
why the bundle path needs both levers and why the hint is
redundant-but-harmless
at `idle`.

Generated with [Claude Code](https://claude.com/claude-code)

https://claude.ai/code/session_01JLB3E2Jm7knNJd37fVpH8X

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: pmaxhogan

crates/driven-core/src/bundle.rs

@@ -129,9 +129,17 @@ fn mtime_ns(meta: &std::fs::Metadata) -> i64 {
 /// could not be read, or its `(size, mtime)` changed between the two stats or
 /// disagreed with the bytes read, so only a coherent snapshot is ever packed. The
 /// gzip layer is written with a zeroed mtime for reproducibility.
+///
+/// `priority` (SPEC s22 `io_priority`) is hinted onto each member's file handle
+/// as it is opened, so these reads are serviced below normal instead of
+/// competing with whatever the user has in the foreground. It is purely a
+/// scheduling hint: it changes nothing about which members are packed, what
+/// bytes they contain, or which are skipped. See
+/// [`crate::priority::apply_to_file_handle`] for the per-OS reality.
 pub fn build_bundle(
     inputs: &[(RelativePath, PathBuf, u64)],
     max_total_bytes: u64,
+    priority: crate::priority::WorkPriority,
 ) -> Result<BuildOutput> {
     use flate2::{Compression, GzBuilder};
 
@@ -167,7 +175,7 @@ pub fn build_bundle(
             continue;
         }
 
-        let bytes = match std::fs::read(path) {
+        let bytes = match read_member(path, pre.len(), priority) {
             Ok(b) => b,
             Err(_) => {
                 skipped.push(rel.clone());
@@ -225,6 +233,33 @@ pub fn build_bundle(
     })
 }
 
+/// Read one bundle member's bytes with the SPEC s22 `io_priority` hint attached
+/// to its handle.
+///
+/// This is `std::fs::read` split open so there is a handle to hint: that call
+/// opens and reads in one step and never exposes the `File`, and the hint has to
+/// land on the handle BEFORE the reads it is meant to shape. Behaviour is
+/// otherwise identical - same default share mode (`File::open` is what
+/// `std::fs::read` uses internally, so the open's sharing/locking semantics are
+/// unchanged), and the same "size the buffer from the stat we already took"
+/// allocation, using the caller's `pre` stat rather than re-statting.
+///
+/// `expected_size` is only a capacity hint. It is deliberately NOT trusted as a
+/// read bound: the caller's post-read coherency stat is what decides whether the
+/// bytes are a usable snapshot, and short-circuiting here would hide a
+/// grew-mid-read member from that check.
+fn read_member(
+    path: &std::path::Path,
+    expected_size: u64,
+    priority: crate::priority::WorkPriority,
+) -> std::io::Result<Vec<u8>> {
+    let mut file = std::fs::File::open(path)?;
+    crate::priority::apply_to_file_handle(&file, priority);
+    let mut bytes = Vec::with_capacity(usize::try_from(expected_size).unwrap_or(0));
+    file.read_to_end(&mut bytes)?;
+    Ok(bytes)
+}
+
 /// Extract one member's plaintext bytes from a decompressed-in-memory `.tar.gz`
 /// bundle by its [`member_entry_name`]. Returns `Ok(None)` if no such entry
 /// exists. `max_decompressed` bounds the TOTAL bytes read from the gzip stream (a
@@ -275,6 +310,7 @@ pub fn extract_member(
 #[cfg(test)]
 mod tests {
     use super::*;
+    use crate::priority::WorkPriority;
 
     fn rel(s: &str) -> RelativePath {
         RelativePath::try_from(s.to_string()).expect("valid relative path")
@@ -295,6 +331,58 @@ mod tests {
     /// any fixture's total).
     const TEST_MAX_TOTAL: u64 = 8 * 1024 * 1024;
 
+    /// SPEC s22 `io_priority` is a SCHEDULING hint and nothing more: the archive
+    /// bytes, the packed members, and the skip list must be identical at every
+    /// level. Byte-equality is a meaningful assertion here because the gzip
+    /// layer is written with a zeroed mtime for reproducibility, so two builds
+    /// over the same inputs are bit-identical.
+    #[test]
+    fn priority_does_not_change_the_archive_or_the_members() {
+        let dir = tempfile::tempdir().expect("tempdir");
+        let mut inputs = Vec::new();
+        for i in 0..6u8 {
+            let name = format!("f{i}.txt");
+            let body = format!("member {i} bytes {i}{i}{i}").into_bytes();
+            std::fs::write(dir.path().join(&name), &body).expect("write");
+            inputs.push((rel(&name), dir.path().join(&name), body.len() as u64));
+        }
+        // A member that will be skipped, so the skip path is compared too.
+        inputs.push((rel("gone.txt"), dir.path().join("gone.txt"), 10));
+
+        let baseline = build_bundle(&inputs, TEST_MAX_TOTAL, WorkPriority::Normal).expect("build");
+        assert_eq!(baseline.members.len(), 6);
+        assert_eq!(baseline.skipped, vec![rel("gone.txt")]);
+
+        for level in [WorkPriority::Low, WorkPriority::Idle] {
+            let out = build_bundle(&inputs, TEST_MAX_TOTAL, level).expect("build");
+            assert_eq!(out.tar_gz, baseline.tar_gz, "{level:?} changed the archive");
+            assert_eq!(out.members, baseline.members, "{level:?} changed members");
+            assert_eq!(out.skipped, baseline.skipped, "{level:?} changed skips");
+        }
+    }
+
+    /// `read_member` replaced a `std::fs::read` call, so it has to reproduce that
+    /// call's behaviour exactly: all the bytes on success, and an error (never a
+    /// truncated read) for a missing file. The `expected_size` argument is a
+    /// capacity hint only - passing a wrong one must not truncate or pad, because
+    /// the caller's coherency stat is what decides whether the bytes are usable.
+    #[test]
+    fn read_member_matches_fs_read_and_ignores_a_wrong_size_hint() {
+        let dir = tempfile::tempdir().expect("tempdir");
+        let path = dir.path().join("payload.bin");
+        let body = b"the exact bytes that must come back".to_vec();
+        std::fs::write(&path, &body).expect("write");
+
+        for hint in [0, body.len() as u64, 1024] {
+            let got = read_member(&path, hint, WorkPriority::Idle).expect("read");
+            assert_eq!(got, body, "size hint {hint} must not change the bytes");
+        }
+        assert!(
+            read_member(&dir.path().join("missing.bin"), 0, WorkPriority::Low).is_err(),
+            "a missing file must error, exactly as std::fs::read does"
+        );
+    }
+
     #[test]
     fn build_then_extract_roundtrips_each_member() {
         let dir = tempfile::tempdir().expect("tempdir");
@@ -308,7 +396,7 @@ mod tests {
             contents.push((rel(&name), body));
         }
 
-        let out = build_bundle(&inputs, TEST_MAX_TOTAL).expect("build");
+        let out = build_bundle(&inputs, TEST_MAX_TOTAL, WorkPriority::Normal).expect("build");
         assert_eq!(out.members.len(), 12);
         assert!(out.skipped.is_empty());
 
@@ -342,7 +430,7 @@ mod tests {
             dir.path().join("big.bin"),
             body.len() as u64,
         )];
-        let out = build_bundle(&inputs, TEST_MAX_TOTAL).expect("build");
+        let out = build_bundle(&inputs, TEST_MAX_TOTAL, WorkPriority::Normal).expect("build");
         // A cap below the member size must fail rather than return truncated bytes.
         let res = extract_member(&out.tar_gz, &member_entry_name(&rel("big.bin")), 1024);
         assert!(res.is_err(), "expected decompressed-cap error");
@@ -356,7 +444,7 @@ mod tests {
             (rel("present.txt"), dir.path().join("present.txt"), 2),
             (rel("gone.txt"), dir.path().join("gone.txt"), 2),
         ];
-        let out = build_bundle(&inputs, TEST_MAX_TOTAL).expect("build");
+        let out = build_bundle(&inputs, TEST_MAX_TOTAL, WorkPriority::Normal).expect("build");
         assert_eq!(out.members.len(), 1);
         assert_eq!(out.skipped, vec![rel("gone.txt")]);
     }
@@ -380,7 +468,7 @@ mod tests {
             ),
         ];
 
-        let out = build_bundle(&inputs, TEST_MAX_TOTAL).expect("build");
+        let out = build_bundle(&inputs, TEST_MAX_TOTAL, WorkPriority::Normal).expect("build");
 
         assert_eq!(
             out.skipped,
@@ -412,7 +500,7 @@ mod tests {
 
         // 2500-byte cap: the first two (1000 + 1000) pack; the third (would reach
         // 3000) is skipped.
-        let out = build_bundle(&inputs, 2500).expect("build");
+        let out = build_bundle(&inputs, 2500, WorkPriority::Normal).expect("build");
         assert_eq!(out.members.len(), 2, "two members fit under the ceiling");
         assert_eq!(out.skipped.len(), 1, "the overflowing member is skipped");
     }

crates/driven-core/src/executor.rs

@@ -1806,9 +1806,15 @@ impl DefaultExecutor {
         // (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.
+        //
+        // The SAME level also goes INTO `build_bundle`, which hints each
+        // member's file handle. Both levers are needed here: the thread guard
+        // covers the gzip CPU (and, at `idle` on Windows, I/O too via background
+        // mode), while the handle hint is what lowers READ priority at `low`,
+        // where the Windows thread guard is CPU-only.
         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)
+            crate::bundle::build_bundle(&inputs, crate::planner::BUNDLE_MAX_BYTES_CEILING, priority)
         })
         .await
         {

design/DESIGN.md

@@ -1614,11 +1614,18 @@ the release and the GH Actions build pipeline takes over.
   attaches the hint to the FILE HANDLE instead (`IoPriorityHintLow` for `low`,
   `IoPriorityHintVeryLow` for `idle`), so every read is shaped regardless of
   which thread performs it, and nothing needs restoring because the handle
-  closes with the upload. Applied inside `executor::open_shared`, the single
-  choke point for every source-file read (live open, VSS snapshot open, resume
-  identity check, reconcile re-hash). A read-only handle carries sufficient
-  access, so the open's access mask - and therefore its sharing/locking
-  behaviour - is unchanged.
+  closes with the upload. Applied at both places the executor reads local file
+  bytes: `executor::open_shared` (the choke point for every individual-file read
+  - live open, VSS snapshot open, resume identity check, reconcile re-hash) and
+  `bundle::build_bundle`, which opens each member of a small-file bundle. A
+  read-only handle carries sufficient access, so the open's access mask - and
+  therefore its sharing/locking behaviour - is unchanged.
+  - The bundle path needs BOTH levers, which is what makes the split concrete.
+    Its thread guard covers the gzip CPU, but on Windows `low` maps to
+    `THREAD_PRIORITY_BELOW_NORMAL`, which is CPU-only - so without the handle
+    hint a `low` backup of many small files would still read at normal I/O
+    priority. At `idle` the thread's background mode already covers I/O, so the
+    hint is redundant there but harmless.
   - Linux and macOS have no per-descriptor equivalent (both scope I/O priority
     to the thread), so upload read I/O is unshaped there. Closing that gap means
     owning the reader thread outright, a streaming-pipeline restructure that

src-tauri/src/commands/restore.rs

@@ -3516,6 +3516,7 @@ mod tests {
         let built = driven_core::bundle::build_bundle(
             &inputs,
             driven_core::planner::BUNDLE_MAX_BYTES_CEILING,
+            driven_core::priority::WorkPriority::Normal,
         )
         .unwrap();
         // Plaintext source stores the archive as-is; an encrypted source stores the