openehr-lang 0.0.128

// SPDX-FileCopyrightText: Cadasto B.V.
// SPDX-FileCopyrightText: openEHR Foundation
// SPDX-License-Identifier: Apache-2.0

//! The P_BMM schema reader: ODIN `.bmm` text → a typed `P_BMM_SCHEMA` object
//! graph.
//!
//! "A BMM schema is a serialisation of the `P_BMM_*` object graph … The ODIN
//! form is described here. The structures are direct ODIN serialisations of the
//! `P_BMM_XXX` classes in the `persistence` package"
//! (`LANG/docs/bmm_persistence/master04-syntax.adoc` §Overview +
//! §Serialisation Formats). This module implements exactly that reading: it
//! parses the text with [`crate::v1_1::odin::parse`] and walks the resulting value
//! tree into the generated `P_BMM_*` types, attribute by attribute, per the
//! class docs under
//! `LANG/docs/UML/classes/org.openehr.lang.bmm_persistence.*.adoc`. The JSON
//! serialisation maps onto the same value tree
//! ([`crate::v1_1::bmm_persistence::json_reader`]) and is read by the same walk.
//!
//! It is the first of the three stages `master02-overview.adoc` §Conceptual
//! Approach describes — "A schema reading component has to resolve the schema
//! inclusions and ultimately `BMM_*` object instantiations to obtain the
//! in-memory form of the model": read
//! ([`read_schema`]) → resolve inclusions
//! ([`crate::v1_1::bmm_persistence::include_resolution::resolve_includes`]) →
//! instantiate ([`crate::v1_1::bmm_persistence::create_model::create_bmm_model`]).
//!
//! **Strict read.** An attribute the P_BMM class docs do not declare is a typed
//! [`PBmmReadError::UnknownAttribute`], never silently dropped — with the two
//! adjudicated tolerances [`TOLERATED_SCHEMA_ATTRIBUTES`] and
//! [`TOLERATED_PROPERTY_ATTRIBUTES`], each carrying its reason.
//!
//! **In-memory-only attributes are not read.** `master03-model.adoc` §Overview:
//! "attributes named `_bmm_xxx_` and of type `BMM_XXX` … are in-memory only
//! references to reconstructed instances", so they are left `None` here and
//! [`crate::v1_1::bmm_persistence::create_model`] reconstructs them.
//!
//! Two attributes documented as set by processing ARE stamped here, because
//! their inputs exist only while reading the file:
//! `P_BMM_CLASS.source_schema_id` takes this schema's own `schema_id`, and
//! `P_BMM_CLASS.uid` is numbered from 1 in document order over `primitive_types`
//! then `class_definitions`. A `(P_BMM_INTERFACE)` entry declares neither
//! (`…p_bmm_interface.adoc` §Attributes) and stamps neither, leaving the
//! remaining `uid`s document-ordered and unique.

#![expect(
    clippy::disallowed_types,
    reason = "ODIN-to-JSON conversion targets the JSON data model by specification (LANG odin \
              spec) (#1694)"
)]

use std::collections::BTreeMap;
use std::collections::BTreeSet;

use indexmap::IndexMap;
use openehr_base::v1_3::prelude::Interval;
use openehr_base::v1_3::prelude::ProperInterval;
use openehr_base::v1_3::prelude::ProperIntervalData;

use crate::v1_1::bmm::core::bmm_include_spec::BmmIncludeSpec;
use crate::v1_1::bmm_persistence::error::PBmmReadError;
use crate::v1_1::bmm_persistence::p_bmm_base_type::PBmmBaseType;
use crate::v1_1::bmm_persistence::p_bmm_class::PBmmClass;
use crate::v1_1::bmm_persistence::p_bmm_class::PBmmClassData;
use crate::v1_1::bmm_persistence::p_bmm_constant::PBmmConstant;
use crate::v1_1::bmm_persistence::p_bmm_container_function_parameter::PBmmContainerFunctionParameter;
use crate::v1_1::bmm_persistence::p_bmm_container_property::PBmmContainerProperty;
use crate::v1_1::bmm_persistence::p_bmm_container_property::PBmmContainerPropertyData;
use crate::v1_1::bmm_persistence::p_bmm_container_type::PBmmContainerType;
use crate::v1_1::bmm_persistence::p_bmm_container_type::PBmmContainerTypeData;
use crate::v1_1::bmm_persistence::p_bmm_enumeration::PBmmEnumeration;
use crate::v1_1::bmm_persistence::p_bmm_enumeration::PBmmEnumerationData;
use crate::v1_1::bmm_persistence::p_bmm_enumeration_integer::PBmmEnumerationInteger;
use crate::v1_1::bmm_persistence::p_bmm_enumeration_string::PBmmEnumerationString;
use crate::v1_1::bmm_persistence::p_bmm_function::PBmmFunction;
use crate::v1_1::bmm_persistence::p_bmm_function_parameter::PBmmFunctionParameter;
use crate::v1_1::bmm_persistence::p_bmm_generic_function_parameter::PBmmGenericFunctionParameter;
use crate::v1_1::bmm_persistence::p_bmm_generic_parameter::PBmmGenericParameter;
use crate::v1_1::bmm_persistence::p_bmm_generic_property::PBmmGenericProperty;
use crate::v1_1::bmm_persistence::p_bmm_generic_type::PBmmGenericType;
use crate::v1_1::bmm_persistence::p_bmm_indexed_container_property::PBmmIndexedContainerProperty;
use crate::v1_1::bmm_persistence::p_bmm_indexed_container_type::PBmmIndexedContainerType;
use crate::v1_1::bmm_persistence::p_bmm_interface::PBmmInterface;
use crate::v1_1::bmm_persistence::p_bmm_open_type::PBmmOpenType;
use crate::v1_1::bmm_persistence::p_bmm_package::PBmmPackage;
use crate::v1_1::bmm_persistence::p_bmm_property::PBmmProperty;
use crate::v1_1::bmm_persistence::p_bmm_schema::PBmmSchema;
use crate::v1_1::bmm_persistence::p_bmm_schema_impl::compose_schema_id;
use crate::v1_1::bmm_persistence::p_bmm_simple_type::PBmmSimpleType;
use crate::v1_1::bmm_persistence::p_bmm_single_function_parameter::PBmmSingleFunctionParameter;
use crate::v1_1::bmm_persistence::p_bmm_single_function_parameter_open::PBmmSingleFunctionParameterOpen;
use crate::v1_1::bmm_persistence::p_bmm_single_property::PBmmSingleProperty;
use crate::v1_1::bmm_persistence::p_bmm_single_property_open::PBmmSinglePropertyOpen;
use crate::v1_1::bmm_persistence::p_bmm_type::PBmmType;
use crate::v1_1::odin::OdinInterval;
use crate::v1_1::odin::OdinKey;
use crate::v1_1::odin::OdinValue;
use openehr_base::containers::present;

/// Schema-level attributes the pinned P_BMM model does not declare, accepted
/// and discarded.
///
/// `model_name` is written by `master04-syntax.adoc` §Header Items itself
/// (`model_name = <"TEST_PKG">`) and by the vendored openEHR `adltest` schema,
/// but neither `P_BMM_SCHEMA` nor `BMM_SCHEMA_CORE` declares it
/// (`org.openehr.lang.bmm_persistence.p_bmm_schema.adoc` +
/// `…bmm.bmm_schema_core.adoc` §Attributes); it is the v3
/// `BMM_MODEL.model_name` (`…bmm3.bmm_model.adoc` §Attributes), outside this
/// generation. Refusing a form the syntax chapter writes would reject valid
/// schema text, so it is tolerated.
pub const TOLERATED_SCHEMA_ATTRIBUTES: &[&str] = &["model_name"];

/// Property-level attributes the pinned P_BMM model does not declare, accepted
/// and discarded.
///
/// `default` appears on `(P_BMM_SINGLE_PROPERTY)` blocks throughout the
/// vendored openEHR BASE/RM/LANG/TERM ODIN schemas, but no attribute of
/// `P_BMM_PROPERTY` or `P_BMM_SINGLE_PROPERTY` corresponds to it
/// (`org.openehr.lang.bmm_persistence.p_bmm_property.adoc` +
/// `…p_bmm_single_property.adoc` §Attributes) and `master04-syntax.adoc` never
/// writes one. NOTE: no openEHR spec governs this attribute — accepting and
/// discarding it is our own decision, taken so the published openEHR schemas
/// read rather than being refused wholesale.
pub const TOLERATED_PROPERTY_ATTRIBUTES: &[&str] = &["default"];

/// Reads a P_BMM schema from its ODIN serialisation.
///
/// The returned `P_BMM_SCHEMA` is the *unresolved* persisted form: its
/// `includes` are recorded but not merged (that is
/// [`crate::v1_1::bmm_persistence::include_resolution::resolve_includes`]) and its
/// `bmm_*` in-memory caches are `None` (that is
/// [`crate::v1_1::bmm_persistence::create_model::create_bmm_model`]). The JSON
/// serialisation reads through
/// [`crate::v1_1::bmm_persistence::json_reader::read_schema_json`] into the same
/// value.
///
/// # Errors
/// Returns [`PBmmReadError::Odin`] when the text is not well-formed ODIN, and
/// one of the schema-shape variants (missing/unknown attribute, wrong value
/// shape, unexpected or missing type marker, key/name mismatch, qualified
/// nested package, unsupported cardinality) when the ODIN tree does not match
/// the P_BMM class model.
pub fn read_schema(src: &str) -> Result<PBmmSchema, PBmmReadError> {
    let root = crate::v1_1::odin::parse(src)?;
    read_schema_tree(&root)
}

/// Reads a P_BMM schema from a value tree in the ODIN data model, whichever
/// serialisation the tree was read from.
///
/// This is the one walk both serialisations share
/// (`master04-syntax.adoc` §Serialisation Formats: "Whatever the format, the
/// same serialisation rules apply"), including the stamping of
/// `P_BMM_CLASS.source_schema_id` and `uid` described in the module docs.
///
/// # Errors
/// Returns [`PBmmReadError::NotASchemaObject`] when the root is not an
/// attribute object, and the schema-shape variants [`read_schema`] lists when
/// the tree does not match the P_BMM class model.
pub(super) fn read_schema_tree(root: &OdinValue) -> Result<PBmmSchema, PBmmReadError> {
    let OdinValue::Object(members) = root else {
        return Err(PBmmReadError::NotASchemaObject {
            found: kind_name(root),
        });
    };
    let mut block = Block::new(String::new(), members);

    let bmm_version = block.required_string("bmm_version")?;
    let rm_publisher = block.required_string("rm_publisher")?;
    let schema_name = block.required_string("schema_name")?;
    let rm_release = block.required_string("rm_release")?;
    let schema_id = compose_schema_id(&rm_publisher, &schema_name, &rm_release);

    let schema_revision = block.documentation_string("schema_revision")?;
    let schema_lifecycle_state = block.documentation_string("schema_lifecycle_state")?;
    let schema_author = block.documentation_string("schema_author")?;
    let schema_description = block.documentation_string("schema_description")?;
    let schema_contributors = block.string_list("schema_contributors")?;
    let archetype_parent_class = block.optional_string("archetype_parent_class")?;
    let archetype_data_value_parent_class =
        block.optional_string("archetype_data_value_parent_class")?;
    let archetype_rm_closure_packages = block.string_list("archetype_rm_closure_packages")?;
    let archetype_visualise_descendants_of = block.visualise_descendants_of()?;

    let includes = read_includes(&mut block)?;
    let mut uid: i32 = 0;
    let primitive_types = read_class_list(&mut block, "primitive_types", &schema_id, &mut uid)?;
    let class_definitions = read_class_list(&mut block, "class_definitions", &schema_id, &mut uid)?;
    let packages = read_packages(&mut block, "packages", PackageLevel::Top)?;
    block.finish(TOLERATED_SCHEMA_ATTRIBUTES)?;

    Ok(PBmmSchema {
        packages,
        rm_publisher,
        rm_release,
        schema_name,
        schema_revision,
        schema_lifecycle_state,
        schema_author,
        schema_description,
        schema_contributors: present(schema_contributors),
        archetype_parent_class,
        archetype_data_value_parent_class,
        archetype_rm_closure_packages: present(archetype_rm_closure_packages),
        archetype_visualise_descendants_of,
        bmm_version,
        includes,
        primitive_types: (!primitive_types.is_empty()).then_some(primitive_types),
        class_definitions: (!class_definitions.is_empty()).then_some(class_definitions),
    })
}

/// Whether a package block sits at the schema's top level, where "only
/// top-level package ids can be paths"
/// (`master04-syntax.adoc` §Package Definition, first NOTE).
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum PackageLevel {
    /// A package declared directly under the schema's `packages` attribute.
    Top,
    /// A package declared under another package's `packages` attribute.
    Nested,
}

/// The ODIN value kind, for error text.
fn kind_name(value: &OdinValue) -> &'static str {
    match value {
        OdinValue::Object(_) => "an attribute object",
        OdinValue::KeyedList(_) => "a keyed list",
        OdinValue::List(_) => "a list",
        OdinValue::Typed { .. } => "a type-marked value",
        OdinValue::PathList(_) | OdinValue::Path(_) => "an object reference",
        OdinValue::Empty => "an empty block",
        OdinValue::String(_) => "a string",
        OdinValue::Integer(_) => "an integer",
        OdinValue::Real(_) => "a real",
        OdinValue::Boolean(_) => "a boolean",
        OdinValue::Character(_) => "a character",
        OdinValue::Date(_) => "a date",
        OdinValue::Time(_) => "a time",
        OdinValue::DateTime(_) => "a date/time",
        OdinValue::Duration(_) => "a duration",
        OdinValue::Interval(_) => "an interval",
        OdinValue::TermCode(_) => "a term code",
        OdinValue::Uri(_) => "a URI",
        OdinValue::PlugIn { .. } => "a plug-in-syntax block",
        OdinValue::ListContinue => "a list-continuation marker",
    }
}

/// A keyed-list key as written, without ODIN quoting.
fn key_text(key: &OdinKey) -> String {
    match key {
        OdinKey::String(text)
        | OdinKey::Date(text)
        | OdinKey::Time(text)
        | OdinKey::DateTime(text) => text.clone(),
        OdinKey::Integer(value) => value.to_string(),
    }
}

/// Joins an ODIN attribute path segment onto a parent path.
pub(super) fn join_path(parent: &str, segment: &str) -> String {
    if parent.is_empty() {
        segment.to_owned()
    } else {
        format!("{parent}/{segment}")
    }
}

/// One ODIN attribute object being read, tracking which of its members have been
/// consumed so [`Block::finish`] can refuse the rest.
struct Block<'a> {
    /// ODIN attribute path of this block, for error reporting.
    path: String,
    /// The block's members, in document order.
    members: &'a IndexMap<String, OdinValue>,
    /// Names consumed so far.
    consumed: BTreeSet<&'a str>,
}

impl<'a> Block<'a> {
    /// A block over `members` at `path`.
    fn new(path: String, members: &'a IndexMap<String, OdinValue>) -> Self {
        Self {
            path,
            members,
            consumed: BTreeSet::new(),
        }
    }

    /// The block's members, if `value` is an attribute object (or an empty
    /// block, which reads as no members).
    fn open(
        path: &str,
        value: &'a OdinValue,
        empty: &'a IndexMap<String, OdinValue>,
    ) -> Result<Self, PBmmReadError> {
        match value {
            OdinValue::Object(members) => Ok(Self::new(path.to_owned(), members)),
            OdinValue::Empty => Ok(Self::new(path.to_owned(), empty)),
            other => Err(PBmmReadError::WrongValueShape {
                path: path.to_owned(),
                expected: "an attribute object",
                found: kind_name(other),
            }),
        }
    }

    /// Marks `name` consumed and returns its value, if present.
    fn take(&mut self, name: &'static str) -> Option<&'a OdinValue> {
        self.consumed.insert(name);
        self.members.get(name)
    }

    /// The path of member `name`.
    fn member_path(&self, name: &str) -> String {
        join_path(&self.path, name)
    }

    /// A mandatory (`1..1`) `String` attribute.
    fn required_string(&mut self, name: &'static str) -> Result<String, PBmmReadError> {
        let path = self.member_path(name);
        match self.take(name) {
            Some(value) => as_string(&path, value),
            None => Err(PBmmReadError::MissingAttribute {
                path: self.path.clone(),
                attribute: name,
            }),
        }
    }

    /// An optional (`0..1`) `String` attribute.
    fn optional_string(&mut self, name: &'static str) -> Result<Option<String>, PBmmReadError> {
        let path = self.member_path(name);
        match self.take(name) {
            Some(value) => as_string(&path, value).map(Some),
            None => Ok(None),
        }
    }

    /// A `String` attribute the class docs declare `1..1` but
    /// `master04-syntax.adoc` §Header Items treats as optional.
    ///
    /// NOTE: `BMM_SCHEMA_CORE` declares the four documentation headers `1..1`
    /// (`org.openehr.lang.bmm.bmm_schema_core.adoc` §Attributes) yet the
    /// spec's own §Header Items example and most published schemas omit
    /// `schema_author` — an absent documentation header reads as the empty
    /// string rather than refusing published schema text; the four
    /// IDENTIFYING headers stay mandatory (`schema_id` derives from them).
    fn documentation_string(&mut self, name: &'static str) -> Result<String, PBmmReadError> {
        Ok(self.optional_string(name)?.unwrap_or_default())
    }

    /// `BMM_SCHEMA_CORE.archetype_visualise_descendants_of`, accepting the
    /// American spelling the vendored `TestBmm1` schema writes.
    ///
    /// NOTE (adjudicated): the spec attribute is
    /// `archetype_visualise_descendants_of`
    /// (`org.openehr.lang.bmm.bmm_schema_core.adoc` §Attributes); the
    /// `archetype_visualize_descendants_of` spelling found in schema text is
    /// read onto the same attribute rather than refused, since the two differ
    /// only in orthography and no second attribute exists to hold it.
    fn visualise_descendants_of(&mut self) -> Result<Option<String>, PBmmReadError> {
        let spec_spelling = self.optional_string("archetype_visualise_descendants_of")?;
        let variant_spelling = self.optional_string("archetype_visualize_descendants_of")?;
        Ok(spec_spelling.or(variant_spelling))
    }

    /// An optional attribute holding a scalar literal in its persisted
    /// (serialised) form.
    ///
    /// `P_BMM_CONSTANT.value` is "The literal value of this constant, in its
    /// persisted (serialised) form" typed `String`
    /// (`org.openehr.lang.bmm_persistence.p_bmm_constant.adoc` §Attributes), and
    /// `master04-syntax.adoc` §Constants writes it quoted
    /// (`value = <"local">`). The vendored openEHR BASE schemas also write bare
    /// ODIN scalars there (`value = <60>` on `Time_Definitions`), which are the
    /// serialised form of a non-`String` constant, so any scalar is accepted and
    /// its literal text taken.
    fn literal_text(&mut self, name: &'static str) -> Result<Option<String>, PBmmReadError> {
        let path = self.member_path(name);
        match self.take(name) {
            None => Ok(None),
            Some(value) => literal_text_of(&path, value).map(Some),
        }
    }

    /// An optional (`0..1`) `Boolean` attribute.
    fn optional_bool(&mut self, name: &'static str) -> Result<Option<bool>, PBmmReadError> {
        let path = self.member_path(name);
        match self.take(name) {
            Some(OdinValue::Boolean(flag)) => Ok(Some(*flag)),
            Some(other) => Err(PBmmReadError::WrongValueShape {
                path,
                expected: "a boolean",
                found: kind_name(other),
            }),
            None => Ok(None),
        }
    }

    /// A `List<String>` attribute, empty when absent.
    fn string_list(&mut self, name: &'static str) -> Result<Vec<String>, PBmmReadError> {
        let path = self.member_path(name);
        match self.take(name) {
            Some(value) => string_list_of(&path, value),
            None => Ok(Vec::new()),
        }
    }

    /// A `Hash<String, String>` attribute (assertion or alias tables), `None`
    /// when absent.
    fn string_map(
        &mut self,
        name: &'static str,
    ) -> Result<Option<BTreeMap<String, String>>, PBmmReadError> {
        let path = self.member_path(name);
        let Some(value) = self.take(name) else {
            return Ok(None);
        };
        let mut out = BTreeMap::new();
        for (key, item) in keyed_entries(&path, value)? {
            let key = key_text(key);
            let entry_path = join_path(&path, &key);
            let text = as_string(&entry_path, item)?;
            out.insert(key, text);
        }
        Ok(Some(out))
    }

    /// A `cardinality` attribute — an ODIN integer range
    /// (`master04-syntax.adoc` §Container Properties: "The optional
    /// `_cardinality_` meta-property indicates cardinality of the container, and
    /// is expressed as a ODIN range").
    fn cardinality(&mut self) -> Result<Option<Interval<i32>>, PBmmReadError> {
        let path = self.member_path("cardinality");
        match self.take("cardinality") {
            Some(OdinValue::Interval(interval)) => integer_interval(&path, interval).map(Some),
            Some(other) => Err(PBmmReadError::WrongValueShape {
                path,
                expected: "an interval",
                found: kind_name(other),
            }),
            None => Ok(None),
        }
    }

    /// Refuses any member neither consumed nor listed in `tolerated`.
    fn finish(&self, tolerated: &[&str]) -> Result<(), PBmmReadError> {
        for name in self.members.keys() {
            if self.consumed.contains(name.as_str()) || tolerated.contains(&name.as_str()) {
                continue;
            }
            return Err(PBmmReadError::UnknownAttribute {
                path: self.path.clone(),
                attribute: name.clone(),
            });
        }
        Ok(())
    }
}

/// A `String` leaf.
fn as_string(path: &str, value: &OdinValue) -> Result<String, PBmmReadError> {
    match value {
        OdinValue::String(text) => Ok(text.clone()),
        other => Err(PBmmReadError::WrongValueShape {
            path: path.to_owned(),
            expected: "a string",
            found: kind_name(other),
        }),
    }
}

/// One scalar ODIN leaf as its literal text (see [`Block::literal_text`]).
///
/// `True`/`False` are the ODIN boolean literals
/// (`LANG/docs/odin/master06-primitive_types` §Boolean).
fn literal_text_of(path: &str, value: &OdinValue) -> Result<String, PBmmReadError> {
    match value {
        OdinValue::String(text)
        | OdinValue::Date(text)
        | OdinValue::Time(text)
        | OdinValue::DateTime(text)
        | OdinValue::Duration(text)
        | OdinValue::TermCode(text)
        | OdinValue::Uri(text) => Ok(text.clone()),
        OdinValue::Integer(number) => Ok(number.to_string()),
        OdinValue::Real(number) => Ok(number.to_string()),
        OdinValue::Character(character) => Ok(character.to_string()),
        OdinValue::Boolean(true) => Ok("True".to_owned()),
        OdinValue::Boolean(false) => Ok("False".to_owned()),
        other => Err(PBmmReadError::WrongValueShape {
            path: path.to_owned(),
            expected: "a scalar literal",
            found: kind_name(other),
        }),
    }
}

/// A `List<String>` leaf: a single string, a string list, or an empty block.
///
/// NOTE: a trailing ODIN list-continuation marker (`ancestors = <"Any", ...>`,
/// the form `master04-syntax.adoc` §Simple Classes and the vendored schemas
/// write) marks the list as open — `LANG/docs/odin/master05-content` §Container
/// Objects — and contributes no member, so it is dropped.
fn string_list_of(path: &str, value: &OdinValue) -> Result<Vec<String>, PBmmReadError> {
    match value {
        OdinValue::String(text) => Ok(vec![text.clone()]),
        OdinValue::Empty => Ok(Vec::new()),
        OdinValue::List(items) => items
            .iter()
            .filter(|item| !matches!(item, OdinValue::ListContinue))
            .map(|item| as_string(path, item))
            .collect(),
        other => Err(PBmmReadError::WrongValueShape {
            path: path.to_owned(),
            expected: "a string list",
            found: kind_name(other),
        }),
    }
}

/// A `List<Any>` leaf of enumeration item values, as JSON scalars.
///
/// `P_BMM_ENUMERATION.item_values` is `List<Any>` (class doc §Attributes) and
/// `master04-syntax.adoc` §Enumerated Types writes integer and string members
/// (`item_values = <0, 1001, 1002, 1003>`, `item_values = <"<=", ">=", "=", "~">`).
fn any_list_of(path: &str, value: &OdinValue) -> Result<Vec<serde_json::Value>, PBmmReadError> {
    match value {
        OdinValue::Empty => Ok(Vec::new()),
        OdinValue::List(items) => items
            .iter()
            .filter(|item| !matches!(item, OdinValue::ListContinue))
            .map(|item| any_scalar(path, item))
            .collect(),
        single => any_scalar(path, single).map(|scalar| vec![scalar]),
    }
}

/// One enumeration item value as a JSON scalar.
fn any_scalar(path: &str, value: &OdinValue) -> Result<serde_json::Value, PBmmReadError> {
    match value {
        OdinValue::String(text) => Ok(serde_json::Value::String(text.clone())),
        OdinValue::Integer(number) => Ok(serde_json::Value::from(*number)),
        OdinValue::Boolean(flag) => Ok(serde_json::Value::Bool(*flag)),
        OdinValue::Character(character) => Ok(serde_json::Value::String(character.to_string())),
        OdinValue::Real(number) => serde_json::Number::from_f64(*number)
            .map(serde_json::Value::Number)
            .ok_or_else(|| PBmmReadError::WrongValueShape {
                path: path.to_owned(),
                expected: "a finite real",
                found: "a non-finite real",
            }),
        other => Err(PBmmReadError::WrongValueShape {
            path: path.to_owned(),
            expected: "an enumeration item value",
            found: kind_name(other),
        }),
    }
}

/// The entries of a keyed container attribute (`["k"] = <…>`), or none for an
/// empty block.
fn keyed_entries<'a>(
    path: &str,
    value: &'a OdinValue,
) -> Result<&'a [(OdinKey, OdinValue)], PBmmReadError> {
    match value {
        OdinValue::KeyedList(entries) => Ok(entries.as_slice()),
        OdinValue::Empty => Ok(&[]),
        other => Err(PBmmReadError::WrongValueShape {
            path: path.to_owned(),
            expected: "a keyed list",
            found: kind_name(other),
        }),
    }
}

/// The keyed attribute `name` read entry by entry: `read` takes each entry's
/// path, key and value. `None` when the attribute is absent.
fn keyed_map<V>(
    block: &mut Block<'_>,
    name: &'static str,
    mut read: impl FnMut(&str, &str, &OdinValue) -> Result<V, PBmmReadError>,
) -> Result<Option<BTreeMap<String, V>>, PBmmReadError> {
    let path = block.member_path(name);
    let Some(value) = block.take(name) else {
        return Ok(None);
    };
    let mut out = BTreeMap::new();
    for (key, entry) in keyed_entries(&path, value)? {
        let key = key_text(key);
        let read_entry = read(&join_path(&path, &key), &key, entry)?;
        out.insert(key, read_entry);
    }
    Ok(Some(out))
}

/// An ODIN range as an `Interval<Integer>`.
///
/// A `None` endpoint is unbounded on that side (the representation
/// [`crate::v1_1::odin::OdinInterval`] already uses), so `|>=1|` reads as
/// `lower = 1, upper unbounded` and `|0..*|` as `lower = 0, upper unbounded`.
/// Always the `Proper_interval` form: `Multiplicity_interval` is "any two-sided
/// or one-sided interval" (`BASE/docs/foundation_types` `Proper_interval`), and
/// a point cardinality `|1|` is the two-sided `1..1`.
fn integer_interval(path: &str, interval: &OdinInterval) -> Result<Interval<i32>, PBmmReadError> {
    let OdinInterval::Range {
        lower,
        lower_included,
        upper,
        upper_included,
    } = interval
    else {
        return Err(PBmmReadError::UnsupportedCardinality {
            path: path.to_owned(),
        });
    };
    let lower = interval_bound(path, lower.as_deref())?;
    let upper = interval_bound(path, upper.as_deref())?;
    Ok(Interval::ProperInterval(ProperInterval::ProperInterval(
        ProperIntervalData {
            lower,
            upper,
            lower_unbounded: lower.is_none(),
            upper_unbounded: upper.is_none(),
            lower_included: *lower_included,
            upper_included: *upper_included,
        },
    )))
}

/// One interval endpoint as an `Integer`.
fn interval_bound(path: &str, bound: Option<&OdinValue>) -> Result<Option<i32>, PBmmReadError> {
    match bound {
        None => Ok(None),
        Some(OdinValue::Integer(number)) => i32::try_from(*number).map(Some).map_err(|_overflow| {
            PBmmReadError::UnsupportedCardinality {
                path: path.to_owned(),
            }
        }),
        Some(_) => Err(PBmmReadError::UnsupportedCardinality {
            path: path.to_owned(),
        }),
    }
}

/// The ODIN type marker on `value`, and the value it wraps.
///
/// `master04-syntax.adoc` §Serialisation Formats: "ODIN uses a type marker
/// `(P_BMM_SINGLE_PROPERTY)`"; "Where the type is unambiguous from context
/// (such as a class definition or a package), no discriminator is needed".
fn split_marker(value: &OdinValue) -> (Option<&str>, &OdinValue) {
    match value {
        OdinValue::Typed { rm_type, value } => (Some(rm_type.as_str()), value.as_ref()),
        plain => (None, plain),
    }
}

/// Reads the schema's `includes` attribute.
///
/// `P_BMM_SCHEMA.includes` is "Other schemas included by this schema, keyed by
/// schema id" (class doc §Attributes), while `master04-syntax.adoc`
/// §Inclusions writes the blocks under ordinal keys (`["1"] = < id = <"…"> >`)
/// and the vendored openEHR component schemas key them by the id itself.
///
/// NOTE (adjudicated): the map is therefore keyed by each block's own `id`, the
/// keying the class doc mandates; the ODIN key is positional in the §Inclusions
/// form and carries no information the `id` does not.
fn read_includes(
    block: &mut Block<'_>,
) -> Result<Option<BTreeMap<String, BmmIncludeSpec>>, PBmmReadError> {
    let path = block.member_path("includes");
    let Some(value) = block.take("includes") else {
        return Ok(None);
    };
    let empty = IndexMap::new();
    let mut out = BTreeMap::new();
    for (key, entry) in keyed_entries(&path, value)? {
        let entry_path = join_path(&path, &key_text(key));
        let mut entry_block = Block::open(&entry_path, entry, &empty)?;
        let id = entry_block.required_string("id")?;
        entry_block.finish(&[])?;
        out.insert(id.clone(), BmmIncludeSpec { id });
    }
    Ok(Some(out))
}

/// Reads a `packages` attribute into a `P_BMM_PACKAGE` tree.
///
/// `master04-syntax.adoc` §Package Definition: "just name the classes and
/// packages in a recursive fashion", with its three NOTEs enforced —
/// only a top-level package id may be a path
/// ([`PBmmReadError::QualifiedNestedPackage`]), and the ODIN key must equal the
/// block's `name` ([`PBmmReadError::KeyNameMismatch`]). The third NOTE (a
/// package may reference only classes the same schema defines) is schema-global
/// rather than local to one block, so it is enforced where the whole schema is
/// in scope — [`crate::v1_1::bmm_persistence::create_model::create_bmm_model`]'s
/// [`PBmmReadError::ClassNotDefined`].
fn read_packages(
    block: &mut Block<'_>,
    name: &'static str,
    level: PackageLevel,
) -> Result<BTreeMap<String, PBmmPackage>, PBmmReadError> {
    let path = block.member_path(name);
    // NOTE: master04-syntax.adoc §Package Definition shows a leaf package without `packages`,
    // against the 1..1 class table (upstream #3770); absent reads as the empty map, as in
    // the generated JSON reader.
    let Some(value) = block.take(name) else {
        return Ok(BTreeMap::new());
    };
    let empty = IndexMap::new();
    let mut out = BTreeMap::new();
    for (key, entry) in keyed_entries(&path, value)? {
        let key = key_text(key);
        let entry_path = join_path(&path, &key);
        let mut entry_block = Block::open(&entry_path, entry, &empty)?;
        let package_name = read_name(&mut entry_block, &key)?;
        if level == PackageLevel::Nested && package_name.contains('.') {
            return Err(PBmmReadError::QualifiedNestedPackage {
                path: entry_path,
                name: package_name,
            });
        }
        let documentation = entry_block.optional_string("documentation")?;
        let classes = entry_block.string_list("classes")?;
        let packages = read_packages(&mut entry_block, "packages", PackageLevel::Nested)?;
        entry_block.finish(&[])?;
        out.insert(
            key,
            PBmmPackage {
                packages,
                documentation,
                name: package_name,
                classes: present(classes),
                bmm_package_definition: None,
            },
        );
    }
    Ok(out)
}

/// The `name` attribute of a keyed block, defaulting to its ODIN key.
///
/// `master04-syntax.adoc` §Non-primitive Classes: "Since `name` is a BMM
/// meta-model attribute, the class definition always contains its ODIN key";
/// §Package Definition NOTE: "make sure that the ODIN 'keys' are the same as
/// the 'name' attributes in each block". A stated `name` that disagrees with the
/// key is a [`PBmmReadError::KeyNameMismatch`]; an omitted `name` takes the key,
/// which the chapter says it equals.
fn read_name(block: &mut Block<'_>, key: &str) -> Result<String, PBmmReadError> {
    match block.optional_string("name")? {
        None => Ok(key.to_owned()),
        Some(name) if name == key => Ok(name),
        Some(name) => Err(PBmmReadError::KeyNameMismatch {
            path: block.path.clone(),
            key: key.to_owned(),
            name,
        }),
    }
}

/// Reads a `primitive_types` or `class_definitions` attribute.
///
/// `master04-syntax.adoc` §Classes for Primitive Types: primitive-type
/// definitions "are just normal class definitions within a `primitive_types`
/// block", so both lists read identically; the distinction is carried into the
/// BMM model by `BMM_CLASS.is_primitive_type`.
fn read_class_list(
    block: &mut Block<'_>,
    name: &'static str,
    schema_id: &str,
    uid: &mut i32,
) -> Result<BTreeMap<String, PBmmClass>, PBmmReadError> {
    let path = block.member_path(name);
    let Some(value) = block.take(name) else {
        return Ok(BTreeMap::new());
    };
    let mut out = BTreeMap::new();
    for (key, entry) in keyed_entries(&path, value)? {
        let key = key_text(key);
        let entry_path = join_path(&path, &key);
        *uid = uid.saturating_add(1);
        let class = read_class(&entry_path, &key, entry, schema_id, *uid)?;
        out.insert(key, class);
    }
    Ok(out)
}

/// The attributes every `P_BMM_CLASS` leaf carries, read once and distributed
/// over the concrete generated struct the type marker selects.
struct ClassParts {
    /// `P_BMM_MODEL_ELEMENT.documentation`.
    documentation: Option<String>,
    /// `P_BMM_CLASS.name`.
    name: String,
    /// `P_BMM_CLASS.ancestors` (optional container: `None` = the class
    /// declares no ancestors).
    ancestors: Option<Vec<String>>,
    /// `P_BMM_CLASS.constants`.
    constants: Option<BTreeMap<String, PBmmConstant>>,
    /// `P_BMM_CLASS.properties`.
    properties: Option<BTreeMap<String, PBmmProperty>>,
    /// `P_BMM_CLASS.functions`.
    functions: Option<BTreeMap<String, PBmmFunction>>,
    /// `P_BMM_CLASS.invariants`.
    invariants: Option<BTreeMap<String, String>>,
    /// `P_BMM_CLASS.is_abstract`.
    is_abstract: Option<bool>,
    /// `P_BMM_CLASS.is_override`.
    is_override: Option<bool>,
    /// `P_BMM_CLASS.generic_parameter_defs`, in declaration order.
    generic_parameter_defs: Option<IndexMap<String, PBmmGenericParameter>>,
    /// `P_BMM_CLASS.source_schema_id`, stamped by the reader.
    source_schema_id: String,
    /// `P_BMM_CLASS.uid`, stamped by the reader.
    uid: i32,
    /// `P_BMM_CLASS.ancestor_defs`, keyed by type signature.
    ancestor_defs: Option<BTreeMap<String, PBmmBaseType>>,
}

/// The enumeration-only attributes of `P_BMM_ENUMERATION`.
struct EnumerationParts {
    /// `P_BMM_ENUMERATION.item_names` (optional container).
    item_names: Option<Vec<String>>,
    /// `P_BMM_ENUMERATION.item_values` (optional container).
    item_values: Option<Vec<serde_json::Value>>,
    /// `P_BMM_ENUMERATION.item_documentations` (optional container).
    item_documentations: Option<Vec<String>>,
}

/// A `P_BMM_CLASS` descendant `$ty` from its [`ClassParts`]: the generated
/// descendants repeat the `P_BMM_CLASS` attributes as fields of their own, and
/// an enumeration form adds its [`EnumerationParts`] after them.
macro_rules! class_from_parts {
    ($ty:ident, $parts:expr, enumeration $items:expr) => {{
        let items: EnumerationParts = $items;
        class_from_parts!(
            $ty,
            $parts,
            item_names: items.item_names,
            item_values: items.item_values,
            item_documentations: items.item_documentations,
        )
    }};
    ($ty:ident, $parts:expr $(, $field:ident $(: $value:expr)?)* $(,)?) => {{
        let parts: ClassParts = $parts;
        $ty {
            documentation: parts.documentation,
            name: parts.name,
            ancestors: parts.ancestors,
            constants: parts.constants,
            properties: parts.properties,
            functions: parts.functions,
            invariants: parts.invariants,
            is_abstract: parts.is_abstract,
            is_override: parts.is_override,
            generic_parameter_defs: parts.generic_parameter_defs,
            source_schema_id: parts.source_schema_id,
            bmm_class: None,
            uid: parts.uid,
            ancestor_defs: parts.ancestor_defs,
            $($field $(: $value)?,)*
        }
    }};
}

/// Reads one class definition, dispatching on its optional type marker.
///
/// A `(P_BMM_INTERFACE)`-marked entry reads into
/// [`PBmmClass::PBmmInterface`]: `master02-overview.adoc` §Conceptual Approach
/// says the model "can also represent pure interfaces via `P_BMM_INTERFACE`,
/// i.e. class-like definitions that declare only functions and carry no state",
/// and openEHR's own published schemas serialise them as members of
/// `class_definitions` (the vendored BASE 1.3.0 and RM 1.2.0 ODIN schemas mark
/// `Env`, `Locale`, `Math`, `Quantity_converter`, `Statistical_evaluator`,
/// `CODE_SET_ACCESS` and `TERMINOLOGY_ACCESS` that way). It declares exactly
/// three attributes — `name`, `documentation` (inherited) and `functions`
/// (`…p_bmm_interface.adoc` §Attributes) — so no other class attribute is read
/// for it.
fn read_class(
    path: &str,
    key: &str,
    value: &OdinValue,
    schema_id: &str,
    uid: i32,
) -> Result<PBmmClass, PBmmReadError> {
    let (marker, body) = split_marker(value);
    let empty = IndexMap::new();
    let mut block = Block::open(path, body, &empty)?;
    if marker == Some("P_BMM_INTERFACE") {
        let name = read_name(&mut block, key)?;
        let documentation = block.optional_string("documentation")?;
        let functions = read_functions(&mut block)?;
        block.finish(&[])?;
        return Ok(PBmmClass::PBmmInterface(PBmmInterface {
            documentation,
            name,
            functions,
        }));
    }
    let parts = read_class_parts(&mut block, key, schema_id, uid)?;
    let class = match marker {
        None | Some("P_BMM_CLASS") => {
            block.finish(&[])?;
            PBmmClass::PBmmClass(class_from_parts!(PBmmClassData, parts))
        }
        Some("P_BMM_ENUMERATION") => {
            let items = read_enumeration_parts(&mut block)?;
            block.finish(&[])?;
            PBmmClass::PBmmEnumeration(PBmmEnumeration::PBmmEnumeration(
                class_from_parts!(PBmmEnumerationData, parts, enumeration items),
            ))
        }
        Some("P_BMM_ENUMERATION_INTEGER") => {
            let items = read_enumeration_parts(&mut block)?;
            block.finish(&[])?;
            PBmmClass::PBmmEnumeration(PBmmEnumeration::PBmmEnumerationInteger(
                class_from_parts!(PBmmEnumerationInteger, parts, enumeration items),
            ))
        }
        Some("P_BMM_ENUMERATION_STRING") => {
            let items = read_enumeration_parts(&mut block)?;
            block.finish(&[])?;
            PBmmClass::PBmmEnumeration(PBmmEnumeration::PBmmEnumerationString(
                class_from_parts!(PBmmEnumerationString, parts, enumeration items),
            ))
        }
        Some(other) => {
            return Err(PBmmReadError::UnexpectedTypeMarker {
                path: path.to_owned(),
                marker: other.to_owned(),
                expected: "P_BMM_CLASS",
            });
        }
    };
    Ok(class)
}

/// Reads the `P_BMM_CLASS` attribute set shared by every class form.
fn read_class_parts(
    block: &mut Block<'_>,
    key: &str,
    schema_id: &str,
    uid: i32,
) -> Result<ClassParts, PBmmReadError> {
    let name = read_name(block, key)?;
    Ok(ClassParts {
        documentation: block.optional_string("documentation")?,
        ancestors: present(block.string_list("ancestors")?),
        constants: read_constants(block)?,
        properties: read_properties(block)?,
        functions: read_functions(block)?,
        invariants: block.string_map("invariants")?,
        is_abstract: block.optional_bool("is_abstract")?,
        is_override: block.optional_bool("is_override")?,
        generic_parameter_defs: read_generic_parameter_defs(block)?,
        ancestor_defs: read_ancestor_defs(block)?,
        source_schema_id: schema_id.to_owned(),
        uid,
        name,
    })
}

/// Reads the `P_BMM_ENUMERATION` item lists.
fn read_enumeration_parts(block: &mut Block<'_>) -> Result<EnumerationParts, PBmmReadError> {
    let values_path = block.member_path("item_values");
    let item_values = match block.take("item_values") {
        Some(value) => any_list_of(&values_path, value)?,
        None => Vec::new(),
    };
    Ok(EnumerationParts {
        item_names: present(block.string_list("item_names")?),
        item_documentations: present(block.string_list("item_documentations")?),
        item_values: present(item_values),
    })
}

/// Reads a class's `generic_parameter_defs`.
///
/// `master04-syntax.adoc` §Generic Classes: "the usual ODIN keyed hash
/// structure is used with each member being keyed by a generic parameter name".
/// The document order is kept: it is "the order of the owning class's formal
/// generic parameter declarations" every actual parameter list follows
/// (`…p_bmm_generic_type.adoc` §Attributes).
fn read_generic_parameter_defs(
    block: &mut Block<'_>,
) -> Result<Option<IndexMap<String, PBmmGenericParameter>>, PBmmReadError> {
    let path = block.member_path("generic_parameter_defs");
    let Some(value) = block.take("generic_parameter_defs") else {
        return Ok(None);
    };
    let empty = IndexMap::new();
    let mut out = IndexMap::new();
    for (key, entry) in keyed_entries(&path, value)? {
        let key = key_text(key);
        let entry_path = join_path(&path, &key);
        let mut entry_block = Block::open(&entry_path, entry, &empty)?;
        let name = read_name(&mut entry_block, &key)?;
        let documentation = entry_block.optional_string("documentation")?;
        let conforms_to_type = entry_block.optional_string("conforms_to_type")?;
        entry_block.finish(&[])?;
        out.insert(
            key,
            PBmmGenericParameter {
                documentation,
                name,
                conforms_to_type,
                bmm_generic_parameter: None,
            },
        );
    }
    Ok(Some(out))
}

/// Reads a class's `ancestor_defs`.
///
/// `P_BMM_CLASS.ancestor_defs` is `Hash<String, P_BMM_BASE_TYPE>`, "keyed by
/// type signature, e.g. `GENERIC_PARENT<T,SUPPLIER_B>`", listing a non-generic
/// ancestor of the same class "as a `P_BMM_SIMPLE_TYPE`" (class doc
/// §Attributes; `master04-syntax.adoc` §Inheritance). The keys are signatures,
/// not names, so they are not matched against a `name` attribute.
fn read_ancestor_defs(
    block: &mut Block<'_>,
) -> Result<Option<BTreeMap<String, PBmmBaseType>>, PBmmReadError> {
    let defs = keyed_map(block, "ancestor_defs", |path, _, entry| {
        read_base_type(path, entry)
    })?;
    Ok(defs.filter(|defs| !defs.is_empty()))
}

/// Reads a class's `constants`.
///
/// `master04-syntax.adoc` §Constants: "Each constant is a `P_BMM_CONSTANT`
/// carrying its `_type_` (a simple class name) and its literal `_value_` in
/// serialised form."
fn read_constants(
    block: &mut Block<'_>,
) -> Result<Option<BTreeMap<String, PBmmConstant>>, PBmmReadError> {
    let empty = IndexMap::new();
    keyed_map(block, "constants", |entry_path, key, entry| {
        let mut entry_block = Block::open(entry_path, entry, &empty)?;
        let name = read_name(&mut entry_block, key)?;
        let documentation = entry_block.optional_string("documentation")?;
        let r#type = entry_block.required_string("type")?;
        let value = entry_block.literal_text("value")?;
        entry_block.finish(&[])?;
        Ok(PBmmConstant {
            documentation,
            name,
            r#type,
            value,
        })
    })
}

/// Reads a class's `functions`.
///
/// `master04-syntax.adoc` §Functions: functions are "expressed as ODIN object
/// blocks under the `_functions_` keyword, keyed by function name … whose
/// formal parameters appear under `_parameters_`, keyed by parameter name, and
/// whose return type, if any, is stated in `_result_`. A function with no
/// `_result_` is a procedure."
fn read_functions(
    block: &mut Block<'_>,
) -> Result<Option<BTreeMap<String, PBmmFunction>>, PBmmReadError> {
    let empty = IndexMap::new();
    keyed_map(block, "functions", |entry_path, key, entry| {
        let mut entry_block = Block::open(entry_path, entry, &empty)?;
        let name = read_name(&mut entry_block, key)?;
        let documentation = entry_block.optional_string("documentation")?;
        let aliases = read_aliases(&mut entry_block)?;
        let is_abstract = entry_block.optional_bool("is_abstract")?;
        let parameters = read_parameters(&mut entry_block)?;
        let pre_conditions = entry_block.string_map("pre_conditions")?;
        let post_conditions = entry_block.string_map("post_conditions")?;
        let result_path = entry_block.member_path("result");
        let result = match entry_block.take("result") {
            Some(value) => Some(read_type(&result_path, value)?),
            None => None,
        };
        let is_nullable = entry_block.optional_bool("is_nullable")?;
        entry_block.finish(&[])?;
        Ok(PBmmFunction {
            documentation,
            name,
            aliases,
            is_abstract,
            parameters,
            pre_conditions,
            post_conditions,
            result,
            is_nullable,
        })
    })
}

/// Reads a function's `aliases`.
///
/// NOTE (adjudicated): `P_BMM_FUNCTION.aliases` is declared
/// `Hash<String, String>` "Optional alias names for this function, keyed by
/// alias" (class doc §Attributes), while the vendored openEHR schemas write it
/// as a plain ODIN string list (`aliases = <"=", "==">`). Each alias is
/// therefore entered under itself — the keying the class doc mandates — since
/// the list form carries no separate key.
fn read_aliases(block: &mut Block<'_>) -> Result<Option<BTreeMap<String, String>>, PBmmReadError> {
    let path = block.member_path("aliases");
    let Some(value) = block.take("aliases") else {
        return Ok(None);
    };
    if matches!(value, OdinValue::KeyedList(_)) {
        let mut out = BTreeMap::new();
        for (key, entry) in keyed_entries(&path, value)? {
            let key = key_text(key);
            let entry_path = join_path(&path, &key);
            let text = as_string(&entry_path, entry)?;
            out.insert(key, text);
        }
        return Ok(Some(out));
    }
    let aliases = string_list_of(&path, value)?;
    Ok(Some(
        aliases
            .into_iter()
            .map(|alias| (alias.clone(), alias))
            .collect(),
    ))
}

/// Reads a function's `parameters`.
///
/// `master04-syntax.adoc` §Functions: "Each parameter carries an ODIN type
/// marker indicating its `P_BMM_FUNCTION_PARAMETER` subtype, in direct analogy
/// with the property meta-types."
fn read_parameters(
    block: &mut Block<'_>,
) -> Result<Option<BTreeMap<String, PBmmFunctionParameter>>, PBmmReadError> {
    keyed_map(block, "parameters", read_parameter)
}

/// Reads one function parameter.
fn read_parameter(
    path: &str,
    key: &str,
    value: &OdinValue,
) -> Result<PBmmFunctionParameter, PBmmReadError> {
    let (marker, body) = split_marker(value);
    let empty = IndexMap::new();
    let mut block = Block::open(path, body, &empty)?;
    let name = read_name(&mut block, key)?;
    let documentation = block.optional_string("documentation")?;
    let is_nullable = block.optional_bool("is_nullable")?;
    let parameter = match marker {
        Some("P_BMM_SINGLE_FUNCTION_PARAMETER") => {
            let r#type = block.required_string("type")?;
            block.finish(&[])?;
            PBmmFunctionParameter::PBmmSingleFunctionParameter(PBmmSingleFunctionParameter {
                documentation,
                name,
                is_nullable,
                r#type,
            })
        }
        Some("P_BMM_SINGLE_FUNCTION_PARAMETER_OPEN") => {
            let r#type = block.required_string("type")?;
            block.finish(&[])?;
            PBmmFunctionParameter::PBmmSingleFunctionParameterOpen(
                PBmmSingleFunctionParameterOpen {
                    documentation,
                    name,
                    is_nullable,
                    r#type,
                },
            )
        }
        Some("P_BMM_CONTAINER_FUNCTION_PARAMETER") => {
            let type_def = read_required_container_type(&mut block)?;
            let cardinality = block.cardinality()?;
            block.finish(&[])?;
            PBmmFunctionParameter::PBmmContainerFunctionParameter(PBmmContainerFunctionParameter {
                documentation,
                name,
                is_nullable,
                type_def,
                cardinality,
            })
        }
        Some("P_BMM_GENERIC_FUNCTION_PARAMETER") => {
            let type_def_path = block.member_path("type_def");
            let Some(type_def) = block.take("type_def") else {
                return Err(PBmmReadError::MissingAttribute {
                    path: path.to_owned(),
                    attribute: "type_def",
                });
            };
            let type_def = read_generic_type(&type_def_path, type_def)?;
            block.finish(&[])?;
            PBmmFunctionParameter::PBmmGenericFunctionParameter(PBmmGenericFunctionParameter {
                documentation,
                name,
                is_nullable,
                type_def,
            })
        }
        Some(other) => {
            return Err(PBmmReadError::UnexpectedTypeMarker {
                path: path.to_owned(),
                marker: other.to_owned(),
                expected: "P_BMM_FUNCTION_PARAMETER",
            });
        }
        None => {
            return Err(PBmmReadError::MissingTypeMarker {
                path: path.to_owned(),
                expected: "P_BMM_FUNCTION_PARAMETER",
            });
        }
    };
    Ok(parameter)
}

/// Reads a mandatory `type_def` of `P_BMM_CONTAINER_TYPE`.
fn read_required_container_type(block: &mut Block<'_>) -> Result<PBmmContainerType, PBmmReadError> {
    let path = block.member_path("type_def");
    match block.take("type_def") {
        Some(value) => read_container_type(&path, value),
        None => Err(PBmmReadError::MissingAttribute {
            path: block.path.clone(),
            attribute: "type_def",
        }),
    }
}

/// Reads a class's `properties`.
///
/// `master04-syntax.adoc` §Class properties: "Class properties from the
/// original model are expressed using ODIN object blocks keyed by property
/// name. Since there are multiple possible descendants of `P_BMM_PROPERTY`,
/// ODIN type markers must be used to indicate which subtypes is used in each
/// case."
fn read_properties(
    block: &mut Block<'_>,
) -> Result<Option<BTreeMap<String, PBmmProperty>>, PBmmReadError> {
    keyed_map(block, "properties", read_property)
}

/// The attributes every `P_BMM_PROPERTY` leaf carries.
struct PropertyParts {
    /// `P_BMM_MODEL_ELEMENT.documentation`.
    documentation: Option<String>,
    /// `P_BMM_PROPERTY.name`.
    name: String,
    /// `P_BMM_PROPERTY.is_mandatory`.
    is_mandatory: Option<bool>,
    /// `P_BMM_PROPERTY.is_computed`.
    is_computed: Option<bool>,
    /// `P_BMM_PROPERTY.is_im_infrastructure`.
    is_im_infrastructure: Option<bool>,
    /// `P_BMM_PROPERTY.is_im_runtime`.
    is_im_runtime: Option<bool>,
}

/// Reads one class property.
#[expect(
    clippy::too_many_lines,
    reason = "one arm per P_BMM_PROPERTY subtype; splitting the dispatch would hide the five-way marker → generated-struct mapping master04 §Class properties defines"
)]
fn read_property(path: &str, key: &str, value: &OdinValue) -> Result<PBmmProperty, PBmmReadError> {
    let (marker, body) = split_marker(value);
    let empty = IndexMap::new();
    let mut block = Block::open(path, body, &empty)?;
    let parts = PropertyParts {
        name: read_name(&mut block, key)?,
        documentation: block.optional_string("documentation")?,
        is_mandatory: block.optional_bool("is_mandatory")?,
        is_computed: block.optional_bool("is_computed")?,
        is_im_infrastructure: block.optional_bool("is_im_infrastructure")?,
        is_im_runtime: block.optional_bool("is_im_runtime")?,
    };
    let property = match marker {
        Some("P_BMM_SINGLE_PROPERTY") => {
            let r#type = block.optional_string("type")?;
            let simple_ref = read_optional_simple_type(&mut block)?;
            let structural = read_optional_type(&mut block)?;
            block.finish(TOLERATED_PROPERTY_ATTRIBUTES)?;
            PBmmProperty::PBmmSingleProperty(PBmmSingleProperty {
                documentation: parts.documentation,
                name: parts.name,
                is_mandatory: parts.is_mandatory,
                is_computed: parts.is_computed,
                is_im_infrastructure: parts.is_im_infrastructure,
                is_im_runtime: parts.is_im_runtime,
                type_def: structural,
                bmm_property: None,
                r#type,
                type_ref: simple_ref,
            })
        }
        Some("P_BMM_SINGLE_PROPERTY_OPEN") => {
            let r#type = block.optional_string("type")?;
            let open_ref = read_optional_open_type(&mut block)?;
            let structural = read_optional_type(&mut block)?;
            block.finish(TOLERATED_PROPERTY_ATTRIBUTES)?;
            PBmmProperty::PBmmSinglePropertyOpen(PBmmSinglePropertyOpen {
                documentation: parts.documentation,
                name: parts.name,
                is_mandatory: parts.is_mandatory,
                is_computed: parts.is_computed,
                is_im_infrastructure: parts.is_im_infrastructure,
                is_im_runtime: parts.is_im_runtime,
                type_def: structural,
                bmm_property: None,
                type_ref: open_ref,
                r#type,
            })
        }
        Some("P_BMM_GENERIC_PROPERTY") => {
            let type_def_path = block.member_path("type_def");
            let type_def = match block.take("type_def") {
                Some(value) => Some(read_generic_type(&type_def_path, value)?),
                None => None,
            };
            block.finish(TOLERATED_PROPERTY_ATTRIBUTES)?;
            PBmmProperty::PBmmGenericProperty(PBmmGenericProperty {
                documentation: parts.documentation,
                name: parts.name,
                is_mandatory: parts.is_mandatory,
                is_computed: parts.is_computed,
                is_im_infrastructure: parts.is_im_infrastructure,
                is_im_runtime: parts.is_im_runtime,
                type_def,
                bmm_property: None,
            })
        }
        Some("P_BMM_CONTAINER_PROPERTY") => {
            let type_def_path = block.member_path("type_def");
            let type_def = match block.take("type_def") {
                Some(value) => Some(read_container_type(&type_def_path, value)?),
                None => None,
            };
            let cardinality = block.cardinality()?;
            block.finish(TOLERATED_PROPERTY_ATTRIBUTES)?;
            PBmmProperty::PBmmContainerProperty(PBmmContainerProperty::PBmmContainerProperty(
                PBmmContainerPropertyData {
                    documentation: parts.documentation,
                    name: parts.name,
                    is_mandatory: parts.is_mandatory,
                    is_computed: parts.is_computed,
                    is_im_infrastructure: parts.is_im_infrastructure,
                    is_im_runtime: parts.is_im_runtime,
                    type_def,
                    bmm_property: None,
                    cardinality,
                },
            ))
        }
        Some("P_BMM_INDEXED_CONTAINER_PROPERTY") => {
            let type_def_path = block.member_path("type_def");
            let type_def = match block.take("type_def") {
                Some(value) => Some(read_indexed_container_type(&type_def_path, value)?),
                None => None,
            };
            let cardinality = block.cardinality()?;
            block.finish(TOLERATED_PROPERTY_ATTRIBUTES)?;
            PBmmProperty::PBmmContainerProperty(
                PBmmContainerProperty::PBmmIndexedContainerProperty(PBmmIndexedContainerProperty {
                    documentation: parts.documentation,
                    name: parts.name,
                    is_mandatory: parts.is_mandatory,
                    is_computed: parts.is_computed,
                    is_im_infrastructure: parts.is_im_infrastructure,
                    is_im_runtime: parts.is_im_runtime,
                    type_def,
                    bmm_property: None,
                    cardinality,
                }),
            )
        }
        Some(other) => {
            return Err(PBmmReadError::UnexpectedTypeMarker {
                path: path.to_owned(),
                marker: other.to_owned(),
                expected: "P_BMM_PROPERTY",
            });
        }
        None => {
            return Err(PBmmReadError::MissingTypeMarker {
                path: path.to_owned(),
                expected: "P_BMM_PROPERTY",
            });
        }
    };
    Ok(property)
}

/// Reads an optional `type_def` of the polymorphic `P_BMM_TYPE` slot.
fn read_optional_type(block: &mut Block<'_>) -> Result<Option<PBmmType>, PBmmReadError> {
    let path = block.member_path("type_def");
    match block.take("type_def") {
        Some(value) => read_type(&path, value).map(Some),
        None => Ok(None),
    }
}

/// Reads an optional `type_ref` of `P_BMM_SIMPLE_TYPE`.
///
/// `master04-syntax.adoc` §Value-set Constraints: "The use of the
/// `value_constraint` attribute forces the use of the `type_ref` structural form
/// of the type definition within a `P_BMM_SINGLE_PROPERTY` instance, rather than
/// the simple `String` form."
fn read_optional_simple_type(
    block: &mut Block<'_>,
) -> Result<Option<PBmmSimpleType>, PBmmReadError> {
    let path = block.member_path("type_ref");
    match block.take("type_ref") {
        Some(value) => read_simple_type(&path, value).map(Some),
        None => Ok(None),
    }
}

/// Reads an optional `type_ref` of `P_BMM_OPEN_TYPE`.
fn read_optional_open_type(block: &mut Block<'_>) -> Result<Option<PBmmOpenType>, PBmmReadError> {
    let path = block.member_path("type_ref");
    match block.take("type_ref") {
        Some(value) => read_open_type(&path, value).map(Some),
        None => Ok(None),
    }
}

/// Reads a `P_BMM_TYPE`, from its marker where stated and from its member set
/// otherwise.
///
/// `master04-syntax.adoc` §Serialisation Formats requires the discriminator
/// only "Wherever a value may be one of several `P_BMM_*` subtypes": the
/// chapter's own examples omit it on a `type_def` whose declaring attribute is
/// a concrete type (`§Container Properties`, `§Generic Classes`). Where the slot
/// IS polymorphic and no marker is written, the subtype is inferred from the
/// attributes present, using the chapter's own rules (§Generic Classes: "use
/// 'type' for simple string type refs; use `_type_def_` for structure types;
/// within `P_BMM_GENERIC_TYPE`, use `_generic_parameters_` for a list of string
/// types") — `container_type` ⇒ a container type (indexed when `index_type` is
/// present), `root_type` ⇒ a generic type, `type` alone ⇒ a simple type.
fn read_type(path: &str, value: &OdinValue) -> Result<PBmmType, PBmmReadError> {
    let (marker, body) = split_marker(value);
    match marker {
        Some("P_BMM_SIMPLE_TYPE") => read_simple_type(path, value).map(PBmmType::PBmmSimpleType),
        Some("P_BMM_OPEN_TYPE") => read_open_type(path, value).map(PBmmType::PBmmOpenType),
        Some("P_BMM_GENERIC_TYPE") => read_generic_type(path, value).map(PBmmType::PBmmGenericType),
        Some("P_BMM_CONTAINER_TYPE" | "P_BMM_INDEXED_CONTAINER_TYPE") => {
            read_container_type(path, value).map(PBmmType::PBmmContainerType)
        }
        Some(other) => Err(PBmmReadError::UnexpectedTypeMarker {
            path: path.to_owned(),
            marker: other.to_owned(),
            expected: "P_BMM_TYPE",
        }),
        None => match infer_type_kind(body) {
            Some(TypeKind::Container | TypeKind::IndexedContainer) => {
                read_container_type(path, value).map(PBmmType::PBmmContainerType)
            }
            Some(TypeKind::Generic) => {
                read_generic_type(path, value).map(PBmmType::PBmmGenericType)
            }
            Some(TypeKind::Simple) => read_simple_type(path, value).map(PBmmType::PBmmSimpleType),
            None => Err(PBmmReadError::MissingTypeMarker {
                path: path.to_owned(),
                expected: "P_BMM_TYPE",
            }),
        },
    }
}

/// Reads a `P_BMM_BASE_TYPE` — the non-container half of the type family
/// (`…p_bmm_base_type.adoc` §Description: "Persistent form of a proper
/// (non-container) BMM type").
fn read_base_type(path: &str, value: &OdinValue) -> Result<PBmmBaseType, PBmmReadError> {
    let (marker, body) = split_marker(value);
    match marker {
        Some("P_BMM_SIMPLE_TYPE") => {
            read_simple_type(path, value).map(PBmmBaseType::PBmmSimpleType)
        }
        Some("P_BMM_OPEN_TYPE") => read_open_type(path, value).map(PBmmBaseType::PBmmOpenType),
        Some("P_BMM_GENERIC_TYPE") => {
            read_generic_type(path, value).map(PBmmBaseType::PBmmGenericType)
        }
        Some(other) => Err(PBmmReadError::UnexpectedTypeMarker {
            path: path.to_owned(),
            marker: other.to_owned(),
            expected: "P_BMM_BASE_TYPE",
        }),
        None => match infer_type_kind(body) {
            Some(TypeKind::Generic) => {
                read_generic_type(path, value).map(PBmmBaseType::PBmmGenericType)
            }
            Some(TypeKind::Simple) => {
                read_simple_type(path, value).map(PBmmBaseType::PBmmSimpleType)
            }
            Some(TypeKind::Container | TypeKind::IndexedContainer) | None => {
                Err(PBmmReadError::MissingTypeMarker {
                    path: path.to_owned(),
                    expected: "P_BMM_BASE_TYPE",
                })
            }
        },
    }
}

/// Which `P_BMM_TYPE` subtype an unmarked type block's members indicate.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum TypeKind {
    /// `container_type` + `index_type` present.
    IndexedContainer,
    /// `container_type` present.
    Container,
    /// `root_type` present.
    Generic,
    /// `type` present.
    Simple,
}

/// Infers the subtype of an unmarked type block from its members.
fn infer_type_kind(body: &OdinValue) -> Option<TypeKind> {
    let OdinValue::Object(members) = body else {
        return None;
    };
    if members.contains_key("container_type") {
        if members.contains_key("index_type") {
            return Some(TypeKind::IndexedContainer);
        }
        return Some(TypeKind::Container);
    }
    if members.contains_key("root_type") {
        return Some(TypeKind::Generic);
    }
    if members.contains_key("type") {
        return Some(TypeKind::Simple);
    }
    None
}

/// Reads a `P_BMM_SIMPLE_TYPE` (`type`, plus the optional
/// `P_BMM_BASE_TYPE.value_constraint`).
fn read_simple_type(path: &str, value: &OdinValue) -> Result<PBmmSimpleType, PBmmReadError> {
    let body = expect_marker(path, value, "P_BMM_SIMPLE_TYPE", &["P_BMM_SIMPLE_TYPE"])?;
    let empty = IndexMap::new();
    let mut block = Block::open(path, body, &empty)?;
    let r#type = block.required_string("type")?;
    let value_constraint = block.optional_string("value_constraint")?;
    block.finish(&[])?;
    Ok(PBmmSimpleType {
        bmm_type: None,
        value_constraint,
        r#type,
    })
}

/// Reads a `P_BMM_OPEN_TYPE` (a generic parameter name, plus the optional
/// `value_constraint`).
fn read_open_type(path: &str, value: &OdinValue) -> Result<PBmmOpenType, PBmmReadError> {
    let body = expect_marker(path, value, "P_BMM_OPEN_TYPE", &["P_BMM_OPEN_TYPE"])?;
    let empty = IndexMap::new();
    let mut block = Block::open(path, body, &empty)?;
    let r#type = block.required_string("type")?;
    let value_constraint = block.optional_string("value_constraint")?;
    block.finish(&[])?;
    Ok(PBmmOpenType {
        bmm_type: None,
        value_constraint,
        r#type,
    })
}

/// Reads a `P_BMM_GENERIC_TYPE`.
///
/// `master04-syntax.adoc` §Generic Classes: "`DV_INTERVAL` is the `_root_type_`";
/// "within `P_BMM_GENERIC_TYPE`, use `_generic_parameters_` for a list of
/// string types; use `_generic_parameter_defs_` for a list of complex type
/// references", keyed "by formal generic parameter name" and kept in document
/// order, which "must match the order of the owning class's formal generic
/// parameter declarations" (`…p_bmm_generic_type.adoc` §Attributes).
fn read_generic_type(path: &str, value: &OdinValue) -> Result<PBmmGenericType, PBmmReadError> {
    let body = expect_marker(path, value, "P_BMM_GENERIC_TYPE", &["P_BMM_GENERIC_TYPE"])?;
    let empty = IndexMap::new();
    let mut block = Block::open(path, body, &empty)?;
    let root_type = block.required_string("root_type")?;
    let (generic_parameters, mut generic_parameter_defs) = read_generic_parameters(&mut block)?;
    let defs_path = block.member_path("generic_parameter_defs");
    if let Some(defs) = block.take("generic_parameter_defs") {
        for (key, entry) in keyed_entries(&defs_path, defs)? {
            let key = key_text(key);
            let entry_path = join_path(&defs_path, &key);
            let def = read_type(&entry_path, entry)?;
            generic_parameter_defs.insert(key, def);
        }
    }
    let value_constraint = block.optional_string("value_constraint")?;
    block.finish(&[])?;
    Ok(PBmmGenericType {
        bmm_type: None,
        value_constraint,
        root_type,
        generic_parameter_defs: (!generic_parameter_defs.is_empty())
            .then_some(generic_parameter_defs),
        generic_parameters: present(generic_parameters),
    })
}

/// Reads a generic type's `generic_parameters` attribute.
///
/// The spec form is a plain ODIN string list — "use `_generic_parameters_` for a
/// list of string types" (`master04-syntax.adoc` §Generic Classes) — and reads
/// into `P_BMM_GENERIC_TYPE.generic_parameters`.
///
/// NOTE: the vendored openEHR AM schemas also write an INTEGER-KEYED list
/// mixing plain names with type-marked blocks — no openEHR spec governs that
/// positional form — and it is read entirely into `generic_parameter_defs`
/// under its integer keys (bare names promoted to `P_BMM_SIMPLE_TYPE`), which
/// [`PBmmGenericType::bind_parameters`] reads as formal positions.
fn read_generic_parameters(
    block: &mut Block<'_>,
) -> Result<(Vec<String>, IndexMap<String, PBmmType>), PBmmReadError> {
    let path = block.member_path("generic_parameters");
    let Some(value) = block.take("generic_parameters") else {
        return Ok((Vec::new(), IndexMap::new()));
    };
    if !matches!(value, OdinValue::KeyedList(_)) {
        return Ok((string_list_of(&path, value)?, IndexMap::new()));
    }
    let mut defs = IndexMap::new();
    for (key, entry) in keyed_entries(&path, value)? {
        let key = key_text(key);
        let entry_path = join_path(&path, &key);
        let def = match entry {
            OdinValue::String(name) => PBmmType::PBmmSimpleType(PBmmSimpleType {
                bmm_type: None,
                value_constraint: None,
                r#type: name.clone(),
            }),
            structured => read_type(&entry_path, structured)?,
        };
        defs.insert(key, def);
    }
    Ok((Vec::new(), defs))
}

/// Reads a `P_BMM_CONTAINER_TYPE`, selecting the indexed form by marker or by
/// the presence of `index_type`.
fn read_container_type(path: &str, value: &OdinValue) -> Result<PBmmContainerType, PBmmReadError> {
    let (marker, body) = split_marker(value);
    match marker {
        Some("P_BMM_INDEXED_CONTAINER_TYPE") => read_indexed_container_type(path, value)
            .map(PBmmContainerType::PBmmIndexedContainerType),
        Some("P_BMM_CONTAINER_TYPE") | None => {
            if infer_type_kind(body) == Some(TypeKind::IndexedContainer) {
                return read_indexed_container_type(path, value)
                    .map(PBmmContainerType::PBmmIndexedContainerType);
            }
            let empty = IndexMap::new();
            let mut block = Block::open(path, body, &empty)?;
            let container_type = block.required_string("container_type")?;
            let r#type = block.optional_string("type")?;
            let type_def = read_optional_base_type(&mut block)?;
            block.finish(&[])?;
            Ok(PBmmContainerType::PBmmContainerType(
                PBmmContainerTypeData {
                    bmm_type: None,
                    container_type,
                    type_def,
                    r#type,
                },
            ))
        }
        Some(other) => Err(PBmmReadError::UnexpectedTypeMarker {
            path: path.to_owned(),
            marker: other.to_owned(),
            expected: "P_BMM_CONTAINER_TYPE",
        }),
    }
}

/// Reads a `P_BMM_INDEXED_CONTAINER_TYPE`.
///
/// `master04-syntax.adoc` §Container Properties: "The meta-element `index_type`
/// is used to state the key type."
fn read_indexed_container_type(
    path: &str,
    value: &OdinValue,
) -> Result<PBmmIndexedContainerType, PBmmReadError> {
    let body = expect_marker(
        path,
        value,
        "P_BMM_INDEXED_CONTAINER_TYPE",
        &["P_BMM_INDEXED_CONTAINER_TYPE"],
    )?;
    let empty = IndexMap::new();
    let mut block = Block::open(path, body, &empty)?;
    let container_type = block.required_string("container_type")?;
    let index_type = block.required_string("index_type")?;
    let r#type = block.optional_string("type")?;
    let type_def = read_optional_base_type(&mut block)?;
    block.finish(&[])?;
    Ok(PBmmIndexedContainerType {
        bmm_type: None,
        container_type,
        type_def,
        r#type,
        index_type,
    })
}

/// Reads a container type's nested `type_def` (a `P_BMM_BASE_TYPE`).
fn read_optional_base_type(block: &mut Block<'_>) -> Result<Option<PBmmBaseType>, PBmmReadError> {
    let path = block.member_path("type_def");
    match block.take("type_def") {
        Some(value) => read_base_type(&path, value).map(Some),
        None => Ok(None),
    }
}

/// Unwraps a type block whose ODIN marker, when present, must be one of
/// `allowed`.
fn expect_marker<'a>(
    path: &str,
    value: &'a OdinValue,
    expected: &'static str,
    allowed: &[&str],
) -> Result<&'a OdinValue, PBmmReadError> {
    let (marker, body) = split_marker(value);
    match marker {
        None => Ok(body),
        Some(found) if allowed.contains(&found) => Ok(body),
        Some(found) => Err(PBmmReadError::UnexpectedTypeMarker {
            path: path.to_owned(),
            marker: found.to_owned(),
            expected,
        }),
    }
}

#[cfg(test)]
mod tests;