edifact_mapper/

mapper.rs

//! High-level [`Mapper`] API for EDIFACT-to-BO4E conversion.

use std::collections::HashMap;
use std::sync::Mutex;

use mig_assembly::ConversionService;
use mig_bo4e::engine::DataBundle;
use mig_bo4e::MappingEngine;

use crate::data_dir::DataDir;
use crate::error::MapperError;

/// Result of a BO4E mapping operation.
pub struct Bo4eResult {
    /// The PID (Pruefidentifikator) that was detected or specified.
    pub pid: String,
    /// The EDIFACT message type (e.g., "UTILMD", "MSCONS").
    pub message_type: String,
    /// The message variant (e.g., "UTILMD_Strom", "MSCONS").
    pub variant: String,
    /// The mapped BO4E JSON output.
    pub bo4e: serde_json::Value,
}

/// High-level facade for bidirectional EDIFACT ↔ BO4E conversion.
///
/// Wraps [`DataBundle`] loading with lazy/eager initialization, and provides
/// convenient accessors for [`ConversionService`] and [`MappingEngine`] instances.
///
/// # Inbound (EDIFACT → BO4E)
///
/// ```ignore
/// use edifact_mapper::{DataDir, Mapper};
///
/// let mapper = Mapper::from_data_dir(DataDir::auto())?;
///
/// // Detect PID from raw EDIFACT (no upfront knowledge needed)
/// let pid = mapper.detect_pid(edifact_str)?;
///
/// // Convert to typed BO4E interchange
/// let interchange: DynamicInterchange =
///     mapper.from_edifact(edifact_str, "FV2504", "UTILMD_Strom", &pid)?;
/// ```
///
/// # Outbound (BO4E → EDIFACT)
///
/// ```ignore
/// let edifact = mapper.to_edifact(
///     &msg_stammdaten, &tx_stammdaten,
///     "FV2504", "UTILMD_Strom", "55001",
/// )?;
/// ```
///
/// # Mid-level Access
///
/// ```ignore
/// let cs = mapper.conversion_service("FV2504", "UTILMD_Strom")?;
/// let engine = mapper.engine("FV2504", "UTILMD_Strom", "55001")?;
/// ```
/// A single entry returned by [`Mapper::list_pids`].
#[derive(Debug, Clone)]
pub struct PidListEntry {
    pub fv: String,
    pub variant: String,
    pub pid: String,
    pub beschreibung: String,
}

pub struct Mapper {
    data_dir: DataDir,
    bundles: Mutex<HashMap<String, DataBundle>>,
}

/// Read one caller-supplied transaction into a [`mig_bo4e::model::MappedTransaktion`].
///
/// Accepts both shapes. A `{transaktionsdaten, stammdaten}` object is taken
/// apart into the two halves; anything else is a bare entity map, which is what
/// callers passed before the metadata slot existed — including one that already
/// contains `prozessdaten` among its entities, where the engine's own reverse
/// merge handles it.
///
/// Either key identifies the wrapper — see
/// [`is_wrapped_transaktion`](mig_bo4e::model::is_wrapped_transaktion). A half
/// that is absent stands in as empty, so a transaction of metadata alone keeps
/// its metadata instead of being read as an entity map (issue #153).
fn split_transaktion(tx: &serde_json::Value) -> mig_bo4e::model::MappedTransaktion {
    let (transaktionsdaten, stammdaten) = if mig_bo4e::model::is_wrapped_transaktion(tx) {
        (
            tx.get("transaktionsdaten")
                .cloned()
                .unwrap_or(serde_json::Value::Null),
            tx.get("stammdaten")
                .cloned()
                .unwrap_or_else(|| serde_json::Value::Object(Default::default())),
        )
    } else {
        (serde_json::Value::Null, tx.clone())
    };
    mig_bo4e::model::MappedTransaktion {
        transaktionsdaten,
        stammdaten,
        nesting_info: Default::default(),
    }
}

impl Mapper {
    /// Create a new `Mapper` from a [`DataDir`] configuration.
    ///
    /// Any format versions marked as [`eager`](DataDir::eager) are loaded immediately.
    /// All others are loaded lazily on first access.
    pub fn from_data_dir(data_dir: DataDir) -> Result<Self, MapperError> {
        let mapper = Self {
            data_dir,
            bundles: Mutex::new(HashMap::new()),
        };
        let eager_fvs: Vec<String> = mapper.data_dir.eager_fvs().to_vec();
        for fv in &eager_fvs {
            mapper.ensure_bundle_loaded(fv)?;
        }
        Ok(mapper)
    }

    /// Ensure that the bundle for `fv` is loaded into memory.
    fn ensure_bundle_loaded(&self, fv: &str) -> Result<(), MapperError> {
        let mut bundles = self.bundles.lock().unwrap();
        if bundles.contains_key(fv) {
            return Ok(());
        }
        let path = self.data_dir.bundle_path(fv);
        if !path.exists() {
            return Err(MapperError::BundleNotFound { fv: fv.to_string() });
        }
        let bundle = DataBundle::load(&path)?;
        // `DataBundle::load` has already checked the serialisation format.
        // That says the file parses, not that its mappings belong with this
        // crate — the check that would have caught #158.
        let expected = DataBundle::PRODUCING_VERSION;
        if !self.data_dir.allows_bundle_from_other_release()
            && bundle.built_by.as_deref() != Some(expected)
        {
            return Err(MapperError::BundleFromOtherRelease {
                fv: fv.to_string(),
                built_by: bundle.built_by.clone(),
                expected: expected.to_string(),
                path: path.display().to_string(),
            });
        }
        bundles.insert(fv.to_string(), bundle);
        Ok(())
    }

    /// Get a [`ConversionService`] for the given format version and variant.
    ///
    /// The service can tokenize EDIFACT input and assemble it into a MIG tree.
    pub fn conversion_service(
        &self,
        fv: &str,
        variant: &str,
    ) -> Result<ConversionService, MapperError> {
        self.ensure_bundle_loaded(fv)?;
        let bundles = self.bundles.lock().unwrap();
        let bundle = bundles.get(fv).unwrap();
        let vc = bundle
            .variant(variant)
            .ok_or_else(|| MapperError::VariantNotFound {
                fv: fv.to_string(),
                variant: variant.to_string(),
            })?;
        let mig = vc
            .mig_schema
            .as_ref()
            .ok_or_else(|| MapperError::VariantNotFound {
                fv: fv.to_string(),
                variant: format!("{variant} (no MIG schema in bundle)"),
            })?;
        Ok(ConversionService::from_mig(mig.clone()))
    }

    /// Get a [`MappingEngine`] for a specific PID within a format version and variant.
    ///
    /// The engine can convert between assembled MIG trees and BO4E JSON.
    pub fn engine(&self, fv: &str, variant: &str, pid: &str) -> Result<MappingEngine, MapperError> {
        self.ensure_bundle_loaded(fv)?;
        let bundles = self.bundles.lock().unwrap();
        let bundle = bundles.get(fv).unwrap();
        let vc = bundle
            .variant(variant)
            .ok_or_else(|| MapperError::VariantNotFound {
                fv: fv.to_string(),
                variant: variant.to_string(),
            })?;
        let pid_key = format!("pid_{pid}");
        let defs = vc
            .combined_defs
            .get(&pid_key)
            .ok_or_else(|| MapperError::PidNotFound {
                fv: fv.to_string(),
                variant: variant.to_string(),
                pid: pid.to_string(),
            })?;
        Ok(MappingEngine::from_definitions_with_code_lists(
            std::sync::Arc::clone(&vc.code_lists),
            defs.clone(),
        ))
    }

    /// Return the [`PidRequirements`] for a specific PID within a format version and variant.
    ///
    /// Requirements describe every entity and field the PID expects, including
    /// AHB status, cardinality, valid code values, and message vs transaction scope.
    pub fn pid_requirements(
        &self,
        fv: &str,
        variant: &str,
        pid: &str,
    ) -> Result<mig_bo4e::pid_requirements::PidRequirements, MapperError> {
        self.ensure_bundle_loaded(fv)?;
        let bundles = self.bundles.lock().unwrap();
        let bundle = bundles.get(fv).unwrap();
        let vc = bundle
            .variant(variant)
            .ok_or_else(|| MapperError::VariantNotFound {
                fv: fv.to_string(),
                variant: variant.to_string(),
            })?;
        let pid_key = format!("pid_{pid}");
        vc.pid_requirements
            .get(&pid_key)
            .cloned()
            .ok_or_else(|| MapperError::PidNotFound {
                fv: fv.to_string(),
                variant: variant.to_string(),
                pid: pid.to_string(),
            })
    }

    /// Return the PID-agnostic [`Bo4eCatalog`] for a format version.
    ///
    /// The catalog contains one entry per BO4E type (BO, COM, Enum) parsed from
    /// `bo4e-german` source at compile-mappings time. Used by Stammdatenaufbau in
    /// downstream services.
    pub fn bo4e_catalog(
        &self,
        fv: &str,
    ) -> Result<mig_bo4e::bo4e_catalog::Bo4eCatalog, MapperError> {
        self.ensure_bundle_loaded(fv)?;
        let bundles = self.bundles.lock().unwrap();
        let bundle = bundles.get(fv).unwrap();
        Ok(bundle.bo4e_catalog.clone())
    }

    /// List all PIDs available across all format versions found in the data directory.
    ///
    /// Scans for `edifact-data-{FV}.bin` files, loads each bundle, and returns
    /// one entry per PID per variant. Results are sorted by PID.
    pub fn list_pids(&self) -> Result<Vec<PidListEntry>, MapperError> {
        let dir = self.data_dir.data_path();
        let read_dir = std::fs::read_dir(dir).map_err(|_| MapperError::DataDirNotFound {
            path: dir.display().to_string(),
        })?;

        let mut result = Vec::new();

        for entry in read_dir.flatten() {
            let path = entry.path();
            if path.extension().is_some_and(|e| e == "bin") {
                let stem = path
                    .file_stem()
                    .and_then(|s| s.to_str())
                    .unwrap_or("")
                    .to_string();
                let fv = match stem.strip_prefix("edifact-data-") {
                    Some(v) => v.to_string(),
                    None => continue,
                };
                self.ensure_bundle_loaded(&fv)?;
                let bundles = self.bundles.lock().unwrap();
                if let Some(bundle) = bundles.get(&fv) {
                    for (variant, vc) in &bundle.variants {
                        for (pid_key, req) in &vc.pid_requirements {
                            let pid = pid_key.strip_prefix("pid_").unwrap_or(pid_key).to_string();
                            result.push(PidListEntry {
                                fv: fv.clone(),
                                variant: variant.clone(),
                                pid,
                                beschreibung: req.beschreibung.clone(),
                            });
                        }
                    }
                }
            }
        }

        result.sort_by(|a, b| a.pid.cmp(&b.pid));
        Ok(result)
    }

    /// Validate a BO4E JSON object against PID requirements.
    ///
    /// Returns a list of validation errors. Empty list = valid.
    /// The `json` should be the transaction-level stammdaten (the entity map).
    pub fn validate_pid(
        &self,
        json: &serde_json::Value,
        fv: &str,
        variant: &str,
        pid: &str,
    ) -> Result<Vec<mig_bo4e::PidValidationError>, MapperError> {
        self.ensure_bundle_loaded(fv)?;
        let bundles = self.bundles.lock().unwrap();
        let bundle = bundles.get(fv).unwrap();
        let vc = bundle
            .variant(variant)
            .ok_or_else(|| MapperError::VariantNotFound {
                fv: fv.to_string(),
                variant: variant.to_string(),
            })?;
        let pid_key = format!("pid_{pid}");
        let requirements =
            vc.pid_requirements
                .get(&pid_key)
                .ok_or_else(|| MapperError::PidNotFound {
                    fv: fv.to_string(),
                    variant: variant.to_string(),
                    pid: pid.to_string(),
                })?;

        Ok(mig_bo4e::pid_validation::validate_pid_json(
            json,
            requirements,
        ))
    }

    /// Validate a typed BO4E struct against PID requirements.
    ///
    /// Convenience wrapper that serializes the struct to JSON first.
    /// Works with any `Pid*Interchange` or `Pid*MessageStammdaten` type.
    ///
    /// # Example
    /// ```ignore
    /// let interchange = build_55001_interchange();
    /// let errors = mapper.validate_pid_struct(&interchange, "FV2504", "UTILMD_Strom", "55001")?;
    /// assert!(errors.is_empty(), "Errors:\n{}", ValidationReport(errors));
    /// ```
    pub fn validate_pid_struct(
        &self,
        value: &impl serde::Serialize,
        fv: &str,
        variant: &str,
        pid: &str,
    ) -> Result<Vec<mig_bo4e::PidValidationError>, MapperError> {
        let json = serde_json::to_value(value).map_err(|e| {
            MapperError::Mapping(mig_bo4e::MappingError::TypeConversion(e.to_string()))
        })?;
        self.validate_pid(&json, fv, variant, pid)
    }

    /// Validate with AHB condition awareness.
    ///
    /// Reverse-maps the JSON to EDIFACT segments, evaluates AHB conditions,
    /// and reports fields as required/optional based on the actual data present.
    ///
    /// Falls back to basic validation (without conditions) if no condition
    /// evaluator is available for the given variant/format version combination.
    pub fn validate_pid_with_conditions(
        &self,
        json: &serde_json::Value,
        fv: &str,
        variant: &str,
        pid: &str,
    ) -> Result<Vec<mig_bo4e::PidValidationError>, MapperError> {
        self.ensure_bundle_loaded(fv)?;
        let bundles = self.bundles.lock().unwrap();
        let bundle = bundles.get(fv).unwrap();
        let vc = bundle
            .variant(variant)
            .ok_or_else(|| MapperError::VariantNotFound {
                fv: fv.to_string(),
                variant: variant.to_string(),
            })?;
        let pid_key = format!("pid_{pid}");

        let requirements =
            vc.pid_requirements
                .get(&pid_key)
                .ok_or_else(|| MapperError::PidNotFound {
                    fv: fv.to_string(),
                    variant: variant.to_string(),
                    pid: pid.to_string(),
                })?;

        // Try to get a condition evaluator for this variant
        let evaluator = crate::evaluator_factory::create_evaluator(variant, fv);

        if let Some(evaluator) = evaluator {
            // Reverse-map JSON to EDIFACT segments for condition evaluation context
            let defs = vc
                .combined_defs
                .get(&pid_key)
                .ok_or_else(|| MapperError::PidNotFound {
                    fv: fv.to_string(),
                    variant: variant.to_string(),
                    pid: pid.to_string(),
                })?;
            let engine = MappingEngine::from_definitions_with_code_lists(
                std::sync::Arc::clone(&vc.code_lists),
                defs.clone(),
            );
            let tree = engine.map_all_reverse(json, None);

            // Convert AssembledTree to flat OwnedSegments for EvaluationContext
            let segments = crate::tree_to_segments::tree_to_owned_segments(&tree);

            // Validate with condition awareness
            Ok(crate::evaluator_factory::validate_with_boxed_evaluator(
                evaluator.as_ref(),
                json,
                requirements,
                pid,
                &segments,
            ))
        } else {
            // No evaluator available — fall back to basic validation
            Ok(mig_bo4e::pid_validation::validate_pid_json_transaction(
                json,
                requirements,
            ))
        }
    }

    /// Convert BO4E JSON back to an EDIFACT string.
    ///
    /// Takes message-level stammdaten, a slice of per-transaction stammdaten,
    /// and produces an EDIFACT message body (UNH through UNT content segments,
    /// without UNB/UNZ interchange envelope).
    ///
    /// # Arguments
    ///
    /// * `msg_stammdaten` — message-level entities (e.g., Marktteilnehmer from SG2)
    /// * `tx_stammdaten` — per-transaction entities (one per transaction/SG4 instance)
    /// * `fv` — format version (e.g., "FV2504")
    /// * `variant` — message variant (e.g., "UTILMD_Strom")
    /// * `pid` — Pruefidentifikator (e.g., "55001")
    ///
    /// # Round-tripping output of [`from_edifact`](Self::from_edifact)
    ///
    /// `msg_stammdaten` is only half of what the forward direction produced.
    /// The message header — `nachrichtentyp`, `nachrichtennummer`,
    /// `erstellungsdatum`, i.e. the wire's `BGM` and `DTM+137` — is in
    /// `nachrichtendaten`, not in `stammdaten`, so passing `stammdaten` alone
    /// renders a body without its header and reports nothing (issue #158).
    /// Use [`to_edifact_nachricht`](Self::to_edifact_nachricht), which takes
    /// both halves.
    ///
    /// # Code fields: names or raw codes
    ///
    /// Where the guide gives a code list, [`from_edifact`](Self::from_edifact)
    /// writes a code as its name (`NAD+Z65` → `"partnerrolle": "kundeDesLf"`);
    /// the name is the canonical form. This method accepts either: a name is
    /// written back as its code, and any other value — the raw code `"Z65"`
    /// included — is written as it is, so both render the same message. No
    /// code table has a code that is also one of its names, so the two cannot
    /// be confused. Pinned by `tests/raw_codes_render_like_names.rs`.
    ///
    /// # Example
    ///
    /// ```ignore
    /// let edifact = mapper.to_edifact(
    ///     &msg_json,
    ///     &[tx_json],
    ///     "FV2504",
    ///     "UTILMD_Strom",
    ///     "55001",
    /// )?;
    /// ```
    ///
    /// # Errors
    ///
    /// Besides lookup failures, returns [`MapperError::MissingGroupEntrySegment`]
    /// when the BO4E fills some of a segment group's fields but not the one its
    /// entry segment is built from — e.g. a `zaehler` with `geraeteNummer` but no
    /// `zaehlertypMerkmal`, which would render SG10 `CAV` without `CCI`. Such a
    /// message cannot be parsed back; its group content would be lost.
    pub fn to_edifact(
        &self,
        msg_stammdaten: &serde_json::Value,
        tx_stammdaten: &[serde_json::Value],
        fv: &str,
        variant: &str,
        pid: &str,
    ) -> Result<String, MapperError> {
        self.render_message_body(
            msg_stammdaten,
            tx_stammdaten,
            fv,
            variant,
            pid,
            EntrySegmentCheck::Refuse,
        )
    }

    /// Render one message body from a [`Nachricht`] as [`from_edifact`] produced it.
    ///
    /// The forward direction splits a message in two: the business objects go to
    /// `stammdaten`, and the message header — `nachrichtentyp`,
    /// `nachrichtennummer`, `erstellungsdatum`, which are the `BGM` and
    /// `DTM+137` of the wire — goes to `nachrichtendaten` beside it.
    /// [`to_edifact`] takes only the first half, so handing it `stammdaten`
    /// alone renders a body without its header and says nothing (issue #158).
    ///
    /// This takes both, so a caller can give back what it was given:
    ///
    /// ```ignore
    /// let interchange = mapper.from_edifact::<Value, Value>(&edifact, fv, variant, pid)?;
    /// let body = mapper.to_edifact_nachricht(&interchange.nachrichten[0], fv, variant, pid)?;
    /// ```
    ///
    /// Only the body: the `UNB`/`UNH`/`UNT`/`UNZ` envelope is
    /// [`to_edifact_interchange`](Self::to_edifact_interchange)'s job.
    ///
    /// # Errors
    ///
    /// As [`to_edifact`].
    ///
    /// [`to_edifact`]: Self::to_edifact
    /// [`from_edifact`]: Self::from_edifact
    /// [`Nachricht`]: mig_bo4e::model::Nachricht
    pub fn to_edifact_nachricht(
        &self,
        nachricht: &mig_bo4e::model::Nachricht<serde_json::Value, serde_json::Value>,
        fv: &str,
        variant: &str,
        pid: &str,
    ) -> Result<String, MapperError> {
        let mut msg_stammdaten = nachricht.stammdaten.clone();
        mig_bo4e::model::restore_message_metadata(&mut msg_stammdaten, &nachricht.nachrichtendaten);
        self.to_edifact(&msg_stammdaten, &nachricht.transaktionen, fv, variant, pid)
    }

    /// Reverse-map and render one message body. `check` decides what happens to
    /// a group instance lacking its MIG entry segment: [`to_edifact`] refuses
    /// it, [`validate_bo4e`] renders it so the validator can report the defect
    /// as findings instead of failing the whole validation.
    ///
    /// [`to_edifact`]: Self::to_edifact
    /// [`validate_bo4e`]: Self::validate_bo4e
    fn render_message_body(
        &self,
        msg_stammdaten: &serde_json::Value,
        tx_stammdaten: &[serde_json::Value],
        fv: &str,
        variant: &str,
        pid: &str,
        check: EntrySegmentCheck,
    ) -> Result<String, MapperError> {
        self.ensure_bundle_loaded(fv)?;
        let bundles = self.bundles.lock().unwrap();
        let bundle = bundles.get(fv).unwrap();
        let vc = bundle
            .variant(variant)
            .ok_or_else(|| MapperError::VariantNotFound {
                fv: fv.to_string(),
                variant: variant.to_string(),
            })?;

        let tx_group = vc.tx_group(pid).ok_or_else(|| MapperError::PidNotFound {
            fv: fv.to_string(),
            variant: variant.to_string(),
            pid: pid.to_string(),
        })?;

        let msg_engine = vc.msg_engine(pid);
        let tx_engine = vc.tx_engine(pid).ok_or_else(|| MapperError::PidNotFound {
            fv: fv.to_string(),
            variant: variant.to_string(),
            pid: pid.to_string(),
        })?;

        let filtered_mig = vc
            .filtered_mig(pid)
            .ok_or_else(|| MapperError::NoMigSchema {
                fv: fv.to_string(),
                variant: variant.to_string(),
            })?;

        // Build MappedMessage from the provided JSON
        let transaktionen: Vec<mig_bo4e::model::MappedTransaktion> =
            tx_stammdaten.iter().map(split_transaktion).collect();
        let mapped = mig_bo4e::model::MappedMessage {
            nachricht_meta: serde_json::Value::Null,
            stammdaten: msg_stammdaten.clone(),
            transaktionen,
            nesting_info: Default::default(),
            inter_group_segments: Default::default(),
        };

        // Reverse map → AssembledTree
        let tree = MappingEngine::map_interchange_reverse(
            &msg_engine,
            &tx_engine,
            &mapped,
            tx_group,
            Some(&filtered_mig),
        );

        // Disassemble → ordered segments. A group instance whose MIG entry
        // segment is missing (e.g. SG10 with CAV but no CCI because the BO4E
        // lacks the field the CCI is built from) renders EDIFACT that no
        // receiver can assemble, so by default it is refused (#103).
        let disassembler = mig_assembly::disassembler::Disassembler::new(&filtered_mig);
        let checked = match check {
            EntrySegmentCheck::Refuse => disassembler.disassemble_checked(&tree),
            EntrySegmentCheck::Render => Ok(disassembler.disassemble(&tree)),
        };
        let segments = checked.map_err(|e| match e {
            mig_assembly::AssemblyError::MissingGroupEntrySegment {
                group_path,
                source_path,
                entry_segment,
                present_segments,
            } => {
                let (entities, entry_fields) = describe_entry_segment_mappings(
                    [msg_engine.definitions(), tx_engine.definitions()],
                    &source_path,
                    &entry_segment,
                );
                MapperError::MissingGroupEntrySegment(Box::new(
                    crate::error::GroupEntrySegmentError {
                        pid: pid.to_string(),
                        group_path,
                        source_path,
                        entry_segment,
                        present_segments,
                        entities,
                        entry_fields,
                    },
                ))
            }
            other => MapperError::Assembly(other),
        })?;

        // Render to EDIFACT string with default delimiters
        let delimiters = edifact_primitives::EdifactDelimiters::default();
        Ok(mig_assembly::renderer::render_edifact(
            &segments,
            &delimiters,
        ))
    }

    /// Convert a typed BO4E struct to an EDIFACT string.
    ///
    /// Convenience wrapper that serializes the struct to JSON first.
    /// The struct should serialize to the `Nachricht` shape:
    /// `{ "stammdaten": {...}, "transaktionen": [{...}] }`
    pub fn to_edifact_struct(
        &self,
        nachricht: &impl serde::Serialize,
        fv: &str,
        variant: &str,
        pid: &str,
    ) -> Result<String, MapperError> {
        let json = serde_json::to_value(nachricht)
            .map_err(|e| MapperError::Serialization(e.to_string()))?;

        let msg_stammdaten = json
            .get("stammdaten")
            .cloned()
            .unwrap_or(serde_json::Value::Object(Default::default()));

        let tx_stammdaten: Vec<serde_json::Value> = json
            .get("transaktionen")
            .and_then(|v| v.as_array())
            .cloned()
            .unwrap_or_default();

        self.to_edifact(&msg_stammdaten, &tx_stammdaten, fv, variant, pid)
    }

    /// Parse an EDIFACT interchange string into a typed PID interchange struct.
    ///
    /// Runs the full pipeline: tokenize → split messages → assemble → forward-map → deserialize.
    /// The type parameters `M` and `T` are the message-level and transaction-level
    /// stammdaten types from the generated PID module.
    ///
    /// # Example
    ///
    /// ```ignore
    /// use bo4e_edifact_types::generated::fv2504::utilmd::pids::pid_55001::*;
    ///
    /// let interchange: Interchange<Pid55001MsgStammdaten, Pid55001TxStammdaten> =
    ///     mapper.from_edifact(edifact_str, "FV2504", "UTILMD_Strom", "55001")?;
    ///
    /// let tx = &interchange.nachrichten[0].transaktionen[0];
    /// println!("Vorgang: {}", tx.prozessdaten.vorgang_id);
    /// ```
    ///
    /// Mapping is lossy for content the assembler cannot place: segments the
    /// PID's AHB does not cover, and segments whose group lacks its entry segment
    /// (e.g. SG10 `CAV` without `CCI`). They have no BO4E representation and are
    /// dropped. The conversion still succeeds, so that everything else in the
    /// message is available; each dropped segment is logged as a `tracing`
    /// warning. Use [`from_edifact_with_diagnostics`] to inspect them in code
    /// (e.g. to reject such messages).
    ///
    /// [`from_edifact_with_diagnostics`]: Self::from_edifact_with_diagnostics
    pub fn from_edifact<M, T>(
        &self,
        edifact: &str,
        fv: &str,
        variant: &str,
        pid: &str,
    ) -> Result<mig_bo4e::model::Interchange<M, T>, MapperError>
    where
        M: serde::de::DeserializeOwned,
        T: serde::de::DeserializeOwned,
    {
        let (interchange, diagnostics) =
            self.from_edifact_with_diagnostics(edifact, fv, variant, pid)?;
        // This signature has no room for diagnostics, and dropped content must
        // not go unnoticed (#103): log it for callers that don't ask for it.
        for d in &diagnostics {
            tracing::warn!(
                fv,
                variant,
                pid,
                kind = ?d.kind,
                segment = %d.segment_id,
                position = d.position,
                "from_edifact: {}",
                d.message
            );
        }
        Ok(interchange)
    }

    /// [`from_edifact`], plus the structure diagnostics raised while assembling.
    ///
    /// A non-empty diagnostic list does not mean the conversion failed — it means
    /// the BO4E result does not represent everything the EDIFACT carried. In
    /// particular [`SkippedUnknownSegment`] marks a segment outside the PID's AHB
    /// that the assembler advanced past, and [`OrphanedGroupSegment`] a segment
    /// the MIG defines but whose group's entry segment is missing; in both cases
    /// its content is absent from the result.
    ///
    /// [`from_edifact`]: Self::from_edifact
    /// [`SkippedUnknownSegment`]: mig_assembly::StructureDiagnosticKind::SkippedUnknownSegment
    /// [`OrphanedGroupSegment`]: mig_assembly::StructureDiagnosticKind::OrphanedGroupSegment
    pub fn from_edifact_with_diagnostics<M, T>(
        &self,
        edifact: &str,
        fv: &str,
        variant: &str,
        pid: &str,
    ) -> Result<
        (
            mig_bo4e::model::Interchange<M, T>,
            Vec<mig_assembly::StructureDiagnostic>,
        ),
        MapperError,
    >
    where
        M: serde::de::DeserializeOwned,
        T: serde::de::DeserializeOwned,
    {
        self.ensure_bundle_loaded(fv)?;
        let bundles = self.bundles.lock().unwrap();
        let bundle = bundles.get(fv).unwrap();
        let vc = bundle
            .variant(variant)
            .ok_or_else(|| MapperError::VariantNotFound {
                fv: fv.to_string(),
                variant: variant.to_string(),
            })?;

        let tx_group = vc.tx_group(pid).ok_or_else(|| MapperError::PidNotFound {
            fv: fv.to_string(),
            variant: variant.to_string(),
            pid: pid.to_string(),
        })?;

        let msg_engine = vc.msg_engine(pid);
        let tx_engine = vc.tx_engine(pid).ok_or_else(|| MapperError::PidNotFound {
            fv: fv.to_string(),
            variant: variant.to_string(),
            pid: pid.to_string(),
        })?;

        let filtered_mig = vc
            .filtered_mig(pid)
            .ok_or_else(|| MapperError::NoMigSchema {
                fv: fv.to_string(),
                variant: variant.to_string(),
            })?;

        // Tokenize → split → assemble. Same assembler config as the v2 `convert`
        // route: `strict_code_matching` disambiguates merged sibling slots, and
        // `skip_unknown_segments` keeps the cursor moving past AHB-foreign
        // segments — without it the cursor stalls on the first one and the whole
        // message tail is silently dropped from the BO4E result.
        let svc = ConversionService::from_mig(filtered_mig);
        let (chunks, trees, assembly_diagnostics) = svc
            .convert_interchange_to_trees_with_diagnostics(
                edifact,
                mig_assembly::assembler::AssemblerConfig {
                    strict_code_matching: true,
                    skip_unknown_segments: true,
                    ..Default::default()
                },
            )?;

        let tree = trees.first().ok_or_else(|| {
            MapperError::Assembly(mig_assembly::AssemblyError::ParseError(
                "No messages in interchange".to_string(),
            ))
        })?;

        // Extract envelope metadata
        let interchangedaten = mig_bo4e::model::extract_interchangedaten(&chunks.envelope);
        let msg_chunk = chunks.messages.first().ok_or_else(|| {
            MapperError::Assembly(mig_assembly::AssemblyError::ParseError(
                "No message chunks".to_string(),
            ))
        })?;
        let (unh_ref, nachrichten_typ) = mig_bo4e::model::extract_unh_fields(&msg_chunk.unh);
        let nachrichtendaten = mig_bo4e::model::Nachrichtendaten {
            unh_referenz: unh_ref,
            nachrichten_typ,
            nachricht: Default::default(),
        };

        // Forward-map to typed interchange
        let interchange = MappingEngine::map_interchange_typed::<M, T>(
            &msg_engine,
            &tx_engine,
            tree,
            tx_group,
            true,
            nachrichtendaten,
            interchangedaten,
        )
        .map_err(|e| MapperError::Serialization(e.to_string()))?;

        Ok((interchange, assembly_diagnostics))
    }

    /// Detect the PID (Pruefidentifikator) from a raw EDIFACT interchange.
    ///
    /// Tokenizes the input, splits into messages, and extracts the PID from the
    /// first message using the RFF+Z13 segment (primary) or BGM+STS fallback.
    ///
    /// This enables inbound message processing where the PID is not known upfront:
    ///
    /// ```ignore
    /// let pid = mapper.detect_pid(edifact_str)?;
    /// let interchange: MyType = mapper.from_edifact(edifact_str, "FV2504", "UTILMD_Strom", &pid)?;
    /// ```
    pub fn detect_pid(&self, edifact: &str) -> Result<String, MapperError> {
        let segments = mig_assembly::tokenize::parse_to_segments(edifact.as_bytes())?;
        let chunks = mig_assembly::split_messages(segments)?;
        let msg_chunk = chunks.messages.first().ok_or_else(|| {
            MapperError::Assembly(mig_assembly::AssemblyError::ParseError(
                "No messages found in EDIFACT content".to_string(),
            ))
        })?;
        let msg_segments = msg_chunk.message_segments();
        mig_assembly::pid_detect::detect_pid(&msg_segments).map_err(MapperError::Assembly)
    }

    /// Validate raw EDIFACT against its AHB rules.
    ///
    /// This is the same pipeline as the v2 API's `POST /api/v2/validate`
    /// (`run_validation`) — both call [`validate_edifact_message`] — exposed here
    /// as a library call so consumers (e.g. mako.hive) get full raw-EDIFACT
    /// validation without running the API server. Detects the PID, resolves the
    /// owning variant + its pre-built [`AhbWorkflow`] from the loaded bundle,
    /// assembles the message, and runs the shared validation core.
    ///
    /// Requires the bundle for `fv` to carry `pid_ahb_workflows` (baked in at
    /// compile-mappings). Returns [`MapperError::PidNotFound`] if no loaded variant
    /// has a workflow for the detected PID.
    ///
    /// [`validate_edifact_message`]: automapper_validation::validate_edifact_message
    /// [`AhbWorkflow`]: automapper_validation::AhbWorkflow
    pub fn validate_edifact(
        &self,
        edifact: &str,
        fv: &str,
        level: automapper_validation::ValidationLevel,
    ) -> Result<automapper_validation::ValidationReport, MapperError> {
        self.validate_edifact_inner(edifact, fv, None, level)
    }

    /// [`validate_edifact`], but validating against a PID the caller already knows.
    ///
    /// Use this when the PID comes from somewhere other than the message — a form,
    /// a route, a job definition. It skips PID detection, which only works for
    /// message types that carry the Prüfidentifikator in `RFF+Z13` (UTILMD); for
    /// ORDERS, MSCONS, IFTSTA and the rest, detection cannot recover a PID that the
    /// caller already has.
    ///
    /// [`validate_edifact`]: Self::validate_edifact
    pub fn validate_edifact_for_pid(
        &self,
        edifact: &str,
        fv: &str,
        variant: &str,
        pid: &str,
        level: automapper_validation::ValidationLevel,
    ) -> Result<automapper_validation::ValidationReport, MapperError> {
        self.validate_edifact_inner(edifact, fv, Some((variant, pid)), level)
    }

    fn validate_edifact_inner(
        &self,
        edifact: &str,
        fv: &str,
        known: Option<(&str, &str)>,
        level: automapper_validation::ValidationLevel,
    ) -> Result<automapper_validation::ValidationReport, MapperError> {
        self.ensure_bundle_loaded(fv)?;
        let bundles = self.bundles.lock().unwrap();
        let bundle = bundles.get(fv).unwrap();

        // Tokenize → split → first message (same as `detect_pid`).
        let segments = mig_assembly::tokenize::parse_to_segments(edifact.as_bytes())?;
        let chunks = mig_assembly::split_messages(segments)?;
        let msg_chunk = chunks.messages.first().ok_or_else(|| {
            MapperError::Assembly(mig_assembly::AssemblyError::ParseError(
                "No messages found in EDIFACT content".to_string(),
            ))
        })?;

        // Resolve the PID: detect it when the caller doesn't know it, and resolve
        // the owning variant from the bundle. When the caller does know both (the
        // `validate_bo4e` path), take them as given — detection only works for
        // message types that carry the PID in RFF+Z13 (UTILMD), so re-deriving a
        // PID the caller already supplied would fail on ORDERS, MSCONS, IFTSTA, …
        let (pid, variant, vc) = match known {
            Some((variant, pid)) => {
                let vc = bundle
                    .variant(variant)
                    .ok_or_else(|| MapperError::VariantNotFound {
                        fv: fv.to_string(),
                        variant: variant.to_string(),
                    })?;
                (pid.to_string(), variant.to_string(), vc)
            }
            None => {
                let pid = mig_assembly::pid_detect::detect_pid(&msg_chunk.message_segments())
                    .map_err(MapperError::Assembly)?;
                let pid_key = format!("pid_{pid}");
                let (variant, vc) = bundle
                    .variants
                    .iter()
                    .find(|(_, vc)| vc.pid_ahb_workflows.contains_key(&pid_key))
                    .ok_or_else(|| MapperError::PidNotFound {
                        fv: fv.to_string(),
                        variant: "?".to_string(),
                        pid: pid.clone(),
                    })?;
                (pid, variant.clone(), vc)
            }
        };
        let pid_key = format!("pid_{pid}");

        let workflow =
            vc.pid_ahb_workflows
                .get(&pid_key)
                .ok_or_else(|| MapperError::PidNotFound {
                    fv: fv.to_string(),
                    variant: variant.clone(),
                    pid: pid.clone(),
                })?;
        let filtered_mig = vc
            .filtered_mig(&pid)
            .ok_or_else(|| MapperError::NoMigSchema {
                fv: fv.to_string(),
                variant: variant.clone(),
            })?;

        // Segments the validator sees: this message's body for the filtered MIG,
        // plus the interchange UNZ when the MIG covers it (e.g. MSCONS).
        let mut all_segments = msg_chunk.segments_for_mig(&filtered_mig);
        if filtered_mig.segments.iter().any(|s| s.id == "UNZ") {
            if let Some(unz) = &chunks.unz {
                all_segments.push(unz.clone());
            }
        }

        // Same evaluator resolution + fallback the v2 route uses. The explicit
        // target type lets each arm coerce (Box<dyn> → Arc<dyn>; Arc<Concrete> →
        // Arc<dyn> unsize) — a `.map(Arc::from)` chain can't infer that.
        let evaluator: std::sync::Arc<dyn automapper_validation::ConditionEvaluator> =
            match crate::evaluator_factory::create_evaluator(&variant, fv) {
                Some(boxed) => std::sync::Arc::from(boxed),
                None => std::sync::Arc::new(
                    automapper_validation::UtilmdStromConditionEvaluatorFV2504::default(),
                ),
            };
        let external = automapper_validation::eval::NoOpExternalProvider;

        let mut report = automapper_validation::validate_edifact_message(
            &all_segments,
            &filtered_mig,
            workflow,
            evaluator,
            &external,
            level,
        );

        // Enrich findings with BO4E field paths so consumers can map the
        // segment-path findings back to the BO4E form (same enrichment the v2
        // `validate-bo4e` route applies). Sourced entirely from the bundle: the
        // combined mapping defs, the PID-filtered MIG, and a reverse resolver
        // built from the full MIG — no generated schema files needed.
        if let (Some(mig), Some(defs)) = (vc.mig_schema.as_ref(), vc.combined_defs.get(&pid_key)) {
            let reverse = mig_bo4e::path_resolver::ReversePathResolver::from_mig(mig);
            let field_index =
                mig_bo4e::Bo4eFieldIndex::build_with_resolver(defs, &filtered_mig, &reverse);
            report.enrich_bo4e_paths(|path, hint| field_index.resolve(path, hint));
        }

        Ok(report)
    }

    /// Validate BO4E JSON against the AHB rules of its Prüfidentifikator.
    ///
    /// This is [`validate_edifact`] with a reverse-mapping front end: the BO4E
    /// input is rendered to a complete EDIFACT interchange
    /// ([`to_edifact_interchange`]) and that interchange is validated. Because it
    /// is literally the same call, the findings are the ones the EDIFACT
    /// validation reports for the message this BO4E describes — including the
    /// `bo4e_path` enrichment that points each finding back at the BO4E field it
    /// came from. Callers working in BO4E (forms, assistants) therefore do not
    /// need their own EDIFACT-path-to-BO4E-path translation.
    ///
    /// `envelope` fills UNB/UNZ. Pass `None` unless the message type's MIG covers
    /// the interchange envelope (e.g. MSCONS) — for the others the envelope is
    /// outside the AHB and a neutral placeholder is used.
    ///
    /// Two classes of finding cannot appear here, because the BO4E input has no
    /// counterpart for them: the UNT segment-count check (the trailer is
    /// regenerated) and skipped-unknown-segment diagnostics (segments outside the
    /// AHB have no BO4E representation).
    ///
    /// [`validate_edifact`]: Self::validate_edifact
    /// [`to_edifact_interchange`]: Self::to_edifact_interchange
    pub fn validate_bo4e(
        &self,
        msg_stammdaten: &serde_json::Value,
        tx_stammdaten: &[serde_json::Value],
        fv: &str,
        variant: &str,
        pid: &str,
        envelope: Option<&InterchangeEnvelope>,
        level: automapper_validation::ValidationLevel,
    ) -> Result<automapper_validation::ValidationReport, MapperError> {
        let placeholder;
        let envelope = match envelope {
            Some(e) => e,
            None => {
                placeholder = InterchangeEnvelope {
                    sender: EdifactParty::bdew("9900000000001"),
                    receiver: EdifactParty::bdew("9900000000002"),
                    interchange_ref: "1".to_string(),
                };
                &placeholder
            }
        };

        // Rendered without the entry-segment check `to_edifact_interchange`
        // applies: a group missing its entry segment is exactly the kind of
        // defect validation exists to report (as missing-field and structure
        // findings), so it must not abort the validation.
        let edifact = self.render_interchange(
            envelope,
            &[InterchangeMessage {
                message_ref: "1".to_string(),
                msg_stammdaten: msg_stammdaten.clone(),
                tx_stammdaten: tx_stammdaten.to_vec(),
                fv: fv.to_string(),
                variant: variant.to_string(),
                pid: pid.to_string(),
            }],
            EntrySegmentCheck::Render,
            &EnvelopeOptions::default(),
        )?;

        // The PID is given, not detected: for every message type but UTILMD the
        // rendered EDIFACT carries no RFF+Z13 to detect it from.
        self.validate_edifact_for_pid(&edifact, fv, variant, pid, level)
    }

    /// Get the UNH association code for a variant (e.g., `"S2.1"`, `"2.4c"`).
    ///
    /// This is the version string from the MIG schema, used as the last component
    /// of the UNH S009 composite: `UTILMD:D:11A:UN:S2.1`.
    ///
    /// # Example
    /// ```ignore
    /// let code = mapper.association_code("FV2604", "UTILMD_Strom")?;
    /// assert_eq!(code, "S2.1");
    /// ```
    pub fn association_code(&self, fv: &str, variant: &str) -> Result<String, MapperError> {
        let meta = self.message_metadata(fv, variant)?;
        Ok(meta.association_code)
    }

    /// Get full message metadata for a variant, including the UNH S009 components.
    ///
    /// Returns the message type, UN/EDIFACT release code, and association code
    /// needed to construct UNH segments.
    pub fn message_metadata(
        &self,
        fv: &str,
        variant: &str,
    ) -> Result<MessageMetadata, MapperError> {
        self.ensure_bundle_loaded(fv)?;
        let bundles = self.bundles.lock().unwrap();
        let bundle = bundles.get(fv).unwrap();
        let vc = bundle
            .variant(variant)
            .ok_or_else(|| MapperError::VariantNotFound {
                fv: fv.to_string(),
                variant: variant.to_string(),
            })?;
        let mig = vc
            .mig_schema
            .as_ref()
            .ok_or_else(|| MapperError::NoMigSchema {
                fv: fv.to_string(),
                variant: variant.to_string(),
            })?;
        Ok(MessageMetadata {
            message_type: mig.message_type.clone(),
            release: release_code_for_message_type(&mig.message_type),
            association_code: mig.version.clone(),
        })
    }

    /// Convert BO4E JSON to a complete EDIFACT interchange with envelope segments.
    ///
    /// Produces a full interchange including UNA, UNB, UNH, message body, UNT, and UNZ.
    ///
    /// # The envelope is regenerated, not reproduced
    ///
    /// This always emits a `UNA` service string advice and stamps the `UNB`
    /// date and time from the clock, so a render is never byte-identical to the
    /// interchange it came from: an input carrying no `UNA` gains one, and its
    /// interchange date becomes today (issue #161). That is right for a
    /// re-send, and wrong for a caller checking that a conversion did not
    /// change the message.
    ///
    /// Two ways to check that instead:
    ///
    /// - compare message **bodies**, which
    ///   [`to_edifact_nachricht`](Self::to_edifact_nachricht) renders without
    ///   any envelope;
    /// - or reproduce the envelope with
    ///   [`to_edifact_interchange_with`](Self::to_edifact_interchange_with) and
    ///   [`EnvelopeOptions`], which take the `UNA` decision and the `UNB` date
    ///   and time from the caller.
    ///
    /// Neither reproduces non-default delimiters: the whole render uses
    /// [`EdifactDelimiters::default`](edifact_primitives::EdifactDelimiters::default).
    ///
    /// # Example
    /// ```ignore
    /// let edifact = mapper.to_edifact_interchange(
    ///     &InterchangeEnvelope {
    ///         sender: EdifactParty::bdew("9900000000003"),
    ///         receiver: EdifactParty::bdew("9900000000001"),
    ///         interchange_ref: "REF001".to_string(),
    ///     },
    ///     &[InterchangeMessage {
    ///         message_ref: "MSG001".to_string(),
    ///         msg_stammdaten: serde_json::json!({"marktteilnehmer": []}),
    ///         tx_stammdaten: vec![serde_json::json!({"prozessdaten": {"pruefidentifikator": "55001"}})],
    ///         fv: "FV2604".to_string(),
    ///         variant: "UTILMD_Strom".to_string(),
    ///         pid: "55001".to_string(),
    ///     }],
    /// )?;
    /// assert!(edifact.starts_with("UNA:+.? '"));
    /// ```
    ///
    /// # Errors
    ///
    /// Fails like [`to_edifact`](Self::to_edifact), including
    /// [`MapperError::MissingGroupEntrySegment`] for a group that would be
    /// rendered without its entry segment.
    pub fn to_edifact_interchange(
        &self,
        envelope: &InterchangeEnvelope,
        messages: &[InterchangeMessage],
    ) -> Result<String, MapperError> {
        self.render_interchange(
            envelope,
            messages,
            EntrySegmentCheck::Refuse,
            &EnvelopeOptions::default(),
        )
    }

    /// Like [`to_edifact_interchange`](Self::to_edifact_interchange), with
    /// control over how the envelope is built.
    ///
    /// The default regenerates it — a fresh `UNA` and a `UNB` timestamped from
    /// the clock — which is right for a re-send but means a render can never
    /// equal its input. [`EnvelopeOptions`] lets a caller that has the original
    /// ask for it back instead (issue #161).
    ///
    /// # Errors
    ///
    /// As [`to_edifact_interchange`](Self::to_edifact_interchange).
    pub fn to_edifact_interchange_with(
        &self,
        envelope: &InterchangeEnvelope,
        messages: &[InterchangeMessage],
        options: &EnvelopeOptions,
    ) -> Result<String, MapperError> {
        self.render_interchange(envelope, messages, EntrySegmentCheck::Refuse, options)
    }

    fn render_interchange(
        &self,
        envelope: &InterchangeEnvelope,
        messages: &[InterchangeMessage],
        check: EntrySegmentCheck,
        options: &EnvelopeOptions,
    ) -> Result<String, MapperError> {
        let delimiters = edifact_primitives::EdifactDelimiters::default();
        let sep = delimiters.component as char;
        let elem = delimiters.element as char;
        let seg_term = delimiters.segment as char;

        let mut output = String::new();

        // UNA — Service string advice. Omitted on request: an input that
        // carried none should not gain one (issue #161).
        if options.emit_una {
            output.push_str(&format!(
                "UNA{}{}{}{}{}{}",
                sep,                        // component separator
                elem,                       // element separator
                delimiters.decimal as char, // decimal notation
                delimiters.release as char, // release/escape character
                ' ',                        // reserved (space)
                seg_term,                   // segment terminator
            ));
        }

        // UNB — Interchange header. The caller's date and time when it has
        // them, the clock otherwise.
        //
        // Checked here rather than in the builder: `datum_zeit` returns `Self`
        // so it cannot fail without spoiling the chaining, and this is the only
        // place that knows both values are present. A width-and-digits check is
        // all that is possible and all that is needed — it cannot know whether
        // a date is the right one, but it catches the two mistakes that happen,
        // an ISO date and a human-formatted time.
        check_unb_field("datum", "yymmdd", 6, options.datum.as_deref())?;
        check_unb_field("zeit", "hhmm", 4, options.zeit.as_deref())?;

        let now = chrono::Utc::now();
        let date_str = options
            .datum
            .clone()
            .unwrap_or_else(|| now.format("%y%m%d").to_string());
        let time_str = options
            .zeit
            .clone()
            .unwrap_or_else(|| now.format("%H%M").to_string());
        let sender = &envelope.sender;
        let receiver = &envelope.receiver;
        let interchange_ref = &envelope.interchange_ref;
        output.push_str(&format!(
            "UNB{elem}UNOC{sep}3{elem}{sid}{sep}{sq}{elem}{rid}{sep}{rq}{elem}{date_str}{sep}{time_str}{elem}{interchange_ref}{seg_term}",
            sid = sender.id,
            sq = sender.qualifier,
            rid = receiver.id,
            rq = receiver.qualifier,
        ));

        let mut message_count = 0u32;

        for msg in messages {
            let meta = self.message_metadata(&msg.fv, &msg.variant)?;

            // Generate body segments
            let body = self.render_message_body(
                &msg.msg_stammdaten,
                &msg.tx_stammdaten,
                &msg.fv,
                &msg.variant,
                &msg.pid,
                check,
            )?;

            // Count segments in body (split by segment terminator, filter empty)
            let body_seg_count = body
                .split(seg_term)
                .filter(|s: &&str| !s.is_empty())
                .count();
            // UNH + body segments + UNT = total segment count
            let segment_count = body_seg_count + 2;

            // UNH — Message header
            output.push_str(&format!(
                "UNH{elem}{ref}{elem}{msg_type}{sep}D{sep}{release}{sep}UN{sep}{assoc}{seg_term}",
                ref = msg.message_ref,
                msg_type = meta.message_type,
                release = meta.release,
                assoc = meta.association_code,
            ));

            // Body segments
            output.push_str(&body);

            // UNT — Message trailer
            output.push_str(&format!(
                "UNT{elem}{segment_count}{elem}{ref}{seg_term}",
                ref = msg.message_ref,
            ));

            message_count += 1;
        }

        // UNZ — Interchange trailer
        output.push_str(&format!(
            "UNZ{elem}{message_count}{elem}{interchange_ref}{seg_term}",
        ));

        Ok(output)
    }

    /// List all format versions currently loaded in memory.
    pub fn loaded_format_versions(&self) -> Vec<String> {
        self.bundles.lock().unwrap().keys().cloned().collect()
    }

    /// List all variants available in a format version's bundle.
    ///
    /// Loads the bundle if not already loaded.
    pub fn variants(&self, fv: &str) -> Result<Vec<String>, MapperError> {
        self.ensure_bundle_loaded(fv)?;
        let bundles = self.bundles.lock().unwrap();
        let bundle = bundles.get(fv).unwrap();
        Ok(bundle.variants.keys().cloned().collect())
    }
}

/// Metadata about a message type needed for constructing UNH segments.
#[derive(Debug, Clone)]
pub struct MessageMetadata {
    /// EDIFACT message type (e.g., `"UTILMD"`, `"MSCONS"`).
    pub message_type: String,
    /// UN/EDIFACT directory release code (e.g., `"11A"`, `"04B"`).
    pub release: String,
    /// Association-assigned code / MIG version (e.g., `"S2.1"`, `"2.4c"`).
    pub association_code: String,
}

/// Envelope parameters for [`Mapper::to_edifact_interchange`].
#[derive(Debug, Clone)]
pub struct InterchangeEnvelope {
    /// Sender party (UNB S002).
    pub sender: EdifactParty,
    /// Receiver party (UNB S003).
    pub receiver: EdifactParty,
    /// Unique interchange reference (UNB 0020 / UNZ 0020).
    pub interchange_ref: String,
}

/// Reject an `UNB` date or time that is not `digits` digits.
///
/// `None` means the caller did not supply one and the clock is used, which is
/// always well formed.
fn check_unb_field(
    field: &'static str,
    expected: &'static str,
    digits: usize,
    value: Option<&str>,
) -> Result<(), MapperError> {
    let Some(value) = value else {
        return Ok(());
    };
    if value.len() == digits && value.bytes().all(|b| b.is_ascii_digit()) {
        return Ok(());
    }
    Err(MapperError::MalformedEnvelopeDateTime {
        field,
        expected,
        digits,
        value: value.to_string(),
    })
}

/// How [`Mapper::to_edifact_interchange_with`] builds the interchange envelope.
///
/// The default is to **regenerate**: emit a `UNA` service string advice and
/// stamp the `UNB` date and time from the clock. That is right for a re-send,
/// and it is what [`Mapper::to_edifact_interchange`] does.
///
/// It is wrong for a caller comparing a render against its input, because the
/// two differences are not about the message (issue #161). Such a caller has
/// the original — the forward direction hands it back as `Interchangedaten` —
/// and can ask for it here.
///
/// ```ignore
/// let options = EnvelopeOptions::default()
///     .emit_una(false)
///     .datum_zeit_from(&interchange.interchangedaten);
/// ```
///
/// # What this cannot reproduce
///
/// Non-default delimiters. The whole render — envelope and body alike — uses
/// [`EdifactDelimiters::default`], so an input whose `UNA` declared other
/// delimiters cannot be reproduced, and `emit_una(true)` always advertises the
/// defaults. Suppressing the `UNA` is honest about that; claiming delimiters
/// the body does not honour would not be.
///
/// [`EdifactDelimiters::default`]: edifact_primitives::EdifactDelimiters::default
#[derive(Debug, Clone)]
pub struct EnvelopeOptions {
    emit_una: bool,
    datum: Option<String>,
    zeit: Option<String>,
}

impl Default for EnvelopeOptions {
    fn default() -> Self {
        Self {
            emit_una: true,
            datum: None,
            zeit: None,
        }
    }
}

impl EnvelopeOptions {
    /// Whether to emit the `UNA` service string advice. Default `true`.
    ///
    /// An input that carried no `UNA` gains one unless this is `false`.
    pub fn emit_una(mut self, emit: bool) -> Self {
        self.emit_una = emit;
        self
    }

    /// Interchange date (`yymmdd`) and time (`hhmm`) for `UNB`, instead of the
    /// clock.
    ///
    /// Both go into the header verbatim. A value that is not the right number
    /// of digits is refused when the interchange is rendered — with
    /// [`MapperError::MalformedEnvelopeDateTime`], not silently — because `UNB`
    /// is the segment whose defects surface at the receiving gateway rather
    /// than anywhere the sender looks.
    pub fn datum_zeit(mut self, datum: impl Into<String>, zeit: impl Into<String>) -> Self {
        self.datum = Some(datum.into());
        self.zeit = Some(zeit.into());
        self
    }

    /// Take the `UNB` date and time from the `Interchangedaten` the forward
    /// direction produced. Fields it does not carry are left to the clock.
    pub fn datum_zeit_from(mut self, daten: &mig_bo4e::model::Interchangedaten) -> Self {
        self.datum = daten.datum.clone();
        self.zeit = daten.zeit.clone();
        self
    }
}

/// An EDIFACT interchange party (sender or receiver) with codelist qualifier.
#[derive(Debug, Clone)]
pub struct EdifactParty {
    /// Party identification (e.g., MP-ID `"9900000000003"` or GLN `"4045458000000"`).
    pub id: String,
    /// Codelist qualifier: `"500"` = BDEW, `"14"` = GS1/EAN.
    pub qualifier: String,
}

impl EdifactParty {
    /// Create a party with BDEW codelist qualifier (500).
    pub fn bdew(id: &str) -> Self {
        Self {
            id: id.to_string(),
            qualifier: "500".to_string(),
        }
    }

    /// Create a party with GS1/EAN codelist qualifier (14).
    pub fn gs1(id: &str) -> Self {
        Self {
            id: id.to_string(),
            qualifier: "14".to_string(),
        }
    }
}

/// A single message to include in an interchange built by
/// [`Mapper::to_edifact_interchange`].
#[derive(Debug, Clone)]
pub struct InterchangeMessage {
    /// Unique message reference number (used in UNH/UNT).
    pub message_ref: String,
    /// Message-level stammdaten (e.g., marktteilnehmer).
    pub msg_stammdaten: serde_json::Value,
    /// Transaction-level stammdaten (one per transaction).
    pub tx_stammdaten: Vec<serde_json::Value>,
    /// Format version (e.g., `"FV2604"`).
    pub fv: String,
    /// Message variant (e.g., `"UTILMD_Strom"`).
    pub variant: String,
    /// Pruefidentifikator (e.g., `"55001"`).
    pub pid: String,
}

/// What rendering does with a group instance that lacks its MIG entry segment.
#[derive(Debug, Clone, Copy)]
enum EntrySegmentCheck {
    /// Fail with [`MapperError::MissingGroupEntrySegment`].
    Refuse,
    /// Render it anyway (for validation, which reports the defect).
    Render,
}

/// Find the mapping definitions for a group that rendered without its entry
/// segment, for the error message: the BO4E entities they fill, and the BO4E
/// fields the entry segment is built from (the data the caller has to supply).
///
/// `source_path` comes from the filtered MIG, where the variant qualifier of a
/// group may be absent (a PID with a single variant, or an instance whose
/// variant is unknown because its entry segment is missing: `sg4.sg8.sg10`)
/// while definitions carry one (`sg4.sg8_z03.sg10`), or the other way round.
/// An unqualified part therefore matches any variant of the same group.
fn describe_entry_segment_mappings<'d>(
    definition_sets: impl IntoIterator<Item = &'d [mig_bo4e::definition::MappingDefinition]>,
    source_path: &str,
    entry_segment: &str,
) -> (Vec<String>, Vec<String>) {
    fn qualifies(unqualified: &str, qualified: &str) -> bool {
        !unqualified.contains('_')
            && qualified.len() > unqualified.len()
            && qualified.is_char_boundary(unqualified.len())
            && qualified[..unqualified.len()].eq_ignore_ascii_case(unqualified)
            && qualified.as_bytes()[unqualified.len()] == b'_'
    }
    fn part_matches(mig_part: &str, def_part: &str) -> bool {
        def_part.eq_ignore_ascii_case(mig_part)
            || qualifies(mig_part, def_part)
            || qualifies(def_part, mig_part)
    }
    let mig_parts: Vec<&str> = source_path.split('.').collect();

    let mut entities: Vec<String> = Vec::new();
    let mut entry_fields: Vec<String> = Vec::new();
    for def in definition_sets.into_iter().flatten() {
        let Some(def_path) = def.meta.source_path.as_deref() else {
            continue;
        };
        let def_parts: Vec<&str> = def_path.split('.').collect();
        if def_parts.len() != mig_parts.len()
            || !mig_parts
                .iter()
                .zip(&def_parts)
                .all(|(m, d)| part_matches(m, d))
        {
            continue;
        }
        if !entities.contains(&def.meta.entity) {
            entities.push(def.meta.entity.clone());
        }
        for (path, mapping) in &def.fields {
            let tag = path
                .split(['.', '['])
                .next()
                .unwrap_or_default()
                .to_ascii_uppercase();
            let target = match mapping {
                mig_bo4e::definition::FieldMapping::Simple(t) => t.as_str(),
                mig_bo4e::definition::FieldMapping::Structured(f) => f.target.as_str(),
                mig_bo4e::definition::FieldMapping::Nested(_) => continue,
            };
            if tag == entry_segment && !target.is_empty() {
                let field = format!("{}.{}", def.meta.entity, target);
                if !entry_fields.contains(&field) {
                    entry_fields.push(field);
                }
            }
        }
    }
    (entities, entry_fields)
}

/// UN/EDIFACT directory release code for a message type.
///
/// These are stable per-message-type constants from the BDEW/DVGW specifications.
fn release_code_for_message_type(msg_type: &str) -> String {
    mig_bo4e::model::release_code_for_message_type(msg_type).to_string()
}

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

    fn data_dir() -> Option<std::path::PathBuf> {
        // Try dist/ first (pre-built data bundles), then cache/mappings/
        let dist = Path::new(env!("CARGO_MANIFEST_DIR")).join("../../dist");
        if dist.join("edifact-data-FV2504.bin").exists() {
            return Some(dist);
        }
        let cache = Path::new(env!("CARGO_MANIFEST_DIR")).join("../../cache/mappings");
        if cache.join("FV2504").exists() {
            return Some(cache);
        }
        eprintln!("Skipping test: no DataBundle files found");
        None
    }

    #[test]
    fn test_to_edifact_produces_edifact_output() {
        let Some(data_dir) = data_dir() else {
            return;
        };
        let mapper = Mapper::from_data_dir(DataDir::path(&data_dir).eager(&["FV2504"])).unwrap();

        let msg_stammdaten = serde_json::json!({
            "marktteilnehmer": [{
                "marktrolle": "MS",
                "rollencodenummer": "9900123456789",
                "codepflegeCode": "293"
            }]
        });
        let tx_stammdaten = serde_json::json!({
            "prozessdaten": {
                "pruefidentifikator": "55001",
                "vorgangId": "ABC123",
                "transaktionsgrund": "E01"
            }
        });

        let result = mapper.to_edifact(
            &msg_stammdaten,
            &[tx_stammdaten],
            "FV2504",
            "UTILMD_Strom",
            "55001",
        );
        assert!(result.is_ok(), "to_edifact failed: {:?}", result.err());
        let edifact = result.unwrap();
        assert!(!edifact.is_empty(), "EDIFACT output should not be empty");
        // Should produce NAD segment from marktteilnehmer
        assert!(edifact.contains("NAD"), "Should contain NAD segment");
        // Should produce IDE segment from prozessdaten
        assert!(edifact.contains("IDE"), "Should contain IDE segment");
    }

    #[test]
    fn test_to_edifact_struct_produces_edifact_output() {
        let Some(data_dir) = data_dir() else {
            return;
        };
        let mapper = Mapper::from_data_dir(DataDir::path(&data_dir).eager(&["FV2504"])).unwrap();

        let nachricht = serde_json::json!({
            "stammdaten": {
                "marktteilnehmer": [{
                    "marktrolle": "MS",
                    "rollencodenummer": "9900123456789",
                    "codepflegeCode": "293"
                }]
            },
            "transaktionen": [{
                "prozessdaten": {
                    "pruefidentifikator": "55001",
                    "vorgangId": "ABC123"
                }
            }]
        });

        let result = mapper.to_edifact_struct(&nachricht, "FV2504", "UTILMD_Strom", "55001");
        assert!(
            result.is_ok(),
            "to_edifact_struct failed: {:?}",
            result.err()
        );
        let edifact = result.unwrap();
        assert!(!edifact.is_empty(), "EDIFACT output should not be empty");
    }

    #[test]
    fn test_to_edifact_invalid_fv_returns_error() {
        let Some(data_dir) = data_dir() else {
            return;
        };
        let mapper = Mapper::from_data_dir(DataDir::path(&data_dir).eager(&["FV2504"])).unwrap();

        let result = mapper.to_edifact(
            &serde_json::json!({}),
            &[serde_json::json!({})],
            "FV9999",
            "UTILMD_Strom",
            "55001",
        );
        assert!(result.is_err());
    }

    #[test]
    fn test_to_edifact_invalid_variant_returns_error() {
        let Some(data_dir) = data_dir() else {
            return;
        };
        let mapper = Mapper::from_data_dir(DataDir::path(&data_dir).eager(&["FV2504"])).unwrap();

        let result = mapper.to_edifact(
            &serde_json::json!({}),
            &[serde_json::json!({})],
            "FV2504",
            "NONEXISTENT",
            "55001",
        );
        assert!(result.is_err());
    }

    #[test]
    fn test_to_edifact_invalid_pid_returns_error() {
        let Some(data_dir) = data_dir() else {
            return;
        };
        let mapper = Mapper::from_data_dir(DataDir::path(&data_dir).eager(&["FV2504"])).unwrap();

        let result = mapper.to_edifact(
            &serde_json::json!({}),
            &[serde_json::json!({})],
            "FV2504",
            "UTILMD_Strom",
            "99999",
        );
        assert!(result.is_err());
    }

    #[test]
    fn test_association_code() {
        let Some(data_dir) = data_dir() else {
            return;
        };
        let mapper = Mapper::from_data_dir(DataDir::path(&data_dir).eager(&["FV2504"])).unwrap();

        let code = mapper.association_code("FV2504", "UTILMD_Strom").unwrap();
        assert_eq!(code, "S2.1");

        let code = mapper.association_code("FV2504", "MSCONS").unwrap();
        assert_eq!(code, "2.4c");
    }

    #[test]
    fn test_message_metadata() {
        let Some(data_dir) = data_dir() else {
            return;
        };
        let mapper = Mapper::from_data_dir(DataDir::path(&data_dir).eager(&["FV2504"])).unwrap();

        let meta = mapper.message_metadata("FV2504", "UTILMD_Strom").unwrap();
        assert_eq!(meta.message_type, "UTILMD");
        assert_eq!(meta.release, "11A");
        assert_eq!(meta.association_code, "S2.1");
    }

    #[test]
    fn test_to_edifact_interchange() {
        let Some(data_dir) = data_dir() else {
            return;
        };
        let mapper = Mapper::from_data_dir(DataDir::path(&data_dir).eager(&["FV2504"])).unwrap();

        let result = mapper.to_edifact_interchange(
            &InterchangeEnvelope {
                sender: EdifactParty::bdew("9900000000003"),
                receiver: EdifactParty::bdew("9900000000001"),
                interchange_ref: "REF001".to_string(),
            },
            &[InterchangeMessage {
                message_ref: "MSG001".to_string(),
                msg_stammdaten: serde_json::json!({
                    "marktteilnehmer": [{
                        "marktrolle": "MS",
                        "rollencodenummer": "9900123456789",
                        "codepflegeCode": "293"
                    }]
                }),
                tx_stammdaten: vec![serde_json::json!({
                    "prozessdaten": {
                        "pruefidentifikator": "55001",
                        "vorgangId": "ABC123",
                        "transaktionsgrund": "E01"
                    }
                })],
                fv: "FV2504".to_string(),
                variant: "UTILMD_Strom".to_string(),
                pid: "55001".to_string(),
            }],
        );
        assert!(
            result.is_ok(),
            "to_edifact_interchange failed: {:?}",
            result.err()
        );
        let edifact = result.unwrap();

        // Verify envelope structure
        assert!(edifact.starts_with("UNA:+.? '"), "Should start with UNA");
        assert!(
            edifact.contains("UNB+UNOC:3+9900000000003:500+9900000000001:500+"),
            "Should contain UNB with sender/receiver"
        );
        assert!(
            edifact.contains("UNH+MSG001+UTILMD:D:11A:UN:S2.1'"),
            "Should contain UNH with correct S009"
        );
        assert!(edifact.contains("NAD"), "Should contain body NAD segment");
        assert!(edifact.contains("UNT+"), "Should contain UNT");
        assert!(
            edifact.contains("+MSG001'"),
            "UNT should reference message ref"
        );
        assert!(
            edifact.contains("UNZ+1+REF001'"),
            "Should contain UNZ with count and ref"
        );
    }

    #[test]
    fn test_detect_pid_from_rff_z13() {
        let Some(data_dir) = data_dir() else {
            return;
        };
        let mapper = Mapper::from_data_dir(DataDir::path(&data_dir).eager(&["FV2504"])).unwrap();

        let edifact = "\
            UNB+UNOC:3+9978842000002:500+9900269000000:500+250331:1329+REF001'\
            UNH+MSG001+UTILMD:D:11A:UN:S2.1'\
            BGM+E01+DOC001'\
            DTM+137:202503311329?+00:303'\
            NAD+MS+9978842000002::293'\
            NAD+MR+9900269000000::293'\
            IDE+24+TX001'\
            DTM+92:202505312200?+00:303'\
            DTM+93:202512312300?+00:303'\
            STS+7++E01+ZW4+E03'\
            LOC+Z16+12345678900'\
            RFF+Z13:55001'\
            UNT+12+MSG001'\
            UNZ+1+REF001'";

        let pid = mapper.detect_pid(edifact).unwrap();
        assert_eq!(pid, "55001");
    }

    #[test]
    fn test_detect_pid_no_messages_returns_error() {
        let Some(data_dir) = data_dir() else {
            return;
        };
        let mapper = Mapper::from_data_dir(DataDir::path(&data_dir).eager(&["FV2504"])).unwrap();

        let edifact = "UNB+UNOC:3+SENDER:500+RECEIVER:500+250401:1200+REF'\
                        UNZ+0+REF'";
        assert!(mapper.detect_pid(edifact).is_err());
    }

    #[test]
    fn test_list_pids_returns_entries() {
        let Some(data_dir) = data_dir() else {
            return;
        };
        let mapper = Mapper::from_data_dir(DataDir::path(&data_dir)).unwrap();
        let pids = mapper.list_pids().expect("list_pids should succeed");
        assert!(!pids.is_empty(), "should return at least one PID");
        assert!(
            pids.iter().any(|p| p.pid == "55001"),
            "should include PID 55001"
        );
        assert!(
            pids.iter().any(|p| p.fv == "FV2504"),
            "should include FV2504"
        );
        assert!(
            pids.iter().any(|p| p.variant == "UTILMD_Strom"),
            "should include UTILMD_Strom"
        );
    }

    #[test]
    fn test_pid_requirements_returns_requirements() {
        let Some(data_dir) = data_dir() else {
            return;
        };
        let mapper = Mapper::from_data_dir(DataDir::path(&data_dir).eager(&["FV2504"])).unwrap();

        let req = mapper
            .pid_requirements("FV2504", "UTILMD_Strom", "55001")
            .expect("pid_requirements should succeed");

        assert_eq!(req.pid, "55001");
        assert!(
            !req.entities.is_empty(),
            "55001 should have at least one entity"
        );
        assert!(
            req.entities.iter().any(|e| e.entity == "Prozessdaten"),
            "55001 should have a Prozessdaten entity"
        );
    }
}