varve-core 0.46.0

Layer manifests, resolution, the core store, and verification wiring for varve
Documentation
//! The platform dimension (REQ-PLATFORM-001, DD-001).
//!
//! A layer is one manifest for N platforms — the OCI index's own mechanism,
//! not a substitution language. Deposit stamps every entry with a target
//! triple; install selects only entries for the host (or an explicit
//! override). Entries WITHOUT a platform annotation are platform-independent
//! — layers deposited before this dimension existed keep working, and a
//! depositor that makes no platform claim gets no platform filtering.
//! A fully-stamped layer with nothing for the host fails closed: a
//! wrong-architecture binary never reaches the core.

/// Annotation carrying an entry's target triple.
pub const ANN_PLATFORM: &str = "eu.pulseengine.platform";

/// What this payload needs from the host's libc (REQ-LIBCSTATED-001).
///
/// `ANN_PLATFORM` names the SLOT a consumer resolves by, and on Linux that
/// slot is spelled `-unknown-linux-gnu` whether the bytes are glibc-linked or
/// a static musl build. Layer 2026.10.1 files `ordeal` under
/// `x86_64-unknown-linux-gnu` from an asset named `...-linux-musl.tar.gz`, and
/// the signed manifest said nothing about which — so the only way to tell was
/// to read the asset FILENAME, the inference varve refuses everywhere else.
///
/// MEASURED from the payload's ELF program headers, never from its name: one
/// of `static`, `musl`, `glibc`, or an unrecognised `PT_INTERP` verbatim.
/// ABSENT when nothing was measurable (a Mach-O, a script, a tree), because
/// absence of evidence is not a portability guarantee and recording one would
/// be a signed claim nobody checked.
pub const ANN_LIBC: &str = "eu.pulseengine.platform.libc";

/// Annotation carrying what a payload BUILDS FOR, when that differs from what
/// runs it (REQ-SDKTARGET-001 clause 2).
///
/// `ANN_PLATFORM` answers "which machine executes these bytes"; this answers
/// "which machine will the artefacts they produce run on". For a compiler you
/// invoke, one question — and this annotation is absent. For a cross-toolchain
/// they are different questions with different answers, and the platform
/// dimension alone cannot tell two of them apart: every target of
/// `zephyr-sdk` for this host has the SAME platform.
///
/// Recorded in the signed manifest so a consumer resolves by target rather
/// than by a name the producer happened to choose — gale asks for "the
/// arm-zephyr-eabi toolchain", not for "the payload called toolchain-3".
pub const ANN_TARGET: &str = "eu.pulseengine.target";

/// What a manifest entry declares it builds for, if anything.
pub fn entry_target(entry: &crate::manifest::ManifestEntry) -> Option<&str> {
    entry.annotations.get(ANN_TARGET).map(String::as_str)
}

/// The host's target triple, in the same vocabulary deposits use.
pub fn host_platform() -> String {
    let arch = std::env::consts::ARCH;
    match std::env::consts::OS {
        "macos" => format!("{arch}-apple-darwin"),
        "linux" => format!("{arch}-unknown-linux-gnu"),
        "windows" => format!("{arch}-pc-windows-msvc"),
        other => format!("{arch}-{other}"),
    }
}

/// Does an entry's (optional) platform annotation admit this platform?
pub fn entry_matches(entry_platform: Option<&str>, platform: &str) -> bool {
    match entry_platform {
        None => true,
        // wasm32 targets are PORTABLE: the bytes run wherever a runner
        // exists (REQ-RUNNER-001) — no per-platform gaps by construction.
        Some(p) if p.starts_with("wasm32") => true,
        Some(p) => p == platform,
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    // rivet: verifies REQ-PLATFORM-001
    #[test]
    fn unstamped_entries_are_platform_independent_and_stamped_ones_are_exact() {
        assert!(entry_matches(None, "aarch64-apple-darwin"));
        assert!(entry_matches(
            Some("aarch64-apple-darwin"),
            "aarch64-apple-darwin"
        ));
        assert!(!entry_matches(
            Some("x86_64-unknown-linux-gnu"),
            "aarch64-apple-darwin"
        ));
    }

    // rivet: verifies REQ-RUNNER-001
    #[test]
    fn wasm32_entries_are_portable_to_every_host() {
        assert!(entry_matches(Some("wasm32-wasip2"), "aarch64-apple-darwin"));
        assert!(entry_matches(
            Some("wasm32-wasip2"),
            "x86_64-unknown-linux-gnu"
        ));
        assert!(entry_matches(Some("wasm32-unknown-unknown"), "anything"));
    }

    // rivet: verifies REQ-PLATFORM-001
    #[test]
    fn the_host_platform_is_a_target_triple() {
        let host = host_platform();
        assert!(
            host.split('-').count() >= 2 && host.contains(std::env::consts::ARCH),
            "host platform should be triple-shaped: {host}"
        );
    }
}