chemicalml 0.1.0

data/TODO.align/02-real-schema-hierarchies.md

@@ -0,0 +1,88 @@
+# 02 — Real Schema3 / Schema24 class hierarchies
+
+**Status:** complete
+**Depends on:** 01
+
+## Goal
+
+Today `Chemicalml::Cml::Schema3::Document` is just an alias for
+`Chemicalml::Cml::Document` — they are literally the same class. This
+means schema-version-specific behavior is impossible to add without
+modifying the shared class (OCP violation).
+
+Promote both namespaces to genuine class hierarchies. Each
+schema-versioned class is a `Lutaml::Model::Serializable` subclass that
+includes the corresponding `Cml::Base::*` mixin (from task 01) and may
+add version-specific declarations.
+
+## Why
+
+The CML Schema 2.4 and Schema 3 XSDs differ in content models —
+Schema 3 loosened many of Schema 2.4's restrictions and added the
+generic `<module>` element. Today's aliasing hides this. Real class
+hierarchies let each version evolve independently.
+
+## Deliverables
+
+- [ ] `lib/chemicalml/cml/schema3/` directory with one file per
+      element, each `class Foo < Lutaml::Model::Serializable;
+      include Base::Foo; end`
+- [ ] `lib/chemicalml/cml/schema24/` directory mirroring the same set
+- [ ] `lib/chemicalml/cml/schema3.rb` — namespace file with autoloads
+      (replaces the current alias module)
+- [ ] `lib/chemicalml/cml/schema24.rb` — same
+- [ ] Backward compatibility: `Chemicalml::Cml::Atom`,
+      `Cml::Molecule`, etc. at the top level become aliases for
+      `Cml::Schema3::*` (so existing user code and specs still load).
+      Document this in `CLAUDE.md` and `README.adoc`.
+
+## Schema-specific deviations to honor
+
+- Schema 2.4 has stricter content models; some elements (e.g.
+  `<module>`) do not exist. `Schema24::Module` therefore does not
+  exist.
+- Schema 3 added `<module>` and loosened `<cml>` content; that
+  behavior is the default in Schema3 wire classes.
+- Future Schema 2.4-specific deviations are added in
+  `Base::Schema24Only::*` modules included only by Schema24 classes
+  (OCP-friendly extension point).
+
+## Pattern
+
+```ruby
+# lib/chemicalml/cml/schema3/molecule.rb
+module Chemicalml
+  module Cml
+    module Schema3
+      class Molecule < Lutaml::Model::Serializable
+        include Base::Molecule
+      end
+    end
+  end
+end
+```
+
+```ruby
+# lib/chemicalml/cml/schema24/molecule.rb  (deviates: no <module> child)
+module Chemicalml
+  module Cml
+    module Schema24
+      class Molecule < Lutaml::Model::Serializable
+        include Base::Molecule
+        # Schema 2.4 doesn't allow child <module> elements;
+        # the Base::Molecule mixin doesn't declare one, so this class
+        # is already correct. If we needed to *remove* an attribute
+        # the Base declares, we'd use `undef_attribute` here.
+      end
+    end
+  end
+end
+```
+
+## Acceptance
+
+- `Chemicalml::Cml::Schema3::Atom` and `Chemicalml::Cml::Schema24::Atom`
+  are different classes (different `object_id`).
+- `Chemicalml::Cml::Atom` is an alias for `Chemicalml::Cml::Schema3::Atom`.
+- All existing specs continue to pass.
+- Round-trip through either schema works on the existing fixtures.

data/TODO.align/03-configuration.md

@@ -0,0 +1,50 @@
+# 03 — Configuration + lutaml_default_register
+
+**Status:** complete
+**Depends on:** 02
+
+## Goal
+
+Wire `lutaml-model`'s `GlobalContext` type-resolution machinery into
+the schema-versioned classes. Each schema gets its own context id
+(`:chemicalml_schema3`, `:chemicalml_schema24`); each wire class
+declares which context it belongs to via `lutaml_default_register`.
+
+This is the same pattern `mml` uses to let `from_xml` resolve child
+element types based on the active context.
+
+## Why
+
+Without context-aware type resolution, parsing `<atom>` inside a Schema3
+document and inside a Schema24 document both yield the same Ruby class.
+Once task 02 introduces real hierarchies, the framework needs to know
+which `Atom` class to instantiate based on which schema's `Document`
+is being parsed.
+
+## Deliverables
+
+- [ ] `lib/chemicalml/cml/schema3/configuration.rb` —
+      `module Schema3::Configuration; extend Chemicalml::ContextConfiguration;
+      CONTEXT_ID = :chemicalml_schema3; end`
+- [ ] `lib/chemicalml/cml/schema24/configuration.rb` — same shape
+      with `CONTEXT_ID = :chemicalml_schema24`
+- [ ] `lib/chemicalml/context_configuration.rb` — shared mixin
+      providing `register_model`, `populate_context!`, `context`,
+      `default_context_id` (modeled on `mml`'s
+      `lib/mml/context_configuration.rb`)
+- [ ] Each `Schema3::*` and `Schema24::*` class defines
+      `def self.lutaml_default_register; :chemicalml_schema3; end`
+      (or `:chemicalml_schema24`)
+- [ ] `lib/chemicalml/versioned_parser.rb` — `extend`-able mixin with
+      `parse(xml, namespace_exist:, context:)` that calls
+      `ensure_registered!` then `GlobalContext.resolve_type(:cml, ctx)`
+      then `root_class.from_xml(xml, register: ctx)`
+- [ ] Schema3 and Schema24 modules `extend VersionedParser`
+
+## Acceptance
+
+- `Chemicalml::Cml::Schema3.parse(xml)` returns a Schema3 document.
+- `Chemicalml::Cml::Schema24.parse(xml)` returns a Schema24 document.
+- `Chemicalml.parse(xml, schema: :schema24)` dispatches correctly.
+- `Lutaml::Model::GlobalContext.context(:chemicalml_schema3)` is
+  populated after first parse.

data/TODO.align/04-parse-entry-points.md

@@ -0,0 +1,59 @@
+# 04 — Top-level parse / serialize entry points
+
+**Status:** complete
+**Depends on:** 02, 03
+
+## Goal
+
+Provide a single, obvious entry point for users: `Chemicalml.parse(xml,
+schema: :schema3)` returns the right wire document. Symmetrically,
+`Chemicalml.serialize(doc)` produces XML. This mirrors `Mml.parse(input,
+version:)`.
+
+## Why
+
+Today users must know which class to call `.from_xml` on:
+`Chemicalml::Cml::Schema3::Document.from_xml(xml)`. After task 02 this
+gets worse — there are now two real hierarchies. A single dispatch
+function is the obvious UX.
+
+## Deliverables
+
+- [ ] `Chemicalml.parse(xml, schema: :schema3, namespace_exist: true)`
+      → dispatches via `Schema::Registry` to the right VersionedParser.
+- [ ] `Chemicalml.serialize(document)` → just calls `document.to_xml`.
+      Exists for API symmetry.
+- [ ] `Chemicalml.parser_for(schema)` → returns the Schema3 or Schema24
+      module (raises `ArgumentError` on unknown).
+- [ ] Document in `README.adoc` and `CLAUDE.md`.
+
+## Pattern
+
+```ruby
+# lib/chemicalml.rb (additions)
+def parse(xml, schema: :schema3, **opts)
+  parser_for(schema).parse(xml, **opts)
+end
+
+def serialize(document, **opts)
+  document.to_xml(**opts)
+end
+
+def parser_for(schema)
+  case schema
+  when :schema3  then Chemicalml::Cml::Schema3
+  when :schema24 then Chemicalml::Cml::Schema24
+  else
+    raise ArgumentError, "unsupported schema: #{schema.inspect} " \
+                         "(supported: :schema3, :schema24)"
+  end
+end
+module_function :parse, :serialize, :parser_for
+```
+
+## Acceptance
+
+- `Chemicalml.parse("<cml>...</cml>")` works (defaults to Schema3).
+- `Chemicalml.parse("<cml>...</cml>", schema: :schema24)` returns a
+  `Schema24::Document`.
+- Unknown schema raises `ArgumentError`.

data/TODO.align/05-schema-aware-translator.md

@@ -0,0 +1,33 @@
+# 05 — Schema-aware Translator
+
+**Status:** complete
+**Depends on:** 02
+
+## Goal
+
+Update `Chemicalml::Cml::Translator` so it can serialize the canonical
+model into either Schema3 or Schema24 wire format, and so it can parse
+either schema's wire format back into the canonical model.
+
+## Why
+
+Today the translator only knows about `Cml::Document` (now an alias for
+Schema3). Once Schema3 and Schema24 are real class hierarchies, the
+translator needs to know which one to instantiate when going from
+canonical → wire.
+
+## Deliverables
+
+- [ ] `Translator.from_canonical(model_doc, schema: :schema3)` →
+      returns a `Schema3::Document` or `Schema24::Document`
+- [ ] `Translator.to_canonical(wire_doc)` → unchanged: detects the
+      wire class via `is_a?` and dispatches correctly
+- [ ] Existing two-method public API (`to_canonical`,
+      `from_canonical`) preserved; new behavior is opt-in via the
+      `schema:` keyword (defaults to `:schema3`)
+
+## Acceptance
+
+- Round-trip canonical → Schema3 wire → canonical yields an equal doc.
+- Round-trip canonical → Schema24 wire → canonical yields an equal doc.
+- Specs cover both schemas.

data/TODO.align/06-no-respond-to.md

@@ -0,0 +1,44 @@
+# 06 — Replace respond_to? with is_a?
+
+**Status:** complete
+**Depends on:** 02
+
+## Goal
+
+The user's global rule forbids `respond_to?` for type checking. Today
+the convention constraint walker uses `respond_to?` heavily to ask
+heterogeneous wire nodes whether they expose a particular attribute.
+Replace every occurrence with `is_a?` checks against the concrete wire
+classes (or a marker module that those classes include).
+
+## Why
+
+`respond_to?` is duck-typing that hides type errors until runtime. The
+right pattern is either:
+
+- Use `is_a?(SpecificClass)` when the constraint genuinely only applies
+  to one class.
+- Introduce a marker module (e.g. `Cml::HasAtomArray`) that the
+  relevant classes include, then check `node.is_a?(HasAtomArray)`. This
+  is OCP-friendly — new classes opt in by including the marker, not by
+  editing a switch.
+
+## Deliverables
+
+- [ ] Introduce `Chemicalml::Cml::Visitable` mixin included by every
+      wire class. Provides a uniform `accept_constraint(visitor)`
+      interface that delegates to `visitor.visit_<class_short_name>`.
+- [ ] Add marker modules where duck-typing is currently used:
+      `Cml::HasAtomArray`, `Cml::HasBondArray`, `Cml::HasEntries`,
+      `Cml::HasUnits`, etc. — included by the relevant wire classes.
+- [ ] Rewrite `Convention::Constraint#wire_children` to walk via
+      `is_a?` checks against marker modules, not `respond_to?`.
+- [ ] Audit `grep -rn 'respond_to?' lib/` — should return zero hits
+      outside spec_helper boilerplate.
+
+## Acceptance
+
+- `grep -rn 'respond_to?' lib/` returns nothing.
+- All convention specs still pass.
+- Constraint walker behavior unchanged (still detects the same
+  violations on the same fixtures).

data/TODO.align/07-canon-xml-comparison.md

@@ -0,0 +1,43 @@
+# 07 — Canon-based semantic XML comparison
+
+**Status:** complete
+**Depends on:** —
+
+## Goal
+
+Replace brittle string-equality assertions in round-trip specs with
+semantic XML comparison via the
+[`canon`](https://github.com/plurimath/canon) gem. This is what `mml`
+uses for its `be_xml_equivalent_to` matcher.
+
+## Why
+
+Plain string equality breaks on:
+
+- attribute order (`<a x="1" y="2"/>` vs `<a y="2" x="1"/>`)
+- whitespace differences inside tags
+- namespace prefix aliases
+- self-closing vs empty-tag forms
+
+Semantic comparison treats all of these as equivalent, which is what
+round-trip tests actually want to verify.
+
+## Deliverables
+
+- [ ] Add `gem "canon"` to the development group in `Gemfile`
+- [ ] Configure `Canon::Config` in `spec/spec_helper.rb`:
+      ```ruby
+      Canon::Config.configure do |config|
+        config.xml.match.profile = :spec_friendly
+        config.xml.diff.algorithm = :semantic
+      end
+      ```
+- [ ] Existing round-trip specs use `expect(out).to be_xml_equivalent_to(in)`
+      instead of `expect(out).to eq(in)` or attribute-by-attribute
+      equality.
+
+## Acceptance
+
+- `bundle exec rspec` is green with the new matcher.
+- Round-trip specs catch real regressions (e.g. dropped attributes)
+  rather than formatting noise.

data/TODO.align/08-expand-fixtures.md

@@ -0,0 +1,37 @@
+# 08 — Expand fixtures corpus
+
+**Status:** complete
+**Depends on:** 02
+
+## Goal
+
+Grow the fixture corpus so it covers the breadth of CML: stereo,
+parity, properties, parameters, modules, dictionaries, units,
+crystals, lattices. Each fixture exercises one feature so a regression
+is easy to localize.
+
+## Deliverables
+
+Add the following seed fixtures under `spec/fixtures/`:
+
+- [ ] `schema3/molecular/ethene_with_bond_stereo.cml` — cis/trans
+- [ ] `schema3/molecular/chiral_center.cml` — atomParity
+- [ ] `schema3/molecular/with_property.cml` — property + scalar
+- [ ] `schema3/molecular/nested_molecules.cml` — parent/child
+- [ ] `schema3/molecular/with_formula_inline.cml` — LaTeX-style inline
+- [ ] `schema3/compchem/full_nwchem.cml` — full jobList with
+      initialization / calculation / finalization
+- [ ] `schema3/compchem/with_basis_set.cml` — basisSet list
+- [ ] `schema3/dictionary/example.cml` — dictionary with entries
+- [ ] `schema3/unit/si_units.cml` — unitList with SI units
+- [ ] `schema24/crystal.cml` — crystal + lattice
+- [ ] `schema24/spectrum.cml` — peakList
+- [ ] `spec/fixtures/README.md` — documents provenance (synthetic vs
+      scraped) and licensing
+
+## Acceptance
+
+- All new fixtures round-trip through both Schema3 and Schema24 wire
+  classes.
+- `bundle exec rspec spec/chemicalml/fixtures_round_trip_spec.rb` is
+  green.

data/TODO.align/09-final-spec-lint.md

@@ -0,0 +1,29 @@
+# 09 — Final spec + lint pass
+
+**Status:** complete
+**Depends on:** all
+
+## Goal
+
+Run the full suite, fix any regressions, run rubocop, document any
+remaining gaps in this file.
+
+## Deliverables
+
+- [ ] `bundle exec rspec` green
+- [ ] `bundle exec rubocop` clean (or only pre-existing offenses,
+      documented)
+- [ ] `grep -rn 'require_relative' lib/` returns nothing (except the
+      gemspec line which is legitimate)
+- [ ] `grep -rn 'respond_to?' lib/` returns nothing
+- [ ] `grep -rn 'instance_variable_set\|instance_variable_get' lib/`
+      returns nothing
+- [ ] `grep -rn '\.send(' lib/` reviewed — no private-method bypasses
+- [ ] This file updated with final status
+
+## Acceptance
+
+- All four grep checks return clean.
+- Full spec suite green.
+- The TODO.align index (`README.md`) shows every workstream as
+  `complete`.

data/TODO.align/10-role-marker-modules.md

@@ -0,0 +1,54 @@
+# 10 — Role marker modules
+
+**Status:** complete
+**Depends on:** —
+
+## Goal
+
+Every constraint currently does:
+
+```ruby
+def molecule?(node)
+  node.is_a?(Chemicalml::Cml::Schema3::Molecule) ||
+    node.is_a?(Chemicalml::Cml::Schema24::Molecule)
+end
+```
+
+This is an OCP violation: adding `Schema5` later means editing every
+constraint. Replace with a single marker module per role:
+
+```ruby
+def molecule?(node)
+  node.is_a?(Chemicalml::Cml::Role::Molecule)
+end
+```
+
+Both `Schema3::Molecule` and `Schema24::Molecule` (and any future
+version) include `Cml::Role::Molecule`. Constraints never change when
+new schema versions are added.
+
+## Why
+
+Type checks against concrete classes couple constraints to the set of
+supported schema versions. Marker modules decouple them: the constraint
+asks "is this a molecule?" not "is this one of the known molecule
+classes?".
+
+## Deliverables
+
+- [ ] `lib/chemicalml/cml/role.rb` — namespace file with autoloads
+- [ ] One module per CML element role under `lib/chemicalml/cml/role/`:
+      `molecule.rb`, `atom.rb`, `atom_array.rb`, `bond.rb`,
+      `bond_array.rb`, `module.rb`, `dictionary.rb`,
+      `dictionary_entry.rb`, `unit.rb`, `unit_type.rb`, etc.
+- [ ] Each `Base::*` module's `included` hook adds `include
+      Chemicalml::Cml::Role::Foo` to the including class.
+- [ ] Every constraint file uses `is_a?(Cml::Role::Foo)` instead of
+      `is_a?(Schema3::Foo) || is_a?(Schema24::Foo)`.
+
+## Acceptance
+
+- `grep -rn 'Schema3.*||.*Schema24' lib/` returns nothing.
+- `grep -rn 'is_a?(Chemicalml::Cml::Schema' lib/chemicalml/convention/`
+      returns nothing.
+- All convention specs pass.

data/TODO.align/11-dry-configuration.md

@@ -0,0 +1,63 @@
+# 11 — DRY Configuration registration
+
+**Status:** complete
+**Depends on:** —
+
+## Goal
+
+`Schema3::Configuration.register_models!` and
+`Schema24::Configuration.register_models!` are 99% identical — only
+the parent module differs. Both list every CML element class with the
+same id. This is a DRY / SSOT violation.
+
+Extract the registration loop into `ContextConfiguration` so each
+schema's Configuration is just a few lines:
+
+```ruby
+module Schema3
+  module Configuration
+    extend Chemicalml::ContextConfiguration
+
+    CONTEXT_ID = :chemicalml_schema3
+    REGISTERED_ELEMENTS = %i[
+      atom atomArray atomParity bond bondArray bondStereo
+      document formula identifier label list matrix metadata
+      ...
+    ].freeze
+
+    register_element_classes!
+  end
+end
+```
+
+The shared `register_element_classes!` walks the list, looks up each
+class on the parent module, and calls `register_model`.
+
+## Why
+
+Today, adding a new CML element means:
+
+1. Creating `Base::Foo`
+2. Creating `Schema3::Foo` and `Schema24::Foo`
+3. **Adding `register_model Foo, id: :foo` to BOTH Configuration files**
+4. Adding translator rules
+5. Adding specs
+
+Step 3 is duplicated work. After this fix, the element name goes in one
+list (`REGISTERED_ELEMENTS`) and both schemas pick it up automatically.
+
+## Deliverables
+
+- [ ] `Chemicalml::ContextConfiguration#register_element_classes!`
+      iterates `REGISTERED_ELEMENTS`, looks up each class on
+      `version_parent_module`, and registers it.
+- [ ] `Schema3::Configuration` and `Schema24::Configuration` reduced
+      to ~10 lines each: `extend`, `CONTEXT_ID =`, `REGISTERED_ELEMENTS =`,
+      `register_element_classes!`.
+
+## Acceptance
+
+- Both Configuration files under 20 lines.
+- Adding a new element requires touching exactly ONE place
+      (the `REGISTERED_ELEMENTS` array).
+- All specs still pass.

data/TODO.align/12-wire-class-macro.md

@@ -0,0 +1,51 @@
+# 12 — Wire class definition macro
+
+**Status:** complete
+**Depends on:** 11
+
+## Goal
+
+Each `lib/chemicalml/cml/schema3/foo.rb` and `schema24/foo.rb` file is
+12 lines of boilerplate differing only by the class name and context
+id. That's 36 × 2 = 72 files of nearly-identical code.
+
+Reduce to a single declarative call per schema:
+
+```ruby
+# lib/chemicalml/cml/schema3.rb
+Chemicalml::Cml.define_wire_classes(
+  in: Schema3,
+  base: Base,
+  context_id: :chemicalml_schema3,
+  elements: REGISTERED_ELEMENTS
+)
+```
+
+The macro creates one class per element name, includes the
+corresponding Base and Visitable mixins, and defines
+`lutaml_default_register`.
+
+## Why
+
+- DRY: one place to change the wire-class shape (e.g. adding another
+  mixin, changing the parent class).
+- SSOT: the per-element declaration lives in `REGISTERED_ELEMENTS` (from
+  task 11), not duplicated across 72 files.
+- New schema version: just add `define_wire_classes(in: Schema5, ...)`
+  with no per-class boilerplate.
+
+## Deliverables
+
+- [ ] `Chemicalml::Cml.define_wire_classes` class method on the `Cml`
+      module. Takes `in:`, `base:`, `context_id:`, `elements:` keyword
+      args.
+- [ ] Delete the 72 per-class files.
+- [ ] Update `schema3.rb` / `schema24.rb` to call the macro.
+
+## Acceptance
+
+- The 72 thin class files are gone.
+- `lib/chemicalml/cml/schema3/*.rb` and `schema24/*.rb` directories
+  contain only `configuration.rb` (and any future schema-specific
+  overrides).
+- All specs still pass.

data/TODO.align/13-wire-namespace.md

@@ -0,0 +1,44 @@
+# 13 — Wire XML namespace setup
+
+**Status:** complete
+**Depends on:** —
+
+## Goal
+
+Today, round-tripping a namespaced CML document produces inner
+elements with spurious `xmlns=""` attributes:
+
+```xml
+<molecule xmlns="http://www.xml-cml.org/schema" id="m1">
+  <atomArray xmlns="">           <!-- ← bug -->
+    <atom id="a1" elementType="C"/>
+  </atomArray>
+</molecule>
+```
+
+This is because the wire classes don't declare a namespace on their
+`xml do ... end` block, so the framework assumes the empty namespace.
+
+Add `namespace Chemicalml::Cml::Namespace` to each Base module's xml
+block so output preserves the CML namespace.
+
+## Why
+
+- Real bug — the round-trip isn't faithful.
+- `canon` semantic comparison will catch this once we switch the
+  fixture spec to it (task 15).
+
+## Deliverables
+
+- [ ] Verify `Chemicalml::Cml::Namespace` is a proper lutaml namespace
+      declaration.
+- [ ] Add `namespace Chemicalml::Cml::Namespace` to the `xml do` block
+      in every `lib/chemicalml/cml/base/*.rb` mixin.
+- [ ] Round-trip a fixture with namespace declaration and confirm no
+      `xmlns=""` appears on inner elements.
+
+## Acceptance
+
+- A round-tripped `<cml xmlns="..."><molecule>...</molecule></cml>` is
+  byte-equivalent in namespace structure to the input.
+- Canon matcher specs pass on full-document round-trip.

data/TODO.align/14-schema24-correctness.md

@@ -0,0 +1,37 @@
+# 14 — Schema 2.4 correctness
+
+**Status:** complete
+**Depends on:** 11
+
+## Goal
+
+Schema 2.4 does NOT have the generic `<module>` element — it was
+introduced in Schema 3. Currently `Chemicalml::Cml::Schema24::Module`
+exists anyway, which is incorrect.
+
+Drop `Schema24::Module` and document the divergence in the schema24.rb
+file's header comment.
+
+## Why
+
+- SSOT — the set of valid Schema 2.4 elements is defined by the XSD,
+  not by Ruby convenience. Including extra elements makes the wire
+  classes lie about what schema they implement.
+- Compchem-convention documents (which use `<module>` heavily) MUST be
+  parsed as Schema 3, not Schema 2.4. This makes that explicit.
+
+## Deliverables
+
+- [ ] Remove `lib/chemicalml/cml/schema24/cml_module.rb`.
+- [ ] Remove `Schema24::Module` autoload from `schema24.rb`.
+- [ ] Ensure `Schema24::Configuration.register_models!` does NOT
+      register `:module`.
+- [ ] Document in `schema24.rb` header that Schema 2.4 lacks `<module>`.
+- [ ] Add a spec verifying `Chemicalml::Cml::Schema24` does not have
+      `Module` defined.
+
+## Acceptance
+
+- `defined?(Chemicalml::Cml::Schema24::Module)` returns `nil`.
+- All other Schema24 classes load and round-trip normally.
+- Specs pass.

data/TODO.align/15-canon-fixture-roundtrip.md

@@ -0,0 +1,38 @@
+# 15 — Canon-based fixture round-trip
+
+**Status:** complete
+**Depends on:** 13
+
+## Goal
+
+The current `spec/chemicalml/fixtures_round_trip_spec.rb` only checks
+that `.molecules.length` is preserved across a round-trip. It misses
+attribute-level regressions (dropped attributes, wrong order, changed
+values).
+
+Switch to `be_xml_equivalent_to` (from the `canon` gem) for semantic
+XML comparison. Depends on task 13 (namespace fix) so the comparison
+isn't tripped up by spurious `xmlns=""` attributes.
+
+## Why
+
+- Catches real regressions: a dropped `elementType` attribute or a
+  reordered atom would slip past today's check.
+- Tolerates formatting differences (attribute order, whitespace) that
+  round-trip serialization legitimately introduces.
+- Matches the spec idioms used in the sibling `mml` gem.
+
+## Deliverables
+
+- [ ] `fixtures_round_trip_spec.rb` rewritten to use
+      `expect(round_tripped_xml).to be_xml_equivalent_to(input_xml)`.
+- [ ] One example per fixture file.
+- [ ] Document any fixtures that can't yet round-trip cleanly (known
+      limitations) with `skip "reason"` rather than removing the test.
+
+## Acceptance
+
+- `bundle exec rspec spec/chemicalml/fixtures_round_trip_spec.rb` is
+  green.
+- Manually introducing a regression (e.g. dropping an attribute from
+  a Base module) causes a spec failure.