Architecture awareness: image manifests, arch on a sandbox, archs on the claim 1abadd4a2fa6

- **Architecture awareness (#36, spec §11.2).** `flow rootfs import` records an image's architecture from its shell's ELF header and refuses an image for another architecture; a claim reports each image's architecture, and a sandbox may say `arch "riscv64"`.

    /// The architecture of each image it holds, by hash, as the image's

    /// manifest records it (spec §11.2): the hub offers a job only to a

    /// runner whose architecture its image is for.

    #[serde(default, skip_serializing_if = "Option::is_none")]

    pub image_archs: Option<std::collections::BTreeMap<String, String>>,

    // The architecture asked for; absent when the image decides.

    if let Some(a) = &s.arch {

        fields.push((7, text(a)));

    }

pub use pipeline::{

    arch_ok, Identity, Job, Mount, MountSource, Network, Pipeline, Problem, Problems, Runtime, Sandbox, Secret, PIPELINE_PATH,

};

    /// The architecture the jobs need (`arch "riscv64"`, spec §11.3);

    /// without it, the rootfs image's.

    #[serde(default, skip_serializing_if = "Option::is_none")]

    pub arch: Option<String>,

}

/// An architecture name as runners report it: `x86_64`, `aarch64`, `riscv64`.

pub fn arch_ok(a: &str) -> bool {

    (2..=16).contains(&a.len()) && a.bytes().all(|b| b.is_ascii_lowercase() || b.is_ascii_digit() || b == b'_')

    let mut arch: Option<String> = None;

            "arch" => {

                arch = match ctx.one_string(c) {

                    Some(a) if arch_ok(&a) => Some(a),

                    Some(a) => {

                        ctx.err(c.span(), format!("arch {a:?} is not an architecture name such as x86_64, aarch64 or riscv64"));

                        None

                    }

                    None => None,

                }

            }

    Some(Sandbox {

        name,

        runtime: runtime?,

        rootfs: rootfs?,

        memory_mib: memory?,

        cpus: cpus?,

        network: network?,

        env,

        runs_on,

        timeout_s,

        arch,

    })

fn a_sandbox_may_name_its_architecture() {

    let plain = Pipeline::parse(&doc("job \"b\" {\n    sandbox \"alpine\"\n    exec \"make\"\n}\n")).unwrap();

    assert_eq!(plain.sandboxes["alpine"].arch, None);

    let src =

        doc("job \"b\" {\n    sandbox \"alpine\"\n    exec \"make\"\n}\n").replace("memory-limit", "arch \"riscv64\"\n    memory-limit");

    let p = Pipeline::parse(&src).unwrap();

    assert_eq!(p.sandboxes["alpine"].arch.as_deref(), Some("riscv64"));

    assert_ne!(p.hash(), plain.hash(), "the architecture is part of the sandbox");

    let bad = src.replace("riscv64", "RISC V");

    assert!(Pipeline::parse(&bad).unwrap_err().to_string().contains("not an architecture name"));

    assert!(arch_ok("x86_64") && arch_ok("aarch64") && !arch_ok("x") && !arch_ok("A64"));

}

#[test]

    /// An image's manifest (`cas/<hash>.json`): what `flow rootfs import`

    /// found out about it.

    pub fn image_manifest(&self, hash: &str) -> PathBuf {

        self.root.join("cas").join(format!("{hash}.json"))

    }

    /// The architecture an image was imported for, when its manifest says.

    pub fn image_arch(&self, hash: &str) -> Option<String> {

        let text = std::fs::read_to_string(self.image_manifest(hash)).ok()?;

        let v: serde_json::Value = serde_json::from_str(&text).ok()?;

        v["arch"].as_str().map(String::from)

    }

    /// Every image with a known architecture (spec §11.2).

    pub fn image_archs(&self) -> std::collections::BTreeMap<String, String> {

        self.images().into_iter().filter_map(|h| self.image_arch(&h).map(|a| (h, a))).collect()

    }

/// The architecture an ELF file was built for, by its header.

fn elf_arch(path: &Path) -> Option<&'static str> {

    let bytes = std::fs::read(path).ok()?;

    if bytes.len() < 20 || &bytes[..4] != b"\x7fELF" {

        return None;

    }

    let little = bytes[5] == 1;

    let machine = if little { u16::from_le_bytes([bytes[18], bytes[19]]) } else { u16::from_be_bytes([bytes[18], bytes[19]]) };

    Some(match machine {

        0x3E => "x86_64",

        0xB7 => "aarch64",

        0xF3 => "riscv64",

        0x03 => "x86",

        0x28 => "arm",

        0x15 => "powerpc64",

        0x16 => "s390x",

        _ => return None,

    })

}

/// The architecture of an unpacked rootfs: its shell's, or the first

/// program's found under bin.

fn tree_arch(tree: &Path) -> Option<&'static str> {

    for rel in ["bin/sh", "bin/busybox", "usr/bin/env", "bin/bash", "usr/bin/sh"] {

        let p = tree.join(rel);

        let p = std::fs::canonicalize(&p).unwrap_or(p);

        if let Some(a) = elf_arch(&p) {

            return Some(a);

        }

    }

    None

}

        }

        // The image's architecture must be this machine's: there is no

        // emulation tier (spec §11.2).

        let arch = tree_arch(&tree).unwrap_or("unknown");

        if arch != "unknown" && arch != std::env::consts::ARCH {

            bail!(

                "{} is a {arch} image; this runner is {}, and jobs here run no other architecture",

                tarball.display(),

                std::env::consts::ARCH

            );

        let manifest = serde_json::json!({ "arch": if arch == "unknown" { std::env::consts::ARCH } else { arch }, "imported_ms": std::time::SystemTime::now().duration_since(std::time::UNIX_EPOCH).map(|d| d.as_millis() as u64).unwrap_or(0) });

        std::fs::write(home.image_manifest(&hash), manifest.to_string())?;

                image_archs: Some(home.image_archs()),

- `arch "riscv64"` on a sandbox asks for that architecture (spec §11.3);

  without it the rootfs image's decides. `flow rootfs import` reads the

  image's architecture from its shell's ELF header, refuses an image for

  another architecture than the runner's, and records it in

  `cas/<hash>.json`; a claim reports each image's architecture

  (`image_archs`) so the hub never offers a job to a runner of the wrong

  one (spec §11.2).

## 11. Runner Capabilities and Placement (proposed 2026-10-04; §11.2 and `arch` of §11.3 done the same day, oxygenflow#36)