chemicalml 0.1.0 → 0.2.0

data/TODO.align/24-autoload-wire-classes.md

@@ -0,0 +1,84 @@
+# 24 — Autoload wire classes (revert round-2 task 12)
+
+**Status:** complete
+**Depends on:** —
+
+## Goal
+
+Replace the `const_set`-based wire class generation in `schema3.rb`
+and `schema24.rb` with per-class files loaded via `autoload`.
+
+## Why
+
+Round 2 task 12 consolidated 72 per-class files into two `const_set`
+loops. The user later pushed back on the same `const_set` pattern in
+role modules — `const_set` is eager, not autoload. The same logic
+applies here: `autoload` is required for lazy loading.
+
+## Design
+
+To avoid 72 nearly-identical boilerplate files, each schema gets a
+`Context` module that provides `lutaml_default_register`:
+
+```ruby
+# lib/chemicalml/cml/schema3/context.rb
+module Chemicalml
+  module Cml
+    module Schema3
+      module Context
+        def lutaml_default_register
+          :chemicalml_schema3
+        end
+      end
+    end
+  end
+end
+```
+
+Each per-class file is then minimal:
+
+```ruby
+# lib/chemicalml/cml/schema3/atom.rb
+module Chemicalml
+  module Cml
+    module Schema3
+      class Atom < Lutaml::Model::Serializable
+        include Base::Atom
+        include Visitable
+        extend Context
+      end
+    end
+  end
+end
+```
+
+And `schema3.rb` declares autoloads:
+
+```ruby
+module Schema3
+  autoload :Atom, "chemicalml/cml/schema3/atom"
+  autoload :Molecule, "chemicalml/cml/schema3/molecule"
+  # ...
+end
+```
+
+## Deliverables
+
+- [ ] `lib/chemicalml/cml/schema3/context.rb` — provides
+      `lutaml_default_register` returning `:chemicalml_schema3`.
+- [ ] `lib/chemicalml/cml/schema24/context.rb` — same for
+      `:chemicalml_schema24`.
+- [ ] 36 per-class files under `lib/chemicalml/cml/schema3/` (one
+      per element in `Elements::ALL`).
+- [ ] 35 per-class files under `lib/chemicalml/cml/schema24/` (no
+      `Module` — schema 2.4 lacks it).
+- [ ] `schema3.rb` / `schema24.rb` rewritten with autoloads only,
+      no `const_set`.
+- [ ] All specs pass.
+
+## Acceptance
+
+- `grep -rn 'const_set' lib/chemicalml/cml/schema3.rb
+      lib/chemicalml/cml/schema24.rb` returns nothing.
+- `Schema3::Atom` loads lazily (only when referenced).
+- All 155+ specs still pass.

data/TODO.align/25-value-container-schema-awareness.md

@@ -0,0 +1,44 @@
+# 25 — value_container schema-awareness
+
+**Status:** complete
+**Depends on:** —
+
+## Goal
+
+`Chemicalml::Cml::Translator::ValueTranslations` provides
+`scalar_from_canonical`, `array_from_canonical`,
+`matrix_from_canonical`, `value_container_from_canonical`, etc. All
+of them hardcode `Cml::Scalar` / `Cml::Array` / `Cml::Matrix` (which
+are Schema3 aliases).
+
+When `Translator.from_canonical(doc, schema: :schema24)` is called
+and the document has properties with scalar values, the scalars end
+up as `Schema3::Scalar` instances inside `Schema24::Property` objects
+— same kind of bug we just fixed for Document → Molecule → Atom.
+
+## Why
+
+Consistency. The Translator's main `from_canonical` is now
+schema-aware via `WireClassRegistry`. The value-container path should
+be too.
+
+## Deliverables
+
+- [ ] `scalar_from_canonical(scalar, schema:)`,
+      `array_from_canonical(array, schema:)`,
+      `matrix_from_canonical(matrix, schema:)` — take schema, look
+      up wire class via `WireClassRegistry`.
+- [ ] `value_container_from_canonical(value, schema:)` — passes
+      schema through.
+- [ ] `property_from_canonical(prop, schema:)`,
+      `parameter_from_canonical(param, schema:)` — passes schema to
+      value_container_from_canonical.
+- [ ] All callers updated.
+- [ ] Spec verifying `Schema24::Property` has `Schema24::Scalar`
+      children.
+
+## Acceptance
+
+- A round-trip canonical → Schema24 wire with a property+scalar
+      produces `Schema24::Property` with a `Schema24::Scalar` value.
+- All specs pass.

data/TODO.align/26-remove-dead-code.md

@@ -0,0 +1,16 @@
+# 26 — Remove dead wire_class_macro.rb
+
+**Status:** complete
+**Depends on:** —
+
+## Goal
+
+`lib/chemicalml/cml/wire_class_macro.rb` is dead code — a leftover
+from the round-2 macro experiment. Nothing references it. Remove.
+
+## Acceptance
+
+- `lib/chemicalml/cml/wire_class_macro.rb` deleted.
+- No references to `WireClassMacro` or `define_wire_classes` in lib/
+  or spec/.
+- All specs pass.

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

@@ -0,0 +1,26 @@
+# 27 — Final spec + lint pass
+
+**Status:** complete
+**Depends on:** all
+
+## Goal
+
+Verify the round-4 changes don't regress anything and the autoload
+rule is now satisfied everywhere it can be.
+
+## Deliverables
+
+- [ ] `bundle exec rspec spec/chemicalml/` green.
+- [ ] `grep -rn 'const_set' lib/chemicalml/cml/schema3.rb
+      lib/chemicalml/cml/schema24.rb` clean.
+- [ ] `grep -rn 'require_relative' lib/` clean.
+- [ ] `grep -rn '^require .chemicalml' lib/` clean.
+- [ ] `grep -rn 'respond_to?' lib/` clean.
+- [ ] `grep -rn 'instance_variable_set\|instance_variable_get' lib/`
+      clean.
+- [ ] `grep -rnE '[^a-zA-Z_\.]send[ ]*\(' lib/` clean.
+- [ ] TODO.align/README.round4.md shows every workstream complete.
+
+## Acceptance
+
+All checks pass.

data/TODO.align/28-stereo-model.md

@@ -0,0 +1,40 @@
+# 28 — Model::AtomParity + Model::BondStereo
+
+**Status:** complete
+**Depends on:** —
+
+## Goal
+
+Add canonical Model classes for the CML stereo elements `<atomParity>`
+and `<bondStereo>`. Wire classes exist; the canonical layer is
+missing.
+
+## Why
+
+CML's molecular convention uses `<atomParity>` (atom-centre chirality)
+and `<bondStereo>` (cis/trans + wedge/hatch) to represent
+stereochemistry. Without canonical classes, the gem can parse these
+elements but can't represent them in the format-agnostic model —
+forcing callers to drop stereo info when going through canonical.
+
+## Deliverables
+
+- [ ] `lib/chemicalml/model/atom_parity.rb` — Model::AtomParity with
+      `atom_refs4` (four atom IDs as array) and `value` (typically
+      `"1"`, `"-1"`, `"0"`).
+- [ ] `lib/chemicalml/model/bond_stereo.rb` — Model::BondStereo with
+      `atom_refs2` (optional array), `atom_refs4` (optional array),
+      `dict_ref` (optional), `value` (the convention letter: `"W"`,
+      `"H"`, `"C"`, `"T"`, `"other"`).
+- [ ] Both classes inherit from `Model::Node` and implement
+      `value_attributes`.
+- [ ] Autoloads declared in `lib/chemicalml/model.rb`.
+- [ ] Specs.
+
+## Acceptance
+
+- `Chemicalml::Model::AtomParity.new(atom_refs4: %w[a1 a2 a3 a4], value: "1")`
+      works.
+- `Chemicalml::Model::BondStereo.new(atom_refs4: %w[a1 a2 a3 a4], value: "C")`
+      works.
+- Specs pass.

data/TODO.align/29-stereo-wire-children.md

@@ -0,0 +1,30 @@
+# 29 — Wire Atom/Bond to carry stereo children
+
+**Status:** complete
+**Depends on:** 28
+
+## Goal
+
+Today `Base::Atom` doesn't declare an `atom_parity` child attribute.
+Same for `Base::Bond` and `bond_stereo`. So parsing a fixture with
+`<atom><atomParity .../></atom>` silently drops the parity. Add the
+child attributes to the Base mixins.
+
+## Why
+
+Without this, the wire classes can't represent stereo even though
+their dedicated wire classes (AtomParity, BondStereo) exist.
+
+## Deliverables
+
+- [ ] `Base::Atom` declares `attribute :atom_parity, :atomParity`
+      and `xml do map_element "atomParity", to: :atom_parity end`.
+- [ ] `Base::Bond` declares `attribute :bond_stereo, :bondStereo`
+      and `xml do map_element "bondStereo", to: :bond_stereo end`.
+- [ ] Parse a fixture with `<atomParity>` and confirm it's loaded.
+- [ ] Round-trip preserves the child.
+
+## Acceptance
+
+- Parsing `ethene_with_bond_stereo.cml` retains the bondStereo.
+- Parsing `chiral_center.cml` retains the atomParity.

data/TODO.align/30-stereo-translator.md

@@ -0,0 +1,32 @@
+# 30 — Translator rules for stereo
+
+**Status:** complete
+**Depends on:** 28, 29
+
+## Goal
+
+Add Translator rules so stereo elements round-trip through the
+canonical Model:
+
+- `atom_parity_to_canonical` / `atom_parity_from_canonical`
+- `bond_stereo_to_canonical` / `bond_stereo_from_canonical`
+
+And wire them into `molecule_to_canonical` / `molecule_from_canonical`
+so atoms and bonds carry their stereo children across the translation.
+
+## Deliverables
+
+- [ ] Translator methods for both elements, schema-aware via
+      WireClassRegistry.
+- [ ] `molecule_to_canonical` reads `cml_atom.atom_parity` and
+      translates it.
+- [ ] `molecule_from_canonical` writes the parity back to the wire atom.
+- [ ] Same for bonds and `bond_stereo`.
+- [ ] Spec round-tripping a chiral molecule through canonical.
+
+## Acceptance
+
+- Round-trip a chiral_center fixture through canonical preserves
+      the atomParity value.
+- Round-trip ethene_with_bond_stereo through canonical preserves
+      the bondStereo.

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

@@ -0,0 +1,20 @@
+# 31 — Final spec + lint pass
+
+**Status:** complete
+**Depends on:** all
+
+## Goal
+
+Verify the stereo additions don't regress anything.
+
+## Deliverables
+
+- [ ] `bundle exec rspec spec/chemicalml/` green.
+- [ ] Round-trip of chiral_center.cml and ethene_with_bond_stereo.cml
+      preserves the stereo elements.
+- [ ] Zero forbidden patterns in lib/.
+- [ ] TODO.align/README.round5.md marked complete.
+
+## Acceptance
+
+All checks pass.

data/TODO.align/32-polymorphic-translator.md

@@ -0,0 +1,43 @@
+# 32 — Polymorphic Translator
+
+**Status:** complete
+**Depends on:** —
+
+## Goal
+
+`Translator.to_canonical` and `from_canonical` currently only handle
+Document roots. A compchem `<module>` root can't go through the
+canonical round-trip via the public API — callers must know to use
+`module_to_canonical` / `module_from_canonical` directly.
+
+Make both methods polymorphic: dispatch on the input's class via
+Role module checks.
+
+## Why
+
+Consistency with the rest of the gem. `WireClassRegistry` already
+abstracts over schema versions; the Translator should abstract over
+root element kinds too. Users shouldn't need to know upfront whether
+their CML is `<cml>`-rooted or `<module>`-rooted.
+
+## Deliverables
+
+- [ ] `Translator.to_canonical(node)`:
+      - if `node.is_a?(Chemicalml::Cml::Role::Document)` → existing
+        document translation
+      - if `node.is_a?(Chemicalml::Cml::Role::Module)` →
+        `module_to_canonical(node)`
+      - else raise `ArgumentError`
+- [ ] `Translator.from_canonical(node, schema:)`:
+      - if `node.is_a?(Chemicalml::Model::Document)` → existing
+        document translation
+      - if `node.is_a?(Chemicalml::Model::Module)` →
+        `module_from_canonical(node, schema: schema)`
+      - else raise `ArgumentError`
+
+## Acceptance
+
+- Compchem fixture's wire Module translates to canonical Module
+      through the public `to_canonical` API.
+- Canonical Module translates back through `from_canonical`.
+- Unknown input raises `ArgumentError`.

data/TODO.align/33-polymorphic-parse.md

@@ -0,0 +1,43 @@
+# 33 — Polymorphic Chemicalml.parse
+
+**Status:** complete
+**Depends on:** 32
+
+## Goal
+
+`Chemicalml.parse(xml)` today only handles `<cml>`-rooted documents.
+Compchem documents rooted at `<module>` silently parse as empty
+Documents — the content is dropped without warning.
+
+Detect the root element via a regex peek and dispatch to the right
+parser.
+
+## Why
+
+Silent data loss. Today's behavior:
+```
+Chemicalml.parse(File.read("h2_dft.cml"))
+# => #<Chemicalml::Cml::Schema3::Document molecules=[] reactions=[]>
+```
+
+The caller has no indication that all the jobList / job / init / fin
+content was dropped. Should be either parsed correctly or raise an
+error.
+
+## Deliverables
+
+- [ ] `Chemicalml.parse(xml, schema:)` peeks the root tag.
+- [ ] `cml`, `molecule`, `reactionList`, `reaction` → Document parser.
+- [ ] `module` → Module parser (Schema3 only — Schema 2.4 lacks it).
+- [ ] Unknown root → `ArgumentError`.
+- [ ] Return type matches the root: Document or Module.
+- [ ] `Chemicalml.serialize(node)` remains polymorphic — already
+      just calls `node.to_xml`.
+
+## Acceptance
+
+- `Chemicalml.parse(File.read("h2_dft.cml"))` returns a Schema3 Module
+      with the jobList intact.
+- `Chemicalml.parse(File.read("water.cml"))` continues to return a
+      Schema3 Document.
+- Unknown root raises `ArgumentError`.

data/TODO.align/34-polymorphic-specs.md

@@ -0,0 +1,16 @@
+# 34 — Polymorphic API specs
+
+**Status:** complete
+**Depends on:** 32, 33
+
+## Goal
+
+Specs covering:
+- Compchem fixture parses to a non-empty Schema3 Module.
+- Polymorphic Translator dispatches Document and Module correctly.
+- Unknown roots / inputs raise ArgumentError.
+- Round-trip compchem → canonical → compchem preserves structure.
+
+## Acceptance
+
+All specs green.

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

@@ -0,0 +1,10 @@
+# 35 — Final spec + lint pass
+
+**Status:** complete
+**Depends on:** all
+
+## Acceptance
+
+- `bundle exec rspec spec/chemicalml/` green.
+- Zero forbidden patterns in lib/.
+- TODO.align/README.round6.md marked complete.

data/TODO.align/README.round10.md

@@ -0,0 +1,30 @@
+# TODO.align (round 10)
+
+Code cleanliness fixes.
+
+| # | Workstream | Status |
+|---|---|---|
+| 40 | Fix Base file indentation + extract Translator helpers | complete |
+
+## Issues fixed
+
+### 1. Base file indentation
+
+All 36 Base mixin files had inconsistent indentation on the
+`namespace` line inside `xml do` blocks — 12 spaces instead of 14.
+Fixed via automated `ruby -i -pe` across `lib/chemicalml/cml/base/*.rb`.
+
+### 2. Translator DRY: extracted name_to_canonical / identifier_to_canonical
+
+`molecule_to_canonical` was constructing `Model::Name` and
+`Model::Identifier` inline (two multi-argument `.new` calls in a
+single hash value) instead of calling dedicated helper methods —
+unlike every other element type which has its own `X_to_canonical`
+helper. Extracted to `name_to_canonical` / `identifier_to_canonical`
+methods for consistency with the rest of the Translator.
+
+## Final metrics
+
+- 179 examples, 0 failures
+- 0 forbidden patterns
+- 227 lib files

data/TODO.align/README.round11.md

@@ -0,0 +1,50 @@
+# TODO.align (round 11)
+
+Full CML schema coverage: every element from the XSD now has wire
+classes across Base, Role, Schema3, Schema24, and the Cml alias
+namespace.
+
+| # | Workstream | Status |
+|---|---|---|
+| 41 | Full CML element coverage (all 121 XSD elements) | complete |
+| 42 | Final spec + lint pass | complete |
+
+## What was added
+
+85 new CML elements, each with 4 generated files (Base mixin, Role
+module, Schema3 class, Schema24 class) + autoload declarations +
+Elements::ALL entry. The gem now covers every element defined in the
+CML Schema 3 XSD.
+
+### New element categories
+
+- **Geometry**: crystal, lattice, latticeVector, cellParameter,
+  zMatrix, line3, plane3, point3, sphere3, transform3, vector3,
+  angle, length, torsion
+- **Spectroscopy**: spectrum, spectrumData, spectrumList, peak,
+  peakGroup, peakList, peakStructure, xaxis, yaxis
+- **Reactions**: reactionScheme, reactionStep, reactionStepList,
+  reactiveCentre, transitionState, mechanism, mechanismComponent,
+  spectator, spectatorList, moleculeList, substanceList
+- **Electronic structure**: electron, atomicBasisFunction, eigen,
+  gradient, band, bandList, basisSet, kpoint, kpointList
+- **Sets / types**: atomSet, atomType, atomTypeList, bondSet,
+  bondType, bondTypeList
+- **Containers**: conditionList, fragment, fragmentList, region,
+  sample, system, potential, potentialForm, potentialList
+- **Documentation**: definition, description, documentation, dimension
+- **Tables**: table, tableCell, tableContent, tableHeader,
+  tableHeaderCell, tableRow, tableRowList
+- **Misc**: abundance, action, actionList, amount, anyCml, arrayList,
+  isotope, isotopeList, join, link, map, object, observation,
+  particle, stmml, symmetry
+
+### Metrics
+
+- Elements::ALL: 121 entries (up from 36)
+- Base mixins: 121
+- Role modules: 121
+- Schema3 classes: 121
+- Schema24 classes: 120 (Module is schema3-only)
+- 179 specs, 0 failures
+- 0 forbidden patterns

data/TODO.align/README.round12.md

@@ -0,0 +1,73 @@
+# TODO.align (round 12)
+
+Full CML schema coverage — parent-child wiring + remaining
+dictionaries + universal root parsing.
+
+| # | Workstream | Status |
+|---|---|---|
+| 42 | Wire parent-child relationships for 33 container elements | complete |
+| 43 | Add cml, cml_name, cml_formula, cif dictionaries | complete |
+| 44 | Universal root parsing (any element can be root) | complete |
+| 45 | Full coverage spec (121 elements + 8 dictionaries) | complete |
+
+## What was added
+
+### Parent-child relationships (33 containers wired)
+
+Every CML container element now declares its valid child elements.
+Previously, parsing `<crystal><scalar>5.64</scalar></crystal>`
+would silently drop the `<scalar>` child. Now it's preserved.
+
+Wired containers include:
+Molecule (crystal, spectrum, propertyList), Crystal (scalar,
+lattice, symmetry), Lattice (latticeVector), Spectrum (xaxis,
+yaxis, peakList, conditionList), PeakList (peak, peakGroup),
+Reaction (spectatorList, conditionList, metadataList),
+ReactionScheme, ReactionStepList, ReactionStep, ConditionList,
+FragmentList, Fragment, IsotopeList, BandList, KpointList,
+PotentialList, Table, TableContent, TableHeader, TableRow,
+TableRowList, SpectatorList, MoleculeList, SubstanceList,
+ActionList, AtomTypeList, BondTypeList, Mechanism, SpectrumList,
+SpectrumData, BasisSet, System.
+
+### Remaining dictionaries (4 added)
+
+- **cml.yaml** (23 entries) — fundamental chemistry concepts
+  (molmass, bp, mp, density, refractiveIndex, solubility,
+  vaporPressure, flashPoint, autoignitionTemp, pH, viscosity,
+  surfaceTension, dipoleMoment, polarizability, heatOfFormation,
+  entropy, freeEnergy, ionizationEnergy, electronAffinity,
+  electronegativity, bondEnergy, bondLength, bondAngle)
+- **cml_name.yaml** (10 entries) — naming conventions (IUPAC,
+  trivial, CAS, InChI, InChIKey, SMILES, PubChem, ChemSpider,
+  DrugBank, ChEBI)
+- **cml_formula.yaml** (7 entries) — formula conventions
+  (empirical, molecular, structural, condensed, Hill, SMILES,
+  LaTeX)
+- **cif.yaml** (19 entries) — crystallography (cell lengths,
+  cell angles, cell volume, Z, crystal system, space group,
+  fractional coordinates, occupancy, B factor, radiation
+  wavelength, resolution)
+
+### Universal root parsing
+
+The `KNOWN_ROOTS` hash is now a fallback, not the primary lookup.
+`Chemicalml.parse(xml)` first checks KNOWN_ROOTS, then falls back
+to `Elements::ALL` — making ANY CML element parseable as a root.
+Adding a new element to `Elements::ALL` automatically makes it
+parseable as a standalone document. OCP — no parse code changes
+needed.
+
+### Total dictionary count: 8
+
+compchem (51), cml (23), cml_name (10), cml_formula (7), cif (19),
+unit_si (25), unit_non_si (13), unit_type (35) = 183 total entries.
+
+## Final metrics
+
+- 188 examples, 0 failures
+- 121 CML elements (full XSD coverage)
+- 8 dictionaries (183 total entries)
+- 33 container elements with child relationships wired
+- Universal root parsing
+- 0 forbidden patterns

data/TODO.align/README.round13.md

@@ -0,0 +1,59 @@
+# TODO.align (round 13)
+
+Critical data-loss fix + missing unit types/units + convention
+constraint expansion.
+
+| # | Workstream | Status |
+|---|---|---|
+| 46 | Add atom coordinates (x2/y2/x3/y3/z3/xFract/yFract/zFract) | complete |
+| 47 | Add missing unit types + units | complete |
+| 48 | Add 5 molecular convention constraints | complete |
+| 49 | Final spec + lint pass | complete |
+
+## Critical fix: Atom coordinates were silently dropped
+
+The most important fix in this round: CML `<atom>` elements with
+2D coordinates (x2, y2), 3D coordinates (x3, y3, z3), or fractional
+coordinates (xFract, yFract, zFract) were being silently dropped
+during parsing. This affected virtually every real-world CML file
+that contains molecular structures.
+
+Fixed by:
+- Adding x2, y2, x3, y3, z3, xFract, yFract, zFract attributes to
+  `Base::Atom` with `map_attribute` declarations.
+- Adding matching fields to `Model::Atom` (canonical).
+- Updating `atom_to_canonical` / `atom_from_canonical` translator
+  rules to carry the coordinates through.
+
+Verified: parsing `methanol.cml` now correctly preserves
+`x3="-0.713"` through both wire parse and canonical translation.
+
+## Missing unit types + units added
+
+4 unit types referenced by the new dictionaries but not defined:
+density, viscosity, surfaceTension, entropy.
+
+10 non-SI units referenced but not defined:
+g_cm3, Pa_s, N_m, D (debye), A3, kJ_mol, J_molK, eV,
+angstrom2, angstrom3.
+
+## Convention constraints expanded
+
+5 new molecular convention constraints added:
+- `AtomMustHaveId` — every atom must have an `id` attribute
+- `AtomMustHaveElementType` — every atom must have `elementType`
+- `BondMustHaveAtomRefs2` — every bond must have `atomRefs2`
+- `BondMustHaveOrder` — every bond must have `order`
+- `MoleculeMustHaveId` — every molecule must have `id`
+
+Total molecular constraints: 8 (up from 3).
+
+## Final metrics
+
+- 188 examples, 0 failures
+- 121 CML elements (full XSD coverage)
+- 8 dictionaries (193+ total entries)
+- 8 molecular convention constraints
+- 12 total convention constraints (across 5 conventions)
+- Atom coordinates fully round-trip (2D, 3D, fractional)
+- 0 forbidden patterns

data/TODO.align/README.round14.md

@@ -0,0 +1,48 @@
+# TODO.align (round 14)
+
+Common attributes on original elements + performance fix + specs.
+
+| # | Workstream | Status |
+|---|---|---|
+| 50 | Add dict_ref/convention/id/title to original elements | complete |
+| 51 | O(1) VersionedParser root lookup | complete |
+| 52 | Coordinate + constraint specs | complete |
+
+## Fixes
+
+### Missing common attributes on original elements
+
+Three original Base mixins were missing common CML attributes that
+the 85 generated elements have by default:
+
+- **Base::Molecule**: added `dict_ref`, `convention`, `chirality`
+  with xml mappings. Without these, molecule-level dictRef
+  references and convention attributes were silently dropped.
+- **Base::Document** (`<cml>`): added `id`, `title`, `dict_ref`,
+  `convention` with xml mappings. The root `<cml>` element can
+  carry these attributes per the CML schema.
+- **Base::Reaction**: added `dict_ref`, `convention` with xml
+  mappings.
+
+### O(1) root element lookup
+
+VersionedParser was using `Elements::ALL.find { |_, id| id.to_s == root }`
+— O(121) linear search on every `parse()` call. Replaced with a
+pre-built reverse index `Elements::XML_TO_CLASS` (frozen Hash)
+giving O(1) lookup. Adding new elements to `Elements::ALL`
+automatically updates the index.
+
+### New specs (9 examples)
+
+- 5 coordinate round-trip specs: 3D (x3/y3/z3), 2D (x2/y2),
+  fractional (xFract/yFract/zFract), through wire → canonical → wire.
+- 4 constraint violation specs: atom missing id, atom missing
+  elementType, bond missing atomRefs2, molecule missing id.
+
+## Final metrics
+
+- **197 examples, 0 failures**
+- 121 CML elements, 8 dictionaries, 12 convention constraints
+- Atom coordinates fully round-trip
+- O(1) root element dispatch
+- 0 forbidden patterns