chemicalml 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5aff6a0c43deeff73ff9684286df7c1a7ef97d61fa919415a381e70de217995c
-  data.tar.gz: 52237d4db8715d8244b88c124cf3bdc1ad43102b4468d8217099ebdec6b89f1b
+  metadata.gz: ed7130181d6d55cbadb29d2630668ab4f16746f10dc20db9c9d1d0ff066586c6
+  data.tar.gz: ac78d79e906862aa42639b2d237ec66661a8c3061e4b25c04535f8941520b3d3
 SHA512:
-  metadata.gz: b9f636c62b495c14f5ab10df0c8fd30e49aa23587731587f2fc9f4d87837376da38db8814df48482e1725751090518722ff3e6ca43ea5197fefb53ab5055183a
-  data.tar.gz: c7b42562ce98060bd3ca135d137be215f25a2ae71e2fc2693b70ab7e1030f8c6868744dea7aa9d60d078ba6adc11fc28a7c8d63de4f5f69c0a9b16ff8fe6f65f
+  metadata.gz: 5909cc1b258048f0c5aefba5844fff9136f2db4713d5cd5b80a22c07045e60a5ee5ead34680a841a9044039824c76cd4913d48d8f3410f86bf99b043f5739ba4
+  data.tar.gz: ff4f54de5ce734ae649554f593cfc1affa766b7e541fef394704bcd1b4d192dbae3e788241ced6a4dc6306bacf62b409fad2fdafe6861617497d7ff2ced16dee

data/.rubocop.yml

@@ -10,11 +10,34 @@ AllCops:
     - "coverage/**/*"
     - "reference-docs/**/*"
     - "spec/fixtures/**/*"
+    - "data/**/*"
 
 Metrics/BlockLength:
   Exclude:
     - "spec/**/*"
     - "*.gemspec"
+    - "lib/chemicalml/cml/base/**/*.rb"
+
+# Base::* modules are structurally long: each declares every attribute
+# and both xml + key_value mapping blocks for one CML element in a
+# single `self.included` hook. This is the correct structure — the
+# alternative (splitting into smaller methods) would scatter one
+# element's declarations across multiple files.
+Metrics/MethodLength:
+  Exclude:
+    - "lib/chemicalml/cml/base/**/*.rb"
+
+Metrics/AbcSize:
+  Exclude:
+    - "lib/chemicalml/cml/base/**/*.rb"
+
+Metrics/ModuleLength:
+  Exclude:
+    - "lib/chemicalml/cml/base/**/*.rb"
+
+Layout/LineLength:
+  Exclude:
+    - "lib/chemicalml/cml/base/**/*.rb"
 
 Style/Documentation:
   Enabled: false

data/CLAUDE.md

@@ -26,6 +26,9 @@ bundle exec rspec -e "round-trips"                       # by name match
 bundle exec rake              # alias for rspec
 bundle exec rubocop           # lint
 bundle exec rubocop -A        # autocorrect
+bundle exec chemicalml validate <file.cml>  # CLI validation
+bundle exec chemicalml conventions          # list registered conventions
+bundle exec chemicalml dictionaries         # list built-in dictionaries
 ```
 
 `spec/examples.txt` and `Gemfile.lock` are gitignored — `spec/examples.txt`
@@ -126,17 +129,35 @@ Schema 3's unified `scalar`/`array`/`table` machinery.
 The framework handles (de)serialization; **never** add `def to_xml` /
 `def from_xml` / `def to_h` to these classes.
 
+### JSON / YAML wire names
+
+Every `Base::*` module declares a `key_value do ... end` block
+alongside its `xml do ... end` block, mirroring the XML wire names
+explicitly. JSON and YAML output carry CML wire names
+(`elementType`, `atomArray`) rather than Ruby snake_case names.
+The blocks are written out by hand per Base module — no runtime
+introspection.
+
 ### Schema versions
 
 `Chemicalml::Schema::Registry` is the registry for schema versions
 (`schema24`, `schema3`). The schema XSDs are **archival source** —
 they must never be deleted, edited, or regenerated from code.
 
+**Type-name collision**: Schema24's legacy `<string>`, `<integer>`,
+`<float>` elements share their XML names with lutaml-model primitives
+(`:string`, `:integer`, `:float`). They are NOT registered as types
+in the Schema24 context (would shadow the primitive, breaking every
+`:string` attribute cast). They remain defined as wire classes and
+parseable as document roots. See
+`Cml::Elements::SCHEMA24_TYPE_COLLISIONS`.
+
 ### Conventions
 
 `Chemicalml::Convention` is a registry of named constraint sets
 (`molecular`, `compchem`, `dictionary`, `unit-dictionary`,
-`unitType-dictionary`). Each convention owns:
+`unitType-dictionary`, `spectroscopy`, `cascade`, `simpleUnit`).
+Each convention owns:
 
 - a namespace URI (e.g. `http://www.xml-cml.org/convention/molecular`)
 - a set of constraint classes registered against it
@@ -148,6 +169,33 @@ renderer code (Open/Closed Principle).
 The constraint walker uses `Cml::Visitable#wire_children` to traverse
 the tree — no `respond_to?` duck typing.
 
+The shared `Cml::Base::CommonChildren` mixin provides `metadataList`,
+`label`, `name`, and `description` children that the XSD grants to
+most container elements. Including it in a `Base::*` module is the
+DRY way to declare the universal child set.
+
+`Cml::Enums` is the canonical Ruby source of truth for every XSD
+enum simpleType. Three constraints validate against it
+(`BondOrderShouldBeInEnum`, `BondStereoShouldBeInEnum`,
+`MoleculeChiralityShouldBeInEnum`) at warning severity — extension
+values are permitted but flagged.
+
+`Cml::ReferenceResolver` walks a document and resolves
+id-references (`atomRefs2`, `atomRefs4`, `bondRefs`, `ref`) to
+target wire instances. `unresolved_refs` lists missing targets;
+useful for callers that need to follow CML references.
+
+### Parallel-array serialisation
+
+`<atomArray>` and `<bondArray>` support two equivalent XML forms: the
+child form (`<atomArray><atom.../><atom.../></atomArray>`) and the
+parallel-array form (`<atomArray atomID="a1 a2" elementType="C O"/>`).
+The wire attribute names in the parallel-array form match the
+singular `<atom>` / `<bond>` attribute names (e.g. `elementType`,
+`atomRef1`) — the XSD attribute *group* is named `elementTypeArray`
+etc., but the wire attribute is `elementType`. Ruby attribute names
+carry an `_array` suffix for clarity at the call site.
+
 ### Dictionaries
 
 `Chemicalml::Dictionary` is the model; entries have `id`, `term`,

data/README.adoc

@@ -4,13 +4,19 @@ ChemML provides a https://www.xml-cml.org/[Chemical Markup Language (CML)]
 object model for Ruby, built on
 {lutaml-model}[https://github.com/lutaml/lutaml-model].
 
-== Purpose
-
-CML is the established XML standard for chemistry. Existing Ruby
-libraries either don't exist or use hand-rolled XML manipulation that
-drifts from the CML schema. ChemML gives CML a proper model layer
-with declarative attribute/mapping definitions and framework-backed
-serialization.
+== Features
+
+* Full Schema 3 and Schema 2.4 coverage — every CML element, attribute,
+  and XSD enum/pattern modelled as Ruby classes.
+* Format-agnostic serialization — XML, JSON, YAML, and TOML round-trip
+  via lutaml-model adapters.
+* Eight built-in conventions with 88+ registered constraints:
+  `molecular`, `compchem`, `dictionary`, `unit-dictionary`,
+  `unitType-dictionary`, `spectroscopy`, `cascade`, `simpleUnit`.
+* Built-in dictionaries (cml, compchem, cif, unit_si, unit_non_si,
+  unit_type, cml_name, cml_formula) loaded from YAML.
+* CLI for command-line validation and inspection.
+* Ruby-native query API (`doc.find_atom(id)`, `doc.each_molecule`).
 
 == Install
 
@@ -30,45 +36,167 @@ $ gem install chemicalml
 
 == Usage
 
-Parse a CML document:
+=== Parse a CML document
 
 [source,ruby]
 ----
 require "chemicalml"
 
-doc = Chemicalml::Cml::Document.from_xml(File.read("ethanol.cml"))
-doc.molecules.first.atoms.first.element_type # => "C"
+doc = Chemicalml.parse_file("ethanol.cml")
+doc.molecules.first.atom_array.atoms.first.element_type # => "C"
+----
+
+=== Validate against a convention
+
+[source,ruby]
+----
+report = Chemicalml.validate(doc)
+puts report.summary
+puts report.errors.map(&:message)
 ----
 
-Build a document programmatically:
+=== Build a document programmatically
 
 [source,ruby]
 ----
 atom = Chemicalml::Cml::Atom.new(id: "a1", element_type: "C")
-mol  = Chemicalml::Cml::Molecule.new(id: "m1", atoms: [atom])
+mol  = Chemicalml::Cml::Molecule.new(
+  id: "m1",
+  atom_array: Chemicalml::Cml::AtomArray.new(atoms: [atom])
+)
 doc  = Chemicalml::Cml::Document.new(molecules: [mol])
 
 doc.to_xml # => well-formed CML XML
 ----
 
-== Design
+=== Query the tree
 
-Each CML element is a `Lutaml::Model::Serializable` subclass with
-declared attributes and an XML mapping block. Serialization goes
-through lutaml-model — no hand-rolled XML.
+[source,ruby]
+----
+doc.each_atom { |a| puts "#{a.id}: #{a.element_type}" }
+doc.find_atom("a1")     # => Atom instance
+doc.atom_count          # => recursive count
+doc.find_molecule("m1") # => Molecule instance
+----
+
+=== Cross-format serialisation
+
+[source,ruby]
+----
+doc.to_xml   # CML XML
+doc.to_json  # JSON with CML wire names (elementType, atomArray, ...)
+doc.to_yaml  # YAML
+----
+
+=== Resolve references
+
+[source,ruby]
+----
+resolver = Chemicalml::Cml::ReferenceResolver.new(doc)
+resolver.unresolved_refs  # => [{ node: <Bond>, attr: :atom_refs2, missing: ["a99"] }]
+----
+
+== CLI
+
+[source,sh]
+----
+$ chemicalml validate file.cml    # auto-detect convention, print violations
+$ chemicalml inspect file.cml     # tree-style summary
+$ chemicalml conventions          # list 8 registered conventions
+$ chemicalml dictionaries         # list built-in YAML dictionaries
+$ chemicalml elements             # list all CML wire classes
+----
+
+== Conventions
+
+Eight conventions register 88+ constraints:
+
+[cols="1,1,1"]
+|===
+| Convention | Constraints | Description
+
+| molecular | 35 | Atom/bond/molecule well-formedness, id patterns,
+  element type validation, dictRef resolution, AtomParity parent
+  check, references-resolve check.
+| compchem | 20 | JobList/Job/Initialization/Calculation/Finalization
+  module structure, scalar/array/matrix value rules.
+| dictionary | 8 | Dictionary namespace, prefix, entry id/term/definition,
+  unitType/units co-constraints.
+| unit-dictionary | 8 | UnitList namespace, unit id/title/symbol/parentSI/
+  multiplierToSI, definition child.
+| unitType-dictionary | 5 | UnitTypeList namespace, unitType id/name/definition.
+| spectroscopy | 5 | Spectrum convention/format/content, peakList, peak values.
+| cascade | 4 | ReactionScheme content, reactionStepList, reactiveCentre atomRefs.
+| simpleUnit | 3 | simpleUnit root, unit power, unit symbol.
+|===
+
+Add a custom convention at runtime:
+
+[source,ruby]
+----
+module MyConvention
+  extend Chemicalml::Convention::Base
+
+  def self.qname; "convention:my"; end
+  def self.namespace_uri; "http://example.com/my"; end
+
+  register MyConstraintClass
+end
 
-The library is designed as a sibling model layer to other chemistry
-tooling. AsciiChem (https://www.asciichem.org) uses ChemML for CML
-round-trip support via a translator adapter.
+Chemicalml::Convention::Registry.register_custom(MyConvention)
+----
+
+== Dictionaries
+
+Eight built-in YAML dictionaries ship under `data/dictionaries/`:
+
+[cols="1,1"]
+|===
+| Dictionary | Prefix
+
+| cml | cml
+| cml_name | cmlName
+| cml_formula | cmlFormula
+| cif | cif
+| compchem | compchem
+| unit_si | si
+| unit_non_si | nonsi
+| unit_type | unitType
+|===
+
+Load via:
 
-Both Schema 2.4 and Schema 3 are supported via
-`Chemicalml::Cml::Schema3` and `Chemicalml::Cml::Schema24` namespaces
-(see `lib/chemicalml/schema.rb`).
+[source,ruby]
+----
+dict = Chemicalml::Dictionary.load(:cml)
+entry = Chemicalml::Dictionary::Registry.lookup("cml:bp")
+entry.term        # => "Boiling Point"
+entry.definition  # => "The temperature at which a substance boils..."
+----
 
-The CML conventions (molecular, compchem, dictionary, unit-dictionary,
-unitType-dictionary) are implemented as registered constraint sets in
-`Chemicalml::Convention`. Built-in dictionaries ship as YAML under
-`data/dictionaries/`.
+== Design
+
+Each CML element is a `Lutaml::Model::Serializable` subclass with
+declared attributes and parallel `xml do ... end` and
+`key_value do ... end` mapping blocks. Serialisation is fully
+framework-backed — no hand-rolled XML.
+
+* `Cml::Base::*` modules declare shared attributes (mixed into both
+  Schema3 and Schema24 wire classes).
+* `Cml::Role::*` modules are type-markers used by the convention
+  constraint walker for `is_a?` dispatch.
+* `Cml::Elements::ALL` is the single source of truth for the CML
+  element table.
+* `Cml::Enums` and `Cml::Patterns` mirror XSD simpleTypes.
+* `Cml::CommonChildren` provides the universal `metadataList`,
+  `label`, `name`, `description` child set as a DRY mixin.
+
+== Reference docs
+
+`reference-docs/` holds archival source material from xml-cml.org:
+the XSDs (`schemas/schema3/schema.xsd`, `schemas/schema24/schema.xsd`),
+the convention specifications, and the CMLLite paper. These are
+**source material, not derived output** — never delete or edit them.
 
 == Acknowledgements
 

data/TODO.align/61-parallel-array-attrs.md

@@ -0,0 +1,54 @@
+# 61 — Parallel-array attrs for atomArray/bondArray
+
+## Why
+
+CML supports two equivalent serialisations of atom/bond tables:
+
+```xml
+<!-- child form (we already model this) -->
+<atomArray><atom id="a1" elementType="C" x3="1.0" .../><atom .../></atomArray>
+
+<!-- parallel-array form (we do NOT model this) -->
+<atomArray atomID="a1 a2" elementType="C O" x3="1.0 2.0" .../>
+```
+
+The parallel-array form is heavily used in real CML documents and is
+the only form some legacy tools emit. Round-trip currently drops these
+attributes silently.
+
+## Source of truth
+
+`reference-docs/schemas/schema3/schema.xsd` — `atomArrayType` complexType
+declares these 14 parallel-array attributes:
+
+- `atomID` (idArrayType)
+- `count`, `countArrayType`
+- `elementType`, `elementTypeArrayType`
+- `formalCharge`, `formalChargeArrayType`
+- `hydrogenCount`, `hydrogenCountArrayType`
+- `occupancy`, `occupancyArrayType`
+- `x2`, `y2` (coordinateComponentArrayType)
+- `x3`, `y3`, `z3` (coordinateComponentArrayType)
+- `xFract`, `yFract`, `zFract` (coordinateComponentArrayType)
+
+`bondArrayType` declares 4:
+
+- `atomRef1`, `atomRef2` (atomRefArrayType)
+- `bondID` (idArrayType)
+- `order` (orderArrayType)
+
+## Work
+
+1. `lib/chemicalml/cml/base/atom_array.rb` — declare the 14 attributes
+   as `:string` (lutaml-model does not need to validate the inner
+   whitespace-separated format) with matching `map_attribute` entries.
+2. `lib/chemicalml/cml/base/bond_array.rb` — declare the 4 attributes.
+3. Add specs in `spec/chemicalml/cml/parallel_array_spec.rb` asserting
+   round-trip for both forms.
+
+## Acceptance
+
+- `Chemicalml.parse` of a parallel-array `<atomArray>` populates the
+  attributes; `Chemicalml.serialize` emits them back unchanged.
+- Both forms supported for Schema3 and Schema24.
+- Specs green.

data/TODO.align/62-per-element-attribute-gaps.md

@@ -0,0 +1,49 @@
+# 62 — Per-element attribute gaps
+
+## Why
+
+XSD vs Ruby Base comparison reveals 53 (schema3) / 58 (schema24)
+attribute declarations that are not yet modelled. They cluster across
+20 elements. Most are 1-3 missing attributes; the parallel-array
+attributes for atomArray/bondArray are split out into TODO 61.
+
+## Gaps (after TODO 61 closes)
+
+| Element | Missing |
+|---|---|
+| alternative | type |
+| band | kpoint (schema24 only) |
+| bond | atomRefs (singular, not atomRefs2) |
+| cellParameter | error, type |
+| cml (module) | fileId, version |
+| eigen | orientation |
+| entry | convention, title, columns, rows, length, minLength, maxLength, pattern, minExclusive, minInclusive, maxExclusive, maxInclusive, fractionDigits, totalDigits, whiteSpace (XSD facets) |
+| isotope | spin |
+| module | role, serial |
+| molecule | formula |
+| peakStructure | type |
+| potential | form |
+| reaction | format, role |
+| reactionScheme | format, role, type |
+| reactionStepList | format |
+| relatedEntry | type (schema24 only) |
+| spectrum | type |
+| substance | id |
+| substanceList | type |
+| unitList | type |
+
+## Work
+
+For each row above, add `attribute :foo, :string` + `map_attribute "foo", to: :foo`
+to the relevant `lib/chemicalml/cml/base/*.rb` module.
+
+The 15 XSD facets on `entry` (columns, fractionDigits, etc.) are
+genuine CML — they describe the data type the entry represents, and
+are emitted by the upstream dictionary files. They are not internal
+XSD noise.
+
+## Acceptance
+
+- XSD vs Ruby comparison reports 0 attribute gaps.
+- Round-trip of an example with `entry/@pattern` etc. is preserved.
+- Spec coverage for at least one new attribute on each touched element.

data/TODO.align/63-universal-children-mixin.md

@@ -0,0 +1,42 @@
+# 63 — Universal children mixin
+
+## Why
+
+The CML Schema 2.4 XSD declares `metadataList`, `label`, `name`, and
+`description` as children of nearly every element. Adding these four
+declarations to every `Base::*` module individually is a DRY
+violation: the same 16 lines of `attribute` + `map_element` would
+appear in ~50 files.
+
+## Solution
+
+Introduce a shared mixin `Chemicalml::Cml::Base::CommonChildren`
+that declares:
+
+```ruby
+attribute :metadata_lists, :metadataList, collection: true
+attribute :labels, :label, collection: true
+attribute :names, :name, collection: true
+attribute :descriptions, :description, collection: true
+```
+
+with matching `map_element` declarations. The mixin is included by
+the `Base::*` modules whose XSD declares these children.
+
+The mixin is **opt-in** — elements that the XSD does not grant these
+children to (e.g. `<atom>`, `<bond>` in schema24) do not include it.
+This keeps MECE discipline: one place owns the universal child set.
+
+## Work
+
+1. Create `lib/chemicalml/cml/base/common_children.rb`.
+2. For each Base module where the XSD declares metadataList/label/name/description as a child, add `include CommonChildren` and remove the now-redundant individual declarations.
+3. Add a spec `spec/chemicalml/cml/common_children_spec.rb` asserting
+   the children appear after `include CommonChildren` and round-trip
+   through XML.
+
+## Acceptance
+
+- `CommonChildren` exists and is included by at least 10 Base modules.
+- No Base module re-declares `metadata_lists` / `labels` / `names` / `descriptions` individually.
+- Specs green.

data/TODO.align/64-per-element-child-gaps.md

@@ -0,0 +1,81 @@
+# 64 — Per-element child element gaps (Schema 2.4)
+
+## Why
+
+XSD vs Ruby Base comparison reveals 235 missing child declarations
+across ~60 Schema 2.4 elements. These are real CML elements that
+real CML documents contain but our Ruby model drops silently.
+
+The Schema 3 XSD declares `<anyCml>` (a wildcard) as a child of every
+element — that is intentionally NOT modelled as a concrete child,
+because doing so would defeat the type system. The Schema 2.4 gaps
+below are *specific* named children, not wildcards.
+
+## Largest clusters
+
+| Element | Missing children |
+|---|---|
+| molecule | angle, arg, array, crystal, electron, join, length, list, matrix, metadataList, propertyList, scalar, symmetry, torsion, zMatrix |
+| reaction | conditionList, identifier, label, map, mechanism, metadataList, name, object, propertyList, reactiveCentre, spectatorList, substanceList, transitionState |
+| reactant, product | amount, electron, formula, identifier, label, metadataList, molecule, name, substanceList |
+| atom | array, atomType, electron, label, matrix, name, particle, scalar, vector3 |
+| atomType, bondType | array, atom/bond, label, matrix, molecule, property, scalar |
+| join | angle, arg, label, length, metadataList, molecule, torsion |
+| peak, peakGroup | atom, bond, metadataList, molecule, peakStructure/peakGroup |
+| spectrum | metadataList, parameterList, sample, spectrumData, substanceList |
+| reactiveCentre | atomSet, atomTypeList, bondSet, bondTypeList, description |
+| parameter | expression, gradient, property |
+| property | metadataList, name |
+| parameterList, productList, reactantList, reactionStepList | metadataList, name, *(selfRef)* |
+| moleculeList | list, metadataList, moleculeList |
+| sample | metadataList, molecule, substance, substanceList |
+| spectator | label, metadataList, molecule, object |
+| substance | amount, metadataList, property |
+| substanceList | amount, metadataList, propertyList |
+| lattice | matrix, scalar, symmetry |
+| gradient | array, matrix, property, scalar |
+| table | arrayList, tableRowList |
+| transitionState | molecule, propertyList |
+| unit | annotation, metadata, metadataList, unit, unitType |
+| unitType | annotation, dimension |
+| zMatrix | angle, length, torsion |
+| symmetry | matrix, transform3 |
+| eigen | array, matrix |
+| xaxis, yaxis | array |
+| metadataList | metadataList |
+| crystal | cellParameter |
+| formula | formula |
+| dictionary | annotation, unitList |
+| dictionary entry | alternative, annotation, enumeration, metadataList, relatedEntry |
+| map | link |
+| mechanism | description, label, name |
+| peakStructure | metadataList, peakStructure |
+| reactionList | metadataList, reactionScheme |
+| reactionScheme | identifier, label, metadataList, name, reactionScheme |
+| reactionStep | label, metadataList, name, reactionScheme |
+| potentialForm | arg, expression, parameter |
+| trow | tcell |
+| peakList | metadataList |
+| atomTypeList, bondTypeList, basisSet | metadataList, name |
+| conditionList | list, metadataList, name |
+| propertyList | metadataList, name, observation, propertyList |
+| spectrumList | list, metadataList, spectrumList |
+
+## Strategy
+
+After TODO 63 (CommonChildren mixin) closes, ~80% of the
+`metadataList`/`label`/`name`/`description` gaps are absorbed by
+adding one `include CommonChildren` line. The remaining ~150 gaps are
+element-specific and require individual declarations.
+
+## Work
+
+1. Apply CommonChildren where the XSD permits.
+2. For each remaining gap, add the specific `attribute` + `map_element` declarations.
+3. Add at least one spec per touched element covering a round-trip
+   with the new child.
+
+## Acceptance
+
+- XSD vs Ruby child comparison reports only `<anyCml>` Schema3 wildcard gaps (intentionally unmodelled).
+- Specs green.

data/TODO.align/65-simple-unit-convention.md

@@ -0,0 +1,40 @@
+# 65 — SimpleUnit convention
+
+## Why
+
+`reference-docs/conventions/index.md` lists six CML conventions.
+We implement five + two added later (spectroscopy, cascade). The
+sixth "official" one is `simpleUnit`, used as the worked example in
+the CMLLite paper. Without it, the convention set is incomplete
+relative to the upstream CML spec.
+
+## Source
+
+`reference-docs/schemas/schema3/schema.xsd` — does not define
+convention rules; the rules come from the CMLLite paper. The
+namespace is `http://www.xml-cml.org/convention/simpleUnit`.
+
+The paper's simpleUnit example constraints:
+
+- A `<unit>` under simpleUnit MUST have a `power` attribute (integer).
+- A `<unit>` under simpleUnit MUST have a `symbol` attribute (non-empty string).
+- The root must be a `<unitList>` declaring `convention='convention:simpleUnit'`.
+
+## Work
+
+1. `lib/chemicalml/convention/simple_unit.rb` — main module (QNAME =
+   `convention:simpleUnit`, NAMESPACE_URI ends in `/simpleUnit`).
+2. `lib/chemicalml/convention/simple_unit/constraints.rb` — autoload registry.
+3. Three constraint files:
+   - `unit_must_have_power.rb` — applies_to Role::Unit
+   - `unit_must_have_symbol.rb` — applies_to Role::Unit
+   - `root_must_be_unit_list.rb` — DocumentConstraint
+4. Register in `Convention::Registry.load_cache`.
+5. Add `autoload :SimpleUnit` to `lib/chemicalml/convention.rb`.
+6. Specs at `spec/chemicalml/convention/simple_unit_spec.rb`.
+
+## Acceptance
+
+- `Chemicalml::Convention.lookup("convention:simpleUnit")` returns the module.
+- Specs cover all three constraints (positive + negative cases).
+- Full suite green.

data/TODO.align/66-schema24-legacy-children.md

@@ -0,0 +1,32 @@
+# 66 — Schema24-only legacy element children
+
+## Why
+
+Schema 2.4 declares 17 elements absent from Schema 3 (TODO 52 modelled
+them). Of those, several have non-trivial child models that were
+skipped during initial modelling. XSD vs Ruby comparison shows:
+
+| Element | Missing children |
+|---|---|
+| annotation | appinfo |
+| arg | array, atom, atomType, expression, matrix, scalar |
+| atomType | array, atom, label, matrix, molecule, property, scalar |
+| bondType | array, bond, label, matrix, molecule, property, scalar |
+| expression | operator, parameter |
+| enumeration | annotation |
+| potentialForm | arg, expression, parameter |
+
+These are real Schema 2.4 features; the rest of the legacy set
+(`float`, `integer`, `string`, `tcell`, `trow`, etc.) are scalar
+leaves without children.
+
+## Work
+
+1. Update each Schema24-only `Base::*` module to declare the missing
+   children + matching `map_element`.
+2. Add a spec per touched element.
+
+## Acceptance
+
+- XSD vs Ruby child comparison reports 0 Schema24-only-legacy gaps.
+- Specs green.

data/TODO.align/67-final-verification.md

@@ -0,0 +1,32 @@
+# 67 — Final spec / lint / docs verification
+
+## Why
+
+After TODOs 61-66 land, the public surface area grows by ~330 element
+attribute/child declarations plus a new convention. CLAUDE.md and the
+spec suite need to reflect the new state.
+
+## Work
+
+1. Update `CLAUDE.md`:
+   - List 8 conventions (molecular, compchem, dictionary, unit-dictionary,
+     unitType-dictionary, spectroscopy, cascade, simpleUnit).
+   - Note the parallel-array atomArray/bondArray serialisation forms.
+   - Note the `CommonChildren` mixin pattern.
+2. Scan the codebase for forbidden patterns:
+   - `require_relative` inside `lib/`
+   - `def to_h`, `def from_h`, `def to_xml`, `def from_xml`, `def to_json`, `def from_json` on model classes
+   - `double(` in specs
+   - `\.send(`, `instance_variable_set`, `instance_variable_get`, `respond_to?`
+   - AI attribution trailers in commit history
+3. Run full `bundle exec rspec` — must be green.
+4. Run `bundle exec rubocop` on touched files — must be clean.
+5. Add a top-level README under `TODO.align/` summarising rounds 1-17.
+
+## Acceptance
+
+- `bundle exec rspec` exits 0.
+- `grep -rn 'require_relative' lib/` returns nothing.
+- `grep -rn 'def to_h\|def from_h' lib/chemicalml/cml/` returns nothing.
+- `grep -rn 'double(' spec/` returns nothing.
+- CLAUDE.md convention list is current.