mecha10_behavior_runtime/config/

validator.rs

//! Validation for behavior tree configurations
//!
//! Ensures that behavior tree JSON is well-formed, matches the `schemars`-derived JSON Schema

use super::types::BehaviorConfig;
use crate::registry::NodeRegistry;
use anyhow::{anyhow, Result};
use mecha10_core::node::Capability;
use serde_json::Value;
use std::collections::HashSet;
use std::sync::LazyLock;

static BEHAVIOR_CONFIG_SCHEMA: LazyLock<Value> = LazyLock::new(|| {
    let root_schema = schemars::schema_for!(BehaviorConfig);
    serde_json::to_value(root_schema).expect("schemars schema always serializes to JSON")
});

static BEHAVIOR_CONFIG_VALIDATOR: LazyLock<jsonschema::Validator> = LazyLock::new(|| {
    jsonschema::validator_for(&BEHAVIOR_CONFIG_SCHEMA).expect("BehaviorConfig schema is a valid JSON Schema")
});

#[derive(Debug, Clone)]
pub struct ValidationResult {
    pub valid: bool,
    pub errors: Vec<String>,
    pub warnings: Vec<String>,
}

impl ValidationResult {
    /// Create a successful validation result
    pub fn success() -> Self {
        Self {
            valid: true,
            errors: Vec::new(),
            warnings: Vec::new(),
        }
    }

    /// Create a failed validation result with errors
    pub fn with_errors(errors: Vec<String>) -> Self {
        Self {
            valid: false,
            errors,
            warnings: Vec::new(),
        }
    }

    /// Add a warning to the result
    pub fn add_warning(&mut self, warning: String) {
        self.warnings.push(warning);
    }

    /// Add an error to the result
    pub fn add_error(&mut self, error: String) {
        self.errors.push(error);
        self.valid = false;
    }
}

/// Validate a behavior composition JSON value against the `schemars`-derived
/// [`BehaviorConfig`] JSON Schema -- structural validation only, no [`NodeRegistry`] required.
/// Returns an error describing every schema violation found.
pub fn validate_behavior_composition_json(config: &Value) -> Result<()> {
    if !BEHAVIOR_CONFIG_VALIDATOR.is_valid(config) {
        let messages: Vec<String> = BEHAVIOR_CONFIG_VALIDATOR
            .iter_errors(config)
            .map(|e| format!("  - {}: {} ({})", e.instance_path(), e, e.instance()))
            .collect();
        return Err(anyhow!(
            "Behavior config schema validation failed:\n{}",
            messages.join("\n")
        ));
    }

    Ok(())
}

/// Validate a behavior tree configuration: checks it against the real `BehaviorConfig` JSON
/// Schema (see [`validate_behavior_composition_json`]), that every leaf node's `node` type
/// exists in `registry`, and that every capability it declares via `requires_capabilities` is
/// present in `available_capabilities` -- rules a JSON Schema can't express on its own since
/// they cross-reference the live node registry / the project's other nodes.
///
/// `available_capabilities` is expected to be `ProjectConfig::capabilities` (the union of every
/// enabled node's declared capabilities) for the project this behavior is being validated
/// against.
pub fn validate_behavior_config(
    config: &Value,
    registry: &NodeRegistry,
    available_capabilities: &HashSet<Capability>,
) -> Result<ValidationResult> {
    let mut result = ValidationResult::success();

    if let Err(schema_err) = validate_behavior_composition_json(config) {
        result.add_error(schema_err.to_string());
    }

    if let Some(root) = config.get("root") {
        validate_node_types(root, registry, &mut result, "root");
    }

    validate_required_capabilities(config, available_capabilities, &mut result);

    if config.get("$schema").is_none() {
        result
            .add_warning("No '$schema' field found. Consider adding schema reference for IDE validation.".to_string());
    }

    Ok(result)
}

/// Check that every capability this behavior declares via `requires_capabilities` is present in
/// `available_capabilities` -- a rule the JSON Schema alone can't express since it cross-
/// references another config (`ProjectConfig::capabilities`). An unsatisfied
/// requirement is a hard validation error naming the missing capability, not a warning.
fn validate_required_capabilities(
    config: &Value,
    available_capabilities: &HashSet<Capability>,
    result: &mut ValidationResult,
) {
    for value in missing_required_capability_values(config, available_capabilities) {
        result.add_error(format!(
            "Behavior requires capability '{}', which is not provided by any enabled node in this project. \
             Add a node that declares this capability, or remove it from 'requires_capabilities'.",
            value.as_str().unwrap_or("<unknown>")
        ));
    }
}

/// Returns `true` if every capability `config` declares via `requires_capabilities` is present
/// in `available_capabilities` -- the same subset check [`validate_required_capabilities`] uses
/// to produce validation errors, exposed for runtime filtering (e.g. excluding a behavior from
/// `/behavior/available` when the robot doesn't provide a capability it needs).
pub fn behavior_capabilities_satisfied(config: &Value, available_capabilities: &HashSet<Capability>) -> bool {
    missing_required_capability_values(config, available_capabilities).is_empty()
}

/// Returns every raw `requires_capabilities` entry in `config` that is not present in
/// `available_capabilities`. An unparseable/unknown capability value is already reported by
/// schema validation elsewhere, so it's treated as satisfied here rather than double-reported.
fn missing_required_capability_values(config: &Value, available_capabilities: &HashSet<Capability>) -> Vec<Value> {
    let Some(required) = config.get("requires_capabilities").and_then(|v| v.as_array()) else {
        return Vec::new();
    };

    required
        .iter()
        .filter(|value| {
            serde_json::from_value::<Capability>((*value).clone())
                .map(|capability| !available_capabilities.contains(&capability))
                .unwrap_or(false)
        })
        .cloned()
        .collect()
}

/// Walk the composition tree checking that every leaf node's `node` identifier is
/// registered in `registry` -- the one rule JSON Schema can't express. Skips anything schema
/// validation already reports (non-object nodes, missing/invalid `type`/`children`).
fn validate_node_types(node: &Value, registry: &NodeRegistry, result: &mut ValidationResult, path: &str) {
    let Some(obj) = node.as_object() else {
        return;
    };

    let Some(node_type) = obj.get("type").and_then(|v| v.as_str()) else {
        return;
    };

    match node_type {
        "node" => {
            if let Some(node_name) = obj.get("node").and_then(|v| v.as_str()) {
                if !registry.has_node(node_name) {
                    result.add_error(format!(
                        "Node at '{}' has unknown type '{}'. Register this node type or check for typos.",
                        path, node_name
                    ));
                }
            }
        }
        "sequence" | "selector" | "parallel" | "watch" => {
            if let Some(children) = obj.get("children").and_then(|v| v.as_array()) {
                if children.is_empty() {
                    result.add_warning(format!(
                        "Composition node at '{}' has no children (will immediately return success/failure)",
                        path
                    ));
                }

                for (i, child) in children.iter().enumerate() {
                    let child_path = format!("{}.children[{}]", path, i);
                    validate_node_types(child, registry, result, &child_path);
                }
            }
        }
        "inverter" | "force_success" | "force_failure" | "repeat" | "retry" | "timeout" | "condition" | "cooldown" => {
            if let Some(child) = obj.get("child") {
                let child_path = format!("{}.child", path);
                validate_node_types(child, registry, result, &child_path);
            }
        }
        "weighted_select" => {
            if let Some(children) = obj.get("children").and_then(|v| v.as_array()) {
                if children.is_empty() {
                    result.add_warning(format!(
                        "Composition node at '{}' has no children (will immediately return success/failure)",
                        path
                    ));
                }

                for (i, weighted_child) in children.iter().enumerate() {
                    if let Some(node) = weighted_child.get("node") {
                        let child_path = format!("{}.children[{}].node", path, i);
                        validate_node_types(node, registry, result, &child_path);
                    }
                }
            }
        }
        "subsumption" => {
            if let Some(layers) = obj.get("layers").and_then(|v| v.as_array()) {
                if layers.is_empty() {
                    result.add_warning(format!(
                        "Subsumption node at '{}' has no layers (will immediately return failure)",
                        path
                    ));
                }

                for (i, layer) in layers.iter().enumerate() {
                    if let Some(node) = layer.get("node") {
                        let child_path = format!("{}.layers[{}].node", path, i);
                        validate_node_types(node, registry, result, &child_path);
                    }
                }
            }
        }
        "include" => {
            // No filesystem access here - this function validates a bare JSON `Value`, with no
            // base directory to resolve `path` against (that context only exists in
            // `BehaviorLoader::load_from_file`). The fragment file's own node types are still
            // checked when the tree is actually loaded (an unknown node type inside it fails
            // loudly there), just not by this static validator.
        }
        _ => {}
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::NodeRegistry;
    use serde_json::json;

    #[test]
    fn test_validate_missing_name() {
        let registry = NodeRegistry::new();
        let config = json!({
            "root": {
                "type": "sequence",
                "children": []
            }
        });

        let result = validate_behavior_config(&config, &registry, &HashSet::new()).unwrap();
        assert!(!result.valid);
        assert!(result.errors.iter().any(|e| e.contains("name")));
    }

    #[test]
    fn test_validate_missing_root() {
        let registry = NodeRegistry::new();
        let config = json!({
            "name": "test"
        });

        let result = validate_behavior_config(&config, &registry, &HashSet::new()).unwrap();
        assert!(!result.valid);
        assert!(result.errors.iter().any(|e| e.contains("root")));
    }

    #[test]
    fn test_validate_valid_config() {
        let registry = NodeRegistry::new();
        let config = json!({
            "name": "test",
            "root": {
                "type": "sequence",
                "children": []
            }
        });

        let result = validate_behavior_config(&config, &registry, &HashSet::new()).unwrap();
        assert!(result.valid, "{:?}", result.errors);
    }

    /// A behavior with no `requires_capabilities` at all (the common case) must be unaffected
    /// by the capability check, regardless of what the project does or doesn't provide.
    #[test]
    fn test_validate_behavior_with_no_requires_capabilities_is_unaffected() {
        let registry = NodeRegistry::new();
        let config = json!({
            "name": "test",
            "root": {
                "type": "sequence",
                "children": []
            }
        });

        let result = validate_behavior_config(&config, &registry, &HashSet::new()).unwrap();
        assert!(result.valid, "{:?}", result.errors);
    }

    #[test]
    fn test_validate_requires_capabilities_passes_when_satisfied() {
        let registry = NodeRegistry::new();
        let config = json!({
            "name": "test",
            "root": {
                "type": "sequence",
                "children": []
            },
            "requires_capabilities": ["locomotion"]
        });

        let available = HashSet::from([Capability::Locomotion]);
        let result = validate_behavior_config(&config, &registry, &available).unwrap();
        assert!(result.valid, "{:?}", result.errors);
    }

    #[test]
    fn test_validate_requires_capabilities_fails_when_unsatisfied() {
        let registry = NodeRegistry::new();
        let config = json!({
            "name": "test",
            "root": {
                "type": "sequence",
                "children": []
            },
            "requires_capabilities": ["flight"]
        });

        // The project has no node providing "flight" -- e.g. just a locomotion node.
        let available = HashSet::from([Capability::Locomotion]);
        let result = validate_behavior_config(&config, &registry, &available).unwrap();
        assert!(!result.valid);
        assert!(
            result.errors.iter().any(|e| e.contains("flight")),
            "expected an error naming the missing 'flight' capability, got: {:?}",
            result.errors
        );
    }

    #[test]
    fn test_validate_requires_capabilities_fails_naming_only_the_missing_one() {
        let registry = NodeRegistry::new();
        let config = json!({
            "name": "test",
            "root": {
                "type": "sequence",
                "children": []
            },
            "requires_capabilities": ["locomotion", "flight"]
        });

        let available = HashSet::from([Capability::Locomotion]);
        let result = validate_behavior_config(&config, &registry, &available).unwrap();
        assert!(!result.valid);
        assert_eq!(result.errors.len(), 1, "{:?}", result.errors);
        assert!(result.errors[0].contains("flight"));
    }

    #[test]
    fn test_behavior_capabilities_satisfied_true_when_no_requires_capabilities() {
        let config = json!({
            "name": "test",
            "root": { "type": "sequence", "children": [] }
        });

        assert!(behavior_capabilities_satisfied(&config, &HashSet::new()));
    }

    #[test]
    fn test_behavior_capabilities_satisfied_true_when_subset_of_available() {
        let config = json!({
            "name": "test",
            "root": { "type": "sequence", "children": [] },
            "requires_capabilities": ["locomotion"]
        });

        let available = HashSet::from([Capability::Locomotion, Capability::Vision]);
        assert!(behavior_capabilities_satisfied(&config, &available));
    }

    #[test]
    fn test_behavior_capabilities_satisfied_false_when_missing_one() {
        let config = json!({
            "name": "test",
            "root": { "type": "sequence", "children": [] },
            "requires_capabilities": ["locomotion", "flight"]
        });

        let available = HashSet::from([Capability::Locomotion]);
        assert!(!behavior_capabilities_satisfied(&config, &available));
    }

    #[test]
    fn test_validate_unknown_node_type() {
        let registry = NodeRegistry::new();
        let config = json!({
            "name": "test",
            "root": {
                "type": "node",
                "node": "unknown_type"
            }
        });

        let result = validate_behavior_config(&config, &registry, &HashSet::new()).unwrap();
        assert!(!result.valid);
        assert!(result.errors.iter().any(|e| e.contains("unknown_type")));
    }

    /// A leaf node shaped as `{"type": "<node_type>"}` never matches the real
    /// `BehaviorConfig`/`CompositionConfig` struct (its `Node` variant tags as `"type": "node"`
    /// with the actual identifier in a separate `node` field) and must be rejected.
    #[test]
    fn test_validate_rejects_legacy_leaf_shape_that_never_matched_the_real_struct() {
        let registry = NodeRegistry::new();
        let config = json!({
            "name": "test",
            "root": {
                "type": "wander",
                "config": {}
            }
        });

        let result = validate_behavior_config(&config, &registry, &HashSet::new()).unwrap();
        assert!(!result.valid);
    }

    #[test]
    fn test_validate_valid_leaf_node_config() {
        let mut registry = NodeRegistry::new();
        crate::register_builtin_actions(&mut registry);

        let config = json!({
            "name": "test",
            "root": {
                "type": "node",
                "node": "wander",
                "config": { "speed": 0.5 }
            }
        });

        let result = validate_behavior_config(&config, &registry, &HashSet::new()).unwrap();
        assert!(result.valid, "{:?}", result.errors);
    }

    #[test]
    fn test_validate_empty_children_warns() {
        let registry = NodeRegistry::new();
        let config = json!({
            "name": "test",
            "root": {
                "type": "sequence",
                "children": []
            }
        });

        let result = validate_behavior_config(&config, &registry, &HashSet::new()).unwrap();
        assert!(result.valid);
        assert!(result.warnings.iter().any(|w| w.contains("no children")));
    }

    #[test]
    fn test_validate_watch_recurses_into_children_like_parallel() {
        let registry = NodeRegistry::new();
        let config = json!({
            "name": "test",
            "root": {
                "type": "watch",
                "policy": "require_one",
                "children": [
                    { "type": "node", "node": "unknown_type" }
                ]
            }
        });

        let result = validate_behavior_config(&config, &registry, &HashSet::new()).unwrap();
        assert!(!result.valid);
        assert!(result.errors.iter().any(|e| e.contains("unknown_type")));
    }

    #[test]
    fn test_validate_weighted_select_recurses_into_children() {
        let registry = NodeRegistry::new();
        let config = json!({
            "name": "test",
            "root": {
                "type": "weighted_select",
                "children": [
                    { "weight": 1.0, "node": { "type": "node", "node": "unknown_type" } }
                ]
            }
        });

        let result = validate_behavior_config(&config, &registry, &HashSet::new()).unwrap();
        assert!(!result.valid);
        assert!(result.errors.iter().any(|e| e.contains("unknown_type")));
    }

    #[test]
    fn test_validate_weighted_select_empty_children_warns() {
        let registry = NodeRegistry::new();
        let config = json!({
            "name": "test",
            "root": {
                "type": "weighted_select",
                "children": []
            }
        });

        let result = validate_behavior_config(&config, &registry, &HashSet::new()).unwrap();
        assert!(result.valid);
        assert!(result.warnings.iter().any(|w| w.contains("no children")));
    }

    #[test]
    fn test_validate_cooldown_recurses_into_child() {
        let registry = NodeRegistry::new();
        let config = json!({
            "name": "test",
            "root": {
                "type": "cooldown",
                "cooldown_secs": 5.0,
                "child": { "type": "node", "node": "unknown_type" }
            }
        });

        let result = validate_behavior_config(&config, &registry, &HashSet::new()).unwrap();
        assert!(!result.valid);
        assert!(result.errors.iter().any(|e| e.contains("unknown_type")));
    }

    #[test]
    fn test_validate_subsumption_recurses_into_layer_nodes() {
        let registry = NodeRegistry::new();
        let config = json!({
            "name": "test",
            "root": {
                "type": "subsumption",
                "layers": [
                    { "priority": 10, "node": { "type": "node", "node": "unknown_type" } },
                    { "priority": 0, "node": { "type": "sequence", "children": [] } }
                ]
            }
        });

        let result = validate_behavior_config(&config, &registry, &HashSet::new()).unwrap();
        assert!(!result.valid);
        assert!(result.errors.iter().any(|e| e.contains("unknown_type")));
    }

    #[test]
    fn test_validate_decorator_recurses_into_child() {
        let registry = NodeRegistry::new();
        for decorator_type in [
            "inverter",
            "force_success",
            "force_failure",
            "repeat",
            "retry",
            "timeout",
            "condition",
            "cooldown",
        ] {
            let config = json!({
                "name": "test",
                "root": {
                    "type": decorator_type,
                    "max_attempts": 1,
                    "timeout_secs": 1.0,
                    "cooldown_secs": 1.0,
                    "condition": { "controller_mode_is": "locomotion" },
                    "child": { "type": "node", "node": "unknown_type" }
                }
            });

            let result = validate_behavior_config(&config, &registry, &HashSet::new()).unwrap();
            assert!(
                result.errors.iter().any(|e| e.contains("unknown_type")),
                "decorator '{}' should recurse into its child: {:?}",
                decorator_type,
                result.errors
            );
        }
    }

    #[test]
    fn test_validate_condition_recurses_into_child() {
        let registry = NodeRegistry::new();
        let config = json!({
            "name": "test",
            "root": {
                "type": "condition",
                "condition": { "controller_mode_is": "locomotion" },
                "child": { "type": "node", "node": "unknown_type" }
            }
        });

        let result = validate_behavior_config(&config, &registry, &HashSet::new()).unwrap();
        assert!(!result.valid);
        assert!(result.errors.iter().any(|e| e.contains("unknown_type")));
    }

    #[test]
    fn test_validate_include_is_accepted_by_schema_without_recursing() {
        let registry = NodeRegistry::new();
        let config = json!({
            "name": "test",
            "root": {
                "type": "include",
                "path": "../_shared/fragment.json"
            }
        });

        let result = validate_behavior_config(&config, &registry, &HashSet::new()).unwrap();
        assert!(result.valid, "{:?}", result.errors);
    }

    #[test]
    fn test_validate_subsumption_empty_layers_warns() {
        let registry = NodeRegistry::new();
        let config = json!({
            "name": "test",
            "root": {
                "type": "subsumption",
                "layers": []
            }
        });

        let result = validate_behavior_config(&config, &registry, &HashSet::new()).unwrap();
        assert!(result.valid);
        assert!(result.warnings.iter().any(|w| w.contains("no layers")));
    }

    #[test]
    fn validate_behavior_composition_json_rejects_non_object() {
        assert!(validate_behavior_composition_json(&json!("not an object")).is_err());
    }

    #[test]
    fn validate_behavior_composition_json_rejects_wrong_children_type() {
        let config = json!({
            "name": "test",
            "root": {
                "type": "sequence",
                "children": "not an array"
            }
        });

        assert!(validate_behavior_composition_json(&config).is_err());
    }

    #[test]
    fn validate_behavior_composition_json_accepts_the_real_repo_seed_templates() {
        let templates_dir = std::path::Path::new(env!("CARGO_MANIFEST_DIR"))
            .join("tests/fixtures/seed_behaviors")
            .canonicalize()
            .unwrap();

        let mut checked = 0;
        for entry in std::fs::read_dir(&templates_dir).unwrap() {
            let config_path = entry.unwrap().path().join("config.json");
            if !config_path.is_file() {
                continue;
            }
            let content = std::fs::read_to_string(&config_path).unwrap();
            let value: Value = serde_json::from_str(&content).unwrap();
            assert!(
                validate_behavior_composition_json(&value).is_ok(),
                "{} should validate against the real BehaviorConfig schema",
                config_path.display()
            );
            checked += 1;
        }
        assert!(
            checked > 0,
            "expected at least one seed behavior config template to check"
        );
    }

    /// LAB-4831: `find_target` is the one true seed behavior for the rl node's find_target
    /// task - it must exist, must validate against the real `NodeRegistry` (not just the bare
    /// JSON Schema), must still wire up the live target-class override (`set_capability_target`
    /// configured for the `rl` control topic), and there must be no separate
    /// `rl`/`find_target_dynamic`/`find_target_sentry` seed directory left behind for this
    /// concept to accidentally fork back into multiple configs.
    ///
    /// Since the `move`/`wander` action nodes migrated to dispatching on the project's
    /// `ControllerMode` (Locomotion vs Joints) rather than always publishing a Twist, the old
    /// joints-only `find_target_sentry` seed behavior was folded into this one too: `find_target`
    /// now uses the same subsumption tree `find_target_sentry` used to (an `instance_track`
    /// interrupt layer over the generic `capability_task`/`set_capability_target` leaf nodes,
    /// configured for the `rl` capability) and, critically, declares no `requires_capabilities`
    /// at all - it works unmodified on every platform.
    #[test]
    fn find_target_seed_behavior_is_the_sole_rl_task_config_and_keeps_the_live_target_override() {
        let seed_dir = std::path::Path::new(env!("CARGO_MANIFEST_DIR"))
            .join("tests/fixtures/seed_behaviors")
            .canonicalize()
            .unwrap();

        assert!(
            !seed_dir.join("rl").exists(),
            "the old 'rl' seed behavior directory should have been folded into 'find_target'"
        );
        assert!(
            !seed_dir.join("find_target_dynamic").exists(),
            "find_target_dynamic should be folded into a single 'find_target' behavior, not kept alongside it"
        );
        assert!(
            !seed_dir.join("find_target_sentry").exists(),
            "find_target_sentry should be folded into a single, platform-agnostic 'find_target' \
             behavior, not kept alongside it"
        );

        let config_path = seed_dir.join("find_target/config.json");
        let content = std::fs::read_to_string(&config_path)
            .unwrap_or_else(|e| panic!("{} should exist: {}", config_path.display(), e));
        let value: Value = serde_json::from_str(&content).unwrap();

        assert_eq!(value["name"], "find_target");
        assert!(
            value.get("requires_capabilities").is_none(),
            "find_target must not declare requires_capabilities at all - it dispatches on \
             ControllerMode at the node level and must run on every platform, not just none/empty"
        );

        let mut registry = crate::NodeRegistry::new();
        crate::register_builtin_actions(&mut registry);
        let result = validate_behavior_config(&value, &registry, &HashSet::new()).unwrap();
        assert!(result.valid, "{:?}", result.errors);

        assert_eq!(value["root"]["type"], "subsumption", "{:?}", value["root"]);
        let layers = value["root"]["layers"].as_array().unwrap();
        let main_layer = layers
            .iter()
            .find(|layer| layer["name"] == "find_target-main")
            .unwrap_or_else(|| panic!("expected a 'find_target-main' layer, got: {:?}", layers));
        let main_node = &main_layer["node"];

        let serialized = content;
        assert!(
            serialized.contains("\"capability_task\""),
            "find_target should still hand control to the rl node via the generic capability_task node"
        );
        assert!(
            serialized.contains("\"set_capability_target\""),
            "find_target should still relay live dashboard target-class overrides via \
             set_capability_target, regardless of whether the rl node's own config.json selects \
             onnx or act_torchscript"
        );
        let main_children: Vec<&str> = main_node["children"]
            .as_array()
            .unwrap_or_else(|| panic!("expected find_target-main's node to have children: {:?}", main_node))
            .iter()
            .map(|child| child["node"].as_str().unwrap())
            .collect();
        assert!(
            main_children.contains(&"capability_task") && main_children.contains(&"set_capability_target"),
            "capability_task/set_capability_target should be nested under the lower-priority \
             'find_target-main' layer, got children: {:?}",
            main_children
        );
    }
}