openehr-its 0.0.2

//! OPT 1.4 → Web Template walk.
//!
//! Walks the OPT 1.4 constraint tree ([`crate::opt14`]) into the Web
//! Template metadata document (`ITS-REST simplified_formats master04
//! §"Web Template Metadata"`):
//!
//! 1. **build** a node per constraint object (rm type, node id, aql path,
//!    occurrences, rubric names, term bindings), giving `DATA_VALUE`/PARTY leaves
//!    their `inputs` and running the per-rm post-processors;
//! 2. **compact** the tree per master04 §"Level Removal": elide the container
//!    attribute names, collapse the always-collapsed wrapper types
//!    (`ITEM_*`/`ITEM_STRUCTURE`/`HISTORY`) and a conditionally-collapsed single
//!    `EVENT`, promote an `ELEMENT`/`DATA_VALUE` single child, and drop empties;
//! 3. **assign ids** (see [`super::id`], master04 §"Node ID Generation Rules").
//!
//! Deliberate shape boundaries of the builder (design decisions, not omissions).
//! The `web-template` mirrors the *constraint* tree of the OPT; RM structure that
//! the operational template does not constrain is not synthesized into the tree
//! here, and is instead completed and enforced where it is authoritative:
//!
//! * **RM-mandatory attributes the OPT leaves unconstrained** are not injected as
//!   web-template nodes. The FLAT/TDD composition builders fill the RM-mandatory
//!   structural fields on `RM ← FLAT/TDD` (`flat::graph::fill_structural_mandatory`,
//!   driven by the same `openehr_rm::model` attribute model), and composition
//!   validation enforces existence/occurrences (`crate::flat::validation`) — so the
//!   produced COMPOSITION is RM-valid without the builder duplicating that
//!   structure. Governing cardinalities: openEHR RM `common`/`composition`/
//!   `data_structures`.
//! * **`ISM_TRANSITION`/careflow-step synthesis**: `ACTION.ism_transition` is
//!   RM-mandatory (`RM ehr §ACTION`) and is materialised downstream by the
//!   composition builders, not expanded into careflow nodes in the tree.
//! * **The "any" (unconstrained) `ELEMENT` value**: an ELEMENT with no value
//!   constraint is emitted without an enumerated per-`DATA_VALUE` `inputs`
//!   expansion. No openEHR spec governs the shape of an unconstrained value node —
//!   our own design/extension.
//! * **Archetype internal-reference (`use_node`) target resolution**: an internal
//!   reference is emitted as its own node rather than resolved to its target
//!   subtree; full ADL/AOM reference resolution is part of the ADL2 work
//!   track, not the OPT 1.4 web-template shape.
//!
//! Node- and coded-value-level external `termBindings` and the multiple-coded-text
//! compaction are wired.

#![expect(
    clippy::disallowed_types,
    reason = "canonical JSON / Simplified Formats operate on the wire value by definition \
              (ITS-JSON; ITS-REST Simplified Formats) — serde_json::Value IS the subject matter \
              (#1694)"
)]

use std::collections::HashMap;

use crate::opt14::{
    ArchetypeTerm, Assertion, CArchetypeRoot, CObject, CPrimitive, Cardinality,
    Constraintbindingset, Intervalofinteger, OperationalTemplate, TermBindingItem, Termbindingset,
};
use indexmap::IndexMap;

use super::inputs::{self, Labels};
use super::model::{
    CodedName, WebTemplate, WebTemplateArchetypeSlot, WebTemplateBindingCodedValue,
    WebTemplateCardinality, WebTemplateClosedAttribute, WebTemplateCodeList,
    WebTemplateConstraintBinding, WebTemplateExistence, WebTemplateNode, WebTemplateStructuralStub,
};
use super::shape;

/// A rubric (`text`/`description`) for a code, resolved from an archetype ontology.
#[derive(Default)]
struct Rubric {
    text: Option<String>,
    description: Option<String>,
}

/// Ontology: `archetype_id → language → code → rubric`.
type Ontology = HashMap<String, HashMap<String, HashMap<String, Rubric>>>;

/// External term bindings per archetype, keyed by `archetype_id`: the archetype
/// root's `term_bindings`. A node inherits its owning archetype root's bindings.
type TermBindings = HashMap<String, Vec<Termbindingset>>;

/// External **constraint** bindings per archetype, keyed by `archetype_id`: the
/// flat ontology's `constraint_bindings` (ac-code → terminology-query URI,
/// `AM/docs/ADL1.4/master08-adl.adoc` §Constraint_bindings).
type ConstraintBindings = HashMap<String, Vec<Constraintbindingset>>;

/// Build context shared across the walk.
struct Ctx {
    default_language: String,
    languages: Vec<String>,
    ontology: Ontology,
    term_bindings: TermBindings,
    constraint_bindings: ConstraintBindings,
}

impl Ctx {
    fn rubric(&self, arch_id: &str, lang: &str, code: &str) -> Option<&Rubric> {
        self.ontology.get(arch_id)?.get(lang)?.get(code)
    }

    fn text(&self, arch_id: &str, code: &str, lang: &str) -> Option<String> {
        self.rubric(arch_id, lang, code)
            .and_then(|r| r.text.clone())
    }

    /// The external term bindings for `code` within `arch_id`'s archetype
    /// (master04 §"Web Template Metadata": a node/coded-value `termBindings` map):
    /// for every terminology whose binding set has an item matching `code`, the
    /// bound code phrase as a `{value, terminologyId}`. Keyed by terminology,
    /// first match per terminology wins, in binding-set order.
    fn term_bindings_for(
        &self,
        arch_id: &str,
        code: &str,
    ) -> IndexMap<String, WebTemplateBindingCodedValue> {
        let mut out = IndexMap::new();
        if code.is_empty() {
            return out;
        }
        let Some(sets) = self.term_bindings.get(arch_id) else {
            return out;
        };
        for set in sets {
            if out.contains_key(&set.terminology) {
                continue;
            }
            if let Some(item) = set.items.iter().find(|it| it.code == code)
                && let Some(bcv) = binding_coded_value(item)
            {
                out.insert(set.terminology.clone(), bcv);
            }
        }
        out
    }

    /// The external constraint bindings of `ac_code` within `arch_id`'s
    /// archetype: one entry per terminology whose `ConstraintBindingSet` binds
    /// the ac-code to a query URI (`AM/docs/ADL1.4/master08-adl.adoc`
    /// §Constraint_bindings). `attr` is the RM attribute of the leaf carrying
    /// the constrained code. An empty query URI is dropped — an unbound
    /// ac-code constrains nothing resolvable.
    fn constraint_bindings_for(
        &self,
        arch_id: &str,
        ac_code: &str,
        attr: &str,
    ) -> Vec<WebTemplateConstraintBinding> {
        let mut out = Vec::new();
        if ac_code.is_empty() {
            return out;
        }
        let Some(sets) = self.constraint_bindings.get(arch_id) else {
            return out;
        };
        for set in sets {
            for item in set.items.iter().filter(|it| it.code == ac_code) {
                let query_uri = item.value.trim();
                if query_uri.is_empty() {
                    continue;
                }
                out.push(WebTemplateConstraintBinding {
                    attr: attr.to_owned(),
                    ac_code: ac_code.to_owned(),
                    terminology: set.terminology.clone(),
                    query_uri: query_uri.to_owned(),
                });
            }
        }
        out
    }
}

/// Every `CONSTRAINT_REF` (`ac`-code proxy) in force on `co`, resolved against
/// the archetype ontology's `constraint_bindings`: the node itself when it IS a
/// `CONSTRAINT_REF` (a bare `CODE_PHRASE` proxy), plus one per coded attribute
/// (`defining_code`, …) whose child is a `CONSTRAINT_REF`. AOM 1.4
/// `master04-constraint_model_package.adoc` §Reference Objects.
fn constraint_bindings_of(
    ctx: &Ctx,
    co: &CObject,
    arch_id: &str,
) -> Vec<WebTemplateConstraintBinding> {
    let mut out = Vec::new();
    if let CObject::ConstraintRef(cr) = co {
        out.extend(ctx.constraint_bindings_for(arch_id, &cr.reference, ""));
    }
    for attr in inputs::attributes(co) {
        let attr_name = inputs::attribute_name(attr);
        for child in inputs::attribute_children(attr) {
            if let CObject::ConstraintRef(cr) = child {
                out.extend(ctx.constraint_bindings_for(arch_id, &cr.reference, attr_name));
            }
        }
    }
    out
}

/// The bound code phrase's code string with its terminology id (falling back to
/// the binding item's own code when the code phrase carries no terminology).
/// `None` when the bound code string is blank. Feeds the `termBindings` map of
/// master04 §"Web Template Metadata".
fn binding_coded_value(item: &TermBindingItem) -> Option<WebTemplateBindingCodedValue> {
    let code_phrase = &item.value;
    if code_phrase.code_string.trim().is_empty() {
        return None;
    }
    let terminology_id = if code_phrase.terminology_id.value.is_empty() {
        item.code.clone()
    } else {
        code_phrase.terminology_id.value.clone()
    };
    Some(WebTemplateBindingCodedValue {
        value: code_phrase.code_string.clone(),
        terminology_id,
    })
}

/// A [`Labels`] view bound to the current archetype, for coded-value rubrics.
struct ArchetypeLabels<'a> {
    ctx: &'a Ctx,
    arch_id: &'a str,
}

impl Labels for ArchetypeLabels<'_> {
    fn text(&self, terminology: &str, code: &str) -> Option<String> {
        // An EXTERNAL code's rubric is keyed by the qualified
        // `TERMINOLOGY::code` form in the OPT ontology (OPT 1.4
        // `term_definitions code="SNOMED-CT::…"`); the bare-code key serves
        // the local at-codes. Try bare first (the overwhelmingly common
        // case), then qualified.
        self.ctx
            .text(self.arch_id, code, &self.ctx.default_language)
            .or_else(|| {
                self.ctx.text(
                    self.arch_id,
                    &format!("{terminology}::{code}"),
                    &self.ctx.default_language,
                )
            })
    }

    fn localized(&self, terminology: &str, code: &str) -> IndexMap<String, String> {
        let mut out = IndexMap::new();
        for lang in &self.ctx.languages {
            if let Some(t) = self.ctx.text(self.arch_id, code, lang).or_else(|| {
                self.ctx
                    .text(self.arch_id, &format!("{terminology}::{code}"), lang)
            }) {
                out.insert(lang.clone(), t);
            }
        }
        out
    }

    fn term_bindings(&self, code: &str) -> IndexMap<String, WebTemplateBindingCodedValue> {
        self.ctx.term_bindings_for(self.arch_id, code)
    }
}

/// Build a [`WebTemplate`] from a parsed OPT 1.4 operational template.
///
/// The document shape (field names, `tree`/`children`, `inputs`, `aqlPath`), the
/// node-id derivation, and the compaction are governed by `ITS-REST
/// simplified_formats master04-basic_concepts.adoc` (§"Web Template Metadata",
/// §"Node ID Generation Rules", §"Level Removal"). `version` is the format
/// version string.
///
/// # Errors
/// [`crate::flat::error::FlatError::InvalidTemplate`] if the template lacks a template id.
pub fn build_web_template(
    opt: &OperationalTemplate,
) -> Result<WebTemplate, crate::flat::error::FlatError> {
    let template_id = opt.template_id.value.clone();
    if template_id.is_empty() {
        return Err(crate::flat::error::FlatError::InvalidTemplate(
            "template_id is mandatory".to_owned(),
        ));
    }
    let default_language = opt.language.code_string.clone();
    let ctx = Ctx {
        languages: collect_languages(opt, &default_language),
        ontology: collect_ontology(opt, &default_language),
        term_bindings: collect_term_bindings(opt),
        constraint_bindings: collect_constraint_bindings(opt),
        default_language,
    };

    let root_arch_id = opt.definition.archetype_id.value.clone();
    let root_co = CObject::CArchetypeRoot(opt.definition.clone());
    let mut tree = build_node(&ctx, None, &root_co, "", &root_arch_id, None);
    tree = shape::compact(tree, 1).unwrap_or_else(shape::tree_placeholder);
    // Synthesize the in-context RM children the master04 example carries for the
    // structural attributes an OPT commonly leaves unconstrained (COMPOSITION
    // context/category/language/territory/composer, per-ENTRY language/encoding/
    // subject, per-EVENT time) BEFORE id assignment, so their ids go through the
    // normal sibling-uniqueness discipline (super::id).
    shape::synthesize_in_context(&mut tree);
    super::id::build_ids(&mut tree);
    // Parse the archetype-conformance walk's template-static constraint paths
    // ONCE now, so the validation walk never re-parses them per instance-node
    // visit.
    crate::flat::validation::prepare_walk(&mut tree);

    Ok(WebTemplate {
        template_id,
        // NOTE: OPT 1.4 has no semantic-version field (semVer is an ADL2/OPT2
        // concept), so the 1.4 adapter always emits `null` — matching what stock
        // tooling produces for a 1.4 template. A value would only appear for OPT 2.
        sem_ver: None,
        version: shape::CURRENT_VERSION.to_owned(),
        default_language: ctx.default_language.clone(),
        languages: ctx.languages.clone(),
        tree,
        other_details: other_details(opt),
    })
}

// ── node build ───────────────────────────────────────────────────────────────

fn build_node(
    ctx: &Ctx,
    attr_name: Option<&str>,
    co: &CObject,
    parent_path: &str,
    parent_arch_id: &str,
    group: Option<&str>,
) -> WebTemplateNode {
    // A C_ARCHETYPE_ROOT switches the ontology scope to its own archetype.
    let node_arch_id = match co {
        CObject::CArchetypeRoot(r) => r.archetype_id.value.as_str(),
        _ => parent_arch_id,
    };
    let mut node = create_node(ctx, attr_name, co, parent_path, node_arch_id);
    build_children(ctx, co, &mut node, node_arch_id, group);
    node
}

fn create_node(
    ctx: &Ctx,
    attr_name: Option<&str>,
    co: &CObject,
    parent_path: &str,
    arch_id: &str,
) -> WebTemplateNode {
    let rm_type = object_rm_type(co).to_owned();
    let arch_node_id = object_archetype_node_id(co);
    let (min, max) = occurrences(object_occurrences(co));
    let name_constraint = name_constraint(co);

    let path = build_path(
        parent_path,
        attr_name,
        &arch_node_id,
        name_constraint.as_deref(),
    );
    let mut node = WebTemplateNode::new(rm_type, path);
    node.node_id = if arch_node_id.is_empty() {
        None
    } else {
        Some(arch_node_id)
    };
    node.min = min;
    node.max = max;

    let name_code = object_node_id(co);
    // A `DV_CODED_TEXT` name constraint (RM common master03 §LOCATABLE — the
    // name is `DV_TEXT` *or* `DV_CODED_TEXT`) fixes both the display value and
    // the `defining_code` the composition builder must stamp; it takes
    // precedence over the plain `name/value` and node-rubric name.
    let coded_name = coded_name_constraint(co, ctx, arch_id, name_constraint.as_deref());
    if let Some((value, coded)) = coded_name {
        node.name = Some(value.clone());
        node.localized_name = Some(value);
        node.name_coded = Some(coded);
    } else if let Some(nc) = &name_constraint {
        node.name = Some(nc.clone());
        node.localized_name = Some(nc.clone());
    } else if !name_code.is_empty() {
        node.name = ctx.text(arch_id, name_code, &ctx.default_language);
        node.localized_name.clone_from(&node.name);
        for lang in &ctx.languages {
            if let Some(r) = ctx.rubric(arch_id, lang, name_code) {
                if let Some(t) = &r.text {
                    node.localized_names.insert(lang.clone(), t.clone());
                }
                if let Some(d) = &r.description {
                    node.localized_descriptions.insert(lang.clone(), d.clone());
                }
            }
        }
    }
    node.name_code = if name_code.is_empty() {
        None
    } else {
        Some(name_code.to_owned())
    };
    // Node-level external term bindings: the archetype root's `term_bindings`
    // whose item code matches this node's constraint node id (master04
    // §"Web Template Metadata": the node-level `termBindings` map).
    node.term_bindings = ctx.term_bindings_for(arch_id, name_code);
    // Archetype constraint bindings (ac-code → external terminology query) in
    // force on this node's coded value — resolvable only by a terminology
    // service, so recorded rather than checked here (BASE
    // `architecture_overview/master12-terminology.adoc` §"Binding Terminology
    // Value-sets to Archetypes").
    node.constraint_bindings = constraint_bindings_of(ctx, co, arch_id);
    node
}

fn build_children(
    ctx: &Ctx,
    co: &CObject,
    node: &mut WebTemplateNode,
    arch_id: &str,
    group: Option<&str>,
) {
    let is_data_value = node.rm_type.starts_with("DV_");
    let recurse_attrs = !is_data_value || node.rm_type.starts_with("DV_INTERVAL");

    let mut children = Vec::new();
    if recurse_attrs {
        for attr in inputs::attributes(co) {
            let attr_name = inputs::attribute_name(attr);
            if attr_name == "name" {
                // The `name` attribute is never a child node — it names the node
                // (master04 §"Field Identifiers": names generate the node id).
                continue;
            }
            // The openEHR terminology group a child's coded value binds to, fixed
            // by (this node's RM type, the attribute) — used to resolve rubrics
            // from the correct group (SPECPR-51 code collisions; see
            // `inputs::openehr_group`).
            let child_group = inputs::openehr_group(&node.rm_type, attr_name);
            for child_co in inputs::attribute_children(attr) {
                if matches!(
                    child_co,
                    CObject::ArchetypeSlot(_) | CObject::ConstraintRef(_)
                ) {
                    continue; // Unfilled slot / constraint ref: no node.
                }
                children.push(build_node(
                    ctx,
                    Some(attr_name),
                    child_co,
                    &node.aql_path,
                    arch_id,
                    child_group,
                ));
            }
        }
    }

    // A party node keeps its inputs even when it HAS children: master05's three
    // PARTY_PROXY tables put the `|name`/`|id`/`|id_scheme`/`|id_namespace`
    // suffixes and the `/relationship` + `/_identifier:i` SUB-PATHS on the same
    // node, so a template that narrows a party and constrains `relationship`
    // (the shape the vendored `Test constrained subject` / `MED - Perinatal
    // history Summary` templates use) still owns every party suffix. For every
    // other leaf family a child means the node is a container, not a datum.
    if has_inputs(&node.rm_type) && (children.is_empty() || is_party(&node.rm_type)) {
        let labels = ArchetypeLabels { ctx, arch_id };
        let (built, ptypes) = inputs::build_inputs(&node.rm_type, co, &labels, group);
        node.inputs = built;
        node.proportion_types = ptypes;
        capture_leaf_constraints(co, node);
    }

    node.cardinalities = cardinalities(co, &node.aql_path);
    node.card_all = all_cardinalities(co, &node.aql_path);
    // Existence is captured only for structural (attribute-recursing) nodes; a
    // DATA_VALUE leaf's constraints (`magnitude`, `is_integral`, `value`, …) are
    // handled by `inputs`/leaf checks, not attribute navigation.
    if recurse_attrs {
        node.existence = existence_constraints(co, &node.aql_path);
        node.closed_attributes = closed_attributes(co, &node.aql_path);
        if shape::is_entry_family(&node.rm_type) {
            node.structural_stubs = structural_stubs(ctx, co, arch_id);
        }
    }
    node.children = children;
    shape::post_process(node);
}

/// Whether a node of this RM type is a web-template LEAF — one that carries
/// `inputs` rather than child nodes.
///
/// The PARTY arm covers all three concrete `PARTY_PROXY` subtypes the
/// Simplified Formats spec gives their own mapping table: master05
/// §§PARTY_SELF, PARTY_IDENTIFIED, PARTY_RELATED share the
/// `|id`/`|id_scheme`/`|id_namespace` rows and the latter two add `|name`, so a
/// slot an OPT narrows to `PARTY_RELATED` is the same party leaf as one left at
/// `PARTY_IDENTIFIED` — its extra `relationship` is a DV_CODED_TEXT SUB-PATH
/// (master05 §"PARTY_RELATED performer": "the `relationship` attribute is
/// emitted as a sub-path under the participation, with the standard
/// DV_CODED_TEXT suffixes"), not a reason to demote the party itself to a
/// container.
fn has_inputs(rm_type: &str) -> bool {
    rm_type.starts_with("DV_") || is_party(rm_type) || rm_type == "CODE_PHRASE"
}

/// The `PARTY_PROXY` family: the abstract type an unnarrowed slot keeps, plus
/// the two concrete subtypes an OPT can narrow one to (`PARTY_SELF` carries no
/// constrainable attribute of its own, so no template names it).
fn is_party(rm_type: &str) -> bool {
    matches!(
        rm_type,
        "PARTY_PROXY" | "PARTY_IDENTIFIED" | "PARTY_RELATED"
    )
}

// ── cardinalities ────────────────────────────────────────────────────────────

fn cardinalities(co: &CObject, node_path: &str) -> Vec<WebTemplateCardinality> {
    let mut out = Vec::new();
    for attr in inputs::attributes(co) {
        if let crate::opt14::CAttribute::CMultipleAttribute(m) = attr
            && requires_cardinality(&m.cardinality, m.children.len())
        {
            let (min, max) = occurrences(&m.cardinality.interval);
            out.push(WebTemplateCardinality {
                min,
                max,
                ids: None,
                path: format!("{node_path}/{}", m.rm_attribute_name),
            });
        }
    }
    out
}

/// Capture **every** constraining multiple-attribute cardinality for the
/// validation walk (AOM 1.4 `master04-constraint_model_package.adoc`
/// §cardinality): any interval with a lower bound `>= 1` or a bounded upper
/// bound constrains the container. This is the superset of the serialized
/// [`requires_cardinality`] selection, which drops `0..1`/`1..1`/`1..*` — those
/// intervals are still real archetype constraints (master15/16 truth tables)
/// and are enforced from [`WebTemplateNode::card_all`], never serialized.
fn all_cardinalities(co: &CObject, node_path: &str) -> Vec<WebTemplateCardinality> {
    let mut out = Vec::new();
    for attr in inputs::attributes(co) {
        if let crate::opt14::CAttribute::CMultipleAttribute(m) = attr {
            let (min, max) = occurrences(&m.cardinality.interval);
            if min.unwrap_or(0) >= 1 || max != -1 {
                out.push(WebTemplateCardinality {
                    min,
                    max,
                    ids: None,
                    path: format!("{node_path}/{}", m.rm_attribute_name),
                });
            }
        }
    }
    out
}

/// Capture the leaf value constraints the `inputs` mapping does not carry, onto
/// the node's validation-only fields:
///
/// - `C_INTEGER.list` / `C_REAL.list` on a numeric datum (`magnitude`, `value`)
///   → [`WebTemplateNode::numeric_lists`] (AOM 1.4 §`C_INTEGER/§C_REAL`);
/// - `C_DURATION.range` on `value` → [`WebTemplateNode::duration_range`]
///   (AOM 1.4 §`C_DURATION`);
/// - `C_CODE_PHRASE` code lists on coded attributes other than
///   `defining_code` (e.g. `DV_MULTIMEDIA.media_type`) →
///   [`WebTemplateNode::code_lists`] (AOM 1.4 §`C_CODE_PHRASE`).
fn capture_leaf_constraints(co: &CObject, node: &mut WebTemplateNode) {
    // `size` covers `DV_MULTIMEDIA.size` (RM `data_types` §`DV_MULTIMEDIA`,
    // `size: Integer`), whose `C_INTEGER` list/range the `inputs` builder does
    // not model (the DV_MULTIMEDIA input is only the `value` text input).
    for datum in ["magnitude", "value", "numerator", "denominator", "size"] {
        match inputs::primitive_under(co, datum) {
            Some(CPrimitive::CInteger(ci)) if !ci.list.is_empty() => {
                node.numeric_lists.push((
                    datum.to_owned(),
                    ci.list.iter().map(|v| f64::from(*v)).collect(),
                ));
            }
            Some(CPrimitive::CReal(cr)) if !cr.list.is_empty() => {
                node.numeric_lists.push((datum.to_owned(), cr.list.clone()));
            }
            _ => {}
        }
    }
    capture_size_range(co, node);
    capture_leaf_existence(co, node);
    if let Some(CPrimitive::CDuration(d)) = inputs::primitive_under(co, "value")
        && let Some(range) = &d.range
    {
        let min = if range.lower_unbounded {
            None
        } else {
            range.lower.clone()
        };
        let max = if range.upper_unbounded {
            None
        } else {
            range.upper.clone()
        };
        if min.is_some() || max.is_some() {
            // Inclusivity comes from the AOM interval flags (BASE
            // foundation_types Interval: lower_included/upper_included) —
            // an exclusive bound (`> PT0S`) must not degrade to `>=`.
            let min_strict = range.lower_included == Some(false);
            let max_strict = range.upper_included == Some(false);
            node.duration_range = Some(super::model::WebTemplateRange {
                min_op: min
                    .as_ref()
                    .map(|_| if min_strict { ">" } else { ">=" }.to_owned()),
                min: min.map(serde_json::Value::String),
                max_op: max
                    .as_ref()
                    .map(|_| if max_strict { "<" } else { "<=" }.to_owned()),
                max: max.map(serde_json::Value::String),
            });
        }
    }
    // C_TIME/C_DATE_TIME timezone_validity (VALIDITY_KIND: OPT 1.4 XSD 1001 =
    // mandatory, 1002 = optional, 1003 = disallowed). C_DATE has no timezone.
    node.tz_validity = match inputs::primitive_under(co, "value") {
        Some(CPrimitive::CTime(c)) => c.timezone_validity.as_deref().and_then(|s| s.parse().ok()),
        Some(CPrimitive::CDateTime(c)) => {
            c.timezone_validity.as_deref().and_then(|s| s.parse().ok())
        }
        _ => None,
    };
    // C_QUANTITY.property (openEHR `property`-group code): captured so the
    // instance's `units` can be checked against the property's unit set
    // (`AM/docs/UML/classes/org.openehr.am.aom14.c_quantity.adoc` §C_QUANTITY:
    // `property` = "Name of physical property for Quantities being
    // constrained"). Only the openEHR-terminology property code is meaningful,
    // and the placeholder "0" (Ocean Template Designer's unconstrained property)
    // is treated as no constraint (matching the OPT-side C_DV_QUANTITY check).
    if let CObject::CDvQuantity(q) = co
        && let Some(property) = &q.property
        && property
            .terminology_id
            .value
            .eq_ignore_ascii_case("openehr")
        && !property.code_string.is_empty()
        && property.code_string != "0"
    {
        node.quantity_property = Some(property.code_string.clone());
    }
    // Explicit-local closed C_CODE_PHRASE on `defining_code` (DV_CODED_TEXT) or
    // the node's own bare CODE_PHRASE: when the archetype author explicitly
    // scopes the code list to the `local` terminology, the closed list admits
    // ONLY local codes, so a foreign-terminology instance code is a violation
    // (`AM/docs/UML/classes/org.openehr.am.aom14.c_coded_text.adoc` §C_CODED_TEXT:
    // the `code_list` is "a list of codes FROM the terminology"). The wt+json
    // `inputs` mapping strips the implicit/default `local`, so this explicit
    // scoping is recorded on the node instead (validation-only). Only the
    // EXPLICIT `local` case is flagged — a `C_CODE_PHRASE` with no terminology
    // named keeps the confident-violations bias (unchanged).
    let defining_cp = match co {
        CObject::CCodePhrase(cp) => Some(cp),
        _ => inputs::attr_children(co, "defining_code").find_map(|c| match c {
            CObject::CCodePhrase(cp) => Some(cp),
            _ => None,
        }),
    };
    if let Some(cp) = defining_cp
        && !cp.code_list.is_empty()
        && cp
            .terminology_id
            .as_ref()
            .is_some_and(|t| t.value.eq_ignore_ascii_case("local"))
    {
        node.coded_terminology_local = true;
    }
    // NOTE — CONSTRAINT_REF (an `ac`-code proxy under a coded attribute, e.g.
    // `defining_code`) is intentionally NOT captured as a leaf constraint.
    // A CONSTRAINT_REF is "a proxy for a set of constraints … expressed in the
    // binding of the constraint reference (e.g. 'ac0004') to a query … into an
    // external service (e.g. a terminology service)"
    // (`AM/docs/AOM1.4/master04-constraint_model_package.adoc` §Reference
    // Objects). Its resolution is a `constraint_binding` to an external
    // terminology-query URI (`AM/docs/ADL1.4/master08-adl.adoc`
    // §Constraint_bindings), not a local code list. AOM 1.4 requires the ac-code
    // be DEFINED in `constraint_definitions` (VATDF/VACDF, master08 §Coded Term
    // Validity) but nowhere states what a DATA validator must do for an ac-code
    // with no binding — the case is spec-silent, and no local fallback is
    // defined. The honest reading is therefore that an unbound/externally-bound
    // CONSTRAINT_REF constrains nothing enforceable at commit time (no openEHR
    // spec governs the no-binding case — our own design/extension), so it admits
    // any well-formed CODE_PHRASE; well-formedness stays the RM-invariant pass's
    // job. A local terminology service integration could resolve a present
    // binding in future (`TerminologyService` seam).
    for attr in inputs::attributes(co) {
        let attr_name = inputs::attribute_name(attr);
        if attr_name == "defining_code" {
            continue; // Modelled by the coded-text `inputs`.
        }
        for child in inputs::attribute_children(attr) {
            if let CObject::CCodePhrase(cp) = child
                && !cp.code_list.is_empty()
            {
                node.code_lists.push(WebTemplateCodeList {
                    attr: attr_name.to_owned(),
                    terminology: cp
                        .terminology_id
                        .as_ref()
                        .map(|t| t.value.clone())
                        .filter(|t| !t.is_empty()),
                    codes: cp.code_list.clone(),
                });
            }
        }
    }
}

/// `DV_MULTIMEDIA.size` against a `C_INTEGER.range` (AOM 1.4
/// `master04-constraint_model_package.adoc` §`C_INTEGER`): the instance's `size`
/// must lie within the declared `IntervalOfInteger`. The other numeric data
/// (`magnitude`/`numerator`/…) already carry their range through the `inputs`
/// builders (`count_input`, `quantity_inputs`, `proportion_part`), so only `size`
/// needs a validation-only range captured here.
fn capture_size_range(co: &CObject, node: &mut WebTemplateNode) {
    let Some(CPrimitive::CInteger(ci)) = inputs::primitive_under(co, "size") else {
        return;
    };
    let Some(iv) = &ci.range else { return };
    let min = if iv.lower_unbounded { None } else { iv.lower };
    let max = if iv.upper_unbounded { None } else { iv.upper };
    if min.is_none() && max.is_none() {
        return;
    }
    let min_strict = iv.lower_included == Some(false);
    let max_strict = iv.upper_included == Some(false);
    node.numeric_ranges.push((
        "size".to_owned(),
        super::model::WebTemplateRange {
            min_op: min.map(|_| if min_strict { ">" } else { ">=" }.to_owned()),
            min: min.map(serde_json::Value::from),
            max_op: max.map(|_| if max_strict { "<" } else { "<=" }.to_owned()),
            max: max.map(serde_json::Value::from),
        },
    ));
}

/// AOM 1.4 `C_ATTRIBUTE.existence` on a DV leaf's directly-navigable data
/// attributes (`master04-constraint_model_package.adoc` §existence): an OPT may
/// narrow an RM-optional leaf attribute (e.g. `DV_IDENTIFIER.issuer`,
/// `.assigner`, `.type` — RM `data_types` §`DV_IDENTIFIER`) to mandatory
/// (existence lower `>= 1`), so a committed value missing that attribute must be
/// rejected. The structural [`existence_constraints`] pass runs only for
/// attribute-recursing nodes, and its primitive-child carve-out excludes exactly
/// these string data attributes.
///
/// Captured **only** when the OPT actually CONSTRAINS the sub-attribute (a
/// `C_STRING` closed list or pattern, surfaced on the matching leaf input) as
/// well as mandating it — an attribute carrying only the tooling-default
/// existence (`{1..1}` serialised for every attribute; see the NOTE on
/// [`existence_constraints`]) with no value constraint is left unenforced, so a
/// real template's optional-in-intent identifier field is not over-rejected.
fn capture_leaf_existence(co: &CObject, node: &mut WebTemplateNode) {
    for attr in inputs::attributes(co) {
        let crate::opt14::CAttribute::CSingleAttribute(s) = attr else {
            continue;
        };
        if s.rm_attribute_name == "name" {
            continue;
        }
        let constrained = node.inputs.iter().any(|i| {
            i.suffix.as_deref() == Some(s.rm_attribute_name.as_str())
                && ((!i.list.is_empty() && i.list_open != Some(true))
                    || i.validation.as_ref().is_some_and(|v| v.pattern.is_some()))
        });
        if !constrained {
            continue;
        }
        let (min, max) = occurrences(&s.existence);
        if min.unwrap_or(0) >= 1 {
            node.existence.push(WebTemplateExistence {
                min: min.unwrap_or(0),
                max,
                path: format!("{}/{}", node.aql_path, s.rm_attribute_name),
            });
        }
    }
}

// ── existence (AOM 1.4 C_ATTRIBUTE.existence) ─────────────────────────────────

/// Capture the AOM 1.4 `C_ATTRIBUTE.existence` constraints for the mandatory
/// single-valued RM attributes of `co`, keyed by their absolute archetype path.
///
/// Scope: `C_SINGLE_ATTRIBUTE`s with an existence lower bound `>= 1` and at
/// least one object-valued constraint child (excluding pure function/primitive
/// constraints such as `is_integral`/`lower_included`, which never appear as
/// navigable instance attributes). `name` is excluded (it names the node —
/// master04 §"Field Identifiers" — and is matched by the archetype-node
/// predicate instead).
///
/// A node-identified structural child (e.g. `OBSERVATION.state → HISTORY[at0005]`,
/// `HISTORY.summary → ITEM_TREE[at0007]`) is captured here **too**, not only when
/// the child carries no `node_id`: existence and *occurrences* are orthogonal
/// (AOM 1.4 §existence — "indicates whether its target object exists or not, i.e.
/// is mandatory or not"), and a mandated structural wrapper with no leaf content
/// is dropped by master04 §"Level Removal" compaction, so it never becomes a
/// walkable node the occurrence check could visit — leaving existence as the only
/// enforcement that the mandatory attribute is present at all. When the child
/// does survive, existence and occurrences both fire only on absence (redundant,
/// never contradictory).
///
/// NOTE: AOM 1.4 (`master04-constraint_model_package.adoc` §existence) makes
/// existence "always required" with an unstated default of `{1..1}`; the OPT XML
/// always serialises it, and we honour the declared value (biasing toward
/// confident violations — an unstated/`{0..1}` existence is not enforced).
fn existence_constraints(co: &CObject, node_path: &str) -> Vec<WebTemplateExistence> {
    let mut out = Vec::new();
    for attr in inputs::attributes(co) {
        // A CONTAINER attribute with existence lower >= 1 demands the
        // attribute's presence regardless of member cardinality (AOM 1.4
        // c_attribute `Existence_set`; cardinality then governs membership of
        // the present container — the two constraints are orthogonal).
        if let crate::opt14::CAttribute::CMultipleAttribute(m) = attr {
            let (min, max) = occurrences(&m.existence);
            if min.unwrap_or(0) >= 1 {
                out.push(WebTemplateExistence {
                    min: min.unwrap_or(0),
                    max,
                    path: format!("{node_path}/{}", m.rm_attribute_name),
                });
            }
            continue;
        }
        let crate::opt14::CAttribute::CSingleAttribute(s) = attr else {
            continue;
        };
        let (min, max) = occurrences(&s.existence);
        let min = min.unwrap_or(0);
        // Require at least one non-primitive (object-valued) constraint child —
        // this targets real structural attributes (`value`, `language`, `data`,
        // `events`, `items`, …) and excludes function/primitive constraints
        // (`is_integral`, `lower_included`, …) that never appear as navigable
        // instance attributes. A **childless** mandatory attribute also counts:
        // AOM 1.4 (`master04-constraint_model_package.adoc` §existence) lets an
        // archetype demand an attribute's presence without constraining its
        // value (a bare `C_SINGLE_ATTRIBUTE` with existence `1..1`, e.g. a
        // mandatory `COMPOSITION.context` or `HISTORY.summary`).
        let object_valued = s.children.is_empty()
            || s.children
                .iter()
                .any(|c| !matches!(c, CObject::CPrimitiveObject(_)));
        if min >= 1 && s.rm_attribute_name != "name" && object_valued {
            out.push(WebTemplateExistence {
                min,
                max,
                path: format!("{node_path}/{}", s.rm_attribute_name),
            });
        }
    }
    out
}

// ── closed-archetype constraints (AOM2 closed-world direction) ────────────────

/// Capture the closed-archetype constraints for the walk: per
/// attribute of `co` that carries **archetype-node-identified** child
/// alternatives (a fixed at-code / archetype-id sibling set) and/or open
/// `ARCHETYPE_SLOT`s, record the admissible child identities keyed by the
/// attribute's absolute archetype path. Captured from the raw OPT `co` (before
/// the tree build drops slots and before compaction hoists wrappers), so no
/// alternative is lost.
///
/// An attribute whose constraint children carry **no** `node_id` and has no slot
/// is left OPEN — AOM 1.4 (`master04-constraint_model_package.adoc` §`node_id`
/// L44: a near-leaf with no same-attribute siblings "can safely have no
/// `node_id`") — matching the RM-metadata / plain-attribute carve-out (closed-world capture
/// rule 2): `name`/`value`/`category`/`context` etc. hold non-LOCATABLE values
/// that carry no `archetype_node_id` and so are never subject to sibling closure.
fn closed_attributes(co: &CObject, node_path: &str) -> Vec<WebTemplateClosedAttribute> {
    let mut out = Vec::new();
    for attr in inputs::attributes(co) {
        let attr_name = inputs::attribute_name(attr);
        if attr_name == "name" {
            continue; // The name is matched by predicate, not closure (master04 §"Field Identifiers").
        }
        // An unresolved internal-ref / constraint-ref makes the admissible set
        // uncertain (target resolution is a documented builder scope gap); leave
        // such an attribute OPEN rather than risk over-rejecting.
        if inputs::attribute_children(attr).iter().any(|c| {
            matches!(
                c,
                CObject::ArchetypeInternalRef(_) | CObject::ConstraintRef(_)
            )
        }) {
            continue;
        }
        let mut allowed_ids: Vec<String> = Vec::new();
        let mut slots: Vec<WebTemplateArchetypeSlot> = Vec::new();
        for child in inputs::attribute_children(attr) {
            if let CObject::ArchetypeSlot(s) = child {
                slots.push(archetype_slot(s));
                continue;
            }
            let id = object_archetype_node_id(child);
            if !id.is_empty() {
                allowed_ids.push(id);
            }
        }
        if allowed_ids.is_empty() && slots.is_empty() {
            continue; // Open attribute (no node-id alternatives, no slot).
        }
        out.push(WebTemplateClosedAttribute {
            path: format!("{node_path}/{attr_name}"),
            allowed_ids,
            slots,
        });
    }
    out
}

// ── structural stubs (constrained-but-content-less ENTRY structural attrs) ────

/// The RM-mandatory / structural attributes of an ENTRY whose value the
/// FLAT/TDD composition builder synthesises when the simplified form carries no
/// content under them (`RM/docs/UML/classes/org.openehr.rm.composition.*`): the
/// ENTRY `data`/`state`/`protocol` structural attributes plus `ACTION.description`
/// (existence `1..1`, `RM/docs/UML/classes/org.openehr.rm.composition.action.adoc`).
const ENTRY_STRUCTURAL_ATTRS: [&str; 4] = ["data", "description", "protocol", "state"];

/// Capture the [`WebTemplateStructuralStub`]s for an ENTRY node: for each
/// structural attribute (`data`/`description`/`protocol`/`state`) the OPT
/// constrains with a node-identified structural child, record its RM type,
/// archetype node id, and rubric name. When the attribute has no leaf content the
/// compactor drops the wrapper, so this is the only surviving record of the
/// *constrained* identity — the composition builder synthesises the empty
/// attribute from it (AOM 1.4 `master04-constraint_model_package.adoc`
/// §`Valid_value`: a constrained attribute must be filled by a conforming value),
/// instead of a blind `at0001` placeholder that a closed-archetype walk rejects.
///
/// The first node-identified, resolvable structural child per attribute is
/// recorded; unresolved refs / slots yield no stub (the attribute then keeps its
/// spec-legal `at0001` "Any" placeholder — ADL 1.4 `master05-cadl.adoc` §"Any"
/// Constraints).
fn structural_stubs(ctx: &Ctx, co: &CObject, arch_id: &str) -> Vec<WebTemplateStructuralStub> {
    let mut out = Vec::new();
    for attr in inputs::attributes(co) {
        let attr_name = inputs::attribute_name(attr);
        if !ENTRY_STRUCTURAL_ATTRS.contains(&attr_name) {
            continue;
        }
        for child in inputs::attribute_children(attr) {
            // An unresolved slot / reference gives no concrete identity to stamp;
            // leave the attribute to the spec-legal "Any" placeholder.
            if matches!(
                child,
                CObject::ArchetypeSlot(_)
                    | CObject::ConstraintRef(_)
                    | CObject::ArchetypeInternalRef(_)
            ) {
                continue;
            }
            let node_id = object_archetype_node_id(child);
            if node_id.is_empty() {
                continue;
            }
            out.push(WebTemplateStructuralStub {
                attr: attr_name.to_owned(),
                rm_type: object_rm_type(child).to_owned(),
                node_id,
                name: ctx.text(arch_id, object_node_id(child), &ctx.default_language),
            });
            break; // first node-identified structural child under this attribute
        }
    }
    out
}

/// Build the validation-only slot record from an OPT `ARCHETYPE_SLOT`: its
/// constrained RM type, occurrences bounds, and the archetype-id regexes lifted
/// from the `includes`/`excludes` assertions (AOM 1.4 `ARCHETYPE_SLOT`).
fn archetype_slot(s: &crate::opt14::ArchetypeSlot) -> WebTemplateArchetypeSlot {
    let (min, max) = occurrences(&s.occurrences);
    WebTemplateArchetypeSlot {
        rm_type: s.rm_type_name.clone(),
        min: min.unwrap_or(0).max(0),
        max,
        includes: s.includes.iter().filter_map(slot_pattern).collect(),
        excludes: s.excludes.iter().filter_map(slot_pattern).collect(),
    }
}

/// The archetype-id regex of a slot `ASSERTION`, lifted from its
/// `string_expression` (`archetype_id/value matches {/<regex>/}` — ADL 1.4
/// `master05-cadl.adoc` §Archetype Slots; the OPT always emits this surface
/// form). Archetype ids contain no `/`, so the last `/}` delimits the regex.
fn slot_pattern(a: &Assertion) -> Option<String> {
    let s = a.string_expression.as_deref()?;
    let (_, rest) = s.split_once("matches {/")?;
    let end = rest.rfind("/}")?;
    Some(rest.get(..end)?.to_owned())
}

fn requires_cardinality(card: &Cardinality, children_count: usize) -> bool {
    let iv = &card.interval;
    let min = if iv.lower_unbounded { None } else { iv.lower };
    let max = if iv.upper_unbounded { None } else { iv.upper };
    if min.is_none() && max.is_none() {
        return false;
    }
    let Some(min) = min else { return false };
    if min == 0 {
        return false;
    }
    let count = i32::try_from(children_count).unwrap_or(i32::MAX);
    if min == 1 && max == Some(1) && children_count == 1 {
        false
    } else {
        min > 1 || max.is_some_and(|m| m < count)
    }
}

// ── ontology / languages / other_details ─────────────────────────────────────

fn collect_languages(opt: &OperationalTemplate, default_language: &str) -> Vec<String> {
    let mut langs = vec![default_language.to_owned()];
    let mut push = |flat: &crate::opt14::FlatArchetypeOntology| {
        for set in &flat.term_definitions {
            if !langs.contains(&set.language) {
                langs.push(set.language.clone());
            }
        }
    };
    if let Some(o) = &opt.ontology {
        push(o);
    }
    for o in &opt.component_ontologies {
        push(o);
    }
    langs
}

fn collect_ontology(opt: &OperationalTemplate, default_language: &str) -> Ontology {
    let mut ontology: Ontology = HashMap::new();

    let mut register_flat = |flat: &crate::opt14::FlatArchetypeOntology| {
        let arch = ontology.entry(flat.archetype_id.clone()).or_default();
        for set in &flat.term_definitions {
            let lang = arch.entry(set.language.clone()).or_default();
            for term in &set.items {
                lang.entry(term.code.clone())
                    .or_insert_with(|| rubric_of(term));
            }
        }
    };
    if let Some(o) = &opt.ontology {
        register_flat(o);
    }
    for o in &opt.component_ontologies {
        register_flat(o);
    }

    // Inline C_ARCHETYPE_ROOT term_definitions are the flattened default-language
    // rubrics; register them (without overwriting an explicit ontology entry).
    collect_inline_terms(&opt.definition, default_language, &mut ontology);
    ontology
}

fn collect_inline_terms(root: &CArchetypeRoot, default_language: &str, ontology: &mut Ontology) {
    let arch = ontology.entry(root.archetype_id.value.clone()).or_default();
    let lang = arch.entry(default_language.to_owned()).or_default();
    for term in &root.term_definitions {
        lang.entry(term.code.clone())
            .or_insert_with(|| rubric_of(term));
    }
    // Recurse into nested archetype roots (each registers its own subtree's
    // rubrics under its own archetype id). Walk by reference — no cloning.
    let mut nested = Vec::new();
    for attr in &root.attributes {
        for child in inputs::attribute_children(attr) {
            collect_nested_roots(child, &mut nested);
        }
    }
    for r in nested {
        collect_inline_terms(r, default_language, ontology);
    }
}

/// Collect archetype roots at or below `co`, without descending past a root
/// (each found root handles its own subtree).
fn collect_nested_roots<'a>(co: &'a CObject, out: &mut Vec<&'a CArchetypeRoot>) {
    if let CObject::CArchetypeRoot(r) = co {
        out.push(r);
        return;
    }
    for attr in inputs::attributes(co) {
        for child in inputs::attribute_children(attr) {
            collect_nested_roots(child, out);
        }
    }
}

/// Collect every archetype root's inline `term_bindings`, keyed by archetype id
/// (a node inherits its owning archetype root's bindings, surfaced as the
/// `termBindings` map of master04 §"Web Template Metadata"). First root wins for a
/// repeated archetype id.
fn collect_term_bindings(opt: &OperationalTemplate) -> TermBindings {
    let mut out: TermBindings = HashMap::new();
    collect_root_bindings(&opt.definition, &mut out);
    out
}

fn collect_root_bindings(root: &CArchetypeRoot, out: &mut TermBindings) {
    if !root.term_bindings.is_empty() {
        out.entry(root.archetype_id.value.clone())
            .or_insert_with(|| root.term_bindings.clone());
    }
    // Recurse into nested archetype roots (each carries its own bindings).
    let mut nested = Vec::new();
    for attr in &root.attributes {
        for child in inputs::attribute_children(attr) {
            collect_nested_roots(child, &mut nested);
        }
    }
    for r in nested {
        collect_root_bindings(r, out);
    }
}

/// Collect the flat ontologies' `constraint_bindings`, keyed by archetype id —
/// the ac-code → terminology-query URI map a `CONSTRAINT_REF` resolves through
/// (`AM/docs/ADL1.4/master08-adl.adoc` §Constraint_bindings). The root
/// `ontology` and every `component_ontologies` entry carries its own
/// `archetype_id`.
fn collect_constraint_bindings(opt: &OperationalTemplate) -> ConstraintBindings {
    let mut out: ConstraintBindings = HashMap::new();
    for onto in opt.ontology.iter().chain(opt.component_ontologies.iter()) {
        if onto.constraint_bindings.is_empty() {
            continue;
        }
        out.entry(onto.archetype_id.clone())
            .or_default()
            .extend(onto.constraint_bindings.iter().cloned());
    }
    out
}

fn rubric_of(term: &ArchetypeTerm) -> Rubric {
    Rubric {
        text: term.items.get("text").cloned(),
        description: term.items.get("description").cloned(),
    }
}

fn other_details(opt: &OperationalTemplate) -> IndexMap<String, String> {
    let mut out = IndexMap::new();
    if let Some(desc) = &opt.description
        && let Some(details) = &desc.other_details
    {
        // `otherDetails` keeps only `is_singleton`. No openEHR spec governs this
        // root field — our own design/extension.
        if let Some(v) = details.get("is_singleton") {
            out.insert("is_singleton".to_owned(), v.clone());
        }
    }
    out
}

// ── opt14 object metadata ────────────────────────────────────────────────────

fn object_rm_type(co: &CObject) -> &str {
    match co {
        CObject::CComplexObject(c) => &c.rm_type_name,
        CObject::CArchetypeRoot(c) => &c.rm_type_name,
        CObject::CCodePhrase(c) => &c.rm_type_name,
        CObject::CCodeReference(c) => &c.rm_type_name,
        CObject::CDvOrdinal(c) => &c.rm_type_name,
        CObject::CDvQuantity(c) => &c.rm_type_name,
        CObject::CDvState(c) => &c.rm_type_name,
        CObject::CPrimitiveObject(c) => &c.rm_type_name,
        CObject::CDefinedObject(c) => &c.rm_type_name,
        CObject::ArchetypeInternalRef(c) => &c.rm_type_name,
        CObject::ArchetypeSlot(c) => &c.rm_type_name,
        CObject::ConstraintRef(c) => &c.rm_type_name,
        CObject::TComplexObject(c) => &c.rm_type_name,
    }
}

fn object_node_id(co: &CObject) -> &str {
    match co {
        CObject::CComplexObject(c) => &c.node_id,
        CObject::CArchetypeRoot(c) => &c.node_id,
        CObject::CCodePhrase(c) => &c.node_id,
        CObject::CCodeReference(c) => &c.node_id,
        CObject::CDvOrdinal(c) => &c.node_id,
        CObject::CDvQuantity(c) => &c.node_id,
        CObject::CDvState(c) => &c.node_id,
        CObject::CPrimitiveObject(c) => &c.node_id,
        CObject::CDefinedObject(c) => &c.node_id,
        CObject::ArchetypeInternalRef(c) => &c.node_id,
        CObject::ArchetypeSlot(c) => &c.node_id,
        CObject::ConstraintRef(c) => &c.node_id,
        CObject::TComplexObject(c) => &c.node_id,
    }
}

/// The RM `archetype_node_id`: the archetype id at archetype roots, else the
/// constraint node id (`atNNNN`).
fn object_archetype_node_id(co: &CObject) -> String {
    match co {
        CObject::CArchetypeRoot(c) => c.archetype_id.value.clone(),
        _ => object_node_id(co).to_owned(),
    }
}

fn object_occurrences(co: &CObject) -> &Intervalofinteger {
    match co {
        CObject::CComplexObject(c) => &c.occurrences,
        CObject::CArchetypeRoot(c) => &c.occurrences,
        CObject::CCodePhrase(c) => &c.occurrences,
        CObject::CCodeReference(c) => &c.occurrences,
        CObject::CDvOrdinal(c) => &c.occurrences,
        CObject::CDvQuantity(c) => &c.occurrences,
        CObject::CDvState(c) => &c.occurrences,
        CObject::CPrimitiveObject(c) => &c.occurrences,
        CObject::CDefinedObject(c) => &c.occurrences,
        CObject::ArchetypeInternalRef(c) => &c.occurrences,
        CObject::ArchetypeSlot(c) => &c.occurrences,
        CObject::ConstraintRef(c) => &c.occurrences,
        CObject::TComplexObject(c) => &c.occurrences,
    }
}

/// `(min, max)` from an occurrences/cardinality interval; `max == -1` unbounded.
fn occurrences(iv: &Intervalofinteger) -> (Option<i32>, i32) {
    let min = if iv.lower_unbounded { None } else { iv.lower };
    let max = if iv.upper_unbounded { None } else { iv.upper };
    (min, max.unwrap_or(-1))
}

/// A single fixed name constraint (`name/value` `C_STRING` with one value), used
/// for the `[atNNNN,'Name']` path predicate.
fn name_constraint(co: &CObject) -> Option<String> {
    for name_child in inputs::attr_children(co, "name") {
        if let Some(CPrimitive::CString(cs)) = inputs::primitive_under(name_child, "value")
            && cs.list.len() == 1
        {
            return cs.list.first().cloned();
        }
    }
    None
}

/// The `DV_CODED_TEXT` name constraint on `co`'s `name` attribute, when the
/// template constrains the runtime `LOCATABLE.name` as a coded text: the display
/// value plus the `defining_code` `(terminology, code)` the composition builder
/// must stamp. Returns `None` for an unconstrained name or a plain `DV_TEXT`
/// name constraint. Spec: RM common `master03-archetyped_package.adoc` §"The
/// `LOCATABLE` class" (name is `DV_TEXT` or `DV_CODED_TEXT`); AOM 1.4
/// `master04-constraint_model_package.adoc` (a `C_ATTRIBUTE` on `name`
/// constrains the whole coded name — `defining_code` + optional `value`).
///
/// `explicit` is the fixed `name/value` `C_STRING` value (from
/// [`name_constraint`]) when the template also narrows the coded name's text.
/// The code is chosen as the `code_list` member whose archetype rubric equals
/// `explicit` (so a name-differentiated sibling keeps its intended code), else
/// the sole member of a single-code list, else the first candidate. The display
/// value is `explicit` when present, else the chosen code's archetype rubric.
fn coded_name_constraint(
    co: &CObject,
    ctx: &Ctx,
    arch_id: &str,
    explicit: Option<&str>,
) -> Option<(String, CodedName)> {
    let name_child =
        inputs::attr_children(co, "name").find(|c| object_rm_type(c) == "DV_CODED_TEXT")?;
    let code_phrase = inputs::attr_children(name_child, "defining_code").find_map(|c| match c {
        CObject::CCodePhrase(cp) => Some(cp),
        _ => None,
    })?;
    let (first, rest) = code_phrase.code_list.split_first()?;
    let terminology = code_phrase
        .terminology_id
        .as_ref()
        .map(|t| t.value.clone())
        .filter(|t| !t.is_empty())
        .unwrap_or_else(|| "local".to_owned());
    // Prefer the candidate code whose archetype rubric equals the fixed name
    // value, so a same-`archetype_node_id` sibling differentiated by a renamed
    // `name/value` keeps a code consistent with that value.
    let matched = explicit.and_then(|v| {
        std::iter::once(first)
            .chain(rest)
            .find(|c| ctx.text(arch_id, c, &ctx.default_language).as_deref() == Some(v))
            .cloned()
    });
    // A fixed value with NO rubric-matching candidate (and more than one
    // candidate to choose from) is display/rubric-incoherent — see
    // [`CodedName::incoherent`].
    let incoherent = explicit.is_some() && matched.is_none() && !rest.is_empty();
    let code = matched.unwrap_or_else(|| first.clone());
    let value = explicit
        .map(str::to_owned)
        .or_else(|| ctx.text(arch_id, &code, &ctx.default_language))
        .unwrap_or_else(|| code.clone());
    Some((
        value,
        CodedName {
            terminology,
            code,
            incoherent,
        },
    ))
}

fn build_path(
    parent_path: &str,
    attr_name: Option<&str>,
    arch_node_id: &str,
    name_constraint: Option<&str>,
) -> String {
    let Some(attr) = attr_name else {
        return String::new(); // root
    };
    let predicate = if arch_node_id.is_empty() {
        String::new()
    } else if let Some(name) = name_constraint {
        format!("[{arch_node_id},'{name}']")
    } else {
        format!("[{arch_node_id}]")
    };
    format!("{parent_path}/{attr}{predicate}")
}