cellstate_pipeline/pack/

ir.rs

//! Pack IR and validation

use crate::ast::AdapterDef as AstAdapterDef;
use crate::ast::InjectionDef as AstInjectionDef;
use crate::ast::IntentDef as AstIntentDef;
use crate::ast::{Action, InjectionMode, MemoryDef, Trigger};
use crate::ast::{AdapterType, CellstateAst, Definition, PolicyDef, PolicyRule};
use crate::ast::{EnvValue, ProviderDef as AstProviderDef, ProviderType};
use crate::compiler::{
    CompiledCredentialDelivery, CompiledInjectionMode, CompiledPackAgentConfig,
    CompiledPackInjectionConfig, CompiledPackRoutingConfig, CompiledToolConfig, CompiledToolKind,
    CompiledToolsetConfig,
};
use crate::config::*;
use std::collections::HashSet;

use super::flow::FlowDefinition;
use super::markdown::{FenceKind, MarkdownDoc};
use super::schema::*;

#[derive(Debug, Clone)]
pub struct PackIr {
    pub manifest: PackManifest,
    pub markdown: Vec<MarkdownDoc>,
    pub adapters: Vec<AstAdapterDef>,
    pub policies: Vec<PolicyDef>,
    pub injections: Vec<AstInjectionDef>,
    pub providers: Vec<AstProviderDef>,
    pub memories: Vec<MemoryDef>,
    pub intents: Vec<AstIntentDef>,
    pub flows: Vec<FlowDefinition>,
}

impl PackIr {
    /// Constructs a PackIr by validating the provided manifest, extracting configurations from
    /// Markdown fence blocks, checking for duplicates, and merging TOML- and Markdown-derived
    /// definitions into a single intermediate representation.
    ///
    /// This performs the following high-level steps:
    /// - Validates profiles, toolsets, agents, injections, and routing declared in the manifest.
    /// - Builds adapters, policies, injections, and providers from the TOML manifest.
    /// - Extracts adapters, policies, injections, and providers from Markdown fence blocks.
    /// - Checks for duplicates within Markdown and across TOML vs Markdown (adapters, policies,
    ///   providers, and injections). Duplicate definitions cause a validation error.
    /// - Merges Markdown-derived definitions into the TOML-derived lists and returns the merged IR.
    ///
    /// # Returns
    ///
    /// `Ok(Self)` containing the manifest, the original Markdown documents, and the merged lists of
    /// adapters, policies, injections, and providers on success; `Err(PackError)` if validation,
    /// TOML parsing, or Markdown extraction fails.
    ///
    /// # Examples
    ///
    /// ```ignore
    /// // Construct a PackIr from a manifest and any Markdown docs.
    /// // (The concrete construction of `manifest` and `markdown` depends on your crate's API.)
    /// # use crate::ir::{PackIr, PackManifest, MarkdownDoc};
    /// # fn build_manifest() -> PackManifest { unimplemented!() }
    /// # fn load_markdown() -> Vec<MarkdownDoc> { Vec::new() }
    /// let manifest = build_manifest();
    /// let markdown = load_markdown();
    /// let pack_ir = PackIr::new(manifest, markdown).expect("manifest and markdown must be valid");
    /// ```
    pub fn new(manifest: PackManifest, markdown: Vec<MarkdownDoc>) -> Result<Self, PackError> {
        validate_meta(&manifest)?;
        validate_defaults(&manifest)?;
        validate_profiles(&manifest)?;
        validate_toolsets(&manifest)?;
        validate_tools(&manifest)?;
        validate_agents(&manifest, &markdown)?;
        validate_injections(&manifest)?;
        validate_routing(&manifest)?;

        // Build from TOML manifest (legacy)
        let mut adapters = build_adapters(&manifest)?;
        let mut policies = build_policies(&manifest)?;
        let mut injections = build_injections(&manifest)?;
        let mut providers = build_providers(&manifest)?;

        // Extract configs from Markdown fence blocks (NEW)
        let md_adapters =
            extract_from_markdown(&markdown, FenceKind::Adapter, parse_adapter_block)?;
        let md_policies = extract_from_markdown(&markdown, FenceKind::Policy, parse_policy_block)?;
        let md_injections =
            extract_from_markdown(&markdown, FenceKind::Injection, parse_injection_block)?;
        let md_providers =
            extract_from_markdown(&markdown, FenceKind::Provider, parse_provider_block)?;
        let md_memories = extract_from_markdown(&markdown, FenceKind::Memory, parse_memory_block)?;
        let md_intents = extract_from_markdown(&markdown, FenceKind::Intent, parse_intent_block)?;
        let md_flows = extract_flows_from_markdown(&markdown)?;

        // Check for duplicates within Markdown configs
        check_markdown_duplicates(
            &md_adapters,
            &md_policies,
            &md_injections,
            &md_providers,
            &md_intents,
        )?;

        // Merge: Check for duplicates before merging
        // Default behavior: ERROR on duplicates (no silent override)

        // Check adapter duplicates
        let toml_adapter_names: HashSet<_> = adapters.iter().map(|a| &a.name).collect();
        for md_adapter in &md_adapters {
            if toml_adapter_names.contains(&md_adapter.name) {
                return Err(PackError::Validation(format!(
                    "Duplicate adapter name '{}' found in both TOML and Markdown",
                    md_adapter.name
                )));
            }
        }

        // Check policy duplicates
        let toml_policy_names: HashSet<_> = policies.iter().map(|p| &p.name).collect();
        for md_policy in &md_policies {
            if toml_policy_names.contains(&md_policy.name) {
                return Err(PackError::Validation(format!(
                    "Duplicate policy name '{}' found in both TOML and Markdown",
                    md_policy.name
                )));
            }
        }

        // Check provider duplicates
        let toml_provider_names: HashSet<_> = providers.iter().map(|p| &p.name).collect();
        for md_provider in &md_providers {
            if toml_provider_names.contains(&md_provider.name) {
                return Err(PackError::Validation(format!(
                    "Duplicate provider name '{}' found in both TOML and Markdown",
                    md_provider.name
                )));
            }
        }

        // Check injection duplicates (by source, target tuple since no name field)
        let toml_injection_keys: HashSet<_> =
            injections.iter().map(|i| (&i.source, &i.target)).collect();
        for md_injection in &md_injections {
            let key = (&md_injection.source, &md_injection.target);
            if toml_injection_keys.contains(&key) {
                return Err(PackError::Validation(format!(
                    "Duplicate injection (source: '{}', target: '{}') found in both TOML and Markdown",
                    md_injection.source, md_injection.target
                )));
            }
        }

        // All clear - merge configs
        adapters.extend(md_adapters);
        policies.extend(md_policies);
        injections.extend(md_injections);
        providers.extend(md_providers);

        Ok(Self {
            manifest,
            markdown,
            adapters,
            policies,
            injections,
            providers,
            memories: md_memories,
            intents: md_intents,
            flows: md_flows,
        })
    }
}

#[derive(Debug, Clone)]
pub enum PackError {
    Toml(String),
    Validation(String),
    Markdown(MarkdownError),
}

impl std::fmt::Display for PackError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            PackError::Toml(msg) => write!(f, "TOML error: {}", msg),
            PackError::Validation(msg) => write!(f, "Validation error: {}", msg),
            PackError::Markdown(err) => write!(f, "Markdown error: {}", err),
        }
    }
}

impl std::error::Error for PackError {}

impl From<MarkdownError> for PackError {
    fn from(err: MarkdownError) -> Self {
        PackError::Markdown(err)
    }
}

impl From<crate::compiler::CompileError> for PackError {
    fn from(err: crate::compiler::CompileError) -> Self {
        PackError::Validation(err.to_string())
    }
}

#[derive(Debug, Clone)]
pub struct MarkdownError {
    pub file: String,
    pub line: usize,
    pub column: usize,
    pub message: String,
}

impl std::fmt::Display for MarkdownError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(
            f,
            "{}:{}:{}: {}",
            self.file, self.line, self.column, self.message
        )
    }
}

fn validate_profiles(manifest: &PackManifest) -> Result<(), PackError> {
    let Some(settings) = &manifest.settings else {
        // still run provider/format reference checks below
        // even when settings.matrix is absent.
        for (name, profile) in &manifest.profiles {
            validate_profile_cross_refs(manifest, name, profile)?;
        }
        return Ok(());
    };
    let Some(matrix) = &settings.matrix else {
        for (name, profile) in &manifest.profiles {
            validate_profile_cross_refs(manifest, name, profile)?;
        }
        return Ok(());
    };
    let mut allowed = HashSet::new();
    for p in &matrix.allowed {
        allowed.insert(profile_key(
            &p.retention,
            &p.index,
            &p.embeddings,
            &p.format,
        ));
    }
    for (name, p) in &manifest.profiles {
        let key = profile_key(&p.retention, &p.index, &p.embeddings, &p.format);
        if !allowed.contains(&key) {
            return Err(PackError::Validation(format!(
                "profile '{}' does not satisfy settings.matrix.allowed",
                name
            )));
        }
        validate_profile_cross_refs(manifest, name, p)?;
    }
    Ok(())
}

fn validate_defaults(manifest: &PackManifest) -> Result<(), PackError> {
    let Some(defaults) = &manifest.defaults else {
        return Ok(());
    };

    if let Some(context_format) = defaults.context_format.as_deref() {
        let normalized = context_format.trim().to_lowercase();
        if normalized.is_empty() {
            return Err(PackError::Validation(
                "defaults.context_format must not be empty".to_string(),
            ));
        }

        let is_builtin = matches!(normalized.as_str(), "markdown" | "json" | "xml");
        if !is_builtin
            && !manifest
                .formats
                .keys()
                .any(|name| name.eq_ignore_ascii_case(context_format))
        {
            return Err(PackError::Validation(format!(
                "defaults.context_format '{}' is unknown. Define it under [formats.*] or use one of markdown|json|xml.",
                context_format
            )));
        }
    }

    Ok(())
}

fn validate_profile_cross_refs(
    manifest: &PackManifest,
    profile_name: &str,
    profile: &ProfileDef,
) -> Result<(), PackError> {
    let embeddings = profile.embeddings.trim();
    if embeddings.is_empty() {
        return Err(PackError::Validation(format!(
            "profile '{}' has empty embeddings value",
            profile_name
        )));
    }

    let embeddings_builtin = matches!(
        embeddings.to_lowercase().as_str(),
        "none" | "local" | "disabled"
    );
    if !embeddings_builtin
        && !manifest.providers.is_empty()
        && !manifest
            .providers
            .keys()
            .any(|name| name.eq_ignore_ascii_case(embeddings))
    {
        return Err(PackError::Validation(format!(
            "profile '{}' references unknown embeddings provider '{}'. Declare it under [providers.*] or use none|local|disabled.",
            profile_name, profile.embeddings
        )));
    }

    let format = profile.format.trim();
    if format.is_empty() {
        return Err(PackError::Validation(format!(
            "profile '{}' has empty format value",
            profile_name
        )));
    }

    let format_builtin = matches!(format.to_lowercase().as_str(), "markdown" | "json" | "xml");
    if !format_builtin
        && !manifest
            .formats
            .keys()
            .any(|name| name.eq_ignore_ascii_case(format))
    {
        return Err(PackError::Validation(format!(
            "profile '{}' references unknown format '{}'. Declare it under [formats.*] or use markdown|json|xml.",
            profile_name, profile.format
        )));
    }

    Ok(())
}

fn validate_toolsets(manifest: &PackManifest) -> Result<(), PackError> {
    let tool_ids = collect_tool_ids(&manifest.tools);
    for (set_name, set) in &manifest.toolsets {
        for tool in &set.tools {
            if !tool_ids.contains(tool) {
                return Err(PackError::Validation(format!(
                    "toolset '{}' references unknown tool id '{}'",
                    set_name, tool
                )));
            }
        }
    }
    Ok(())
}

fn validate_agents(manifest: &PackManifest, markdown: &[MarkdownDoc]) -> Result<(), PackError> {
    let toolsets: HashSet<String> = manifest.toolsets.keys().cloned().collect();
    let profiles: HashSet<String> = manifest.profiles.keys().cloned().collect();
    let adapters: HashSet<String> = manifest.adapters.keys().cloned().collect();
    let formats: HashSet<String> = manifest.formats.keys().cloned().collect();
    let md_paths: HashSet<String> = markdown.iter().map(|m| m.file.clone()).collect();

    for (name, agent) in &manifest.agents {
        // Validate profile reference exists
        if !profiles.contains(&agent.profile) {
            return Err(PackError::Validation(format!(
                "agent '{}' references unknown profile '{}'. Available profiles: {:?}",
                name,
                agent.profile,
                profiles.iter().collect::<Vec<_>>()
            )));
        }

        // Validate adapter reference exists (if specified)
        if let Some(ref adapter_name) = agent.adapter {
            if !adapters.contains(adapter_name) {
                return Err(PackError::Validation(format!(
                    "agent '{}' references unknown adapter '{}'. Available adapters: {:?}",
                    name,
                    adapter_name,
                    adapters.iter().collect::<Vec<_>>()
                )));
            }
        }

        // Validate format reference exists (if specified)
        if let Some(ref format_name) = agent.format {
            let builtin = matches!(
                format_name.trim().to_lowercase().as_str(),
                "markdown" | "json" | "xml"
            );
            if !builtin && !formats.contains(format_name) {
                return Err(PackError::Validation(format!(
                    "agent '{}' references unknown format '{}'. Available formats: {:?}",
                    name,
                    format_name,
                    formats.iter().collect::<Vec<_>>()
                )));
            }
        }

        // Validate token_budget is positive (if specified)
        if let Some(budget) = agent.token_budget {
            if budget <= 0 {
                return Err(PackError::Validation(format!(
                    "agent '{}' has invalid token_budget '{}'. Must be greater than 0.",
                    name, budget
                )));
            }
        }

        // Validate toolset references
        for toolset in &agent.toolsets {
            if !toolsets.contains(toolset) {
                return Err(PackError::Validation(format!(
                    "agent '{}' references unknown toolset '{}'",
                    name, toolset
                )));
            }
        }

        // Validate prompt markdown path
        if !md_paths.contains(&agent.prompt_md) {
            // allow relative path match by suffix
            let found = md_paths.iter().any(|p| p.ends_with(&agent.prompt_md));
            if !found {
                return Err(PackError::Validation(format!(
                    "agent '{}' prompt_md '{}' not found in pack markdowns",
                    name, agent.prompt_md
                )));
            }
        }
    }
    Ok(())
}

fn validate_tools(manifest: &PackManifest) -> Result<(), PackError> {
    for (name, tool) in &manifest.tools.prompts {
        if tool.prompt_md.trim().is_empty() {
            return Err(PackError::Validation(format!(
                "tools.prompts.{}: prompt_md must not be empty",
                name
            )));
        }

        if let Some(result_format) = tool.result_format.as_deref() {
            let normalized = result_format.trim().to_lowercase();
            if normalized.is_empty() {
                return Err(PackError::Validation(format!(
                    "tools.prompts.{}: result_format must not be empty",
                    name
                )));
            }

            let is_builtin = matches!(normalized.as_str(), "markdown" | "json" | "xml");
            if !is_builtin
                && !manifest
                    .formats
                    .keys()
                    .any(|format_name| format_name.eq_ignore_ascii_case(result_format))
            {
                return Err(PackError::Validation(format!(
                    "tools.prompts.{}: result_format '{}' is unknown. Define it under [formats.*] or use markdown|json|xml.",
                    name, result_format
                )));
            }
        }
    }

    for (name, tool) in &manifest.tools.bin {
        for provider in &tool.oauth_providers {
            let provider = provider.trim();
            if provider.is_empty() {
                return Err(PackError::Validation(format!(
                    "tools.bin.{}: oauth_providers contains an empty provider name",
                    name
                )));
            }

            if !manifest
                .providers
                .keys()
                .any(|known| known.eq_ignore_ascii_case(provider))
            {
                return Err(PackError::Validation(format!(
                    "tools.bin.{}: oauth_providers references unknown provider '{}'. Declare it under [providers.*].",
                    name, provider
                )));
            }
        }

        for provider in tool.oauth_required_scopes.keys() {
            let provider = provider.trim();
            if provider.is_empty() {
                return Err(PackError::Validation(format!(
                    "tools.bin.{}: oauth_required_scopes contains an empty provider key",
                    name
                )));
            }

            if !tool
                .oauth_providers
                .iter()
                .any(|configured| configured.trim().eq_ignore_ascii_case(provider))
            {
                return Err(PackError::Validation(format!(
                    "tools.bin.{}: oauth_required_scopes references provider '{}' which is not declared in oauth_providers",
                    name, provider
                )));
            }

            if !manifest
                .providers
                .keys()
                .any(|known| known.eq_ignore_ascii_case(provider))
            {
                return Err(PackError::Validation(format!(
                    "tools.bin.{}: oauth_required_scopes references unknown provider '{}'. Declare it under [providers.*].",
                    name, provider
                )));
            }
        }
    }

    Ok(())
}

/// Maximum priority allowed for pack injections.
/// Priorities 900+ are reserved for platform-level injections.
const MAX_PACK_INJECTION_PRIORITY: i32 = 899;

fn validate_injections(manifest: &PackManifest) -> Result<(), PackError> {
    for (name, injection) in &manifest.injections {
        if injection.source.trim().is_empty() {
            return Err(PackError::Validation(format!(
                "injections.{}: source must not be empty",
                name
            )));
        }
        if injection.target.trim().is_empty() {
            return Err(PackError::Validation(format!(
                "injections.{}: target must not be empty",
                name
            )));
        }

        // Validate entity type if specified
        if let Some(entity_type) = injection.entity_type.as_deref() {
            let normalized = entity_type.to_lowercase();
            let valid = matches!(
                normalized.as_str(),
                "note" | "notes" | "artifact" | "artifacts"
            );
            if !valid {
                return Err(PackError::Validation(format!(
                    "injections.{}: invalid entity_type '{}' (expected 'note' or 'artifact')",
                    name, entity_type
                )));
            }
        }

        // Validate priority is within pack range (0-899)
        if injection.priority > MAX_PACK_INJECTION_PRIORITY {
            return Err(PackError::Validation(format!(
                "injections.{}: priority {} exceeds pack maximum ({}). Priorities {}+ are reserved for platform.",
                name, injection.priority, MAX_PACK_INJECTION_PRIORITY, MAX_PACK_INJECTION_PRIORITY + 1
            )));
        }

        if let Some(max_tokens) = injection.max_tokens {
            if max_tokens <= 0 {
                return Err(PackError::Validation(format!(
                    "injections.{}: max_tokens must be greater than 0",
                    name
                )));
            }
        }

        if let Some(top_k) = injection.top_k {
            if top_k == 0 {
                return Err(PackError::Validation(format!(
                    "injections.{}: top_k must be greater than 0",
                    name
                )));
            }
        }

        if let Some(threshold) = injection.threshold {
            if !(0.0..=1.0).contains(&threshold) {
                return Err(PackError::Validation(format!(
                    "injections.{}: threshold must be within [0.0, 1.0]",
                    name
                )));
            }
        }
    }
    Ok(())
}

fn validate_meta(manifest: &PackManifest) -> Result<(), PackError> {
    let Some(meta) = manifest.meta.as_ref() else {
        return Ok(());
    };
    if let Some(spec) = meta.spec.as_deref() {
        if spec != "cstate.toml/v1.0" {
            return Err(PackError::Validation(format!(
                "meta.spec: unsupported value '{}'. Expected \"cstate.toml/v1.0\"",
                spec
            )));
        }
    }
    if meta.project.is_none() {
        return Err(PackError::Validation(
            "meta.project is required. Set it to your project name, e.g. project = \"my-agent\""
                .to_string(),
        ));
    }
    Ok(())
}

fn validate_routing(manifest: &PackManifest) -> Result<(), PackError> {
    let Some(routing) = manifest.routing.as_ref() else {
        return Ok(());
    };

    if let Some(strategy) = routing.strategy.as_deref() {
        let strategy = strategy.to_lowercase();
        let valid = matches!(
            strategy.as_str(),
            "first" | "round_robin" | "roundrobin" | "random" | "least_latency" | "leastlatency"
        );
        if !valid {
            return Err(PackError::Validation(format!(
                "routing.strategy: invalid value '{}' (expected first|round_robin|random|least_latency)",
                strategy
            )));
        }
    }

    if let Some(provider) = routing.embedding_provider.as_deref() {
        if !manifest.providers.contains_key(provider) {
            return Err(PackError::Validation(format!(
                "routing.embedding_provider: unknown provider '{}'",
                provider
            )));
        }
    }

    if let Some(provider) = routing.summarization_provider.as_deref() {
        if !manifest.providers.contains_key(provider) {
            return Err(PackError::Validation(format!(
                "routing.summarization_provider: unknown provider '{}'",
                provider
            )));
        }
    }

    if let Some(provider) = routing.chat_provider.as_deref() {
        if !manifest.providers.contains_key(provider) {
            return Err(PackError::Validation(format!(
                "routing.chat_provider: unknown provider '{}'",
                provider
            )));
        }
    }

    if let Some(provider_order) = routing.provider_order.as_ref() {
        for provider in provider_order {
            if !manifest.providers.contains_key(provider) {
                return Err(PackError::Validation(format!(
                    "routing.provider_order references unknown provider '{}'",
                    provider
                )));
            }
        }
    }

    Ok(())
}

fn collect_tool_ids(tools: &ToolsSection) -> HashSet<String> {
    let mut ids = HashSet::new();
    for name in tools.bin.keys() {
        ids.insert(format!("tools.bin.{}", name));
    }
    for name in tools.prompts.keys() {
        ids.insert(format!("tools.prompts.{}", name));
    }
    for name in tools.bash.keys() {
        ids.insert(format!("tools.bash.{}", name));
    }
    for name in tools.browser.keys() {
        ids.insert(format!("tools.browser.{}", name));
    }
    for name in tools.composio.keys() {
        ids.insert(format!("tools.composio.{}", name));
    }
    // Composio Gateway meta-tool (synthesized at compile time if enabled)
    if tools.composio_gateway.as_ref().is_some_and(|gw| gw.enabled) {
        ids.insert("composio_search_tools".to_string());
    }
    ids
}

/// Contract files loaded from the pack for schema compilation.
pub type ContractFiles = std::collections::HashMap<String, String>;

/// Validate that a tool command is a safe executable path.
///
/// Commands must be:
/// - A relative path starting with `./tools/`
/// - Free of shell metacharacters that could enable injection
/// - Free of path traversal sequences (`..`)
///
/// This prevents shell injection attacks like `cmd = "rm -rf / && echo hacked"`
/// and path traversal attacks like `cmd = "./tools/../../../bin/sh"`.
fn is_valid_executable_path(cmd: &str) -> bool {
    // Forbidden shell metacharacters
    const FORBIDDEN: &[char] = &[
        ';', '|', '&', '$', '`', '(', ')', '{', '}', '<', '>', '!', '\n', '\r',
    ];

    // Must not contain forbidden characters
    if cmd.chars().any(|c| FORBIDDEN.contains(&c)) {
        return false;
    }

    // Block path traversal attempts (e.g., "../../../etc/passwd")
    if cmd.contains("..") {
        return false;
    }

    // Must be under ./tools to prevent arbitrary absolute/bare executable invocation.
    // This keeps execution constrained to explicitly provisioned tool binaries/scripts.
    cmd.starts_with("./tools/")
}

/// Compile pack tool registry into runtime tool configs.
/// `contracts` maps contract paths to their JSON content.
pub fn compile_tools(
    manifest: &PackManifest,
    contracts: &ContractFiles,
) -> Result<Vec<CompiledToolConfig>, PackError> {
    let mut tools = Vec::new();

    for (name, def) in &manifest.tools.bin {
        // Validate command is a safe executable path, not arbitrary shell
        if !is_valid_executable_path(&def.cmd) {
            return Err(PackError::Validation(format!(
                "tools.bin.{}: cmd must be a relative executable path under ./tools/ \
                and must not contain shell metacharacters. Got: '{}'",
                name, def.cmd
            )));
        }

        let oauth_required_scopes = if def.oauth_required_scopes.is_empty() {
            None
        } else {
            let mut out = std::collections::HashMap::new();
            for (provider, scopes) in &def.oauth_required_scopes {
                let provider = provider.trim().to_ascii_lowercase();
                if provider.is_empty() {
                    return Err(PackError::Validation(format!(
                        "tools.bin.{}: oauth_required_scopes has empty provider key",
                        name
                    )));
                }
                if !def
                    .oauth_providers
                    .iter()
                    .any(|configured| configured.trim().eq_ignore_ascii_case(&provider))
                {
                    return Err(PackError::Validation(format!(
                        "tools.bin.{}: oauth_required_scopes references provider '{}' which is not declared in oauth_providers",
                        name, provider
                    )));
                }

                let mut normalized_scopes = scopes
                    .iter()
                    .map(|scope| scope.trim().to_string())
                    .filter(|scope| !scope.is_empty())
                    .collect::<Vec<_>>();
                normalized_scopes.sort();
                normalized_scopes.dedup();
                if normalized_scopes.is_empty() {
                    return Err(PackError::Validation(format!(
                        "tools.bin.{}: oauth_required_scopes for provider '{}' must include at least one scope",
                        name, provider
                    )));
                }
                out.insert(provider, normalized_scopes);
            }
            Some(out)
        };

        let credential_delivery = match def.credential_delivery.as_deref() {
            None => None,
            Some(raw) => match raw.trim().to_ascii_lowercase().as_str() {
                "environment" => Some(CompiledCredentialDelivery::Environment),
                "file" => Some(CompiledCredentialDelivery::File),
                other => {
                    return Err(PackError::Validation(format!(
                        "tools.bin.{}: invalid credential_delivery '{}' (expected 'environment' or 'file')",
                        name, other
                    )));
                }
            },
        };

        // Auto-detect WASM tools by file extension: .wasm files get
        // WasmExec kind (Level 2 wasmtime sandbox), all others get Exec.
        let kind = if def.cmd.ends_with(".wasm") {
            CompiledToolKind::WasmExec
        } else {
            CompiledToolKind::Exec
        };

        tools.push(CompiledToolConfig {
            id: format!("tools.bin.{}", name),
            kind,
            cmd: Some(def.cmd.clone()),
            prompt_md: None,
            contract: None,
            compiled_schema: None,
            result_format: None,
            timeout_ms: def.timeout_ms,
            allow_network: def.allow_network,
            allow_fs: def.allow_fs,
            allow_subprocess: def.allow_subprocess,
            credential_delivery,
            oauth_providers: if def.oauth_providers.is_empty() {
                None
            } else {
                Some(def.oauth_providers.clone())
            },
            oauth_required_scopes,
            allowed_commands: None,
            blocked_commands: None,
            requires_challenge: None,
            allowed_domains: None,
            blocked_domains: None,
            max_navigations: None,
            max_duration_ms: None,
            use_vision: None,
            composio_toolkit: None,
            composio_actions: None,
            is_composio_gateway: None,
        });
    }

    for (name, def) in &manifest.tools.prompts {
        // If contract specified, compile the schema
        let compiled_schema = if let Some(contract_path) = &def.contract {
            let json_str = contracts.get(contract_path).ok_or_else(|| {
                PackError::Validation(format!(
                    "tools.prompts.{}: contract file '{}' not found",
                    name, contract_path
                ))
            })?;
            let schema: serde_json::Value = serde_json::from_str(json_str).map_err(|e| {
                PackError::Validation(format!(
                    "tools.prompts.{}: contract '{}' is invalid JSON: {}",
                    name, contract_path, e
                ))
            })?;
            Some(schema)
        } else {
            None
        };

        tools.push(CompiledToolConfig {
            id: format!("tools.prompts.{}", name),
            kind: CompiledToolKind::Prompt,
            cmd: None,
            prompt_md: Some(def.prompt_md.clone()),
            contract: def.contract.clone(),
            compiled_schema,
            result_format: def.result_format.clone(),
            timeout_ms: def.timeout_ms,
            allow_network: None,
            allow_fs: None,
            allow_subprocess: None,
            credential_delivery: None,
            oauth_providers: None,
            oauth_required_scopes: None,
            allowed_commands: None,
            blocked_commands: None,
            requires_challenge: None,
            allowed_domains: None,
            blocked_domains: None,
            max_navigations: None,
            max_duration_ms: None,
            use_vision: None,
            composio_toolkit: None,
            composio_actions: None,
            is_composio_gateway: None,
        });
    }

    // Compile bash tools
    for (name, def) in &manifest.tools.bash {
        tools.push(CompiledToolConfig {
            id: format!("tools.bash.{}", name),
            kind: CompiledToolKind::Bash,
            cmd: None,
            prompt_md: None,
            contract: None,
            compiled_schema: None,
            result_format: None,
            timeout_ms: def.timeout_ms,
            allow_network: def.allow_network,
            allow_fs: def.allow_fs,
            allow_subprocess: None,
            credential_delivery: None,
            oauth_providers: None,
            oauth_required_scopes: None,
            allowed_commands: if def.allowed_commands.is_empty() {
                None
            } else {
                Some(def.allowed_commands.clone())
            },
            blocked_commands: if def.blocked_commands.is_empty() {
                None
            } else {
                Some(def.blocked_commands.clone())
            },
            requires_challenge: None,
            allowed_domains: None,
            blocked_domains: None,
            max_navigations: None,
            max_duration_ms: None,
            use_vision: None,
            composio_toolkit: None,
            composio_actions: None,
            is_composio_gateway: None,
        });
    }

    // Compile browser tools
    for (name, def) in &manifest.tools.browser {
        tools.push(CompiledToolConfig {
            id: format!("tools.browser.{}", name),
            kind: CompiledToolKind::Browser,
            cmd: None,
            prompt_md: None,
            contract: None,
            compiled_schema: None,
            result_format: None,
            timeout_ms: def.timeout_ms,
            allow_network: def.allow_network,
            allow_fs: None,
            allow_subprocess: None,
            credential_delivery: None,
            oauth_providers: None,
            oauth_required_scopes: None,
            allowed_commands: None,
            blocked_commands: None,
            requires_challenge: None,
            allowed_domains: if def.allowed_domains.is_empty() {
                None
            } else {
                Some(def.allowed_domains.clone())
            },
            blocked_domains: if def.blocked_domains.is_empty() {
                None
            } else {
                Some(def.blocked_domains.clone())
            },
            max_navigations: def.max_navigations,
            max_duration_ms: def.max_duration_ms,
            use_vision: def.use_vision,
            composio_toolkit: None,
            composio_actions: None,
            is_composio_gateway: None,
        });
    }

    // Compile composio tools
    for (name, def) in &manifest.tools.composio {
        tools.push(CompiledToolConfig {
            id: format!("tools.composio.{}", name),
            kind: CompiledToolKind::Composio,
            cmd: None,
            prompt_md: None,
            contract: None,
            compiled_schema: None,
            result_format: None,
            timeout_ms: def.timeout_ms,
            allow_network: Some(true), // Composio always needs network
            allow_fs: None,
            allow_subprocess: None,
            credential_delivery: None,
            oauth_providers: None,
            oauth_required_scopes: None,
            allowed_commands: None,
            blocked_commands: None,
            requires_challenge: None,
            allowed_domains: None,
            blocked_domains: None,
            max_navigations: None,
            max_duration_ms: None,
            use_vision: None,
            composio_toolkit: Some(def.toolkit.clone()),
            composio_actions: if def.actions.is_empty() {
                None
            } else {
                Some(def.actions.clone())
            },
            is_composio_gateway: None,
        });
    }

    // Compile Composio Gateway meta-tool (if enabled)
    if let Some(ref gateway) = manifest.tools.composio_gateway {
        if gateway.enabled {
            tools.push(CompiledToolConfig {
                id: "composio_search_tools".to_string(),
                kind: CompiledToolKind::ComposioGateway,
                cmd: None,
                prompt_md: None,
                contract: None,
                compiled_schema: None,
                result_format: None,
                timeout_ms: Some(30_000),
                allow_network: Some(true),
                allow_fs: None,
                allow_subprocess: None,
                credential_delivery: None,
                oauth_providers: None,
                oauth_required_scopes: None,
                allowed_commands: None,
                blocked_commands: None,
                requires_challenge: None,
                allowed_domains: None,
                blocked_domains: None,
                max_navigations: None,
                max_duration_ms: None,
                use_vision: None,
                composio_toolkit: None,
                composio_actions: None,
                is_composio_gateway: Some(true),
            });
        }
    }

    Ok(tools)
}

/// Compile pack toolsets into runtime toolset configs.
pub fn compile_toolsets(manifest: &PackManifest) -> Vec<CompiledToolsetConfig> {
    manifest
        .toolsets
        .iter()
        .map(|(name, set)| CompiledToolsetConfig {
            name: name.clone(),
            tools: set.tools.clone(),
        })
        .collect()
}

/// Compile pack agent bindings to toolsets with extracted markdown metadata.
///
/// This function transforms manifest agent definitions into runtime-ready
/// configurations, combining TOML settings with markdown-extracted metadata.
/// All reference validations (profile, adapter, format, toolsets) have been
/// performed during the IR validation phase.
pub fn compile_pack_agents(
    manifest: &PackManifest,
    markdown_docs: &[super::MarkdownDoc],
) -> Vec<CompiledPackAgentConfig> {
    // Build lookup from markdown file path to extracted data
    let md_by_path: std::collections::HashMap<&str, &super::MarkdownDoc> =
        markdown_docs.iter().map(|m| (m.file.as_str(), m)).collect();

    manifest
        .agents
        .iter()
        .map(|(name, agent)| {
            // Find matching markdown doc by prompt_md path
            let md: Option<&super::MarkdownDoc> = md_by_path
                .get(agent.prompt_md.as_str())
                .copied()
                .or_else(|| {
                    // Try suffix match for relative paths
                    md_by_path
                        .iter()
                        .find(|(path, _)| path.ends_with(&agent.prompt_md))
                        .map(|(_, doc)| *doc)
                });

            let (constraints, tool_refs, rag_config, system_prompt) = match md {
                Some(doc) => (
                    doc.extracted_constraints.clone(),
                    doc.extracted_tool_refs.clone(),
                    doc.extracted_rag_config.clone(),
                    Some(doc.system.clone()).filter(|s| !s.is_empty()),
                ),
                None => (Vec::new(), Vec::new(), None, None),
            };

            // PROFILE INHERITANCE: Resolve format from agent or profile
            let profile_def = manifest.profiles.get(&agent.profile);
            let resolved_format = agent
                .format
                .clone()
                .or_else(|| profile_def.map(|p| p.format.clone()))
                .unwrap_or_else(|| "markdown".to_string());

            CompiledPackAgentConfig {
                name: name.clone(),
                enabled: agent.enabled.unwrap_or(true),
                profile: agent.profile.clone(),
                adapter: agent.adapter.clone(),
                format: agent.format.clone(),
                resolved_format,
                token_budget: agent.token_budget,
                prompt_md: agent.prompt_md.clone(),
                toolsets: agent.toolsets.clone(),
                extracted_constraints: constraints,
                extracted_tool_refs: tool_refs,
                extracted_rag_config: rag_config,
                description: agent.description.clone(),
                tags: agent.tags.clone(),
                system_prompt,
            }
        })
        .collect()
}

/// Compile pack injection metadata for runtime wiring.
pub fn compile_pack_injections(
    manifest: &PackManifest,
) -> Result<Vec<CompiledPackInjectionConfig>, PackError> {
    let mut out = Vec::new();
    for def in manifest.injections.values() {
        let mode = compile_injection_mode_compiled(def)?;
        out.push(CompiledPackInjectionConfig {
            source: def.source.clone(),
            target: def.target.clone(),
            entity_type: def.entity_type.clone().map(|s| s.to_lowercase()),
            mode,
            priority: def.priority,
            max_tokens: def.max_tokens,
        });
    }
    Ok(out)
}

/// Compile pack provider routing hints.
pub fn compile_pack_routing(manifest: &PackManifest) -> Option<CompiledPackRoutingConfig> {
    manifest
        .routing
        .as_ref()
        .map(|routing| CompiledPackRoutingConfig {
            strategy: routing.strategy.clone().map(|s| s.to_lowercase()),
            embedding_provider: routing.embedding_provider.clone(),
            summarization_provider: routing.summarization_provider.clone(),
            chat_provider: routing.chat_provider.clone(),
            sort: routing.sort.clone(),
            zdr: routing.zdr,
            provider_order: routing.provider_order.clone(),
            data_collection: routing.data_collection.clone(),
        })
}

fn build_adapters(manifest: &PackManifest) -> Result<Vec<AstAdapterDef>, PackError> {
    let mut adapters = Vec::new();
    for (name, def) in &manifest.adapters {
        let adapter_type = match def.adapter_type.to_lowercase().as_str() {
            "postgres" => AdapterType::Postgres,
            "redis" => AdapterType::Redis,
            "memory" => AdapterType::Memory,
            other => {
                return Err(PackError::Validation(format!(
                    "adapter '{}' has invalid type '{}'",
                    name, other
                )))
            }
        };
        let options = def
            .options
            .iter()
            .map(|(k, v)| (k.clone(), v.clone()))
            .collect();
        adapters.push(AstAdapterDef {
            name: name.clone(),
            adapter_type,
            connection: def.connection.clone(),
            options,
        });
    }
    Ok(adapters)
}

fn build_policies(manifest: &PackManifest) -> Result<Vec<PolicyDef>, PackError> {
    let mut policies = Vec::new();
    for (name, def) in &manifest.policies {
        let trigger = parse_trigger(&def.trigger)?;
        let mut actions = Vec::new();
        for action in &def.actions {
            actions.push(parse_action(action)?);
        }
        policies.push(PolicyDef {
            name: name.clone(),
            rules: vec![PolicyRule { trigger, actions }],
        });
    }
    Ok(policies)
}

fn build_injections(manifest: &PackManifest) -> Result<Vec<AstInjectionDef>, PackError> {
    let mut injections = Vec::new();
    for def in manifest.injections.values() {
        let mode = parse_injection_mode(def)?;
        injections.push(AstInjectionDef {
            source: def.source.clone(),
            target: def.target.clone(),
            mode,
            priority: def.priority,
            max_tokens: def.max_tokens,
            filter: None,
        });
    }
    Ok(injections)
}

fn build_providers(manifest: &PackManifest) -> Result<Vec<AstProviderDef>, PackError> {
    let mut providers = Vec::new();
    for (name, def) in &manifest.providers {
        let provider_type = match def.provider_type.to_lowercase().as_str() {
            "openai" => ProviderType::OpenAI,
            "anthropic" => ProviderType::Anthropic,
            "custom" => ProviderType::Custom,
            other => {
                return Err(PackError::Validation(format!(
                    "provider '{}' has invalid type '{}'",
                    name, other
                )))
            }
        };

        let api_key = parse_env_value(def.api_key.expose_secret());
        let options = def
            .options
            .iter()
            .map(|(k, v)| (k.clone(), v.clone()))
            .collect::<Vec<_>>();

        providers.push(AstProviderDef {
            name: name.clone(),
            provider_type,
            api_key,
            model: def.model.clone(),
            options,
        });
    }
    Ok(providers)
}

fn parse_env_value(value: &str) -> EnvValue {
    if let Some(rest) = value.strip_prefix("env:") {
        EnvValue::Env(rest.trim().to_string())
    } else {
        EnvValue::Literal(value.to_string())
    }
}

fn parse_trigger(value: &str) -> Result<Trigger, PackError> {
    match value.to_lowercase().as_str() {
        "task_start" => Ok(Trigger::TaskStart),
        "task_end" => Ok(Trigger::TaskEnd),
        "scope_close" => Ok(Trigger::ScopeClose),
        "turn_end" => Ok(Trigger::TurnEnd),
        "manual" => Ok(Trigger::Manual),
        other if other.starts_with("schedule:") => Ok(Trigger::Schedule(
            other["schedule:".len()..].trim().to_string(),
        )),
        other => Err(PackError::Validation(format!(
            "invalid trigger '{}'",
            other
        ))),
    }
}

fn parse_action(action: &PolicyActionDef) -> Result<Action, PackError> {
    let typ = action.action_type.to_lowercase();
    match typ.as_str() {
        "summarize" => Ok(Action::Summarize(action.target.clone().ok_or_else(
            || PackError::Validation("summarize action missing target".into()),
        )?)),
        "checkpoint" => Ok(Action::Checkpoint(action.target.clone().ok_or_else(
            || PackError::Validation("checkpoint action missing target".into()),
        )?)),
        "extract_artifacts" => Ok(Action::ExtractArtifacts(action.target.clone().ok_or_else(
            || PackError::Validation("extract_artifacts action missing target".into()),
        )?)),
        "notify" => Ok(Action::Notify(action.target.clone().ok_or_else(|| {
            PackError::Validation("notify action missing target".into())
        })?)),
        "inject" => Ok(Action::Inject {
            target: action
                .target
                .clone()
                .ok_or_else(|| PackError::Validation("inject action missing target".into()))?,
            mode: InjectionMode::Full,
        }),
        other => Err(PackError::Validation(format!(
            "unsupported action type '{}'",
            other
        ))),
    }
}

fn parse_injection_mode(def: &InjectionDef) -> Result<InjectionMode, PackError> {
    match def.mode.to_lowercase().as_str() {
        "full" => Ok(InjectionMode::Full),
        "summary" => Ok(InjectionMode::Summary),
        "topk" => Ok(InjectionMode::TopK(def.top_k.ok_or_else(|| {
            PackError::Validation("topk mode requires top_k".into())
        })?)),
        "relevant" => Ok(InjectionMode::Relevant(def.threshold.ok_or_else(|| {
            PackError::Validation("relevant mode requires threshold".into())
        })?)),
        other => Err(PackError::Validation(format!(
            "invalid injection mode '{}'",
            other
        ))),
    }
}

fn compile_injection_mode_compiled(def: &InjectionDef) -> Result<CompiledInjectionMode, PackError> {
    match def.mode.to_lowercase().as_str() {
        "full" => Ok(CompiledInjectionMode::Full),
        "summary" => Ok(CompiledInjectionMode::Summary),
        "topk" => {
            let k = def
                .top_k
                .ok_or_else(|| PackError::Validation("topk mode requires top_k".into()))?;
            let k = i32::try_from(k)
                .map_err(|e| PackError::Validation(format!("top_k out of range: {e}")))?;
            Ok(CompiledInjectionMode::TopK { k })
        }
        "relevant" => {
            let threshold = def
                .threshold
                .ok_or_else(|| PackError::Validation("relevant mode requires threshold".into()))?;
            Ok(CompiledInjectionMode::Relevant { threshold })
        }
        other => Err(PackError::Validation(format!(
            "invalid injection mode '{}'",
            other
        ))),
    }
}

fn profile_key(ret: &str, idx: &str, emb: &str, fmt: &str) -> String {
    format!(
        "{}|{}|{}|{}",
        ret.to_lowercase(),
        idx.to_lowercase(),
        emb.to_lowercase(),
        fmt.to_lowercase()
    )
}

/// Builds a CELLSTATE AST from a pack intermediate representation.
///
/// The resulting AST contains definitions for adapters, policies, injections, and providers
/// extracted from the given `PackIr`. The AST version is taken from `ir.manifest.meta.version`
/// if present; otherwise `"1.0"` is used.
///
/// # Examples
///
/// ```
/// // Construct a minimal PackIr (fields elided for brevity) and convert it.
/// // let ir = PackIr { manifest: ..., markdown: vec![], adapters: vec![], policies: vec![], injections: vec![], providers: vec![] };
/// // let ast = ast_from_ir(&ir);
/// // assert_eq!(ast.version, "1.0");
/// ```
pub fn ast_from_ir(ir: &PackIr) -> CellstateAst {
    let mut defs: Vec<Definition> = Vec::new();
    for a in &ir.adapters {
        defs.push(Definition::Adapter(a.clone()));
    }
    for p in &ir.policies {
        defs.push(Definition::Policy(p.clone()));
    }
    for i in &ir.injections {
        defs.push(Definition::Injection(i.clone()));
    }
    for provider in &ir.providers {
        defs.push(Definition::Provider(provider.clone()));
    }
    for memory in &ir.memories {
        defs.push(Definition::Memory(memory.clone()));
    }
    for intent in &ir.intents {
        defs.push(Definition::Intent(intent.clone()));
    }
    CellstateAst {
        version: ir
            .manifest
            .meta
            .as_ref()
            .and_then(|m| m.version.clone())
            .unwrap_or_else(|| "1.0".to_string()),
        definitions: defs,
    }
}

// ============================================================================
// MARKDOWN CONFIG EXTRACTION (NEW)
// ============================================================================

/// Validates that Markdown-extracted adapters, policies, injections, and providers contain no duplicate definitions.
///
/// Returns an error if any adapter, policy, or provider name appears more than once, or if any injection's (source, target) pair is duplicated.
///
/// # Errors
///
/// Returns `PackError::Validation` with a descriptive message for the first duplicate encountered.
///
/// # Examples
///
/// ```ignore
/// // Accepts empty collections when there are no duplicates
/// let adapters: Vec<_> = vec![];
/// let policies: Vec<_> = vec![];
/// let injections: Vec<_> = vec![];
/// let providers: Vec<_> = vec![];
/// assert!(check_markdown_duplicates(&adapters, &policies, &injections, &providers).is_ok());
/// ```
fn check_markdown_duplicates(
    adapters: &[AstAdapterDef],
    policies: &[PolicyDef],
    injections: &[AstInjectionDef],
    providers: &[AstProviderDef],
    intents: &[AstIntentDef],
) -> Result<(), PackError> {
    // Check for duplicate adapter names
    let mut adapter_names = HashSet::new();
    for adapter in adapters {
        if !adapter_names.insert(&adapter.name) {
            return Err(PackError::Validation(format!(
                "Duplicate adapter name '{}' found in Markdown configs",
                adapter.name
            )));
        }
    }

    // Check for duplicate policy names
    let mut policy_names = HashSet::new();
    for policy in policies {
        if !policy_names.insert(&policy.name) {
            return Err(PackError::Validation(format!(
                "Duplicate policy name '{}' found in Markdown configs",
                policy.name
            )));
        }
    }

    // Check for duplicate provider names
    let mut provider_names = HashSet::new();
    for provider in providers {
        if !provider_names.insert(&provider.name) {
            return Err(PackError::Validation(format!(
                "Duplicate provider name '{}' found in Markdown configs",
                provider.name
            )));
        }
    }

    // Check for duplicate injection (source, target) tuples
    let mut injection_keys = HashSet::new();
    for injection in injections {
        let key = (&injection.source, &injection.target);
        if !injection_keys.insert(key) {
            return Err(PackError::Validation(format!(
                "Duplicate injection (source: '{}', target: '{}') found in Markdown configs",
                injection.source, injection.target
            )));
        }
    }

    // Check for duplicate intent names
    let mut intent_names = HashSet::new();
    for intent in intents {
        if !intent_names.insert(&intent.name) {
            return Err(PackError::Validation(format!(
                "Duplicate intent name '{}' found in Markdown configs",
                intent.name
            )));
        }
    }

    Ok(())
}

/// Generic helper that extracts items from Markdown fence blocks.
///
/// Scans all documents, users, and blocks for blocks matching `kind`, then
/// calls `parser` on each match. This eliminates the repeated triple-nested
/// loop that was duplicated across the six typed extraction functions.
fn extract_from_markdown<T>(
    markdown: &[MarkdownDoc],
    kind: FenceKind,
    parser: impl Fn(Option<&str>, &str) -> Result<T, ConfigError>,
) -> Result<Vec<T>, PackError> {
    let mut items = Vec::new();
    for doc in markdown {
        for user in &doc.users {
            for block in &user.blocks {
                if block.kind == kind {
                    let item = parser(block.header_name.as_deref(), &block.content)?;
                    items.push(item);
                }
            }
        }
    }
    Ok(items)
}

/// Extract flow definitions from Markdown fence blocks.
fn extract_flows_from_markdown(markdown: &[MarkdownDoc]) -> Result<Vec<FlowDefinition>, PackError> {
    let mut flows = Vec::new();

    for doc in markdown {
        for user in &doc.users {
            for block in &user.blocks {
                if block.kind == FenceKind::Flow {
                    let flow: FlowDefinition = serde_yaml::from_str(&block.content)
                        .map_err(|e| PackError::Validation(format!("Invalid flow YAML: {}", e)))?;
                    flows.push(flow);
                }
            }
        }
    }

    Ok(flows)
}

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

    // ── parse_env_value ────────────────────────────────────────────────

    #[test]
    fn parse_env_value_literal() -> Result<(), PackError> {
        match parse_env_value("hello world") {
            EnvValue::Literal(v) => assert_eq!(v, "hello world"),
            other => {
                return Err(PackError::Validation(format!(
                    "expected Literal, got {:?}",
                    other
                )))
            }
        }
        Ok(())
    }

    #[test]
    fn parse_env_value_env_ref() -> Result<(), PackError> {
        match parse_env_value("env:MY_VAR") {
            EnvValue::Env(v) => assert_eq!(v, "MY_VAR"),
            other => {
                return Err(PackError::Validation(format!(
                    "expected Env, got {:?}",
                    other
                )))
            }
        }
        Ok(())
    }

    #[test]
    fn parse_env_value_env_ref_trimmed() -> Result<(), PackError> {
        match parse_env_value("env:  SPACED_VAR  ") {
            EnvValue::Env(v) => assert_eq!(v, "SPACED_VAR"),
            other => {
                return Err(PackError::Validation(format!(
                    "expected Env, got {:?}",
                    other
                )))
            }
        }
        Ok(())
    }

    #[test]
    fn parse_env_value_empty_string() -> Result<(), PackError> {
        match parse_env_value("") {
            EnvValue::Literal(v) => assert_eq!(v, ""),
            other => {
                return Err(PackError::Validation(format!(
                    "expected Literal, got {:?}",
                    other
                )))
            }
        }
        Ok(())
    }

    #[test]
    fn parse_env_value_env_prefix_only() -> Result<(), PackError> {
        match parse_env_value("env:") {
            EnvValue::Env(v) => assert_eq!(v, ""),
            other => {
                return Err(PackError::Validation(format!(
                    "expected Env, got {:?}",
                    other
                )))
            }
        }
        Ok(())
    }

    // ── parse_trigger ──────────────────────────────────────────────────

    #[test]
    fn parse_trigger_task_start() {
        assert!(matches!(
            parse_trigger("task_start").unwrap(),
            Trigger::TaskStart
        ));
    }

    #[test]
    fn parse_trigger_task_end() {
        assert!(matches!(
            parse_trigger("task_end").unwrap(),
            Trigger::TaskEnd
        ));
    }

    #[test]
    fn parse_trigger_scope_close() {
        assert!(matches!(
            parse_trigger("scope_close").unwrap(),
            Trigger::ScopeClose
        ));
    }

    #[test]
    fn parse_trigger_turn_end() {
        assert!(matches!(
            parse_trigger("turn_end").unwrap(),
            Trigger::TurnEnd
        ));
    }

    #[test]
    fn parse_trigger_manual() {
        assert!(matches!(parse_trigger("manual").unwrap(), Trigger::Manual));
    }

    #[test]
    fn parse_trigger_case_insensitive() {
        assert!(matches!(
            parse_trigger("TASK_START").unwrap(),
            Trigger::TaskStart
        ));
        assert!(matches!(parse_trigger("Manual").unwrap(), Trigger::Manual));
    }

    #[test]
    fn parse_trigger_schedule() -> Result<(), PackError> {
        match parse_trigger("schedule:0 * * * *").unwrap() {
            Trigger::Schedule(cron) => assert_eq!(cron, "0 * * * *"),
            other => {
                return Err(PackError::Validation(format!(
                    "expected Schedule, got {:?}",
                    other
                )))
            }
        }
        Ok(())
    }

    #[test]
    fn parse_trigger_invalid() {
        assert!(parse_trigger("bogus").is_err());
    }

    // ── is_valid_executable_path ───────────────────────────────────────

    #[test]
    fn valid_executable_path() {
        assert!(is_valid_executable_path("./tools/my_tool"));
        assert!(is_valid_executable_path("./tools/sub/deep/tool.sh"));
    }

    #[test]
    fn rejects_absolute_path() {
        assert!(!is_valid_executable_path("/usr/bin/bash"));
    }

    #[test]
    fn rejects_bare_command() {
        assert!(!is_valid_executable_path("curl"));
    }

    #[test]
    fn rejects_path_traversal() {
        assert!(!is_valid_executable_path("./tools/../../../bin/sh"));
    }

    #[test]
    fn rejects_shell_metacharacters() {
        assert!(!is_valid_executable_path("./tools/a; rm -rf /"));
        assert!(!is_valid_executable_path("./tools/a | cat"));
        assert!(!is_valid_executable_path("./tools/a && echo"));
        assert!(!is_valid_executable_path("./tools/a`whoami`"));
    }

    #[test]
    fn rejects_wrong_prefix() {
        assert!(!is_valid_executable_path("./bin/tool"));
        assert!(!is_valid_executable_path("tools/tool")); // missing ./
    }

    // ── PackError Display ──────────────────────────────────────────────

    #[test]
    fn pack_error_validation_display() {
        let err = PackError::Validation("bad config".into());
        let s = format!("{}", err);
        assert!(s.contains("bad config"));
    }

    #[test]
    fn pack_error_toml_display() {
        let err = PackError::Toml("parse error".into());
        let s = format!("{}", err);
        assert!(s.contains("parse error"));
    }

    // ── parse_manifest (schema.rs) ─────────────────────────────────────

    #[test]
    fn parse_manifest_minimal() {
        let toml = r#"
[meta]
project = "test-pack"
version = "1.0.0"
"#;
        let manifest = super::super::schema::parse_manifest(toml).unwrap();
        let meta = manifest.meta.as_ref().unwrap();
        assert_eq!(meta.project.as_deref(), Some("test-pack"));
        assert_eq!(meta.version.as_deref(), Some("1.0.0"));
    }

    #[test]
    fn parse_manifest_invalid_toml() {
        let result = super::super::schema::parse_manifest("not valid toml {{{}}}");
        assert!(result.is_err());
    }

    #[test]
    fn parse_manifest_with_defaults() {
        let toml = r#"
[meta]
project = "test"
version = "0.1.0"

[defaults]
context_format = "markdown"
token_budget = 16000
"#;
        let manifest = super::super::schema::parse_manifest(toml).unwrap();
        let defaults = manifest.defaults.as_ref().unwrap();
        assert_eq!(defaults.context_format.as_deref(), Some("markdown"));
        assert_eq!(defaults.token_budget, Some(16000));
    }

    #[test]
    fn parse_manifest_with_tools() {
        let toml = r#"
[meta]
project = "test"
version = "0.1.0"

[tools.bash.my_script]
description = "A test script"
"#;
        let manifest = super::super::schema::parse_manifest(toml).unwrap();
        assert!(manifest.tools.bash.contains_key("my_script"));
    }

    // ── profile_key ────────────────────────────────────────────────────

    #[test]
    fn profile_key_lowercases() {
        let key = profile_key("FULL", "HNSW", "ADA", "JSON");
        assert_eq!(key, "full|hnsw|ada|json");
    }

    #[test]
    fn profile_key_deterministic() {
        let a = profile_key("a", "b", "c", "d");
        let b = profile_key("a", "b", "c", "d");
        assert_eq!(a, b);
    }
}