voidzero-dev · wan9chi · Jul 11, 2026 · Jul 10, 2026 · Jul 10, 2026 · Jul 10, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,6 @@
 # Changelog
 
+- **Improved** Windows file-access tracking now uses sparse temporary backing files where supported, avoiding upfront allocation of the full backing file on disk ([#524](https://github.com/voidzero-dev/vite-task/pull/524)).
 - **Fixed** Automatic file-access tracking on Linux now works in containers and Kubernetes runners with limited `/dev/shm` space ([#353](https://github.com/voidzero-dev/vite-task/issues/353), [#523](https://github.com/voidzero-dev/vite-task/pull/523)).
 - **Fixed** Windows automatic input tracking now records executable image reads when process creation performs the lookup inside `NtCreateUserProcess` ([#518](https://github.com/voidzero-dev/vite-task/pull/518)).
 - **Fixed** Failures while waiting for a started task process to exit no longer incorrectly say the process failed to spawn ([#515](https://github.com/voidzero-dev/vite-task/pull/515)).

diff --git a/Cargo.lock b/Cargo.lock
diff --git a/Cargo.toml b/Cargo.toml
@@ -168,6 +168,7 @@ wax = "0.7.0"
 which = "8.0.0"
 widestring = "1.2.0"
 winapi = "0.3.9"
+windows-sys = "0.61"
 winsafe = { version = "0.0.27", features = ["kernel"] }
 xxhash-rust = { version = "0.8.15", features = ["const_xxh3"] }
 ntest = "0.9.5"

diff --git a/crates/fspy_preload_windows/Cargo.toml b/crates/fspy_preload_windows/Cargo.toml
@@ -23,6 +23,7 @@ winapi = { workspace = true, features = [
   "memoryapi",
   "std",
 ] }
+windows-sys = { workspace = true, features = ["Win32_Foundation", "Win32_UI_Shell"] }
 winsafe = { workspace = true }
 
 [target.'cfg(target_os = "windows")'.dev-dependencies]

diff --git a/crates/fspy_preload_windows/src/windows/winapi_utils.rs b/crates/fspy_preload_windows/src/windows/winapi_utils.rs
@@ -6,8 +6,8 @@ use widestring::{U16CStr, U16Str};
 use winapi::{
     ctypes::c_long,
     shared::{
-        minwindef::{BOOL, FALSE, HLOCAL, MAX_PATH, ULONG},
-        ntdef::{HANDLE, HRESULT, PCWSTR, PWSTR, UNICODE_STRING},
+        minwindef::{BOOL, FALSE, MAX_PATH},
+        ntdef::{HANDLE, PWSTR, UNICODE_STRING},
         winerror::{NO_ERROR, S_OK},
     },
     um::{
@@ -18,6 +18,10 @@ use winapi::{
         },
     },
 };
+use windows_sys::Win32::{
+    Foundation::LocalFree,
+    UI::Shell::{PATHCCH_ALLOW_LONG_PATHS, PathAllocCombine},
+};
 use winsafe::{GetLastError, co};
 
 pub fn ck(b: BOOL) -> winsafe::SysResult<()> {
@@ -99,16 +103,6 @@ pub const fn access_mask_to_mode(desired_access: ACCESS_MASK) -> AccessMode {
     }
 }
 
-unsafe extern "system" {
-    fn LocalFree(hmem: HLOCAL) -> HLOCAL;
-    fn PathAllocCombine(
-        pszpathin: PCWSTR,
-        pszmore: PCWSTR,
-        dwflags: ULONG,
-        ppszpathout: *mut PWSTR,
-    ) -> HRESULT;
-}
-
 pub struct HeapPath(PWSTR);
 impl HeapPath {
     #[must_use]
@@ -125,7 +119,6 @@ impl Drop for HeapPath {
 }
 
 pub fn combine_paths(path1: &U16CStr, path2: &U16CStr) -> winsafe::SysResult<HeapPath> {
-    const PATHCCH_ALLOW_LONG_PATHS: ULONG = 0x0000_0001;
     let mut out = std::ptr::null_mut();
     // SAFETY: FFI call to PathAllocCombine with valid null-terminated wide string pointers
     let hr = unsafe {

diff --git a/crates/fspy_shm/Cargo.toml b/crates/fspy_shm/Cargo.toml
@@ -7,7 +7,7 @@ license.workspace = true
 publish = false
 rust-version.workspace = true
 
-[target.'cfg(not(target_os = "linux"))'.dependencies]
+[target.'cfg(not(any(target_os = "linux", target_os = "windows")))'.dependencies]
 shared_memory = { workspace = true, features = ["logging"] }
 
 [target.'cfg(target_os = "linux")'.dependencies]
@@ -19,6 +19,17 @@ tokio-util = { workspace = true }
 tracing = { workspace = true }
 uuid = { workspace = true, features = ["v4"] }
 
+[target.'cfg(target_os = "windows")'.dependencies]
+uuid = { workspace = true, features = ["v4"] }
+windows-sys = { workspace = true, features = [
+  "Win32_Foundation",
+  "Win32_Security",
+  "Win32_Storage_FileSystem",
+  "Win32_System_IO",
+  "Win32_System_Ioctl",
+  "Win32_System_Memory",
+] }
+
 [dev-dependencies]
 ctor = { workspace = true }
 subprocess_test = { workspace = true }

diff --git a/crates/fspy_shm/README.md b/crates/fspy_shm/README.md
@@ -34,5 +34,6 @@ The channel hides that difference with its lock file. [`ChannelConf::sender`](..
 Each platform keeps its implementation rationale beside its source:
 
 - [Linux: `memfd` with a descriptor broker](src/linux/README.md)
+- [Windows: sparse file-backed named mapping](src/windows/README.md)
 
-At this point in the stack, Windows and macOS still delegate mapping creation and opening to the [`shared_memory`](https://crates.io/crates/shared_memory) crate.
+At this point in the stack, macOS still delegates mapping creation and opening to the [`shared_memory`](https://crates.io/crates/shared_memory) crate.
diff --git a/crates/fspy_shm/src/lib.rs b/crates/fspy_shm/src/lib.rs
@@ -1,18 +1,22 @@
 #![doc = include_str!("../README.md")]
 
-#[cfg(not(target_os = "linux"))]
+#[cfg(not(any(target_os = "linux", target_os = "windows")))]
 use std::io;
 
 #[cfg(target_os = "linux")]
 mod linux;
+#[cfg(target_os = "windows")]
+mod windows;
 
 #[cfg(target_os = "linux")]
 pub use linux::{Shm, create, open};
-#[cfg(not(target_os = "linux"))]
+#[cfg(not(any(target_os = "linux", target_os = "windows")))]
 use shared_memory::{Shmem, ShmemConf};
+#[cfg(target_os = "windows")]
+pub use windows::{Shm, create, open};
 
 /// An owned shared-memory mapping.
-#[cfg(not(target_os = "linux"))]
+#[cfg(not(any(target_os = "linux", target_os = "windows")))]
 pub struct Shm {
     inner: Shmem,
 }
@@ -26,11 +30,9 @@ pub struct Shm {
 /// # Errors
 ///
 /// Returns an error if the platform cannot create or map the region.
-#[cfg(not(target_os = "linux"))]
+#[cfg(not(any(target_os = "linux", target_os = "windows")))]
 pub fn create(size: usize) -> io::Result<Shm> {
     let conf = ShmemConf::new().size(size);
-    #[cfg(target_os = "windows")]
-    let conf = conf.allow_raw(true);
 
     let inner = conf.create().map_err(io::Error::other)?;
     Ok(Shm { inner })
@@ -45,17 +47,15 @@ pub fn create(size: usize) -> io::Result<Shm> {
 /// # Errors
 ///
 /// Returns an error if the mapping does not exist or cannot be mapped.
-#[cfg(not(target_os = "linux"))]
+#[cfg(not(any(target_os = "linux", target_os = "windows")))]
 pub fn open(id: &str) -> io::Result<Shm> {
     let conf = ShmemConf::new().os_id(id);
-    #[cfg(target_os = "windows")]
-    let conf = conf.allow_raw(true);
 
     let inner = conf.open().map_err(io::Error::other)?;
     Ok(Shm { inner })
 }
 
-#[cfg(not(target_os = "linux"))]
+#[cfg(not(any(target_os = "linux", target_os = "windows")))]
 #[expect(clippy::len_without_is_empty, reason = "shared-memory mappings are always non-empty")]
 impl Shm {
     /// Returns this mapping's opaque platform identifier.

diff --git a/crates/fspy_shm/src/windows/README.md b/crates/fspy_shm/src/windows/README.md
@@ -0,0 +1,23 @@
+# Windows backend
+
+The Windows backend maps a sparse temporary file and gives the mapping a Windows section name. Another process opens the same section using only that name. Creating the mapping does not reserve its full size in system commit or disk space.
+
+## Options considered
+
+| Option                                                       | Decision                                                                                                                      |
+| ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------- |
+| Paging-file-backed section                                   | Rejected because the section's full size is charged against system commit.                                                    |
+| Reserved section with incremental `VirtualAlloc(MEM_COMMIT)` | Rejected because writers would need to coordinate when committing more pages.                                                 |
+| Sparse temporary file with a named section                   | Selected. Disk blocks are allocated only for written ranges, and another process can open the mapping using the section name. |
+
+`FILE_ATTRIBUTE_TEMPORARY` tells Windows to keep file data in memory when possible, but Windows may still write dirty pages to disk under memory pressure. Creation fails if the temporary volume does not support sparse files.
+
+## Why not `shared_memory`
+
+`shared_memory` creates and extends a regular file before fspy can mark it sparse. It therefore cannot ensure that untouched ranges use no disk blocks.
+
+`shared_memory` also uses the file path to identify the mapping. Fspy uses the section name, so another process does not need the creator's temporary-file path.
+
+## Lifetime semantics
+
+Dropping the owner unmaps its view and closes the delete-on-close backing file. Existing views keep the section alive. The section name may remain openable during that period. `ChannelConf::sender` checks the receiver's lock file first to prevent new senders after the receiver has shut down.