Skip to main content

varve_core/
store.rs

1//! The core — the local content-addressed store (REQ-COEXIST-001, DD-006).
2//!
3//! ```text
4//! <root>/core/sha256-<hex>/          # one layer, keyed by its manifest digest
5//!   layer.json                       # the layer manifest, kept for verify/archive
6//!   bin/<tool>                       # the tools — dispatched by name
7//!   payloads/<name>/<version>        # everything else — held by name AND version
8//! ```
9//!
10//! The split is REQ-STORE-002. A tool is dispatched by name (`varve which`,
11//! `varve run`, the argv[0] shims), so a name must resolve to exactly one
12//! binary and `bin/<name>` is right. A crate, a WIT package, an SDK or a wasm
13//! component is not dispatched at all, and a dependency graph ordinarily holds
14//! several versions of one name — laying those down by name alone made the
15//! second entry silently overwrite the first's bytes.
16//!
17//! Keyed by manifest digest, so layers coexist by construction: installing
18//! August cannot disturb July, and selecting either costs no download.
19//! The store is written at lay-down time and read-only ever after — nothing
20//! in resolution or listing mutates it (REQ-SCOPE-001's read-only half).
21
22use std::collections::BTreeMap;
23use std::path::{Path, PathBuf};
24
25use serde::Deserialize;
26use sha2::{Digest, Sha256};
27
28use crate::layer::LayerId;
29use crate::manifest::ManifestEntry;
30
31/// The directory holding non-dispatchable payloads, keyed by name AND version.
32pub const PAYLOAD_DIR: &str = "payloads";
33
34/// One payload to lay down. What it *is* decides where it lands: a dispatchable
35/// payload is placed by name, everything else by name and version.
36#[derive(Debug, Clone, Copy)]
37pub struct Payload<'a> {
38    pub name: &'a str,
39    /// The version from the signed manifest. Absent only for pre-kind layers
40    /// and for tools, which are not keyed by version.
41    pub version: Option<&'a str>,
42    /// Dispatched by name — see `PayloadKind::is_dispatchable`.
43    pub dispatchable: bool,
44    /// What this payload BUILDS FOR, when that differs from what runs it
45    /// (REQ-SDKTARGET-001 clause 1). `platform` says which machine executes
46    /// these bytes; `target` says which machine the artefacts they produce
47    /// will run on. For a compiler you invoke they are the same question and
48    /// this is `None`; for a cross-toolchain they are different, and the PAIR
49    /// is what identifies the payload.
50    pub target: Option<&'a str>,
51    pub bytes: &'a [u8],
52}
53
54impl<'a> Payload<'a> {
55    /// A dispatchable tool binary: `bin/<name>`, the original layout.
56    pub fn tool(name: &'a str, bytes: &'a [u8]) -> Self {
57        Payload {
58            name,
59            version: None,
60            dispatchable: true,
61            target: None,
62            bytes,
63        }
64    }
65
66    /// A payload that builds for a target other than the machine running it:
67    /// `payloads/<name>/<version>/<target>`.
68    pub fn targeted(name: &'a str, version: &'a str, target: &'a str, bytes: &'a [u8]) -> Self {
69        Payload {
70            name,
71            version: Some(version),
72            dispatchable: false,
73            target: Some(target),
74            bytes,
75        }
76    }
77}
78
79/// Is this manifest entry dispatched by name (REQ-STORE-002 clause 1)?
80///
81/// An entry with no kind annotation is a `tool` (pre-kind layers), so it is.
82/// An entry whose kind THIS build does not recognise is not: varve cannot
83/// dispatch what it cannot classify, and placing an unknown kind by name alone
84/// is exactly the overwrite this requirement exists to prevent — a newer
85/// varve's versioned kind must not collapse onto one path here.
86pub fn entry_is_dispatchable(entry: &ManifestEntry) -> bool {
87    matches!(entry.kind(), Ok(kind) if kind.is_dispatchable())
88}
89
90/// The version a manifest entry declares, if any.
91pub fn entry_version(entry: &ManifestEntry) -> Option<&str> {
92    entry
93        .annotations
94        .get("eu.pulseengine.tool.version")
95        .map(String::as_str)
96}
97
98/// Refuse a name or version that is not a single, safe path component. These
99/// strings come out of a signed manifest, but "signed" means "attributable",
100/// not "benign": a realm root signing `../../evil` must not be able to place
101/// bytes outside the layer it is laying down.
102fn safe_component(what: &'static str, value: &str) -> Result<(), StoreError> {
103    let bad = |why: &str| {
104        Err(StoreError::UnsafeComponent {
105            what,
106            value: value.to_string(),
107            why: why.to_string(),
108        })
109    };
110    if value.is_empty() {
111        return bad("empty");
112    }
113    if value == "." || value == ".." {
114        return bad("a relative path element");
115    }
116    if let Some(c) = value
117        .chars()
118        .find(|c| matches!(c, '/' | '\\' | '\0') || c.is_control())
119    {
120        return bad(&format!("contains {c:?}"));
121    }
122    Ok(())
123}
124
125/// Where a payload lives inside a layer root, relative to it (clause 2).
126///
127/// Dispatchable → `bin/<name>`, unchanged and byte-compatible with every layer
128/// installed before this requirement. Non-dispatchable with a version →
129/// `payloads/<name>/<version>`, so `serde@1.0.200` and `serde@1.0.210` are two
130/// files, not one file written twice. A non-dispatchable payload with NO
131/// version keeps the legacy `bin/<name>` place — that is what a pre-kind layer
132/// looks like on disk, and the collision guard in `lay_down` still refuses to
133/// let two of them land on one path.
134pub fn payload_rel_path(
135    dispatchable: bool,
136    name: &str,
137    version: Option<&str>,
138    target: Option<&str>,
139) -> Result<PathBuf, StoreError> {
140    safe_component("payload name", name)?;
141    match (dispatchable, version) {
142        (false, Some(version)) => {
143            safe_component("payload version", version)?;
144            let at = PathBuf::from(PAYLOAD_DIR).join(name).join(version);
145            // The target is the LAST component, so a payload that declares
146            // none keeps the exact path it had before this dimension existed
147            // (clause 4) and a layer installed by an older varve is still
148            // found where it was put.
149            match target {
150                Some(target) => {
151                    safe_component("payload target", target)?;
152                    Ok(at.join(target))
153                }
154                None => Ok(at),
155            }
156        }
157        _ => Ok(PathBuf::from("bin").join(name)),
158    }
159}
160
161/// The minimal slice of a layer manifest the store needs: the annotations
162/// carrying the layer identity. Everything else is preserved verbatim in
163/// `layer.json` for later verification and archiving.
164#[derive(Debug, Clone, Deserialize)]
165struct ManifestEnvelope {
166    #[serde(default)]
167    annotations: BTreeMap<String, String>,
168}
169
170/// One layer present in the core.
171#[derive(Debug, Clone, PartialEq, Eq)]
172pub struct InstalledLayer {
173    /// `sha256:<hex>` of the manifest bytes — the store key.
174    pub digest: String,
175    /// The layer identity from the manifest annotations.
176    pub layer: LayerId,
177    /// The channel annotation (`qualified` / `rolling`), verbatim.
178    pub channel: String,
179    /// Root directory of this layer in the core.
180    pub root: PathBuf,
181    /// The platform this layer was INSTALLED FOR, where the install recorded
182    /// one (`varve install --platform`, or the host at install time).
183    ///
184    /// `verify` must filter by this and not by the host it happens to be run
185    /// on. Installing a Linux toolchain from a Mac is legitimate — building or
186    /// inspecting one — and before this, `verify` resolved the HOST, found the
187    /// darwin entry, hashed the linux bytes that were actually laid down, and
188    /// reported "its bytes were altered" about bytes nobody had touched
189    /// (varve#189). A trust tool that cries wolf teaches people to ignore it.
190    ///
191    /// `None` for layers installed before this was recorded; callers fall back
192    /// to the host, which is what they did for all of them.
193    ///
194    /// This file is LOCAL state and is not signed, which is safe in one
195    /// direction only: a tampered value can name a platform whose payloads
196    /// were never laid down (`MissingTool`), or one the layer has no entries
197    /// for (`NothingToVerify`), or one whose digests do not match what is on
198    /// disk (`ToolDigestMismatch`). Every outcome is a refusal. It cannot
199    /// cause a verification to pass that would otherwise fail.
200    pub platform: Option<String>,
201}
202
203/// The core store rooted at a directory (defaults to `~/.varve` in the CLI;
204/// injectable here so tests and future tools own their roots).
205#[derive(Debug, Clone)]
206pub struct Store {
207    root: PathBuf,
208}
209
210/// Store failures. Note what is *absent*: there is no variant for "fell back
211/// to another layer" — the API cannot express fallback.
212#[derive(Debug, thiserror::Error)]
213pub enum StoreError {
214    #[error("io error at {path}")]
215    Io {
216        path: String,
217        #[source]
218        source: std::io::Error,
219    },
220    #[error("{path}: layer.json is not a valid layer manifest: {reason}")]
221    BadManifest { path: String, reason: String },
222    #[error("{what} {value:?} is not a usable path component ({why}) — refusing to lay it down")]
223    UnsafeComponent {
224        what: &'static str,
225        value: String,
226        why: String,
227    },
228    #[error(
229        "two payloads of this layer both claim {path} ('{first}' and '{second}') — refusing to \
230         lay one down over the other. A layer may hold several versions of one name, but each \
231         must be a distinct payload; two entries with one identity would mean the wrong bytes \
232         land under the right name."
233    )]
234    Collision {
235        path: String,
236        first: String,
237        second: String,
238    },
239}
240
241impl Store {
242    pub fn at(root: impl Into<PathBuf>) -> Self {
243        Store { root: root.into() }
244    }
245
246    pub fn root(&self) -> &Path {
247        &self.root
248    }
249
250    /// Lay a layer down in the core from its manifest bytes and tool
251    /// binaries. Returns the manifest digest (`sha256:<hex>`) — the store key.
252    ///
253    /// The dispatchable-only convenience over [`Store::lay_down_payloads`],
254    /// which is the single writer.
255    pub fn lay_down(
256        &self,
257        manifest_bytes: &[u8],
258        tools: &[(&str, &[u8])],
259    ) -> Result<String, StoreError> {
260        let payloads: Vec<Payload<'_>> = tools
261            .iter()
262            .map(|(name, bytes)| Payload::tool(name, bytes))
263            .collect();
264        self.lay_down_payloads(manifest_bytes, &payloads)
265    }
266
267    /// Lay a layer down in the core from its manifest bytes and its payloads.
268    /// Returns the manifest digest (`sha256:<hex>`) — the store key.
269    ///
270    /// This is the write path shared by the installer and by tests; nothing
271    /// else writes to the core. Two payloads that would land on ONE path are
272    /// refused (`StoreError::Collision`) rather than written in turn: relaxing
273    /// the deposit-time identity check without this would turn a clean error
274    /// into silent data loss — the second entry's bytes under the first's name,
275    /// with verification then failing on the *other* entry and nothing
276    /// explaining why (REQ-STORE-002).
277    pub fn lay_down_payloads(
278        &self,
279        manifest_bytes: &[u8],
280        payloads: &[Payload<'_>],
281    ) -> Result<String, StoreError> {
282        let digest = manifest_digest(manifest_bytes);
283        let entry = self.core_dir().join(digest.replace(':', "-"));
284        let io = |path: &Path, source: std::io::Error| StoreError::Io {
285            path: path.display().to_string(),
286            source,
287        };
288
289        // Resolve every destination BEFORE writing anything: an unusable name
290        // or a collision must leave the core untouched, not half-written.
291        let mut placed: BTreeMap<PathBuf, String> = BTreeMap::new();
292        let mut plan: Vec<(PathBuf, &Payload<'_>)> = Vec::new();
293        for payload in payloads {
294            let rel = payload_rel_path(
295                payload.dispatchable,
296                payload.name,
297                payload.version,
298                payload.target,
299            )?;
300            let who = match (payload.version, payload.target) {
301                (Some(v), Some(t)) => format!("{}@{v} for {t}", payload.name),
302                (Some(v), None) => format!("{}@{v}", payload.name),
303                (None, _) => payload.name.to_string(),
304            };
305            if let Some(first) = placed.get(&rel) {
306                return Err(StoreError::Collision {
307                    path: rel.display().to_string(),
308                    first: first.clone(),
309                    second: who,
310                });
311            }
312            placed.insert(rel.clone(), who);
313            plan.push((rel, payload));
314        }
315
316        let bin = entry.join("bin");
317        std::fs::create_dir_all(&bin).map_err(|e| io(&bin, e))?;
318        let manifest_path = entry.join("layer.json");
319        std::fs::write(&manifest_path, manifest_bytes).map_err(|e| io(&manifest_path, e))?;
320        for (rel, payload) in plan {
321            let path = entry.join(rel);
322            if let Some(parent) = path.parent() {
323                std::fs::create_dir_all(parent).map_err(|e| io(parent, e))?;
324            }
325            std::fs::write(&path, payload.bytes).map_err(|e| io(&path, e))?;
326            #[cfg(unix)]
327            {
328                use std::os::unix::fs::PermissionsExt;
329                // Only what is dispatched gets the execute bit. A `.crate`
330                // tarball or a WIT package is data varve hands to another tool.
331                let mode = if payload.dispatchable { 0o755 } else { 0o644 };
332                std::fs::set_permissions(&path, std::fs::Permissions::from_mode(mode))
333                    .map_err(|e| io(&path, e))?;
334            }
335        }
336        Ok(digest)
337    }
338
339    /// Every layer present in the core, in stable (digest) order.
340    pub fn list(&self) -> Result<Vec<InstalledLayer>, StoreError> {
341        let core = self.core_dir();
342        if !core.exists() {
343            return Ok(Vec::new());
344        }
345        let mut names: Vec<String> = std::fs::read_dir(&core)
346            .map_err(|e| StoreError::Io {
347                path: core.display().to_string(),
348                source: e,
349            })?
350            .filter_map(|e| e.ok())
351            .filter(|e| e.path().is_dir())
352            .map(|e| e.file_name().to_string_lossy().into_owned())
353            .filter(|n| n.starts_with("sha256-"))
354            .collect();
355        names.sort();
356        names
357            .into_iter()
358            .map(|name| self.read_entry(&name.replacen('-', ":", 1)))
359            .collect()
360    }
361
362    /// Look up a layer by manifest digest (`sha256:<hex>`).
363    /// The varve root this store lives under: itself, or the parent of a realm
364    /// partition (`<root>/realms/<fingerprint>`).
365    pub fn varve_root(&self) -> std::path::PathBuf {
366        let root = self.root();
367        if root
368            .parent()
369            .and_then(|p| p.file_name())
370            .is_some_and(|n| n == "realms")
371        {
372            root.parent()
373                .and_then(|p| p.parent())
374                .map(|p| p.to_path_buf())
375                .unwrap_or_else(|| root.to_path_buf())
376        } else {
377            root.to_path_buf()
378        }
379    }
380
381    /// Every partition under this varve root: the top-level core first, then
382    /// each realm partition in a stable order, paired with the realm
383    /// fingerprint that names it (`None` for the top-level core, which is not
384    /// realm-scoped).
385    ///
386    /// `find_anywhere` had this enumeration inline and private, so a caller
387    /// that needed to WALK the store rather than look one digest up had no way
388    /// to do it — which is how `verify --all` came to check only the pinned
389    /// realm's partition while its `--help` promised every installed layer
390    /// (REQ-VERIFYALL-001, varve#84).
391    pub fn partitions(&self) -> Vec<(Option<String>, Store)> {
392        let root = self.varve_root();
393        let mut out: Vec<(Option<String>, Store)> = vec![(None, Store::at(&root))];
394        if let Ok(rd) = std::fs::read_dir(root.join("realms")) {
395            let mut parts: Vec<std::path::PathBuf> =
396                rd.filter_map(|e| e.ok()).map(|e| e.path()).collect();
397            parts.sort();
398            for p in parts {
399                let fp = p.file_name().map(|n| n.to_string_lossy().into_owned());
400                out.push((fp, Store::at(p)));
401            }
402        }
403        out
404    }
405
406    /// Find a layer by digest in ANY partition under this varve root — the
407    /// top-level core or any realm's. A digest is content-addressed, so where
408    /// it happens to live does not change what it is; a cross-realm composition
409    /// include is installed under the INCLUDED realm's fingerprint, not the
410    /// including project's, and looking only in one partition reported it as
411    /// missing while `list` showed it installed (REQ-STORE-001).
412    ///
413    /// Locating a layer is not accepting it: the caller still verifies it
414    /// against the trust root of the realm that vouches for it.
415    pub fn find_anywhere(
416        &self,
417        digest: &str,
418    ) -> Result<Option<(Store, InstalledLayer)>, StoreError> {
419        if let Some(entry) = self.get(digest)? {
420            return Ok(Some((self.clone(), entry)));
421        }
422        let root = self.varve_root();
423        // The top-level core, then every realm partition, in a stable order.
424        let mut candidates = vec![Store::at(&root)];
425        if let Ok(rd) = std::fs::read_dir(root.join("realms")) {
426            let mut parts: Vec<std::path::PathBuf> =
427                rd.filter_map(|e| e.ok()).map(|e| e.path()).collect();
428            parts.sort();
429            candidates.extend(parts.into_iter().map(Store::at));
430        }
431        for candidate in candidates {
432            if candidate.root() == self.root() {
433                continue;
434            }
435            if let Some(entry) = candidate.get(digest)? {
436                return Ok(Some((candidate, entry)));
437            }
438        }
439        Ok(None)
440    }
441
442    pub fn get(&self, digest: &str) -> Result<Option<InstalledLayer>, StoreError> {
443        let entry = self.core_dir().join(digest.replace(':', "-"));
444        if !entry.join("layer.json").is_file() {
445            return Ok(None);
446        }
447        self.read_entry(digest).map(Some)
448    }
449
450    /// Path of one tool's binary within an installed layer, if present.
451    /// Dispatch is by name, so this takes a bare name — see `entry_path` for
452    /// payloads that are held rather than dispatched.
453    pub fn tool_path(&self, layer: &InstalledLayer, tool: &str) -> Option<PathBuf> {
454        let path = layer.root.join("bin").join(tool);
455        path.is_file().then_some(path)
456    }
457
458    /// Path of the bytes one MANIFEST ENTRY refers to within an installed
459    /// layer, if present. This is the read side of `lay_down_payloads`, and
460    /// every consumer of a layer's bytes (`verify`, `archive`, the export
461    /// adapters) goes through it so the two cannot drift.
462    ///
463    /// Backward compatibility: a layer installed BEFORE REQ-STORE-002 holds its
464    /// crates at `bin/<name>`, so a versioned payload that is not at its
465    /// versioned path falls back there. Such a layer can hold only one version
466    /// per name — the old deposit check made sure of it — so the fallback is
467    /// unambiguous.
468    pub fn entry_path(&self, layer: &InstalledLayer, entry: &ManifestEntry) -> Option<PathBuf> {
469        let name = entry.annotations.get("eu.pulseengine.tool")?;
470        let dispatchable = entry_is_dispatchable(entry);
471        let rel = payload_rel_path(
472            dispatchable,
473            name,
474            entry_version(entry),
475            crate::platform::entry_target(entry),
476        )
477        .ok()?;
478        let path = layer.root.join(rel);
479        if path.is_file() {
480            return Some(path);
481        }
482        (!dispatchable)
483            .then(|| layer.root.join("bin").join(name))
484            .filter(|legacy| legacy.is_file())
485    }
486
487    fn core_dir(&self) -> PathBuf {
488        self.root.join("core")
489    }
490
491    fn read_entry(&self, digest: &str) -> Result<InstalledLayer, StoreError> {
492        let root = self.core_dir().join(digest.replace(':', "-"));
493        let manifest_path = root.join("layer.json");
494        let bad = |reason: String| StoreError::BadManifest {
495            path: manifest_path.display().to_string(),
496            reason,
497        };
498        let bytes = std::fs::read(&manifest_path).map_err(|source| StoreError::Io {
499            path: manifest_path.display().to_string(),
500            source,
501        })?;
502        let envelope: ManifestEnvelope =
503            serde_json::from_slice(&bytes).map_err(|e| bad(e.to_string()))?;
504        let layer_str = envelope
505            .annotations
506            .get("eu.pulseengine.varve.layer")
507            .ok_or_else(|| bad("missing eu.pulseengine.varve.layer annotation".into()))?;
508        let layer: LayerId = layer_str
509            .parse()
510            .map_err(|e: crate::layer::LayerIdError| bad(e.to_string()))?;
511        let channel = envelope
512            .annotations
513            .get("eu.pulseengine.varve.channel")
514            .cloned()
515            .unwrap_or_default();
516        let platform = std::fs::read_to_string(root.join(INSTALL_FILE))
517            .ok()
518            .and_then(|t| serde_json::from_str::<InstallRecord>(&t).ok())
519            .map(|r| r.platform);
520        Ok(InstalledLayer {
521            digest: digest.to_string(),
522            layer,
523            channel,
524            root,
525            platform,
526        })
527    }
528}
529
530/// What the install recorded about itself, beside the layer it laid down.
531pub const INSTALL_FILE: &str = "installed.json";
532
533#[derive(Debug, serde::Serialize, serde::Deserialize)]
534struct InstallRecord {
535    platform: String,
536}
537
538/// Record the platform a layer was laid down FOR.
539///
540/// Written by `install` after the lay-down, so `verify` filters by the
541/// decision the install made rather than re-deriving one from the host it is
542/// run on — the shape that has cost this codebase repeatedly.
543pub fn record_install_platform(root: &Path, platform: &str) -> Result<(), StoreError> {
544    let path = root.join(INSTALL_FILE);
545    let body = serde_json::to_vec_pretty(&InstallRecord {
546        platform: platform.to_string(),
547    })
548    .map_err(|e| StoreError::Io {
549        path: path.display().to_string(),
550        source: std::io::Error::other(e),
551    })?;
552    std::fs::write(&path, body).map_err(|source| StoreError::Io {
553        path: path.display().to_string(),
554        source,
555    })
556}
557
558/// Compute the store key for manifest bytes: `sha256:<hex>`.
559impl Store {
560    /// Every tool name the layer's SIGNED manifest carries, whatever this host
561    /// laid down. Used to tell "the pin asks for something that was never in
562    /// this layer" apart from "the install is incomplete" — the two need
563    /// opposite advice, and conflating them produced an error whose stated fix
564    /// could not work.
565    pub fn manifest_tool_names(&self, layer: &InstalledLayer) -> Result<Vec<String>, StoreError> {
566        let payload = std::fs::read(layer.root.join("layer.json")).map_err(|e| StoreError::Io {
567            path: layer.root.join("layer.json").display().to_string(),
568            source: e,
569        })?;
570        let json: serde_json::Value = match serde_json::from_slice(&payload) {
571            Ok(j) => j,
572            Err(_) => return Ok(Vec::new()),
573        };
574        Ok(json["manifests"]
575            .as_array()
576            .map(|es| {
577                es.iter()
578                    .filter_map(|e| e["annotations"]["eu.pulseengine.tool"].as_str())
579                    .map(str::to_string)
580                    .collect()
581            })
582            .unwrap_or_default())
583    }
584}
585
586pub fn manifest_digest(bytes: &[u8]) -> String {
587    format!("sha256:{}", hex::encode(Sha256::digest(bytes)))
588}
589
590/// Buffer size for [`digest_file`]. Large enough that syscall overhead is
591/// negligible against a GB-scale payload, small enough that the memory a
592/// digest costs is a constant rather than the size of the thing being checked.
593pub const DIGEST_BUFFER: usize = 1 << 16;
594
595/// The digest of a file, computed from a stream in bounded memory
596/// (REQ-VERIFYSTREAM-001 clause 1).
597///
598/// `manifest_digest(&std::fs::read(path)?)` gives the same answer, and it is
599/// what verify used to do — which made checking a 2 GB SDK a 2 GB heap
600/// allocation per payload, one at a time, reported from real use as ~9 seconds
601/// with nothing printed (varve#141). The answer does not change; only what it
602/// costs to reach it.
603///
604/// No hand-rolled cursor, deliberately. `io::copy` drives the loop and decides
605/// when it ends, so there is no `pos += n` for a mutant to turn into a loop
606/// that never advances — the shape that killed a CI job outright in v0.35.0.
607pub fn digest_file(path: &Path) -> std::io::Result<String> {
608    Ok(digest_file_timed(path)?.0)
609}
610
611/// Where the time went while digesting one file (REQ-VERIFYSTREAM-001 clause 2).
612///
613/// Attributed rather than guessed. varve#141 reported ~9 s to verify a layer
614/// with a 2 GB SDK, and the arithmetic said the hash could not account for it:
615/// a claim like that is only settled by measuring the stages separately.
616///
617/// There is no `decompress` field because verify does not decompress. A payload
618/// is hashed exactly as its producer signed it — that is what makes the digest
619/// re-derivable — so an archive's compression costs verify nothing.
620#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
621pub struct StageTiming {
622    /// Time inside the reader: the syscall and whatever the kernel did to serve
623    /// it, which on a cold cache is the disk.
624    pub read: std::time::Duration,
625    /// Time inside SHA-256.
626    pub hash: std::time::Duration,
627    /// Bytes read, which is the file's size — reported so a rate can be
628    /// computed from the same run that produced the times.
629    pub bytes: u64,
630}
631
632impl StageTiming {
633    /// Sum, for attributing a whole layer from its payloads.
634    pub fn add(&mut self, other: StageTiming) {
635        self.read += other.read;
636        self.hash += other.hash;
637        self.bytes += other.bytes;
638    }
639}
640
641/// [`digest_file`], with the read and hash time attributed separately.
642///
643/// The timing rides ON the real digest path rather than living in a benchmark:
644/// a number measured by a copy of the code is a number about the copy. The
645/// clocks are read per buffer, which at a 64 KiB buffer is two `Instant::now()`
646/// calls per 64 KiB — under a millisecond per gigabyte, and measured against
647/// the untimed path in the tests below.
648pub fn digest_file_timed(path: &Path) -> std::io::Result<(String, StageTiming)> {
649    let file = std::fs::File::open(path)?;
650    let mut reader = TimedReader {
651        inner: std::io::BufReader::with_capacity(DIGEST_BUFFER, file),
652        timing: StageTiming::default(),
653    };
654    let mut hasher = Sha256::new();
655    let mut writer = HashWriter {
656        hasher: &mut hasher,
657        hash: std::time::Duration::ZERO,
658    };
659    std::io::copy(&mut reader, &mut writer)?;
660    let hash = writer.hash;
661    let mut timing = reader.timing;
662    timing.hash = hash;
663    Ok((format!("sha256:{}", hex::encode(hasher.finalize())), timing))
664}
665
666/// Times the reads without changing what is read.
667///
668/// A wrapper rather than a hand-written loop, for the reason `io::copy` is used
669/// at all: a loop here would need its own termination condition, and a mutant
670/// that removes it hangs the job instead of failing a test.
671struct TimedReader<R> {
672    inner: R,
673    timing: StageTiming,
674}
675
676impl<R: std::io::Read> std::io::Read for TimedReader<R> {
677    fn read(&mut self, buf: &mut [u8]) -> std::io::Result<usize> {
678        let t = std::time::Instant::now();
679        let n = self.inner.read(buf)?;
680        self.timing.read += t.elapsed();
681        self.timing.bytes += n as u64;
682        Ok(n)
683    }
684}
685
686/// Feeds whatever `io::copy` writes straight into a hasher.
687///
688/// A local adapter rather than enabling a `sha2` feature: a dependency's
689/// feature set inside a verification crate is a thing to keep small. Mutating
690/// the reported length is caught rather than hidden — `Ok(0)` makes `copy`
691/// fail with `WriteZero`, and a short count makes it re-send bytes already
692/// hashed, so the digest disagrees with `manifest_digest` at every size the
693/// differential test checks.
694struct HashWriter<'a> {
695    hasher: &'a mut Sha256,
696    hash: std::time::Duration,
697}
698
699impl std::io::Write for HashWriter<'_> {
700    fn write(&mut self, buf: &[u8]) -> std::io::Result<usize> {
701        let t = std::time::Instant::now();
702        self.hasher.update(buf);
703        self.hash += t.elapsed();
704        Ok(buf.len())
705    }
706
707    fn flush(&mut self) -> std::io::Result<()> {
708        Ok(())
709    }
710}
711
712#[cfg(test)]
713mod digest_file_tests {
714    use super::*;
715
716    /// The streaming digest must be BYTE-FOR-BYTE the digest of the whole
717    /// file. Asserted against `manifest_digest` rather than against a
718    /// hard-coded hash, so the oracle is the implementation that has always
719    /// been trusted, and the new one has to agree with it.
720    ///
721    /// The sizes are where a chunked reader goes wrong: empty, a single
722    /// byte, one short of the buffer, exactly the buffer, one past it, and
723    /// several buffers with a ragged tail. A reader that drops a final partial
724    /// chunk, or double-counts one at a boundary, is right on most of these
725    /// and wrong on exactly one.
726    // rivet: verifies REQ-VERIFYSTREAM-001
727    #[test]
728    fn a_streamed_digest_equals_the_whole_file_digest_at_every_boundary() {
729        let guard = tempfile::tempdir().expect("temp dir");
730        let dir = guard.path();
731        let b = DIGEST_BUFFER;
732        for len in [0, 1, b - 1, b, b + 1, 3 * b + 7] {
733            // Not all zeros: a pattern that changes with position, so a chunk
734            // read out of order would hash differently.
735            let bytes: Vec<u8> = (0..len).map(|i| (i % 251) as u8).collect();
736            let path = dir.join(format!("payload-{len}"));
737            std::fs::write(&path, &bytes).expect("write fixture");
738            assert_eq!(
739                digest_file(&path).expect("streams"),
740                manifest_digest(&bytes),
741                "streaming and whole-file digests disagree at {len} bytes"
742            );
743        }
744    }
745
746    /// The timed path and the untimed path must agree about the digest, at
747    /// every buffer boundary: timing must not be able to change the answer,
748    /// and `digest_file` is now implemented BY the timed one.
749    // rivet: verifies REQ-VERIFYSTREAM-001
750    #[test]
751    fn timing_does_not_change_the_digest_at_any_boundary() {
752        let dir = tempfile::tempdir().expect("tempdir");
753        let b = DIGEST_BUFFER;
754        for size in [0usize, 1, b - 1, b, b + 1, 3 * b + 7] {
755            let path = dir.path().join(format!("f{size}"));
756            let bytes: Vec<u8> = (0..size).map(|i| (i % 251) as u8).collect();
757            std::fs::write(&path, &bytes).expect("write");
758            let (timed, stage) = digest_file_timed(&path).expect("timed digest");
759            assert_eq!(timed, manifest_digest(&bytes), "size {size}");
760            assert_eq!(digest_file(&path).expect("digest"), timed, "size {size}");
761            assert_eq!(stage.bytes, size as u64, "size {size}: bytes read");
762        }
763    }
764
765    /// Both stages are attributed, and the bytes are the file's. The numbers
766    /// this requirement asks to have RECORDED are what a rate is computed
767    /// from, so a stage left silently at zero would make the record a lie.
768    // rivet: verifies REQ-VERIFYSTREAM-001
769    #[test]
770    fn read_and_hash_are_attributed_separately() {
771        let dir = tempfile::tempdir().expect("tempdir");
772        let path = dir.path().join("many-buffers");
773        // Enough buffers that neither stage can round to zero on any clock.
774        std::fs::write(&path, vec![7u8; DIGEST_BUFFER * 64]).expect("write");
775        let (_, stage) = digest_file_timed(&path).expect("timed digest");
776        assert_eq!(stage.bytes, (DIGEST_BUFFER * 64) as u64);
777        assert!(stage.read > std::time::Duration::ZERO, "read unattributed");
778        assert!(stage.hash > std::time::Duration::ZERO, "hash unattributed");
779    }
780
781    /// Summing is how a whole layer is attributed from its payloads.
782    // rivet: verifies REQ-VERIFYSTREAM-001
783    #[test]
784    fn stage_timings_sum() {
785        let mut total = StageTiming::default();
786        total.add(StageTiming {
787            read: std::time::Duration::from_millis(3),
788            hash: std::time::Duration::from_millis(5),
789            bytes: 100,
790        });
791        total.add(StageTiming {
792            read: std::time::Duration::from_millis(7),
793            hash: std::time::Duration::from_millis(11),
794            bytes: 23,
795        });
796        assert_eq!(total.read, std::time::Duration::from_millis(10));
797        assert_eq!(total.hash, std::time::Duration::from_millis(16));
798        assert_eq!(total.bytes, 123);
799    }
800
801    /// THE CLASS GUARD. The paths that answer "does this installed payload
802    /// still match its signed digest" must digest it through `digest_file`,
803    /// never through `manifest_digest(&std::fs::read(..))`.
804    ///
805    /// A blanket "no fs::read" would be wrong — reverify legitimately reads
806    /// the small signed envelope and manifest. The precise invariant is that
807    /// their production code calls `manifest_digest` NOT AT ALL, so the only
808    /// way to hash a payload there is the streaming one.
809    ///
810    /// Two files, not one, and that is the point: `reverify` is varve's own
811    /// verify, `consumer` is the check other repositories call. Fixing only the
812    /// first would stream varve's answer while every consumer still allocated a
813    /// 2 GB SDK to ask the same question.
814    // rivet: verifies REQ-VERIFYSTREAM-001
815    #[test]
816    fn no_payload_check_digests_a_whole_file_read() {
817        let root = std::path::Path::new(env!("CARGO_MANIFEST_DIR"));
818        for rel in ["src/reverify.rs", "src/consumer.rs"] {
819            let src = std::fs::read_to_string(root.join(rel)).expect("readable");
820            let prod = match src.find("#[cfg(test)]") {
821                Some(i) => &src[..i],
822                None => &src[..],
823            };
824            assert!(
825                !prod.contains("manifest_digest("),
826                "{rel} digests with `manifest_digest` in production code. A payload \
827                 check must stream through `digest_file`; hashing a whole-file read \
828                 allocates the entire payload, which is 2 GB for an SDK (varve#141)."
829            );
830            // `digest_file_timed` counts: it IS the streaming path, and
831            // `digest_file` is a thin wrapper over it. What must not appear is
832            // a whole-file read, which the assertion above covers.
833            assert!(
834                prod.contains("digest_file(") || prod.contains("digest_file_timed("),
835                "{rel} no longer streams a payload digest at all — the payload check \
836                 has moved or vanished, and this guard would pass vacuously"
837            );
838        }
839    }
840
841    /// A missing file is an error the caller can name, not a digest of
842    /// nothing. Hashing an absent file to the empty-string digest would be a
843    /// silent pass for any entry whose signed digest happened to be that.
844    // rivet: verifies REQ-VERIFYSTREAM-001
845    #[test]
846    fn a_missing_file_is_an_error_not_the_empty_digest() {
847        let dir = tempfile::tempdir().expect("tempdir");
848        let missing = dir.path().join("definitely-absent");
849        assert!(digest_file(&missing).is_err());
850    }
851}
852
853#[cfg(test)]
854pub(crate) mod fixtures {
855    /// A minimal, valid layer manifest for tests.
856    pub fn manifest(layer: &str, channel: &str) -> Vec<u8> {
857        format!(
858            r#"{{
859  "schemaVersion": 2,
860  "mediaType": "application/vnd.oci.image.index.v1+json",
861  "artifactType": "application/vnd.pulseengine.varve.layer.v1+json",
862  "annotations": {{
863    "eu.pulseengine.varve.layer": "{layer}",
864    "eu.pulseengine.varve.channel": "{channel}"
865  }},
866  "manifests": []
867}}"#
868        )
869        .into_bytes()
870    }
871
872    /// A layer from before channel annotations existed. The resolver's channel
873    /// guard must exempt it: a pre-channel layer states no channel, so it
874    /// contradicts no pin.
875    pub fn manifest_without_channel(layer: &str) -> Vec<u8> {
876        format!(
877            r#"{{
878  "schemaVersion": 2,
879  "mediaType": "application/vnd.oci.image.index.v1+json",
880  "artifactType": "application/vnd.pulseengine.varve.layer.v1+json",
881  "annotations": {{
882    "eu.pulseengine.varve.layer": "{layer}"
883  }},
884  "manifests": []
885}}"#
886        )
887        .into_bytes()
888    }
889}
890
891#[cfg(test)]
892mod partition_tests {
893    use super::*;
894
895    // rivet: verifies REQ-STORE-001
896    #[test]
897    fn a_layer_is_found_in_any_partition_under_the_same_root() {
898        // A cross-realm composition include lives under the INCLUDED realm's
899        // fingerprint, not the including project's. Looking in one partition
900        // reported it missing while `list` showed it installed — `verify`,
901        // `which` and `run` disagreed with `list`, and the corrective advice
902        // failed (REQ-STORE-001).
903        let tmp = tempfile::tempdir().unwrap();
904        let root = tmp.path();
905        let mine = Store::at(root.join("realms").join("aaaa"));
906        let theirs = Store::at(root.join("realms").join("bbbb"));
907        let digest = theirs
908            .lay_down(
909                &fixtures::manifest("2026.08.0", "qualified"),
910                &[("btool", b"b")],
911            )
912            .unwrap();
913
914        // My own partition does not have it…
915        assert!(mine.get(&digest).unwrap().is_none());
916        // …but it is installed under this varve root, and locating it says so.
917        let (owner, entry) = mine.find_anywhere(&digest).unwrap().expect("found");
918        assert_eq!(entry.digest, digest);
919        assert_eq!(owner.root(), theirs.root(), "found in the owning partition");
920        // The tool resolves through the partition that actually holds it.
921        assert!(owner.tool_path(&entry, "btool").is_some());
922    }
923
924    // rivet: verifies REQ-STORE-001
925    #[test]
926    fn the_varve_root_is_recovered_from_a_realm_partition() {
927        let tmp = tempfile::tempdir().unwrap();
928        let root = tmp.path();
929        assert_eq!(
930            Store::at(root.join("realms").join("ffff")).varve_root(),
931            root.to_path_buf()
932        );
933        // A non-partition store is its own root.
934        assert_eq!(Store::at(root).varve_root(), root.to_path_buf());
935    }
936}
937
938#[cfg(test)]
939mod tests {
940    use super::*;
941
942    fn store() -> (tempfile::TempDir, Store) {
943        let tmp = tempfile::tempdir().unwrap();
944        let store = Store::at(tmp.path().join("varve-root"));
945        (tmp, store)
946    }
947
948    // rivet: verifies REQ-COEXIST-001
949    #[test]
950    fn two_layers_coexist_and_are_independently_addressable() {
951        let (_tmp, store) = store();
952        let july = fixtures::manifest("2026.07.0", "qualified");
953        let august = fixtures::manifest("2026.08.0", "qualified");
954        let d_july = store.lay_down(&july, &[("synth", b"july-synth")]).unwrap();
955        let d_august = store
956            .lay_down(&august, &[("synth", b"august-synth")])
957            .unwrap();
958        assert_ne!(d_july, d_august);
959
960        let listed = store.list().unwrap();
961        assert_eq!(listed.len(), 2);
962
963        let july_entry = store.get(&d_july).unwrap().unwrap();
964        let august_entry = store.get(&d_august).unwrap().unwrap();
965        assert_eq!(july_entry.layer.to_string(), "2026.07.0");
966        assert_eq!(august_entry.layer.to_string(), "2026.08.0");
967
968        // The same tool name resolves to different bytes per layer — the
969        // wohl-on-July-while-relay-on-August afternoon, on one machine.
970        let july_synth = store.tool_path(&july_entry, "synth").unwrap();
971        let august_synth = store.tool_path(&august_entry, "synth").unwrap();
972        assert_eq!(std::fs::read(july_synth).unwrap(), b"july-synth");
973        assert_eq!(std::fs::read(august_synth).unwrap(), b"august-synth");
974    }
975
976    // rivet: verifies REQ-COEXIST-001
977    #[test]
978    fn store_key_is_the_manifest_digest() {
979        let (_tmp, store) = store();
980        let bytes = fixtures::manifest("2026.07.0", "qualified");
981        let digest = store.lay_down(&bytes, &[]).unwrap();
982        assert_eq!(digest, manifest_digest(&bytes));
983        let entry = store.get(&digest).unwrap().unwrap();
984        assert!(
985            entry
986                .root
987                .ends_with(format!("core/{}", digest.replace(':', "-"))),
988            "entry rooted at digest-keyed dir, got {}",
989            entry.root.display()
990        );
991        // layer.json preserved verbatim for verify/archive.
992        assert_eq!(std::fs::read(entry.root.join("layer.json")).unwrap(), bytes);
993    }
994
995    // rivet: verifies REQ-PIN-001
996    #[test]
997    fn missing_layer_is_none_not_an_invention() {
998        let (_tmp, store) = store();
999        assert_eq!(
1000            store
1001                .get("sha256:0000000000000000000000000000000000000000000000000000000000000000")
1002                .unwrap(),
1003            None
1004        );
1005        assert_eq!(store.list().unwrap(), vec![]);
1006    }
1007
1008    /// A manifest entry as a signed layer carries it.
1009    fn entry(name: &str, version: Option<&str>, kind: Option<&str>) -> ManifestEntry {
1010        let mut annotations = BTreeMap::new();
1011        annotations.insert("eu.pulseengine.tool".to_string(), name.to_string());
1012        if let Some(v) = version {
1013            annotations.insert("eu.pulseengine.tool.version".to_string(), v.to_string());
1014        }
1015        if let Some(k) = kind {
1016            annotations.insert(crate::kind::ANN_KIND.to_string(), k.to_string());
1017        }
1018        ManifestEntry {
1019            digest: manifest_digest(name.as_bytes()),
1020            annotations,
1021        }
1022    }
1023
1024    fn held<'a>(name: &'a str, version: &'a str, bytes: &'a [u8]) -> Payload<'a> {
1025        Payload {
1026            name,
1027            version: Some(version),
1028            dispatchable: false,
1029            target: None,
1030            bytes,
1031        }
1032    }
1033
1034    // rivet: verifies REQ-STORE-002
1035    #[test]
1036    fn two_versions_of_one_name_are_two_files_neither_overwriting_the_other() {
1037        // Clause 2. `lay_down` wrote every payload to `bin/<name>`, so relaxing
1038        // the deposit check alone would have made the second serde silently
1039        // overwrite the first: the WRONG BYTES land under the right name, and
1040        // verification then fails on the OTHER entry with nothing explaining
1041        // why. A clean error turned into silent data loss.
1042        let (_tmp, store) = store();
1043        let manifest = fixtures::manifest("2026.08.0", "qualified");
1044        let digest = store
1045            .lay_down_payloads(
1046                &manifest,
1047                &[
1048                    held("serde", "1.0.200", b"serde-200-bytes"),
1049                    held("serde", "1.0.210", b"serde-210-bytes"),
1050                ],
1051            )
1052            .unwrap();
1053        let layer = store.get(&digest).unwrap().unwrap();
1054
1055        // Each version is its OWN file, holding its OWN bytes.
1056        let two_hundred = layer.root.join("payloads/serde/1.0.200");
1057        let two_ten = layer.root.join("payloads/serde/1.0.210");
1058        assert_eq!(std::fs::read(&two_hundred).unwrap(), b"serde-200-bytes");
1059        assert_eq!(std::fs::read(&two_ten).unwrap(), b"serde-210-bytes");
1060        // …and nothing landed under the bare name, where one would have won.
1061        assert!(!layer.root.join("bin/serde").exists());
1062
1063        // Both are reachable FROM THEIR MANIFEST ENTRIES — the lookup every
1064        // consumer uses, so `verify`, `archive` and `export-cargo` each see the
1065        // version they asked for rather than whichever landed last.
1066        assert_eq!(
1067            store.entry_path(&layer, &entry("serde", Some("1.0.200"), Some("crate"))),
1068            Some(two_hundred)
1069        );
1070        assert_eq!(
1071            store.entry_path(&layer, &entry("serde", Some("1.0.210"), Some("crate"))),
1072            Some(two_ten)
1073        );
1074    }
1075
1076    /// A cross-toolchain is identified by a PAIR: the host that runs it and
1077    /// the target it builds for. Two SDKs with one name and one version, for
1078    /// one host, differing only in target, are two different payloads —
1079    /// `toolchain_gnu_linux-x86_64_arm-zephyr-eabi` and
1080    /// `..._riscv64-zephyr-elf` are both "the toolchain", for this machine,
1081    /// and a realm wants both installed at once.
1082    ///
1083    /// Before this they landed on one path. The platform dimension could not
1084    /// separate them because platform describes the machine that RUNS the
1085    /// bytes, and for a cross-toolchain that is the same machine for every
1086    /// target — which is the whole reason this requirement exists.
1087    // rivet: verifies REQ-SDKTARGET-001
1088    #[test]
1089    fn two_sdks_differing_only_by_target_are_two_payloads() {
1090        let (_tmp, store) = store();
1091        let manifest = fixtures::manifest("2026.08.0", "qualified");
1092        let arm = Payload::targeted("zephyr-sdk", "1.0.1", "arm-zephyr-eabi", b"arm-bytes");
1093        let riscv = Payload::targeted("zephyr-sdk", "1.0.1", "riscv64-zephyr-elf", b"riscv-bytes");
1094        let digest = store
1095            .lay_down_payloads(&manifest, &[arm, riscv])
1096            .expect("two targets of one SDK are not a collision");
1097
1098        let root = store.core_dir().join(digest.replace(':', "-"));
1099        let arm_path = root
1100            .join(crate::store::PAYLOAD_DIR)
1101            .join("zephyr-sdk")
1102            .join("1.0.1")
1103            .join("arm-zephyr-eabi");
1104        let riscv_path = root
1105            .join(crate::store::PAYLOAD_DIR)
1106            .join("zephyr-sdk")
1107            .join("1.0.1")
1108            .join("riscv64-zephyr-elf");
1109        assert_eq!(std::fs::read(&arm_path).unwrap(), b"arm-bytes");
1110        assert_eq!(std::fs::read(&riscv_path).unwrap(), b"riscv-bytes");
1111    }
1112
1113    /// …and the guard still holds WITHIN a target: two payloads with the same
1114    /// name, version and target are still one identity and must be refused.
1115    /// Adding a dimension must not open a hole in the rule it extends.
1116    // rivet: verifies REQ-SDKTARGET-001
1117    #[test]
1118    fn two_sdks_with_the_same_target_still_collide() {
1119        let (_tmp, store) = store();
1120        let manifest = fixtures::manifest("2026.08.0", "qualified");
1121        let err = store
1122            .lay_down_payloads(
1123                &manifest,
1124                &[
1125                    Payload::targeted("zephyr-sdk", "1.0.1", "arm-zephyr-eabi", b"first"),
1126                    Payload::targeted("zephyr-sdk", "1.0.1", "arm-zephyr-eabi", b"second"),
1127                ],
1128            )
1129            .unwrap_err();
1130        assert!(matches!(&err, StoreError::Collision { .. }), "got: {err}");
1131    }
1132
1133    // rivet: verifies REQ-STORE-002
1134    #[test]
1135    fn two_payloads_claiming_one_path_are_refused_before_anything_is_written() {
1136        // The guard that makes the relaxation safe. deposit refuses two tools
1137        // under one name, but deposit is not the only producer: install accepts
1138        // ANY manifest a realm root signed, including one built by other
1139        // software. If two entries ever reach one path, the store must say so
1140        // loudly rather than write one over the other.
1141        let (_tmp, store) = store();
1142        let manifest = fixtures::manifest("2026.08.0", "qualified");
1143        let err = store
1144            .lay_down_payloads(
1145                &manifest,
1146                &[
1147                    Payload::tool("synth", b"first-bytes"),
1148                    Payload::tool("synth", b"second-bytes"),
1149                ],
1150            )
1151            .unwrap_err();
1152        assert!(
1153            matches!(&err, StoreError::Collision { path, .. } if path.contains("synth")),
1154            "got: {err}"
1155        );
1156        // And the core is untouched: destinations are resolved before any byte
1157        // is written, so a colliding layer never half-lands.
1158        assert!(store.list().unwrap().is_empty(), "nothing may be laid down");
1159
1160        // The same collision through the versionless legacy placement.
1161        let err = store
1162            .lay_down_payloads(
1163                &manifest,
1164                &[
1165                    Payload {
1166                        name: "wit-pkg",
1167                        version: None,
1168                        dispatchable: false,
1169                        target: None,
1170                        bytes: b"a",
1171                    },
1172                    Payload {
1173                        name: "wit-pkg",
1174                        version: None,
1175                        dispatchable: false,
1176                        target: None,
1177                        bytes: b"b",
1178                    },
1179                ],
1180            )
1181            .unwrap_err();
1182        assert!(matches!(err, StoreError::Collision { .. }), "got: {err}");
1183    }
1184
1185    // rivet: verifies REQ-STORE-002
1186    #[test]
1187    fn a_name_or_version_that_escapes_the_layer_is_refused() {
1188        // The names now compose a PATH, and they come out of a manifest.
1189        // "Signed" means attributable, not benign: a realm root must not be
1190        // able to place bytes outside the layer it is laying down.
1191        let (_tmp, store) = store();
1192        let manifest = fixtures::manifest("2026.08.0", "qualified");
1193        for (name, version) in [
1194            ("../../escape", Some("1.0.0")),
1195            ("serde", Some("../../escape")),
1196            ("a/b", Some("1.0.0")),
1197            ("..", Some("1.0.0")),
1198            ("", Some("1.0.0")),
1199            ("serde", Some("")),
1200        ] {
1201            let err = store
1202                .lay_down_payloads(&manifest, &[held(name, version.unwrap(), b"x")])
1203                .unwrap_err();
1204            assert!(
1205                matches!(err, StoreError::UnsafeComponent { .. }),
1206                "{name:?}@{version:?} must be refused, got: {err}"
1207            );
1208        }
1209        assert!(store.list().unwrap().is_empty());
1210        // The escape did not happen by any other route either.
1211        assert!(!store.root().join("escape").exists());
1212    }
1213
1214    // rivet: verifies REQ-STORE-002
1215    #[test]
1216    fn a_layer_installed_before_this_change_still_resolves_its_crate() {
1217        // Backward compatibility, stated as a test rather than a hope: a layer
1218        // laid down by an older varve holds its crate at `bin/<name>`, and
1219        // `verify`/`archive`/`export-cargo` must still find it there. Such a
1220        // layer can hold only ONE version per name — the old deposit check made
1221        // sure of it — so the fallback is unambiguous.
1222        let (_tmp, store) = store();
1223        let manifest = fixtures::manifest("2026.08.0", "qualified");
1224        let digest = store
1225            .lay_down(&manifest, &[("legacy-crate", b"old-layout-bytes")])
1226            .unwrap();
1227        let layer = store.get(&digest).unwrap().unwrap();
1228        let path = store
1229            .entry_path(&layer, &entry("legacy-crate", Some("0.1.0"), Some("crate")))
1230            .expect("a pre-REQ-STORE-002 layer must keep resolving");
1231        assert_eq!(std::fs::read(path).unwrap(), b"old-layout-bytes");
1232    }
1233
1234    // rivet: verifies REQ-STORE-002
1235    #[test]
1236    fn a_tool_keeps_bin_and_a_held_payload_never_borrows_it() {
1237        // Dispatch is by name, so `bin/<name>` is not merely retained for
1238        // compatibility — it is the contract `varve which`, `varve run` and the
1239        // argv[0] shims resolve through. A held payload must never satisfy a
1240        // dispatch lookup by landing there.
1241        let (_tmp, store) = store();
1242        let manifest = fixtures::manifest("2026.08.0", "qualified");
1243        let digest = store
1244            .lay_down_payloads(
1245                &manifest,
1246                &[
1247                    Payload::tool("synth", b"synth-binary"),
1248                    held("serde", "1.0.200", b"serde-crate"),
1249                ],
1250            )
1251            .unwrap();
1252        let layer = store.get(&digest).unwrap().unwrap();
1253        assert_eq!(
1254            std::fs::read(store.tool_path(&layer, "synth").unwrap()).unwrap(),
1255            b"synth-binary"
1256        );
1257        assert_eq!(store.tool_path(&layer, "serde"), None, "not dispatchable");
1258        #[cfg(unix)]
1259        {
1260            use std::os::unix::fs::PermissionsExt;
1261            let mode =
1262                |p: std::path::PathBuf| std::fs::metadata(p).unwrap().permissions().mode() & 0o777;
1263            assert_eq!(mode(layer.root.join("bin/synth")), 0o755);
1264            assert_eq!(
1265                mode(layer.root.join("payloads/serde/1.0.200")),
1266                0o644,
1267                "a .crate tarball is data, not something to execute"
1268            );
1269        }
1270    }
1271
1272    // rivet: verifies REQ-STORE-002
1273    #[test]
1274    fn an_unrecognised_kind_is_held_by_version_never_dispatched_by_name() {
1275        // A layer deposited by a NEWER varve carries kinds this build has never
1276        // heard of, and installs and verifies normally (DD-003, kind.rs). If an
1277        // unknown kind were placed by name alone, two versions of it would
1278        // overwrite each other — the very loss this requirement forbids, one
1279        // release later.
1280        let e = entry("future", Some("2.0.0"), Some("quantum-blob"));
1281        assert!(!entry_is_dispatchable(&e));
1282        assert_eq!(
1283            payload_rel_path(false, "future", Some("2.0.0"), None).unwrap(),
1284            PathBuf::from("payloads/future/2.0.0")
1285        );
1286        // …while an entry with NO kind annotation is a tool, as pre-kind
1287        // layers require.
1288        assert!(entry_is_dispatchable(&entry("synth", Some("0.45.0"), None)));
1289        assert_eq!(
1290            payload_rel_path(true, "synth", Some("0.45.0"), None).unwrap(),
1291            PathBuf::from("bin/synth")
1292        );
1293    }
1294
1295    // rivet: verifies REQ-SDK-001
1296    #[test]
1297    fn a_tree_shaped_payload_is_held_by_name_and_version_like_any_other() {
1298        // REQ-SDK-001 clause 1, and the correction the clause needed. A tree
1299        // payload is held as the single archive its producer SIGNED — one blob,
1300        // one digest, at `payloads/<name>/<version>` exactly like a `.crate` or
1301        // a `.vsix`. It is not unpacked here, and that is the design rather than
1302        // a shortfall:
1303        //
1304        //   * `verify` and `archive` re-hash ONE file at `entry_path` against
1305        //     ONE signed digest, so an unpacked store entry would be neither
1306        //     verifiable nor archivable — the opposite of clause 2;
1307        //   * relocation can only ever SHORTEN a path, and the store path is
1308        //     ~90 characters before any content, so an SDK could not be
1309        //     relocated INTO the store even if it were unpacked there.
1310        //
1311        // The tree is materialised where it is used, by `sdkexport`.
1312        let (_tmp, store) = store();
1313        let manifest = fixtures::manifest("2026.08.0", "qualified");
1314        let digest = store
1315            .lay_down_payloads(
1316                &manifest,
1317                &[
1318                    held("poky-cortexa53", "4.0.15", b"sdk-tarball-4.0.15"),
1319                    held("poky-cortexa53", "5.0.2", b"sdk-tarball-5.0.2"),
1320                    held("zephyr-hal", "3.6.0", b"zephyr-module-tarball"),
1321                ],
1322            )
1323            .unwrap();
1324        let layer = store.get(&digest).unwrap().unwrap();
1325
1326        // Two SDK versions coexist, neither overwriting the other — a project
1327        // migrating between Yocto releases holds both.
1328        for (version, want) in [
1329            ("4.0.15", &b"sdk-tarball-4.0.15"[..]),
1330            ("5.0.2", &b"sdk-tarball-5.0.2"[..]),
1331        ] {
1332            let path = store
1333                .entry_path(&layer, &entry("poky-cortexa53", Some(version), Some("sdk")))
1334                .expect("an sdk resolves from its manifest entry like any held payload");
1335            assert_eq!(
1336                path,
1337                layer
1338                    .root
1339                    .join(format!("payloads/poky-cortexa53/{version}"))
1340            );
1341            assert_eq!(std::fs::read(&path).unwrap(), want);
1342        }
1343        // An SDK is data handed to a compiler, never something varve dispatches.
1344        assert!(!crate::kind::PayloadKind::Sdk.is_dispatchable());
1345        assert_eq!(store.tool_path(&layer, "poky-cortexa53"), None);
1346        assert!(!layer.root.join("bin/poky-cortexa53").exists());
1347        // The other tree kinds are held the same way — nothing about `sdk` is
1348        // special in the store, which is what "like any other held payload"
1349        // means.
1350        assert!(
1351            store
1352                .entry_path(
1353                    &layer,
1354                    &entry("zephyr-hal", Some("3.6.0"), Some("zephyr-module"))
1355                )
1356                .is_some()
1357        );
1358    }
1359
1360    // rivet: verifies REQ-PIN-001
1361    #[test]
1362    fn missing_tool_in_an_installed_layer_is_none() {
1363        let (_tmp, store) = store();
1364        let bytes = fixtures::manifest("2026.07.0", "qualified");
1365        let digest = store.lay_down(&bytes, &[("rivet", b"r")]).unwrap();
1366        let entry = store.get(&digest).unwrap().unwrap();
1367        assert!(store.tool_path(&entry, "rivet").is_some());
1368        assert_eq!(store.tool_path(&entry, "synth"), None);
1369    }
1370}