featherbit/graph/

validation.rs

//! Structural validation of policy node graphs, run before compilation
//! (e.g. at config load and on Admin API writes) so malformed policies are
//! rejected with actionable messages instead of failing at request time.

use std::collections::HashSet;

use super::expand::{split_endpoint, BOUNDARY_TYPES};
use crate::config::{PolicyConfig, SupernodeConfig};

/// Output-boundary ids that would collide with an instance's fixed port
/// names (spec §1). `output` is the one special id: it maps to `success`.
pub(crate) const RESERVED_OUTPUT_IDS: [&str; 5] = ["input", "error", "in", "out", "success"];

/// Error-boundary ids that would collide with an instance's fixed port
/// names (spec §1). `error` is the one special id: it is both the port
/// name and the black-box default exit.
pub(crate) const RESERVED_ERROR_IDS: [&str; 5] = ["input", "output", "in", "out", "success"];

/// Validates a policy's node graph structure, collecting all violations.
///
/// Enforced rules:
/// - no two nodes share an id;
/// - the policy has a `listener` node (entry) and a `client` node (exit);
/// - every edge endpoint references an existing node;
/// - no orphan nodes (a node with neither incoming nor outgoing edges;
///   being named as the policy-level `error_handler` counts as connected);
/// - `error_handler`, if set, references an existing node that is not a
///   `type: supernode` instance (expansion removes instance nodes, so a
///   catch-all pointed at one would dangle at request time).
///
/// Returns `Ok(())` when valid, otherwise `Err` with one message per
/// violation (validation does not stop at the first error).
pub fn validate_policy(policy: &PolicyConfig) -> Result<(), Vec<String>> {
    let mut errors = Vec::new();

    let node_ids: HashSet<&str> = policy.nodes.iter().map(|n| n.id.as_str()).collect();

    // Duplicate node ids collapse silently in compile — with supernodes they
    // would silently drop an expansion — so reject each duplicate up front.
    let mut seen_ids: HashSet<&str> = HashSet::new();
    for node in &policy.nodes {
        if !seen_ids.insert(node.id.as_str()) {
            errors.push(format!("Duplicate node id '{}'", node.id));
        }
    }

    // Must have a listener node
    let has_listener = policy.nodes.iter().any(|n| n.node_type == "listener");
    if !has_listener {
        errors.push("Policy must have a 'listener' node".to_string());
    }

    // Must have a client node
    let has_client = policy.nodes.iter().any(|n| n.node_type == "client");
    if !has_client {
        errors.push("Policy must have a 'client' node".to_string());
    }

    // Node-id and reserved-type hygiene: `/` is the supernode namespace
    // separator, and boundary pseudo-types only exist inside definitions.
    for node in &policy.nodes {
        if node.id.contains('/') {
            errors.push(format!(
                "Node id '{}' must not contain '/' (reserved for supernode expansion)",
                node.id
            ));
        }
        if BOUNDARY_TYPES.contains(&node.node_type.as_str()) {
            errors.push(format!(
                "Node '{}' has type '{}', which is reserved for supernode definitions",
                node.id, node.node_type
            ));
        }
    }

    // Validate edges reference existing nodes
    for edge in &policy.edges {
        let from_node = edge.from.split('.').next().unwrap_or("");
        let to_node = edge.to.split('.').next().unwrap_or("");

        if !node_ids.contains(from_node) {
            errors.push(format!(
                "Edge references unknown source node: '{}'",
                from_node
            ));
        }
        if !node_ids.contains(to_node) {
            errors.push(format!(
                "Edge references unknown target node: '{}'",
                to_node
            ));
        }
    }

    // Fan-in is unrestricted: any number of edges may converge on the same
    // input port. The engine indexes edges by source port only (fan-out and
    // cycles are compile-time errors in engine.rs).

    // Check for orphan nodes (no incoming or outgoing edges)
    let mut connected_nodes: HashSet<&str> = HashSet::new();
    for edge in &policy.edges {
        let from_node = edge.from.split('.').next().unwrap_or("");
        let to_node = edge.to.split('.').next().unwrap_or("");
        connected_nodes.insert(from_node);
        connected_nodes.insert(to_node);
    }

    // Also include the catch-all handler if specified
    if let Some(ref handler) = policy.error_handler {
        connected_nodes.insert(handler.as_str());
    }

    for node in &policy.nodes {
        if !connected_nodes.contains(node.id.as_str()) {
            errors.push(format!("Orphan node '{}' has no connections", node.id));
        }
    }

    // Validate error_handler references an existing node
    if let Some(ref handler) = policy.error_handler {
        if !node_ids.contains(handler.as_str()) {
            errors.push(format!(
                "Policy error_handler references unknown node: '{}'",
                handler
            ));
        } else if let Some(node) = policy.nodes.iter().find(|n| n.id == *handler) {
            if node.node_type == "supernode" {
                errors.push(format!(
                    "Policy error_handler cannot reference supernode instance '{}' — point it at a concrete node",
                    handler
                ));
            }
        }
    }

    if errors.is_empty() {
        Ok(())
    } else {
        Err(errors)
    }
}

/// Validates a supernode definition's structure, collecting all violations.
///
/// Enforced rules (spec §3):
/// - exactly one boundary node of type `input`, id `input`; one or more
///   `output` boundaries (id = port name, `output` = the `success` port);
///   one or more `error` boundaries (id = error-kind port name, `error` =
///   the default the black-box rule targets);
/// - output/error ids must not be in RESERVED_OUTPUT_IDS/RESERVED_ERROR_IDS
///   (collide with fixed instance port names like `success`, `input`, etc.);
/// - no two nodes share an id (duplicate ids would create ambiguous output ports);
/// - inner nodes must not be `listener`/`client`/`supernode`, must not use
///   reserved ids, and must not contain `/`;
/// - exactly one edge leaves `input`; no edges into `input` or out of
///   `output`/`error` boundaries;
/// - every edge endpoint references an existing node;
/// - no orphan inner nodes (unconnected `output`/`error` boundaries are
///   fine — not every subgraph uses both exits);
/// - every inner edge leaves a port its source node's type actually declares
///   (`out` normalizes to `success`; boundary pseudo-nodes are exempt — they
///   have no plugin type and therefore no `PortSpec`);
/// - every `success`/outcome port of every inner node is wired **inside** the
///   definition, to another inner node or to a boundary. Definitions are
///   compiled as part of each policy that instantiates them, so an unwired
///   outcome port would otherwise surface as a confusing compile error on an
///   unrelated policy rather than at save time on the definition itself.
///   `error` ports stay exempt: the black-box rule in
///   [`expand_policy`](crate::graph::expand_policy) wires every unhandled
///   inner error port to the instance's error exit.
pub fn validate_supernode(sn: &SupernodeConfig) -> Result<(), Vec<String>> {
    let mut errors = Vec::new();

    // Duplicate ids: two output boundaries sharing an id would be one
    // ambiguous instance port; inner-node duplicates collapse in compile.
    let mut seen_ids: HashSet<&str> = HashSet::new();
    for n in &sn.nodes {
        if !seen_ids.insert(n.id.as_str()) {
            errors.push(format!(
                "Supernode '{}': duplicate node id '{}'",
                sn.name, n.id
            ));
        }
    }

    // input: exactly one, id == type (unchanged rule).
    {
        let ty = "input";
        let matching: Vec<&crate::config::NodeConfig> =
            sn.nodes.iter().filter(|n| n.node_type == ty).collect();
        match matching.as_slice() {
            [one] if one.id == ty => {}
            [one] => errors.push(format!(
                "Supernode '{}': boundary node of type '{}' must have id '{}' (got '{}')",
                sn.name, ty, ty, one.id
            )),
            [] => errors.push(format!(
                "Supernode '{}' must declare an '{}' boundary node",
                sn.name, ty
            )),
            _ => errors.push(format!(
                "Supernode '{}' declares more than one '{}' node",
                sn.name, ty
            )),
        }
    }

    // error: one or more; each id is an error-kind instance port name (`error`
    // is the default the black-box rule targets), so reserved ids that collide
    // with fixed port names are rejected.
    let error_nodes: Vec<&crate::config::NodeConfig> =
        sn.nodes.iter().filter(|n| n.node_type == "error").collect();
    if error_nodes.is_empty() {
        errors.push(format!(
            "Supernode '{}' must declare at least one 'error' boundary node",
            sn.name
        ));
    }
    for e in &error_nodes {
        if RESERVED_ERROR_IDS.contains(&e.id.as_str()) {
            errors.push(format!(
                "Supernode '{}': error boundary id '{}' is reserved — it would \
                 collide with a fixed instance port name",
                sn.name, e.id
            ));
        }
    }

    // output: one or more; each id is an instance port name (`output` -> the
    // `success` port), so reserved ids that collide with fixed port names are
    // rejected.
    let output_nodes: Vec<&crate::config::NodeConfig> = sn
        .nodes
        .iter()
        .filter(|n| n.node_type == "output")
        .collect();
    if output_nodes.is_empty() {
        errors.push(format!(
            "Supernode '{}' must declare at least one 'output' boundary node",
            sn.name
        ));
    }
    for o in &output_nodes {
        if RESERVED_OUTPUT_IDS.contains(&o.id.as_str()) {
            errors.push(format!(
                "Supernode '{}': output boundary id '{}' is reserved — it would \
                 collide with a fixed instance port name",
                sn.name, o.id
            ));
        }
    }

    for n in &sn.nodes {
        let is_boundary = BOUNDARY_TYPES.contains(&n.node_type.as_str());
        if n.id.contains('/') {
            errors.push(format!(
                "Supernode '{}': node id '{}' must not contain '/'",
                sn.name, n.id
            ));
        }
        if !is_boundary {
            if BOUNDARY_TYPES.contains(&n.id.as_str()) {
                errors.push(format!(
                    "Supernode '{}': node id '{}' is reserved for boundary nodes",
                    sn.name, n.id
                ));
            }
            if ["listener", "client", "supernode"].contains(&n.node_type.as_str()) {
                errors.push(format!(
                    "Supernode '{}': node '{}' has forbidden type '{}' \
                     (supernodes cannot contain endpoints or other supernodes)",
                    sn.name, n.id, n.node_type
                ));
            }
        }
    }

    let node_ids: HashSet<&str> = sn.nodes.iter().map(|n| n.id.as_str()).collect();

    // Build a set of exit-boundary ids once, above the edge loop
    let exit_boundary_ids: HashSet<&str> = sn
        .nodes
        .iter()
        .filter(|n| n.node_type == "output" || n.node_type == "error")
        .map(|n| n.id.as_str())
        .collect();

    for edge in &sn.edges {
        let (from_node, _) = split_endpoint(&edge.from);
        let (to_node, _) = split_endpoint(&edge.to);
        if !node_ids.contains(from_node) {
            errors.push(format!(
                "Supernode '{}': edge references unknown source node: '{}'",
                sn.name, from_node
            ));
        }
        if !node_ids.contains(to_node) {
            errors.push(format!(
                "Supernode '{}': edge references unknown target node: '{}'",
                sn.name, to_node
            ));
        }
        if to_node == "input" {
            errors.push(format!(
                "Supernode '{}': the 'input' boundary cannot have incoming edges",
                sn.name
            ));
        }
        if exit_boundary_ids.contains(from_node) {
            errors.push(format!(
                "Supernode '{}': the '{}' boundary cannot have outgoing edges",
                sn.name, from_node
            ));
        }
    }

    let input_out_edges = sn
        .edges
        .iter()
        .filter(|e| split_endpoint(&e.from).0 == "input")
        .count();
    if input_out_edges != 1 {
        errors.push(format!(
            "Supernode '{}' must have exactly one edge from input.out (found {})",
            sn.name, input_out_edges
        ));
    }

    // Fan-in is unrestricted here too: any number of inner edges may converge
    // on the same input port or boundary exit.

    // Port hygiene on inner nodes. Boundary pseudo-nodes have no plugin type
    // (and no PortSpec), so they are exempt; an unknown inner type is left to
    // the forbidden-type/factory checks rather than reported twice here.
    let inner_specs: std::collections::HashMap<&str, &'static crate::plugins::ports::PortSpec> = sn
        .nodes
        .iter()
        .filter(|n| !BOUNDARY_TYPES.contains(&n.node_type.as_str()))
        .filter_map(|n| crate::plugins::port_spec(&n.node_type).map(|s| (n.id.as_str(), s)))
        .collect();

    // (a) Every inner edge must leave a port its source type declares.
    let mut wired_ports: HashSet<(&str, &str)> = HashSet::new();
    for edge in &sn.edges {
        let (from_node, from_port) = split_endpoint(&edge.from);
        let from_port = if from_port == "out" {
            "success"
        } else {
            from_port
        };
        let Some(spec) = inner_specs.get(from_node) else {
            continue; // boundary node, or a type reported elsewhere
        };
        if spec.outputs.iter().any(|p| p.name == from_port) {
            wired_ports.insert((from_node, from_port));
        } else {
            let node_type = sn
                .nodes
                .iter()
                .find(|n| n.id == from_node)
                .map(|n| n.node_type.as_str())
                .unwrap_or("");
            errors.push(format!(
                "Supernode '{}': node '{}' (type '{}') has no output port '{}'",
                sn.name, from_node, node_type, from_port
            ));
        }
    }

    // (b) Every success/outcome port of every inner node must be wired inside
    // the definition. `error` is exempt (the black-box rule covers it).
    for n in &sn.nodes {
        let Some(spec) = inner_specs.get(n.id.as_str()) else {
            continue;
        };
        for p in spec.outputs {
            if matches!(p.kind, crate::plugins::ports::PortKind::Error) {
                continue;
            }
            if !wired_ports.contains(&(n.id.as_str(), p.name)) {
                errors.push(format!(
                    "Supernode '{}': output port '{}' of node '{}' (type '{}') must be wired \
                     inside the definition — add an edge from '{}.{}' to another inner node or \
                     to the 'output'/'error' boundary",
                    sn.name, p.name, n.id, n.node_type, n.id, p.name
                ));
            }
        }
    }

    // Orphans: every non-boundary node needs at least one edge.
    let mut connected: HashSet<&str> = HashSet::new();
    for edge in &sn.edges {
        connected.insert(split_endpoint(&edge.from).0);
        connected.insert(split_endpoint(&edge.to).0);
    }
    for n in &sn.nodes {
        if !BOUNDARY_TYPES.contains(&n.node_type.as_str()) && !connected.contains(n.id.as_str()) {
            errors.push(format!(
                "Supernode '{}': Orphan node '{}' has no connections",
                sn.name, n.id
            ));
        }
    }

    if errors.is_empty() {
        Ok(())
    } else {
        Err(errors)
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::config::{EdgeConfig, NodeConfig, PolicyConfig, SupernodeConfig};
    use std::collections::HashMap;

    fn listener_node() -> NodeConfig {
        NodeConfig {
            id: "listener".to_string(),
            node_type: "listener".to_string(),
            config: HashMap::new(),
            config_ref: None,
            position: None,
        }
    }

    fn client_node() -> NodeConfig {
        NodeConfig {
            id: "client".to_string(),
            node_type: "client".to_string(),
            config: HashMap::new(),
            config_ref: None,
            position: None,
        }
    }

    fn upstream_node() -> NodeConfig {
        NodeConfig {
            id: "backend".to_string(),
            node_type: "upstream".to_string(),
            config: HashMap::new(),
            config_ref: None,
            position: None,
        }
    }

    fn boundary_nodes() -> Vec<NodeConfig> {
        ["input", "output", "error"]
            .into_iter()
            .map(|t| NodeConfig {
                id: t.to_string(),
                node_type: t.to_string(),
                config: HashMap::new(),
                config_ref: None,
                position: None,
            })
            .collect()
    }

    fn inner(id: &str, ty: &str) -> NodeConfig {
        NodeConfig {
            id: id.to_string(),
            node_type: ty.to_string(),
            config: HashMap::new(),
            config_ref: None,
            position: None,
        }
    }

    fn sn_edge(from: &str, to: &str) -> EdgeConfig {
        EdgeConfig {
            from: from.to_string(),
            to: to.to_string(),
        }
    }

    fn valid_supernode() -> SupernodeConfig {
        let mut nodes = boundary_nodes();
        nodes.push(inner("up", "upstream"));
        SupernodeConfig {
            name: "sn".to_string(),
            description: None,
            nodes,
            edges: vec![
                sn_edge("input.out", "up.in"),
                sn_edge("up.success", "output.in"),
                sn_edge("up.error", "error.in"),
            ],
        }
    }

    #[test]
    fn test_valid_simple_policy() {
        let policy = PolicyConfig {
            name: "test".to_string(),
            error_handler: None,
            nodes: vec![listener_node(), upstream_node(), client_node()],
            edges: vec![
                EdgeConfig {
                    from: "listener.out".to_string(),
                    to: "backend.in".to_string(),
                },
                EdgeConfig {
                    from: "backend.success".to_string(),
                    to: "client.in".to_string(),
                },
            ],
        };
        assert!(validate_policy(&policy).is_ok());
    }

    #[test]
    fn test_missing_listener() {
        let policy = PolicyConfig {
            name: "test".to_string(),
            error_handler: None,
            nodes: vec![upstream_node(), client_node()],
            edges: vec![],
        };
        let errors = validate_policy(&policy).unwrap_err();
        assert!(errors.iter().any(|e| e.contains("listener")));
    }

    #[test]
    fn test_missing_client() {
        let policy = PolicyConfig {
            name: "test".to_string(),
            error_handler: None,
            nodes: vec![listener_node(), upstream_node()],
            edges: vec![EdgeConfig {
                from: "listener.out".to_string(),
                to: "backend.in".to_string(),
            }],
        };
        let errors = validate_policy(&policy).unwrap_err();
        assert!(errors.iter().any(|e| e.contains("client")));
    }

    #[test]
    fn test_unknown_edge_reference() {
        let policy = PolicyConfig {
            name: "test".to_string(),
            error_handler: None,
            nodes: vec![listener_node(), client_node()],
            edges: vec![EdgeConfig {
                from: "listener.out".to_string(),
                to: "nonexistent.in".to_string(),
            }],
        };
        let errors = validate_policy(&policy).unwrap_err();
        assert!(errors.iter().any(|e| e.contains("nonexistent")));
    }

    #[test]
    fn test_client_allows_multiple_inputs() {
        let policy = PolicyConfig {
            name: "test".to_string(),
            error_handler: None,
            nodes: vec![listener_node(), upstream_node(), client_node()],
            edges: vec![
                EdgeConfig {
                    from: "listener.out".to_string(),
                    to: "backend.in".to_string(),
                },
                EdgeConfig {
                    from: "backend.success".to_string(),
                    to: "client.in".to_string(),
                },
                EdgeConfig {
                    from: "backend.error".to_string(),
                    to: "client.in".to_string(),
                },
            ],
        };
        assert!(validate_policy(&policy).is_ok());
    }

    /// Fan-in is legal on every node, not just client/error-handler: the
    /// engine indexes edges by source port only, so any number of edges may
    /// converge on the same input.
    #[test]
    fn test_any_node_allows_multiple_inputs() {
        let mut second = upstream_node();
        second.id = "backend2".to_string();
        let policy = PolicyConfig {
            name: "test".to_string(),
            error_handler: None,
            nodes: vec![listener_node(), upstream_node(), second, client_node()],
            edges: vec![
                EdgeConfig {
                    from: "listener.out".to_string(),
                    to: "backend2.in".to_string(),
                },
                EdgeConfig {
                    from: "backend2.success".to_string(),
                    to: "backend.in".to_string(),
                },
                EdgeConfig {
                    from: "backend2.error".to_string(),
                    to: "backend.in".to_string(),
                },
                EdgeConfig {
                    from: "backend.success".to_string(),
                    to: "client.in".to_string(),
                },
            ],
        };
        assert!(validate_policy(&policy).is_ok());
    }

    #[test]
    fn test_valid_supernode_passes() {
        assert!(validate_supernode(&valid_supernode()).is_ok());
    }

    /// Fan-in converges on inner nodes too, not only boundary exits.
    #[test]
    fn test_supernode_fan_in_into_inner_node_ok() {
        let mut sn = valid_supernode();
        sn.nodes.push(inner("up2", "upstream"));
        sn.edges = vec![
            sn_edge("input.out", "up2.in"),
            sn_edge("up2.success", "up.in"),
            sn_edge("up2.error", "up.in"),
            sn_edge("up.success", "output.in"),
            sn_edge("up.error", "error.in"),
        ];
        assert!(validate_supernode(&sn).is_ok());
    }

    #[test]
    fn test_supernode_missing_boundary_nodes() {
        let mut sn = valid_supernode();
        sn.nodes.retain(|n| n.node_type != "error");
        let errors = validate_supernode(&sn).unwrap_err();
        assert!(
            errors.iter().any(|e| e.contains("'error' boundary node")),
            "{errors:?}"
        );
    }

    #[test]
    fn test_supernode_boundary_id_must_match_type() {
        let mut sn = valid_supernode();
        sn.nodes
            .iter_mut()
            .find(|n| n.node_type == "input")
            .unwrap()
            .id = "start".into();
        let errors = validate_supernode(&sn).unwrap_err();
        assert!(
            errors.iter().any(|e| e.contains("must have id 'input'")),
            "{errors:?}"
        );
    }

    #[test]
    fn test_supernode_forbidden_inner_types() {
        for ty in ["listener", "client", "supernode"] {
            let mut sn = valid_supernode();
            sn.nodes.push(inner("x", ty));
            sn.edges.push(sn_edge("up.success", "x.in"));
            let errors = validate_supernode(&sn).unwrap_err();
            assert!(
                errors.iter().any(|e| e.contains("forbidden type")),
                "type {ty}: {errors:?}"
            );
        }
    }

    #[test]
    fn test_supernode_reserved_inner_ids_and_slash() {
        let mut sn = valid_supernode();
        sn.nodes.push(inner("output2/x", "cors"));
        sn.edges.push(sn_edge("up.success", "output2/x.in"));
        let errors = validate_supernode(&sn).unwrap_err();
        assert!(
            errors.iter().any(|e| e.contains("must not contain '/'")),
            "{errors:?}"
        );
    }

    #[test]
    fn test_supernode_input_needs_exactly_one_outgoing_edge() {
        let mut sn = valid_supernode();
        sn.nodes.push(inner("cors", "cors"));
        sn.edges.push(sn_edge("input.out", "cors.in"));
        sn.edges.push(sn_edge("cors.success", "output.in"));
        let errors = validate_supernode(&sn).unwrap_err();
        assert!(
            errors.iter().any(|e| e.contains("exactly one edge")),
            "{errors:?}"
        );

        let mut sn = valid_supernode();
        sn.edges.retain(|e| !e.from.starts_with("input."));
        let errors = validate_supernode(&sn).unwrap_err();
        assert!(
            errors.iter().any(|e| e.contains("exactly one edge")),
            "{errors:?}"
        );
    }

    #[test]
    fn test_supernode_boundary_direction_rules() {
        let mut sn = valid_supernode();
        sn.edges.push(sn_edge("output.out", "up.in")); // out of output: invalid
        sn.edges.push(sn_edge("up.success", "input.in")); // into input: invalid
        let errors = validate_supernode(&sn).unwrap_err();
        assert!(
            errors.iter().any(|e| e.contains("cannot have outgoing")),
            "{errors:?}"
        );
        assert!(
            errors.iter().any(|e| e.contains("cannot have incoming")),
            "{errors:?}"
        );
    }

    /// Two branches may exit through the same boundary port (fan-in), and an
    /// unconnected `error` boundary is not an orphan.
    #[test]
    fn test_supernode_fan_in_to_output_and_unused_error_ok() {
        let mut nodes = boundary_nodes();
        nodes.push(inner("a", "cors"));
        nodes.push(inner("b", "gzip"));
        let sn = SupernodeConfig {
            name: "fan".to_string(),
            description: None,
            nodes,
            edges: vec![
                sn_edge("input.out", "a.in"),
                sn_edge("a.success", "b.in"),
                sn_edge("a.preflight", "output.in"), // cors' outcome port
                sn_edge("a.error", "output.in"),
                sn_edge("b.success", "output.in"),
            ],
        };
        assert!(
            validate_supernode(&sn).is_ok(),
            "{:?}",
            validate_supernode(&sn)
        );
    }

    /// I4(b): an inner node whose outcome port is left unwired inside the
    /// definition must be rejected at save time. Otherwise the failure only
    /// surfaces later, as a compile error on whichever unrelated policy
    /// happens to instantiate the supernode.
    #[test]
    fn test_supernode_unwired_inner_outcome_port_rejected() {
        let mut nodes = boundary_nodes();
        nodes.push(inner("auth", "key-auth"));
        let sn = SupernodeConfig {
            name: "unwired".to_string(),
            description: None,
            nodes,
            edges: vec![
                sn_edge("input.out", "auth.in"),
                sn_edge("auth.success", "output.in"),
                // auth.denied deliberately left unwired
            ],
        };
        let errors = validate_supernode(&sn).unwrap_err();
        assert!(
            errors.iter().any(|e| e.contains("output port 'denied'")
                && e.contains("'auth'")
                && e.contains("must be wired inside the definition")),
            "{errors:?}"
        );
    }

    /// The same definition with `denied` wired to a boundary is accepted.
    #[test]
    fn test_supernode_fully_wired_outcome_port_accepted() {
        let mut nodes = boundary_nodes();
        nodes.push(inner("auth", "key-auth"));
        let sn = SupernodeConfig {
            name: "wired".to_string(),
            description: None,
            nodes,
            edges: vec![
                sn_edge("input.out", "auth.in"),
                sn_edge("auth.success", "output.in"),
                sn_edge("auth.denied", "output.in"),
            ],
        };
        assert_eq!(validate_supernode(&sn), Ok(()));
    }

    /// I4(a): an inner edge naming a port the node's type does not declare is
    /// rejected — the same rule `compile_policy` applies to policy edges.
    #[test]
    fn test_supernode_undeclared_inner_port_rejected() {
        let mut nodes = boundary_nodes();
        nodes.push(inner("up", "upstream"));
        let sn = SupernodeConfig {
            name: "bogus-port".to_string(),
            description: None,
            nodes,
            edges: vec![
                sn_edge("input.out", "up.in"),
                sn_edge("up.success", "output.in"),
                sn_edge("up.banana", "error.in"),
            ],
        };
        let errors = validate_supernode(&sn).unwrap_err();
        assert!(
            errors
                .iter()
                .any(|e| e.contains("has no output port 'banana'") && e.contains("'up'")),
            "{errors:?}"
        );
    }

    /// `out` is the YAML alias for `success` on an inner edge too, and must
    /// satisfy the mandatory-wiring check rather than trip the port-name one.
    #[test]
    fn test_supernode_out_alias_satisfies_inner_wiring() {
        let mut nodes = boundary_nodes();
        nodes.push(inner("up", "upstream"));
        let sn = SupernodeConfig {
            name: "alias".to_string(),
            description: None,
            nodes,
            edges: vec![
                sn_edge("input.out", "up.in"),
                sn_edge("up.out", "output.in"),
            ],
        };
        assert_eq!(validate_supernode(&sn), Ok(()));
    }

    /// All violations are collected, not just the first: two inner nodes each
    /// missing a mandatory port report two errors.
    #[test]
    fn test_supernode_collects_all_port_violations() {
        let mut nodes = boundary_nodes();
        nodes.push(inner("auth", "key-auth"));
        nodes.push(inner("rl", "rate-limit"));
        let sn = SupernodeConfig {
            name: "many".to_string(),
            description: None,
            nodes,
            edges: vec![
                sn_edge("input.out", "auth.in"),
                sn_edge("auth.success", "rl.in"),
                sn_edge("rl.success", "output.in"),
                // auth.denied and rl.limited both unwired
            ],
        };
        let errors = validate_supernode(&sn).unwrap_err();
        assert!(errors.iter().any(|e| e.contains("'denied'")), "{errors:?}");
        assert!(errors.iter().any(|e| e.contains("'limited'")), "{errors:?}");
    }

    #[test]
    fn test_supernode_dangling_edge_and_orphan() {
        let mut sn = valid_supernode();
        sn.edges.push(sn_edge("ghost.success", "output.in"));
        sn.nodes.push(inner("lonely", "cors"));
        let errors = validate_supernode(&sn).unwrap_err();
        assert!(
            errors
                .iter()
                .any(|e| e.contains("unknown source node: 'ghost'")),
            "{errors:?}"
        );
        assert!(
            errors.iter().any(|e| e.contains("Orphan node 'lonely'")),
            "{errors:?}"
        );
    }

    #[test]
    fn test_policy_rejects_slash_ids_and_reserved_types() {
        let mut policy = PolicyConfig {
            name: "test".to_string(),
            error_handler: None,
            nodes: vec![listener_node(), upstream_node(), client_node()],
            edges: vec![
                EdgeConfig {
                    from: "listener.out".to_string(),
                    to: "backend.in".to_string(),
                },
                EdgeConfig {
                    from: "backend.success".to_string(),
                    to: "client.in".to_string(),
                },
            ],
        };
        policy.nodes[1].id = "a/b".to_string();
        policy.edges[0].to = "a/b.in".to_string();
        policy.edges[1].from = "a/b.success".to_string();
        let errors = validate_policy(&policy).unwrap_err();
        assert!(
            errors.iter().any(|e| e.contains("must not contain '/'")),
            "{errors:?}"
        );

        let mut policy2 = PolicyConfig {
            name: "test2".to_string(),
            error_handler: None,
            nodes: vec![listener_node(), inner("x", "input"), client_node()],
            edges: vec![
                EdgeConfig {
                    from: "listener.out".to_string(),
                    to: "x.in".to_string(),
                },
                EdgeConfig {
                    from: "x.success".to_string(),
                    to: "client.in".to_string(),
                },
            ],
        };
        policy2.nodes[1].node_type = "input".to_string();
        let errors = validate_policy(&policy2).unwrap_err();
        assert!(
            errors.iter().any(|e| e.contains("reserved for supernode")),
            "{errors:?}"
        );
    }

    /// I-1: a policy whose `error_handler` names a `type: supernode`
    /// instance passes structural checks against the un-expanded node list
    /// but dangles after expansion (the instance node is removed). Must be
    /// rejected at validate_policy time, before expansion ever runs.
    #[test]
    fn test_error_handler_rejects_supernode_instance() {
        let mut sn_instance = inner("sec", "supernode");
        sn_instance
            .config
            .insert("name".to_string(), serde_json::json!("secured-call"));

        let policy = PolicyConfig {
            name: "test".to_string(),
            error_handler: Some("sec".to_string()),
            nodes: vec![listener_node(), sn_instance, client_node()],
            edges: vec![
                EdgeConfig {
                    from: "listener.out".to_string(),
                    to: "sec.in".to_string(),
                },
                EdgeConfig {
                    from: "sec.success".to_string(),
                    to: "client.in".to_string(),
                },
            ],
        };
        let errors = validate_policy(&policy).unwrap_err();
        assert!(
            errors
                .iter()
                .any(|e| e.contains("error_handler") && e.contains("sec")),
            "{errors:?}"
        );
    }

    /// FINDING D: two nodes sharing an id collapse silently in compile —
    /// with supernodes this would silently drop an expansion — so
    /// validate_policy must reject every duplicate.
    #[test]
    fn test_duplicate_node_ids_rejected() {
        let policy = PolicyConfig {
            name: "test".to_string(),
            error_handler: None,
            nodes: vec![
                listener_node(),
                upstream_node(),
                upstream_node(),
                client_node(),
            ],
            edges: vec![
                EdgeConfig {
                    from: "listener.out".to_string(),
                    to: "backend.in".to_string(),
                },
                EdgeConfig {
                    from: "backend.success".to_string(),
                    to: "client.in".to_string(),
                },
            ],
        };
        let errors = validate_policy(&policy).unwrap_err();
        assert!(
            errors
                .iter()
                .any(|e| e.contains("Duplicate node id 'backend'")),
            "{errors:?}"
        );
    }

    /// Named output ports: any number of `type: output` boundary nodes, each
    /// id becoming an instance port name (spec §1-2).
    #[test]
    fn test_supernode_multiple_output_boundaries_accepted() {
        let mut nodes = boundary_nodes(); // input/output/error
        nodes.push(inner("denied", "output"));
        nodes.push(inner("auth", "key-auth"));
        let sn = SupernodeConfig {
            name: "gate".to_string(),
            description: None,
            nodes,
            edges: vec![
                sn_edge("input.out", "auth.in"),
                sn_edge("auth.success", "output.in"),
                sn_edge("auth.denied", "denied.in"),
            ],
        };
        assert_eq!(validate_supernode(&sn), Ok(()));
    }

    /// A definition may have only named outputs (no `output`-id node): the
    /// instance then has no `success` port.
    #[test]
    fn test_supernode_only_named_outputs_accepted() {
        let nodes: Vec<NodeConfig> = vec![
            inner("input", "input"),
            inner("done", "output"),
            inner("error", "error"),
            inner("up", "upstream"),
        ];
        let sn = SupernodeConfig {
            name: "named-only".to_string(),
            description: None,
            nodes,
            edges: vec![
                sn_edge("input.out", "up.in"),
                sn_edge("up.success", "done.in"),
            ],
        };
        assert_eq!(validate_supernode(&sn), Ok(()));
    }

    /// Reserved ids collide with fixed instance port names.
    #[test]
    fn test_supernode_reserved_output_ids_rejected() {
        for id in ["input", "error", "in", "out", "success"] {
            let mut sn = valid_supernode();
            sn.nodes.push(inner(id, "output"));
            let errors = validate_supernode(&sn).unwrap_err();
            assert!(
                errors.iter().any(|e| e.contains("reserved")),
                "id {id}: {errors:?}"
            );
        }
    }

    /// Zero output boundaries is still an error.
    #[test]
    fn test_supernode_zero_output_boundaries_rejected() {
        let mut sn = valid_supernode();
        sn.nodes.retain(|n| n.node_type != "output");
        sn.edges.retain(|e| !e.to.starts_with("output."));
        // keep `up` connected so only the output complaint fires
        sn.edges.push(sn_edge("up.success", "error.in"));
        let errors = validate_supernode(&sn).unwrap_err();
        assert!(
            errors
                .iter()
                .any(|e| e.contains("at least one 'output' boundary")),
            "{errors:?}"
        );
    }

    /// Duplicate node ids inside a definition are rejected (two outputs with
    /// the same id would otherwise be one ambiguous port).
    #[test]
    fn test_supernode_duplicate_node_ids_rejected() {
        let mut sn = valid_supernode();
        sn.nodes.push(inner("denied", "output"));
        sn.nodes.push(inner("denied", "output"));
        let errors = validate_supernode(&sn).unwrap_err();
        assert!(
            errors
                .iter()
                .any(|e| e.contains("duplicate node id 'denied'")),
            "{errors:?}"
        );
    }

    /// Named output boundaries obey the no-outgoing-edges rule like `output`/`error`.
    #[test]
    fn test_supernode_named_output_boundary_no_outgoing_edges() {
        let mut sn = valid_supernode();
        sn.nodes.push(inner("denied", "output"));
        sn.edges.push(sn_edge("denied.out", "up.in"));
        let errors = validate_supernode(&sn).unwrap_err();
        assert!(
            errors
                .iter()
                .any(|e| e.contains("'denied'") && e.contains("cannot have outgoing")),
            "{errors:?}"
        );
    }

    /// Named error ports: any number of `type: error` boundary nodes (spec §1-2).
    #[test]
    fn test_supernode_multiple_error_boundaries_accepted() {
        let mut sn = valid_supernode();
        sn.nodes.push(inner("auth-error", "error"));
        // `up.error` already exits via the default `error` boundary; the extra
        // named error boundary may stay unconnected (boundaries are orphan-exempt).
        assert_eq!(validate_supernode(&sn), Ok(()));
    }

    /// A definition whose only error boundary is renamed away from `error` is
    /// legal — the instance then has no default black-box exit.
    #[test]
    fn test_supernode_renamed_only_error_boundary_accepted() {
        let mut sn = valid_supernode();
        sn.nodes
            .iter_mut()
            .find(|n| n.node_type == "error")
            .unwrap()
            .id = "oops".into();
        sn.edges.iter_mut().find(|e| e.to == "error.in").unwrap().to = "oops.in".into();
        assert_eq!(validate_supernode(&sn), Ok(()));
    }

    #[test]
    fn test_supernode_zero_error_boundaries_rejected() {
        let mut sn = valid_supernode();
        sn.nodes.retain(|n| n.node_type != "error");
        sn.edges.retain(|e| !e.to.starts_with("error."));
        let errors = validate_supernode(&sn).unwrap_err();
        assert!(
            errors
                .iter()
                .any(|e| e.contains("at least one 'error' boundary")),
            "{errors:?}"
        );
    }

    #[test]
    fn test_supernode_reserved_error_ids_rejected() {
        for id in ["input", "output", "in", "out", "success"] {
            let mut sn = valid_supernode();
            sn.nodes.push(inner(id, "error"));
            let errors = validate_supernode(&sn).unwrap_err();
            assert!(
                errors.iter().any(|e| e.contains("reserved")),
                "id {id}: {errors:?}"
            );
        }
    }
}