capsule_runtime/

artifact.rs

use std::io::Cursor;

use murmur_artifact::payload_shape::{
    check_skill_payload_entries, select_root_wasm_in_archive, SkillPayloadError, SKILL_MD_ENTRY,
};
use murmur_artifact::zip_guard;
use murmur_artifact::{BUILD_INFO_FILE, PACKED_MANIFEST_ENTRY};
use zip::ZipArchive;

use crate::errors::RuntimeError;

/// The root wasm of a `.mur.zip`: `capsule.wasm`, or its one root `*.wasm`, inflated under the
/// artifact decompression ceiling.
///
/// A refusal added here must also go into [`check_root_wasm`] or into the compiled-form key built
/// by `CompiledForms`. Staging skips this inflate when a form is stored for the payload and runs
/// only [`check_root_wasm`], which is exact only while every other input deciding whether this
/// succeeds is in the key: the payload sha256 and the ceiling. A check on the entry's contents, a
/// new setting, or a `zip` upgrade that changes what inflates is such an input.
pub fn extract_root_wasm(
    artifact_name: &str,
    artifact_version: &str,
    artifact_bytes: &[u8],
) -> Result<Vec<u8>, RuntimeError> {
    extract_root_wasm_capped(
        artifact_name,
        artifact_version,
        artifact_bytes,
        zip_guard::max_artifact_decompressed_bytes(),
    )
}

/// The refusals [`extract_root_wasm`] makes before it inflates anything, with the same errors:
/// the archive opens, and its entries name exactly one root wasm.
pub fn check_root_wasm(
    artifact_name: &str,
    artifact_version: &str,
    artifact_bytes: &[u8],
) -> Result<(), RuntimeError> {
    locate_root_wasm(artifact_name, artifact_version, artifact_bytes).map(|_| ())
}

type BorrowedArchive<'a> = ZipArchive<Cursor<&'a [u8]>>;

/// The opened archive and the name of its root wasm entry.
fn locate_root_wasm<'a>(
    artifact_name: &str,
    artifact_version: &str,
    artifact_bytes: &'a [u8],
) -> Result<(BorrowedArchive<'a>, String), RuntimeError> {
    let mut archive = ZipArchive::new(Cursor::new(artifact_bytes)).map_err(|err| {
        RuntimeError::ArtifactArchive {
            name: artifact_name.to_string(),
            version: artifact_version.to_string(),
            message: err.to_string(),
        }
    })?;

    // Which root entry counts as the wasm payload is the shared payload-shape contract; the
    // selector (and its error text) lives in murmur_artifact::payload_shape.
    let selected_name =
        select_root_wasm_in_archive(&mut archive).map_err(|err| RuntimeError::ArtifactArchive {
            name: artifact_name.to_string(),
            version: artifact_version.to_string(),
            message: err.to_string(),
        })?;

    Ok((archive, selected_name))
}

fn extract_root_wasm_capped(
    artifact_name: &str,
    artifact_version: &str,
    artifact_bytes: &[u8],
    max_bytes: u64,
) -> Result<Vec<u8>, RuntimeError> {
    let (mut archive, selected_name) =
        locate_root_wasm(artifact_name, artifact_version, artifact_bytes)?;

    zip_guard::read_zip_entry_capped(&mut archive, &selected_name, max_bytes).map_err(|err| {
        RuntimeError::ArtifactArchive {
            name: artifact_name.to_string(),
            version: artifact_version.to_string(),
            message: err.to_string(),
        }
    })
}

/// One skill's installable files: each as its `/`-separated path under `tools/<name>/` and its
/// bytes, `SKILL.md` first.
pub type SkillFiles = Vec<(String, Vec<u8>)>;

/// The files of a skill artifact's `.mur.zip` that install under `tools/<name>/`: each as its
/// `/`-separated path inside the archive and its bytes, `SKILL.md` first.
///
/// Skill artifact layout:
///   murmur.yaml        — artifact manifest at zip root (not returned; staging writes its own)
///   SKILL.md           — guidance content at zip root (required), installed byte for byte
///   murmur-build.json  — build record at zip root (not returned)
///   anything else      — supporting files the guidance points at, at their packed paths
///
/// An archive whose root holds `skill.md` in another casing and no `SKILL.md`, the layout an
/// older `mur build` wrote, is refused with [`RuntimeError::SkillArtifactLayout`]. An entry name
/// that escapes the archive fails the extraction, and so does a total past the artifact
/// decompression ceiling.
pub fn extract_skill_files(
    artifact_name: &str,
    artifact_version: &str,
    artifact_bytes: &[u8],
) -> Result<SkillFiles, RuntimeError> {
    extract_skill_files_capped(
        artifact_name,
        artifact_version,
        artifact_bytes,
        zip_guard::max_artifact_decompressed_bytes(),
    )
}

fn extract_skill_files_capped(
    artifact_name: &str,
    artifact_version: &str,
    artifact_bytes: &[u8],
    max_bytes: u64,
) -> Result<SkillFiles, RuntimeError> {
    let archive_error = |message: String| RuntimeError::ArtifactArchive {
        name: artifact_name.to_string(),
        version: artifact_version.to_string(),
        message,
    };
    let cursor = std::io::Cursor::new(artifact_bytes);
    let mut archive = ZipArchive::new(cursor).map_err(|err| archive_error(err.to_string()))?;

    if let Err(reason @ SkillPayloadError::BuiltBeforeStandard) =
        check_skill_payload_entries(archive.file_names().filter_map(Result::ok))
    {
        return Err(RuntimeError::SkillArtifactLayout {
            name: artifact_name.to_string(),
            version: artifact_version.to_string(),
            reason,
        });
    }
    let skill_md = zip_guard::read_zip_entry_capped(&mut archive, SKILL_MD_ENTRY, max_bytes)
        .map_err(|err| {
            archive_error(format!(
                "{SKILL_MD_ENTRY} not found or unreadable at archive root (ensure \
                 {SKILL_MD_ENTRY} is at the root of the .mur.zip): {err}"
            ))
        })?;
    let mut total = skill_md.len() as u64;
    let mut files = vec![(SKILL_MD_ENTRY.to_string(), skill_md)];

    let mut supporting = Vec::new();
    for index in 0..archive.len() {
        let entry = archive
            .by_index_raw(index)
            .map_err(|err| archive_error(err.to_string()))?;
        if entry.is_dir() {
            continue;
        }
        let raw_name = entry
            .name()
            .map_err(|err| archive_error(err.to_string()))?
            .into_owned();
        let relative = zip_guard::normalized_entry_name(&raw_name)
            .map_err(|err| archive_error(err.to_string()))?;
        if relative.is_empty()
            || [SKILL_MD_ENTRY, PACKED_MANIFEST_ENTRY, BUILD_INFO_FILE].contains(&relative.as_str())
        {
            continue;
        }
        supporting.push((raw_name, relative));
    }

    for (raw_name, relative) in supporting {
        let remaining = max_bytes.saturating_sub(total);
        let bytes = zip_guard::read_zip_entry_capped(&mut archive, &raw_name, remaining)
            .map_err(|err| archive_error(format!("failed to read '{raw_name}': {err}")))?;
        total += bytes.len() as u64;
        files.push((relative, bytes));
    }
    Ok(files)
}

pub fn extract_manifest_yaml(
    artifact_name: &str,
    artifact_version: &str,
    artifact_bytes: &[u8],
) -> Result<String, RuntimeError> {
    extract_manifest_yaml_capped(
        artifact_name,
        artifact_version,
        artifact_bytes,
        zip_guard::max_artifact_decompressed_bytes(),
    )
}

fn extract_manifest_yaml_capped(
    artifact_name: &str,
    artifact_version: &str,
    artifact_bytes: &[u8],
    max_bytes: u64,
) -> Result<String, RuntimeError> {
    let cursor = std::io::Cursor::new(artifact_bytes);
    let mut archive = ZipArchive::new(cursor).map_err(|err| RuntimeError::ArtifactArchive {
        name: artifact_name.to_string(),
        version: artifact_version.to_string(),
        message: err.to_string(),
    })?;

    zip_guard::read_zip_entry_to_string_capped(&mut archive, PACKED_MANIFEST_ENTRY, max_bytes)
        .map_err(|err| RuntimeError::ArtifactArchive {
            name: artifact_name.to_string(),
            version: artifact_version.to_string(),
            message: format!(
                "missing or unreadable {PACKED_MANIFEST_ENTRY} in artifact archive: {err}"
            ),
        })
}

/// The `capabilities.env.allow` a packed manifest declares, read on its own.
///
/// Narrow on purpose. `murmur_artifact::RuntimeManifest::from_yaml_str` validates the whole
/// manifest, and that resolves every `${VAR}` in a `gateway.api_key` against the reading
/// process's environment — so a parent asking what its child declares would have to already hold
/// the child's variables before it could read which ones they are. Reading the one key answers
/// that without the circle.
///
/// A manifest with no `capabilities:` block, or none under `env:`, declares nothing and yields an
/// empty list. Malformed YAML, or an `env.allow` that is not a list of strings, is an error
/// naming the artifact and version.
pub fn extract_declared_env_allow(
    artifact_name: &str,
    artifact_version: &str,
    manifest_yaml: &str,
) -> Result<Vec<String>, RuntimeError> {
    let declared: DeclaredAllows =
        serde_norway::from_str(manifest_yaml).map_err(|err| RuntimeError::ArtifactArchive {
            name: artifact_name.to_string(),
            version: artifact_version.to_string(),
            message: format!(
                "cannot read capabilities.env.allow from {PACKED_MANIFEST_ENTRY}: {err}"
            ),
        })?;
    Ok(declared
        .capabilities
        .and_then(|capabilities| capabilities.env)
        .map(|env| env.allow)
        .unwrap_or_default())
}

/// The `capabilities.spawn.allow` a packed manifest declares, read on its own.
///
/// The sibling of [`extract_declared_env_allow`], and narrow for the same reason: walking a
/// `spawn.allow` closure means reading which capsules a child may in turn spawn, and a
/// whole-manifest parse would demand that child's own `${VAR}` references be resolvable first.
///
/// A manifest with no `capabilities:` block, or none under `spawn:`, declares nothing and yields
/// an empty list. Malformed YAML, or a `spawn.allow` that is not a list of strings, is an error
/// naming the artifact and version.
pub fn extract_declared_spawn_allow(
    artifact_name: &str,
    artifact_version: &str,
    manifest_yaml: &str,
) -> Result<Vec<String>, RuntimeError> {
    let declared: DeclaredAllows =
        serde_norway::from_str(manifest_yaml).map_err(|err| RuntimeError::ArtifactArchive {
            name: artifact_name.to_string(),
            version: artifact_version.to_string(),
            message: format!(
                "cannot read capabilities.spawn.allow from {PACKED_MANIFEST_ENTRY}: {err}"
            ),
        })?;
    Ok(declared
        .capabilities
        .and_then(|capabilities| capabilities.spawn)
        .map(|spawn| spawn.allow)
        .unwrap_or_default())
}

/// The `capabilities.resources.workdir_max_bytes` a packed manifest declares, read on its own:
/// `None` when it declares none, which is [`crate::resources::DEFAULT_WORKDIR_MAX_BYTES`].
///
/// The sibling of [`extract_declared_env_allow`], and narrow for the same reason: a delegating
/// parent bounds the copy of its work folder into a child's by the child's own ceiling, and a
/// whole-manifest parse would demand that child's `${VAR}` references be resolvable first.
/// Malformed YAML, or a value that is not a non-negative integer, is an error naming the artifact
/// and version.
pub fn extract_declared_workdir_max_bytes(
    artifact_name: &str,
    artifact_version: &str,
    manifest_yaml: &str,
) -> Result<Option<u64>, RuntimeError> {
    let declared: DeclaredResourcesManifest =
        serde_norway::from_str(manifest_yaml).map_err(|err| RuntimeError::ArtifactArchive {
            name: artifact_name.to_string(),
            version: artifact_version.to_string(),
            message: format!(
                "cannot read capabilities.resources.workdir_max_bytes from \
                 {PACKED_MANIFEST_ENTRY}: {err}"
            ),
        })?;
    Ok(declared
        .capabilities
        .and_then(|capabilities| capabilities.resources)
        .and_then(|resources| resources.workdir_max_bytes))
}

/// The only keys [`extract_declared_env_allow`] and [`extract_declared_spawn_allow`] read. Every
/// other manifest key deserializes into nothing here, so a child declaring anything at all is
/// still readable.
#[derive(serde::Deserialize)]
struct DeclaredAllows {
    #[serde(default)]
    capabilities: Option<DeclaredCapabilities>,
}

#[derive(serde::Deserialize)]
struct DeclaredCapabilities {
    #[serde(default)]
    env: Option<DeclaredAllowList>,
    #[serde(default)]
    spawn: Option<DeclaredAllowList>,
}

/// The only key [`extract_declared_workdir_max_bytes`] reads, apart from the allows so a
/// malformed `resources:` block never stops a child's `env.allow` being read.
#[derive(serde::Deserialize)]
struct DeclaredResourcesManifest {
    #[serde(default)]
    capabilities: Option<DeclaredResourcesCapabilities>,
}

#[derive(serde::Deserialize)]
struct DeclaredResourcesCapabilities {
    #[serde(default)]
    resources: Option<DeclaredResources>,
}

#[derive(serde::Deserialize)]
struct DeclaredResources {
    #[serde(default)]
    workdir_max_bytes: Option<u64>,
}

#[derive(serde::Deserialize)]
struct DeclaredAllowList {
    #[serde(default)]
    allow: Vec<String>,
}

#[cfg(test)]
pub(crate) mod test_support {
    use std::io::Write;

    use zip::write::SimpleFileOptions;

    /// A `.mur.zip` payload holding `files`, each `(path in the archive, bytes)`.
    pub(crate) fn archive_with_files(files: &[(&str, &[u8])]) -> Vec<u8> {
        let mut cursor = std::io::Cursor::new(Vec::<u8>::new());
        {
            let mut zip = zip::ZipWriter::new(&mut cursor);
            let options = SimpleFileOptions::default();
            for (name, bytes) in files {
                zip.start_file(*name, options).unwrap();
                zip.write_all(bytes).unwrap();
            }
            zip.finish().unwrap();
        }
        cursor.into_inner()
    }
}

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

    #[test]
    fn prefers_capsule_wasm_when_present() {
        let archive = archive_with_files(&[
            ("tool.wasm", b"tool"),
            ("capsule.wasm", b"capsule"),
            (PACKED_MANIFEST_ENTRY, b"name: demo"),
        ]);

        let wasm = extract_root_wasm("demo", "0.0.1", &archive).unwrap();
        assert_eq!(wasm, b"capsule");
    }

    #[test]
    fn extracts_manifest_yaml_from_archive() {
        let archive = archive_with_files(&[
            (PACKED_MANIFEST_ENTRY, b"name: demo\nversion: 0.1.0\n"),
            ("tool.wasm", b"tool"),
        ]);

        let manifest = extract_manifest_yaml("demo", "0.1.0", &archive).unwrap();
        assert!(manifest.contains("name: demo"));
        assert!(manifest.contains("version: 0.1.0"));
    }

    #[test]
    fn reads_the_declared_env_allow_out_of_a_manifest() {
        let manifest = "name: worker\nversion: 0.1.0\ncapabilities:\n  network:\n    \
                        allow: [127.0.0.1]\n  env:\n    allow: [OPENAI_API_KEY, HTTPS_PROXY]\n";

        assert_eq!(
            extract_declared_env_allow("worker", "0.1.0", manifest).unwrap(),
            vec!["OPENAI_API_KEY".to_string(), "HTTPS_PROXY".to_string()]
        );
    }

    /// The read answers what the child declares without validating the rest of the manifest: a
    /// `${VAR}` the reading process does not hold would fail a full parse, and the whole point is
    /// to learn which variables the child needs before holding any of them.
    #[test]
    fn an_unresolvable_inference_key_does_not_stop_the_read() {
        let manifest = "name: worker\nversion: 0.1.0\ninference:\n  transport: http\n  \
                        api_key: ${MURMUR_A_VARIABLE_NOBODY_EXPORTED}\ncapabilities:\n  env:\n    \
                        allow: [MURMUR_A_VARIABLE_NOBODY_EXPORTED]\n";

        assert_eq!(
            extract_declared_env_allow("worker", "0.1.0", manifest).unwrap(),
            vec!["MURMUR_A_VARIABLE_NOBODY_EXPORTED".to_string()]
        );
    }

    #[test]
    fn a_manifest_declaring_no_env_allow_declares_nothing() {
        for manifest in [
            "name: worker\nversion: 0.1.0\n",
            "name: worker\nversion: 0.1.0\ncapabilities:\n  shell:\n    allow: [bash]\n",
            "name: worker\nversion: 0.1.0\ncapabilities:\n  env:\n    allow: []\n",
        ] {
            assert_eq!(
                extract_declared_env_allow("worker", "0.1.0", manifest).unwrap(),
                Vec::<String>::new(),
                "{manifest}"
            );
        }
    }

    #[test]
    fn an_unreadable_env_allow_is_an_error_naming_the_artifact() {
        for manifest in [
            "name: worker\nversion: 0.1.0\ncapabilities:\n  env:\n    allow: OPENAI_API_KEY\n",
            "name: worker\nversion: 0.1.0\ncapabilities:\n  env:\n    allow: [[OPENAI_API_KEY]]\n",
            "name: worker\nversion: 0.1.0\ncapabilities:\n\tenv: broken\n",
        ] {
            let err = extract_declared_env_allow("worker", "0.1.0", manifest).unwrap_err();
            match err {
                RuntimeError::ArtifactArchive {
                    name,
                    version,
                    message,
                } => {
                    assert_eq!(name, "worker");
                    assert_eq!(version, "0.1.0");
                    assert!(message.contains("capabilities.env.allow"), "{message}");
                }
                other => panic!("expected ArtifactArchive error, got {other:?}"),
            }
        }
    }

    #[test]
    fn reads_the_declared_spawn_allow_out_of_a_manifest() {
        let manifest = "name: worker\nversion: 0.1.0\ncapabilities:\n  env:\n    \
                        allow: [OPENAI_API_KEY]\n  spawn:\n    allow: [deep-worker, sibling]\n";

        assert_eq!(
            extract_declared_spawn_allow("worker", "0.1.0", manifest).unwrap(),
            vec!["deep-worker".to_string(), "sibling".to_string()]
        );
        assert_eq!(
            extract_declared_env_allow("worker", "0.1.0", manifest).unwrap(),
            vec!["OPENAI_API_KEY".to_string()]
        );
    }

    #[test]
    fn a_manifest_declaring_no_spawn_allow_declares_nothing() {
        for manifest in [
            "name: worker\nversion: 0.1.0\n",
            "name: worker\nversion: 0.1.0\ncapabilities:\n  env:\n    allow: [A_KEY]\n",
            "name: worker\nversion: 0.1.0\ncapabilities:\n  spawn:\n    allow: []\n",
        ] {
            assert_eq!(
                extract_declared_spawn_allow("worker", "0.1.0", manifest).unwrap(),
                Vec::<String>::new(),
                "{manifest}"
            );
        }
    }

    #[test]
    fn an_unreadable_spawn_allow_is_an_error_naming_the_artifact() {
        for manifest in [
            "name: worker\nversion: 0.1.0\ncapabilities:\n  spawn:\n    allow: deep-worker\n",
            "name: worker\nversion: 0.1.0\ncapabilities:\n  spawn:\n    allow: [[deep]]\n",
            "name: worker\nversion: 0.1.0\ncapabilities:\n\tspawn: broken\n",
        ] {
            match extract_declared_spawn_allow("worker", "0.1.0", manifest).unwrap_err() {
                RuntimeError::ArtifactArchive {
                    name,
                    version,
                    message,
                } => {
                    assert_eq!(name, "worker");
                    assert_eq!(version, "0.1.0");
                    assert!(message.contains("capabilities.spawn.allow"), "{message}");
                }
                other => panic!("expected ArtifactArchive error, got {other:?}"),
            }
        }
    }

    #[test]
    fn reads_the_declared_workdir_max_bytes_out_of_a_manifest() {
        let declared = "name: worker\nversion: 0.1.0\ncapabilities:\n  resources:\n    \
                        workdir_max_bytes: 1024\n    cgroup_pids_max: 64\n";
        assert_eq!(
            extract_declared_workdir_max_bytes("worker", "0.1.0", declared).unwrap(),
            Some(1024)
        );
        for manifest in [
            "name: worker\nversion: 0.1.0\n",
            "name: worker\nversion: 0.1.0\ncapabilities:\n  env:\n    allow: [A_KEY]\n",
            "name: worker\nversion: 0.1.0\ncapabilities:\n  resources:\n    cgroup_pids_max: 8\n",
        ] {
            assert_eq!(
                extract_declared_workdir_max_bytes("worker", "0.1.0", manifest).unwrap(),
                None,
                "{manifest}"
            );
        }
        let malformed = "name: worker\nversion: 0.1.0\ncapabilities:\n  resources:\n    \
                         workdir_max_bytes: lots\n  env:\n    allow: [A_KEY]\n";
        match extract_declared_workdir_max_bytes("worker", "0.1.0", malformed).unwrap_err() {
            RuntimeError::ArtifactArchive { name, message, .. } => {
                assert_eq!(name, "worker");
                assert!(
                    message.contains("capabilities.resources.workdir_max_bytes"),
                    "{message}"
                );
            }
            other => panic!("expected ArtifactArchive error, got {other:?}"),
        }
        assert_eq!(
            extract_declared_env_allow("worker", "0.1.0", malformed).unwrap(),
            vec!["A_KEY".to_string()],
            "a malformed resources block does not stop env.allow being read"
        );
    }

    #[test]
    fn rejects_path_traversal_entry_as_root_wasm_candidate() {
        let archive = archive_with_files(&[
            ("../../evil.wasm", b"evil"),
            (PACKED_MANIFEST_ENTRY, b"name: demo"),
        ]);

        let err = extract_root_wasm("demo", "0.0.1", &archive).unwrap_err();
        match err {
            RuntimeError::ArtifactArchive { message, .. } => {
                assert!(message.contains("missing root .wasm file"));
            }
            other => panic!("expected ArtifactArchive error, got {other:?}"),
        }
    }

    #[test]
    fn rejects_leading_slash_entry_as_root_wasm_candidate() {
        let archive = archive_with_files(&[
            ("/capsule.wasm", b"evil"),
            (PACKED_MANIFEST_ENTRY, b"name: demo"),
        ]);

        let err = extract_root_wasm("demo", "0.0.1", &archive).unwrap_err();
        match err {
            RuntimeError::ArtifactArchive { message, .. } => {
                assert!(message.contains("missing root .wasm file"));
            }
            other => panic!("expected ArtifactArchive error, got {other:?}"),
        }
    }

    #[test]
    fn extract_manifest_yaml_rejects_entry_past_ceiling() {
        let big = vec![b'a'; 1024];
        let archive = archive_with_files(&[(PACKED_MANIFEST_ENTRY, &big)]);

        let err = extract_manifest_yaml_capped("demo", "0.0.1", &archive, 16).unwrap_err();
        match err {
            RuntimeError::ArtifactArchive { message, .. } => {
                assert!(message.contains("decompression ceiling"));
            }
            other => panic!("expected ArtifactArchive error, got {other:?}"),
        }
    }

    #[test]
    fn extract_root_wasm_rejects_entry_past_ceiling() {
        let big = vec![b'a'; 1024];
        let archive = archive_with_files(&[("capsule.wasm", &big)]);

        let err = extract_root_wasm_capped("demo", "0.0.1", &archive, 16).unwrap_err();
        match err {
            RuntimeError::ArtifactArchive { message, .. } => {
                assert!(message.contains("decompression ceiling"));
            }
            other => panic!("expected ArtifactArchive error, got {other:?}"),
        }
    }

    #[test]
    fn extract_skill_files_rejects_entry_past_ceiling() {
        let big = vec![b'a'; 1024];
        let archive = archive_with_files(&[("SKILL.md", &big)]);

        let err = extract_skill_files_capped("demo", "0.0.1", &archive, 16).unwrap_err();
        match err {
            RuntimeError::ArtifactArchive { message, .. } => {
                assert!(message.contains("decompression ceiling"));
            }
            other => panic!("expected ArtifactArchive error, got {other:?}"),
        }
    }

    #[test]
    fn extract_skill_files_rejects_a_total_past_ceiling() {
        let archive =
            archive_with_files(&[("SKILL.md", &[b'a'; 10]), ("references/a.md", &[b'b'; 10])]);

        let err = extract_skill_files_capped("demo", "0.0.1", &archive, 16).unwrap_err();
        match err {
            RuntimeError::ArtifactArchive { message, .. } => {
                assert!(message.contains("references/a.md"), "{message}");
                assert!(message.contains("decompression ceiling"), "{message}");
            }
            other => panic!("expected ArtifactArchive error, got {other:?}"),
        }
    }

    #[test]
    fn extract_skill_files_returns_supporting_files_without_manifest_or_build_record() {
        let archive = archive_with_files(&[
            (PACKED_MANIFEST_ENTRY, b"name: demo"),
            ("references/forms.md", b"# Forms\n"),
            ("SKILL.md", b"# Demo\n"),
            (BUILD_INFO_FILE, b"{}"),
            ("scripts/fill.py", b"print(1)\n"),
        ]);

        let files = extract_skill_files("demo", "0.0.1", &archive).unwrap();
        assert_eq!(
            files,
            vec![
                ("SKILL.md".to_string(), b"# Demo\n".to_vec()),
                ("references/forms.md".to_string(), b"# Forms\n".to_vec()),
                ("scripts/fill.py".to_string(), b"print(1)\n".to_vec()),
            ]
        );
    }

    #[test]
    fn extract_skill_files_requires_skill_md() {
        let archive = archive_with_files(&[(PACKED_MANIFEST_ENTRY, b"name: demo")]);

        let err = extract_skill_files("demo", "0.0.1", &archive).unwrap_err();
        match err {
            RuntimeError::ArtifactArchive { message, .. } => {
                assert!(
                    message.contains("SKILL.md not found or unreadable at archive root"),
                    "{message}"
                );
            }
            other => panic!("expected ArtifactArchive error, got {other:?}"),
        }
    }

    #[test]
    fn extract_skill_files_refuses_an_archive_built_before_the_standard() {
        let archive = archive_with_files(&[
            (
                PACKED_MANIFEST_ENTRY,
                b"name: demo\nversion: 0.0.1\nruntime: skill\n",
            ),
            ("skill.md", b"# Demo\n"),
        ]);

        let err = extract_skill_files("local/demo", "0.0.1", &archive).unwrap_err();
        assert!(
            matches!(
                &err,
                RuntimeError::SkillArtifactLayout { name, version, reason: SkillPayloadError::BuiltBeforeStandard }
                    if name == "local/demo" && version == "0.0.1"
            ),
            "{err:?}"
        );
        assert_eq!(
            err.to_string(),
            "skill artifact local/demo@0.0.1 cannot be installed: it holds skill.md, so it was \
             built before skills followed the Agent Skills standard, which names the file SKILL.md"
        );
    }

    #[test]
    fn extract_skill_files_refuses_an_escaping_entry() {
        let archive = archive_with_files(&[("SKILL.md", b"# s"), ("../escape.md", b"x")]);

        let err = extract_skill_files("demo", "0.0.1", &archive).unwrap_err();
        match err {
            RuntimeError::ArtifactArchive { message, .. } => {
                assert!(message.contains("../escape.md"), "{message}");
            }
            other => panic!("expected ArtifactArchive error, got {other:?}"),
        }
    }

    #[test]
    fn check_root_wasm_refuses_exactly_as_extract_root_wasm() {
        let no_root_wasm = archive_with_files(&[(PACKED_MANIFEST_ENTRY, b"name: demo")]);
        let two_root_wasms = archive_with_files(&[
            ("alpha.wasm", b"a"),
            ("zeta.wasm", b"z"),
            (PACKED_MANIFEST_ENTRY, b"name: demo"),
        ]);
        for payload in [b"not a zip".to_vec(), no_root_wasm, two_root_wasms] {
            let checked = check_root_wasm("demo", "0.0.1", &payload).unwrap_err();
            let extracted = extract_root_wasm("demo", "0.0.1", &payload).unwrap_err();
            assert_eq!(checked.to_string(), extracted.to_string());
        }

        let valid = archive_with_files(&[
            (PACKED_MANIFEST_ENTRY, b"name: demo"),
            ("tool.wasm", b"tool"),
        ]);
        check_root_wasm("demo", "0.0.1", &valid).unwrap();
        extract_root_wasm("demo", "0.0.1", &valid).unwrap();
    }

    #[test]
    fn check_root_wasm_does_not_inflate() {
        let big = vec![b'a'; 1024];
        let archive = archive_with_files(&[("tool.wasm", &big)]);

        let err = extract_root_wasm_capped("demo", "0.0.1", &archive, 16).unwrap_err();
        assert!(
            err.to_string()
                .contains("exceeds the 16-byte decompression ceiling"),
            "{err}"
        );
        check_root_wasm("demo", "0.0.1", &archive).unwrap();
    }

    #[test]
    fn default_ceiling_does_not_reject_small_fixtures() {
        let archive = archive_with_files(&[
            (PACKED_MANIFEST_ENTRY, b"name: demo\nversion: 0.1.0\n"),
            ("capsule.wasm", b"small wasm bytes"),
        ]);

        extract_manifest_yaml("demo", "0.1.0", &archive).unwrap();
        extract_root_wasm("demo", "0.1.0", &archive).unwrap();
    }
}