KeiSeiKit-1.0/_primitives/_rust/kei-agent-runtime/src/role.rs

//! Role expression resolver — Layer E.
//!
//! Parses `_roles/<name>.toml` and resolves `extends` chains with `relaxes`
//! subtraction, emitting a flat `ResolvedRole` for downstream consumers
//! (`compose`, `prepare`, `verify`, `dna`).
//!
//! Semantics:
//!   - `extends` — optional parent role slug; loaded recursively.
//!   - `required` (local) — merged on top of parent's resolved required.
//!   - `relaxes` — slugs in parent's resolved required to DROP. Warn on stderr
//!     if a relaxed cap wasn't present in the inherited set.
//!   - Cycle detection — visited set passed down the recursion; an error with
//!     a clear path is returned when a cycle is found.
//!
//! Constructor Pattern: one cube = one responsibility (role expression only).
//! No I/O beyond `std::fs::read_to_string`. Dispatched from `compose::load_role`
//! and `verify::load_role_capabilities` so both share the same semantics.

use anyhow::{anyhow, Context, Result};
use serde::Deserialize;
use std::collections::HashSet;
use std::path::Path;

/// Flattened role ready for downstream composition.
#[derive(Debug, Clone, Default)]
pub struct ResolvedRole {
    /// Ordered capability names after `extends` merge + `relaxes` subtraction.
    pub required: Vec<String>,
}

/// Deserialized role file (raw shape, pre-resolution).
#[derive(Debug, Default, Deserialize)]
pub struct RoleFileRaw {
    #[serde(default)]
    pub capabilities: RoleCapsRaw,
}

#[derive(Debug, Default, Deserialize)]
pub struct RoleCapsRaw {
    #[serde(default)]
    pub extends: Option<String>,
    #[serde(default)]
    pub required: Vec<String>,
    #[serde(default)]
    pub relaxes: Vec<String>,
}

/// Resolve a role by slug; read role file, walk `extends`, apply `relaxes`.
pub fn resolve_role(kit_root: &Path, role: &str) -> Result<ResolvedRole> {
    let mut visited: HashSet<String> = HashSet::new();
    resolve_inner(kit_root, role, &mut visited)
}

fn resolve_inner(
    kit_root: &Path,
    role: &str,
    visited: &mut HashSet<String>,
) -> Result<ResolvedRole> {
    if !visited.insert(role.to_string()) {
        return Err(anyhow!(
            "cycle detected in role `extends` chain at `{role}` (path: {:?})",
            visited
        ));
    }
    let raw = read_role_file(kit_root, role)?;
    let mut merged = match raw.capabilities.extends.as_deref() {
        Some(parent) => resolve_inner(kit_root, parent, visited)?.required,
        None => Vec::new(),
    };
    for cap in &raw.capabilities.required {
        if !merged.iter().any(|c| c == cap) {
            merged.push(cap.clone());
        }
    }
    for dropped in &raw.capabilities.relaxes {
        let before = merged.len();
        merged.retain(|c| c != dropped);
        if merged.len() == before {
            eprintln!(
                "[kei-agent-runtime] role `{role}` relaxes `{dropped}` \
                 but it was not in the inherited capability set — no-op"
            );
        }
    }
    visited.remove(role);
    Ok(ResolvedRole { required: merged })
}

fn read_role_file(kit_root: &Path, role: &str) -> Result<RoleFileRaw> {
    let path = kit_root.join("_roles").join(format!("{role}.toml"));
    let text = std::fs::read_to_string(&path)
        .with_context(|| format!("read role file {}", path.display()))?;
    toml::from_str::<RoleFileRaw>(&text)
        .with_context(|| format!("parse role TOML {}", path.display()))
}