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}