chemicalml 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 74eb61f89b283d3263aa4ead18e9b76061700defcc54232002855af6b1291c0a
-  data.tar.gz: 228f8f704086b458a73b3f4cb679b25133cf5ee36aa16d58c688a6439abb1974
+  metadata.gz: 5aff6a0c43deeff73ff9684286df7c1a7ef97d61fa919415a381e70de217995c
+  data.tar.gz: 52237d4db8715d8244b88c124cf3bdc1ad43102b4468d8217099ebdec6b89f1b
 SHA512:
-  metadata.gz: ba13a979cce6d48bbef181917107ac9ad24291131e8568652a012698c5e3ebe7f43851f908408478e4b4481d270cb9b83371d9c3f19093700df19a97565af2a9
-  data.tar.gz: 8557d650ab706936b25031541e256e840cc638d025d5c4b7308a512aa46e27d4223a050ba27b37c7d9c5408c1b1dd7af4974697699af317fec17a3ecfa262f92
+  metadata.gz: b9f636c62b495c14f5ab10df0c8fd30e49aa23587731587f2fc9f4d87837376da38db8814df48482e1725751090518722ff3e6ca43ea5197fefb53ab5055183a
+  data.tar.gz: c7b42562ce98060bd3ca135d137be215f25a2ae71e2fc2693b70ab7e1030f8c6868744dea7aa9d60d078ba6adc11fc28a7c8d63de4f5f69c0a9b16ff8fe6f65f

data/.github/workflows/release.yml

@@ -16,13 +16,19 @@ on:
           Also, you can pass 'skip' to skip 'git tag' and do 'gem push' for the current version
         required: true
         default: 'skip'
+      acknowledge_breaking_in_patch:
+        description: 'Override the patch-release breaking-change guard when the trip is a known false-positive'
+        required: false
+        type: boolean
+        default: false
   repository_dispatch:
     types: [ do-release ]
 
 jobs:
   release:
-    uses: relaton/support/.github/workflows/release.yml@main
+    uses: metanorma/ci/.github/workflows/rubygems-release.yml@main
     with:
       next_version: ${{ github.event.inputs.next_version }}
+      acknowledge_breaking_in_patch: ${{ inputs.acknowledge_breaking_in_patch }}
     secrets:
       rubygems-api-key: ${{ secrets.LUTAML_CI_RUBYGEMS_API_KEY }}

data/CLAUDE.md

@@ -33,23 +33,30 @@ is regenerated by RSpec on every run, and `Gemfile.lock` is development-only.
 
 ## Architecture (big picture)
 
-There are **five namespaces** under `Chemicalml`, deliberately kept
+There are **four namespaces** under `Chemicalml`, deliberately kept
 independent:
 
 ```
 Chemicalml
 ├── parse(xml, schema: :schema3)   # top-level entry point
-├── Model                          # canonical, format-agnostic chemistry objects
-├── Cml                            # CML XML wire-format classes
-│  ├── Base::*                     # shared attribute+mapping mixins
-│  ├── Schema3::*                  # Schema 3 wire classes
-│  ├── Schema24::*                 # Schema 2.4 wire classes
-│  └── Translator                  # the only adapter between Model and Cml
+├── Cml                            # CML model (lutaml-model Serializables)
+│  ├── Base::*                     # shared attribute + xml-mapping mixins
+│  ├── Schema3::*                  # Schema 3 classes (121 elements)
+│  ├── Schema24::*                 # Schema 2.4 classes (121 + 3 legacy)
+│  ├── Role::*                     # type-marker modules (schema-version-agnostic)
+│  ├── Visitable                   # constraint-walker interface
+│  └── WireClassRegistry           # (schema, role) → class lookup
 ├── Schema                         # version registry
 ├── Convention                     # 5 conventions + constraint framework
 └── Dictionary                     # dictionary model + YAML store
 ```
 
+The Cml classes ARE the model — every one is a
+`Lutaml::Model::Serializable` subclass with `attribute` declarations
+and an `xml do ... end` mapping block. lutaml-model handles XML
+parsing and serialization directly. There is no separate "canonical"
+layer and no translator.
+
 ### Schema-versioned wire classes (mirrors `mml` V3/V4 pattern)
 
 Both Schema 3 and Schema 2.4 have **real, distinct** class hierarchies
@@ -83,43 +90,41 @@ Chemicalml::Cml::Schema3.parse(xml)      # version-specific
 Chemicalml::Cml::Schema24.parse(xml)     # version-specific
 ```
 
-### The canonical model (`Chemicalml::Model::*`)
-
-Plain Ruby `Node` subclasses. **No XML, no JSON, no YAML**. Format-agnostic.
-Every adapter speaks this model; adapters never talk to each other directly.
-`Node` provides `accept(visitor)`, `value_attributes`, `children`, and
-class-level `short_name` so visitors written against the canonical model
-work across every adapter.
+### The CML model (`Chemicalml::Cml::*`)
 
-### The CML wire layer (`Chemicalml::Cml::*`)
+Every CML element is a `Lutaml::Model::Serializable` subclass — these
+ARE the model. lutaml-model is format-agnostic (XML/JSON/YAML/TOML
+via adapters), so the same class supports whatever serialization
+lutaml-model supports. Each class includes three mixins:
 
-Every CML element is a `Lutaml::Model::Serializable` subclass that
-includes three mixins: a `Base::*` module (shared declarations +
-xml mapping + `namespace Chemicalml::Cml::Namespace`), a
-`Role::*` marker module (type identity used by constraints and the
-translator — independent of which schema version's class it is), and
-`Cml::Visitable` (uniform interface for the constraint walker —
-`wire_children`, `node_id`, `element_name`).
+- a `Base::*` module (shared `attribute` declarations + `xml do ... end`
+  mapping block + `namespace Chemicalml::Cml::Namespace`)
+- a `Role::*` marker module (type identity used by constraints —
+  independent of which schema version's class it is)
+- `Cml::Visitable` (uniform interface for the constraint walker —
+  `wire_children`, `node_id`, `element_name`)
 
 Wire classes are generated in-place by each schema module from the
-shared `Chemicalml::Cml::Elements::ALL` table — no 70+ boilerplate
-files. Adding a new CML element = adding one entry to `Elements::ALL`,
-one `Base::*` mixin, and one `Role::*` module. Both `Schema3::*` and
-`Schema24::*` pick up the new element automatically (unless it's
-listed in `Elements::SCHEMA3_ONLY`).
+shared `Chemicalml::Cml::Elements::ALL` table — 121 entries spanning
+the entire Schema 3 XSD. Adding a new CML element = adding one entry
+to `Elements::ALL`, one `Base::*` mixin, and one `Role::*` module.
+Both `Schema3::*` and `Schema24::*` pick up the new element
+automatically unless it's listed in `Elements::SCHEMA3_ONLY`
+(currently `%i[AnyCml]` — the only element in Schema 3 that Schema 2.4
+lacks; verified by direct XSD diff).
+
+Schema 2.4 actually declares 137 elements (a superset of Schema 3 in
+most respects); 17 legacy elements (`alternative`, `annotation`,
+`appinfo`, `arg`, `complexObject`, `enumeration`, `expression`,
+`float`, `floatArray`, `integer`, `integerArray`, `operator`,
+`relatedEntry`, `string`, `stringArray`, `tcell`, `trow`) are
+Schema-2.4-only. Three of them (`annotation`, `appinfo`,
+`enumeration`) are explicitly modeled in `Elements::SCHEMA24_ONLY`
+because they carry semantic meaning; the rest are redundant with
+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.
-
-### The translator (`Chemicalml::Cml::Translator`)
-
-Pure transformation. `to_canonical(wire_doc)` accepts either Schema3
-or Schema24 wire documents (dispatches via `is_a?`).
-`from_canonical(model_doc, schema: :schema3)` produces the requested
-schema's wire format. It is the **only** place that imports both
-`Chemicalml::Model` and `Chemicalml::Cml`. Adding a new CML element
-means updating translator rules — the two namespaces stay decoupled.
+`def from_xml` / `def to_h` to these classes.
 
 ### Schema versions
 
@@ -172,9 +177,11 @@ These are non-negotiable and apply in addition to the user's global rules:
    or `respond_to?` for type checks.** Use `is_a?` or design the type
    hierarchy so the check isn't needed.
 
-5. **One concern, one place (MECE).** Adding a CML element = adding one
-   model class + one Cml class + one translator rule + specs. Don't
-   entangle them.
+5. **One concern, one place (MECE).** Adding a CML element = adding
+   one `Base::*` mixin + one `Role::*` module + one entry to
+   `Elements::ALL` + (if needed) one entry to `SCHEMA3_ONLY` or
+   `SCHEMA24_ONLY`. Both Schema3::* and Schema24::* pick it up
+   automatically.
 
 ## Reference docs (in-tree)
 

data/TODO.align/36-molecular-convention-coverage.md

@@ -0,0 +1,46 @@
+# 36 — Molecular convention: full upstream constraint coverage
+
+## Why
+
+`reference-docs/conventions/molecular.md` mandates more rules than the
+gem currently enforces. The walker framework already exists; this is
+purely additive constraint registration.
+
+## Current constraints (13)
+
+AtomArrayMustContainAtoms, AtomIdsUniqueWithinMolecule,
+BondMustReferenceAtomsInSameMolecule, AtomMustHaveId,
+AtomMustHaveElementType, BondMustHaveAtomRefs2, BondMustHaveOrder,
+MoleculeMustHaveId, AtomCoordinatesMustBePaired,
+PropertyMustHaveDictRef, ScalarMustHaveDataType,
+BondOrderShouldNotBeNumeric, AtomIdMustMatchPattern.
+
+## Missing rules per upstream spec
+
+- `count` attribute MUST NOT appear on top-level molecules (only on
+  children of another molecule).
+- `atomArray` — at most one per molecule; mutually exclusive with
+  child `<molecule>` elements.
+- `bondArray` — at most one per molecule; mutually exclusive with
+  child `<molecule>` elements.
+- `bondStereo` value `W` or `H` MUST have `atomRefs2`, MUST NOT have
+  `atomRefs4`.
+- `bondStereo` value `C` or `T` MUST have `atomRefs4`, MUST NOT have
+  `atomRefs2`.
+- `bondStereo` value `other` MUST have `dictRef`.
+- `bond` `id` MUST be unique within the eldest containing molecule.
+- `bond` with `order="other"` MUST have `dictRef`.
+- `atomArray` MUST be a child of `molecule` or `formula`.
+- `bondArray` MUST be a child of `molecule`.
+
+## Implementation
+
+Each rule → one Constraint subclass + `register` call in
+`lib/chemicalml/convention/molecular.rb`. New files autoloaded from
+`lib/chemicalml/convention/molecular/constraints.rb`.
+
+## Acceptance
+
+- 10 new constraint classes registered.
+- Per-class spec under `spec/chemicalml/convention/molecular/`.
+- Full suite still green.

data/TODO.align/37-compchem-convention-coverage.md

@@ -0,0 +1,55 @@
+# 37 — CompChem convention: full upstream constraint coverage
+
+## Why
+
+`reference-docs/conventions/compchem.md` defines a deep module
+structure (jobList → job → initialization/calculation/finalization/
+environment) and value-container rules. The gem currently ships only
+2 of the ~19 rules.
+
+## Current constraints (2)
+
+CompchemModuleMustContainJobList, JobMustContainInitialization.
+
+## Missing structural rules
+
+- `jobList` module MUST have `id` unique within compchem module.
+- `job` module MUST have `id` unique within compchem module.
+- `job` module MUST contain at most one `finalization`.
+- `job` module MUST contain at most one `environment`.
+- If a `calculation` is present in a `job`, a `finalization` MUST
+  also be present (co-constraint).
+- `initialization` module MUST NOT contain `property`/`propertyList`.
+- `initialization` module MUST NOT contain more than one `molecule`.
+- `initialization` module MUST NOT contain more than one
+  `parameterList`.
+- `finalization` module MUST NOT contain `parameter`/`parameterList`.
+- `finalization` module MUST NOT contain more than one `molecule`.
+- `finalization` module MUST NOT contain more than one `propertyList`.
+- `environment` module MUST NOT contain more than one `propertyList`.
+- `environment` module MUST NOT contain `parameter`/`parameterList`
+  directly.
+
+## Missing value-container rules
+
+- `scalar` with `dataType` `xsd:integer` or `xsd:double` MUST have
+  `units`.
+- `scalar` with `dataType` `xsd:string` MUST NOT have `units`.
+- `array` MUST have `size` ≥ 1; `dataType` MUST be integer or double;
+  MUST have `units`.
+- `matrix` MUST have `rows` ≥ 1 and `columns` ≥ 1; `dataType` MUST
+  be integer or double; MUST have `units`.
+
+## Implementation
+
+Use `DocumentConstraint` for cross-node rules (calculation→finalization
+co-constraint), `NodeConstraint` for single-node rules.
+
+CompChem modules are `<module dictRef="compchem:*">`. Match by
+`node.is_a?(Chemicalml::Cml::Role::Module)` then check `dict_ref`.
+
+## Acceptance
+
+- 17 new constraint classes registered.
+- Per-class spec under `spec/chemicalml/convention/compchem/`.
+- Full suite still green.

data/TODO.align/38-dictionary-convention-coverage.md

@@ -0,0 +1,34 @@
+# 38 — Dictionary convention: full upstream constraint coverage
+
+## Why
+
+`reference-docs/conventions/dictionary.md` requires namespace,
+definition children, id patterns, and unitType/units co-constraints.
+Currently 2 of 7 rules enforced.
+
+## Current constraints (2)
+
+EntryMustHaveIdAndTerm, EntryIdsUniqueWithinDictionary.
+
+## Missing rules
+
+- `dictionary` MUST have `namespace` attribute.
+- `dictionary` `namespace` SHOULD end with `/` or `#` (warning).
+- `entry` MUST contain a single `definition` child.
+- `entry` `id` MUST match `[A-Za-z][A-Za-z0-9._-]*`.
+- `entry` MUST have `unitType` attribute.
+- If `unitType` is `unknown`, `units` MUST NOT be present.
+- If `unitType` is `none`, `units` MUST be present and point to
+  `http://www.xml-cml.org/unit/si#none`.
+
+## Implementation
+
+New files under
+`lib/chemicalml/convention/dictionary/constraints/`, registered in
+`lib/chemicalml/convention/dictionary.rb`.
+
+## Acceptance
+
+- 7 new constraint classes registered.
+- Per-class spec under `spec/chemicalml/convention/dictionary/`.
+- Full suite still green.

data/TODO.align/39-unit-dictionary-convention-coverage.md

@@ -0,0 +1,33 @@
+# 39 — Unit-dictionary convention: full upstream constraint coverage
+
+## Why
+
+`reference-docs/conventions/unit-dictionary.md` requires 8 attributes
+on every `<unit>`. The gem currently ships 1 rule.
+
+## Current constraints (1)
+
+UnitMustHaveSymbolAndUnitType.
+
+## Missing rules
+
+- `unitList` MUST have `namespace` attribute.
+- `unit` MUST have `id` (unique within unitList — already implied by
+  pattern rules but enforce presence).
+- `unit` MUST have `title` attribute.
+- `unit` MUST have `parentSI` attribute.
+- `unit` MUST have at least one of `multiplierToSI` or `constantToSI`.
+- `unit` MUST contain a single `definition` child.
+- `unitList` MUST contain at least one `unit` child.
+
+## Implementation
+
+NodeConstraint subclasses. Register in
+`lib/chemicalml/convention/unit_dictionary.rb`.
+
+## Acceptance
+
+- 7 new constraint classes registered (some may consolidate with
+  existing UnitMustHaveSymbolAndUnitType).
+- Per-class spec under `spec/chemicalml/convention/unit_dictionary/`.
+- Full suite still green.

data/TODO.align/40-unit-type-dictionary-convention-coverage.md

@@ -0,0 +1,28 @@
+# 40 — UnitType-dictionary convention: full upstream constraint coverage
+
+## Why
+
+`reference-docs/conventions/unitType-dictionary.md` requires
+namespace, definition child, and id pattern. The gem ships 1 rule.
+
+## Current constraints (1)
+
+UnitTypeMustHaveIdAndName.
+
+## Missing rules
+
+- `unitTypeList` MUST have `namespace` attribute.
+- `unitType` MUST contain a single `definition` child.
+- `unitType` `id` MUST match `[A-Za-z][A-Za-z0-9._-]*`.
+- `unitTypeList` MUST contain at least one `unitType` child.
+
+## Implementation
+
+NodeConstraint subclasses. Register in
+`lib/chemicalml/convention/unit_type_dictionary.rb`.
+
+## Acceptance
+
+- 4 new constraint classes registered.
+- Per-class spec under `spec/chemicalml/convention/unit_type_dictionary/`.
+- Full suite still green.

data/TODO.align/41-expand-canonical-model-layer.md

@@ -0,0 +1,43 @@
+# 41 — Expand canonical Model layer for chemistry completeness
+
+## Why
+
+The canonical `Model::*` layer has 28 classes but the CML wire layer
+has 121. Many chemistry concepts (crystallography, spectroscopy,
+z-matrix, isotopes, samples, reaction schemes) have no canonical
+representation, forcing callers to use wire classes directly —
+breaking the "all adapters speak the canonical model" invariant.
+
+## New Model classes
+
+- `Model::Lattice` — `lattice_type`, `a/b/c/alpha/beta/gamma`,
+  children: cell_parameters, lattice_vectors
+- `Model::Crystal` — wraps lattice + scalar/array geometry
+- `Model::ZMatrix` — internal coordinates (atomRefs + lengths/angles)
+- `Model::Isotope` — number, spin, abundance, mass
+- `Model::IsotopeList` — collection
+- `Model::Sample` — sample metadata (state, amount, count)
+- `Model::Spectrum` — `id`, `title`, `dict_ref`, xaxis/yaxis,
+  spectrum_data
+- `Model::Peak` — `atomRefs`, `xValue`, `yValue`, `multiplicity`,
+  `peakShape`
+- `Model::PeakList` — collection
+- `Model::ReactionScheme` — `id`, `name`, reaction_step_list
+- `Model::ReactionStep` — `atoms`, `reactiveCentre`, `type`
+- `Model::Spectator` / `Model::SpectatorList`
+- `Model::MoleculeList` — collection (distinct from `molecule[]`)
+- `Model::Observation` — observation record
+
+## Implementation pattern
+
+Each class subclasses `Model::Node` and provides:
+- `attr_accessor` for every value
+- `initialize` with keyword args + sensible defaults
+- `children` returning child Model nodes
+- `value_attributes` returning the equality/hash snapshot
+
+## Acceptance
+
+- 14 new Model classes.
+- Per-class spec under `spec/chemicalml/model/`.
+- Full suite still green.

data/TODO.align/42-translator-wire-new-models.md

@@ -0,0 +1,31 @@
+# 42 — Wire new Model classes through the translator
+
+## Why
+
+New `Model::*` classes from TODO 41 are inert until the translator
+maps them to/from CML wire format.
+
+## Translator additions
+
+- `molecule_to_canonical`: include `crystal`, `spectra`,
+  `spectra_lists`, `z_matrix`, `isotope_list`, `sample` fields.
+- `molecule_from_canonical`: reverse of above.
+- New helpers: `crystal_to/from_canonical`,
+  `lattice_to/from_canonical`, `spectrum_to/from_canonical`,
+  `peak_to/from_canonical`, `z_matrix_to/from_canonical`,
+  `isotope_to/from_canonical`, `sample_to/from_canonical`,
+  `reaction_scheme_to/from_canonical`, `spectator_to/from_canonical`.
+- `module_to_canonical`: stop hardcoding `lists: []` — collect
+  `<list>` children into Model::List collection.
+
+## Implementation
+
+All schema-aware (take `schema:` keyword). Use `WireClassRegistry`
+for every wire class lookup. Add to existing
+`translator.rb` + `translator/value_translations.rb`.
+
+## Acceptance
+
+- Round-trip spec: parse CML with crystal/spectrum/zMatrix →
+  Model → serialize → same CML (canon-compared).
+- Full suite still green.

data/TODO.align/43-dictionary-model-no-to-h.md

@@ -0,0 +1,39 @@
+# 43 — Refactor Dictionary::Model away from hand-rolled `to_h`
+
+## Why
+
+`lib/chemicalml/dictionary/model.rb`, `entry.rb`, `enum.rb`, `link.rb`
+define `def to_h` — hand-rolled serialization. The project's coding
+standard #2 forbids this. The Loader uses `to_h` to round-trip YAML,
+but the canonical Model layer uses `value_attributes` for the same
+purpose. Align Dictionary with the rest of the codebase.
+
+## Current state
+
+```ruby
+class Model
+  def to_h
+    { namespace: ..., prefix: ..., title: ...,
+      description: ..., entries: entries.map(&:to_h) }
+  end
+end
+```
+
+Same pattern in Entry, Enum, Link.
+
+## Target
+
+- Drop `def to_h`.
+- `value_attributes` returns the same shape (used by Loader to dump
+  YAML, by `==`/`hash` for equality).
+- Loader's `dump_to_hash` calls `model.value_attributes`.
+
+If Loader needs a specific YAML shape (string keys vs symbol keys),
+add a thin `as_yaml` adapter — but the model itself only exposes
+`value_attributes`.
+
+## Acceptance
+
+- No `def to_h` / `to_hash` anywhere in `lib/chemicalml/dictionary/`.
+- Loader round-trip still works (specs pass).
+- Full suite still green.

data/TODO.align/44-schema3-only-and-schema24-module.md

@@ -0,0 +1,44 @@
+# 44 — Fix SCHEMA3_ONLY and add Schema24 Module class
+
+## Why
+
+Actual XSD diff (via `grep '<xsd:element name='`):
+
+- Schema3 has **121** elements. Our `Elements::ALL` matches.
+- Schema24 has **137** elements (a superset of Schema3 for most parts).
+- **`anyCml` is in Schema3 but NOT Schema24** → must be in
+  `SCHEMA3_ONLY`.
+- `module` is in BOTH schemas → currently listed in SCHEMA3_ONLY
+  is **wrong**.
+
+Current `SCHEMA3_ONLY = %i[Module]` is incorrect and Schema24 is
+missing its `cml_module.rb` wire class entirely.
+
+## Fix
+
+1. `lib/chemicalml/cml/elements.rb`:
+   `SCHEMA3_ONLY = %i[AnyCml].freeze`
+2. Create `lib/chemicalml/cml/schema24/cml_module.rb` mirroring
+   `schema3/cml_module.rb`.
+3. Update Schema24 autoload list to include `cml_module`.
+4. Update translator comment ("Schema 3 only — Schema 2.4 lacks
+   `<module>`") — no longer accurate.
+5. Verify Schema24 Configuration registers Module.
+
+## Schema24-only elements (not modeled yet)
+
+Schema24 has 16 elements not in Schema3: alternative, annotation,
+appinfo, arg, complexObject, enumeration, expression, float,
+floatArray, integer, integerArray, operator, relatedEntry, string,
+stringArray, tcell, trow.
+
+These are Schema-2.4-only legacy elements. They're outside the
+gem's current scope (the gem focuses on Schema 3 + intersection).
+Document them in CLAUDE.md so future contributors know.
+
+## Acceptance
+
+- SCHEMA3_ONLY = %i[AnyCml].
+- Schema24::CmlModule wire class exists, parses, serializes.
+- Translator's module_from_canonical works for schema24.
+- Full suite still green.

data/TODO.align/45-documentation-and-final-verification.md

@@ -0,0 +1,23 @@
+# 45 — Documentation cleanup and final spec verification
+
+## Why
+
+Stale comments and docs rot fast. After TODOs 36–44 land, sweep the
+codebase for outdated references and run the full suite end-to-end.
+
+## Updates
+
+- `lib/chemicalml/cml.rb`: comment says "All 36 aliases load from a
+  single file" — actually 121 now.
+- `CLAUDE.md`: refresh any counts (121 elements, ~45 constraints,
+  14 model classes added, etc.).
+- `CLAUDE.md`: note Schema24-only legacy elements not modeled.
+- Verify `bundle exec rspec` is fully green.
+- Verify `bundle exec rubocop` is clean (or autocorrect what's
+  safe).
+
+## Acceptance
+
+- All counts in docs match the actual codebase.
+- Full rspec suite passes.
+- Rubocop reports no new offenses.

data/TODO.align/46-lattice-vector-content.md

@@ -0,0 +1,24 @@
+# 46 — Fix LatticeVector content attribute
+
+## Why
+
+`<latticeVector>1 0 0</latticeVector>` carries vector components as
+element content. `lib/chemicalml/cml/base/lattice_vector.rb` declares
+only id/title/dictRef/convention/units — **no content attribute**.
+The translator's workaround maps `lv.content` ↔ wire `units` —
+semantically wrong (units ≠ vector components).
+
+## Fix
+
+1. Add `attribute :content, :string` + `map_content` to Base::LatticeVector.
+2. Update Model::LatticeVector to carry `units` and `content` as
+   independent fields.
+3. Update translator `lattice_vector_to/from_canonical` to map both.
+4. Spec round-trip.
+
+## Acceptance
+
+- `<latticeVector units="unit:nm">1 0 0</latticeVector>` round-trips
+  with units and content preserved.
+- Translator spec covers the fix.
+- Full suite green.

data/TODO.align/47-molecule-crystal-spectra-property-lists.md

@@ -0,0 +1,23 @@
+# 47 — Wire Molecule#crystal/spectra/property_lists through translator
+
+## Why
+
+`Base::Molecule` declares `crystal`, `spectra`, `property_lists`
+children, but `Model::Molecule` doesn't have those fields and
+`molecule_to_canonical/from_canonical` silently drops them. Silent
+data loss.
+
+## Fix
+
+1. Add `crystal`, `spectra`, `property_lists` accessors to
+   `Model::Molecule`.
+2. Wire through `molecule_to_canonical` (read wire, build Model) and
+   `molecule_from_canonical` (read Model, build wire).
+3. Update `Model::Molecule#children` and `#value_attributes`.
+4. Spec round-trip with a molecule containing crystal + propertyList.
+
+## Acceptance
+
+- A molecule with `<crystal>` and `<propertyList>` children round-trips
+  through canonical without loss.
+- Full suite green.

data/TODO.align/48-model-list-and-module-lists.md

@@ -0,0 +1,21 @@
+# 48 — Add Model::List and wire Module#lists
+
+## Why
+
+`Model::Module` has a `lists` accessor but `module_to_canonical`
+hardcodes `lists: []`. There is no `Model::List` canonical class, so
+wire `<list>` children of `<module>` are silently dropped.
+
+## Fix
+
+1. Add `Model::List` mirroring `Base::List` shape: id/title/dictRef/
+   convention + scalar/array/matrix/list children.
+2. Wire `module_to_canonical` to map `wire_module.lists` (drop the
+   hardcoded `[]`).
+3. Wire `module_from_canonical` reverse.
+4. Spec round-trip.
+
+## Acceptance
+
+- A `<module>` containing a `<list>` child round-trips without loss.
+- Full suite green.

data/TODO.align/49-more-chemistry-models.md

@@ -0,0 +1,34 @@
+# 49 — Add more chemistry Model classes
+
+## Why
+
+Several chemically-meaningful CML elements still lack canonical Model
+classes, forcing callers to use wire classes directly and breaking the
+"all adapters speak canonical" invariant.
+
+## New Model classes
+
+- `Model::Torsion` — `<torsion>` (4-atom dihedral)
+- `Model::Angle` — `<angle>` (3-atom angle)
+- `Model::Length` — `<length>` (2-atom distance)
+- `Model::Action` / `Model::ActionList` — `<action>` / `<actionList>`
+- `Model::Map` — `<map>` (atom mapping across reaction)
+- `Model::Fragment` / `Model::FragmentList` — substructure references
+- `Model::ReactionStepList` — list of `<reactionStep>`
+- `Model::ReactiveCentre` — `<reactiveCentre>`
+- `Model::TransitionState` — `<transitionState>`
+- `Model::PeakGroup` — `<peakGroup>`
+- `Model::SpectrumList` — `<spectrumList>`
+- `Model::SpectrumData` — `<spectrumData>`
+- `Model::Region` — `<region>`
+
+## Wire translator mappings
+
+For each new Model class, add `*_to_canonical` / `*_from_canonical`
+helpers. Most are simple (id/title/dictRef/convention).
+
+## Acceptance
+
+- Each new Model class has instantiation + value_attributes specs.
+- Translator mappings round-trip.
+- Full suite green.