ktstr/
scheduler_artifact.rs

1//! Parent-built scheduler artifact handoff for orchestrated test runs.
2//!
3//! A `cargo ktstr` parent discovers every `Path` and `Discover` scheduler
4//! referenced by the warmed test executables before nextest starts. It builds
5//! each distinct `Discover` package once, writes one immutable manifest, and
6//! exports [`crate::KTSTR_SCHEDULER_MANIFEST_ENV`] to every child. This module
7//! is the single reader and wire format shared by ordinary tests, coverage,
8//! raw `llvm-cov nextest`, staged schedulers, and verifier cells.
9
10use std::collections::{BTreeMap, BTreeSet};
11use std::ffi::OsStr;
12use std::io::Read;
13use std::path::{Path, PathBuf};
14use std::sync::{Arc, Mutex, OnceLock};
15
16/// Current schema version for [`SchedulerArtifactManifest`].
17pub const SCHEDULER_ARTIFACT_MANIFEST_VERSION: u32 = 1;
18
19const SCHEDULER_ARTIFACT_TREE_NAMESPACE: &str = "scheduler-workspace-v1";
20
21/// Parent-owned scheduler artifacts for one orchestrated test run.
22#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
23#[serde(deny_unknown_fields)]
24pub struct SchedulerArtifactManifest {
25    /// Wire schema version.
26    pub version: u32,
27    /// Effective Cargo profile used for every scheduler build.
28    pub profile: String,
29    /// Exact package-and-declaring-workspace artifact mappings.
30    pub entries: Vec<SchedulerArtifactEntry>,
31}
32
33/// Exact scheduler executable specification carried in a manifest entry.
34///
35/// The tagged variant is part of the identity: `Discover("x")` and
36/// `Path("x")` can never alias even though their string payloads match.
37#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, serde::Serialize, serde::Deserialize)]
38#[serde(rename_all = "snake_case", tag = "kind", content = "value")]
39pub enum SchedulerArtifactSpec {
40    /// Cargo package built by the parent.
41    Discover(String),
42    /// Explicit source path pinned and snapshotted by the parent.
43    Path(String),
44}
45
46impl SchedulerArtifactSpec {
47    fn from_scheduler_spec(spec: &crate::test_support::SchedulerSpec) -> anyhow::Result<Self> {
48        match spec {
49            crate::test_support::SchedulerSpec::Discover(package) => {
50                Ok(Self::Discover((*package).to_string()))
51            }
52            crate::test_support::SchedulerSpec::Path(path) => Ok(Self::Path((*path).to_string())),
53            crate::test_support::SchedulerSpec::Eevdf
54            | crate::test_support::SchedulerSpec::KernelBuiltin { .. } => {
55                anyhow::bail!("kernel-only scheduler has no artifact manifest identity")
56            }
57        }
58    }
59}
60
61/// One exact scheduler artifact and every scheduler name which requires it.
62///
63/// `(binary, manifest_dir, manifest.profile)` is the executable identity.
64/// `schedulers` is validation metadata: ordinary resolution needs only the
65/// exact artifact identity, while verifier dispatch additionally proves that
66/// the selected declared scheduler was part of the parent's build plan.
67#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
68#[serde(deny_unknown_fields)]
69pub struct SchedulerArtifactEntry {
70    /// Exact tagged scheduler executable specification.
71    pub binary: SchedulerArtifactSpec,
72    /// Exact declaring `CARGO_MANIFEST_DIR`.
73    pub manifest_dir: String,
74    /// Sorted, unique declared scheduler names which use this artifact.
75    pub schedulers: Vec<String>,
76    /// Canonical absolute executable path emitted or snapshotted by the parent.
77    pub path: PathBuf,
78}
79
80#[derive(Clone)]
81struct CachedSchedulerArtifactManifest {
82    identity: crate::cache::content::StableFileIdentity,
83    manifest: Arc<SchedulerArtifactManifest>,
84}
85
86fn scheduler_manifest_cache() -> &'static Mutex<BTreeMap<PathBuf, CachedSchedulerArtifactManifest>>
87{
88    static CACHE: OnceLock<Mutex<BTreeMap<PathBuf, CachedSchedulerArtifactManifest>>> =
89        OnceLock::new();
90    CACHE.get_or_init(|| Mutex::new(BTreeMap::new()))
91}
92
93/// Read one manifest through its pinned inode and memoize immutable revisions.
94///
95/// Parent-published manifests are mode-0444 and shared by every nextest child.
96/// A process may resolve hundreds of scheduler declarations, so repeatedly
97/// reading and parsing the same JSON is avoidable. The cache is keyed by the
98/// absolute pathname and exact inode revision; atomic replacement therefore
99/// invalidates it naturally. Mutable manifests are never cached, preserving
100/// direct test/development rewrites.
101fn read_scheduler_artifact_manifest(
102    manifest_path: &Path,
103) -> anyhow::Result<Arc<SchedulerArtifactManifest>> {
104    use std::os::unix::fs::PermissionsExt as _;
105
106    let mut file = std::fs::File::open(manifest_path).map_err(|error| {
107        anyhow::anyhow!(
108            "read scheduler artifact manifest {}: {error}",
109            manifest_path.display()
110        )
111    })?;
112    let metadata = file.metadata().map_err(|error| {
113        anyhow::anyhow!(
114            "stat scheduler artifact manifest {}: {error}",
115            manifest_path.display()
116        )
117    })?;
118    if !metadata.is_file() {
119        anyhow::bail!(
120            "scheduler artifact manifest is not a regular file: {}",
121            manifest_path.display()
122        );
123    }
124    let identity = crate::cache::content::StableFileIdentity::from_metadata(&metadata);
125    let immutable = metadata.permissions().mode() & 0o222 == 0;
126    if immutable {
127        let cached = scheduler_manifest_cache()
128            .lock()
129            .unwrap_or_else(std::sync::PoisonError::into_inner)
130            .get(manifest_path)
131            .filter(|cached| cached.identity == identity)
132            .cloned();
133        if let Some(cached) = cached {
134            anyhow::ensure!(
135                crate::cache::content::StableFileIdentity::from_file(&file)? == identity,
136                "scheduler artifact manifest changed during cached lookup: {}",
137                manifest_path.display()
138            );
139            return Ok(cached.manifest);
140        }
141    }
142
143    let mut bytes = Vec::new();
144    file.read_to_end(&mut bytes).map_err(|error| {
145        anyhow::anyhow!(
146            "read scheduler artifact manifest {}: {error}",
147            manifest_path.display()
148        )
149    })?;
150    anyhow::ensure!(
151        crate::cache::content::StableFileIdentity::from_file(&file)? == identity,
152        "scheduler artifact manifest changed while reading: {}",
153        manifest_path.display()
154    );
155    let manifest: SchedulerArtifactManifest = serde_json::from_slice(&bytes).map_err(|error| {
156        anyhow::anyhow!(
157            "parse scheduler artifact manifest {}: {error}",
158            manifest_path.display()
159        )
160    })?;
161    let manifest = Arc::new(manifest);
162    if immutable {
163        scheduler_manifest_cache()
164            .lock()
165            .unwrap_or_else(std::sync::PoisonError::into_inner)
166            .insert(
167                manifest_path.to_path_buf(),
168                CachedSchedulerArtifactManifest {
169                    identity,
170                    manifest: Arc::clone(&manifest),
171                },
172            );
173    }
174    Ok(manifest)
175}
176
177fn validate_scheduler_artifact(path: &Path) -> anyhow::Result<()> {
178    use std::os::unix::fs::PermissionsExt;
179
180    if !path.is_absolute() {
181        anyhow::bail!(
182            "scheduler artifact path must be absolute, got {}",
183            path.display()
184        );
185    }
186    let canonical = std::fs::canonicalize(path).map_err(|error| {
187        anyhow::anyhow!(
188            "canonicalize scheduler artifact {}: {error}",
189            path.display()
190        )
191    })?;
192    if canonical.as_path() != path {
193        anyhow::bail!(
194            "scheduler artifact path is not canonical: {} resolves to {}",
195            path.display(),
196            canonical.display(),
197        );
198    }
199    let metadata = std::fs::metadata(path)
200        .map_err(|error| anyhow::anyhow!("stat scheduler artifact {}: {error}", path.display()))?;
201    if !metadata.is_file() {
202        anyhow::bail!("scheduler artifact is not a file: {}", path.display());
203    }
204    if metadata.permissions().mode() & 0o111 == 0 {
205        anyhow::bail!("scheduler artifact is not executable: {}", path.display());
206    }
207    if metadata.permissions().mode() & 0o222 != 0 {
208        anyhow::bail!(
209            "scheduler artifact is mutable; parent snapshots must be read-only: {}",
210            path.display()
211        );
212    }
213    Ok(())
214}
215
216fn scheduler_artifact_from_manifest_path(
217    manifest_path: Option<&OsStr>,
218    expected_scheduler: Option<&str>,
219    binary: &SchedulerArtifactSpec,
220    manifest_dir: &str,
221) -> anyhow::Result<Option<PathBuf>> {
222    let Some(manifest_path) = manifest_path else {
223        return Ok(None);
224    };
225    if manifest_path.is_empty() {
226        anyhow::bail!("{} is set but empty", crate::KTSTR_SCHEDULER_MANIFEST_ENV);
227    }
228    let manifest_path = PathBuf::from(manifest_path);
229    if !manifest_path.is_absolute() {
230        anyhow::bail!(
231            "{} must name an absolute path, got {}",
232            crate::KTSTR_SCHEDULER_MANIFEST_ENV,
233            manifest_path.display(),
234        );
235    }
236    let manifest = read_scheduler_artifact_manifest(&manifest_path)?;
237    if manifest.version != SCHEDULER_ARTIFACT_MANIFEST_VERSION {
238        anyhow::bail!(
239            "unsupported scheduler artifact manifest version {} in {} (expected {})",
240            manifest.version,
241            manifest_path.display(),
242            SCHEDULER_ARTIFACT_MANIFEST_VERSION,
243        );
244    }
245    let expected_profile = crate::scheduler_profile_name();
246    if manifest.profile != expected_profile {
247        anyhow::bail!(
248            "scheduler artifact manifest {} was built with profile {:?}, \
249             but this child resolves scheduler profile {:?}",
250            manifest_path.display(),
251            manifest.profile,
252            expected_profile,
253        );
254    }
255
256    let mut identities = BTreeSet::new();
257    let mut matched = None;
258    for entry in &manifest.entries {
259        let binary_value = match &entry.binary {
260            SchedulerArtifactSpec::Discover(value) | SchedulerArtifactSpec::Path(value) => value,
261        };
262        if binary_value.is_empty() || entry.manifest_dir.is_empty() {
263            anyhow::bail!(
264                "scheduler artifact manifest {} contains an empty binary value or manifest_dir",
265                manifest_path.display(),
266            );
267        }
268        if !identities.insert((&entry.binary, &entry.manifest_dir)) {
269            anyhow::bail!(
270                "duplicate scheduler artifact manifest entry for binary {:?}, \
271                 manifest_dir {:?}",
272                entry.binary,
273                entry.manifest_dir,
274            );
275        }
276        if entry.schedulers.is_empty() {
277            anyhow::bail!(
278                "scheduler artifact manifest entry for binary {:?}, manifest_dir {:?} \
279                 has no requiring scheduler names",
280                entry.binary,
281                entry.manifest_dir,
282            );
283        }
284        let mut scheduler_names = BTreeSet::new();
285        for scheduler in &entry.schedulers {
286            if scheduler.is_empty() || !scheduler_names.insert(scheduler) {
287                anyhow::bail!(
288                    "scheduler artifact manifest entry for binary {:?}, manifest_dir {:?} \
289                     has an empty or duplicate scheduler name",
290                    entry.binary,
291                    entry.manifest_dir,
292                );
293            }
294        }
295        if entry.binary == *binary && entry.manifest_dir == manifest_dir {
296            matched = Some(entry);
297        }
298    }
299
300    let Some(entry) = matched else {
301        anyhow::bail!(
302            "scheduler artifact manifest {} has no exact entry for binary {binary:?}, \
303             manifest_dir {manifest_dir:?}",
304            manifest_path.display(),
305        );
306    };
307    validate_scheduler_artifact(&entry.path)?;
308    if let Some(scheduler) = expected_scheduler
309        && !entry.schedulers.iter().any(|name| name == scheduler)
310    {
311        anyhow::bail!(
312            "scheduler artifact manifest entry for binary {binary:?}, \
313             manifest_dir {manifest_dir:?} was not prepared for scheduler {scheduler:?}",
314        );
315    }
316    Ok(Some(entry.path.clone()))
317}
318
319/// Resolve one `Discover` scheduler through the orchestrator manifest.
320///
321/// `Ok(None)` means no orchestrator manifest is present, which preserves the
322/// direct/manual test-binary resolution path. Once the environment variable is
323/// present, the manifest is authoritative: every parse, version, identity,
324/// scheduler-name, profile, and artifact failure is returned and callers must
325/// not invoke Cargo as a fallback.
326pub(crate) fn scheduler_artifact_from_env(
327    expected_scheduler: Option<&str>,
328    spec: &crate::test_support::SchedulerSpec,
329    manifest_dir: &str,
330) -> anyhow::Result<Option<PathBuf>> {
331    if std::env::var_os(crate::KTSTR_SCHEDULER_MANIFEST_ENV).is_none() {
332        return Ok(None);
333    }
334    let binary = SchedulerArtifactSpec::from_scheduler_spec(spec)?;
335    let manifest_path = std::env::var_os(crate::KTSTR_SCHEDULER_MANIFEST_ENV);
336    scheduler_artifact_from_manifest_path(
337        manifest_path.as_deref(),
338        expected_scheduler,
339        &binary,
340        manifest_dir,
341    )
342}
343
344/// A live lease over one immutable scheduler executable in the machine CAS.
345///
346/// Every process which snapshots identical bytes receives the same canonical
347/// pathname and inode. Keeping this value alive prevents cache collection from
348/// unlinking that pathname while a child manifest refers to it.
349pub struct SchedulerArtifactSnapshot {
350    snapshot: crate::cache::ContentFileSnapshot,
351}
352
353impl SchedulerArtifactSnapshot {
354    /// Canonical shared-CAS pathname for the immutable executable.
355    pub fn path(&self) -> &Path {
356        self.snapshot.path()
357    }
358}
359
360/// Pin and snapshot one scheduler executable into the shared content CAS.
361///
362/// The source is opened before hashing or publication, which pins its inode
363/// against Cargo's atomic replacement. Identical bytes across components,
364/// workspaces, and processes converge on one immutable mode-0555 inode.
365pub fn snapshot_scheduler_artifact(
366    source_path: &Path,
367) -> Result<SchedulerArtifactSnapshot, String> {
368    let pinned = crate::cache::pin_content_file(source_path).map_err(|error| {
369        format!(
370            "open scheduler artifact {} for immutable snapshot: {error:#}",
371            source_path.display()
372        )
373    })?;
374    snapshot_pinned_scheduler_artifact(pinned)
375}
376
377/// Snapshot an already-pinned scheduler descriptor.
378///
379/// This is public for cargo-ktstr's race test; production callers normally use
380/// [`snapshot_scheduler_artifact`].
381#[doc(hidden)]
382pub fn snapshot_pinned_scheduler_artifact(
383    pinned: crate::cache::PinnedContentFile,
384) -> Result<SchedulerArtifactSnapshot, String> {
385    use std::os::unix::fs::PermissionsExt;
386
387    let source_path = pinned.source_path().to_path_buf();
388    let source_metadata = pinned.source().metadata().map_err(|error| {
389        format!(
390            "stat opened scheduler artifact {}: {error}",
391            source_path.display()
392        )
393    })?;
394    if !source_metadata.is_file() {
395        return Err(format!(
396            "scheduler artifact is not a file: {}",
397            source_path.display()
398        ));
399    }
400    if source_metadata.permissions().mode() & 0o111 == 0 {
401        return Err(format!(
402            "scheduler artifact is not executable: {}",
403            source_path.display()
404        ));
405    }
406
407    let snapshot = crate::cache::snapshot_pinned_artifact_file(pinned).map_err(|error| {
408        format!(
409            "publish pinned scheduler artifact {} in shared content cache: {error:#}",
410            source_path.display()
411        )
412    })?;
413    Ok(SchedulerArtifactSnapshot { snapshot })
414}
415
416/// One input-addressed scheduler workspace build result.
417///
418/// Every path names a private COW materialization of the generic Cargo
419/// artifact-tree cache. Keeping `tree` alive keeps both that materialization
420/// and its immutable content-object leases alive through the child run. A
421/// cache hit never invokes Cargo or enters the target-directory/build leases.
422#[doc(hidden)]
423pub struct CachedSchedulerWorkspaceArtifacts {
424    pub paths: BTreeMap<String, PathBuf>,
425    pub tree: crate::cache::artifact_tree::MaterializedArtifactTree,
426    pub cache_hit: bool,
427}
428
429fn load_or_build_scheduler_workspace_artifacts_at_root<F, V, C>(
430    root: &Path,
431    identity: u64,
432    packages: &[String],
433    progress_label: &str,
434    validate_identity: V,
435    cancelled: C,
436    build: F,
437) -> Result<CachedSchedulerWorkspaceArtifacts, String>
438where
439    F: FnOnce() -> Result<BTreeMap<String, crate::cache::PinnedContentFile>, String>,
440    V: Fn() -> Result<bool, String>,
441    C: Fn() -> bool,
442{
443    if packages.is_empty()
444        || packages.windows(2).any(|pair| pair[0] >= pair[1])
445        || packages.iter().any(String::is_empty)
446    {
447        return Err(format!(
448            "scheduler build cache packages must be non-empty, sorted, unique names: {packages:?}"
449        ));
450    }
451    let cache = crate::cache::artifact_tree::ArtifactTreeCache::new(
452        root.join(SCHEDULER_ARTIFACT_TREE_NAMESPACE),
453    );
454    let materializations = root.join("materialized");
455    let tree = cache
456        .load_or_build(
457            identity,
458            &materializations,
459            progress_label,
460            || validate_identity().map_err(anyhow::Error::msg),
461            &cancelled,
462            || {
463                let pinned = build().map_err(anyhow::Error::msg)?;
464                anyhow::ensure!(
465                    pinned.keys().eq(packages.iter()),
466                    "scheduler workspace builder emitted packages {:?}, expected {packages:?}",
467                    pinned.keys().collect::<Vec<_>>(),
468                );
469                let mut source = crate::cache::artifact_tree::ArtifactTreeSource::new();
470                for (package, artifact) in pinned {
471                    source.insert_immutable_pinned_file(
472                        Path::new("artifacts").join(package),
473                        artifact,
474                    )?;
475                }
476                Ok(source)
477            },
478        )
479        .map_err(|error| format!("{error:#}"))?;
480    let paths = packages
481        .iter()
482        .map(|package| (package.clone(), tree.root().join("artifacts").join(package)))
483        .collect();
484    let cache_hit = tree.cache_hit();
485    if let Err(error) = tree.persist_decision_diagnostic(
486        "scheduler-workspace",
487        serde_json::json!({
488            "namespace": SCHEDULER_ARTIFACT_TREE_NAMESPACE,
489            "normalized_inputs_digest": format!("{identity:016x}"),
490            "packages": packages,
491        }),
492    ) {
493        tracing::warn!(error = %error, "could not persist scheduler artifact-cache decision");
494    }
495    Ok(CachedSchedulerWorkspaceArtifacts {
496        paths,
497        tree,
498        cache_hit,
499    })
500}
501
502/// Reuse or build one exact scheduler workspace output identity.
503///
504/// The key is supplied by cargo-ktstr's source/toolchain/environment
505/// fingerprint planner. This function owns cross-process election and atomic
506/// publication. Same-key consumers wait for one producer and then reacquire
507/// ordinary immutable content-CAS leases; they never invoke the builder.
508#[doc(hidden)]
509pub fn load_or_build_scheduler_workspace_artifacts<F, V, C>(
510    identity: u64,
511    packages: &[String],
512    progress_label: &str,
513    validate_identity: V,
514    cancelled: C,
515    build: F,
516) -> Result<CachedSchedulerWorkspaceArtifacts, String>
517where
518    F: FnOnce() -> Result<BTreeMap<String, crate::cache::PinnedContentFile>, String>,
519    V: Fn() -> Result<bool, String>,
520    C: Fn() -> bool,
521{
522    let root = crate::cache::cargo_artifact_tree_cache_root()
523        .map_err(|error| format!("resolve Cargo artifact tree cache root: {error:#}"))?;
524    load_or_build_scheduler_workspace_artifacts_at_root(
525        &root,
526        identity,
527        packages,
528        progress_label,
529        validate_identity,
530        cancelled,
531        build,
532    )
533}
534
535/// Build scheduler workspaces through the same deterministic stable-output
536/// producer used by ordinary, coverage, and verifier harness closures.
537///
538/// Scheduler binaries may embed `OUT_DIR`, so the Cargo child must write at
539/// the final persistent pathname supplied to `build`; execution still uses a
540/// private reflink materialization.
541#[doc(hidden)]
542pub fn load_or_build_scheduler_workspace_artifacts_stable<F, V, C>(
543    identity: u64,
544    packages: &[String],
545    progress_label: &str,
546    validate_identity: V,
547    cancelled: C,
548    build: F,
549) -> Result<CachedSchedulerWorkspaceArtifacts, String>
550where
551    F: FnOnce(
552        &crate::cache::artifact_tree::StableCargoBuild,
553    ) -> Result<BTreeMap<String, crate::cache::PinnedContentFile>, String>,
554    V: Fn() -> Result<bool, String>,
555    C: Fn() -> bool,
556{
557    if packages.is_empty()
558        || packages.windows(2).any(|pair| pair[0] >= pair[1])
559        || packages.iter().any(String::is_empty)
560    {
561        return Err(format!(
562            "scheduler build cache packages must be non-empty, sorted, unique names: {packages:?}"
563        ));
564    }
565    let root = crate::cache::cargo_artifact_tree_cache_root()
566        .map_err(|error| format!("resolve Cargo artifact tree cache root: {error:#}"))?;
567    let cache = crate::cache::artifact_tree::ArtifactTreeCache::new(
568        root.join(SCHEDULER_ARTIFACT_TREE_NAMESPACE),
569    );
570    let tree = cache
571        .load_or_build_with_stable_cargo_output(
572            identity,
573            &root.join("stable-builds-v1"),
574            &root.join("materialized"),
575            progress_label,
576            || validate_identity().map_err(anyhow::Error::msg),
577            cancelled,
578            |stable| {
579                let pinned = build(stable).map_err(anyhow::Error::msg)?;
580                anyhow::ensure!(
581                    pinned.keys().eq(packages.iter()),
582                    "scheduler workspace builder emitted packages {:?}, expected {packages:?}",
583                    pinned.keys().collect::<Vec<_>>(),
584                );
585                let mut source = crate::cache::artifact_tree::ArtifactTreeSource::new();
586                for (package, artifact) in pinned {
587                    let stable_path = artifact.source_path().to_path_buf();
588                    let stable_relative = stable_path.strip_prefix(&stable.root).map_err(|_| {
589                        anyhow::anyhow!(
590                            "scheduler artifact {} is outside stable Cargo output {}",
591                            stable_path.display(),
592                            stable.root.display(),
593                        )
594                    })?;
595                    anyhow::ensure!(
596                        stable_relative.starts_with("target"),
597                        "scheduler artifact {} is outside stable Cargo target {}",
598                        stable_path.display(),
599                        stable.target_directory.display(),
600                    );
601                    source.insert_immutable_pinned_file(
602                        Path::new("artifacts").join(package),
603                        artifact,
604                    )?;
605                    // Preserve the exact absolute Cargo output pathname as
606                    // part of the generic closure. Scheduler binaries may
607                    // embed OUT_DIR/CARGO_BIN_EXE paths even though consumers
608                    // execute the convenient `artifacts/<package>` alias.
609                    source.insert_immutable_path(stable_relative, &stable_path)?;
610                }
611                // The build closure (dependency objects and build-script
612                // OUT_DIRs) is deliberately not sealed here. Cargo now writes it
613                // to a persistent, non-source-keyed directory shared across
614                // digests for dependency and OUT_DIR reuse, and no scheduler
615                // consumer reads it: production snapshots the `artifacts/<pkg>`
616                // alias into the machine content CAS and executes from there.
617                // scx-ktstr's only OUT_DIR use is a compile-time `include!`, so
618                // nothing resolves the build closure at runtime.
619                Ok(source)
620            },
621        )
622        .map_err(|error| format!("{error:#}"))?;
623    let paths = packages
624        .iter()
625        .map(|package| (package.clone(), tree.root().join("artifacts").join(package)))
626        .collect();
627    let cache_hit = tree.cache_hit();
628    if let Err(error) = tree.persist_decision_diagnostic(
629        "scheduler-workspace",
630        serde_json::json!({
631            "namespace": SCHEDULER_ARTIFACT_TREE_NAMESPACE,
632            "normalized_inputs_digest": format!("{identity:016x}"),
633            "packages": packages,
634        }),
635    ) {
636        tracing::warn!(error = %error, "could not persist scheduler artifact-cache decision");
637    }
638    Ok(CachedSchedulerWorkspaceArtifacts {
639        paths,
640        tree,
641        cache_hit,
642    })
643}
644
645/// Atomically publish one immutable scheduler artifact manifest.
646pub fn write_scheduler_artifact_manifest(
647    directory: &Path,
648    manifest: &SchedulerArtifactManifest,
649) -> Result<PathBuf, String> {
650    use std::os::unix::fs::PermissionsExt;
651
652    let final_path = directory.join("scheduler-artifacts-v1.json");
653    let mut temporary = tempfile::NamedTempFile::new_in(directory).map_err(|error| {
654        format!(
655            "create temporary scheduler artifact manifest in {}: {error}",
656            directory.display()
657        )
658    })?;
659    serde_json::to_writer_pretty(temporary.as_file_mut(), manifest)
660        .map_err(|error| format!("serialize scheduler artifact manifest: {error}"))?;
661    temporary
662        .as_file()
663        .sync_all()
664        .map_err(|error| format!("sync scheduler artifact manifest: {error}"))?;
665    temporary
666        .as_file()
667        .set_permissions(std::fs::Permissions::from_mode(0o444))
668        .map_err(|error| format!("make scheduler artifact manifest read-only: {error}"))?;
669    temporary.persist(&final_path).map_err(|error| {
670        format!(
671            "atomically install scheduler artifact manifest {}: {}",
672            final_path.display(),
673            error.error,
674        )
675    })?;
676    std::fs::canonicalize(&final_path).map_err(|error| {
677        format!(
678            "canonicalize scheduler artifact manifest {}: {error}",
679            final_path.display()
680        )
681    })
682}
683
684#[cfg(test)]
685mod tests {
686    use super::*;
687    use std::os::unix::fs::{MetadataExt, PermissionsExt};
688
689    fn executable(dir: &Path) -> PathBuf {
690        let path = dir.join("scx_sched");
691        std::fs::write(&path, b"#!/bin/sh\nexit 0\n").expect("write executable");
692        std::fs::set_permissions(&path, std::fs::Permissions::from_mode(0o555))
693            .expect("chmod executable");
694        std::fs::canonicalize(path).expect("canonical executable")
695    }
696
697    fn write_manifest(
698        dir: &Path,
699        executable: &Path,
700        profile: String,
701    ) -> (PathBuf, SchedulerArtifactManifest) {
702        let manifest = SchedulerArtifactManifest {
703            version: SCHEDULER_ARTIFACT_MANIFEST_VERSION,
704            profile,
705            entries: vec![SchedulerArtifactEntry {
706                binary: SchedulerArtifactSpec::Discover("scx_sched".into()),
707                manifest_dir: "/workspace/member".into(),
708                schedulers: vec!["sched".into()],
709                path: executable.to_path_buf(),
710            }],
711        };
712        let path = dir.join("manifest.json");
713        std::fs::write(
714            &path,
715            serde_json::to_vec(&manifest).expect("serialize manifest"),
716        )
717        .expect("write manifest");
718        (path, manifest)
719    }
720
721    #[test]
722    fn absent_manifest_preserves_direct_resolution() {
723        assert!(
724            scheduler_artifact_from_manifest_path(
725                None,
726                None,
727                &SchedulerArtifactSpec::Discover("scx_sched".into()),
728                "/workspace/member",
729            )
730            .expect("absence is not an error")
731            .is_none(),
732        );
733    }
734
735    #[test]
736    fn manifest_requires_exact_identity_and_optional_scheduler_name() {
737        let dir = tempfile::tempdir().expect("tempdir");
738        let executable = executable(dir.path());
739        let (manifest_path, _) =
740            write_manifest(dir.path(), &executable, crate::scheduler_profile_name());
741
742        assert_eq!(
743            scheduler_artifact_from_manifest_path(
744                Some(manifest_path.as_os_str()),
745                Some("sched"),
746                &SchedulerArtifactSpec::Discover("scx_sched".into()),
747                "/workspace/member",
748            )
749            .expect("exact manifest lookup"),
750            Some(executable),
751        );
752        let wrong_dir = scheduler_artifact_from_manifest_path(
753            Some(manifest_path.as_os_str()),
754            None,
755            &SchedulerArtifactSpec::Discover("scx_sched".into()),
756            "/workspace/other",
757        )
758        .expect_err("manifest_dir is part of the exact identity");
759        assert!(
760            wrong_dir.to_string().contains("has no exact entry"),
761            "unexpected error: {wrong_dir:#}"
762        );
763        let wrong_scheduler = scheduler_artifact_from_manifest_path(
764            Some(manifest_path.as_os_str()),
765            Some("other"),
766            &SchedulerArtifactSpec::Discover("scx_sched".into()),
767            "/workspace/member",
768        )
769        .expect_err("verifier scheduler validation is exact");
770        assert!(
771            wrong_scheduler.to_string().contains("was not prepared"),
772            "unexpected error: {wrong_scheduler:#}"
773        );
774        let wrong_kind = scheduler_artifact_from_manifest_path(
775            Some(manifest_path.as_os_str()),
776            None,
777            &SchedulerArtifactSpec::Path("scx_sched".into()),
778            "/workspace/member",
779        )
780        .expect_err("Path and Discover identities never alias");
781        assert!(
782            wrong_kind.to_string().contains("has no exact entry"),
783            "unexpected error: {wrong_kind:#}"
784        );
785    }
786
787    #[test]
788    fn immutable_manifest_cache_tracks_atomic_path_replacement() {
789        let dir = tempfile::tempdir().expect("tempdir");
790        let first = executable(dir.path());
791        let second = dir.path().join("scx_sched_replacement");
792        std::fs::write(&second, b"#!/bin/sh\nexit 1\n").expect("write replacement executable");
793        std::fs::set_permissions(&second, std::fs::Permissions::from_mode(0o555))
794            .expect("chmod replacement executable");
795        let second = std::fs::canonicalize(second).expect("canonical replacement executable");
796        let mut manifest = SchedulerArtifactManifest {
797            version: SCHEDULER_ARTIFACT_MANIFEST_VERSION,
798            profile: crate::scheduler_profile_name(),
799            entries: vec![SchedulerArtifactEntry {
800                binary: SchedulerArtifactSpec::Discover("scx_sched".into()),
801                manifest_dir: "/workspace/member".into(),
802                schedulers: vec!["sched".into()],
803                path: first.clone(),
804            }],
805        };
806        let manifest_path =
807            write_scheduler_artifact_manifest(dir.path(), &manifest).expect("write first manifest");
808        assert_eq!(
809            scheduler_artifact_from_manifest_path(
810                Some(manifest_path.as_os_str()),
811                Some("sched"),
812                &SchedulerArtifactSpec::Discover("scx_sched".into()),
813                "/workspace/member",
814            )
815            .expect("resolve first immutable manifest"),
816            Some(first),
817        );
818
819        manifest.entries[0].path = second.clone();
820        assert_eq!(
821            write_scheduler_artifact_manifest(dir.path(), &manifest)
822                .expect("atomically replace immutable manifest"),
823            manifest_path,
824        );
825        assert_eq!(
826            scheduler_artifact_from_manifest_path(
827                Some(manifest_path.as_os_str()),
828                Some("sched"),
829                &SchedulerArtifactSpec::Discover("scx_sched".into()),
830                "/workspace/member",
831            )
832            .expect("resolve replacement immutable manifest"),
833            Some(second),
834            "the process-local parse memo must key the exact inode revision",
835        );
836    }
837
838    #[test]
839    fn lookup_only_stats_the_exact_artifact_but_still_validates_the_wire() {
840        let dir = tempfile::tempdir().expect("tempdir");
841        let executable = executable(dir.path());
842        let (manifest_path, mut manifest) =
843            write_manifest(dir.path(), &executable, crate::scheduler_profile_name());
844        manifest.entries.push(SchedulerArtifactEntry {
845            binary: SchedulerArtifactSpec::Discover("unrelated".into()),
846            manifest_dir: "/workspace/other".into(),
847            schedulers: vec!["other".into()],
848            path: dir.path().join("missing-unrelated-artifact"),
849        });
850        std::fs::write(
851            &manifest_path,
852            serde_json::to_vec(&manifest).expect("serialize manifest"),
853        )
854        .expect("write manifest");
855
856        assert_eq!(
857            scheduler_artifact_from_manifest_path(
858                Some(manifest_path.as_os_str()),
859                Some("sched"),
860                &SchedulerArtifactSpec::Discover("scx_sched".into()),
861                "/workspace/member",
862            )
863            .expect("unrelated artifact paths are not touched"),
864            Some(executable),
865        );
866
867        manifest.entries[1].schedulers.clear();
868        std::fs::write(
869            &manifest_path,
870            serde_json::to_vec(&manifest).expect("serialize malformed manifest"),
871        )
872        .expect("write malformed manifest");
873        let error = scheduler_artifact_from_manifest_path(
874            Some(manifest_path.as_os_str()),
875            Some("sched"),
876            &SchedulerArtifactSpec::Discover("scx_sched".into()),
877            "/workspace/member",
878        )
879        .expect_err("structural validation remains manifest-wide");
880        assert!(
881            error.to_string().contains("no requiring scheduler names"),
882            "unexpected error: {error:#}"
883        );
884    }
885
886    #[test]
887    fn present_manifest_never_degrades_to_fallback() {
888        let dir = tempfile::tempdir().expect("tempdir");
889        let malformed = dir.path().join("malformed.json");
890        std::fs::write(&malformed, b"{").expect("write malformed manifest");
891        let error = scheduler_artifact_from_manifest_path(
892            Some(malformed.as_os_str()),
893            None,
894            &SchedulerArtifactSpec::Discover("pkg".into()),
895            "/workspace",
896        )
897        .expect_err("malformed present manifest is fatal");
898        assert!(
899            error
900                .to_string()
901                .contains("parse scheduler artifact manifest"),
902            "unexpected error: {error:#}"
903        );
904
905        let executable = executable(dir.path());
906        let (missing_path, mut manifest) =
907            write_manifest(dir.path(), &executable, crate::scheduler_profile_name());
908        manifest.entries[0].path = dir.path().join("does-not-exist");
909        std::fs::write(
910            &missing_path,
911            serde_json::to_vec(&manifest).expect("serialize manifest"),
912        )
913        .expect("write missing artifact manifest");
914        let error = scheduler_artifact_from_manifest_path(
915            Some(missing_path.as_os_str()),
916            None,
917            &SchedulerArtifactSpec::Discover("scx_sched".into()),
918            "/workspace/member",
919        )
920        .expect_err("missing artifact is fatal");
921        assert!(
922            error
923                .to_string()
924                .contains("canonicalize scheduler artifact"),
925            "unexpected error: {error:#}"
926        );
927
928        manifest.entries[0].path = executable;
929        manifest.profile = format!("{}-other", crate::scheduler_profile_name());
930        std::fs::write(
931            &missing_path,
932            serde_json::to_vec(&manifest).expect("serialize mismatched manifest"),
933        )
934        .expect("write mismatched manifest");
935        let error = scheduler_artifact_from_manifest_path(
936            Some(missing_path.as_os_str()),
937            None,
938            &SchedulerArtifactSpec::Discover("scx_sched".into()),
939            "/workspace/member",
940        )
941        .expect_err("profile mismatch is fatal");
942        assert!(
943            error.to_string().contains("was built with profile"),
944            "unexpected error: {error:#}"
945        );
946    }
947
948    #[test]
949    fn snapshot_publishes_across_filesystems_via_byte_copy() {
950        use crate::test_support::test_helpers::{EnvVarGuard, lock_env};
951
952        let _environment = lock_env();
953        // /dev/shm is tmpfs on every supported host: it can never reflink
954        // (no remap_file_range) and is a different mount from the cache
955        // tempdir below, so publication from here always exercises the
956        // cross-filesystem byte-copy fallback — the shape a user hits when
957        // their project checkout and KTSTR_CACHE_DIR live on different
958        // mounts.
959        let source_dir = tempfile::tempdir_in("/dev/shm").expect("tmpfs source tempdir");
960        let cache_dir = tempfile::tempdir().expect("cache tempdir");
961        let _cache = EnvVarGuard::set(crate::KTSTR_CACHE_DIR_ENV, cache_dir.path());
962        let source = source_dir.path().join("scheduler");
963        std::fs::write(&source, b"cross-fs scheduler bytes").expect("write source");
964        std::fs::set_permissions(&source, std::fs::Permissions::from_mode(0o755))
965            .expect("chmod source");
966
967        let snapshot = snapshot_scheduler_artifact(&source).expect("snapshot across filesystems");
968        assert_eq!(
969            std::fs::read(snapshot.path()).expect("read snapshot"),
970            b"cross-fs scheduler bytes",
971        );
972        assert_eq!(
973            std::fs::metadata(snapshot.path())
974                .expect("stat snapshot")
975                .permissions()
976                .mode()
977                & 0o7777,
978            0o555,
979            "byte-copied publication must land with the same immutable mode \
980             as a reflinked one",
981        );
982    }
983
984    #[test]
985    fn snapshot_pins_bytes_and_inode_across_source_replacement() {
986        use crate::test_support::test_helpers::{EnvVarGuard, lock_env};
987
988        let _environment = lock_env();
989        let source_dir = tempfile::tempdir().expect("source tempdir");
990        let _cache = EnvVarGuard::set(crate::KTSTR_CACHE_DIR_ENV, source_dir.path().join("cache"));
991        let source = source_dir.path().join("scheduler");
992        std::fs::write(&source, b"old scheduler bytes").expect("write source");
993        std::fs::set_permissions(&source, std::fs::Permissions::from_mode(0o755))
994            .expect("chmod source");
995
996        let snapshot = snapshot_scheduler_artifact(&source).expect("snapshot scheduler");
997        let replacement = source_dir.path().join("replacement");
998        std::fs::write(&replacement, b"new scheduler bytes").expect("write replacement");
999        std::fs::set_permissions(&replacement, std::fs::Permissions::from_mode(0o755))
1000            .expect("chmod replacement");
1001        std::fs::rename(&replacement, &source).expect("atomically replace source");
1002
1003        assert_eq!(
1004            std::fs::read(snapshot.path()).expect("read snapshot"),
1005            b"old scheduler bytes",
1006        );
1007        assert_eq!(
1008            std::fs::metadata(snapshot.path())
1009                .expect("stat snapshot")
1010                .permissions()
1011                .mode()
1012                & 0o777,
1013            0o555,
1014        );
1015        assert_ne!(
1016            std::fs::metadata(snapshot.path())
1017                .expect("stat snapshot")
1018                .ino(),
1019            std::fs::metadata(&source).expect("stat replacement").ino(),
1020            "the child artifact must remain a parent-owned immutable inode",
1021        );
1022    }
1023
1024    #[test]
1025    fn scheduler_workspace_build_uses_generic_artifact_tree_and_skips_warm_builder() {
1026        use std::sync::atomic::{AtomicUsize, Ordering};
1027
1028        let root = tempfile::tempdir().expect("scheduler artifact-tree root");
1029        let source = root.path().join("scheduler-source");
1030        std::fs::write(&source, b"generic-scheduler-tree").expect("write scheduler fixture");
1031        std::fs::set_permissions(&source, std::fs::Permissions::from_mode(0o755))
1032            .expect("chmod scheduler fixture");
1033        let packages = vec!["scx_generic_cache".to_string()];
1034        let builds = AtomicUsize::new(0);
1035        let first = load_or_build_scheduler_workspace_artifacts_at_root(
1036            root.path(),
1037            0x5ced_7aee,
1038            &packages,
1039            "cargo ktstr test",
1040            || Ok(true),
1041            || false,
1042            || {
1043                builds.fetch_add(1, Ordering::SeqCst);
1044                Ok(BTreeMap::from([(
1045                    packages[0].clone(),
1046                    crate::cache::pin_content_file(&source).map_err(|error| error.to_string())?,
1047                )]))
1048            },
1049        )
1050        .expect("cold scheduler artifact tree");
1051        assert!(!first.cache_hit);
1052        assert_eq!(
1053            std::fs::read(&first.paths[&packages[0]]).expect("read cold scheduler artifact"),
1054            b"generic-scheduler-tree",
1055        );
1056        drop(first);
1057
1058        let hit = load_or_build_scheduler_workspace_artifacts_at_root(
1059            root.path(),
1060            0x5ced_7aee,
1061            &packages,
1062            "cargo ktstr test",
1063            || Ok(true),
1064            || false,
1065            || -> Result<BTreeMap<String, crate::cache::PinnedContentFile>, String> {
1066                panic!("a generic artifact-tree hit must not invoke the Cargo builder")
1067            },
1068        )
1069        .expect("warm scheduler artifact tree");
1070        assert!(hit.cache_hit);
1071        assert_eq!(
1072            std::fs::read(&hit.paths[&packages[0]]).expect("read warm scheduler artifact"),
1073            b"generic-scheduler-tree",
1074        );
1075        assert_eq!(builds.load(Ordering::SeqCst), 1);
1076    }
1077
1078    /// The sealed per-source tree preserves the scheduler binary at both the
1079    /// convenient `artifacts/<pkg>` alias and its exact Cargo output pathname,
1080    /// but deliberately does **not** preserve the Cargo build closure
1081    /// (dependency objects, build-script `OUT_DIR`s).
1082    ///
1083    /// Production consumes only the `artifacts/<pkg>` alias — it snapshots that
1084    /// executable into the machine content CAS and executes from there, never
1085    /// resolving the build closure at runtime (scx-ktstr's sole `OUT_DIR` use is
1086    /// a compile-time `include!`). The build closure now lives in a persistent,
1087    /// non-source-keyed directory shared across source digests so Cargo reuses
1088    /// unchanged dependencies; sealing a per-source copy of it would be dead
1089    /// weight. Even when the producer writes an `OUT_DIR` payload under the
1090    /// stable root, distillation retains only `target/`.
1091    #[test]
1092    fn stable_scheduler_workspace_seals_target_alias_but_not_build_closure() {
1093        use crate::test_support::test_helpers::{EnvVarGuard, lock_env};
1094
1095        let _environment = lock_env();
1096        let temp = tempfile::tempdir().unwrap();
1097        let cache_root = temp.path().join("cache");
1098        let _cache = EnvVarGuard::set(crate::KTSTR_CACHE_DIR_ENV, &cache_root);
1099        let identity = 0x5ced_57ab;
1100        let packages = vec!["scx_stable_cache".to_string()];
1101
1102        let cached = load_or_build_scheduler_workspace_artifacts_stable(
1103            identity,
1104            &packages,
1105            "stable scheduler artifact-tree test",
1106            || Ok(true),
1107            || false,
1108            |stable| {
1109                let scheduler = stable.target_directory.join("release/scx_stable_cache");
1110                let out_file = stable.root.join("build/scx-stable/out/generated");
1111                std::fs::create_dir_all(scheduler.parent().unwrap())
1112                    .map_err(|error| error.to_string())?;
1113                std::fs::create_dir_all(out_file.parent().unwrap())
1114                    .map_err(|error| error.to_string())?;
1115                std::fs::write(&scheduler, b"stable scheduler")
1116                    .map_err(|error| error.to_string())?;
1117                std::fs::set_permissions(&scheduler, std::fs::Permissions::from_mode(0o755))
1118                    .map_err(|error| error.to_string())?;
1119                std::fs::write(&out_file, b"embedded OUT_DIR payload")
1120                    .map_err(|error| error.to_string())?;
1121                let junk = stable.target_directory.join("release/deps/unrecorded");
1122                std::fs::create_dir_all(&junk).map_err(|error| error.to_string())?;
1123                std::fs::write(junk.join("junk"), b"discard").map_err(|error| error.to_string())?;
1124                Ok(BTreeMap::from([(
1125                    packages[0].clone(),
1126                    crate::cache::pin_content_file(&scheduler)
1127                        .map_err(|error| error.to_string())?,
1128                )]))
1129            },
1130        )
1131        .unwrap();
1132
1133        assert_eq!(
1134            std::fs::read(&cached.paths[&packages[0]]).unwrap(),
1135            b"stable scheduler",
1136        );
1137        assert_eq!(
1138            std::fs::read(cached.tree.root().join("target/release/scx_stable_cache")).unwrap(),
1139            b"stable scheduler",
1140        );
1141        // The build closure is intentionally not part of the sealed tree.
1142        assert!(
1143            !cached.tree.root().join("build").exists(),
1144            "the build closure must not be preserved in the materialized tree",
1145        );
1146        let stable_root = cache_root
1147            .join("stable-builds-v1")
1148            .join(format!("{identity:016x}"));
1149        assert!(
1150            stable_root
1151                .join("target/release/scx_stable_cache")
1152                .is_file()
1153        );
1154        // Distillation retains only `target/`; any `build/` the producer wrote
1155        // under the stable root is discarded, along with unrecorded deps.
1156        assert!(
1157            !stable_root.join("build").exists(),
1158            "distillation must not seal the build closure under the stable root",
1159        );
1160        assert!(!stable_root.join("target/release/deps/unrecorded").exists());
1161    }
1162}