chemicalml 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 74eb61f89b283d3263aa4ead18e9b76061700defcc54232002855af6b1291c0a
-  data.tar.gz: 228f8f704086b458a73b3f4cb679b25133cf5ee36aa16d58c688a6439abb1974
+  metadata.gz: ed7130181d6d55cbadb29d2630668ab4f16746f10dc20db9c9d1d0ff066586c6
+  data.tar.gz: ac78d79e906862aa42639b2d237ec66661a8c3061e4b25c04535f8941520b3d3
 SHA512:
-  metadata.gz: ba13a979cce6d48bbef181917107ac9ad24291131e8568652a012698c5e3ebe7f43851f908408478e4b4481d270cb9b83371d9c3f19093700df19a97565af2a9
-  data.tar.gz: 8557d650ab706936b25031541e256e840cc638d025d5c4b7308a512aa46e27d4223a050ba27b37c7d9c5408c1b1dd7af4974697699af317fec17a3ecfa262f92
+  metadata.gz: 5909cc1b258048f0c5aefba5844fff9136f2db4713d5cd5b80a22c07045e60a5ee5ead34680a841a9044039824c76cd4913d48d8f3410f86bf99b043f5739ba4
+  data.tar.gz: ff4f54de5ce734ae649554f593cfc1affa766b7e541fef394704bcd1b4d192dbae3e788241ced6a4dc6306bacf62b409fad2fdafe6861617497d7ff2ced16dee

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/.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`
@@ -33,23 +36,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 +93,50 @@ 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.
+`def from_xml` / `def to_h` to these classes.
 
-### The translator (`Chemicalml::Cml::Translator`)
+### JSON / YAML wire names
 
-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.
+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
 
@@ -127,11 +144,20 @@ means updating translator rules — the two namespaces stay decoupled.
 (`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
@@ -143,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`,
@@ -172,9 +225,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/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/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.