feat(cache): fingerprint tracked getEnvs match sets

Motivation:
Bulk env reads are only cache-safe if the cache remembers the entire matched env set. Without match-set fingerprinting, changing a matching env value, adding a new matching name, or removing one could replay stale output.

Scope:
Make the getEnvs tracked option meaningful, record tracked match sets in IPC reports, store them in the post-run fingerprint, validate changed/added/removed matches during cache lookup, and render env-specific miss messages. This PR does not add the real Vite fixture.

Verification:
- cargo test -p vite_task_server --test integration
- UPDATE_SNAPSHOTS=1 cargo test -p vite_task_bin --test e2e_snapshots fetch_envs_tracks_glob_match_set -- --ignored
- cargo test -p vite_task_bin --test e2e_snapshots fetch_envs_tracks_glob_match_set -- --ignored

Author: wan9chi

CHANGELOG.md

@@ -1,5 +1,6 @@
 # Changelog
 
+- **Added** Runner-aware `getEnvs` match sets can now participate in task cache fingerprints, so changing, adding, or removing a matching env var invalidates the cache.
 - **Added** Runner-aware `getEnvs` calls now return env values served by the runner for matching env glob patterns.
 - **Added** Runner-aware `getEnv` reads can now participate in task cache fingerprints, so changing a tool-served env value invalidates the cache and names the env var in the miss message.
 - **Added** Runner-aware tools can now opt the current task run out of caching through the new IPC channel; Vite dev server integration uses this automatically ([#441](https://github.com/voidzero-dev/vite-task/pull/441))

Cargo.lock

@@ -45,6 +45,7 @@ tracing = { workspace = true }
 twox-hash = { workspace = true }
 materialized_artifact = { workspace = true }
 uuid = { workspace = true, features = ["v4"] }
+vite_glob = { workspace = true }
 vite_path = { workspace = true }
 vite_select = { workspace = true }
 vite_str = { workspace = true }

crates/vite_task/Cargo.toml

@@ -195,7 +195,8 @@ pub fn format_cache_status_inline(cache_status: &CacheStatus) -> Option<Str> {
                 FingerprintMismatch::InputChanged { kind, path } => {
                     format_input_change_str(*kind, path.as_str())
                 }
-                FingerprintMismatch::TrackedEnvChanged(mismatch) => {
+                FingerprintMismatch::TrackedEnvChanged(mismatch)
+                | FingerprintMismatch::TrackedEnvGlobChanged { mismatch, .. } => {
                     format_env_changed_inline(&[mismatch.name()])
                 }
             };

crates/vite_task/src/session/cache/display.rs

@@ -220,14 +220,22 @@ pub enum FingerprintMismatch {
     },
     /// A runner-aware tool-tracked env var changed between runs.
     TrackedEnvChanged(EnvMismatch),
+    /// A runner-aware tool-tracked env glob's match-set changed between runs.
+    TrackedEnvGlobChanged {
+        pattern: Str,
+        mismatch: EnvMismatch,
+    },
 }
 
 impl From<crate::session::execute::fingerprint::PostRunMismatch> for FingerprintMismatch {
     fn from(mismatch: crate::session::execute::fingerprint::PostRunMismatch) -> Self {
         use crate::session::execute::fingerprint::PostRunMismatch;
         match mismatch {
-            PostRunMismatch::InputChanged { kind, path } => Self::InputChanged { kind, path },
-            PostRunMismatch::TrackedEnvChanged(mismatch) => Self::TrackedEnvChanged(mismatch),
+            PostRunMismatch::Input { kind, path } => Self::InputChanged { kind, path },
+            PostRunMismatch::TrackedEnv(mismatch) => Self::TrackedEnvChanged(mismatch),
+            PostRunMismatch::TrackedEnvGlob { pattern, mismatch } => {
+                Self::TrackedEnvGlobChanged { pattern, mismatch }
+            }
         }
     }
 }
@@ -253,7 +261,7 @@ pub fn split_path(path: &str) -> (Option<&str>, &str) {
 /// its own cache warm across branch switches, and a cache from a different
 /// version is simply ignored (it lives in a directory this build never looks
 /// at) rather than aborting the run. Bumping the version starts a fresh cache.
-const CACHE_SCHEMA_VERSION: u32 = 14;
+const CACHE_SCHEMA_VERSION: u32 = 15;
 
 /// Name of the per-version subdirectory (e.g. `v13`) under the task-cache
 /// directory that holds the database and output archives for the current

crates/vite_task/src/session/cache/mod.rs

@@ -101,23 +101,28 @@ pub(super) async fn update_cache(
     // names that the user already declared are skipped because their values
     // are already part of the spawn fingerprint.
     let tracked_envs = reports.map(|r| collect_tracked_envs(r, metadata)).unwrap_or_default();
+    let tracked_env_globs = reports.map(collect_tracked_env_globs).unwrap_or_default();
 
     // Paths already in globbed_inputs are skipped: the overlap check above
     // guarantees no input modification, so the prerun hash is the correct
     // post-exec hash.
     let empty_path_reads = HashMap::default();
     let path_reads = fspy_outcome.as_ref().map_or(&empty_path_reads, |o| &o.path_reads);
-    let post_run_fingerprint =
-        match PostRunFingerprint::create(path_reads, workspace_root, &globbed_inputs, tracked_envs)
-        {
-            Ok(fingerprint) => fingerprint,
-            Err(err) => {
-                return (
-                    CacheUpdateStatus::NotUpdated(CacheNotUpdatedReason::CacheDisabled),
-                    Some(ExecutionError::PostRunFingerprint(err)),
-                );
-            }
-        };
+    let post_run_fingerprint = match PostRunFingerprint::create(
+        path_reads,
+        workspace_root,
+        &globbed_inputs,
+        tracked_envs,
+        tracked_env_globs,
+    ) {
+        Ok(fingerprint) => fingerprint,
+        Err(err) => {
+            return (
+                CacheUpdateStatus::NotUpdated(CacheNotUpdatedReason::CacheDisabled),
+                Some(ExecutionError::PostRunFingerprint(err)),
+            );
+        }
+    };
 
     let output_archive = match collect_and_archive_outputs(metadata, workspace_root, cache_dir) {
         Ok(archive) => archive,
@@ -192,6 +197,29 @@ fn collect_tracked_envs(reports: &Reports, metadata: &CacheMetadata) -> BTreeMap
         .collect()
 }
 
+/// Select tool-reported env-glob records to embed in the post-run
+/// fingerprint. Only `tracked: true` records are included, and the full
+/// match-set is stored as-is.
+fn collect_tracked_env_globs(reports: &Reports) -> BTreeMap<Str, BTreeMap<Str, Str>> {
+    reports
+        .env_glob_records
+        .iter()
+        .filter(|(_, record)| record.tracked)
+        .map(|(pattern, record)| {
+            let matches: BTreeMap<Str, Str> = record
+                .matches
+                .iter()
+                .filter_map(|(name, value)| {
+                    let name_str = name.to_str()?;
+                    let value_str = value.to_str()?;
+                    Some((Str::from(name_str), Str::from(value_str)))
+                })
+                .collect();
+            (Str::from(pattern.as_ref()), matches)
+        })
+        .collect()
+}
+
 /// Collect output files matching the configured globs and create a tar.zst
 /// archive in the cache directory.
 ///

crates/vite_task/src/session/execute/cache_update.rs

@@ -42,15 +42,24 @@ pub struct PostRunFingerprint {
     /// `None` if unset. Validated at cache lookup against the same plan env
     /// context that served the original request.
     pub tracked_envs: BTreeMap<Str, Option<Str>>,
+
+    /// Glob-pattern env queries (`getEnvs`) made with `tracked: true`.
+    /// Outer key is the glob pattern, inner map is the match-set at execution
+    /// time (name -> value). Validated at cache lookup by re-matching against
+    /// the current env context and comparing the resulting set.
+    pub tracked_env_globs: BTreeMap<Str, BTreeMap<Str, Str>>,
 }
 
 /// A mismatch between the stored post-run fingerprint and the current state.
 #[derive(Debug, Clone)]
 pub enum PostRunMismatch {
     /// An inferred input file or directory changed.
-    InputChanged { kind: InputChangeKind, path: RelativePathBuf },
+    Input { kind: InputChangeKind, path: RelativePathBuf },
     /// A tool-tracked env var changed value, appeared, or disappeared.
-    TrackedEnvChanged(EnvMismatch),
+    TrackedEnv(EnvMismatch),
+    /// A tool-tracked env glob's match-set changed between runs. Carries the
+    /// first differing entry in env-name order.
+    TrackedEnvGlob { pattern: Str, mismatch: EnvMismatch },
 }
 
 /// Fingerprint for a single path (file or directory)
@@ -90,12 +99,14 @@ impl PostRunFingerprint {
     /// * `base_dir` - Workspace root for resolving relative paths
     /// * `globbed_inputs` - Prerun glob fingerprint; paths here are skipped
     /// * `tracked_envs` - Tool-requested env vars (name -> value), validated on lookup
+    /// * `tracked_env_globs` - Tool-requested env globs (pattern -> matches)
     #[tracing::instrument(level = "debug", skip_all, name = "create_post_run_fingerprint")]
     pub fn create(
         inferred_path_reads: &HashMap<RelativePathBuf, PathRead>,
         base_dir: &AbsolutePath,
         globbed_inputs: &BTreeMap<RelativePathBuf, u64>,
         tracked_envs: BTreeMap<Str, Option<Str>>,
+        tracked_env_globs: BTreeMap<Str, BTreeMap<Str, Str>>,
     ) -> anyhow::Result<Self> {
         let inferred_inputs = inferred_path_reads
             .par_iter()
@@ -107,7 +118,7 @@ impl PostRunFingerprint {
             })
             .collect::<anyhow::Result<HashMap<_, _>>>()?;
 
-        Ok(Self { inferred_inputs, tracked_envs })
+        Ok(Self { inferred_inputs, tracked_envs, tracked_env_globs })
     }
 
     /// Validates the fingerprint against current filesystem state and env
@@ -143,7 +154,7 @@ impl PostRunFingerprint {
                     } else {
                         input_relative_path.clone()
                     };
-                    Some(Ok(PostRunMismatch::InputChanged { kind, path }))
+                    Some(Ok(PostRunMismatch::Input { kind, path }))
                 }
             },
         );
@@ -157,14 +168,88 @@ impl PostRunFingerprint {
             if let Some(mismatch) =
                 EnvMismatch::compare(name, stored_value.as_ref(), current_value.as_ref())
             {
-                return Ok(Some(PostRunMismatch::TrackedEnvChanged(mismatch)));
+                return Ok(Some(PostRunMismatch::TrackedEnv(mismatch)));
+            }
+        }
+
+        for (pattern, stored_matches) in &self.tracked_env_globs {
+            let current_matches = match_env_glob(pattern.as_str(), envs)?;
+            if let Some(mismatch) = first_env_glob_mismatch(stored_matches, &current_matches) {
+                return Ok(Some(PostRunMismatch::TrackedEnvGlob {
+                    pattern: pattern.clone(),
+                    mismatch,
+                }));
             }
         }
 
         Ok(None)
     }
 }
 
+/// Build the current match-set for `pattern` by enumerating the given env
+/// snapshot and keeping UTF-8 names whose representation matches the glob.
+fn match_env_glob(
+    pattern: &str,
+    envs: &FxHashMap<Arc<OsStr>, Arc<OsStr>>,
+) -> anyhow::Result<BTreeMap<Str, Str>> {
+    let glob = vite_glob::env::EnvGlob::new(pattern)?;
+    Ok(envs
+        .iter()
+        .filter_map(|(name, value)| {
+            let name_str = name.to_str()?;
+            let value_str = value.to_str()?;
+            if glob.is_match(name_str) {
+                Some((Str::from(name_str), Str::from(value_str)))
+            } else {
+                None
+            }
+        })
+        .collect())
+}
+
+/// Find the first deterministic difference between stored and current env
+/// glob match-sets.
+fn first_env_glob_mismatch(
+    stored: &BTreeMap<Str, Str>,
+    current: &BTreeMap<Str, Str>,
+) -> Option<EnvMismatch> {
+    let mut stored_iter = stored.iter();
+    let mut current_iter = current.iter();
+    let mut s = stored_iter.next();
+    let mut c = current_iter.next();
+
+    loop {
+        match (s, c) {
+            (None, None) => return None,
+            (Some((name, value)), None) => {
+                return Some(EnvMismatch::Removed { name: name.clone(), value: value.clone() });
+            }
+            (None, Some((name, value))) => {
+                return Some(EnvMismatch::Added { name: name.clone(), value: value.clone() });
+            }
+            (Some((sn, sv)), Some((cn, cv))) => match sn.cmp(cn) {
+                std::cmp::Ordering::Equal => {
+                    if sv != cv {
+                        return Some(EnvMismatch::Changed {
+                            name: sn.clone(),
+                            old_value: sv.clone(),
+                            new_value: cv.clone(),
+                        });
+                    }
+                    s = stored_iter.next();
+                    c = current_iter.next();
+                }
+                std::cmp::Ordering::Less => {
+                    return Some(EnvMismatch::Removed { name: sn.clone(), value: sv.clone() });
+                }
+                std::cmp::Ordering::Greater => {
+                    return Some(EnvMismatch::Added { name: cn.clone(), value: cv.clone() });
+                }
+            },
+        }
+    }
+}
+
 /// Determine the kind of change between two differing path fingerprints.
 /// Caller guarantees `stored != current`.
 ///

crates/vite_task/src/session/execute/fingerprint.rs

@@ -137,6 +137,9 @@ pub enum SavedCacheMissReason {
     InputChanged { kind: InputChangeKind, path: Str },
     /// A runner-aware tool reported a tracked env var that changed between runs.
     TrackedEnvChanged(EnvMismatch),
+    /// A runner-aware tool reported a tracked env glob whose match-set changed
+    /// between runs. Carries the first differing entry.
+    TrackedEnvGlobChanged { pattern: Str, mismatch: EnvMismatch },
 }
 
 /// An execution error, serializable for persistence.
@@ -283,6 +286,12 @@ impl SavedCacheMissReason {
                 FingerprintMismatch::TrackedEnvChanged(mismatch) => {
                     Self::TrackedEnvChanged(mismatch.clone())
                 }
+                FingerprintMismatch::TrackedEnvGlobChanged { pattern, mismatch } => {
+                    Self::TrackedEnvGlobChanged {
+                        pattern: pattern.clone(),
+                        mismatch: mismatch.clone(),
+                    }
+                }
             },
         }
     }
@@ -572,7 +581,8 @@ impl TaskResult {
                         let desc = format_input_change_str(*kind, path.as_str());
                         vite_str::format!("→ Cache miss: {desc}")
                     }
-                    SavedCacheMissReason::TrackedEnvChanged(mismatch) => {
+                    SavedCacheMissReason::TrackedEnvChanged(mismatch)
+                    | SavedCacheMissReason::TrackedEnvGlobChanged { mismatch, .. } => {
                         vite_str::format!("→ Cache miss: {mismatch}")
                     }
                 },