refactor(cache): name remote cache values by where they come from

- `PlanOptions.remote_cache_mode`: the `--remote-cache` flag.
- `ResolvedRemoteCacheConfig` with `access`: resolved for a `vp run` level.
- `PlanContext::resolved_remote_cache`: the level's resolved value.
- `CacheConfig.remote_cache_allowed`: the task's `cache.remote`.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

Author: wan9chi

crates/vt/src/cli/mod.rs

@@ -19,7 +19,7 @@ pub enum LogMode {
     Grouped,
 }
 
-/// Remote cache access selected on the command line.
+/// Remote cache mode selected with `--remote-cache`.
 #[derive(Debug, Clone, Copy, PartialEq, Eq, clap::ValueEnum)]
 pub enum RemoteCacheMode {
     /// Remote caching is disabled.
@@ -261,7 +261,7 @@ impl ResolvedRunCommand {
                 plan_options: PlanOptions {
                     extra_args: self.additional_args.into(),
                     cache_override,
-                    remote_cache: self.flags.remote_cache.map(Into::into),
+                    remote_cache_mode: self.flags.remote_cache.map(Into::into),
                     concurrency_limit,
                     parallel,
                     fail_if_no_match,

crates/vt/src/session/mod.rs

@@ -582,7 +582,7 @@ impl<'a> Session<'a> {
             plan_options: PlanOptions {
                 extra_args: run_command.additional_args.clone().into(),
                 cache_override: run_command.flags.cache_override(),
-                remote_cache: run_command.flags.remote_cache.map(Into::into),
+                remote_cache_mode: run_command.flags.remote_cache.map(Into::into),
                 concurrency_limit: None,
                 parallel: false,
                 // The selector path runs whatever the user picked interactively;

crates/vt_graph/src/config/mod.rs

@@ -82,7 +82,7 @@ impl ResolvedTaskOptions {
                 )?;
 
                 Some(CacheConfig {
-                    remote_cache: enabled_cache_config.remote.unwrap_or(true),
+                    remote_cache_allowed: enabled_cache_config.remote.unwrap_or(true),
                     env_config: EnvConfig {
                         fingerprinted_envs: enabled_cache_config
                             .env
@@ -101,8 +101,9 @@ impl ResolvedTaskOptions {
 
 #[derive(Debug, Clone, Serialize)]
 pub struct CacheConfig {
-    /// Whether this task permits remote caching when local caching is enabled.
-    pub remote_cache: bool,
+    /// Whether the task's `cache.remote` allows remote caching. An execution uses
+    /// the remote cache only if its `vp run` level also resolves one.
+    pub remote_cache_allowed: bool,
     pub env_config: EnvConfig,
     pub input_config: ResolvedGlobConfig,
     pub output_config: ResolvedGlobConfig,

crates/vt_graph/src/config/user.rs

@@ -377,7 +377,8 @@ pub enum UserGlobalCacheConfig {
 pub struct ResolvedGlobalCacheConfig {
     pub scripts: bool,
     pub tasks: bool,
-    /// Remote cache endpoint from `cache.remote.url`, if configured.
+    /// Remote cache endpoint from `cache.remote.url`, if configured. Planning
+    /// uses `VP_REMOTE_CACHE_URL` instead when it's set.
     pub remote_url: Option<Arc<str>>,
 }
 

crates/vt_plan/src/cache_metadata.rs

@@ -9,7 +9,7 @@ use vt_str::{self, Str};
 use wincode::{SchemaRead, SchemaWrite};
 
 pub use crate::envs::EnvValueHash;
-use crate::{envs::EnvFingerprints, remote_cache::RemoteCacheConfig};
+use crate::{envs::EnvFingerprints, remote_cache::ResolvedRemoteCacheConfig};
 
 /// Key to identify an execution across sessions.
 #[derive(Debug, SchemaWrite, SchemaRead, Serialize)]
@@ -55,8 +55,9 @@ pub struct CacheMetadata {
     /// Used at execution time to determine what output files to archive.
     pub output_config: ResolvedGlobConfig,
 
-    /// Remote cache access. `None` means local caching only.
-    pub remote_cache: Option<RemoteCacheConfig>,
+    /// Remote cache for this execution: the one resolved for its `vp run` level,
+    /// unless the task sets `cache.remote: false`. `None` means local caching only.
+    pub remote_cache: Option<ResolvedRemoteCacheConfig>,
 
     /// The unfiltered env context for runner-aware APIs. This is the planning
     /// context's envs before spawn-env filtering, including command prefix envs

crates/vt_plan/src/context.rs

@@ -8,7 +8,9 @@ use vt_graph::{
 use vt_path::AbsolutePath;
 use vt_str::Str;
 
-use crate::{PlanRequestParser, path_env::prepend_path_env, remote_cache::RemoteCacheConfig};
+use crate::{
+    PlanRequestParser, path_env::prepend_path_env, remote_cache::ResolvedRemoteCacheConfig,
+};
 
 #[derive(Debug, thiserror::Error)]
 #[error(
@@ -65,7 +67,7 @@ pub struct PlanContext<'a> {
     /// Settings pass between levels only through envs. A nested level gets a
     /// copy of this value through [`duplicate`](Self::duplicate), but replaces
     /// it before any reads.
-    remote_cache: Option<RemoteCacheConfig>,
+    resolved_remote_cache: Option<ResolvedRemoteCacheConfig>,
 
     /// The query that caused the current expansion.
     /// Used by the skip rule to detect and skip duplicate nested expansions.
@@ -91,7 +93,7 @@ impl<'a> PlanContext<'a> {
             indexed_task_graph,
             extra_args: Arc::default(),
             resolved_global_cache,
-            remote_cache: None,
+            resolved_remote_cache: None,
             parent_query,
         }
     }
@@ -166,12 +168,12 @@ impl<'a> PlanContext<'a> {
         self.resolved_global_cache = config;
     }
 
-    pub const fn remote_cache(&self) -> Option<&RemoteCacheConfig> {
-        self.remote_cache.as_ref()
+    pub const fn resolved_remote_cache(&self) -> Option<&ResolvedRemoteCacheConfig> {
+        self.resolved_remote_cache.as_ref()
     }
 
-    pub fn set_remote_cache(&mut self, remote_cache: Option<RemoteCacheConfig>) {
-        self.remote_cache = remote_cache;
+    pub fn set_resolved_remote_cache(&mut self, config: Option<ResolvedRemoteCacheConfig>) {
+        self.resolved_remote_cache = config;
     }
 
     pub fn parent_query(&self) -> &TaskQuery {
@@ -198,7 +200,7 @@ impl<'a> PlanContext<'a> {
             indexed_task_graph: self.indexed_task_graph,
             extra_args: Arc::clone(&self.extra_args),
             resolved_global_cache: self.resolved_global_cache.clone(),
-            remote_cache: self.remote_cache.clone(),
+            resolved_remote_cache: self.resolved_remote_cache.clone(),
             parent_query: Arc::clone(&self.parent_query),
         }
     }

crates/vt_plan/src/plan.rs

@@ -41,7 +41,7 @@ use crate::{
         CacheOverride, PlanOptions, PlanRequest, QueryPlanRequest, ScriptCommand,
         SyntheticPlanRequest,
     },
-    remote_cache::{self, RemoteCacheConfig},
+    remote_cache::{self, ResolvedRemoteCacheConfig},
     resolve_cache_with_override,
 };
 
@@ -306,7 +306,7 @@ async fn plan_task_as_execution_node(
                             &cwd,
                             package_path,
                             parent_cache_config,
-                            context.remote_cache(),
+                            context.resolved_remote_cache(),
                         )?;
                         ExecutionItemKind::Leaf(LeafExecutionKind::Spawn(spawn_execution))
                     }
@@ -337,7 +337,7 @@ async fn plan_task_as_execution_node(
                             Some(task_execution_cache_key),
                             &and_item.envs,
                             &resolved_options,
-                            context.remote_cache(),
+                            context.resolved_remote_cache(),
                             &script_command.envs,
                             program_path,
                             spawn_args,
@@ -405,7 +405,7 @@ async fn plan_task_as_execution_node(
                 }),
                 &BTreeMap::new(),
                 &resolved_options,
-                context.remote_cache(),
+                context.resolved_remote_cache(),
                 context.envs(),
                 Arc::clone(&*SHELL_PROGRAM_PATH),
                 SHELL_ARGS.iter().map(|s| Str::from(*s)).chain(std::iter::once(script)).collect(),
@@ -496,7 +496,7 @@ fn resolve_synthetic_cache_config(
                 Some(enabled_cache_config) => {
                     let EnabledCacheConfig { env, untracked_env, input, output, remote } =
                         enabled_cache_config;
-                    parent_config.remote_cache &= remote.unwrap_or(true);
+                    parent_config.remote_cache_allowed &= remote.unwrap_or(true);
                     parent_config.env_config.fingerprinted_envs.extend(env.unwrap_or_default());
                     parent_config
                         .env_config
@@ -559,7 +559,7 @@ pub fn plan_synthetic_request(
     cwd: &Arc<AbsolutePath>,
     package_dir: &AbsolutePath,
     parent_cache_config: ParentCacheConfig,
-    remote_cache: Option<&RemoteCacheConfig>,
+    resolved_remote_cache: Option<&ResolvedRemoteCacheConfig>,
 ) -> Result<SpawnExecution, Error> {
     let SyntheticPlanRequest { program, args, cache_config, envs } = synthetic_plan_request;
 
@@ -580,7 +580,7 @@ pub fn plan_synthetic_request(
         execution_cache_key,
         prefix_envs,
         &resolved_options,
-        remote_cache,
+        resolved_remote_cache,
         &envs,
         program_path,
         args,
@@ -617,7 +617,7 @@ fn plan_spawn_execution(
     execution_cache_key: Option<ExecutionCacheKey>,
     prefix_envs: &BTreeMap<EnvName<Str>, Str>,
     resolved_task_options: &ResolvedTaskOptions,
-    remote_cache: Option<&RemoteCacheConfig>,
+    resolved_remote_cache: Option<&ResolvedRemoteCacheConfig>,
     envs: &Arc<FxHashMap<EnvName<Arc<OsStr>>, Arc<OsStr>>>,
     program_path: Arc<AbsolutePath>,
     args: Arc<[Str]>,
@@ -691,7 +691,11 @@ fn plan_spawn_execution(
                 execution_cache_key,
                 input_config: cache_config.input_config.clone(),
                 output_config: cache_config.output_config.clone(),
-                remote_cache: if cache_config.remote_cache { remote_cache.cloned() } else { None },
+                remote_cache: if cache_config.remote_cache_allowed {
+                    resolved_remote_cache.cloned()
+                } else {
+                    None
+                },
                 unfiltered_envs: Arc::clone(envs),
             });
         }
@@ -760,16 +764,17 @@ pub async fn plan_query_request(
         );
         context.set_resolved_global_cache(final_cache);
     }
-    // Resolve `context.remote_cache` for this level (see its doc for the data
-    // flow). Write this level's `--remote-cache` flag to `VP_REMOTE_CACHE` first,
-    // so it overrides inherited values and nested levels inherit it. Leave the
-    // default unset so each level picks its own from the endpoint it sees.
-    if let Some(mode) = plan_options.remote_cache {
+    // Resolve `context.resolved_remote_cache` for this level (see its doc for
+    // the data flow). Write this level's `--remote-cache` flag to
+    // `VP_REMOTE_CACHE` first, so it overrides inherited values and nested
+    // levels inherit it. Leave the default unset so each level picks its own
+    // from the endpoint it sees.
+    if let Some(mode) = plan_options.remote_cache_mode {
         context.add_envs(std::iter::once((remote_cache::MODE_ENV, mode.as_str())));
     }
-    let remote_cache =
+    let resolved_remote_cache =
         remote_cache::resolve(context.resolved_global_cache().remote_url.as_ref(), context.envs())?;
-    context.set_remote_cache(remote_cache);
+    context.set_resolved_remote_cache(resolved_remote_cache);
 
     // Resolve effective concurrency for this level.
     //
@@ -974,7 +979,7 @@ mod tests {
 
     fn parent_config(includes_auto: bool, positive_globs: &[&str]) -> CacheConfig {
         CacheConfig {
-            remote_cache: true,
+            remote_cache_allowed: true,
             env_config: EnvConfig {
                 fingerprinted_envs: FxHashSet::default(),
                 untracked_env: FxHashSet::default(),
@@ -1175,7 +1180,7 @@ mod tests {
         )
         .unwrap()
         .unwrap();
-        assert!(!result.remote_cache);
+        assert!(!result.remote_cache_allowed);
     }
 
     #[test]

crates/vt_plan/src/plan_request.rs

@@ -50,8 +50,9 @@ pub enum CacheOverride {
 pub struct PlanOptions {
     pub extra_args: Arc<[Str]>,
     pub cache_override: CacheOverride,
-    /// Remote mode for this invocation. None inherits the planning environment.
-    pub remote_cache: Option<crate::remote_cache::RemoteCacheMode>,
+    /// This level's `--remote-cache` flag. `None` when the flag isn't passed,
+    /// leaving `VP_REMOTE_CACHE` from the envs to select the mode.
+    pub remote_cache_mode: Option<crate::remote_cache::RemoteCacheMode>,
     /// Per-level concurrency limit. `None` means inherit from the parent level
     /// (or default to [`crate::DEFAULT_CONCURRENCY_LIMIT`] at the root).
     pub concurrency_limit: Option<usize>,

crates/vt_plan/src/remote_cache.rs

@@ -1,4 +1,5 @@
-//! Remote cache settings resolved for each invocation during planning.
+//! Remote cache settings: the mode requested with `--remote-cache` or
+//! `VP_REMOTE_CACHE`, and the access resolved from it for each `vp run` level.
 
 use std::{ffi::OsStr, sync::Arc};
 
@@ -11,7 +12,8 @@ use crate::Error;
 pub(crate) const MODE_ENV: &str = "VP_REMOTE_CACHE";
 const URL_ENV: &str = "VP_REMOTE_CACHE_URL";
 
-/// Remote access requested by an invocation. Local cache policy is independent.
+/// Remote cache mode requested with `--remote-cache` or `VP_REMOTE_CACHE`.
+/// `resolve` combines it with the endpoint into a [`ResolvedRemoteCacheConfig`].
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
 #[serde(rename_all = "kebab-case")]
 pub enum RemoteCacheMode {
@@ -30,15 +32,16 @@ impl RemoteCacheMode {
     }
 }
 
-/// Remote endpoint and access mode for a cacheable execution.
+/// Remote cache access and endpoint resolved for a `vp run` level from the
+/// requested mode, `VP_REMOTE_CACHE_URL`, and `cache.remote.url`.
 #[derive(Debug, Clone, Serialize)]
-pub struct RemoteCacheConfig {
-    pub mode: RemoteCacheAccess,
+pub struct ResolvedRemoteCacheConfig {
+    pub access: RemoteCacheAccess,
     /// Endpoint as configured. It is validated when the remote cache is used.
     pub url: Arc<str>,
 }
 
-/// Access permitted when remote caching is enabled.
+/// Remote cache access after resolution. `off` resolves to no remote cache.
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
 #[serde(rename_all = "kebab-case")]
 pub enum RemoteCacheAccess {
@@ -56,11 +59,11 @@ fn env_value<'a>(
 }
 
 /// Resolves remote cache access for one `vp run` level from the envs visible at
-/// that level. See `PlanContext::remote_cache` for what they include.
+/// that level. See `PlanContext::resolved_remote_cache` for what they include.
 pub(crate) fn resolve(
     configured_url: Option<&Arc<str>>,
     envs: &FxHashMap<EnvName<Arc<OsStr>>, Arc<OsStr>>,
-) -> Result<Option<RemoteCacheConfig>, Error> {
+) -> Result<Option<ResolvedRemoteCacheConfig>, Error> {
     let mode = match env_value(envs, MODE_ENV) {
         None => None,
         Some(value) => Some(match value.to_str() {
@@ -80,10 +83,10 @@ pub(crate) fn resolve(
     match (mode, url) {
         (Some(RemoteCacheMode::Off), _) | (None, None) => Ok(None),
         (Some(RemoteCacheMode::Read) | None, Some(url)) => {
-            Ok(Some(RemoteCacheConfig { url, mode: RemoteCacheAccess::Read }))
+            Ok(Some(ResolvedRemoteCacheConfig { access: RemoteCacheAccess::Read, url }))
         }
         (Some(RemoteCacheMode::ReadWrite), Some(url)) => {
-            Ok(Some(RemoteCacheConfig { url, mode: RemoteCacheAccess::ReadWrite }))
+            Ok(Some(ResolvedRemoteCacheConfig { access: RemoteCacheAccess::ReadWrite, url }))
         }
         (Some(RemoteCacheMode::Read | RemoteCacheMode::ReadWrite), None) => {
             Err(Error::MissingRemoteCacheEndpoint)
@@ -110,7 +113,7 @@ mod tests {
         let resolved = resolve(None, &envs).unwrap();
         if cfg!(windows) {
             let resolved = resolved.unwrap();
-            assert_eq!(resolved.mode, RemoteCacheAccess::ReadWrite);
+            assert_eq!(resolved.access, RemoteCacheAccess::ReadWrite);
             assert_eq!(&*resolved.url, "https://cache.example");
         } else {
             assert!(resolved.is_none());

crates/vt_plan/tests/plan_snapshots/fixtures/additional_env/snapshots/task_graph.md

@@ -22,7 +22,7 @@ flowchart TD
     "resolved_options": {
       "cwd": "<workspace>/",
       "cache_config": {
-        "remote_cache": true,
+        "remote_cache_allowed": true,
         "env_config": {
           "fingerprinted_envs": [],
           "untracked_env": [
@@ -62,7 +62,7 @@ flowchart TD
     "resolved_options": {
       "cwd": "<workspace>/",
       "cache_config": {
-        "remote_cache": true,
+        "remote_cache_allowed": true,
         "env_config": {
           "fingerprinted_envs": [],
           "untracked_env": [