automapper_validation/validator/

validate.rs

//! Main EdifactValidator implementation.

use std::collections::{BTreeMap, HashMap, HashSet};

use crate::expr::{ConditionExpr, ConditionParser};

use crate::eval::{
    ConditionEvaluator, ConditionExprEvaluator, ConditionResult, EvaluationContext,
    ExternalConditionProvider, GroupScope,
};
use mig_types::navigator::GroupNavigator;
use mig_types::segment::OwnedSegment;

use super::tree::{AhbGroupNode, AhbNode, ValidatedTree};

use super::issue::{Severity, ValidationIssue};
use super::level::ValidationLevel;
use super::report::ValidationReport;
use crate::{IssueKind, UnresolvedConditions};

// The AHB rulebook data types (`AhbFieldRule`, `AhbCodeRule`, `AhbWorkflow`) now
// live in the `ahb-types` crate so both this validation crate and `mig-bo4e`
// (which embeds `AhbWorkflow` in the distribution bundle) can share them as
// serializable data — without a mapping↔validation dependency edge. Re-exported
// here so existing `crate::validator::validate::Ahb*` paths keep resolving.
pub use ahb_types::{AhbCodeRule, AhbFieldRule, AhbWorkflow};

/// Validates EDIFACT messages against AHB business rules.
///
/// The validator is a pure validation engine: it receives pre-parsed
/// segments, an AHB workflow, and an external condition provider.
/// Parsing and message-type detection are the caller's responsibility.
///
/// The validator is generic over the `ConditionEvaluator` implementation,
/// which is typically generated from AHB XML schemas.
///
/// # Example
///
/// ```ignore
/// use automapper_validation::validator::EdifactValidator;
/// use automapper_validation::eval::NoOpExternalProvider;
///
/// let evaluator = UtilmdConditionEvaluatorFV2510::new();
/// let validator = EdifactValidator::new(evaluator);
/// let external = NoOpExternalProvider;
///
/// let report = validator.validate(
///     &segments,
///     &ahb_workflow,
///     &external,
///     ValidationLevel::Full,
/// );
///
/// if !report.is_valid() {
///     for error in report.errors() {
///         eprintln!("{error}");
///     }
/// }
/// ```
pub struct EdifactValidator<E: ConditionEvaluator> {
    evaluator: E,
}

impl<E: ConditionEvaluator> EdifactValidator<E> {
    /// Create a new validator with the given condition evaluator.
    pub fn new(evaluator: E) -> Self {
        Self { evaluator }
    }

    /// Validate pre-parsed EDIFACT segments against an AHB workflow.
    ///
    /// # Arguments
    ///
    /// * `segments` - Pre-parsed EDIFACT segments
    /// * `workflow` - AHB workflow definition for the PID
    /// * `external` - Provider for external conditions
    /// * `level` - Validation strictness level
    ///
    /// # Returns
    ///
    /// A `ValidationReport` with all issues found.
    pub fn validate(
        &self,
        segments: &[OwnedSegment],
        workflow: &AhbWorkflow,
        external: &dyn ExternalConditionProvider,
        level: ValidationLevel,
    ) -> ValidationReport {
        let mut report = ValidationReport::new(self.evaluator.message_type(), level)
            .with_format_version(self.evaluator.format_version())
            .with_pruefidentifikator(&workflow.pruefidentifikator);

        let ctx = EvaluationContext::new(&workflow.pruefidentifikator, external, segments);

        if matches!(level, ValidationLevel::Conditions | ValidationLevel::Full) {
            self.validate_conditions(workflow, &ctx, &mut report);
        }

        report
    }

    /// Validate with a group navigator for group-scoped condition queries.
    ///
    /// Same as [`validate`] but passes a `GroupNavigator` to the
    /// `EvaluationContext`, enabling conditions to query segments within
    /// specific group instances (e.g., "in derselben SG8").
    pub fn validate_with_navigator(
        &self,
        segments: &[OwnedSegment],
        workflow: &AhbWorkflow,
        external: &dyn ExternalConditionProvider,
        level: ValidationLevel,
        navigator: &dyn GroupNavigator,
    ) -> ValidationReport {
        let mut report = ValidationReport::new(self.evaluator.message_type(), level)
            .with_format_version(self.evaluator.format_version())
            .with_pruefidentifikator(&workflow.pruefidentifikator);

        let ctx = EvaluationContext::with_navigator(
            &workflow.pruefidentifikator,
            external,
            segments,
            navigator,
        );

        if matches!(level, ValidationLevel::Conditions | ValidationLevel::Full) {
            self.validate_conditions(workflow, &ctx, &mut report);
        }

        report
    }

    /// Validate using a pre-built ValidatedTree where each node carries
    /// its resolved EDIFACT value.
    ///
    /// This is the preferred validation path -- conditions see `ctx.resolved_value`
    /// set from the tree node, so format conditions like [931] "ZZZ=+00" check
    /// the correct segment instance (e.g., DTM+92, not DTM+137).
    pub fn validate_tree(
        &self,
        validated_tree: &ValidatedTree,
        segments: &[OwnedSegment],
        external: &dyn ExternalConditionProvider,
        level: ValidationLevel,
        navigator: Option<&dyn GroupNavigator>,
    ) -> ValidationReport {
        let mut report = ValidationReport::new(self.evaluator.message_type(), level)
            .with_format_version(self.evaluator.format_version())
            .with_pruefidentifikator(validated_tree.pruefidentifikator);

        if !matches!(level, ValidationLevel::Conditions | ValidationLevel::Full) {
            return report;
        }

        let ctx = match navigator {
            Some(nav) => EvaluationContext::with_navigator(
                validated_tree.pruefidentifikator,
                external,
                segments,
                nav,
            ),
            None => EvaluationContext::new(validated_tree.pruefidentifikator, external, segments),
        };

        let expr_eval = ConditionExprEvaluator::new(&self.evaluator);

        // Collect all nodes depth-first from the tree (used for tag_migs
        // precomputation and for the synthetic workflow at the bottom).
        let mut all_nodes: Vec<&AhbNode> = Vec::new();
        all_nodes.extend(validated_tree.root_fields.iter());
        for group in &validated_tree.groups {
            collect_nodes_depth_first(group, &mut all_nodes);
        }

        // For each segment tag, collect all distinct mig_numbers the workflow
        // defines. Tags with a single mig variant (UNT/UNS/UNZ in MSCONS) let
        // us fall back to a flat-segment check when assembly didn't claim the
        // segment; tags with multiple variants (DTM with +92/+93 in UTILMD)
        // must not, because a different variant's segment may satisfy
        // `is_field_present` while the rule's specific variant is absent.
        let mut tag_migs: HashMap<String, HashSet<&str>> = HashMap::new();
        for node in &all_nodes {
            if let Some(ref m) = node.rule.mig_number {
                tag_migs
                    .entry(extract_segment_id(&node.rule.segment_path))
                    .or_default()
                    .insert(m.as_str());
            }
        }
        for rule in &validated_tree.unmatched_rules {
            if let Some(ref m) = rule.mig_number {
                tag_migs
                    .entry(extract_segment_id(&rule.segment_path))
                    .or_default()
                    .insert(m.as_str());
            }
        }

        // Evaluate root-level fields (not inside any group) with message-wide scope.
        for node in &validated_tree.root_fields {
            evaluate_node(
                node,
                &ctx,
                &expr_eval,
                &self.evaluator,
                validated_tree.ub_definitions,
                &tag_migs,
                None,
                &mut report,
            );
        }

        // Walk top-level groups with per-instance scope. `validated_tree.groups`
        // is a flat Vec<AhbGroupNode> where each entry corresponds to one
        // group repetition; compute the instance index by counting preceding
        // entries with the same group_id.
        let mut instance_counter: HashMap<&str, usize> = HashMap::new();
        for group in &validated_tree.groups {
            let instance_index = *instance_counter
                .entry(group.group_id)
                .and_modify(|c| *c += 1)
                .or_insert(0);

            let group_path_storage = [group.group_id];
            // Build a scoped context without consuming `ctx` (used again for
            // the synthetic-workflow checks at the end of this method).
            let scoped_ctx = ctx.with_scope(GroupScope {
                group_path: &group_path_storage,
                instance_index,
            });

            walk_group_instance(
                group,
                &scoped_ctx,
                &expr_eval,
                &self.evaluator,
                validated_tree.ub_definitions,
                &tag_migs,
                instance_index,
                &mut report,
            );
        }

        // Evaluate rules whose mig_number wasn't matched to any tree node.
        // These represent entirely-absent group variants (e.g., NAD+MS when
        // only NAD+MR is present). Use the flat is_field_present/is_group_variant_absent
        // logic which correctly distinguishes mandatory-but-missing variants from
        // optional-and-absent ones.
        for field in &validated_tree.unmatched_rules {
            if should_skip_for_parent_group(field, &expr_eval, &ctx, validated_tree.ub_definitions)
            {
                continue;
            }

            let (condition_result, _) = expr_eval.evaluate_status_detailed_with_ub(
                &field.ahb_status,
                &ctx,
                validated_tree.ub_definitions,
            );

            if matches!(condition_result, ConditionResult::True)
                && is_mandatory_status(&field.ahb_status)
                && !is_field_present(&ctx, field)
                && !is_group_variant_absent(&ctx, field)
            {
                let mut issue = ValidationIssue::new(
                    Severity::Error,
                    IssueKind::MissingRequiredField {
                        field_name: field.name.clone(),
                    },
                )
                .with_field_path(&field.segment_path)
                .with_rule(&field.ahb_status);
                if let Some(first_code) = field.codes.first() {
                    issue.expected_value = Some(first_code.value.clone());
                }
                issue = attach_field_position(issue, field);
                report.add_issue(issue);
            }
        }

        // Run cross-field code validation and package cardinality checks.
        // These operate on flat field rules (no resolved_value needed),
        // so we reconstruct a lightweight workflow from the tree's rules.
        if matches!(level, ValidationLevel::Full) {
            let mut all_fields: Vec<AhbFieldRule> = Vec::new();
            for node in &all_nodes {
                all_fields.push(node.rule.clone());
            }
            for rule in &validated_tree.unmatched_rules {
                all_fields.push((*rule).clone());
            }
            let synthetic_workflow = AhbWorkflow {
                pruefidentifikator: validated_tree.pruefidentifikator.to_string(),
                description: String::new(),
                communication_direction: None,
                fields: all_fields,
                ub_definitions: validated_tree.ub_definitions.clone(),
            };
            self.validate_codes_cross_field(&synthetic_workflow, &ctx, &mut report);
            self.validate_package_cardinality(&synthetic_workflow, &ctx, &mut report);
        }

        report
    }

    /// Validate AHB conditions for each field in the workflow.
    fn validate_conditions(
        &self,
        workflow: &AhbWorkflow,
        ctx: &EvaluationContext,
        report: &mut ValidationReport,
    ) {
        let expr_eval = ConditionExprEvaluator::new(&self.evaluator);

        for field in &workflow.fields {
            // Skip if parent group condition is not met (False or Unknown).
            if should_skip_for_parent_group(field, &expr_eval, ctx, &workflow.ub_definitions) {
                continue;
            }

            // Evaluate the AHB status condition expression, collecting
            // which specific condition IDs are unknown when the result is Unknown.
            let (condition_result, unknown_ids) = expr_eval.evaluate_status_detailed_with_ub(
                &field.ahb_status,
                ctx,
                &workflow.ub_definitions,
            );

            match condition_result {
                ConditionResult::True => {
                    // Condition is met - field is required/applicable
                    if is_mandatory_status(&field.ahb_status)
                        && !is_field_present(ctx, field)
                        && !is_group_variant_absent(ctx, field)
                    {
                        let mut issue = ValidationIssue::new(
                            Severity::Error,
                            IssueKind::MissingRequiredField {
                                field_name: field.name.clone(),
                            },
                        )
                        .with_field_path(&field.segment_path)
                        .with_rule(&field.ahb_status);
                        // Store the first expected code for BO4E path disambiguation.
                        // E.g., DTM+93's code "93" helps resolve SG4/DTM/C507/2005
                        // to Prozessdaten.gueltigBis vs gueltigAb.
                        if let Some(first_code) = field.codes.first() {
                            issue.expected_value = Some(first_code.value.clone());
                        }
                        report.add_issue(issue);
                    }
                }
                ConditionResult::False => {
                    // Condition not met.
                    // If the field has a mandatory prefix (X, Muss) AND the field is
                    // present, the condition is a format/value constraint that the
                    // value violates. E.g., "X [UB1]" where UB1 checks timezone
                    // format — the field is required, but its value is wrong.
                    if is_mandatory_status(&field.ahb_status) && is_field_present(ctx, field) {
                        report.add_issue(
                            ValidationIssue::new(
                                Severity::Error,
                                IssueKind::FieldConditionNotSatisfied {
                                    field_name: field.name.clone(),
                                },
                            )
                            .with_field_path(&field.segment_path)
                            .with_rule(&field.ahb_status),
                        );
                    }
                }
                ConditionResult::Unknown => {
                    // Partition unknown IDs into three categories:
                    // 1. External: require an external provider (business context)
                    // 2. Undetermined: implemented but returned Unknown (data not present)
                    // 3. Missing: not implemented in evaluator at all
                    let mut external_ids = Vec::new();
                    let mut undetermined_ids = Vec::new();
                    let mut missing_ids = Vec::new();
                    for id in unknown_ids {
                        if self.evaluator.is_external(id) {
                            external_ids.push(id);
                        } else if self.evaluator.is_known(id) {
                            undetermined_ids.push(id);
                        } else {
                            missing_ids.push(id);
                        }
                    }

                    report.add_issue(
                        ValidationIssue::new(
                            Severity::Info,
                            IssueKind::ConditionUnknown {
                                field_name: field.name.clone(),
                                unresolved: UnresolvedConditions {
                                    external: external_ids,
                                    undetermined: undetermined_ids,
                                    missing: missing_ids,
                                },
                            },
                        )
                        .with_field_path(&field.segment_path)
                        .with_rule(&field.ahb_status),
                    );
                }
            }
        }

        // Cross-field code validation: aggregate allowed codes across all field
        // rules sharing the same segment path, then check each segment instance
        // against the combined set. This avoids false positives from per-field
        // validation (e.g., NAD/3035 with [MS] for sender and [MR] for receiver).
        self.validate_codes_cross_field(workflow, ctx, report);

        // Package cardinality post-processing: check that the count of codes
        // present from each package group falls within [min..max] bounds.
        self.validate_package_cardinality(workflow, ctx, report);
    }

    /// Validate package cardinality constraints across all field rules.
    ///
    /// Scans each code's `ahb_status` for `[NP_min..max]` package references,
    /// groups codes by `(segment_path, package_id)`, counts how many of the
    /// package's codes are actually present in the segment, and emits AHB006
    /// if the count falls outside `[min..max]`.
    fn validate_package_cardinality(
        &self,
        workflow: &AhbWorkflow,
        ctx: &EvaluationContext,
        report: &mut ValidationReport,
    ) {
        // Collect package groups: (segment_path, package_id) -> (min, max, Vec<code_value>)
        // Also store (element_index, component_index) for looking up the value in the segment.
        struct PackageGroup {
            min: u32,
            max: u32,
            code_values: Vec<String>,
            element_index: usize,
            component_index: usize,
        }

        // Key: (segment_path, mig_number, package_id).
        //
        // `mig_number` scopes the package to a specific MIG segment variant.
        // Example: in MSCONS SG10, STS+Z32 and STS+Z40 are separate variants
        // that both declare `[4P0..1]` on component 9013, but they refer to
        // disjoint packages (Z32's Statusanlaß codes vs Z40's). Without the
        // mig_number key, both variants' codes merge into one "super-package"
        // and any real message using both STS types fails cardinality.
        let mut groups: HashMap<(String, Option<String>, u32), PackageGroup> = HashMap::new();

        let expr_eval = ConditionExprEvaluator::new(&self.evaluator);

        for field in &workflow.fields {
            let el_idx = field.element_index.unwrap_or(0);
            let comp_idx = field.component_index.unwrap_or(0);

            // Skip package codes whose parent group condition is False or Unknown.
            if should_skip_for_parent_group(field, &expr_eval, ctx, &workflow.ub_definitions) {
                continue;
            }

            for code in &field.codes {
                // Parse the code's ahb_status for Package nodes
                if let Ok(Some(expr)) = ConditionParser::parse(&code.ahb_status) {
                    // Walk the AST to find Package nodes
                    let mut packages = Vec::new();
                    collect_packages(&expr, &mut packages);

                    for (pkg_id, pkg_min, pkg_max) in packages {
                        let key = (field.segment_path.clone(), field.mig_number.clone(), pkg_id);
                        let group = groups.entry(key).or_insert_with(|| PackageGroup {
                            min: pkg_min,
                            max: pkg_max,
                            code_values: Vec::new(),
                            element_index: el_idx,
                            component_index: comp_idx,
                        });
                        // Update min/max in case different codes specify different bounds
                        // (should be the same, but take the intersection to be safe)
                        group.min = group.min.max(pkg_min);
                        group.max = group.max.min(pkg_max);
                        group.code_values.push(code.value.clone());
                    }
                }
            }
        }

        // For each package group, count present codes and check bounds.
        //
        // Package cardinality like `[4P0..1]` limits the number of codes that
        // may appear *within a single group instance*, not message-wide. When
        // a navigator is available and the field has a group path, iterate
        // per-instance and check each independently; otherwise fall back to
        // the message-wide count (used by flat-segment test fixtures).
        for ((seg_path, mig_number, pkg_id), group) in &groups {
            let segment_id = extract_segment_id(seg_path);

            // Deduplicate code values: the synthetic workflow built from a
            // validated tree duplicates rules once per matched node, which
            // otherwise inflates the error message's code list.
            let mut unique_codes: Vec<&str> =
                group.code_values.iter().map(|s| s.as_str()).collect();
            unique_codes.sort_unstable();
            unique_codes.dedup();
            let code_set: HashSet<&str> = unique_codes.iter().copied().collect();

            let group_path_str = extract_group_path_key(seg_path);
            let group_path: Vec<&str> = if group_path_str.is_empty() {
                Vec::new()
            } else {
                group_path_str.split('/').collect()
            };

            let min = group.min as usize;
            let max = group.max as usize;

            let per_instance_counts: Option<Vec<usize>> =
                match (ctx.navigator, group_path.is_empty()) {
                    (Some(nav), false) => {
                        let instance_count = nav.group_instance_count(&group_path);
                        if instance_count == 0 {
                            None
                        } else {
                            // Restrict the check to instances whose variant
                            // declares the rule's mig_number. Without this, a
                            // rule from one SG variant (e.g. PID 55218 SEQ
                            // mig=00171 for sg8_z45_z84) is counted against
                            // sibling variants (sg8_z01 with SEQ mig=00115)
                            // and fires "0 codes present" on those. Rules
                            // with no mig_number stay unscoped.
                            Some(
                                (0..instance_count)
                                    .filter(|i| match mig_number.as_deref() {
                                        Some(m) => nav.instance_has_mig_number(&group_path, *i, m),
                                        None => true,
                                    })
                                    .map(|i| {
                                        nav.find_segments_in_group(&segment_id, &group_path, i)
                                            .iter()
                                            .filter_map(|seg| {
                                                seg.elements
                                                    .get(group.element_index)
                                                    .and_then(|e| e.get(group.component_index))
                                                    .filter(|v| !v.is_empty())
                                                    .cloned()
                                            })
                                            .filter(|v| code_set.contains(v.as_str()))
                                            .count()
                                    })
                                    .collect(),
                            )
                        }
                    }
                    _ => None,
                };

            let counts: Vec<usize> = per_instance_counts.unwrap_or_else(|| {
                let segments = ctx.find_segments(&segment_id);
                let count = segments
                    .iter()
                    .filter_map(|seg| {
                        seg.elements
                            .get(group.element_index)
                            .and_then(|e| e.get(group.component_index))
                            .filter(|v| !v.is_empty())
                            .map(|s| s.as_str())
                    })
                    .filter(|v| code_set.contains(v))
                    .count();
                vec![count]
            });

            // Emit one issue per out-of-bounds instance. Dedup by count so a
            // single message-wide overflow doesn't produce N copies of the
            // same error for repeated groups.
            let mut reported_counts: HashSet<usize> = HashSet::new();
            for present_count in counts {
                if (present_count < min || present_count > max)
                    && reported_counts.insert(present_count)
                {
                    report.add_issue(
                        ValidationIssue::new(
                            Severity::Error,
                            IssueKind::PackageCardinality {
                                package_id: pkg_id.to_string(),
                                present: present_count,
                                min,
                                max,
                                codes: unique_codes.iter().map(|s| s.to_string()).collect(),
                            },
                        )
                        .with_field_path(seg_path)
                        .with_expected(format!("{}..{}", group.min, group.max))
                        .with_actual(present_count.to_string()),
                    );
                }
            }
        }
    }

    /// Validate qualifier codes by aggregating allowed values across field rules.
    ///
    /// When a group navigator is available, codes are grouped by segment path
    /// (e.g., `SG2/NAD/3035` → `{MS, MR}`) and segments are looked up within
    /// the specific group, giving precise per-group validation.
    ///
    /// Without a navigator, falls back to grouping by segment tag and unioning
    /// all codes across groups to avoid cross-group false positives.
    ///
    /// Only validates simple qualifier paths (`[SG/]*/SEG/ELEMENT`) where the
    /// code is in `element[0][0]`. Composite paths are skipped.
    fn validate_codes_cross_field(
        &self,
        workflow: &AhbWorkflow,
        ctx: &EvaluationContext,
        report: &mut ValidationReport,
    ) {
        if ctx.navigator.is_some() {
            self.validate_codes_group_scoped(workflow, ctx, report);
        } else {
            self.validate_codes_tag_scoped(workflow, ctx, report);
        }
    }

    /// Group-scoped code validation: group codes by path, use navigator to
    /// find segments within each group, check against that group's codes only.
    fn validate_codes_group_scoped(
        &self,
        workflow: &AhbWorkflow,
        ctx: &EvaluationContext,
        report: &mut ValidationReport,
    ) {
        let by_loc = partition_codes_by_mig(workflow);
        let known_qualifiers = global_qualifiers_by_tag(&by_loc);
        let nav = ctx.navigator.unwrap();

        for ((group_key, tag), migs) in &by_loc {
            let field_path = if group_key.is_empty() {
                format!("{tag}/qualifier")
            } else {
                format!("{group_key}/{tag}/qualifier")
            };

            let group_path: Vec<&str> = if group_key.is_empty() {
                Vec::new()
            } else {
                group_key.split('/').collect()
            };

            let tag_qualifiers = known_qualifiers.get(tag);

            if group_path.is_empty() {
                Self::validate_segments_per_mig(
                    &ctx.find_segments(tag),
                    migs,
                    tag_qualifiers,
                    tag,
                    &field_path,
                    report,
                );
            } else {
                let instance_count = nav.group_instance_count(&group_path);
                for i in 0..instance_count {
                    let owned = nav.find_segments_in_group(tag, &group_path, i);
                    let refs: Vec<&OwnedSegment> = owned.iter().collect();
                    Self::validate_segments_per_mig(
                        &refs,
                        migs,
                        tag_qualifiers,
                        tag,
                        &field_path,
                        report,
                    );
                }
            }
        }
    }

    /// Fallback: no navigator — validate segments flat by tag. Still partitions
    /// codes by mig_number so segments are checked only against codes from their
    /// matching mig.
    fn validate_codes_tag_scoped(
        &self,
        workflow: &AhbWorkflow,
        ctx: &EvaluationContext,
        report: &mut ValidationReport,
    ) {
        let by_loc = partition_codes_by_mig(workflow);
        let known_qualifiers = global_qualifiers_by_tag(&by_loc);
        // Merge entries that share a tag (tag-scoped ignores group_key).
        let mut by_tag: HashMap<String, HashMap<Option<String>, MigCodeBucket>> = HashMap::new();
        for ((_group_key, tag), migs) in by_loc {
            let merged = by_tag.entry(tag).or_default();
            for (mig_key, bucket) in migs {
                let entry = merged.entry(mig_key).or_default();
                if entry.qualifier_position.is_none() {
                    entry.qualifier_position = bucket.qualifier_position;
                }
                if entry.qualifier_position == bucket.qualifier_position {
                    entry.qualifier_values.extend(&bucket.qualifier_values);
                }
                for (pos, codes) in bucket.codes {
                    entry.codes.entry(pos).or_default().extend(codes);
                }
            }
        }

        for (tag, migs) in &by_tag {
            let field_path = format!("{tag}/qualifier");
            Self::validate_segments_per_mig(
                &ctx.find_segments(tag),
                migs,
                known_qualifiers.get(tag),
                tag,
                &field_path,
                report,
            );
        }
    }

    /// For each segment, match it to a mig_number via its primary qualifier and
    /// validate only that mig's code constraints.
    ///
    /// `tag_qualifiers` is the set of all qualifier values this tag uses anywhere
    /// in the workflow, keyed by position. When no mig at the current location
    /// matches a segment, but the segment's qualifier IS valid somewhere else for
    /// this tag, we skip it (the segment belongs to another location that's
    /// handled separately). Only truly unknown qualifier values are flagged.
    fn validate_segments_per_mig(
        segments: &[&OwnedSegment],
        migs: &HashMap<Option<String>, MigCodeBucket>,
        tag_qualifiers: Option<&HashMap<(usize, usize), HashSet<String>>>,
        tag: &str,
        field_path: &str,
        report: &mut ValidationReport,
    ) {
        for seg in segments {
            match match_segment_to_mig(seg, migs) {
                Some(bucket) => {
                    for ((el, c), allowed) in &bucket.codes {
                        if allowed.is_empty() {
                            continue;
                        }
                        Self::check_segments_against_codes(
                            vec![*seg],
                            allowed,
                            tag,
                            *el,
                            *c,
                            field_path,
                            report,
                        );
                    }
                }
                None => {
                    let Some(qualifiers) = tag_qualifiers else {
                        continue;
                    };
                    // Find a qualifier position where this segment has a value.
                    // If the value matches any known qualifier for this tag (at any
                    // location), the segment belongs elsewhere — skip. Otherwise
                    // report an invalid qualifier against the union at this position.
                    for ((el, c), allowed) in qualifiers {
                        let Some(actual) = seg
                            .elements
                            .get(*el)
                            .and_then(|e| e.get(*c))
                            .filter(|v| !v.is_empty())
                            .map(|s| s.as_str())
                        else {
                            continue;
                        };
                        if allowed.iter().any(|v| v == actual) {
                            // Qualifier is valid at some location — skip here.
                            break;
                        }
                        // Truly unknown qualifier value — report against this
                        // location's bucket union if it has one.
                        let bucket_values: HashSet<&str> = migs
                            .values()
                            .filter(|b| b.qualifier_position == Some((*el, *c)))
                            .flat_map(|b| b.qualifier_values.iter().copied())
                            .collect();
                        if !bucket_values.is_empty() {
                            Self::check_segments_against_codes(
                                vec![*seg],
                                &bucket_values,
                                tag,
                                *el,
                                *c,
                                field_path,
                                report,
                            );
                            break;
                        }
                    }
                }
            }
        }
    }

    /// Check a list of segments' qualifier at the given element/component index against allowed codes.
    fn check_segments_against_codes(
        segments: Vec<&OwnedSegment>,
        allowed_codes: &HashSet<&str>,
        _tag: &str,
        el_idx: usize,
        comp_idx: usize,
        field_path: &str,
        report: &mut ValidationReport,
    ) {
        for segment in segments {
            if let Some(code_value) = segment
                .elements
                .get(el_idx)
                .and_then(|e| e.get(comp_idx))
                .filter(|v| !v.is_empty())
            {
                if !allowed_codes.contains(code_value.as_str()) {
                    let mut sorted_codes: Vec<&str> = allowed_codes.iter().copied().collect();
                    sorted_codes.sort_unstable();
                    let kind = IssueKind::CodeNotAllowedForPid {
                        value: code_value.to_string(),
                        allowed: sorted_codes.iter().map(|s| (*s).to_string()).collect(),
                    };
                    report.add_issue(
                        ValidationIssue::new(Severity::Error, kind)
                            .with_field_path(field_path)
                            .with_actual(code_value)
                            .with_expected(sorted_codes.join(", ")),
                    );
                }
            }
        }
    }
}

/// Check if the parent group's conditional status evaluates to False or Unknown.
///
/// Returns `true` if the field should be skipped (parent group condition not met).
/// Only evaluates when `parent_group_ahb_status` contains condition brackets `[`.
/// Simple statuses like "Kann" or "Muss" pass through (return `false`).
fn should_skip_for_parent_group<E: ConditionEvaluator>(
    field: &AhbFieldRule,
    expr_eval: &ConditionExprEvaluator<E>,
    ctx: &EvaluationContext,
    ub_definitions: &BTreeMap<String, ConditionExpr>,
) -> bool {
    if let Some(ref group_status) = field.parent_group_ahb_status {
        if group_status.contains('[') {
            let result = expr_eval.evaluate_status_with_ub(group_status, ctx, ub_definitions);
            return matches!(result, ConditionResult::False | ConditionResult::Unknown);
        }
    }
    false
}

/// Check if a field's required segment instance is present.
///
/// For fields with qualifier codes (e.g., `SG2/NAD/3035` with `[MR]`),
/// checks that a segment with one of those qualifier values exists.
/// Otherwise just checks that any segment with the tag is present.
///
/// This prevents false negatives where `NAD+MS` is present but the
/// validator incorrectly says NAD "exists" when `NAD+MR` is missing.
fn is_field_present(ctx: &EvaluationContext, field: &AhbFieldRule) -> bool {
    let segment_id = extract_segment_id(&field.segment_path);

    // When a field has known codes, check for a segment containing one of those
    // specific values at the right element/component position. This applies to both
    // simple qualifier paths (NAD/3035) and composite paths (CCI/C240/7037) —
    // without this, a CCI segment from a different group variant (e.g., CCI+Z61)
    // would falsely satisfy the check for CCI with C240/7037 codes Z15/Z18.
    if !field.codes.is_empty() {
        if let (Some(el_idx), Some(comp_idx)) = (field.element_index, field.component_index) {
            let required_codes: Vec<&str> = field.codes.iter().map(|c| c.value.as_str()).collect();
            let matching = ctx.find_segments(&segment_id);
            return matching.iter().any(|seg| {
                seg.elements
                    .get(el_idx)
                    .and_then(|e| e.get(comp_idx))
                    .is_some_and(|v| required_codes.contains(&v.as_str()))
            });
        }
        // Fallback for fields with codes but no element/component indices:
        // use simple qualifier check if it's a qualifier-style path.
        if is_qualifier_field(&field.segment_path) {
            let required_codes: Vec<&str> = field.codes.iter().map(|c| c.value.as_str()).collect();
            let el_idx = field.element_index.unwrap_or(0);
            let comp_idx = field.component_index.unwrap_or(0);
            let matching = ctx.find_segments(&segment_id);
            return matching.iter().any(|seg| {
                seg.elements
                    .get(el_idx)
                    .and_then(|e| e.get(comp_idx))
                    .is_some_and(|v| required_codes.contains(&v.as_str()))
            });
        }
    }

    ctx.has_segment(&segment_id)
}

/// Check if the group variant for a field is absent from the message.
///
/// Uses tree-based logic:
/// 1. **Group entirely absent**: If the group path has 0 instances, the
///    whole group is absent and its children aren't required.
/// 2. **Optional group variant absent**: If the parent group is optional
///    ("Kann") and the specific qualifier variant isn't present, the variant
///    is absent. E.g., SG5 "Kann" with LOC+Z17 — if no SG5 instance has
///    LOC+Z17, all fields under that variant are skipped.
///
/// Returns `false` (not absent) when:
/// - The field has no group prefix (e.g., `NAD/3035`)
/// - No navigator is available (can't determine group presence)
/// - The parent group is mandatory and has instances
fn is_group_variant_absent(ctx: &EvaluationContext, field: &AhbFieldRule) -> bool {
    let group_path: Vec<&str> = field
        .segment_path
        .split('/')
        .take_while(|p| p.starts_with("SG"))
        .collect();

    if group_path.is_empty() {
        return false;
    }

    let nav = match ctx.navigator {
        Some(nav) => nav,
        None => return false,
    };

    let instance_count = nav.group_instance_count(&group_path);

    // Case 1: group entirely absent — only skip if the group is NOT mandatory.
    // When a mandatory group (parent_group_ahb_status contains "Muss" or "X")
    // has 0 instances, the group's absence is itself the error, so we should
    // NOT skip field validation — let the field-level check report the missing field.
    if instance_count == 0 {
        let is_group_mandatory = field
            .parent_group_ahb_status
            .as_deref()
            .is_some_and(is_mandatory_status);
        if !is_group_mandatory {
            return true;
        }
        // Mandatory group with 0 instances → don't suppress field errors
        return false;
    }

    // Case 2: group has instances, but the specific qualifier variant may be absent.
    // Only applies when the parent group is optional ("Kann") — mandatory groups
    // ("Muss", "X") require all their qualifier variants to be present.
    if let Some(ref group_status) = field.parent_group_ahb_status {
        if !is_mandatory_status(group_status) && !group_status.contains('[') {
            // Parent group is unconditionally optional (e.g., "Kann").
            // Check if the field's qualifier variant is present in any instance.
            if !field.codes.is_empty() && is_qualifier_field(&field.segment_path) {
                let segment_id = extract_segment_id(&field.segment_path);
                let required_codes: Vec<&str> =
                    field.codes.iter().map(|c| c.value.as_str()).collect();

                let any_instance_has_qualifier = (0..instance_count).any(|i| {
                    nav.find_segments_in_group(&segment_id, &group_path, i)
                        .iter()
                        .any(|seg| {
                            seg.elements
                                .first()
                                .and_then(|e| e.first())
                                .is_some_and(|v| required_codes.contains(&v.as_str()))
                        })
                });

                if !any_instance_has_qualifier {
                    return true; // optional group variant absent
                }
            }
        }
    }

    // Case 3: non-entry segment absent from all group instances.
    // E.g., SG10 has QTY (entry) + optional STS segments. If no STS appears
    // in any SG10 instance but the entry segment (QTY) is present, fields
    // under STS are not required.
    //
    // We check `has_any_segment_in_group` to confirm the group instance is
    // genuinely populated (proving our target segment is a non-entry optional
    // one) vs a navigator that simply can't resolve segments.
    let segment_id = extract_segment_id(&field.segment_path);
    let segment_absent_from_all = (0..instance_count).all(|i| {
        nav.find_segments_in_group(&segment_id, &group_path, i)
            .is_empty()
    });
    if segment_absent_from_all {
        let group_has_other_segments =
            (0..instance_count).any(|i| nav.has_any_segment_in_group(&group_path, i));
        if group_has_other_segments {
            return true;
        }
    }

    false
}

/// Recursively collect all AhbNodes from a group node in depth-first order.
fn collect_nodes_depth_first<'a, 'b>(group: &'b AhbGroupNode<'a>, out: &mut Vec<&'b AhbNode<'a>>) {
    out.extend(group.fields.iter());
    for child in &group.children {
        collect_nodes_depth_first(child, out);
    }
}

/// Evaluate a single `AhbNode` with the given (possibly scoped) context,
/// emitting AHB001/AHB003/AHB005 issues as appropriate. When `instance_index`
/// is `Some`, errors are tagged with it via `with_instance_index`.
#[allow(clippy::too_many_arguments)]
fn evaluate_node<E: ConditionEvaluator>(
    node: &AhbNode,
    ctx: &EvaluationContext,
    expr_eval: &ConditionExprEvaluator<E>,
    evaluator: &E,
    ub_definitions: &BTreeMap<String, ConditionExpr>,
    tag_migs: &HashMap<String, HashSet<&str>>,
    instance_index: Option<usize>,
    report: &mut ValidationReport,
) {
    let field = node.rule;

    // Create a field-scoped context with resolved value from the tree node.
    let node_ctx = ctx.with_resolved(node.value, node.segment_elements);

    // Skip if parent group condition is not met (False or Unknown).
    if should_skip_for_parent_group(field, expr_eval, ctx, ub_definitions) {
        return;
    }

    // Evaluate the field's AHB status condition using the node context
    // (WITH resolved_value set).
    let (condition_result, unknown_ids) =
        expr_eval.evaluate_status_detailed_with_ub(&field.ahb_status, &node_ctx, ub_definitions);

    match condition_result {
        ConditionResult::True => {
            // Condition is met -- field is required/applicable.
            //
            // Normally rely on the tree's resolved value. The exception:
            // if assembly didn't claim the segment at all (value AND
            // segment_elements both absent) AND the tag has exactly one
            // mig variant in this PID, a flat-segment hit means the
            // segment IS present and assembly just failed to pick it up.
            // Don't double-report — structure diagnostics already warn.
            if is_mandatory_status(&field.ahb_status) && node.value.is_none() {
                let tag = extract_segment_id(&field.segment_path);
                let single_variant_present = node.segment_elements.is_none()
                    && tag_migs.get(&tag).is_some_and(|ms| ms.len() == 1)
                    && is_field_present(ctx, field);
                // Suppress missing-field errors when the containing segment
                // is optional (Kann/Soll) and absent from the instance.
                // "X" on a Kann segment's sub-element means "required IF
                // segment present"; the segment's absence is legal.
                let segment_optional_and_absent = node.segment_elements.is_none()
                    && field
                        .segment_ahb_status
                        .as_deref()
                        .is_some_and(is_optional_segment_status);
                if !single_variant_present && !segment_optional_and_absent {
                    let mut issue = ValidationIssue::new(
                        Severity::Error,
                        IssueKind::MissingRequiredField {
                            field_name: field.name.clone(),
                        },
                    )
                    .with_field_path(&field.segment_path)
                    .with_rule(&field.ahb_status);
                    if let Some(first_code) = field.codes.first() {
                        issue.expected_value = Some(first_code.value.clone());
                    }
                    if let Some(idx) = instance_index {
                        issue = issue.with_instance_index(idx);
                    }
                    if let Some(num) = node.matched_segment_number {
                        issue = issue.with_position(crate::SegmentPosition {
                            segment_number: num,
                            byte_offset: 0,
                            message_number: 1,
                        });
                    }
                    issue = attach_field_position(issue, field);
                    report.add_issue(issue);
                }
            }
        }
        ConditionResult::False => {
            // Condition not met. If mandatory AND value is present,
            // the value violates the condition constraint.
            if is_mandatory_status(&field.ahb_status) && node.value.is_some() {
                let mut issue = ValidationIssue::new(
                    Severity::Error,
                    IssueKind::FieldConditionNotSatisfied {
                        field_name: field.name.clone(),
                    },
                )
                .with_field_path(&field.segment_path)
                .with_rule(&field.ahb_status);
                if let Some(idx) = instance_index {
                    issue = issue.with_instance_index(idx);
                }
                if let Some(num) = node.matched_segment_number {
                    issue = issue.with_position(crate::SegmentPosition {
                        segment_number: num,
                        byte_offset: 0,
                        message_number: 1,
                    });
                }
                issue = attach_field_position(issue, field);
                report.add_issue(issue);
            }
        }
        ConditionResult::Unknown => {
            // Partition unknown IDs into external / undetermined / missing.
            let mut external_ids = Vec::new();
            let mut undetermined_ids = Vec::new();
            let mut missing_ids = Vec::new();
            for id in unknown_ids {
                if evaluator.is_external(id) {
                    external_ids.push(id);
                } else if evaluator.is_known(id) {
                    undetermined_ids.push(id);
                } else {
                    missing_ids.push(id);
                }
            }

            let mut issue = ValidationIssue::new(
                Severity::Info,
                IssueKind::ConditionUnknown {
                    field_name: field.name.clone(),
                    unresolved: UnresolvedConditions {
                        external: external_ids,
                        undetermined: undetermined_ids,
                        missing: missing_ids,
                    },
                },
            )
            .with_field_path(&field.segment_path)
            .with_rule(&field.ahb_status);
            if let Some(idx) = instance_index {
                issue = issue.with_instance_index(idx);
            }
            if let Some(num) = node.matched_segment_number {
                issue = issue.with_position(crate::SegmentPosition {
                    segment_number: num,
                    byte_offset: 0,
                    message_number: 1,
                });
            }
            issue = attach_field_position(issue, field);
            report.add_issue(issue);
        }
    }
}

/// Attach UCD `S011` position info derived from the AHB field rule's
/// `element_index` / `component_index`. Both are 0-based array indices
/// in the parsed segment; CONTRL DE0098 / DE0104 are 1-based and
/// DE0098 counts the segment identifier as position 1.
fn attach_field_position(issue: ValidationIssue, field: &AhbFieldRule) -> ValidationIssue {
    match field.element_index {
        Some(el) => {
            let element_pos = (el as u32) + 2;
            let component_pos = field.component_index.map(|c| (c as u32) + 1);
            issue.with_field_position(element_pos, component_pos)
        }
        None => issue,
    }
}

/// Recursively walk a group instance (and its children) evaluating every
/// `AhbNode` with the same scoped context. Child groups inherit the parent's
/// scope for this initial implementation — deeper nested scoping (computing
/// a child's own instance_index among siblings within the parent) can be
/// added later if conditions actually differentiate on nested SGx.
// TODO(path-c-nested): when an AHB condition references "in dieser SG10"
// (nested within SG8), we'd need to compute SG10's own instance_index
// among its siblings under the current SG8 and push a deeper GroupScope
// path like ["SG4", "SG8", "SG10"]. No condition in the current UTILMD
// codegen drives on nested SGx scope directly, so this is YAGNI for now.
#[allow(clippy::too_many_arguments)]
fn walk_group_instance<E: ConditionEvaluator>(
    group: &AhbGroupNode,
    scoped_ctx: &EvaluationContext,
    expr_eval: &ConditionExprEvaluator<E>,
    evaluator: &E,
    ub_definitions: &BTreeMap<String, ConditionExpr>,
    tag_migs: &HashMap<String, HashSet<&str>>,
    instance_index: usize,
    report: &mut ValidationReport,
) {
    for node in &group.fields {
        evaluate_node(
            node,
            scoped_ctx,
            expr_eval,
            evaluator,
            ub_definitions,
            tag_migs,
            Some(instance_index),
            report,
        );
    }
    for child in &group.children {
        walk_group_instance(
            child,
            scoped_ctx,
            expr_eval,
            evaluator,
            ub_definitions,
            tag_migs,
            instance_index,
            report,
        );
    }
}

/// Recursively collect all Package nodes from a condition expression tree.
fn collect_packages(expr: &ConditionExpr, out: &mut Vec<(u32, u32, u32)>) {
    match expr {
        ConditionExpr::Package { id, min, max } => {
            out.push((*id, *min, *max));
        }
        ConditionExpr::And(exprs) | ConditionExpr::Or(exprs) => {
            for e in exprs {
                collect_packages(e, out);
            }
        }
        ConditionExpr::Xor(left, right) => {
            collect_packages(left, out);
            collect_packages(right, out);
        }
        ConditionExpr::Not(inner) => {
            collect_packages(inner, out);
        }
        ConditionExpr::Ref(_) => {}
    }
}

/// Check if an AHB status is mandatory (Muss or X prefix).
fn is_mandatory_status(status: &str) -> bool {
    let trimmed = status.trim();
    trimmed.starts_with("Muss") || trimmed.starts_with('X')
}

/// Check if a segment-level AHB status indicates an optional segment.
///
/// "Kann" / "Kann [x]" — always optional: absence is legal.
/// "Soll" / "Soll [x]" — should-be: absence is tolerated (not an error).
/// "Muss" (with or without conditions) — required; absence must be reported.
///
/// Used to suppress AHB001 missing-field errors on sub-elements of a segment
/// that is both optional at segment-level and absent from the assembled
/// instance: "X" on such a sub-element means "required IF segment present".
fn is_optional_segment_status(status: &str) -> bool {
    let trimmed = status.trim();
    trimmed.starts_with("Kann") || trimmed.starts_with("Soll")
}

/// Check if a field path points to a simple qualifier element (element[0] of the segment).
///
/// Returns `true` for paths like `[SG/]*/SEG/ELEMENT` where the data element is
/// directly under the segment (no composite wrapper). These fields have their code
/// in `element[0][0]` and can be validated.
///
/// Also accepts composite paths like `SEG/COMPOSITE/ELEMENT` (e.g., `STS/C556/9013`).
/// The `element_index` and `component_index` on the field rule carry the exact
/// position, so composites can be checked just like simple elements.
fn is_qualifier_field(path: &str) -> bool {
    let parts: Vec<&str> = path.split('/').filter(|p| !p.starts_with("SG")).collect();
    // [SEG, ELEMENT] for simple data elements; [SEG, COMPOSITE, ELEMENT] for composites.
    matches!(parts.len(), 2 | 3)
}

/// Per-mig code constraints at one (group_key, tag) location.
///
/// A bucket represents one mig_number (or the `None` bucket when rules lack
/// mig numbers). Each bucket tracks its qualifier position and the set of
/// valid qualifier values there, so multiple single-code rules under the same
/// mig key (e.g. two distinct NAD qualifiers both under mig=None in a test
/// fixture) all contribute as valid qualifier matches.
#[derive(Default)]
struct MigCodeBucket<'a> {
    /// The position (element_index, component_index) treated as the discriminator
    /// for this bucket — the first single-code required field seen in the workflow.
    qualifier_position: Option<(usize, usize)>,
    /// Valid qualifier values at `qualifier_position`. Empty if no single-code
    /// required field exists for this bucket.
    qualifier_values: HashSet<&'a str>,
    /// Allowed codes for this bucket, keyed by `(element_index, component_index)`.
    /// Includes the qualifier position itself.
    codes: HashMap<(usize, usize), HashSet<&'a str>>,
}

/// Partition workflow code rules by `(group_key, tag, mig_number)`. Without this
/// split, codes from multiple migs sharing a tag (e.g. STS+7 mig 00035 and
/// STS+E01 mig 00036 in PID 55018) get unioned and every segment is checked
/// against codes that only apply to one mig.
fn partition_codes_by_mig(
    workflow: &AhbWorkflow,
) -> HashMap<(String, String), HashMap<Option<String>, MigCodeBucket<'_>>> {
    let mut out: HashMap<(String, String), HashMap<Option<String>, MigCodeBucket>> = HashMap::new();
    for field in &workflow.fields {
        if field.codes.is_empty() || !is_qualifier_field(&field.segment_path) {
            continue;
        }
        let tag = extract_segment_id(&field.segment_path);
        let group_key = extract_group_path_key(&field.segment_path);
        let mig = field.mig_number.clone();
        let el = field.element_index.unwrap_or(0);
        let c = field.component_index.unwrap_or(0);

        let bucket = out
            .entry((group_key, tag))
            .or_default()
            .entry(mig)
            .or_default();

        // A code is "allowed for this PID" whenever its AHB status declares it
        // usable — whether unconditionally (`X`, `Muss`) or under a condition
        // (`X [35]`, `X [35] ∨ ([32] ∧ [77])`). Matching only the exact string
        // `"X"` drops every conditionally-allowed code, causing COD002 false
        // positives on fields like MSCONS QTY 6063 (220 unconditional, 67/Z18
        // conditional).
        let required: Vec<&str> = field
            .codes
            .iter()
            .filter(|code| code.ahb_status.starts_with('X') || code.ahb_status.starts_with("Muss"))
            .map(|code| code.value.as_str())
            .collect();

        // The first code-bearing field locks in the qualifier position; any
        // further required codes at that position contribute additional valid
        // qualifier values. A bucket whose entry qualifier permits multiple
        // codes (e.g. PID 55035 SG8/RFF mig=00075 allows {Z31, Z39}) must be
        // matchable by any of them — without this, segments with Z39 fall
        // through to the union-of-other-migs path and produce a false COD002.
        if !required.is_empty() {
            if bucket.qualifier_position.is_none() {
                bucket.qualifier_position = Some((el, c));
            }
            if bucket.qualifier_position == Some((el, c)) {
                bucket.qualifier_values.extend(required.iter().copied());
            }
        }

        for v in required {
            bucket.codes.entry((el, c)).or_default().insert(v);
        }
    }
    out
}

/// For each tag, collect every qualifier value used anywhere in the workflow,
/// keyed by qualifier position. This lets code validation distinguish "segment
/// has an unknown qualifier value" (truly invalid — report) from "segment has
/// a valid qualifier used at a different location than the current bucket"
/// (belongs elsewhere — skip at this location).
fn global_qualifiers_by_tag(
    by_loc: &HashMap<(String, String), HashMap<Option<String>, MigCodeBucket<'_>>>,
) -> HashMap<String, HashMap<(usize, usize), HashSet<String>>> {
    let mut out: HashMap<String, HashMap<(usize, usize), HashSet<String>>> = HashMap::new();
    for ((_group, tag), migs) in by_loc {
        let tag_entry = out.entry(tag.clone()).or_default();
        for bucket in migs.values() {
            if let Some(pos) = bucket.qualifier_position {
                tag_entry
                    .entry(pos)
                    .or_default()
                    .extend(bucket.qualifier_values.iter().map(|s| s.to_string()));
            }
        }
    }
    out
}

/// Find the bucket that best matches this segment.
///
/// A bucket is a candidate if its `qualifier_values` contain the segment's
/// value at `qualifier_position`. Among candidates, the one with the most
/// additional code positions matching the segment wins. This disambiguates
/// migs that share the same primary qualifier but differ on a secondary
/// code position (e.g. PID 55035 SG8/PIA variants all use 4347='5' but
/// differ on C212/7143={Z12} vs {SRW}).
///
/// Returns `None` if no bucket's qualifier matches the segment.
fn match_segment_to_mig<'a, 'b>(
    seg: &OwnedSegment,
    migs: &'a HashMap<Option<String>, MigCodeBucket<'b>>,
) -> Option<&'a MigCodeBucket<'b>> {
    let actual_at = |el: usize, c: usize| -> &str {
        seg.elements
            .get(el)
            .and_then(|e| e.get(c))
            .map(|s| s.as_str())
            .unwrap_or("")
    };

    let mut best: Option<&MigCodeBucket> = None;
    let mut best_matches = 0usize;

    for bucket in migs.values() {
        let Some((el, c)) = bucket.qualifier_position else {
            continue;
        };
        if !bucket.qualifier_values.contains(actual_at(el, c)) {
            continue;
        }
        let extra_matches = bucket
            .codes
            .iter()
            .filter(|(pos, _)| **pos != (el, c))
            .filter(|((e, k), allowed)| {
                let v = actual_at(*e, *k);
                !v.is_empty() && allowed.contains(v)
            })
            .count();
        if best.is_none() || extra_matches > best_matches {
            best = Some(bucket);
            best_matches = extra_matches;
        }
    }
    best
}

/// Extract the group path prefix from a field path.
///
/// `"SG2/NAD/3035"` → `"SG2"`, `"SG4/SG12/NAD/3035"` → `"SG4/SG12"`,
/// `"NAD/3035"` → `""` (no group prefix).
fn extract_group_path_key(path: &str) -> String {
    let sg_parts: Vec<&str> = path
        .split('/')
        .take_while(|p| p.starts_with("SG"))
        .collect();
    sg_parts.join("/")
}

/// Extract the segment ID from a field path like "SG2/NAD/C082/3039" -> "NAD".
fn extract_segment_id(path: &str) -> String {
    for part in path.split('/') {
        // Skip segment group identifiers and composite/element identifiers
        if part.starts_with("SG") || part.starts_with("C_") || part.starts_with("D_") {
            continue;
        }
        // Return first 3-letter uppercase segment identifier
        if part.len() >= 3
            && part
                .chars()
                .all(|c| c.is_ascii_uppercase() || c.is_ascii_digit())
        {
            return part.to_string();
        }
    }
    // Fallback: return the last part
    path.split('/').next_back().unwrap_or(path).to_string()
}

/// Validate that the UNT segment count matches the actual number of segments.
///
/// The UNT segment's first data element (D0074) declares the number of segments
/// in the message, counting from UNH to UNT inclusive. This function compares
/// that declared value against the actual segment count.
///
/// Pass per-message segments (from [`MessageChunk::message_segments()`] or
/// [`MessageChunk::all_segments()`]), not the full interchange. For multi-message
/// interchanges, call once per message.
///
/// Returns `Some(ValidationIssue)` if there's a mismatch, `None` if correct.
pub fn validate_unt_segment_count(segments: &[OwnedSegment]) -> Option<ValidationIssue> {
    // Reject multi-message input — counting would be incorrect.
    let unh_count = segments.iter().filter(|s| s.id == "UNH").count();
    if unh_count > 1 {
        return Some(ValidationIssue::new(
            Severity::Error,
            IssueKind::UntCountNotVerifiable { unh_count },
        ));
    }

    // Find the UNT segment
    let unt = segments.iter().rfind(|s| s.id == "UNT")?;
    let declared: usize = unt.get_element(0).parse().ok()?;

    // Count segments from UNH to UNT inclusive
    let actual = segments
        .iter()
        .filter(|s| s.id != "UNA" && s.id != "UNB" && s.id != "UNZ")
        .count();

    if declared != actual {
        Some(
            ValidationIssue::new(
                Severity::Error,
                IssueKind::UntSegmentCountMismatch { declared, actual },
            )
            .with_field_path("UNT/0074")
            .with_expected(actual.to_string())
            .with_actual(declared.to_string()),
        )
    } else {
        None
    }
}

#[cfg(test)]
mod tests {
    use super::super::codes::ErrorCodes;
    use super::super::issue::ValidationCategory;
    use super::*;
    use crate::display::{EdifactView, IssueNarrator, IssueView, TechnicalNarrator};
    use crate::eval::{ConditionResult as CR, NoOpExternalProvider};
    use std::collections::HashMap;

    /// Narrate an issue the way the EDIFACT view would, for assertions that
    /// used to read `.message` before Task 5 removed it.
    fn narrate(issue: &ValidationIssue) -> String {
        TechnicalNarrator.describe(issue, EdifactView.location(issue).as_deref())
    }

    /// Mock evaluator for testing the validator.
    struct MockEvaluator {
        results: HashMap<u32, CR>,
    }

    impl MockEvaluator {
        fn new(results: Vec<(u32, CR)>) -> Self {
            Self {
                results: results.into_iter().collect(),
            }
        }

        fn all_true(ids: &[u32]) -> Self {
            Self::new(ids.iter().map(|&id| (id, CR::True)).collect())
        }
    }

    impl ConditionEvaluator for MockEvaluator {
        fn evaluate(&self, condition: u32, _ctx: &EvaluationContext) -> CR {
            self.results.get(&condition).copied().unwrap_or(CR::Unknown)
        }
        fn is_external(&self, _condition: u32) -> bool {
            false
        }
        fn message_type(&self) -> &str {
            "UTILMD"
        }
        fn format_version(&self) -> &str {
            "FV2510"
        }
    }

    // === Helper function tests ===

    #[test]
    fn test_is_mandatory_status() {
        assert!(is_mandatory_status("Muss"));
        assert!(is_mandatory_status("Muss [182] ∧ [152]"));
        assert!(is_mandatory_status("X"));
        assert!(is_mandatory_status("X [567]"));
        assert!(!is_mandatory_status("Soll [1]"));
        assert!(!is_mandatory_status("Kann [1]"));
        assert!(!is_mandatory_status(""));
    }

    #[test]
    fn test_extract_segment_id_simple() {
        assert_eq!(extract_segment_id("NAD"), "NAD");
    }

    #[test]
    fn test_extract_segment_id_with_sg_prefix() {
        assert_eq!(extract_segment_id("SG2/NAD/C082/3039"), "NAD");
    }

    #[test]
    fn test_extract_segment_id_nested_sg() {
        assert_eq!(extract_segment_id("SG4/SG8/SEQ/C286/6350"), "SEQ");
    }

    // === Validator tests with mock data ===

    #[test]
    fn test_validate_missing_mandatory_field() {
        let evaluator = MockEvaluator::all_true(&[182, 152]);
        let validator = EdifactValidator::new(evaluator);
        let external = NoOpExternalProvider;

        let workflow = AhbWorkflow {
            pruefidentifikator: "11001".to_string(),
            description: "Test".to_string(),
            communication_direction: None,
            fields: vec![AhbFieldRule {
                segment_path: "SG2/NAD/C082/3039".to_string(),
                name: "MP-ID des MSB".to_string(),
                ahb_status: "Muss [182] ∧ [152]".to_string(),
                codes: vec![],
                parent_group_ahb_status: None,
                segment_ahb_status: None,
                ..Default::default()
            }],
            ub_definitions: BTreeMap::new(),
        };

        // Validate with no segments
        let report = validator.validate(&[], &workflow, &external, ValidationLevel::Conditions);

        // Should have an error for missing mandatory field
        assert!(!report.is_valid());
        let errors: Vec<_> = report.errors().collect();
        assert_eq!(errors.len(), 1);
        assert_eq!(errors[0].code(), ErrorCodes::MISSING_REQUIRED_FIELD);
        assert!(narrate(errors[0]).contains("MP-ID des MSB"));
    }

    #[test]
    fn test_validate_condition_false_no_error() {
        // When condition evaluates to False, field is not required
        let evaluator = MockEvaluator::new(vec![(182, CR::True), (152, CR::False)]);
        let validator = EdifactValidator::new(evaluator);
        let external = NoOpExternalProvider;

        let workflow = AhbWorkflow {
            pruefidentifikator: "11001".to_string(),
            description: "Test".to_string(),
            communication_direction: None,
            fields: vec![AhbFieldRule {
                segment_path: "NAD".to_string(),
                name: "Partnerrolle".to_string(),
                ahb_status: "Muss [182] ∧ [152]".to_string(),
                codes: vec![],
                parent_group_ahb_status: None,
                segment_ahb_status: None,
                ..Default::default()
            }],
            ub_definitions: BTreeMap::new(),
        };

        let report = validator.validate(&[], &workflow, &external, ValidationLevel::Conditions);

        // Condition is false, so field is not required - no error
        assert!(report.is_valid());
    }

    #[test]
    fn test_validate_condition_unknown_adds_info() {
        // When condition is Unknown, add an info-level note
        let evaluator = MockEvaluator::new(vec![(182, CR::True)]);
        // 152 is not registered -> Unknown
        let validator = EdifactValidator::new(evaluator);
        let external = NoOpExternalProvider;

        let workflow = AhbWorkflow {
            pruefidentifikator: "11001".to_string(),
            description: "Test".to_string(),
            communication_direction: None,
            fields: vec![AhbFieldRule {
                segment_path: "NAD".to_string(),
                name: "Partnerrolle".to_string(),
                ahb_status: "Muss [182] ∧ [152]".to_string(),
                codes: vec![],
                parent_group_ahb_status: None,
                segment_ahb_status: None,
                ..Default::default()
            }],
            ub_definitions: BTreeMap::new(),
        };

        let report = validator.validate(&[], &workflow, &external, ValidationLevel::Conditions);

        // Should be valid (Unknown is not an error) but have an info issue
        assert!(report.is_valid());
        let infos: Vec<_> = report.infos().collect();
        assert_eq!(infos.len(), 1);
        assert_eq!(infos[0].code(), ErrorCodes::CONDITION_UNKNOWN);
    }

    #[test]
    fn test_validate_structure_level_skips_conditions() {
        let evaluator = MockEvaluator::all_true(&[182, 152]);
        let validator = EdifactValidator::new(evaluator);
        let external = NoOpExternalProvider;

        let workflow = AhbWorkflow {
            pruefidentifikator: "11001".to_string(),
            description: "Test".to_string(),
            communication_direction: None,
            fields: vec![AhbFieldRule {
                segment_path: "NAD".to_string(),
                name: "Partnerrolle".to_string(),
                ahb_status: "Muss [182] ∧ [152]".to_string(),
                codes: vec![],
                parent_group_ahb_status: None,
                segment_ahb_status: None,
                ..Default::default()
            }],
            ub_definitions: BTreeMap::new(),
        };

        // With Structure level, conditions are not checked
        let report = validator.validate(&[], &workflow, &external, ValidationLevel::Structure);

        // No AHB errors because conditions were not evaluated
        assert!(report.is_valid());
        assert_eq!(report.by_category(ValidationCategory::Ahb).count(), 0);
    }

    #[test]
    fn test_validate_empty_workflow_no_condition_errors() {
        let evaluator = MockEvaluator::all_true(&[]);
        let validator = EdifactValidator::new(evaluator);
        let external = NoOpExternalProvider;

        let empty_workflow = AhbWorkflow {
            pruefidentifikator: String::new(),
            description: String::new(),
            communication_direction: None,
            fields: vec![],
            ub_definitions: BTreeMap::new(),
        };

        let report = validator.validate(&[], &empty_workflow, &external, ValidationLevel::Full);

        assert!(report.is_valid());
    }

    #[test]
    fn test_validate_bare_muss_always_required() {
        let evaluator = MockEvaluator::new(vec![]);
        let validator = EdifactValidator::new(evaluator);
        let external = NoOpExternalProvider;

        let workflow = AhbWorkflow {
            pruefidentifikator: "55001".to_string(),
            description: "Test".to_string(),
            communication_direction: Some("NB an LF".to_string()),
            fields: vec![AhbFieldRule {
                segment_path: "SG2/NAD/3035".to_string(),
                name: "Partnerrolle".to_string(),
                ahb_status: "Muss".to_string(), // No conditions
                codes: vec![],
                parent_group_ahb_status: None,
                segment_ahb_status: None,
                ..Default::default()
            }],
            ub_definitions: BTreeMap::new(),
        };

        let report = validator.validate(&[], &workflow, &external, ValidationLevel::Conditions);

        // Bare "Muss" with no conditions -> unconditionally required -> missing = error
        assert!(!report.is_valid());
        assert_eq!(report.error_count(), 1);
    }

    #[test]
    fn test_validate_x_status_is_mandatory() {
        let evaluator = MockEvaluator::new(vec![]);
        let validator = EdifactValidator::new(evaluator);
        let external = NoOpExternalProvider;

        let workflow = AhbWorkflow {
            pruefidentifikator: "55001".to_string(),
            description: "Test".to_string(),
            communication_direction: None,
            fields: vec![AhbFieldRule {
                segment_path: "DTM".to_string(),
                name: "Datum".to_string(),
                ahb_status: "X".to_string(),
                codes: vec![],
                parent_group_ahb_status: None,
                segment_ahb_status: None,
                ..Default::default()
            }],
            ub_definitions: BTreeMap::new(),
        };

        let report = validator.validate(&[], &workflow, &external, ValidationLevel::Conditions);

        assert!(!report.is_valid());
        let errors: Vec<_> = report.errors().collect();
        assert_eq!(errors[0].code(), ErrorCodes::MISSING_REQUIRED_FIELD);
    }

    #[test]
    fn test_validate_soll_not_mandatory() {
        let evaluator = MockEvaluator::new(vec![]);
        let validator = EdifactValidator::new(evaluator);
        let external = NoOpExternalProvider;

        let workflow = AhbWorkflow {
            pruefidentifikator: "55001".to_string(),
            description: "Test".to_string(),
            communication_direction: None,
            fields: vec![AhbFieldRule {
                segment_path: "DTM".to_string(),
                name: "Datum".to_string(),
                ahb_status: "Soll".to_string(),
                codes: vec![],
                parent_group_ahb_status: None,
                segment_ahb_status: None,
                ..Default::default()
            }],
            ub_definitions: BTreeMap::new(),
        };

        let report = validator.validate(&[], &workflow, &external, ValidationLevel::Conditions);

        // Soll is not mandatory, so missing is not an error
        assert!(report.is_valid());
    }

    #[test]
    fn test_report_includes_metadata() {
        let evaluator = MockEvaluator::new(vec![]);
        let validator = EdifactValidator::new(evaluator);
        let external = NoOpExternalProvider;

        let workflow = AhbWorkflow {
            pruefidentifikator: "55001".to_string(),
            description: String::new(),
            communication_direction: None,
            fields: vec![],
            ub_definitions: BTreeMap::new(),
        };

        let report = validator.validate(&[], &workflow, &external, ValidationLevel::Full);

        assert_eq!(report.format_version.as_deref(), Some("FV2510"));
        assert_eq!(report.level, ValidationLevel::Full);
        assert_eq!(report.message_type, "UTILMD");
        assert_eq!(report.pruefidentifikator.as_deref(), Some("55001"));
    }

    #[test]
    fn test_validate_with_navigator_returns_report() {
        let evaluator = MockEvaluator::all_true(&[]);
        let validator = EdifactValidator::new(evaluator);
        let external = NoOpExternalProvider;
        let nav = crate::eval::NoOpGroupNavigator;

        let workflow = AhbWorkflow {
            pruefidentifikator: "55001".to_string(),
            description: "Test".to_string(),
            communication_direction: None,
            fields: vec![],
            ub_definitions: BTreeMap::new(),
        };

        let report = validator.validate_with_navigator(
            &[],
            &workflow,
            &external,
            ValidationLevel::Full,
            &nav,
        );
        assert!(report.is_valid());
    }

    #[test]
    fn test_code_validation_composite_paths_valid_codes() {
        // UNH/S009/0065 and UNH/S009/0052 carry codes inside composite S009 at
        // element_index=1, component sub_index 0 and 1. Validation should match
        // the actual composite positions and find no errors for matching values.
        let evaluator = MockEvaluator::new(vec![]);
        let validator = EdifactValidator::new(evaluator);
        let external = NoOpExternalProvider;

        let unh_segment = OwnedSegment {
            id: "UNH".to_string(),
            elements: vec![
                vec!["ALEXANDE951842".to_string()],
                vec![
                    "UTILMD".to_string(),
                    "D".to_string(),
                    "11A".to_string(),
                    "UN".to_string(),
                    "S2.1".to_string(),
                ],
            ],
            segment_number: 1,
        };

        let workflow = AhbWorkflow {
            pruefidentifikator: "55001".to_string(),
            description: "Test".to_string(),
            communication_direction: None,
            fields: vec![
                AhbFieldRule {
                    segment_path: "UNH/S009/0065".to_string(),
                    name: "Nachrichtentyp".to_string(),
                    ahb_status: "X".to_string(),
                    codes: vec![AhbCodeRule {
                        value: "UTILMD".to_string(),
                        description: "Stammdaten".to_string(),
                        ahb_status: "X".to_string(),
                    }],
                    parent_group_ahb_status: None,
                    segment_ahb_status: None,
                    element_index: Some(1),
                    component_index: Some(0),
                    ..Default::default()
                },
                AhbFieldRule {
                    segment_path: "UNH/S009/0052".to_string(),
                    name: "Version".to_string(),
                    ahb_status: "X".to_string(),
                    codes: vec![AhbCodeRule {
                        value: "D".to_string(),
                        description: "Draft".to_string(),
                        ahb_status: "X".to_string(),
                    }],
                    parent_group_ahb_status: None,
                    segment_ahb_status: None,
                    element_index: Some(1),
                    component_index: Some(1),
                    ..Default::default()
                },
            ],
            ub_definitions: BTreeMap::new(),
        };

        let report = validator.validate(
            &[unh_segment],
            &workflow,
            &external,
            ValidationLevel::Conditions,
        );

        let code_errors: Vec<_> = report
            .by_category(ValidationCategory::Code)
            .filter(|i| i.severity == Severity::Error)
            .collect();
        assert!(
            code_errors.is_empty(),
            "Expected no code errors when composite values match allowed codes, got: {:?}",
            code_errors
        );
    }

    #[test]
    fn test_code_validation_partitions_by_mig_number() {
        // PID 55018 has two STS migs: 00035 (Statuskategorie=7) constrains
        // element 2 to {E03}; 00036 (Statuskategorie=E01) has no constraint there.
        // Unioning codes across migs would flag A99 in STS+E01 — it must not.
        let evaluator = MockEvaluator::new(vec![]);
        let validator = EdifactValidator::new(evaluator);
        let external = NoOpExternalProvider;

        let sts_7 = OwnedSegment {
            id: "STS".to_string(),
            elements: vec![
                vec!["7".to_string()],
                vec![String::new()],
                vec!["GH02".to_string()],
                vec!["ZW4".to_string()],
            ],
            segment_number: 1,
        };
        let sts_e01 = OwnedSegment {
            id: "STS".to_string(),
            elements: vec![
                vec!["E01".to_string()],
                vec![String::new()],
                vec!["A99".to_string(), "E_0614".to_string()],
            ],
            segment_number: 2,
        };

        let workflow = AhbWorkflow {
            pruefidentifikator: "55018".to_string(),
            description: "Test".to_string(),
            communication_direction: None,
            fields: vec![
                // Mig 00035: qualifier 7 at element 0, E03 required at element 2.
                AhbFieldRule {
                    segment_path: "SG4/STS/C601/9015".to_string(),
                    name: "Statuskategorie".to_string(),
                    ahb_status: "X".to_string(),
                    codes: vec![AhbCodeRule {
                        value: "7".to_string(),
                        description: "Transaktionsgrund".to_string(),
                        ahb_status: "X".to_string(),
                    }],
                    parent_group_ahb_status: None,
                    segment_ahb_status: None,
                    element_index: Some(0),
                    component_index: Some(0),
                    mig_number: Some("00035".to_string()),
                },
                AhbFieldRule {
                    segment_path: "SG4/STS/C556/9013".to_string(),
                    name: "Statusanlaß".to_string(),
                    ahb_status: "X".to_string(),
                    codes: vec![AhbCodeRule {
                        value: "E03".to_string(),
                        description: "Transaktionsgrund".to_string(),
                        ahb_status: "X".to_string(),
                    }],
                    parent_group_ahb_status: None,
                    segment_ahb_status: None,
                    element_index: Some(2),
                    component_index: Some(0),
                    mig_number: Some("00035".to_string()),
                },
                // Mig 00036: qualifier E01 at element 0, no codes at element 2.
                AhbFieldRule {
                    segment_path: "SG4/STS/C601/9015".to_string(),
                    name: "Statuskategorie".to_string(),
                    ahb_status: "X".to_string(),
                    codes: vec![AhbCodeRule {
                        value: "E01".to_string(),
                        description: "Antwort".to_string(),
                        ahb_status: "X".to_string(),
                    }],
                    parent_group_ahb_status: None,
                    segment_ahb_status: None,
                    element_index: Some(0),
                    component_index: Some(0),
                    mig_number: Some("00036".to_string()),
                },
            ],
            ub_definitions: BTreeMap::new(),
        };

        let report = validator.validate(
            &[sts_7, sts_e01],
            &workflow,
            &external,
            ValidationLevel::Conditions,
        );

        let code_errors: Vec<_> = report
            .by_category(ValidationCategory::Code)
            .filter(|i| {
                i.severity == Severity::Error && i.code() == ErrorCodes::CODE_NOT_ALLOWED_FOR_PID
            })
            .collect();
        assert_eq!(
            code_errors.len(),
            1,
            "Expected one COD002 (for GH02 only), got: {:?}",
            code_errors
        );
        assert_eq!(code_errors[0].actual_value.as_deref(), Some("GH02"));
    }

    #[test]
    fn test_code_validation_composite_paths_detects_invalid_code() {
        // Mirror of the STS+7 case that motivated composite validation: a bad code
        // at element_index=2, component_index=0 must produce COD002.
        let evaluator = MockEvaluator::new(vec![]);
        let validator = EdifactValidator::new(evaluator);
        let external = NoOpExternalProvider;

        let sts_segment = OwnedSegment {
            id: "STS".to_string(),
            elements: vec![
                vec!["7".to_string()],
                vec![String::new()],
                vec!["GH02".to_string()],
                vec!["ZW4".to_string()],
            ],
            segment_number: 1,
        };

        let workflow = AhbWorkflow {
            pruefidentifikator: "55018".to_string(),
            description: "Test".to_string(),
            communication_direction: None,
            fields: vec![AhbFieldRule {
                segment_path: "SG4/STS/C556/9013".to_string(),
                name: "Statusanlaß".to_string(),
                ahb_status: "X".to_string(),
                codes: vec![AhbCodeRule {
                    value: "E03".to_string(),
                    description: "Transaktionsgrund".to_string(),
                    ahb_status: "X".to_string(),
                }],
                parent_group_ahb_status: None,
                segment_ahb_status: None,
                element_index: Some(2),
                component_index: Some(0),
                ..Default::default()
            }],
            ub_definitions: BTreeMap::new(),
        };

        let report = validator.validate(
            &[sts_segment],
            &workflow,
            &external,
            ValidationLevel::Conditions,
        );

        let code_errors: Vec<_> = report
            .by_category(ValidationCategory::Code)
            .filter(|i| {
                i.severity == Severity::Error && i.code() == ErrorCodes::CODE_NOT_ALLOWED_FOR_PID
            })
            .collect();
        assert_eq!(
            code_errors.len(),
            1,
            "Expected COD002 for GH02, got: {:?}",
            code_errors
        );
        assert_eq!(code_errors[0].actual_value.as_deref(), Some("GH02"));
    }

    #[test]
    fn test_cross_field_code_validation_valid_qualifiers() {
        // NAD/3035 has separate field rules: [MS] for sender, [MR] for receiver.
        // Cross-field validation unions them → {MS, MR}. Both segments are valid.
        let evaluator = MockEvaluator::new(vec![]);
        let validator = EdifactValidator::new(evaluator);
        let external = NoOpExternalProvider;

        let nad_ms = OwnedSegment {
            id: "NAD".to_string(),
            elements: vec![vec!["MS".to_string()]],
            segment_number: 4,
        };
        let nad_mr = OwnedSegment {
            id: "NAD".to_string(),
            elements: vec![vec!["MR".to_string()]],
            segment_number: 5,
        };

        let workflow = AhbWorkflow {
            pruefidentifikator: "55001".to_string(),
            description: "Test".to_string(),
            communication_direction: None,
            fields: vec![
                AhbFieldRule {
                    segment_path: "SG2/NAD/3035".to_string(),
                    name: "Absender".to_string(),
                    ahb_status: "X".to_string(),
                    codes: vec![AhbCodeRule {
                        value: "MS".to_string(),
                        description: "Absender".to_string(),
                        ahb_status: "X".to_string(),
                    }],
                    parent_group_ahb_status: None,
                    segment_ahb_status: None,
                    ..Default::default()
                },
                AhbFieldRule {
                    segment_path: "SG2/NAD/3035".to_string(),
                    name: "Empfaenger".to_string(),
                    ahb_status: "X".to_string(),
                    codes: vec![AhbCodeRule {
                        value: "MR".to_string(),
                        description: "Empfaenger".to_string(),
                        ahb_status: "X".to_string(),
                    }],
                    parent_group_ahb_status: None,
                    segment_ahb_status: None,
                    ..Default::default()
                },
            ],
            ub_definitions: BTreeMap::new(),
        };

        let report = validator.validate(
            &[nad_ms, nad_mr],
            &workflow,
            &external,
            ValidationLevel::Conditions,
        );

        let code_errors: Vec<_> = report
            .by_category(ValidationCategory::Code)
            .filter(|i| i.severity == Severity::Error)
            .collect();
        assert!(
            code_errors.is_empty(),
            "Expected no code errors for valid qualifiers, got: {:?}",
            code_errors
        );
    }

    #[test]
    fn test_cross_field_code_validation_catches_invalid_qualifier() {
        // NAD+MT is not in the allowed set {MS, MR} → should produce COD002.
        let evaluator = MockEvaluator::new(vec![]);
        let validator = EdifactValidator::new(evaluator);
        let external = NoOpExternalProvider;

        let nad_ms = OwnedSegment {
            id: "NAD".to_string(),
            elements: vec![vec!["MS".to_string()]],
            segment_number: 4,
        };
        let nad_mt = OwnedSegment {
            id: "NAD".to_string(),
            elements: vec![vec!["MT".to_string()]], // invalid
            segment_number: 5,
        };

        let workflow = AhbWorkflow {
            pruefidentifikator: "55001".to_string(),
            description: "Test".to_string(),
            communication_direction: None,
            fields: vec![
                AhbFieldRule {
                    segment_path: "SG2/NAD/3035".to_string(),
                    name: "Absender".to_string(),
                    ahb_status: "X".to_string(),
                    codes: vec![AhbCodeRule {
                        value: "MS".to_string(),
                        description: "Absender".to_string(),
                        ahb_status: "X".to_string(),
                    }],
                    parent_group_ahb_status: None,
                    segment_ahb_status: None,
                    ..Default::default()
                },
                AhbFieldRule {
                    segment_path: "SG2/NAD/3035".to_string(),
                    name: "Empfaenger".to_string(),
                    ahb_status: "X".to_string(),
                    codes: vec![AhbCodeRule {
                        value: "MR".to_string(),
                        description: "Empfaenger".to_string(),
                        ahb_status: "X".to_string(),
                    }],
                    parent_group_ahb_status: None,
                    segment_ahb_status: None,
                    ..Default::default()
                },
            ],
            ub_definitions: BTreeMap::new(),
        };

        let report = validator.validate(
            &[nad_ms, nad_mt],
            &workflow,
            &external,
            ValidationLevel::Conditions,
        );

        let code_errors: Vec<_> = report
            .by_category(ValidationCategory::Code)
            .filter(|i| i.severity == Severity::Error)
            .collect();
        assert_eq!(code_errors.len(), 1, "Expected one COD002 error for MT");
        assert!(narrate(code_errors[0]).contains("MT"));
        assert!(narrate(code_errors[0]).contains("MR"));
        assert!(narrate(code_errors[0]).contains("MS"));
    }

    #[test]
    fn test_cross_field_code_validation_unions_across_groups() {
        // SG2/NAD/3035 allows {MS, MR}, SG4/SG12/NAD/3035 allows {Z04, Z09}.
        // Since find_segments("NAD") returns all NADs, codes must be unioned
        // by tag: {MS, MR, Z04, Z09}. NAD+MT should be caught, all others pass.
        let evaluator = MockEvaluator::new(vec![]);
        let validator = EdifactValidator::new(evaluator);
        let external = NoOpExternalProvider;

        let segments = vec![
            OwnedSegment {
                id: "NAD".to_string(),
                elements: vec![vec!["MS".to_string()]],
                segment_number: 3,
            },
            OwnedSegment {
                id: "NAD".to_string(),
                elements: vec![vec!["MR".to_string()]],
                segment_number: 4,
            },
            OwnedSegment {
                id: "NAD".to_string(),
                elements: vec![vec!["Z04".to_string()]],
                segment_number: 20,
            },
            OwnedSegment {
                id: "NAD".to_string(),
                elements: vec![vec!["Z09".to_string()]],
                segment_number: 21,
            },
            OwnedSegment {
                id: "NAD".to_string(),
                elements: vec![vec!["MT".to_string()]], // invalid
                segment_number: 22,
            },
        ];

        let workflow = AhbWorkflow {
            pruefidentifikator: "55001".to_string(),
            description: "Test".to_string(),
            communication_direction: None,
            fields: vec![
                AhbFieldRule {
                    segment_path: "SG2/NAD/3035".to_string(),
                    name: "Absender".to_string(),
                    ahb_status: "X".to_string(),
                    codes: vec![AhbCodeRule {
                        value: "MS".to_string(),
                        description: "Absender".to_string(),
                        ahb_status: "X".to_string(),
                    }],
                    parent_group_ahb_status: None,
                    segment_ahb_status: None,
                    ..Default::default()
                },
                AhbFieldRule {
                    segment_path: "SG2/NAD/3035".to_string(),
                    name: "Empfaenger".to_string(),
                    ahb_status: "X".to_string(),
                    codes: vec![AhbCodeRule {
                        value: "MR".to_string(),
                        description: "Empfaenger".to_string(),
                        ahb_status: "X".to_string(),
                    }],
                    parent_group_ahb_status: None,
                    segment_ahb_status: None,
                    ..Default::default()
                },
                AhbFieldRule {
                    segment_path: "SG4/SG12/NAD/3035".to_string(),
                    name: "Anschlussnutzer".to_string(),
                    ahb_status: "X".to_string(),
                    codes: vec![AhbCodeRule {
                        value: "Z04".to_string(),
                        description: "Anschlussnutzer".to_string(),
                        ahb_status: "X".to_string(),
                    }],
                    parent_group_ahb_status: None,
                    segment_ahb_status: None,
                    ..Default::default()
                },
                AhbFieldRule {
                    segment_path: "SG4/SG12/NAD/3035".to_string(),
                    name: "Korrespondenzanschrift".to_string(),
                    ahb_status: "X".to_string(),
                    codes: vec![AhbCodeRule {
                        value: "Z09".to_string(),
                        description: "Korrespondenzanschrift".to_string(),
                        ahb_status: "X".to_string(),
                    }],
                    parent_group_ahb_status: None,
                    segment_ahb_status: None,
                    ..Default::default()
                },
            ],
            ub_definitions: BTreeMap::new(),
        };

        let report =
            validator.validate(&segments, &workflow, &external, ValidationLevel::Conditions);

        let code_errors: Vec<_> = report
            .by_category(ValidationCategory::Code)
            .filter(|i| i.severity == Severity::Error)
            .collect();
        assert_eq!(
            code_errors.len(),
            1,
            "Expected exactly one COD002 error for MT, got: {:?}",
            code_errors
        );
        assert!(narrate(code_errors[0]).contains("MT"));
    }

    #[test]
    fn test_cross_field_code_validation_accepts_conditionally_allowed_codes() {
        // QTY 6063 in MSCONS PID 13025 has three AHB-allowed codes:
        //   220  ahb_status "X"                        (unconditional)
        //   67   ahb_status "X [35] ∨ ([32] ∧ [77])"   (conditional)
        //   Z18  ahb_status "X [35]"                    (conditional)
        // All three are "allowed codes for this PID" — they differ only in when
        // they may be used. The COD002 "code not allowed for this PID" check
        // must accept the conditional ones too, otherwise real-world load-profile
        // messages using QTY+67 (Ersatzwert) are incorrectly rejected.
        let evaluator = MockEvaluator::new(vec![]);
        let validator = EdifactValidator::new(evaluator);
        let external = NoOpExternalProvider;

        let qty_67 = OwnedSegment {
            id: "QTY".to_string(),
            elements: vec![vec!["67".to_string(), "0.185".to_string()]],
            segment_number: 10,
        };

        let workflow = AhbWorkflow {
            pruefidentifikator: "13025".to_string(),
            description: "Test".to_string(),
            communication_direction: None,
            fields: vec![AhbFieldRule {
                segment_path: "SG5/SG6/SG9/SG10/QTY/qualifier".to_string(),
                name: "Menge, Qualifier".to_string(),
                ahb_status: "X".to_string(),
                codes: vec![
                    AhbCodeRule {
                        value: "220".to_string(),
                        description: "Wahrer Wert".to_string(),
                        ahb_status: "X".to_string(),
                    },
                    AhbCodeRule {
                        value: "67".to_string(),
                        description: "Ersatzwert".to_string(),
                        ahb_status: "X [35] ∨ ([32] ∧ [77])".to_string(),
                    },
                    AhbCodeRule {
                        value: "Z18".to_string(),
                        description: "Vorläufiger Wert".to_string(),
                        ahb_status: "X [35]".to_string(),
                    },
                ],
                parent_group_ahb_status: None,
                segment_ahb_status: None,
                element_index: Some(0),
                component_index: Some(0),
                ..Default::default()
            }],
            ub_definitions: BTreeMap::new(),
        };

        let report =
            validator.validate(&[qty_67], &workflow, &external, ValidationLevel::Conditions);

        let code_errors: Vec<_> = report
            .by_category(ValidationCategory::Code)
            .filter(|i| i.severity == Severity::Error)
            .collect();
        assert!(
            code_errors.is_empty(),
            "QTY+67 should be accepted because code '67' is conditionally allowed for this PID (X [35] ∨ ([32] ∧ [77])). Got errors: {:?}",
            code_errors
        );
    }

    #[test]
    fn test_is_qualifier_field_simple_paths() {
        assert!(is_qualifier_field("NAD/3035"));
        assert!(is_qualifier_field("SG2/NAD/3035"));
        assert!(is_qualifier_field("SG4/SG8/SEQ/6350"));
        assert!(is_qualifier_field("LOC/3227"));
    }

    #[test]
    fn test_is_qualifier_field_composite_paths() {
        // Composite paths (3 parts after SG stripping) are accepted so composite-level
        // codes like STS/C556/9013 get validated. The field rule's element_index and
        // component_index carry the exact position.
        assert!(is_qualifier_field("UNH/S009/0065"));
        assert!(is_qualifier_field("NAD/C082/3039"));
        assert!(is_qualifier_field("SG2/NAD/C082/3039"));
        assert!(is_qualifier_field("SG4/STS/C556/9013"));
    }

    #[test]
    fn test_is_qualifier_field_bare_segment() {
        assert!(!is_qualifier_field("NAD"));
        assert!(!is_qualifier_field("SG2/NAD"));
    }

    #[test]
    fn test_is_qualifier_field_rejects_deep_paths() {
        // 4+ parts after SG stripping are malformed — reject.
        assert!(!is_qualifier_field("SEG/A/B/C/D"));
    }

    #[test]
    fn test_missing_qualifier_instance_is_detected() {
        // NAD+MS is present but NAD+MR is missing.
        // The Empfaenger field requires [MR] → should produce AHB001.
        let evaluator = MockEvaluator::new(vec![]);
        let validator = EdifactValidator::new(evaluator);
        let external = NoOpExternalProvider;

        let nad_ms = OwnedSegment {
            id: "NAD".to_string(),
            elements: vec![vec!["MS".to_string()]],
            segment_number: 3,
        };

        let workflow = AhbWorkflow {
            pruefidentifikator: "55001".to_string(),
            description: "Test".to_string(),
            communication_direction: None,
            fields: vec![
                AhbFieldRule {
                    segment_path: "SG2/NAD/3035".to_string(),
                    name: "Absender".to_string(),
                    ahb_status: "X".to_string(),
                    codes: vec![AhbCodeRule {
                        value: "MS".to_string(),
                        description: "Absender".to_string(),
                        ahb_status: "X".to_string(),
                    }],
                    parent_group_ahb_status: None,
                    segment_ahb_status: None,
                    ..Default::default()
                },
                AhbFieldRule {
                    segment_path: "SG2/NAD/3035".to_string(),
                    name: "Empfaenger".to_string(),
                    ahb_status: "Muss".to_string(),
                    codes: vec![AhbCodeRule {
                        value: "MR".to_string(),
                        description: "Empfaenger".to_string(),
                        ahb_status: "X".to_string(),
                    }],
                    parent_group_ahb_status: None,
                    segment_ahb_status: None,
                    ..Default::default()
                },
            ],
            ub_definitions: BTreeMap::new(),
        };

        let report =
            validator.validate(&[nad_ms], &workflow, &external, ValidationLevel::Conditions);

        let ahb_errors: Vec<_> = report
            .by_category(ValidationCategory::Ahb)
            .filter(|i| i.severity == Severity::Error)
            .collect();
        assert_eq!(
            ahb_errors.len(),
            1,
            "Expected AHB001 for missing NAD+MR, got: {:?}",
            ahb_errors
        );
        assert!(narrate(ahb_errors[0]).contains("Empfaenger"));
    }

    #[test]
    fn test_present_qualifier_instance_no_error() {
        // Both NAD+MS and NAD+MR present → no AHB001 for either.
        let evaluator = MockEvaluator::new(vec![]);
        let validator = EdifactValidator::new(evaluator);
        let external = NoOpExternalProvider;

        let segments = vec![
            OwnedSegment {
                id: "NAD".to_string(),
                elements: vec![vec!["MS".to_string()]],
                segment_number: 3,
            },
            OwnedSegment {
                id: "NAD".to_string(),
                elements: vec![vec!["MR".to_string()]],
                segment_number: 4,
            },
        ];

        let workflow = AhbWorkflow {
            pruefidentifikator: "55001".to_string(),
            description: "Test".to_string(),
            communication_direction: None,
            fields: vec![
                AhbFieldRule {
                    segment_path: "SG2/NAD/3035".to_string(),
                    name: "Absender".to_string(),
                    ahb_status: "Muss".to_string(),
                    codes: vec![AhbCodeRule {
                        value: "MS".to_string(),
                        description: "Absender".to_string(),
                        ahb_status: "X".to_string(),
                    }],
                    parent_group_ahb_status: None,
                    segment_ahb_status: None,
                    ..Default::default()
                },
                AhbFieldRule {
                    segment_path: "SG2/NAD/3035".to_string(),
                    name: "Empfaenger".to_string(),
                    ahb_status: "Muss".to_string(),
                    codes: vec![AhbCodeRule {
                        value: "MR".to_string(),
                        description: "Empfaenger".to_string(),
                        ahb_status: "X".to_string(),
                    }],
                    parent_group_ahb_status: None,
                    segment_ahb_status: None,
                    ..Default::default()
                },
            ],
            ub_definitions: BTreeMap::new(),
        };

        let report =
            validator.validate(&segments, &workflow, &external, ValidationLevel::Conditions);

        let ahb_errors: Vec<_> = report
            .by_category(ValidationCategory::Ahb)
            .filter(|i| i.severity == Severity::Error)
            .collect();
        assert!(
            ahb_errors.is_empty(),
            "Expected no AHB001 errors, got: {:?}",
            ahb_errors
        );
    }

    #[test]
    fn test_extract_group_path_key() {
        assert_eq!(extract_group_path_key("SG2/NAD/3035"), "SG2");
        assert_eq!(extract_group_path_key("SG4/SG12/NAD/3035"), "SG4/SG12");
        assert_eq!(extract_group_path_key("NAD/3035"), "");
        assert_eq!(extract_group_path_key("SG4/SG8/SEQ/6350"), "SG4/SG8");
    }

    #[test]
    fn test_absent_optional_group_no_missing_field_error() {
        // SG3 is optional ("Kann"). If SG3 is absent, its children CTA/3139
        // and CTA/C056/3412 should NOT produce AHB001 errors.
        use mig_types::navigator::GroupNavigator;

        struct NavWithoutSG3;
        impl GroupNavigator for NavWithoutSG3 {
            fn find_segments_in_group(&self, _: &str, _: &[&str], _: usize) -> Vec<OwnedSegment> {
                vec![]
            }
            fn find_segments_with_qualifier_in_group(
                &self,
                _: &str,
                _: usize,
                _: &str,
                _: &[&str],
                _: usize,
            ) -> Vec<OwnedSegment> {
                vec![]
            }
            fn group_instance_count(&self, group_path: &[&str]) -> usize {
                match group_path {
                    ["SG2"] => 2,        // two NAD groups present
                    ["SG2", "SG3"] => 0, // SG3 is absent
                    _ => 0,
                }
            }
        }

        let evaluator = MockEvaluator::new(vec![]);
        let validator = EdifactValidator::new(evaluator);
        let external = NoOpExternalProvider;
        let nav = NavWithoutSG3;

        // Only NAD segments present, no CTA
        let segments = vec![
            OwnedSegment {
                id: "NAD".into(),
                elements: vec![vec!["MS".into()]],
                segment_number: 3,
            },
            OwnedSegment {
                id: "NAD".into(),
                elements: vec![vec!["MR".into()]],
                segment_number: 4,
            },
        ];

        let workflow = AhbWorkflow {
            pruefidentifikator: "55001".to_string(),
            description: "Test".to_string(),
            communication_direction: None,
            fields: vec![
                AhbFieldRule {
                    segment_path: "SG2/SG3/CTA/3139".to_string(),
                    name: "Funktion des Ansprechpartners, Code".to_string(),
                    ahb_status: "Muss".to_string(),
                    codes: vec![],
                    parent_group_ahb_status: None,
                    segment_ahb_status: None,
                    ..Default::default()
                },
                AhbFieldRule {
                    segment_path: "SG2/SG3/CTA/C056/3412".to_string(),
                    name: "Name vom Ansprechpartner".to_string(),
                    ahb_status: "X".to_string(),
                    codes: vec![],
                    parent_group_ahb_status: None,
                    segment_ahb_status: None,
                    ..Default::default()
                },
            ],
            ub_definitions: BTreeMap::new(),
        };

        let report = validator.validate_with_navigator(
            &segments,
            &workflow,
            &external,
            ValidationLevel::Conditions,
            &nav,
        );

        let ahb_errors: Vec<_> = report
            .by_category(ValidationCategory::Ahb)
            .filter(|i| i.severity == Severity::Error)
            .collect();
        assert!(
            ahb_errors.is_empty(),
            "Expected no AHB001 errors when SG3 is absent, got: {:?}",
            ahb_errors
        );
    }

    #[test]
    fn test_present_group_still_checks_mandatory_fields() {
        // If SG3 IS present but CTA is missing within it → AHB001 error.
        use mig_types::navigator::GroupNavigator;

        struct NavWithSG3;
        impl GroupNavigator for NavWithSG3 {
            fn find_segments_in_group(&self, _: &str, _: &[&str], _: usize) -> Vec<OwnedSegment> {
                vec![]
            }
            fn find_segments_with_qualifier_in_group(
                &self,
                _: &str,
                _: usize,
                _: &str,
                _: &[&str],
                _: usize,
            ) -> Vec<OwnedSegment> {
                vec![]
            }
            fn group_instance_count(&self, group_path: &[&str]) -> usize {
                match group_path {
                    ["SG2"] => 1,
                    ["SG2", "SG3"] => 1, // SG3 is present
                    _ => 0,
                }
            }
        }

        let evaluator = MockEvaluator::new(vec![]);
        let validator = EdifactValidator::new(evaluator);
        let external = NoOpExternalProvider;
        let nav = NavWithSG3;

        // SG3 is present (nav says 1 instance) but CTA is not in flat segments
        let segments = vec![OwnedSegment {
            id: "NAD".into(),
            elements: vec![vec!["MS".into()]],
            segment_number: 3,
        }];

        let workflow = AhbWorkflow {
            pruefidentifikator: "55001".to_string(),
            description: "Test".to_string(),
            communication_direction: None,
            fields: vec![AhbFieldRule {
                segment_path: "SG2/SG3/CTA/3139".to_string(),
                name: "Funktion des Ansprechpartners, Code".to_string(),
                ahb_status: "Muss".to_string(),
                codes: vec![],
                parent_group_ahb_status: None,
                segment_ahb_status: None,
                ..Default::default()
            }],
            ub_definitions: BTreeMap::new(),
        };

        let report = validator.validate_with_navigator(
            &segments,
            &workflow,
            &external,
            ValidationLevel::Conditions,
            &nav,
        );

        let ahb_errors: Vec<_> = report
            .by_category(ValidationCategory::Ahb)
            .filter(|i| i.severity == Severity::Error)
            .collect();
        assert_eq!(
            ahb_errors.len(),
            1,
            "Expected AHB001 error when SG3 is present but CTA missing"
        );
        assert!(narrate(ahb_errors[0]).contains("CTA"));
    }

    #[test]
    fn test_missing_qualifier_with_navigator_is_detected() {
        // NAD+MS is in SG2 but NAD+MR is missing. With a navigator that
        // reports SG2 has 1 instance, the missing MR must still be flagged.
        use mig_types::navigator::GroupNavigator;

        struct NavWithSG2;
        impl GroupNavigator for NavWithSG2 {
            fn find_segments_in_group(
                &self,
                segment_id: &str,
                group_path: &[&str],
                instance_index: usize,
            ) -> Vec<OwnedSegment> {
                if segment_id == "NAD" && group_path == ["SG2"] && instance_index == 0 {
                    vec![OwnedSegment {
                        id: "NAD".into(),
                        elements: vec![vec!["MS".into()]],
                        segment_number: 3,
                    }]
                } else {
                    vec![]
                }
            }
            fn find_segments_with_qualifier_in_group(
                &self,
                _: &str,
                _: usize,
                _: &str,
                _: &[&str],
                _: usize,
            ) -> Vec<OwnedSegment> {
                vec![]
            }
            fn group_instance_count(&self, group_path: &[&str]) -> usize {
                match group_path {
                    ["SG2"] => 1,
                    _ => 0,
                }
            }
        }

        let evaluator = MockEvaluator::new(vec![]);
        let validator = EdifactValidator::new(evaluator);
        let external = NoOpExternalProvider;
        let nav = NavWithSG2;

        let segments = vec![OwnedSegment {
            id: "NAD".into(),
            elements: vec![vec!["MS".into()]],
            segment_number: 3,
        }];

        let workflow = AhbWorkflow {
            pruefidentifikator: "55001".to_string(),
            description: "Test".to_string(),
            communication_direction: None,
            fields: vec![
                AhbFieldRule {
                    segment_path: "SG2/NAD/3035".to_string(),
                    name: "Absender".to_string(),
                    ahb_status: "X".to_string(),
                    codes: vec![AhbCodeRule {
                        value: "MS".to_string(),
                        description: "Absender".to_string(),
                        ahb_status: "X".to_string(),
                    }],
                    parent_group_ahb_status: None,
                    segment_ahb_status: None,
                    ..Default::default()
                },
                AhbFieldRule {
                    segment_path: "SG2/NAD/3035".to_string(),
                    name: "Empfaenger".to_string(),
                    ahb_status: "Muss".to_string(),
                    codes: vec![AhbCodeRule {
                        value: "MR".to_string(),
                        description: "Empfaenger".to_string(),
                        ahb_status: "X".to_string(),
                    }],
                    parent_group_ahb_status: None,
                    segment_ahb_status: None,
                    ..Default::default()
                },
            ],
            ub_definitions: BTreeMap::new(),
        };

        let report = validator.validate_with_navigator(
            &segments,
            &workflow,
            &external,
            ValidationLevel::Conditions,
            &nav,
        );

        let ahb_errors: Vec<_> = report
            .by_category(ValidationCategory::Ahb)
            .filter(|i| i.severity == Severity::Error)
            .collect();
        assert_eq!(
            ahb_errors.len(),
            1,
            "Expected AHB001 for missing NAD+MR even with navigator, got: {:?}",
            ahb_errors
        );
        assert!(narrate(ahb_errors[0]).contains("Empfaenger"));
    }

    #[test]
    fn test_optional_group_variant_absent_no_error() {
        // SG5 is "Kann" (optional) with LOC+Z16 present but LOC+Z17 absent.
        // Field rules for LOC/3227 with Z17 and its children should NOT error
        // because the parent group is optional and the variant is absent.
        // Meanwhile, SG2 is "Muss" — missing NAD+MR MUST still error.
        use mig_types::navigator::GroupNavigator;

        struct TestNav;
        impl GroupNavigator for TestNav {
            fn find_segments_in_group(
                &self,
                segment_id: &str,
                group_path: &[&str],
                instance_index: usize,
            ) -> Vec<OwnedSegment> {
                match (segment_id, group_path, instance_index) {
                    ("LOC", ["SG4", "SG5"], 0) => vec![OwnedSegment {
                        id: "LOC".into(),
                        elements: vec![vec!["Z16".into()], vec!["DE00012345".into()]],
                        segment_number: 10,
                    }],
                    ("NAD", ["SG2"], 0) => vec![OwnedSegment {
                        id: "NAD".into(),
                        elements: vec![vec!["MS".into()]],
                        segment_number: 3,
                    }],
                    _ => vec![],
                }
            }
            fn find_segments_with_qualifier_in_group(
                &self,
                _: &str,
                _: usize,
                _: &str,
                _: &[&str],
                _: usize,
            ) -> Vec<OwnedSegment> {
                vec![]
            }
            fn group_instance_count(&self, group_path: &[&str]) -> usize {
                match group_path {
                    ["SG2"] => 1,
                    ["SG4"] => 1,
                    ["SG4", "SG5"] => 1, // only Z16 instance
                    _ => 0,
                }
            }
        }

        let evaluator = MockEvaluator::new(vec![]);
        let validator = EdifactValidator::new(evaluator);
        let external = NoOpExternalProvider;
        let nav = TestNav;

        let segments = vec![
            OwnedSegment {
                id: "NAD".into(),
                elements: vec![vec!["MS".into()]],
                segment_number: 3,
            },
            OwnedSegment {
                id: "LOC".into(),
                elements: vec![vec!["Z16".into()], vec!["DE00012345".into()]],
                segment_number: 10,
            },
        ];

        let workflow = AhbWorkflow {
            pruefidentifikator: "55001".to_string(),
            description: "Test".to_string(),
            communication_direction: None,
            fields: vec![
                // SG2 "Muss" — NAD+MS present, NAD+MR missing → should error
                AhbFieldRule {
                    segment_path: "SG2/NAD/3035".to_string(),
                    name: "Absender".to_string(),
                    ahb_status: "X".to_string(),
                    codes: vec![AhbCodeRule {
                        value: "MS".to_string(),
                        description: "Absender".to_string(),
                        ahb_status: "X".to_string(),
                    }],
                    parent_group_ahb_status: Some("Muss".to_string()),
                    segment_ahb_status: None,
                    ..Default::default()
                },
                AhbFieldRule {
                    segment_path: "SG2/NAD/3035".to_string(),
                    name: "Empfaenger".to_string(),
                    ahb_status: "Muss".to_string(),
                    codes: vec![AhbCodeRule {
                        value: "MR".to_string(),
                        description: "Empfaenger".to_string(),
                        ahb_status: "X".to_string(),
                    }],
                    parent_group_ahb_status: Some("Muss".to_string()),
                    segment_ahb_status: None,
                    ..Default::default()
                },
                // SG5 "Kann" — LOC+Z16 present, LOC+Z17 absent → should NOT error
                AhbFieldRule {
                    segment_path: "SG4/SG5/LOC/3227".to_string(),
                    name: "Ortsangabe, Qualifier (Z16)".to_string(),
                    ahb_status: "X".to_string(),
                    codes: vec![AhbCodeRule {
                        value: "Z16".to_string(),
                        description: "Marktlokation".to_string(),
                        ahb_status: "X".to_string(),
                    }],
                    parent_group_ahb_status: Some("Kann".to_string()),
                    segment_ahb_status: None,
                    ..Default::default()
                },
                AhbFieldRule {
                    segment_path: "SG4/SG5/LOC/3227".to_string(),
                    name: "Ortsangabe, Qualifier (Z17)".to_string(),
                    ahb_status: "Muss".to_string(),
                    codes: vec![AhbCodeRule {
                        value: "Z17".to_string(),
                        description: "Messlokation".to_string(),
                        ahb_status: "X".to_string(),
                    }],
                    parent_group_ahb_status: Some("Kann".to_string()),
                    segment_ahb_status: None,
                    ..Default::default()
                },
            ],
            ub_definitions: BTreeMap::new(),
        };

        let report = validator.validate_with_navigator(
            &segments,
            &workflow,
            &external,
            ValidationLevel::Conditions,
            &nav,
        );

        let ahb_errors: Vec<_> = report
            .by_category(ValidationCategory::Ahb)
            .filter(|i| i.severity == Severity::Error)
            .collect();

        // Exactly 1 error: NAD+MR missing (mandatory group)
        // LOC+Z17 should NOT error (optional group variant absent)
        assert_eq!(
            ahb_errors.len(),
            1,
            "Expected only AHB001 for missing NAD+MR, got: {:?}",
            ahb_errors
        );
        assert!(
            narrate(ahb_errors[0]).contains("Empfaenger"),
            "Error should be for missing NAD+MR (Empfaenger)"
        );
    }

    #[test]
    fn test_conditional_group_variant_absent_no_error() {
        // Real-world scenario: SG5 "Messlokation" has AHB_Status="Soll [165]".
        // Condition [165] evaluates to False → LOC+Z17 should NOT error.
        // SG5 "Marktlokation" has AHB_Status="Muss [2061]".
        // Condition [2061] evaluates to True → LOC+Z16 is present → no error.
        use mig_types::navigator::GroupNavigator;

        struct TestNav;
        impl GroupNavigator for TestNav {
            fn find_segments_in_group(
                &self,
                segment_id: &str,
                group_path: &[&str],
                instance_index: usize,
            ) -> Vec<OwnedSegment> {
                if segment_id == "LOC" && group_path == ["SG4", "SG5"] && instance_index == 0 {
                    vec![OwnedSegment {
                        id: "LOC".into(),
                        elements: vec![vec!["Z16".into()], vec!["DE00012345".into()]],
                        segment_number: 10,
                    }]
                } else {
                    vec![]
                }
            }
            fn find_segments_with_qualifier_in_group(
                &self,
                _: &str,
                _: usize,
                _: &str,
                _: &[&str],
                _: usize,
            ) -> Vec<OwnedSegment> {
                vec![]
            }
            fn group_instance_count(&self, group_path: &[&str]) -> usize {
                match group_path {
                    ["SG4"] => 1,
                    ["SG4", "SG5"] => 1, // only Z16 instance
                    _ => 0,
                }
            }
        }

        // Condition 165 → False (Messlokation not required)
        // Condition 2061 → True (Marktlokation required)
        let evaluator = MockEvaluator::new(vec![(165, CR::False), (2061, CR::True)]);
        let validator = EdifactValidator::new(evaluator);
        let external = NoOpExternalProvider;
        let nav = TestNav;

        let segments = vec![OwnedSegment {
            id: "LOC".into(),
            elements: vec![vec!["Z16".into()], vec!["DE00012345".into()]],
            segment_number: 10,
        }];

        let workflow = AhbWorkflow {
            pruefidentifikator: "55001".to_string(),
            description: "Test".to_string(),
            communication_direction: None,
            fields: vec![
                // SG5 "Muss [2061]" with [2061]=True → LOC+Z16 required, present → OK
                AhbFieldRule {
                    segment_path: "SG4/SG5/LOC/3227".to_string(),
                    name: "Ortsangabe, Qualifier (Z16)".to_string(),
                    ahb_status: "X".to_string(),
                    codes: vec![AhbCodeRule {
                        value: "Z16".to_string(),
                        description: "Marktlokation".to_string(),
                        ahb_status: "X".to_string(),
                    }],
                    parent_group_ahb_status: Some("Muss [2061]".to_string()),
                    segment_ahb_status: None,
                    ..Default::default()
                },
                // SG5 "Soll [165]" with [165]=False → LOC+Z17 NOT required → skip
                AhbFieldRule {
                    segment_path: "SG4/SG5/LOC/3227".to_string(),
                    name: "Ortsangabe, Qualifier (Z17)".to_string(),
                    ahb_status: "X".to_string(),
                    codes: vec![AhbCodeRule {
                        value: "Z17".to_string(),
                        description: "Messlokation".to_string(),
                        ahb_status: "X".to_string(),
                    }],
                    parent_group_ahb_status: Some("Soll [165]".to_string()),
                    segment_ahb_status: None,
                    ..Default::default()
                },
            ],
            ub_definitions: BTreeMap::new(),
        };

        let report = validator.validate_with_navigator(
            &segments,
            &workflow,
            &external,
            ValidationLevel::Conditions,
            &nav,
        );

        let ahb_errors: Vec<_> = report
            .by_category(ValidationCategory::Ahb)
            .filter(|i| i.severity == Severity::Error)
            .collect();

        // Zero errors: Z16 is present, and Z17's group condition is False
        assert!(
            ahb_errors.is_empty(),
            "Expected no errors when conditional group variant [165]=False, got: {:?}",
            ahb_errors
        );
    }

    #[test]
    fn test_conditional_group_variant_unknown_no_error() {
        // When a parent group condition evaluates to Unknown (unimplemented
        // condition), child fields should NOT produce mandatory-missing errors.
        // The group-level entry itself will produce an Info "condition unknown".

        // Condition 165 is NOT in the evaluator → returns Unknown
        let evaluator = MockEvaluator::new(vec![]);
        let validator = EdifactValidator::new(evaluator);
        let external = NoOpExternalProvider;

        let workflow = AhbWorkflow {
            pruefidentifikator: "55001".to_string(),
            description: "Test".to_string(),
            communication_direction: None,
            fields: vec![AhbFieldRule {
                segment_path: "SG4/SG5/LOC/3227".to_string(),
                name: "Ortsangabe, Qualifier (Z17)".to_string(),
                ahb_status: "X".to_string(),
                codes: vec![AhbCodeRule {
                    value: "Z17".to_string(),
                    description: "Messlokation".to_string(),
                    ahb_status: "X".to_string(),
                }],
                parent_group_ahb_status: Some("Soll [165]".to_string()),
                segment_ahb_status: None,
                ..Default::default()
            }],
            ub_definitions: BTreeMap::new(),
        };

        let report = validator.validate(&[], &workflow, &external, ValidationLevel::Conditions);

        let ahb_errors: Vec<_> = report
            .by_category(ValidationCategory::Ahb)
            .filter(|i| i.severity == Severity::Error)
            .collect();

        // No errors: parent group condition [165] is Unknown → skip child fields
        assert!(
            ahb_errors.is_empty(),
            "Expected no errors when parent group condition is Unknown, got: {:?}",
            ahb_errors
        );
    }

    #[test]
    fn test_segment_absent_within_present_group_no_error() {
        // MSCONS scenario: SG10 has QTY (entry) + optional STS segments.
        // SG10 is present (QTY+220 exists) but STS is absent.
        // Fields under STS should NOT produce AHB001 errors.
        use mig_types::navigator::GroupNavigator;

        struct TestNav;
        impl GroupNavigator for TestNav {
            fn find_segments_in_group(
                &self,
                segment_id: &str,
                group_path: &[&str],
                instance_index: usize,
            ) -> Vec<OwnedSegment> {
                // SG10 has QTY but no STS
                if segment_id == "QTY"
                    && group_path == ["SG5", "SG6", "SG9", "SG10"]
                    && instance_index == 0
                {
                    vec![OwnedSegment {
                        id: "QTY".into(),
                        elements: vec![vec!["220".into(), "0".into()]],
                        segment_number: 14,
                    }]
                } else {
                    vec![]
                }
            }
            fn find_segments_with_qualifier_in_group(
                &self,
                _: &str,
                _: usize,
                _: &str,
                _: &[&str],
                _: usize,
            ) -> Vec<OwnedSegment> {
                vec![]
            }
            fn group_instance_count(&self, group_path: &[&str]) -> usize {
                match group_path {
                    ["SG5"] => 1,
                    ["SG5", "SG6"] => 1,
                    ["SG5", "SG6", "SG9"] => 1,
                    ["SG5", "SG6", "SG9", "SG10"] => 1,
                    _ => 0,
                }
            }
            fn has_any_segment_in_group(&self, group_path: &[&str], instance_index: usize) -> bool {
                // SG10 instance 0 has QTY (the entry segment)
                group_path == ["SG5", "SG6", "SG9", "SG10"] && instance_index == 0
            }
        }

        let evaluator = MockEvaluator::all_true(&[]);
        let validator = EdifactValidator::new(evaluator);
        let external = NoOpExternalProvider;
        let nav = TestNav;

        let segments = vec![OwnedSegment {
            id: "QTY".into(),
            elements: vec![vec!["220".into(), "0".into()]],
            segment_number: 14,
        }];

        let workflow = AhbWorkflow {
            pruefidentifikator: "13017".to_string(),
            description: "Test".to_string(),
            communication_direction: None,
            fields: vec![
                // STS/C601/9015 — mandatory field under STS, but STS is absent from SG10
                AhbFieldRule {
                    segment_path: "SG5/SG6/SG9/SG10/STS/C601/9015".to_string(),
                    name: "Statuskategorie, Code".to_string(),
                    ahb_status: "X".to_string(),
                    codes: vec![],
                    parent_group_ahb_status: Some("Muss".to_string()),
                    segment_ahb_status: None,
                    ..Default::default()
                },
                // STS/C556/9013 — another field under STS
                AhbFieldRule {
                    segment_path: "SG5/SG6/SG9/SG10/STS/C556/9013".to_string(),
                    name: "Statusanlaß, Code".to_string(),
                    ahb_status: "X [5]".to_string(),
                    codes: vec![],
                    parent_group_ahb_status: Some("Muss".to_string()),
                    segment_ahb_status: None,
                    ..Default::default()
                },
            ],
            ub_definitions: BTreeMap::new(),
        };

        let report = validator.validate_with_navigator(
            &segments,
            &workflow,
            &external,
            ValidationLevel::Conditions,
            &nav,
        );

        let ahb_errors: Vec<_> = report
            .by_category(ValidationCategory::Ahb)
            .filter(|i| i.severity == Severity::Error)
            .collect();

        assert!(
            ahb_errors.is_empty(),
            "Expected no AHB001 errors when STS segment is absent from SG10, got: {:?}",
            ahb_errors
        );
    }

    #[test]
    fn test_group_scoped_code_validation_with_navigator() {
        // With a navigator, SG2/NAD is checked against {MS, MR} only,
        // and SG4/SG12/NAD is checked against {Z04, Z09} only.
        // NAD+MT in SG2 → error with allowed [MR, MS] (not the full union).
        use mig_types::navigator::GroupNavigator;

        struct TestNav;
        impl GroupNavigator for TestNav {
            fn find_segments_in_group(
                &self,
                segment_id: &str,
                group_path: &[&str],
                _instance_index: usize,
            ) -> Vec<OwnedSegment> {
                if segment_id != "NAD" {
                    return vec![];
                }
                match group_path {
                    ["SG2"] => vec![
                        OwnedSegment {
                            id: "NAD".into(),
                            elements: vec![vec!["MS".into()]],
                            segment_number: 3,
                        },
                        OwnedSegment {
                            id: "NAD".into(),
                            elements: vec![vec!["MT".into()]], // invalid in SG2
                            segment_number: 4,
                        },
                    ],
                    ["SG4", "SG12"] => vec![
                        OwnedSegment {
                            id: "NAD".into(),
                            elements: vec![vec!["Z04".into()]],
                            segment_number: 20,
                        },
                        OwnedSegment {
                            id: "NAD".into(),
                            elements: vec![vec!["Z09".into()]],
                            segment_number: 21,
                        },
                    ],
                    _ => vec![],
                }
            }
            fn find_segments_with_qualifier_in_group(
                &self,
                _: &str,
                _: usize,
                _: &str,
                _: &[&str],
                _: usize,
            ) -> Vec<OwnedSegment> {
                vec![]
            }
            fn group_instance_count(&self, group_path: &[&str]) -> usize {
                match group_path {
                    ["SG2"] | ["SG4", "SG12"] => 1,
                    _ => 0,
                }
            }
        }

        let evaluator = MockEvaluator::new(vec![]);
        let validator = EdifactValidator::new(evaluator);
        let external = NoOpExternalProvider;
        let nav = TestNav;

        let workflow = AhbWorkflow {
            pruefidentifikator: "55001".to_string(),
            description: "Test".to_string(),
            communication_direction: None,
            fields: vec![
                AhbFieldRule {
                    segment_path: "SG2/NAD/3035".to_string(),
                    name: "Absender".to_string(),
                    ahb_status: "X".to_string(),
                    codes: vec![AhbCodeRule {
                        value: "MS".to_string(),
                        description: "Absender".to_string(),
                        ahb_status: "X".to_string(),
                    }],
                    parent_group_ahb_status: None,
                    segment_ahb_status: None,
                    ..Default::default()
                },
                AhbFieldRule {
                    segment_path: "SG2/NAD/3035".to_string(),
                    name: "Empfaenger".to_string(),
                    ahb_status: "X".to_string(),
                    codes: vec![AhbCodeRule {
                        value: "MR".to_string(),
                        description: "Empfaenger".to_string(),
                        ahb_status: "X".to_string(),
                    }],
                    parent_group_ahb_status: None,
                    segment_ahb_status: None,
                    ..Default::default()
                },
                AhbFieldRule {
                    segment_path: "SG4/SG12/NAD/3035".to_string(),
                    name: "Anschlussnutzer".to_string(),
                    ahb_status: "X".to_string(),
                    codes: vec![AhbCodeRule {
                        value: "Z04".to_string(),
                        description: "Anschlussnutzer".to_string(),
                        ahb_status: "X".to_string(),
                    }],
                    parent_group_ahb_status: None,
                    segment_ahb_status: None,
                    ..Default::default()
                },
                AhbFieldRule {
                    segment_path: "SG4/SG12/NAD/3035".to_string(),
                    name: "Korrespondenzanschrift".to_string(),
                    ahb_status: "X".to_string(),
                    codes: vec![AhbCodeRule {
                        value: "Z09".to_string(),
                        description: "Korrespondenzanschrift".to_string(),
                        ahb_status: "X".to_string(),
                    }],
                    parent_group_ahb_status: None,
                    segment_ahb_status: None,
                    ..Default::default()
                },
            ],
            ub_definitions: BTreeMap::new(),
        };

        // All segments flat (for condition evaluation), navigator provides group scope.
        let all_segments = vec![
            OwnedSegment {
                id: "NAD".into(),
                elements: vec![vec!["MS".into()]],
                segment_number: 3,
            },
            OwnedSegment {
                id: "NAD".into(),
                elements: vec![vec!["MT".into()]],
                segment_number: 4,
            },
            OwnedSegment {
                id: "NAD".into(),
                elements: vec![vec!["Z04".into()]],
                segment_number: 20,
            },
            OwnedSegment {
                id: "NAD".into(),
                elements: vec![vec!["Z09".into()]],
                segment_number: 21,
            },
        ];

        let report = validator.validate_with_navigator(
            &all_segments,
            &workflow,
            &external,
            ValidationLevel::Conditions,
            &nav,
        );

        let code_errors: Vec<_> = report
            .by_category(ValidationCategory::Code)
            .filter(|i| i.severity == Severity::Error)
            .collect();

        // Only one error: MT in SG2 (not allowed in {MS, MR}).
        // Z04 and Z09 are NOT checked against {MS, MR} — group-scoped.
        assert_eq!(
            code_errors.len(),
            1,
            "Expected exactly one COD002 error for MT in SG2, got: {:?}",
            code_errors
        );
        assert!(narrate(code_errors[0]).contains("MT"));
        // Error should show only SG2's allowed codes, not the full union
        assert!(narrate(code_errors[0]).contains("MR"));
        assert!(narrate(code_errors[0]).contains("MS"));
        assert!(
            !narrate(code_errors[0]).contains("Z04"),
            "SG4/SG12 codes should not leak into SG2 error"
        );
        // Field path should include the group
        assert!(
            code_errors[0]
                .field_path
                .as_deref()
                .unwrap_or("")
                .contains("SG2"),
            "Error field_path should reference SG2, got: {:?}",
            code_errors[0].field_path
        );
    }

    // === Package cardinality tests ===

    #[test]
    fn test_package_cardinality_within_bounds() {
        // 1 code present from package [4P0..1], max=1 -> OK
        let evaluator = MockEvaluator::all_true(&[]);
        let validator = EdifactValidator::new(evaluator);
        let external = NoOpExternalProvider;

        let segments = vec![OwnedSegment {
            id: "STS".into(),
            elements: vec![
                vec!["Z33".into()], // element[0]
                vec![],             // element[1]
                vec!["E01".into()], // element[2], component[0]
            ],
            segment_number: 5,
        }];

        let workflow = AhbWorkflow {
            pruefidentifikator: "13017".to_string(),
            description: "Test".to_string(),
            communication_direction: None,
            ub_definitions: BTreeMap::new(),
            fields: vec![AhbFieldRule {
                segment_path: "SG5/SG6/SG9/SG10/STS/C556/9013".to_string(),
                name: "Statusanlaß, Code".to_string(),
                ahb_status: "X".to_string(),
                element_index: Some(2),
                component_index: Some(0),
                codes: vec![
                    AhbCodeRule {
                        value: "E01".into(),
                        description: "Code 1".into(),
                        ahb_status: "X [4P0..1]".into(),
                    },
                    AhbCodeRule {
                        value: "E02".into(),
                        description: "Code 2".into(),
                        ahb_status: "X [4P0..1]".into(),
                    },
                ],
                parent_group_ahb_status: Some("Muss".to_string()),
                segment_ahb_status: None,
                mig_number: None,
            }],
        };

        let report = validator.validate(&segments, &workflow, &external, ValidationLevel::Full);
        let pkg_errors: Vec<_> = report
            .by_category(ValidationCategory::Ahb)
            .filter(|i| i.code() == ErrorCodes::PACKAGE_CARDINALITY_VIOLATION)
            .collect();
        assert!(
            pkg_errors.is_empty(),
            "1 code within [4P0..1] bounds — no error expected, got: {:?}",
            pkg_errors
        );
    }

    #[test]
    fn test_package_cardinality_zero_present_min_zero() {
        // No codes from the package present, min=0 -> OK
        let evaluator = MockEvaluator::all_true(&[]);
        let validator = EdifactValidator::new(evaluator);
        let external = NoOpExternalProvider;

        let segments = vec![OwnedSegment {
            id: "STS".into(),
            elements: vec![
                vec!["Z33".into()],
                vec![],
                vec!["X99".into()], // X99 not in package
            ],
            segment_number: 5,
        }];

        let workflow = AhbWorkflow {
            pruefidentifikator: "13017".to_string(),
            description: "Test".to_string(),
            communication_direction: None,
            ub_definitions: BTreeMap::new(),
            fields: vec![AhbFieldRule {
                segment_path: "SG5/SG6/SG9/SG10/STS/C556/9013".to_string(),
                name: "Statusanlaß, Code".to_string(),
                ahb_status: "X".to_string(),
                element_index: Some(2),
                component_index: Some(0),
                codes: vec![
                    AhbCodeRule {
                        value: "E01".into(),
                        description: "Code 1".into(),
                        ahb_status: "X [4P0..1]".into(),
                    },
                    AhbCodeRule {
                        value: "E02".into(),
                        description: "Code 2".into(),
                        ahb_status: "X [4P0..1]".into(),
                    },
                ],
                parent_group_ahb_status: Some("Muss".to_string()),
                segment_ahb_status: None,
                mig_number: None,
            }],
        };

        let report = validator.validate(&segments, &workflow, &external, ValidationLevel::Full);
        let pkg_errors: Vec<_> = report
            .by_category(ValidationCategory::Ahb)
            .filter(|i| i.code() == ErrorCodes::PACKAGE_CARDINALITY_VIOLATION)
            .collect();
        assert!(
            pkg_errors.is_empty(),
            "0 codes, min=0 — no error expected, got: {:?}",
            pkg_errors
        );
    }

    #[test]
    fn test_package_cardinality_too_many() {
        // 2 codes present from package [4P0..1], max=1 -> ERROR
        let evaluator = MockEvaluator::all_true(&[]);
        let validator = EdifactValidator::new(evaluator);
        let external = NoOpExternalProvider;

        // Two STS segments, each with a different package code
        let segments = vec![
            OwnedSegment {
                id: "STS".into(),
                elements: vec![vec!["Z33".into()], vec![], vec!["E01".into()]],
                segment_number: 5,
            },
            OwnedSegment {
                id: "STS".into(),
                elements: vec![vec!["Z33".into()], vec![], vec!["E02".into()]],
                segment_number: 6,
            },
        ];

        let workflow = AhbWorkflow {
            pruefidentifikator: "13017".to_string(),
            description: "Test".to_string(),
            communication_direction: None,
            ub_definitions: BTreeMap::new(),
            fields: vec![AhbFieldRule {
                segment_path: "SG5/SG6/SG9/SG10/STS/C556/9013".to_string(),
                name: "Statusanlaß, Code".to_string(),
                ahb_status: "X".to_string(),
                element_index: Some(2),
                component_index: Some(0),
                codes: vec![
                    AhbCodeRule {
                        value: "E01".into(),
                        description: "Code 1".into(),
                        ahb_status: "X [4P0..1]".into(),
                    },
                    AhbCodeRule {
                        value: "E02".into(),
                        description: "Code 2".into(),
                        ahb_status: "X [4P0..1]".into(),
                    },
                ],
                parent_group_ahb_status: Some("Muss".to_string()),
                segment_ahb_status: None,
                mig_number: None,
            }],
        };

        let report = validator.validate(&segments, &workflow, &external, ValidationLevel::Full);
        let pkg_errors: Vec<_> = report
            .by_category(ValidationCategory::Ahb)
            .filter(|i| i.code() == ErrorCodes::PACKAGE_CARDINALITY_VIOLATION)
            .collect();
        assert_eq!(
            pkg_errors.len(),
            1,
            "2 codes present, max=1 — expected 1 error, got: {:?}",
            pkg_errors
        );
        assert!(narrate(pkg_errors[0]).contains("[4P0..1]"));
        assert_eq!(pkg_errors[0].actual_value.as_deref(), Some("2"));
        assert_eq!(pkg_errors[0].expected_value.as_deref(), Some("0..1"));
    }

    #[test]
    fn test_package_cardinality_too_few() {
        // 0 codes present from package [5P1..3], min=1 -> ERROR
        let evaluator = MockEvaluator::all_true(&[]);
        let validator = EdifactValidator::new(evaluator);
        let external = NoOpExternalProvider;

        let segments = vec![OwnedSegment {
            id: "STS".into(),
            elements: vec![
                vec!["Z33".into()],
                vec![],
                vec!["X99".into()], // not in package
            ],
            segment_number: 5,
        }];

        let workflow = AhbWorkflow {
            pruefidentifikator: "13017".to_string(),
            description: "Test".to_string(),
            communication_direction: None,
            ub_definitions: BTreeMap::new(),
            fields: vec![AhbFieldRule {
                segment_path: "SG5/SG6/SG9/SG10/STS/C556/9013".to_string(),
                name: "Statusanlaß, Code".to_string(),
                ahb_status: "X".to_string(),
                element_index: Some(2),
                component_index: Some(0),
                codes: vec![
                    AhbCodeRule {
                        value: "E01".into(),
                        description: "Code 1".into(),
                        ahb_status: "X [5P1..3]".into(),
                    },
                    AhbCodeRule {
                        value: "E02".into(),
                        description: "Code 2".into(),
                        ahb_status: "X [5P1..3]".into(),
                    },
                    AhbCodeRule {
                        value: "E03".into(),
                        description: "Code 3".into(),
                        ahb_status: "X [5P1..3]".into(),
                    },
                ],
                parent_group_ahb_status: Some("Muss".to_string()),
                segment_ahb_status: None,
                mig_number: None,
            }],
        };

        let report = validator.validate(&segments, &workflow, &external, ValidationLevel::Full);
        let pkg_errors: Vec<_> = report
            .by_category(ValidationCategory::Ahb)
            .filter(|i| i.code() == ErrorCodes::PACKAGE_CARDINALITY_VIOLATION)
            .collect();
        assert_eq!(
            pkg_errors.len(),
            1,
            "0 codes present, min=1 — expected 1 error, got: {:?}",
            pkg_errors
        );
        assert!(narrate(pkg_errors[0]).contains("[5P1..3]"));
        assert_eq!(pkg_errors[0].actual_value.as_deref(), Some("0"));
        assert_eq!(pkg_errors[0].expected_value.as_deref(), Some("1..3"));
    }

    #[test]
    fn test_package_cardinality_no_packages_in_workflow() {
        // Codes without package annotations -> no package errors
        let evaluator = MockEvaluator::all_true(&[]);
        let validator = EdifactValidator::new(evaluator);
        let external = NoOpExternalProvider;

        let segments = vec![OwnedSegment {
            id: "STS".into(),
            elements: vec![vec!["E01".into()]],
            segment_number: 5,
        }];

        let workflow = AhbWorkflow {
            pruefidentifikator: "13017".to_string(),
            description: "Test".to_string(),
            communication_direction: None,
            ub_definitions: BTreeMap::new(),
            fields: vec![AhbFieldRule {
                segment_path: "STS/9015".to_string(),
                name: "Status Code".to_string(),
                ahb_status: "X".to_string(),
                codes: vec![AhbCodeRule {
                    value: "E01".into(),
                    description: "Code 1".into(),
                    ahb_status: "X".into(),
                }],
                parent_group_ahb_status: Some("Muss".to_string()),
                segment_ahb_status: None,
                ..Default::default()
            }],
        };

        let report = validator.validate(&segments, &workflow, &external, ValidationLevel::Full);
        let pkg_errors: Vec<_> = report
            .by_category(ValidationCategory::Ahb)
            .filter(|i| i.code() == ErrorCodes::PACKAGE_CARDINALITY_VIOLATION)
            .collect();
        assert!(
            pkg_errors.is_empty(),
            "No packages in workflow — no errors expected"
        );
    }

    #[test]
    fn test_package_cardinality_with_condition_and_package() {
        // Code status "X [901] [4P0..1]" has both condition and package
        let evaluator = MockEvaluator::all_true(&[901]);
        let validator = EdifactValidator::new(evaluator);
        let external = NoOpExternalProvider;

        let segments = vec![OwnedSegment {
            id: "STS".into(),
            elements: vec![vec![], vec![], vec!["E01".into()]],
            segment_number: 5,
        }];

        let workflow = AhbWorkflow {
            pruefidentifikator: "13017".to_string(),
            description: "Test".to_string(),
            communication_direction: None,
            ub_definitions: BTreeMap::new(),
            fields: vec![AhbFieldRule {
                segment_path: "SG10/STS/C556/9013".to_string(),
                name: "Code".to_string(),
                ahb_status: "X".to_string(),
                element_index: Some(2),
                component_index: Some(0),
                codes: vec![
                    AhbCodeRule {
                        value: "E01".into(),
                        description: "Code 1".into(),
                        ahb_status: "X [901] [4P0..1]".into(),
                    },
                    AhbCodeRule {
                        value: "E02".into(),
                        description: "Code 2".into(),
                        ahb_status: "X [901] [4P0..1]".into(),
                    },
                ],
                parent_group_ahb_status: Some("Muss".to_string()),
                segment_ahb_status: None,
                mig_number: None,
            }],
        };

        let report = validator.validate(&segments, &workflow, &external, ValidationLevel::Full);
        let pkg_errors: Vec<_> = report
            .by_category(ValidationCategory::Ahb)
            .filter(|i| i.code() == ErrorCodes::PACKAGE_CARDINALITY_VIOLATION)
            .collect();
        assert!(
            pkg_errors.is_empty(),
            "1 code within [4P0..1] bounds — no error, got: {:?}",
            pkg_errors
        );
    }

    #[test]
    fn test_package_cardinality_scoped_per_group_instance() {
        // Package [4P0..1] caps the number of codes per SG10 group instance at 0..1.
        // MSCONS PID 13025 messages contain many SG10 reps (one per interval); each
        // rep has its own STS+Z32++<reason> segment using one code from the package.
        // The old global count summed codes across reps and flagged every
        // multi-interval message (e.g. 96 intervals → 96 codes "allowed 0..1").
        // With a navigator present, package cardinality must be evaluated per
        // group instance, not message-wide.
        use mig_types::navigator::GroupNavigator;

        struct TwoSg10s {
            sts_a: OwnedSegment,
            sts_b: OwnedSegment,
        }
        impl GroupNavigator for TwoSg10s {
            fn find_segments_in_group(
                &self,
                segment_id: &str,
                group_path: &[&str],
                instance_index: usize,
            ) -> Vec<OwnedSegment> {
                if group_path == ["SG5", "SG6", "SG9", "SG10"] && segment_id == "STS" {
                    match instance_index {
                        0 => vec![self.sts_a.clone()],
                        1 => vec![self.sts_b.clone()],
                        _ => vec![],
                    }
                } else {
                    vec![]
                }
            }
            fn find_segments_with_qualifier_in_group(
                &self,
                _: &str,
                _: usize,
                _: &str,
                _: &[&str],
                _: usize,
            ) -> Vec<OwnedSegment> {
                vec![]
            }
            fn group_instance_count(&self, group_path: &[&str]) -> usize {
                match group_path {
                    ["SG5"] | ["SG5", "SG6"] | ["SG5", "SG6", "SG9"] => 1,
                    ["SG5", "SG6", "SG9", "SG10"] => 2,
                    _ => 0,
                }
            }
        }

        let sts_a = OwnedSegment {
            id: "STS".into(),
            elements: vec![vec!["Z32".into()], vec![], vec!["E01".into()]],
            segment_number: 10,
        };
        let sts_b = OwnedSegment {
            id: "STS".into(),
            elements: vec![vec!["Z32".into()], vec![], vec!["E01".into()]],
            segment_number: 15,
        };
        let nav = TwoSg10s {
            sts_a: sts_a.clone(),
            sts_b: sts_b.clone(),
        };

        let evaluator = MockEvaluator::all_true(&[]);
        let validator = EdifactValidator::new(evaluator);
        let external = NoOpExternalProvider;

        let workflow = AhbWorkflow {
            pruefidentifikator: "13025".to_string(),
            description: "Test".to_string(),
            communication_direction: None,
            ub_definitions: BTreeMap::new(),
            fields: vec![AhbFieldRule {
                segment_path: "SG5/SG6/SG9/SG10/STS/C556/9013".to_string(),
                name: "Statusanlaß, Code".to_string(),
                ahb_status: "X".to_string(),
                element_index: Some(2),
                component_index: Some(0),
                codes: vec![
                    AhbCodeRule {
                        value: "E01".into(),
                        description: "Code 1".into(),
                        ahb_status: "X [4P0..1]".into(),
                    },
                    AhbCodeRule {
                        value: "E02".into(),
                        description: "Code 2".into(),
                        ahb_status: "X [4P0..1]".into(),
                    },
                ],
                parent_group_ahb_status: Some("Muss".to_string()),
                segment_ahb_status: None,
                mig_number: None,
            }],
        };

        let report = validator.validate_with_navigator(
            &[sts_a, sts_b],
            &workflow,
            &external,
            ValidationLevel::Full,
            &nav,
        );
        let pkg_errors: Vec<_> = report
            .by_category(ValidationCategory::Ahb)
            .filter(|i| i.code() == ErrorCodes::PACKAGE_CARDINALITY_VIOLATION)
            .collect();
        assert!(
            pkg_errors.is_empty(),
            "Package cardinality is per-instance: 1 code per SG10 rep is within [4P0..1]. Got: {:?}",
            pkg_errors
        );
    }

    fn make_segment(id: &str, elements: Vec<Vec<&str>>) -> OwnedSegment {
        OwnedSegment {
            id: id.to_string(),
            elements: elements
                .into_iter()
                .map(|e| e.into_iter().map(|s| s.to_string()).collect())
                .collect(),
            segment_number: 0,
        }
    }

    /// Package cardinality must not fire against sibling group variants.
    ///
    /// PID 55218 has two SG8 variants: `sg8_z01` (SEQ mig=00115, no
    /// package) and `sg8_z45_z84` (SEQ mig=00171, with `[1P1..n]`
    /// package on Z45/Z84). The rule is scoped to mig=00171, but the
    /// old per-instance loop counted codes across every SG8 instance
    /// (including the Z01 sibling) and fired "0 codes present" on
    /// instances belonging to the other variant. With
    /// `instance_has_mig_number` the loop skips instances whose variant
    /// doesn't define the rule's mig_number.
    #[test]
    fn test_package_cardinality_scoped_to_rule_mig_variant() {
        use mig_types::navigator::GroupNavigator;

        struct TwoSg8Variants {
            seq_z01: OwnedSegment,
            seq_z45: OwnedSegment,
        }
        impl GroupNavigator for TwoSg8Variants {
            fn find_segments_in_group(
                &self,
                segment_id: &str,
                group_path: &[&str],
                instance_index: usize,
            ) -> Vec<OwnedSegment> {
                if group_path == ["SG4", "SG8"] && segment_id == "SEQ" {
                    match instance_index {
                        0 => vec![self.seq_z01.clone()],
                        1 => vec![self.seq_z45.clone()],
                        _ => vec![],
                    }
                } else {
                    vec![]
                }
            }
            fn find_segments_with_qualifier_in_group(
                &self,
                _: &str,
                _: usize,
                _: &str,
                _: &[&str],
                _: usize,
            ) -> Vec<OwnedSegment> {
                vec![]
            }
            fn group_instance_count(&self, group_path: &[&str]) -> usize {
                match group_path {
                    ["SG4"] => 1,
                    ["SG4", "SG8"] => 2,
                    _ => 0,
                }
            }
            fn instance_has_mig_number(
                &self,
                group_path: &[&str],
                instance_index: usize,
                mig_number: &str,
            ) -> bool {
                if group_path != ["SG4", "SG8"] {
                    return true;
                }
                match (instance_index, mig_number) {
                    (0, "00115") => true,
                    (0, _) => false,
                    (1, "00171") => true,
                    (1, _) => false,
                    _ => false,
                }
            }
        }

        let seq_z01 = OwnedSegment {
            id: "SEQ".into(),
            elements: vec![vec!["Z01".into()], vec!["1".into()]],
            segment_number: 10,
        };
        let seq_z45 = OwnedSegment {
            id: "SEQ".into(),
            elements: vec![vec!["Z45".into()], vec!["1".into()]],
            segment_number: 20,
        };
        let nav = TwoSg8Variants {
            seq_z01: seq_z01.clone(),
            seq_z45: seq_z45.clone(),
        };

        let evaluator = MockEvaluator::all_true(&[]);
        let validator = EdifactValidator::new(evaluator);
        let external = NoOpExternalProvider;

        let workflow = AhbWorkflow {
            pruefidentifikator: "55218".to_string(),
            description: "Test".to_string(),
            communication_direction: None,
            ub_definitions: BTreeMap::new(),
            fields: vec![AhbFieldRule {
                segment_path: "SG4/SG8/SEQ/1229".to_string(),
                name: "Handlung, Code".to_string(),
                ahb_status: "X".to_string(),
                element_index: Some(0),
                component_index: Some(0),
                codes: vec![
                    AhbCodeRule {
                        value: "Z45".into(),
                        description: "NNA".into(),
                        ahb_status: "X [1P1..4294967295]".into(),
                    },
                    AhbCodeRule {
                        value: "Z84".into(),
                        description: "Differenz-NNA".into(),
                        ahb_status: "X [1P0..4294967295]".into(),
                    },
                ],
                parent_group_ahb_status: Some("Muss".to_string()),
                segment_ahb_status: None,
                mig_number: Some("00171".to_string()),
            }],
        };

        let report = validator.validate_with_navigator(
            &[seq_z01, seq_z45],
            &workflow,
            &external,
            ValidationLevel::Full,
            &nav,
        );
        let pkg_errors: Vec<_> = report
            .by_category(ValidationCategory::Ahb)
            .filter(|i| i.code() == ErrorCodes::PACKAGE_CARDINALITY_VIOLATION)
            .collect();
        assert!(
            pkg_errors.is_empty(),
            "Package rule with mig=00171 must only count the Z45 instance (which has 1 code), not the sibling Z01 variant. Got: {:?}",
            pkg_errors
        );
    }

    #[test]
    fn test_unt_count_correct() {
        // UNH + BGM + DTM + UNT = 4 segments, UNT declares 4
        let segments = vec![
            make_segment("UNH", vec![vec!["001"]]),
            make_segment("BGM", vec![vec!["E01"]]),
            make_segment("DTM", vec![vec!["137", "20250401"]]),
            make_segment("UNT", vec![vec!["4", "001"]]),
        ];
        assert!(
            validate_unt_segment_count(&segments).is_none(),
            "Correct count should produce no issue"
        );
    }

    #[test]
    fn test_unt_count_mismatch() {
        // UNH + BGM + UNT = 3 segments, but UNT declares 5
        let segments = vec![
            make_segment("UNH", vec![vec!["001"]]),
            make_segment("BGM", vec![vec!["E01"]]),
            make_segment("UNT", vec![vec!["5", "001"]]),
        ];
        let issue =
            validate_unt_segment_count(&segments).expect("Mismatch should produce an issue");
        assert_eq!(issue.code(), ErrorCodes::UNT_SEGMENT_COUNT_MISMATCH);
        assert_eq!(issue.severity, Severity::Error);
        assert!(narrate(&issue).contains("declared 5"));
        assert!(narrate(&issue).contains("actual 3"));
    }

    #[test]
    fn test_unt_count_excludes_envelope() {
        // Envelope segments (UNA, UNB, UNZ) should not be counted
        let segments = vec![
            make_segment("UNA", vec![]),
            make_segment("UNB", vec![vec!["UNOC", "3"]]),
            make_segment("UNH", vec![vec!["001"]]),
            make_segment("BGM", vec![vec!["E01"]]),
            make_segment("UNT", vec![vec!["3", "001"]]),
            make_segment("UNZ", vec![vec!["1"]]),
        ];
        assert!(
            validate_unt_segment_count(&segments).is_none(),
            "Envelope segments excluded — count should be 3 (UNH+BGM+UNT)"
        );
    }

    #[test]
    fn test_unt_count_no_unt_returns_none() {
        let segments = vec![
            make_segment("UNH", vec![vec!["001"]]),
            make_segment("BGM", vec![vec!["E01"]]),
        ];
        assert!(
            validate_unt_segment_count(&segments).is_none(),
            "No UNT segment should return None (not our problem)"
        );
    }

    #[test]
    fn test_unt_count_rejects_multi_message_input() {
        // Two messages spliced together — should return an error
        let segments = vec![
            make_segment("UNH", vec![vec!["001"]]),
            make_segment("BGM", vec![vec!["E01"]]),
            make_segment("UNT", vec![vec!["3", "001"]]),
            make_segment("UNH", vec![vec!["002"]]),
            make_segment("BGM", vec![vec!["E02"]]),
            make_segment("UNT", vec![vec!["3", "002"]]),
        ];
        let issue = validate_unt_segment_count(&segments)
            .expect("Multi-message input should produce an error");
        assert_eq!(issue.code(), ErrorCodes::UNT_SEGMENT_COUNT_MISMATCH);
        assert!(
            narrate(&issue).contains("2 UNH"),
            "Should mention UNH count: {}",
            narrate(&issue)
        );
    }

    #[test]
    fn test_code_validation_accepts_multi_code_variant_qualifier() {
        // PID 55035 SG4/SG8 has many RFF variants — one per mig_number. The
        // variant with mig=00075 has TWO required codes (Z31, Z39): both are
        // valid qualifier values for that variant. Prior behavior only treated
        // buckets with exactly one required code as qualifier buckets, so
        // segments with Z31/Z39 fell through and were compared against the
        // union of *other* variants' codes — producing a false COD002.
        let evaluator = MockEvaluator::new(vec![]);
        let validator = EdifactValidator::new(evaluator);
        let external = NoOpExternalProvider;

        let rff_z39 = OwnedSegment {
            id: "RFF".to_string(),
            elements: vec![
                vec!["RFF".to_string()],
                vec!["Z39".to_string(), "REF1".to_string()],
            ],
            segment_number: 1,
        };

        let workflow = AhbWorkflow {
            pruefidentifikator: "55035".to_string(),
            description: "Test".to_string(),
            communication_direction: None,
            fields: vec![
                // Mig 00075 variant: qualifier is Z31 or Z39 (multi-code bucket)
                AhbFieldRule {
                    segment_path: "SG4/SG8/RFF/C506/1153".to_string(),
                    name: "Referenznummer Qualifier".to_string(),
                    ahb_status: "Muss".to_string(),
                    codes: vec![
                        AhbCodeRule {
                            value: "Z31".to_string(),
                            description: "".to_string(),
                            ahb_status: "X".to_string(),
                        },
                        AhbCodeRule {
                            value: "Z39".to_string(),
                            description: "".to_string(),
                            ahb_status: "X".to_string(),
                        },
                    ],
                    parent_group_ahb_status: None,
                    segment_ahb_status: None,
                    element_index: Some(1),
                    component_index: Some(0),
                    mig_number: Some("00075".to_string()),
                },
                // Mig 00078 variant: single-code qualifier Z33
                AhbFieldRule {
                    segment_path: "SG4/SG8/RFF/C506/1153".to_string(),
                    name: "Referenznummer Qualifier".to_string(),
                    ahb_status: "Muss".to_string(),
                    codes: vec![AhbCodeRule {
                        value: "Z33".to_string(),
                        description: "".to_string(),
                        ahb_status: "X".to_string(),
                    }],
                    parent_group_ahb_status: None,
                    segment_ahb_status: None,
                    element_index: Some(1),
                    component_index: Some(0),
                    mig_number: Some("00078".to_string()),
                },
            ],
            ub_definitions: BTreeMap::new(),
        };

        let report = validator.validate(
            &[rff_z39],
            &workflow,
            &external,
            ValidationLevel::Conditions,
        );

        let code_errors: Vec<_> = report
            .by_category(ValidationCategory::Code)
            .filter(|i| {
                i.severity == Severity::Error && i.code() == ErrorCodes::CODE_NOT_ALLOWED_FOR_PID
            })
            .collect();
        assert!(
            code_errors.is_empty(),
            "RFF+Z39 must be accepted (Z39 is valid for mig=00075). Got: {:?}",
            code_errors
        );
    }

    #[test]
    fn test_code_validation_disambiguates_migs_by_full_code_profile() {
        // PID 55035 SG4/SG8 PIA variants all share element 0 code '5' as
        // qualifier. They differ only at composite C212/7143 (one variant
        // allows Z12, another allows SRW). Matching on the first single-code
        // field alone picks an arbitrary bucket and then rejects the other
        // variant's composite value — a false COD002.
        let evaluator = MockEvaluator::new(vec![]);
        let validator = EdifactValidator::new(evaluator);
        let external = NoOpExternalProvider;

        // Include BOTH variants so the current bug is triggered deterministically:
        // match_segment_to_mig picks one bucket by HashMap iteration order, so
        // exactly one of {Z12, SRW} is rejected under the current logic.
        let pia_5_z12 = OwnedSegment {
            id: "PIA".to_string(),
            elements: vec![vec!["5".to_string()], vec!["Z12".to_string()]],
            segment_number: 1,
        };
        let pia_5_srw = OwnedSegment {
            id: "PIA".to_string(),
            elements: vec![vec!["5".to_string()], vec!["SRW".to_string()]],
            segment_number: 2,
        };

        let make_rules = |mig: &str, composite_code: &str| {
            vec![
                AhbFieldRule {
                    segment_path: "SG4/SG8/PIA/4347".to_string(),
                    name: "Produkt-ID-Funktion".to_string(),
                    ahb_status: "Muss".to_string(),
                    codes: vec![AhbCodeRule {
                        value: "5".to_string(),
                        description: "".to_string(),
                        ahb_status: "X".to_string(),
                    }],
                    parent_group_ahb_status: None,
                    segment_ahb_status: None,
                    element_index: Some(0),
                    component_index: Some(0),
                    mig_number: Some(mig.to_string()),
                },
                AhbFieldRule {
                    segment_path: "SG4/SG8/PIA/C212/7143".to_string(),
                    name: "Artikel/Dienstleistung-Identifikator".to_string(),
                    ahb_status: "Muss".to_string(),
                    codes: vec![AhbCodeRule {
                        value: composite_code.to_string(),
                        description: "".to_string(),
                        ahb_status: "X".to_string(),
                    }],
                    parent_group_ahb_status: None,
                    segment_ahb_status: None,
                    element_index: Some(1),
                    component_index: Some(0),
                    mig_number: Some(mig.to_string()),
                },
            ]
        };

        let mut fields = make_rules("00108", "Z12");
        fields.extend(make_rules("00197", "SRW"));

        let workflow = AhbWorkflow {
            pruefidentifikator: "55035".to_string(),
            description: "Test".to_string(),
            communication_direction: None,
            fields,
            ub_definitions: BTreeMap::new(),
        };

        let report = validator.validate(
            &[pia_5_z12, pia_5_srw],
            &workflow,
            &external,
            ValidationLevel::Conditions,
        );

        let code_errors: Vec<_> = report
            .by_category(ValidationCategory::Code)
            .filter(|i| {
                i.severity == Severity::Error && i.code() == ErrorCodes::CODE_NOT_ALLOWED_FOR_PID
            })
            .collect();
        assert!(
            code_errors.is_empty(),
            "Both PIA+5+Z12 (mig=00108) and PIA+5+SRW (mig=00197) must be accepted. Got: {:?}",
            code_errors
        );
    }
}