From 67b9550883b16cdab0736a8f5bb313fd6ca04657 Mon Sep 17 00:00:00 2001 From: "gominimal-aw-bot[bot]" <281738952+gominimal-aw-bot[bot]@users.noreply.github.com> Date: Fri, 28 Aug 2026 16:57:37 +0000 Subject: [PATCH] refactor(mfile,graph): deterministic order for package-derived setup MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Package-derived sandbox setup was carried in HashMap/HashSet collections, so the same package declarations could produce a different sandbox setup — filesystem mapping order, env vars, and /state subdirectory creation — from one run to the next, and EnvPatches (which is Serialize) churned on re-serialization. None of this reaches a cache key, so it is a reproducibility issue rather than a correctness one. Switch the collections keyed by path or variable name to BTreeMap/BTreeSet, so iteration and serialization follow key order: - mfile::EnvPatches dir/file - graph::SetupForPackages env_vars, state_dirs, fs_mapping_packages, and the build() locals feeding them - decode::patches_from_term patch tables - minimald::env::state_dirs_from_env_vars and the Env::build locals - mctx::env::declared_by and the declarations lookup - the minimald session parity test The type change does not compile crate by crate, so all five crates move together. EnvPatches::to_fs_mappings drops its explicit sort_by_key and takes order straight off the now-sorted maps. Two tests pin the property: identical patches built in opposite insertion orders lower to the same mapping sequence and serialize identically, and SetupForPackages::build over the same packages in two walk orders yields the same key sequences and state-dir set. --- crates/decode/src/lib.rs | 10 +-- crates/graph/src/env_setup.rs | 84 ++++++++++++++++++--- crates/mctx/src/env.rs | 8 +- crates/mfile/src/lib.rs | 48 ++++++++++-- crates/minimald/src/env.rs | 16 ++-- crates/minimald/src/sessions/composables.rs | 4 +- 6 files changed, 131 insertions(+), 39 deletions(-) diff --git a/crates/decode/src/lib.rs b/crates/decode/src/lib.rs index aa0577d912..3191fe5a11 100644 --- a/crates/decode/src/lib.rs +++ b/crates/decode/src/lib.rs @@ -16,7 +16,7 @@ use nickel_lang_core::{ program::Program, }; use serde::{Deserialize, Serialize}; -use std::collections::HashMap; +use std::collections::{BTreeMap, HashMap}; use std::path::Path; mod load; @@ -431,8 +431,8 @@ pub(crate) fn patches_from_term( ) -> Result { let patch_rt = eval_if_closure(rt, program)?; - let mut dirs: Option> = None; - let mut files: Option> = None; + let mut dirs: Option> = None; + let mut files: Option> = None; let Some(r) = record_data_from_val(&patch_rt) else { return Err(Error::unexpected_type( @@ -486,7 +486,7 @@ pub(crate) fn patches_from_term( )) }, ) - .collect::, Error>>()?, + .collect::, Error>>()?, ); Ok(()) } @@ -529,7 +529,7 @@ pub(crate) fn patches_from_term( )) }, ) - .collect::, Error>>()?, + .collect::, Error>>()?, ); Ok(()) } diff --git a/crates/graph/src/env_setup.rs b/crates/graph/src/env_setup.rs index 083f0a0c7a..4d75a93f40 100644 --- a/crates/graph/src/env_setup.rs +++ b/crates/graph/src/env_setup.rs @@ -1,5 +1,5 @@ use std::{ - collections::{HashMap, HashSet}, + collections::{BTreeMap, BTreeSet}, path::PathBuf, }; @@ -12,9 +12,9 @@ use mfile::EnvPatches; #[derive(Debug, Clone, PartialEq, Eq)] pub struct SetupForPackages { /// Environment variables that need to be set, typically for an env_state_wiring entry. - pub env_vars: HashMap, + pub env_vars: BTreeMap, /// Directories that should be created in `/state`, typically from an env_state_wiring entry. - pub state_dirs: HashSet, + pub state_dirs: BTreeSet, /// Whether any package sets `needs.dns`. pub needs_dns: bool, @@ -28,7 +28,7 @@ pub struct SetupForPackages { /// /// Consumed when a mapping can't be honoured, so the error can name the /// package to go and look at rather than only the path it landed on. - pub fs_mapping_packages: HashMap, + pub fs_mapping_packages: BTreeMap, } impl SetupForPackages { @@ -44,10 +44,10 @@ impl SetupForPackages { i: I, ) -> Result { let mut patch = EnvPatches::default(); - let mut fs_mapping_packages: HashMap = Default::default(); + let mut fs_mapping_packages: BTreeMap = Default::default(); let (mut needs_dns, mut needs_internet) = (false, false); - let mut env_vars: HashMap = Default::default(); - let mut state_dirs = HashSet::default(); + let mut env_vars: BTreeMap = Default::default(); + let mut state_dirs = BTreeSet::default(); for dep in i.into_iter() { let b = g.get(dep).unwrap(); @@ -184,10 +184,10 @@ mod tests { needs_internet: false, state_dirs: Default::default(), fs_mappings: EnvPatches { - dir: HashMap::from_iter([("~/.claude".to_string(), PatchSetting::ReadWrite)]), - file: HashMap::new(), + dir: BTreeMap::from_iter([("~/.claude".to_string(), PatchSetting::ReadWrite)]), + file: BTreeMap::new(), }, - fs_mapping_packages: HashMap::from_iter([( + fs_mapping_packages: BTreeMap::from_iter([( "~/.claude".to_string(), "b1".to_string() )]), @@ -329,16 +329,76 @@ mod tests { assert_eq!( SetupForPackages::build(&g, [g.by_name("b1").unwrap()]).unwrap(), SetupForPackages { - env_vars: HashMap::from_iter([ + env_vars: BTreeMap::from_iter([ ("GOCACHE".to_string(), "/state/gocache".to_string(),), ("GOMODCACHE".to_string(), "/state/gomodcache".to_string(),) ]), needs_dns: false, needs_internet: false, - state_dirs: HashSet::from_iter(["gocache".to_string(), "gomodcache".to_string()]), + state_dirs: BTreeSet::from_iter(["gocache".to_string(), "gomodcache".to_string()]), fs_mappings: Default::default(), fs_mapping_packages: Default::default(), } ) } + + /// The same packages walked in opposite orders yield the same env-var, + /// fs-mapping and package-attribution key sequences and the same + /// state-dir set: the ordered collections take their order from their + /// keys, not from the walk, so the sandbox setup is stable run to run. + #[test] + fn build_is_walk_order_independent() { + let layer = Layer::new_for_test( + indoc! { + " + let {BuildSpec, ..} = import \"minimal.ncl\" in + + let + b1 = { + name = \"b1\", + build_deps = [], + cmd = \"\", + attrs = { + env_state_wiring = [{ env_var = \"AVAR\", prefix = \"adir\" }], + env_dir_mappings = [{ read_only = false, path = \"~/a\", class = 'State }], + }, + } | BuildSpec, + b2 = { + name = \"b2\", + build_deps = [], + cmd = \"\", + attrs = { + env_state_wiring = [{ env_var = \"BVAR\", prefix = \"bdir\" }], + env_dir_mappings = [{ read_only = false, path = \"~/b\", class = 'State }], + }, + } | BuildSpec, + in + [b1, b2] + " + } + .to_string(), + ) + .unwrap_or_else(|e| { + e.report_to_stderr(); + panic!("spec parsing failed"); + }); + + let g = Graph::new().ingest(layer).unwrap(); + let (b1, b2) = (g.by_name("b1").unwrap(), g.by_name("b2").unwrap()); + + let forward = SetupForPackages::build(&g, [b1, b2]).unwrap(); + let reverse = SetupForPackages::build(&g, [b2, b1]).unwrap(); + + let keys = |m: &BTreeMap| m.keys().cloned().collect::>(); + assert_eq!(keys(&forward.env_vars), keys(&reverse.env_vars)); + assert_eq!( + keys(&forward.fs_mapping_packages), + keys(&reverse.fs_mapping_packages) + ); + assert_eq!( + forward.fs_mappings.dir.keys().collect::>(), + reverse.fs_mappings.dir.keys().collect::>() + ); + assert_eq!(forward.state_dirs, reverse.state_dirs); + } } diff --git a/crates/mctx/src/env.rs b/crates/mctx/src/env.rs index dcb32124a4..8d8efa2088 100644 --- a/crates/mctx/src/env.rs +++ b/crates/mctx/src/env.rs @@ -1,5 +1,5 @@ use std::{ - collections::{HashMap, HashSet}, + collections::{BTreeMap, HashMap, HashSet}, fs::Permissions, io::Write, os::unix::{fs::PermissionsExt, net::UnixStream}, @@ -571,7 +571,7 @@ pub fn interpolate_task_strings( /// Names whoever put a patch path into the environment: the package that /// declared it, or — for a path that arrived through the task's own `patch` /// table rather than a package attribute — the task itself. -fn declared_by(packages: &HashMap, declared: &str, task: &str) -> String { +fn declared_by(packages: &BTreeMap, declared: &str, task: &str) -> String { match packages.get(declared) { Some(p) => format!("package `{p}`"), None => format!("task `{task}`"), @@ -694,7 +694,7 @@ impl<'a> Env<'a> { // the expanded form, so its "create mapped file" failures name a path // nobody wrote down; this puts the package and its `~/`-rooted // declaration back into the message. - let declarations: HashMap = fs_mapping_packages + let declarations: BTreeMap = fs_mapping_packages .keys() .filter_map(|declared| { Some(( @@ -990,7 +990,7 @@ mod tests { #[test] fn declared_by_names_the_package_then_the_task() { let packages = - HashMap::from_iter([("~/.claude.json".to_string(), "claude-code".to_string())]); + BTreeMap::from_iter([("~/.claude.json".to_string(), "claude-code".to_string())]); assert_eq!( declared_by(&packages, "~/.claude.json", "test"), "package `claude-code`" diff --git a/crates/mfile/src/lib.rs b/crates/mfile/src/lib.rs index 2d94ca8c98..f580600c3e 100644 --- a/crates/mfile/src/lib.rs +++ b/crates/mfile/src/lib.rs @@ -232,11 +232,11 @@ pub struct EnvPatches { /// The list of directories to be patched into the environment. Keys are expected to be path strings, /// either absolute paths are starting with the prefix `~/` to be rooted in the users home directory. #[serde(default, alias = "dirs")] - pub dir: HashMap, + pub dir: BTreeMap, /// The list of files to be patched into the environment. Keys are expected to be path strings, /// either absolute paths are starting with the prefix `~/` to be rooted in the users home directory. #[serde(default, alias = "files")] - pub file: HashMap, + pub file: BTreeMap, } /// Why a `~/`-rooted patch path had no home directory to expand against. @@ -312,8 +312,6 @@ impl EnvPatches { ) -> Result, PatchHomeError> { let mut mappings = Vec::with_capacity(self.dir.len() + self.file.len()); for (is_file, entries) in [(false, &self.dir), (true, &self.file)] { - let mut entries: Vec<_> = entries.iter().collect(); - entries.sort_by_key(|(path, _)| *path); for (path, settings) in entries { mappings.push(common::FsMapping { host_path: Self::expand_home(path, home)?, @@ -1422,7 +1420,7 @@ mod tests { vars: HashMap::new(), patch: EnvPatches { dir: [("~/.claude".to_string(), PatchSetting::ReadWrite)].into(), - file: HashMap::new() + file: BTreeMap::new() }, packages: vec!["base".to_string(), "go".to_string()], action: TaskAction::exec_from_str("go test ./..."), @@ -1545,7 +1543,7 @@ mod tests { }) .unwrap(); let other = EnvPatches { - dir: HashMap::from_iter([ + dir: BTreeMap::from_iter([ ("~/.claude".to_string(), PatchSetting::ReadOnly), ("other".to_string(), PatchSetting::ReadOnly), ]), @@ -1563,7 +1561,7 @@ mod tests { ("other".to_string(), PatchSetting::ReadOnly), ] .into(), - file: HashMap::new() + file: BTreeMap::new() } ); } @@ -1719,6 +1717,42 @@ mod tests { ); } + /// Two [`EnvPatches`] holding the same entries inserted in opposite + /// orders lower to the same mapping sequence and serialize identically: + /// the order comes off the sorted map, not off insertion, so the sandbox + /// setup and any serialized patch table are stable from run to run. + #[test] + fn to_fs_mappings_and_serialization_are_insertion_order_independent() { + let mut forward = EnvPatches::default(); + for k in ["~/a", "~/b", "~/c"] { + forward.dir.insert(k.to_string(), PatchSetting::ReadOnly); + } + for k in ["/x", "/y", "/z"] { + forward.file.insert(k.to_string(), PatchSetting::ReadWrite); + } + + let mut reverse = EnvPatches::default(); + for k in ["~/c", "~/b", "~/a"] { + reverse.dir.insert(k.to_string(), PatchSetting::ReadOnly); + } + for k in ["/z", "/y", "/x"] { + reverse.file.insert(k.to_string(), PatchSetting::ReadWrite); + } + + let seq = |p: &EnvPatches| { + p.to_fs_mappings(Some(Path::new("/home/dev"))) + .unwrap() + .into_iter() + .map(|m| m.host_path) + .collect::>() + }; + assert_eq!(seq(&forward), seq(&reverse)); + assert_eq!( + toml::to_string(&forward).unwrap(), + toml::to_string(&reverse).unwrap() + ); + } + #[test] fn output_arch_defaults_to_none() { let mf: File = toml::from_str(indoc! { diff --git a/crates/minimald/src/env.rs b/crates/minimald/src/env.rs index ba0386429f..3caef492ba 100644 --- a/crates/minimald/src/env.rs +++ b/crates/minimald/src/env.rs @@ -23,7 +23,7 @@ //! requests one at a time on the runtime, so every handler is a plain //! `async fn` that `.await`s — no nested runtimes, no sync/async bridge writers. -use std::collections::{BTreeMap, HashMap, HashSet}; +use std::collections::{BTreeMap, BTreeSet, HashMap, HashSet}; use std::fs::Permissions; use std::io::Write; use std::os::unix::fs::PermissionsExt; @@ -379,9 +379,7 @@ impl RuntimeEnv { /// resolved env-var value shaped `/state/`. /// Multi-component and empty prefixes are dropped — they can't be /// distinguished from coincidental `/state/`-prefixed values. -fn state_dirs_from_env_vars( - env_vars: &HashMap, -) -> std::collections::HashSet { +fn state_dirs_from_env_vars(env_vars: &BTreeMap) -> BTreeSet { env_vars .values() .filter_map(|v| v.strip_prefix("/state/")) @@ -449,7 +447,7 @@ impl Env { .map_err(std::io::Error::other)?; (state_dirs, env_vars) } else { - (std::collections::HashSet::::new(), HashMap::new()) + (BTreeSet::::new(), BTreeMap::new()) }; if let Some(vars) = &args.env_vars { @@ -471,7 +469,7 @@ impl Env { // `deny` policy on some GOCACHE env var) also skips creating // its state dir — no orphaned `/state` slot for a var the // session doesn't actually have. - let state_dirs: std::collections::HashSet = if args.include_package_attr_wiring { + let state_dirs: BTreeSet = if args.include_package_attr_wiring { legacy_state_dirs } else { state_dirs_from_env_vars(&pkg_env_vars) @@ -2057,7 +2055,7 @@ mod tests { /// it can be unit-tested directly. #[test] fn state_dirs_from_env_vars_extracts_single_component_prefixes() { - let env = HashMap::from([ + let env = BTreeMap::from([ ("GOCACHE".to_string(), "/state/gocache".to_string()), ("GOMODCACHE".to_string(), "/state/gomodcache".to_string()), ("HOME".to_string(), "/home/user".to_string()), @@ -2073,7 +2071,7 @@ mod tests { /// ignored — creating `state_base_dir/` itself is nonsense. #[test] fn state_dirs_from_env_vars_ignores_bare_state() { - let env = HashMap::from([("WEIRD".to_string(), "/state/".to_string())]); + let env = BTreeMap::from([("WEIRD".to_string(), "/state/".to_string())]); assert!(state_dirs_from_env_vars(&env).is_empty()); } @@ -2415,7 +2413,7 @@ mod tests { /// diagnosing bad ones. #[test] fn state_dirs_from_env_vars_silently_drops_multi_component() { - let env = HashMap::from([("WEIRD".to_string(), "/state/foo/bar".to_string())]); + let env = BTreeMap::from([("WEIRD".to_string(), "/state/foo/bar".to_string())]); assert!(state_dirs_from_env_vars(&env).is_empty()); } } diff --git a/crates/minimald/src/sessions/composables.rs b/crates/minimald/src/sessions/composables.rs index a13e14215b..9740464ff5 100644 --- a/crates/minimald/src/sessions/composables.rs +++ b/crates/minimald/src/sessions/composables.rs @@ -650,7 +650,7 @@ mod tests { let env = |_: &str| Err(std::env::VarError::NotPresent); let contribution = composable.contribute(&env).unwrap(); - let composition_env_vars: std::collections::HashMap = contribution + let composition_env_vars: std::collections::BTreeMap = contribution .vars() .iter() .map(|pv| (pv.var().name().to_string(), pv.var().value().to_string())) @@ -660,7 +660,7 @@ mod tests { // Composition's state-dir derivation (values shaped // `/state/` → `prefix`) matches what // `SetupForPackages` extracted from `env_state_wiring`. - let composition_state_dirs: std::collections::HashSet = composition_env_vars + let composition_state_dirs: std::collections::BTreeSet = composition_env_vars .values() .filter_map(|v| v.strip_prefix("/state/")) .filter(|p| !p.is_empty() && !p.contains('/'))