mml 2.3.7 → 2.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 47af8c20b7e74aa165f2c37b79c42114fefd3271cb69ede3c80dc684c6009295
-  data.tar.gz: 146194a451aefd1f06fdddbe0d914944650eefd3f555a1a09f792b110d64ffc6
+  metadata.gz: 753f58cf7a8516296624dc7eb472621cd4ecaab7a7d1c3f34d7e8d67eff9bbce
+  data.tar.gz: 062164c14aa4475421fc48ca37de907be75938d8b574a768cc8e8e374bd91252
 SHA512:
-  metadata.gz: 6ecd1f5b414c7ee585196a3576d2a34a76962e5ec4008013b1b3b6fada27df01d3cbe68891e80cc7077a7ccfc8996aa952d8617ebaf11b49b3bed11831cdf767
-  data.tar.gz: 2dddd5b009a917449239df9b663e31afc532e6f1b4562b37f6bb8edc9c3e4f1c6737bfafe4c0cf88344a6c5bec92038b2050442234fe2ea4573d816720164101
+  metadata.gz: b43c4d0bd97523c911860ff881eb7375ae9755ac5755985408c27c4aa43246d57cd4b26d7a8bb00c8e5020ee1b9cf9d331f49a6e3a5524957f36469d3c5b9549
+  data.tar.gz: 5d93d2e051d43efb46e83e36bc5464339020e73742183369e6b45813cf3fcd90203c3d3440768c8259f0e174c6435b20863a994debf4417f30308391c9df2e90

data/CLAUDE.md

@@ -4,70 +4,129 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Project Overview
 
-`mml` is a Ruby gem that provides MathML 3 and MathML 4 XML parsing and serialization. It maps MathML elements into Ruby model classes using the `lutaml-model` framework. Part of the [Plurimath](https://github.com/plurimath/mml) ecosystem.
+`mml` is a Ruby gem that provides MathML 2, MathML 3, and MathML 4 XML parsing and serialization. It maps MathML elements into Ruby model classes using the `lutaml-model` framework. Part of the [Plurimath](https://github.com/plurimath/mml) ecosystem.
 
 ## Commands
 
 ```bash
-rake                    # Run specs + rubocop (default task)
-bundle exec rspec       # Run tests
-bundle exec rspec spec/mml_spec.rb:42  # Run single test by line
-bundle exec rspec --only-failures      # Run only previously failing tests
-bundle exec rubocop     # Lint
-bundle exec rubocop -a  # Auto-fix lint issues
-bin/console             # IRB with gem loaded
+rake                                # Run specs + rubocop (default task)
+bundle exec rspec                   # Run all tests
+bundle exec rspec spec/mml/v3/msub_spec.rb:14  # Run single test by line
+bundle exec rspec --only-failures   # Previously failing tests only
+bundle exec rubocop                 # Lint
+bundle exec rubocop -a              # Auto-fix lint issues
+bin/console                         # IRB with gem loaded
 ```
 
 ## Versioned Architecture
 
-**MathML 3 vs MathML 4:** The gem maintains separate class hierarchies for MathML 3 (`Mml::V3::`) and MathML 4 (`Mml::V4::`). Users must reference the versioned namespace explicitly — no backward-compat aliases.
+The gem maintains **three** separate class hierarchies: `Mml::V2::` (MathML 2), `Mml::V3::` (MathML 3), and `Mml::V4::` (MathML 4). Users must reference the versioned namespace explicitly — no backward-compat aliases.
 
 ```ruby
-Mml.parse(input)                    # Default: MathML 3
-Mml.parse(input, version: 3)       # Explicit MathML 3
-Mml.parse(input, version: 4)        # MathML 4 with intent/arg attributes
+Mml.parse(input)                # Default: MathML 3
+Mml.parse(input, version: 2)   # MathML 2
+Mml.parse(input, version: 3)   # Explicit MathML 3
+Mml.parse(input, version: 4)   # MathML 4 with intent/arg attributes
 ```
 
 **Directory structure:**
-- `lib/mml/v3/` — MathML 3 element classes (original)
-- `lib/mml/v4/` — MathML 4 element classes (intent/arg added, deprecated attrs removed)
+- `lib/mml/base/` — version-agnostic element modules, mixed into each version's class via `include Base::XYZ`. The single source of truth for the XML mapping DSL.
+- `lib/mml/v2/`, `lib/mml/v3/`, `lib/mml/v4/` — per-version class declarations (each ~3 lines: declare class, mix in base module, register).
 
-**Key difference:** MathML 4 adds `intent`, `arg`, `displaystyle`, and `scriptlevel` attributes as universal presentation attributes for accessibility markup.
+**Key difference (V3 → V4):** MathML 4 adds `intent`, `arg`, `displaystyle`, and `scriptlevel` as universal presentation attributes for accessibility markup; removes some deprecated attributes.
 
 **No hidden delegation:** The `Mml` module does not alias or delegate constants. Use `Mml::V3::Math`, `Mml::V4::Mi`, etc. directly.
 
 ## Entry Points
 
-- `Mml.parse(input, version: N)` — parse XML, returns `Mml::V3::Math` or `Mml::V4::Math` object graph
+- `Mml.parse(input, version: N)` — parse XML, returns `Mml::V{2,3,4}::Math` object graph
 - `Mml::V3.parse(input)` / `Mml::V4.parse(input)` — version-specific parsing
 - `Mml::V4::Math.from_xml(input)` — directly parse with v4 classes
 - Call `to_xml` on any element to serialize back
 
-## Pattern
+## Element Mapping Pattern
 
-Each MathML element is a `Mml::V3::` or `Mml::V4::` class inheriting from `Lutaml::Model::Serializable` with an `xml do...end` DSL block. Two element types:
-- **Leaf elements** (e.g., `Mi`, `Mn`, `Mo`): use `map_content to: :value` for text content
-- **Container elements** (e.g., `Math`, `Mrow`, `Mfrac`): use `mixed_content` to accept arbitrary child elements
+Each MathML element is a `Lutaml::Model::Serializable` subclass with an `xml do...end` DSL block. The XML mapping lives in `lib/mml/base/<tag>.rb` as a module included into each version's class (e.g., `Mml::V3::Msub` includes `Mml::Base::Msub`).
 
-**CommonAttributes:** A `no_root` Lutaml model imported into container elements via `import_model`. It dynamically creates `#{tag}_value` attributes for each tag in `Configuration::SUPPORTED_TAGS`. Classes that receive it are listed in `Configuration::COMMON_ATTRIBUTES_CLASSES`.
+### Content model — `mixed_content` vs `ordered` vs `map_content`
 
-**Autoloading:** Each version (`lib/mml/v3.rb`, `lib/mml/v4.rb`) autoloads its element classes. `CommonAttributes` is required after all classes exist, then `update_attributes` mixes it into the configured classes.
+This is the most important decision when adding or editing an element. Pick based on the **schema** (see `schemas/mathml3/`, `schemas/mathml4/`, `reference-docs/mathml-source/`):
 
-**Namespace:** Both versions use the same URI (`http://www.w3.org/1998/Math/MathML`) — MathML 4 chose backward compatibility over a new namespace.
+| Schema content model                              | Use                                  | Examples                       |
+|---------------------------------------------------|--------------------------------------|--------------------------------|
+| True mixed `(#PCDATA \| mglyph \| malignmark)*`   | `mixed_content` + `map_content`      | `Mi`, `Mn`, `Mo`, `Ms`, `Mtext`|
+| Element-only (`ImpliedMrow`, `<xs:sequence>`, etc.) | `ordered`                          | `Msub`, `Mfrac`, `Mrow`, `Math`, `Munder`, `Mfenced`, `Msgroup`, … |
+
+**Why this matters:** lutaml-model's `each_mixed_content` iteration exposes all children to consumers (Plurimath's translator does positional indexing like `children[0]`, `children[1]` for `msub`/`mfrac`/etc.).
+- Under `mixed_content`, whitespace between elements is yielded as a String child, shifting positional indices.
+- Under `ordered`, whitespace-only text nodes are skipped — only elements and non-whitespace text are yielded.
+
+If you mistakenly use `mixed_content` on an element-only schema element, downstream consumers see phantom whitespace children and silently misinterpret the tree (e.g., render `<msub><mi>t</mi><mn>90</mn></msub>` with whitespace between children as base=whitespace, sub=`<mi>t</mi>`, dropping `<mn>90</mn>`).
+
+**Verification workflow for any element edit:**
+```bash
+grep -A15 'name="<tag>"' schemas/mathml3/mathml3-presentation.xsd schemas/mathml3/mathml3-common.xsd
+grep -A3 '<tag>\s*=\s*element' schemas/mathml4/mathml4-core.rnc schemas/mathml4/mathml4-presentation.rnc
+```
+
+If the schema says `ImpliedMrow`, `MathExpression, MathExpression`, `MstackExpression*`, `TableRowExpression*`, etc. (any element-only sequence), use `ordered`. If it says `(#PCDATA | mglyph | malignmark)*`, use `mixed_content` + `map_content` + `map_element` for the inline children.
+
+### Token elements are the only true mixed content
+
+Per MathML schema, token elements (`mi`, `mn`, `mo`, `ms`, `mtext`) accept `(#PCDATA | mglyph | malignmark)*` — text interleaved with inline elements. They use:
+
+```ruby
+attribute :value, :string, collection: true           # collection required for mixed_content
+attribute :mglyph_value, :mglyph, collection: true
+attribute :malignmark_value, :malignmark, collection: true
+
+xml do
+  element "<tag>"
+  mixed_content
+  map_content to: :value
+  map_element "mglyph", to: :mglyph_value
+  map_element "malignmark", to: :malignmark_value
+end
+```
+
+`value` is a `String` **collection** (Array) because text can be split by intervening inline elements (e.g., `<mi>x<malignmark/>y</mi>` → `["x", "y"]`).
+
+### CommonAttributes
+
+A `no_root` Lutaml model imported into container elements via `import_model`. It dynamically creates `#{tag}_value` attributes for each tag in `Configuration::SUPPORTED_TAGS`. Classes that receive it are listed in `Configuration::COMMON_ATTRIBUTES_CLASSES`.
+
+### Version module body registration
+
+Each `lib/mml/v{2,3,4}.rb` declares `autoload :Klass, "mml/v{2,3,4}/klass"` for every element class, then calls `Configuration.register_model(Klass, id: :tag)` in the module body. The register_model call triggers autoload on first reference, preserving eager-registration semantics while using Ruby autoload (no `require_relative` for internal code).
+
+Per-element files (e.g. `lib/mml/v3/math.rb`) define only the class — they no longer call `register_model` themselves. The version module is the single source of truth for registration.
+
+For grouped files (e.g. `lib/mml/v3/arith.rb` defines 22 classes), each class has its own `autoload` entry pointing at the shared file.
+
+`spec/mml/code_quality_spec.rb` enforces the lint rules and verifies every expected element ID is registered in its version's context.
+
+**Namespace:** All versions use the same URI (`http://www.w3.org/1998/Math/MathML`) — MathML 4 chose backward compatibility over a new namespace.
+
+## Adapter
+
+`Mml.default_adapter` returns `:oga` under Opal, otherwise delegates to `Lutaml::Model::Config.xml_adapter_type` (defaults to `:nokogiri`). Specs pin `:nokogiri` in `spec_helper.rb`. Users can override globally via `Lutaml::Model::Config`.
 
 ## Spec Structure
 
-- `spec/mml_spec.rb` — tests `Mml::V3` and `Mml::V4` with separate fixture directories
-- `spec/fixtures/with_namespace/` — v3 fixtures (MathML 3)
-- `spec/fixtures/with_namespace_prefix/` — v3 fixtures with namespace prefix
-- `spec/fixtures/v4/` — v4 fixtures (MathML 4 with intent attributes)
+- `spec/mml/v2/`, `spec/mml/v3/`, `spec/mml/v4/` — per-version element specs (round-trip + attribute preservation)
+- `spec/mml/v3_spec.rb`, `spec/mml/v4_spec.rb` — whole-testsuite round-trip tests against `spec/fixtures/mml3-testsuite/` and `spec/fixtures/mmlcore-testsuite/`
+- `spec/mml/ordered_content_spec.rb` — regression specs locking in the mixed_content vs ordered distinction (whitespace handling + token element inline children)
+- `spec/mml/adapter_configuration_spec.rb` — adapter delegation
+- `spec/context_support_spec.rb`, `spec/lutaml_default_register_spec.rb` — registry/context behavior
+- `spec/fixtures/mml2-testsuite/`, `mml3-testsuite/`, `mmlcore-testsuite/` — W3C test suites (submodules)
+- `spec/fixtures/v2/`, `v4/` — version-specific fixtures
 
-Specs use the `:nokogiri` Lutaml adapter (configured in `spec_helper.rb`). Runtime uses `:ox` adapter by default.
+Specs use `canon`'s `be_xml_equivalent_to` matcher with the `:spec_friendly` profile (whitespace-tolerant). When adding a regression spec for an ordering bug, **explicitly test the inter-element-whitespace scenario** — the suite's whitespace tolerance masks positional bugs.
 
 ## Key Dependencies
 
-- `lutaml-model` (~ 0.8.0) — data mapper framework; all element classes inherit from `Lutaml::Model::Serializable`
-- `moxml` — XML parsing library (uses `:ox` adapter by default)
+- `lutaml-model` (~> 0.8.0) — data mapper framework; all element classes inherit from `Lutaml::Model::Serializable`
+- `moxml` — XML parsing backbone (adapter selected via `Lutaml::Model::Config`)
 - `canon` — XML comparison for specs
 
 ## Conventions
@@ -77,3 +136,10 @@ Specs use the `:nokogiri` Lutaml adapter (configured in `spec_helper.rb`). Runti
 - CI workflows are auto-generated by Cimas — do not edit manually
 - `Gemfile.lock` is gitignored; dependencies come from the gemspec
 - Type signatures exist in `sig/mml.rbs`
+
+## Reference Materials
+
+- `schemas/mathml2/`, `schemas/mathml3/`, `schemas/mathml4/` — official W3C schemas (XSD for 2/3, RelaxNG for 4). **Authoritative** source for content models and attribute lists.
+- `reference-docs/mathml-source/` — W3C spec source XML (presentation-markup.xml, validation-grammar.xml, etc.)
+
+When deciding whether an element should have `mixed_content`, `ordered`, or `map_content`, **always** verify against the schema first.

data/TODO.complete/1-v3-autoload.md

@@ -0,0 +1,63 @@
+# TODO 1 — Migrate `lib/mml/v3.rb` from `require_relative` to `autoload`
+
+## Why
+Global rule: never use `require_relative` for code inside our own library.
+Use Ruby `autoload` declared in the immediate parent namespace's file
+(`lib/mml/v3.rb`). `lib/mml/v4.rb` already follows this pattern; V3 should
+match it for consistency (MECE/SSOT).
+
+## Scope
+- `lib/mml/v3.rb` — replace every `require_relative "v3/..."` with the
+  corresponding `autoload :Klass, "mml/v3/..."`.
+- Grouped files (e.g. `v3/arith.rb`) contain multiple classes — emit one
+  `autoload` line per class, all pointing at the same file path.
+- Keep the existing `Configuration.register_model(...)` calls in the module
+  body — they trigger autoload on first reference and preserve eager
+  registration behavior.
+- Foundational files (`configuration`, `namespace`, `common_elements`) also
+  switch to `autoload`.
+
+## Class → file map (V3)
+### One-class files (presentation)
+Maction, Maligngroup, Malignmark, Menclose, Merror, Mfenced, Mfrac,
+Mfraction, Mglyph, Mi, Mlabeledtr, Mlongdiv, Mmultiscripts, Mn, Mo, Mover,
+Mpadded, Mphantom, Mprescripts, Mroot, Mrow, Ms, Mscarries, Mscarry,
+Msgroup, Msline, Mspace, Msqrt, Msrow, Mstack, Mstyle, Msub, Msubsup, Msup,
+Mtable, Mtd, Mtext, Mtr, Munder, Munderover, None, Semantics, Math
+
+### One-class files (content)
+Apply, Cbytes, Cerror, Cs, Ci, Cn, Csymbol, AnnotationXml, Annotation,
+Bind, Bvar, Condition, Degree, Interval, Inverse, Lambda, Otherwise, Piece,
+Piecewise, Reln, Sep, Fn, Declare, Share
+
+### Grouped files (multiple classes per file)
+- `v3/arith.rb` → Abs, Conjugate, Arg, Real, Imaginary, Floor, Ceiling,
+  Quotient, Divide, Rem, Minus, Plus, Times, Power, Root, Max, Min, Gcd, Lcm,
+  Sum, Product, Factorial
+- `v3/calculus.rb` → Int, Diff, Partialdiff, Limit, Lowlimit, Uplimit, Tendsto
+- `v3/constants.rb` → Naturalnumbers, Primes, Integers, Rationals, Reals,
+  Complexes, Emptyset, Exponentiale, Imaginaryi, Pi, Eulergamma, Mtrue,
+  Mfalse, Infinity, Notanumber
+- `v3/elementary_functions.rb` → Exp, Ln, Log, Logbase, Sin, Cos, Tan, Sec,
+  Csc, Cot, Arcsin, Arccos, Arctan, Arccot, Arccsc, Arcsec, Sinh, Cosh, Tanh,
+  Sech, Csch, Coth, Arcsinh, Arccosh, Arctanh, Arccoth, Arccsch, Arcsech
+- `v3/functions.rb` → Compose, Domain, Codomain, Image, Ident,
+  Domainofapplication
+- `v3/linear_algebra.rb` → Vector, Matrix, Matrixrow, Determinant, Transpose,
+  Selector, Vectorproduct, Scalarproduct, Outerproduct
+- `v3/logic.rb` → And, Or, Xor, Not, Exists, Forall, Implies
+- `v3/relations.rb` → Eq, Neq, Leq, Lt, Geq, Gt, Equivalent, Approx, Factorof
+- `v3/sets.rb` → Set, Mlist, Union, Intersect, In, Notin, Subset, Prsubset,
+  Notsubset, Notprsubset, Setdiff, Card, Cartesianproduct
+- `v3/statistics.rb` → Mean, Sdev, Variance, Median, Mode, Moment, Momentabout
+- `v3/vector_calculus.rb` → Divergence, Grad, Curl, Laplacian
+- `v3/constructs.rb` → Bvar, Condition, Interval, Lambda, Inverse, Degree,
+  Piecewise, Piece, Otherwise, Sep
+- `v3/deprecated_content.rb` → Fn, Reln, Declare, Share
+
+## Acceptance
+- `grep -rn "require_relative" lib/mml/v3.rb` returns nothing.
+- `bundle exec rspec` passes (2940+ examples, 36 pre-existing pending).
+- `bundle exec rubocop lib/mml/v3.rb` clean.
+- All `Mml::V3::*` constants remain accessible and registered after
+  `require "mml"`.

data/TODO.complete/2-v2-autoload.md

@@ -0,0 +1,46 @@
+# TODO 2 — Migrate `lib/mml/v2.rb` from `require_relative` to `autoload`
+
+## Why
+Same as TODO 1 but for V2. Mirror the V4 pattern.
+
+## Scope
+- Replace every `require_relative "v2/..."` with `autoload :Klass, "mml/v2/..."`.
+- Grouped files have multiple classes per file.
+
+## Class → file map (V2)
+### One-class files (presentation + content)
+Same shape as V3 but in `v2/` directory: Maction, Maligngroup, Malignmark,
+Menclose, Merror, Mfenced, Mfrac, Mfraction, Mglyph, Mi, Mlabeledtr, Mlongdiv,
+Mmultiscripts, Mn, Mo, Mover, Mpadded, Mphantom, Mprescripts, Mroot, Mrow,
+Ms, Mscarries, Mscarry, Msgroup, Msline, Mspace, Msqrt, Msrow, Mstack,
+Mstyle, Msub, Msubsup, Msup, Mtable, Mtd, Mtext, Mtr, Munder, Munderover,
+None, Semantics, Math, Annotation, AnnotationXml, Apply, Bvar, Bind, Ci,
+Cn, Condition, Csymbol, Degree, Fn, Interval, Inverse, Lambda, Otherwise,
+Piece, Piecewise, Reln, Sep
+
+### Grouped files
+- `v2/arith.rb` → Abs, Conjugate, Arg, Real, Imaginary, Floor, Ceiling,
+  Quotient, Divide, Rem, Minus, Plus, Times, Power, Root, Max, Min, Gcd, Lcm,
+  Sum, Product, Factorial
+- `v2/calculus.rb` → Int, Diff, Partialdiff, Limit, Lowlimit, Uplimit, Tendsto
+- `v2/constants.rb` → Naturalnumbers, Primes, Integers, Rationals, Reals,
+  Complexes, Emptyset, Exponentiale, Imaginaryi, Pi, Eulergamma, Mtrue,
+  Mfalse, Infinity, Notanumber
+- `v2/elementary_functions.rb` → Exp, Ln, Log, Logbase, Sin, Cos, Tan, Sec,
+  Csc, Cot, Arcsin, Arccos, Arctan, Arccot, Arccsc, Arcsec, Sinh, Cosh, Tanh,
+  Sech, Csch, Coth, Arcsinh, Arccosh, Arctanh, Arccoth, Arccsch, Arcsech
+- `v2/functions.rb` → Compose, Domain, Codomain, Image, Ident,
+  Domainofapplication
+- `v2/linear_algebra.rb` → Vector, Matrix, Matrixrow, Determinant, Transpose,
+  Selector, Vectorproduct, Scalarproduct, Outerproduct
+- `v2/logic.rb` → And, Or, Xor, Not, Exists, Forall, Implies
+- `v2/relations.rb` → Eq, Neq, Leq, Lt, Geq, Gt, Equivalent, Approx, Factorof
+- `v2/sets.rb` → Set, Mlist, Union, Intersect, In, Notin, Subset, Prsubset,
+  Notsubset, Notprsubset, Setdiff, Card, Cartesianproduct
+- `v2/statistics.rb` → Mean, Sdev, Variance, Median, Mode, Moment, Momentabout
+- `v2/vector_calculus.rb` → Divergence, Grad, Curl, Laplacian
+
+## Acceptance
+- `grep -rn "require_relative" lib/mml/v2.rb` returns nothing.
+- `bundle exec rspec` passes.
+- `bundle exec rubocop lib/mml/v2.rb` clean.

data/TODO.complete/3-no-require-relative.md

@@ -0,0 +1,32 @@
+# TODO 3 — Eliminate remaining `require_relative` in `lib/mml/`
+
+## Why
+After TODO 1 & 2, the only remaining `require_relative` calls in `lib/mml/`
+are:
+- `lib/mml/v2.rb:4`  — `require_relative "versioned_parser"`
+- `lib/mml/v3.rb:4`  — `require_relative "versioned_parser"`
+- `lib/mml/v4.rb:4`  — `require_relative "versioned_parser"`
+- `lib/mml/v{2,3,4}/configuration.rb:3` — `require_relative "../context_configuration"`
+- `lib/mml/v{2,3,4}.rb` top — `require_relative "v{2,3,4}/configuration"`,
+  `"v{2,3,4}/namespace"`, `"v{2,3,4}/common_elements"` (V4 only today, but if
+  V2/V3 also adopt the same pattern during TODO 1/2 they need the same fix).
+
+All of these can be replaced with autoloads declared in `lib/mml.rb` and in
+the version module files.
+
+## Scope
+1. `lib/mml.rb` — add `autoload :VersionedParser, "mml/versioned_parser"`
+   (currently `ContextOptions` and others are autoloaded; `VersionedParser`
+   is missing).
+2. `lib/mml/v{2,3,4}/configuration.rb` — remove the
+   `require_relative "../context_configuration"` line. `Mml::ContextConfiguration`
+   is autoloaded from `lib/mml.rb`, so the `extend Mml::ContextConfiguration`
+   call resolves correctly.
+3. `lib/mml/v{2,3,4}.rb` — replace `require_relative "v{2,3,4}/configuration"`
+   and the foundational requires with `autoload` declarations.
+
+## Acceptance
+- `grep -rn "require_relative" lib/mml/` returns zero matches.
+- `bundle exec rspec` passes.
+- `bundle exec rubocop lib/` clean.
+- Smoke spec (TODO 7) confirms every `Mml::V{2,3,4}::*` class resolves.

data/TODO.complete/4-remove-duplicate-register-model.md

@@ -0,0 +1,31 @@
+# TODO 4 — Remove duplicate per-element `Configuration.register_model` (DRY/SSOT)
+
+## Why
+After TODO 1 & 2, V2 and V3 will mirror V4's pattern of `autoload + module-body
+register_model`. The per-element files (`lib/mml/v{2,3}/<tag>.rb`) currently
+also end with `Configuration.register_model(Klass, id: :tag)`. That is
+duplicate work — `register_model` overwrites the same key with the same class.
+
+V4 is inconsistent: most files omit the per-element call, but `annotation.rb`,
+`elementary_functions.rb`, and `functions.rb` still have it.
+
+Single source of truth: the version module body (`lib/mml/v{2,3,4}.rb`).
+
+## Scope
+- Remove the trailing `Configuration.register_model(...)` line from every
+  per-element file under `lib/mml/v2/`, `lib/mml/v3/`, `lib/mml/v4/`.
+- Do NOT touch `lib/mml/v{2,3,4}.rb` (module-body registrations stay).
+
+## Files affected
+- V3: 66 per-element files (every file under `lib/mml/v3/` except
+  `configuration.rb`, `namespace.rb`, `common_elements.rb`, `version.rb`).
+- V2: ~62 per-element files.
+- V4: 3 files — `annotation.rb`, `elementary_functions.rb`, `functions.rb`.
+
+## Acceptance
+- `grep -rn "Configuration.register_model" lib/mml/v2 lib/mml/v3 lib/mml/v4 |
+  grep -v "v[234]\.rb:"` returns nothing (only version module files have it).
+- `bundle exec rspec` passes.
+- `bundle exec rubocop lib/` clean.
+- Registration spec (TODO 7) confirms all element IDs are still registered
+  in their respective contexts.

data/TODO.complete/5-context-options-type-check.md

@@ -0,0 +1,44 @@
+# TODO 5 — Replace `respond_to?(:id)` with explicit type check in `context_options.rb`
+
+## Why
+Global rule: never use `respond_to?` for type checking. Use `is_a?` or
+design the type hierarchy so the check isn't needed.
+
+`lib/mml/context_options.rb:34` uses `reference.respond_to?(:id)` to duck-type
+any object that exposes an `id`. The actual types that can reach this code are:
+- `Symbol` — handled earlier
+- `String` — handled earlier
+- `Lutaml::Model::TypeContext` (lutaml-model) — has `attr_reader :id`
+- `Lutaml::Model::Register` (lutaml-model) — has `attr_reader :id`
+
+## Scope
+- Replace the `respond_to?` branch with explicit `is_a?` checks against the
+  two known lutaml-model classes.
+- Keep the `ArgumentError` fallback for unknown types — preserves
+  fail-fast behavior.
+
+## Implementation
+```ruby
+def normalize_context_reference(reference)
+  return nil if reference.nil?
+  return reference if reference.is_a?(Symbol)
+  return reference.to_sym if reference.is_a?(String)
+  return reference.id.to_sym if context_reference_object?(reference)
+
+  raise ArgumentError,
+        "Unsupported context/register reference: #{reference.inspect}"
+end
+
+private
+
+def context_reference_object?(reference)
+  reference.is_a?(Lutaml::Model::TypeContext) ||
+    reference.is_a?(Lutaml::Model::Register)
+end
+```
+
+## Acceptance
+- `grep -n "respond_to?" lib/mml/context_options.rb` returns nothing.
+- `bundle exec rspec spec/mml/context_options_spec.rb` passes (new spec from
+  TODO 7).
+- Existing parse/configuration specs still pass.

data/TODO.complete/6-context-configuration-type-check.md

@@ -0,0 +1,32 @@
+# TODO 6 — Replace `respond_to?(:clear_cache)` with explicit type check in `context_configuration.rb`
+
+## Why
+Global rule: never use `respond_to?` for type checking.
+
+`lib/mml/context_configuration.rb:144` uses
+`klass.clear_cache(context_id) if klass.respond_to?(:clear_cache)`.
+
+Every class registered via `Configuration.register_model` inherits from
+`Lutaml::Model::Serializable`, which defines `clear_cache` as a class method
+(see lutaml-model `lib/lutaml/model/serialize/initialization.rb:180`).
+
+## Scope
+- Replace the `respond_to?` guard with an explicit type check:
+  `klass.is_a?(Class) && klass <= Lutaml::Model::Serialize`.
+- Note the use of `<=` (subclass-or-equal) rather than `<` so that
+  `Serializable` itself would also qualify, matching the intent of "any class
+  in the Serializable hierarchy".
+
+## Implementation
+```ruby
+def clear_cache(klass)
+  return unless klass.is_a?(Class) && (klass <= Lutaml::Model::Serialize)
+
+  klass.clear_cache(context_id)
+end
+```
+
+## Acceptance
+- `grep -n "respond_to?" lib/mml/context_configuration.rb` returns nothing.
+- `bundle exec rspec` passes.
+- `bundle exec rubocop lib/mml/context_configuration.rb` clean.

data/TODO.complete/7-specs-for-refactor.md

@@ -0,0 +1,38 @@
+# TODO 7 — Add specs covering the refactorings
+
+## Why
+Lock in the behavior of the refactorings in TODOs 1–6 so future regressions
+are caught. MECE with existing specs:
+- `spec/mml/adapter_configuration_spec.rb` — adapter selection
+- `spec/mml/ordered_content_spec.rb` — mixed_content vs ordered
+- `spec/mml/nested_in_mixed_content_spec.rb` — entity preservation in host
+- `spec/lutaml_default_register_spec.rb` — every Serializable class has
+  `lutaml_default_register`
+- `spec/context_support_spec.rb` — context creation/substitution
+
+None of these cover:
+- `ContextOptions.normalize_context_reference` for `TypeContext`/`Register`
+  inputs.
+- Lint: no `require_relative` in `lib/mml/**/*.rb`.
+- Lint: no `respond_to?` in `lib/mml/**/*.rb`.
+- Lint: no `.send(` / `instance_variable_set` / `instance_variable_get` in
+  `lib/mml/**/*.rb`.
+- Smoke: every `Mml::V{2,3,4}` autoload constant resolves and is registered
+  after `require "mml"`.
+
+## Scope
+Create `spec/mml/code_quality_spec.rb` covering all four lint checks plus a
+smoke test that iterates the Configuration register and asserts every
+expected element ID is present for V2, V3, V4.
+
+Update `spec/context_support_spec.rb` (or add a new spec) to cover
+`ContextOptions.normalize_context_reference` with `TypeContext` and `Register`
+inputs — these now flow through the new `is_a?` branches.
+
+## Acceptance
+- New spec file(s) added.
+- `bundle exec rspec` passes.
+- `bundle exec rubocop` clean.
+- Removing any autoload declaration or per-element class breaks the smoke
+  spec.
+- Adding a new `require_relative` to `lib/mml/` breaks the lint spec.

data/lib/mml/base/maction.rb

@@ -15,7 +15,7 @@ module Mml
           xml do
             namespace Mml::Namespace
             element "maction"
-            mixed_content
+            ordered
 
             map_attribute "mathcolor", to: :mathcolor
             map_attribute "mathbackground", to: :mathbackground

data/lib/mml/base/math.rb

@@ -37,7 +37,7 @@ module Mml
           xml do
             namespace Mml::Namespace
             element "math"
-            mixed_content
+            ordered
 
             map_attribute :display, to: :display
             map_attribute "mode", to: :mode

data/lib/mml/base/menclose.rb

@@ -14,7 +14,7 @@ module Mml
           xml do
             namespace Mml::Namespace
             element "menclose"
-            mixed_content
+            ordered
 
             map_attribute "mathcolor", to: :mathcolor
             map_attribute "mathbackground", to: :mathbackground

data/lib/mml/base/merror.rb

@@ -13,7 +13,7 @@ module Mml
           xml do
             namespace Mml::Namespace
             element "merror"
-            mixed_content
+            ordered
 
             map_attribute "mathcolor", to: :mathcolor
             map_attribute "mathbackground", to: :mathbackground

data/lib/mml/base/mfenced.rb

@@ -10,16 +10,13 @@ module Mml
           attribute :mathbackground, :string
           attribute :separators, :string
           attribute :mathcolor, :string
-          attribute :content, :string, collection: true
           attribute :close, :string
           attribute :open, :string
 
           xml do
             namespace Mml::Namespace
             element "mfenced"
-            mixed_content
-
-            map_content to: :content
+            ordered
 
             map_attribute "mathbackground", to: :mathbackground
             map_attribute "separators", to: :separators, render_empty: true

data/lib/mml/base/mfrac.rb

@@ -17,7 +17,7 @@ module Mml
           xml do
             namespace Mml::Namespace
             element "mfrac"
-            mixed_content
+            ordered
 
             map_attribute "mathcolor", to: :mathcolor
             map_attribute "mathbackground", to: :mathbackground

data/lib/mml/base/mfraction.rb

@@ -17,7 +17,7 @@ module Mml
           xml do
             namespace Mml::Namespace
             element "mfraction"
-            mixed_content
+            ordered
 
             map_attribute "mathcolor", to: :mathcolor
             map_attribute "mathbackground", to: :mathbackground

data/lib/mml/base/mi.rb

@@ -13,6 +13,7 @@ module Mml
           attribute :mathsize, :string
           attribute :mathvariant, :string
           attribute :mglyph_value, :mglyph, collection: true
+          attribute :malignmark_value, :malignmark, collection: true
           attribute :lang, :string
 
           xml do
@@ -27,6 +28,7 @@ module Mml
             map_attribute "mathvariant", to: :mathvariant
             map_attribute "xml:lang", to: :lang
             map_element "mglyph", to: :mglyph_value
+            map_element "malignmark", to: :malignmark_value
           end
         end
       end

data/lib/mml/base/mlabeledtr.rb

@@ -18,7 +18,7 @@ module Mml
           xml do
             namespace Mml::Namespace
             element "mlabeledtr"
-            mixed_content
+            ordered
 
             map_attribute "mathbackground", to: :mathbackground
             map_attribute "columnalign", to: :columnalign

data/lib/mml/base/mlongdiv.rb

@@ -16,7 +16,7 @@ module Mml
           xml do
             namespace Mml::Namespace
             element "mlongdiv"
-            mixed_content
+            ordered
 
             map_attribute "mathbackground", to: :mathbackground
             map_attribute "longdivstyle", to: :longdivstyle

data/lib/mml/base/mmultiscripts.rb

@@ -16,7 +16,7 @@ module Mml
           xml do
             namespace Mml::Namespace
             element "mmultiscripts"
-            mixed_content
+            ordered
 
             map_attribute "mathcolor", to: :mathcolor
             map_attribute "mathbackground", to: :mathbackground

data/lib/mml/base/mn.rb

@@ -13,6 +13,7 @@ module Mml
           attribute :mathvariant, :string
           attribute :mathsize, :string
           attribute :mglyph_value, :mglyph, collection: true
+          attribute :malignmark_value, :malignmark, collection: true
 
           xml do
             namespace Mml::Namespace
@@ -25,6 +26,7 @@ module Mml
             map_attribute "mathvariant", to: :mathvariant
             map_attribute "mathsize", to: :mathsize
             map_element "mglyph", to: :mglyph_value
+            map_element "malignmark", to: :malignmark_value
           end
         end
       end