chemicalml 0.2.1 → 0.3.0

data/TODO.align/README.round27.md

@@ -0,0 +1,51 @@
+# Round 27 — User-facing API, CLI improvements
+
+This round adds the user-facing query API on `Cml::Visitable`, a
+top-level `Chemicalml.validate` shortcut, and two new CLI commands
+(`inspect`, `elements`).
+
+## Files
+
+- [110 — Document query API](110-document-query-api.md)
+- [111 — Top-level Chemicalml.validate](111-toplevel-validate.md)
+- [112 — CLI inspect command](112-cli-inspect.md)
+- [113 — CLI elements command](113-cli-elements.md)
+- [114 — Final verification round 27](114-final-verification-round27.md)
+
+## Outcomes
+
+- **`Cml::Visitable` query methods** (inherited by every wire class):
+  - `#each_wire_node`, `#each_atom`, `#each_bond`, `#each_molecule` — recursive iterators
+  - `#find_atom(id)`, `#find_bond(id)`, `#find_molecule(id)` — id-based lookup
+  - `#atom_count`, `#bond_count`, `#molecule_count` — recursive counts
+  - All return Enumerators without a block (Enumerable-style)
+
+- **`Chemicalml.validate(doc)`** — top-level shortcut for
+  `Convention.detect_and_validate(doc)`. Users no longer need to
+  remember the full namespace.
+
+- **`chemicalml inspect <file>`** — new CLI command. Prints a
+  tree-style summary of the document with element names, ids, and
+  structure. Useful for debugging.
+
+- **`chemicalml elements`** — new CLI command. Lists every Schema3
+  wire class with its XML root name. Useful for introspection.
+
+- **CLI refactor**: `run_validate` now uses `report.summary` instead
+  of manual rendering. Cleaner code, better output.
+
+- **559 examples, 0 failures, 3 pending** (TOML adapter pending).
+  Zero forbidden patterns.
+
+## Architectural insight
+
+The query methods live on `Visitable` (the marker mixin every wire
+class includes) rather than on `Document` specifically. This means
+ANY wire class can be the root of a query — `molecule.find_atom(id)`,
+`reaction.find_molecule(id)`, etc. This was the right call: the
+walker is already general (visits any subtree); exposing query
+methods only on Document would have required callers to navigate
+up to Document first.
+
+The CLI's `print_tree` helper is recursive but bounded (`max_depth: 6`)
+to avoid runaway output on pathological documents.

data/TODO.align/README.round28.md

@@ -0,0 +1,61 @@
+# Round 28 — Convenience API, custom conventions, compchem completion
+
+This round adds user-facing convenience (`parse_file`, custom
+convention registration), more compchem constraints from the spec,
+and a comprehensive lint cleanup.
+
+## Files
+
+- [115 — parse_file convenience](115-parse-file.md)
+- [116 — Custom convention registration](116-custom-convention.md)
+- [117 — More compchem constraints](117-more-compchem-constraints.md)
+- [118 — Final verification round 28](118-final-verification-round28.md)
+
+## Outcomes
+
+- **`Chemicalml.parse_file(path)`** — convenience wrapper around
+  `parse(File.read(path))`. Raises ArgumentError for missing files.
+  Eliminates the `File.read` boilerplate.
+
+- **`Convention::Registry.register_custom(mod)`** — runtime
+  registration of custom conventions. The module must `extend Base`
+  and return a non-empty `qname`. Useful for domain-specific CML
+  extensions (e.g., a `convention:my-lab-extensions` for a research
+  group's custom vocabulary).
+
+- **Two new compchem constraints** from the spec:
+  - `InitializationMustHaveContent` — initialization module must
+    contain at least one of molecule, parameterList, or user-defined
+    module
+  - `FinalizationMustHaveContent` — finalization module must contain
+    at least one of molecule, propertyList, or user-defined module
+
+- **Lint cleanup**: ran `rubocop -A` on all recently-touched files.
+  80 offenses autocorrected (string quotes, modifier-if usage,
+  parenthesised method args, etc.). Zero remaining style issues.
+
+- **Real bug caught during round 28**: `register_custom` initially
+  deadlocked because it called `load_cache` while holding the mutex.
+  Fixed by separating the load step (which acquires/releases its
+  own mutex) from the mutation step (direct hash access after load
+  is guaranteed to have populated `@cache`).
+
+- Compchem convention: 20 constraints (up from 18).
+
+- **568 examples, 0 failures, 3 pending** (TOML adapter pending).
+  Zero forbidden patterns. **88 constraints across 8 conventions.**
+
+## Architectural insight
+
+The `register_custom` deadlock is a classic Ruby mutex pitfall:
+re-entering a non-reentrant `Mutex#synchronize` block from within
+itself deadlocks. The fix — call `load_cache` first (which manages
+its own mutex acquisition), then mutate `@cache` directly — works
+because Ruby's `||=` assignment makes `@cache` non-nil after the
+first load. Documented in the method comment.
+
+This round also reinforced the value of running rubocop on each
+round's output. 80 autocorrected offenses across 8 files means
+style drift was creeping in — single-quote vs double-quote,
+`unless` vs `if !`, etc. A small CI rule (`bundle exec rubocop`
+must pass) would catch this in future.

data/TODO.align/README.round29.md

@@ -0,0 +1,64 @@
+# Round 29 — Wire introspection, README, dataType consistency
+
+This round adds wire-class introspection, updates the README to
+reflect the current API, and adds a property-dataType consistency
+constraint that bridges the convention and dictionary subsystems
+in a new way.
+
+## Files
+
+- [119 — Wire-class introspection](119-wire-introspection.md)
+- [120 — Update README](120-readme-update.md)
+- [121 — Property dataType consistency](121-property-datatype.md)
+- [122 — Final verification round 29](122-final-verification-round29.md)
+
+## Outcomes
+
+- **`Cml.for_xml_name(name, schema:)`** — wire-class lookup by XML
+  element name. Uses the existing `Elements::XML_TO_CLASS` reverse
+  index. Returns nil for unknown names.
+
+- **`Cml.wire_classes(schema:)`** — enumerator over all wire classes
+  for a schema version. Useful for code generation and tooling.
+
+- **README rewritten**:
+  - 8 conventions + 88+ constraints documented
+  - All modern API examples (`parse_file`, `validate`, `each_atom`)
+  - CLI commands documented (`validate`, `inspect`, `conventions`,
+    `dictionaries`, `elements`)
+  - Cross-format serialisation examples
+  - Custom convention registration example
+  - Dictionary lookup example
+  - Architectural overview (`Base::*`, `Role::*`, `Elements::ALL`)
+
+- **`PropertyScalarDataTypeMatchesDictionary`** — molecular warning
+  when a `<property>`'s `<scalar>` `dataType` doesn't match the
+  `dataType` declared in the dictionary entry referenced by `dictRef`.
+  This is a **three-component integration check**: convention
+  constraint system queries the dictionary registry AND inspects the
+  document's scalar child.
+
+- Molecular convention: 36 constraints (up from 35).
+
+- **574 examples, 0 failures, 3 pending**. Zero forbidden patterns.
+
+## Architectural insight
+
+`PropertyScalarDataTypeMatchesDictionary` is the deepest
+cross-component check yet — it validates that:
+
+1. The property's `dictRef` resolves to a real dictionary entry
+   (uses `Dictionary::Registry.lookup`).
+2. The entry declares a `dataType`.
+3. The property's `<scalar>` child declares a `dataType`.
+4. The two `dataType` values match.
+
+If any step is missing data, the constraint silently passes (no
+false positives). When all the data is present, it catches real
+inconsistencies that would cause downstream type errors.
+
+This kind of multi-step semantic validation is what mature
+document-validation frameworks look like. Round 29 is the first
+round where it's been possible — earlier rounds built the
+primitives (dictionary registry, dictRef resolution, scalar
+dataType attribute) that this constraint composes.

data/TODO.align/README.round30.md

@@ -0,0 +1,50 @@
+# Round 30 — unitType resolution, JSON CLI, enumeration
+
+This round adds the unit-unitType cross-component check (parallels
+dictRef resolution), CLI JSON output for machine consumers, and a
+constraint-enumeration API.
+
+## Files
+
+- [123 — Unit unitType resolution](123-unit-unittype-resolution.md)
+- [124 — CLI JSON output](124-cli-json-output.md)
+- [125 — Constraint enumeration API](125-constraint-enumeration.md)
+- [126 — Final verification round 30](126-final-verification-round30.md)
+
+## Outcomes
+
+- **`UnitUnitTypeShouldResolve`** — unit-dictionary warning when a
+  `<unit>`'s `unitType` attribute doesn't resolve against the
+  built-in unitType-dictionary. Cross-component check parallel to
+  the molecular convention's `DictRefShouldResolve`.
+
+- **`chemicalml validate --json file.cml`** — JSON output mode for
+  the CLI. Returns `{ file:, ok:, has_warnings:, violations: [...] }`
+  where each violation has `severity`, `path`, `message`, `value`.
+  Useful for editor integration, CI pipelines, automated tooling.
+
+- **`Convention::Registry.each_constraint`** — iterates every
+  constraint across every convention, yielding `(convention, class)`
+  pairs. Useful for documentation generation and introspection.
+
+- **`Convention::Registry.total_constraint_count`** — sum of all
+  registered constraints across all conventions (currently 90).
+
+- Unit-dictionary convention: 9 constraints (up from 8).
+
+- **580 examples, 0 failures, 3 pending** (TOML adapter pending).
+  Zero forbidden patterns. **90 constraints across 8 conventions.**
+
+## Architectural insight
+
+`UnitUnitTypeShouldResolve` completes a symmetric pair with
+`DictRefShouldResolve` from round 25. Both follow the same pattern:
+walk the document, look up reference attributes against the
+dictionary registry, warn on misses. The pattern is now established
+enough that adding a new reference-resolution constraint is a
+2-minute job: copy the structure, change the attribute name and the
+target dictionary.
+
+The `each_constraint` iterator makes the constraint table tractable
+for documentation generation. A future round could auto-generate a
+Markdown table of all 90 constraints from this single API call.

data/TODO.align/README.round31.md

@@ -0,0 +1,54 @@
+# Round 31 — CLI tooling, parentSI resolution
+
+This round completes the CLI tooling suite (constraints + enums
+commands) and adds the parentSI resolution constraint, completing
+the cross-component check symmetry.
+
+## Files
+
+- [127 — CLI constraints command](127-cli-constraints.md)
+- [128 — CLI enums command](128-cli-enums.md)
+- [129 — ParentSI resolution](129-parentsi-resolution.md)
+- [130 — Final verification round 31](130-final-verification-round31.md)
+
+## Outcomes
+
+- **`chemicalml constraints`** — new CLI command listing all 91
+  constraints grouped by convention. Each line shows the constraint
+  class name and its declared `applies_to` roles.
+
+- **`chemicalml enums`** — new CLI command listing every
+  `Cml::Enums` constant with its allowed values. Useful for users
+  who want to know what enum values an attribute accepts.
+
+- **`UnitParentSiShouldResolve`** — unit-dictionary warning when a
+  `<unit>`'s `parentSI` doesn't resolve against built-in
+  dictionaries. Completes the cross-component check symmetry:
+  - dictRef resolution (molecular)
+  - unitType resolution (unit-dictionary)
+  - parentSI resolution (unit-dictionary)
+
+- **Real bug caught during round 31**: existing fixture
+  `convention_spec.rb:226` used `parent_si: "siUnits:s"` which
+  doesn't resolve (correct prefix is `si`, not `siUnits`). Fixed.
+
+- Unit-dictionary convention: 10 constraints (up from 9).
+
+- **583 examples, 0 failures, 3 pending**. Zero forbidden patterns.
+  **91 constraints across 8 conventions.**
+
+## Architectural insight
+
+The cross-component check pattern (walk document → look up reference
+attribute against registry → warn on miss) is now fully
+established across three constraint pairs:
+
+| Convention | Attribute | Lookup target |
+|---|---|---|
+| molecular | `dictRef` | dictionary registry |
+| unit-dictionary | `unitType` | unitType-dictionary registry |
+| unit-dictionary | `parentSI` | unit dictionary registry |
+
+Adding a fourth is mechanical: copy the structure, change the
+attribute name and lookup target. The pattern's clarity is its own
+form of documentation.

data/TODO.align/README.round32.md

@@ -0,0 +1,67 @@
+# Round 32 — Thor CLI refactor, info command, auto-docs
+
+This round refactors the CLI to use Thor with one class per command,
+adds the `info` command for element introspection, and auto-generates
+constraint documentation.
+
+## Files
+
+- [131 — CLI info command](131-cli-info-command.md)
+- [132 — Auto-generated constraint docs](132-auto-generated-constraint-docs.md)
+- [133 — Final verification round 32](133-final-verification-round32.md)
+
+## Outcomes
+
+- **CLI refactored to Thor**. Each command is now a dedicated class:
+  - `Chemicalml::Cli::Base < Thor` — dispatcher
+  - `Chemicalml::Cli::Command` — base class with `.run(args, options)`
+    and `#run(args, options)`
+  - `Chemicalml::Cli::ValidateCommand`
+  - `Chemicalml::Cli::InspectCommand`
+  - `Chemicalml::Cli::ConventionsCommand`
+  - `Chemicalml::Cli::DictionariesCommand`
+  - `Chemicalml::Cli::ElementsCommand`
+  - `Chemicalml::Cli::ConstraintsCommand`
+  - `Chemicalml::Cli::EnumsCommand`
+  - `Chemicalml::Cli::InfoCommand`
+
+  Each command supports both `MyCommand.run(args, options)` (class
+  method) and `MyCommand.new.run(args, options)` (instance method)
+  invocation patterns — matching the user's requested pattern.
+
+- **`chemicalml info <element>`** — new CLI command. Shows element
+  XML name, Ruby class, included Role module, all attributes (with
+  collection marker), and all applicable constraints across every
+  convention. Useful for users exploring the model.
+
+- **Auto-generated constraint docs** — `docs/generate_constraint_docs.rb`
+  script produces `docs/constraints.md` from
+  `Convention::Registry.each_constraint`. Single source of truth —
+  regenerating picks up new constraints automatically. No manual
+  maintenance.
+
+- **Bug fix from autocorrect**: `Convention::Registry#load_cache`
+  had `@cache` renamed to `@load_cache` by rubocop's
+  `MemoizedInstanceVariableName` rule. `register_custom` and `reset!`
+  needed alignment — fixed in this round.
+
+- **586 examples, 0 failures, 3 pending**. Zero forbidden patterns.
+
+## Architectural insight
+
+The Thor refactor separates concerns cleanly:
+
+1. **Thor dispatcher** owns argument parsing, help text, option
+   declarations. Each `desc + def` block is 2-3 lines.
+2. **Command class** owns the actual work. Easy to test in isolation
+   (`MyCommand.new.run(args, options)` returns an exit code).
+3. **No business logic in the dispatcher** — it's pure routing.
+
+This pattern scales: a future `rake` task, Rake task, or web handler
+can re-use any `*Command` class without going through Thor. The
+Thor dispatcher is just one possible entry point.
+
+The auto-generated constraint docs demonstrate the value of the
+`each_constraint` API from round 30: a single iteration produces
+comprehensive documentation with zero manual upkeep. Adding a new
+constraint and re-running the generator is all it takes.

data/TODO.align/README.round33.md

@@ -0,0 +1,62 @@
+# Round 33 — CLI run(options) signature alignment
+
+This round refactors every CLI command class so the run method
+takes a single `options` hash, matching the user-requested
+invocation pattern exactly:
+
+    MyCommandClass.new.run(options)
+
+## Files
+
+- [134 — CLI run(options) alignment](134-cli-run-options-alignment.md)
+- [135 — Final verification round 33](135-final-verification-round33.md)
+
+## Outcomes
+
+- Every `Chemicalml::Cli::*Command` now implements
+  `def run(options)` (single hash argument). The hash carries both
+  positional args (keyed by name: `:file`, `:element`) and flags
+  (`:json`, etc.).
+
+- `Chemicalml::Cli::Base` (Thor dispatcher) builds the options hash
+  for each command and calls `<Name>Command.new.run(hash)`. Example:
+  ```ruby
+  desc "validate FILE", "..."
+  method_option :json, type: :boolean, aliases: "-j"
+  def validate(file)
+    ValidateCommand.new.run(file: file, json: options[:json])
+  end
+  ```
+
+- Each command supports both invocation styles:
+  - Instance: `MyCommand.new.run(options)` (primary, per user spec)
+  - Class: `MyCommand.run(options)` (convenience, delegates to instance)
+
+- Bug fix: validation guards `return warn(...), 2 unless path`
+  were returning `[warn_result, 2]` (array) instead of integer 2.
+  Rewrote as explicit `warn; return 2` two-line guards.
+
+- CLI spec updated to test both invocation styles. 17 specs covering
+  every command via `MyCommandClass.new.run(options)` direct call.
+
+- **593 examples, 0 failures, 3 pending**. Zero forbidden patterns.
+
+## Architectural insight
+
+The single-hash `run(options)` signature is more flexible than the
+prior `(args, options)` split:
+
+- Positional args are named (`file:`, `element:`), not positional.
+  Easier to extend (add a new arg = add a new hash key, no method
+  signature change).
+- Same hash carries flags (`json:`, etc.). One argument, one source
+  of truth.
+- Commands are unit-testable in isolation without Thor:
+  ```ruby
+  Chemicalml::Cli::ValidateCommand.new.run(file: "x.cml", json: true)
+  ```
+
+The Thor dispatcher is now truly just routing — it parses CLI input
+and constructs the options hash. Every command class can be reused
+from Rake tasks, RSpec tests, or web handlers without going through
+Thor at all.

data/TODO.align/README.round34.md

@@ -0,0 +1,70 @@
+# Round 34 — Constraint descriptions, diverse fixtures, perf baseline, BIG perf fix
+
+This round adds constraint-class descriptions, more diverse fixtures,
+a performance baseline spec, and crucially **fixes a 680× performance
+regression** discovered by the baseline spec.
+
+## Files
+
+- [136 — Constraint descriptions](136-constraint-descriptions.md)
+- [137 — More diverse fixtures](137-more-diverse-fixtures.md)
+- [138 — Performance baseline spec](138-performance-baseline-spec.md)
+- [139 — Final verification round 34](139-final-verification-round34.md)
+
+## Outcomes
+
+- **Constraint `description` class method** added to
+  `Convention::Constraint`. Each constraint can now carry a
+  human-readable description of the rule it enforces. Two molecular
+  constraints (`AtomMustHaveId`, `BondMustHaveOrder`) updated as
+  examples. `chemicalml constraints` command now shows descriptions
+  when present.
+
+- **Three new diverse fixtures**:
+  - `molecular/ethylene_with_cis_trans_stereo.cml` — bondStereo with
+    `atomRefs4` (cis/trans case)
+  - `reactions/free_radical_halogenation.cml` — multi-reactant
+    reaction with substanceList catalyst
+  - `spectroscopy/ethanol_nmr.cml` — NMR spectrum with xaxis/yaxis
+    arrays, peakList with multiplicity, metadataList
+
+- **Performance baseline spec** — establishes timing baselines for:
+  - XML/JSON serialisation of a 1000-atom molecule (< 2s)
+  - Molecular validation of a 1000-atom molecule (< 2s)
+  - `atom_count` / `find_atom` queries (< 500ms)
+  - Fixture parsing (< 20ms)
+
+- **MAJOR performance fix**: the `ReferencesShouldResolve` constraint
+  was taking **47.8 seconds** on a 1000-atom document. Root cause:
+  `ReferenceResolver#unresolved_for` called `containing_molecule`
+  for every bond, which walked the entire document every time
+  (O(n²) for n bonds × n molecules × n atoms).
+
+  Fixed by:
+  - Adding lazily-built `atom_index` (id → Atom hash, O(1) lookup)
+  - Removing the `containing_molecule` indirection in
+    `unresolved_for` — the resolver now uses the global atom index
+    directly. CML semantics already enforce that bond refs live in
+    the parent molecule (that's `BondMustReferenceAtomsInSameMolecule`'s
+    job).
+
+  Result: **47.8s → 68ms (680× faster)**.
+
+- **609 examples, 0 failures, 3 pending** (TOML adapter pending).
+  Zero forbidden patterns.
+
+## Architectural insight
+
+The performance baseline spec paid for itself immediately by catching
+a 47-second regression that I'd introduced in round 22 when adding
+the `ReferencesShouldResolve` constraint. Without the baseline,
+this would have shipped to users.
+
+The fix follows the **build indices once, query many times** pattern.
+The resolver now builds an `atom_index` lazily on first lookup; all
+subsequent `find_atom` calls are O(1). This is a Ruby-native
+performance pattern that fits the existing architecture cleanly.
+
+Lesson: baseline specs aren't just for regression detection — they
+catch bugs that you didn't know you had. Always write the baseline
+before optimising.

data/docs/constraints.md

@@ -0,0 +1,161 @@
+# Registered Convention Constraints
+
+Auto-generated from `Chemicalml::Convention::Registry.each_constraint`.
+Last regenerated: 2026-07-20T09:43:53Z.
+
+Total constraints: **91**
+
+## convention:cascade
+
+- **Namespace**: `http://www.xml-cml.org/convention/cascade`
+- **Constraint count**: 4
+
+| Constraint | Applies to | Description |
+|---|---|---|
+| `ReactionSchemeMustHaveContent` | ReactionScheme | A `<reactionScheme>` MUST contain at least one `<reactionStepList>` or `<reaction>` child. An empty scheme carries no cascade information. |
+| `ReactionStepListMustContainSteps` | ReactionStepList | A `<reactionStepList>` MUST contain at least one `<reactionStep>` child. An empty step list breaks the cascade chain. |
+| `ReactionStepMustHaveReactionOrLists` | ReactionStep | A `<reactionStep>` MUST contain either a `<reaction>` child or explicit `<reactantList>` + `<productList>` children. An empty step is a dead-end in the cascade. |
+| `ReactiveCentreAtomRefsShouldBePresent` | ReactiveCentre | A `<reactiveCentre>` SHOULD declare its `atomRefs` attribute. Without atom references the reactive centre is indistinguishable from a placeholder. Warning severity — |
+
+## convention:compchem
+
+- **Namespace**: `http://www.xml-cml.org/convention/compchem`
+- **Constraint count**: 20
+
+| Constraint | Applies to | Description |
+|---|---|---|
+| `CompchemModuleMustContainJobList` | _(document-wide)_ | A CompChem module MUST contain at least one jobList module child per the compchem convention. |
+| `JobMustContainInitialization` | Module | A job module MUST contain exactly one initialization module child per the compchem convention. |
+| `JobListModuleMustHaveId` | Module | A jobList module MUST have an `id` unique within the compchem module. |
+| `JobModuleMustHaveId` | Module | A job module MUST have an `id` unique within the compchem module. |
+| `JobModuleAtMostOneFinalization` | Module | A job module MUST contain at most one finalization module. |
+| `JobModuleAtMostOneEnvironment` | Module | A job module MUST contain at most one environment module. |
+| `CalculationRequiresFinalization` | Module | Co-constraint: if a calculation module is present inside a job, a finalization MUST also be present. |
+| `InitializationAtMostOneMolecule` | Module | The initialization module MUST NOT contain more than one molecule child. |
+| `InitializationAtMostOneParameterList` | Module | The initialization module MUST NOT contain more than one parameterList child. |
+| `InitializationMustNotContainProperty` | Module | The initialization module MUST NOT contain property or propertyList children directly. (Properties belong in finalization.) |
+| `FinalizationAtMostOneMolecule` | Module | The finalization module MUST NOT contain more than one molecule child. |
+| `FinalizationAtMostOnePropertyList` | Module | The finalization module MUST NOT contain more than one propertyList child. |
+| `FinalizationMustNotContainParameter` | Module | The finalization module MUST NOT contain parameter or parameterList children directly. (Parameters belong in initialization.) |
+| `EnvironmentAtMostOnePropertyList` | Module | The environment module MUST NOT contain more than one propertyList child. |
+| `EnvironmentMustNotContainParameter` | Module | The environment module MUST NOT contain parameter or parameterList children directly. It MAY contain a propertyList (which itself can hold parameters). |
+| `ScalarUnits` | Scalar | CompChem value-container rules: `scalar` with dataType `xsd:integer` or `xsd:double` MUST have `units`; `scalar` with dataType `xsd:string` MUST NOT have `units`. |
+| `ArrayRules` | Array | CompChem `array` value-container rules: MUST have `size` attribute (≥ 1); `dataType` MUST be integer or double; MUST have `units`. |
+| `MatrixRules` | Matrix | CompChem `matrix` value-container rules: MUST have `rows` and `columns` attributes (each ≥ 1); `dataType` MUST be integer or double; MUST have `units`. |
+| `InitializationMustHaveContent` | Module | An `initialization` module MUST contain at least one of: `molecule`, `parameterList`, or a user-defined module child. Per the compchem convention spec. |
+| `FinalizationMustHaveContent` | Module | A `finalization` module MUST contain at least one of: `molecule`, `propertyList`, or a user-defined module child. Per the compchem convention spec. |
+
+## convention:dictionary
+
+- **Namespace**: `http://www.xml-cml.org/convention/dictionary`
+- **Constraint count**: 8
+
+| Constraint | Applies to | Description |
+|---|---|---|
+| `EntryMustHaveIdAndTerm` | DictionaryEntry | Every entry MUST have an `id` and a `term` attribute per the dictionary convention. |
+| `EntryIdsUniqueWithinDictionary` | Dictionary | Entry ids MUST be unique within the parent dictionary per the dictionary convention. |
+| `DictionaryMustHaveNamespace` | Dictionary | A `<dictionary>` element MUST have a `namespace` attribute whose value is a valid URI defining the scope within which the entry terms are unique. |
+| `DictionaryNamespaceShouldEndWithSlashOrHash` | Dictionary | The `namespace` URI SHOULD end with `/` or `#` so terms can be referenced by appending them to the URI. Warning level. |
+| `EntryMustContainDefinition` | DictionaryEntry | An `<entry>` MUST contain a single `definition` child element. The schema allows it as a string; this constraint enforces presence. |
+| `EntryIdMustMatchPattern` | DictionaryEntry | An `<entry>` `id` MUST match `[A-Za-z][A-Za-z0-9._-]*` — start with a letter, followed by letters/digits/dot/hyphen/ underscore. Mirrors the upstream IdStartChar / IdChar BNF. |
+| `EntryMustHaveUnitType` | DictionaryEntry | An `<entry>` MUST have a `unitType` attribute. Entries describing concepts that should not have units (e.g. name of a program) should reference `none` in the standard CML |
+| `EntryUnitsCoConstraints` | DictionaryEntry | Co-constraint between `unitType` and `units`: - If `unitType` is `unknown`, `units` MUST NOT be present. - If `unitType` is `none`, `units` MUST be present and point |
+
+## convention:molecular
+
+- **Namespace**: `http://www.xml-cml.org/convention/molecular`
+- **Constraint count**: 36
+
+| Constraint | Applies to | Description |
+|---|---|---|
+| `AtomArrayMustContainAtoms` | Molecule | `atomArray` MUST contain at least one atom. The atoms can be in the child form (`<atom>` elements) or the parallel-array form (`atomID` attribute with whitespace-separated ids). |
+| `AtomIdsUniqueWithinMolecule` | _(document-wide)_ | Atom ids MUST be unique within the eldest containing molecule per the molecular convention. |
+| `BondMustReferenceAtomsInSameMolecule` | _(document-wide)_ | Bonds MUST reference atoms within the same parent molecule per the molecular convention. |
+| `AtomMustHaveId` | Atom | An <atom> inside an atomArray in a molecule MUST have an id attribute. |
+| `AtomMustHaveElementType` | Atom | An <atom> inside an atomArray in a molecule MUST have an elementType attribute. |
+| `BondMustHaveAtomRefs2` | Bond | A <bond> MUST have an atomRefs2 attribute referencing two distinct atoms in the same molecule. |
+| `BondMustHaveOrder` | Bond | A <bond> MUST have an order attribute (S/D/T/A recommended). |
+| `MoleculeMustHaveId` | Molecule | A <molecule> in a molecular document MUST have an id attribute unique within document scope. |
+| `AtomCoordinatesMustBePaired` | Atom | <atom> 2D coordinates (x2, y2) must appear together; 3D coordinates (x3, y3, z3) must appear together. |
+| `PropertyMustHaveDictRef` | Property | A <property> MUST have a dictRef attribute that identifies the property type via a dictionary entry. |
+| `ScalarMustHaveDataType` | Scalar | A <scalar> child of a <property> MUST have a dataType attribute (e.g. xsd:float, xsd:integer). |
+| `BondOrderShouldNotBeNumeric` | Bond | A <bond>'s order attribute SHOULD be one of S/D/T/Q/A or 'other' (numeric values are not recommended). |
+| `AtomIdMustMatchPattern` | Atom | An <atom>'s id attribute SHOULD start with a letter and contain only letters, digits, dot, hyphen, or underscore. |
+| `MoleculeCountMustNotAppearOnTopLevel` | _(document-wide)_ | Molecular convention: `count` MUST NOT appear on top-level molecules (direct children of `<cml>`). It is REQUIRED on molecules nested inside another `<molecule>`. |
+| `MoleculeAtomArrayMutuallyExclusiveWithChildren` | Molecule | Molecular convention: a `<molecule>` MAY hold an `atomArray` OR child `<molecule>` elements, but not both. The two are mutually exclusive ways of describing composition. |
+| `MoleculeBondArrayMutuallyExclusiveWithChildren` | Molecule | Molecular convention: a `<molecule>` MAY hold a `bondArray` OR child `<molecule>` elements, but not both. |
+| `BondStereoWedgeHashMustHaveAtomRefs2` | BondStereo | Molecular convention: `<bondStereo>` value W (wedge) or H (hatch) MUST have `atomRefs2` and MUST NOT have `atomRefs4`. |
+| `BondStereoCisTransMustHaveAtomRefs4` | BondStereo | Molecular convention: `<bondStereo>` value C (cis) or T (trans) MUST have `atomRefs4` and MUST NOT have `atomRefs2`. |
+| `BondStereoOtherMustHaveDictRef` | BondStereo | Molecular convention: `<bondStereo>` with value `other` MUST have a `dictRef` pointing to the convention that defines the stereo semantics. |
+| `BondIdsUniqueWithinMolecule` | _(document-wide)_ | Molecular convention: a `<bond>` `id` MUST be unique within the eldest containing molecule. Mirrors the existing `AtomIdsUniqueWithinMolecule` constraint for bonds. |
+| `BondOrderOtherMustHaveDictRef` | Bond | Molecular convention: `<bond>` with `order="other"` MUST have a `dictRef` pointing to the dictionary that defines the order semantics. The warning-level "should not be |
+| `AtomArrayMustBeChildOfMoleculeOrFormula` | _(document-wide)_ | Molecular convention: `<atomArray>` MUST be a child of `<molecule>` or `<formula>`. Any other parent is invalid. Checked from the parent's perspective during the walk — |
+| `BondArrayMustBeChildOfMolecule` | _(document-wide)_ | Molecular convention: `<bondArray>` MUST be a child of `<molecule>`. Any other parent is invalid. |
+| `BondOrderShouldBeInEnum` | Bond | A `<bond>`'s `order` attribute SHOULD be one of the XSD orderType enum values: S/1/D/2/T/3/A/unknown/other. Warning severity — CML permits extension values via |
+| `BondStereoShouldBeInEnum` | BondStereo | A `<bondStereo>`'s `value` attribute SHOULD be one of the XSD stereoType enum values: C/T/W/H/undefined/other. Warning severity. |
+| `MoleculeChiralityShouldBeInEnum` | Molecule | A `<molecule>`'s `chirality` attribute SHOULD be one of the XSD chiralityType enum values: enantiomer/racemate/unknown/other. Warning severity. |
+| `BondAtomRefs2ShouldBeDistinct` | Bond | A `<bond>`'s `atomRefs2` SHOULD reference two distinct atom ids. A self-bond (`a1 a1`) is chemically meaningless. Warning severity — there are edge cases in non-classical |
+| `ReferencesShouldResolve` | _(document-wide)_ | Walks the document via `Cml::ReferenceResolver` and reports every bond whose `atomRefs2` references atoms that don't exist in the parent molecule. Warning severity — there are |
+| `BondStereoAtomRefs4ShouldBeDistinct` | BondStereo | A `<bondStereo>` with `atomRefs4` (used by C/T stereo) SHOULD reference four distinct atom ids. Duplicate ids make the stereo descriptor meaningless. Warning severity. |
+| `AtomParityAtomRefs4ShouldBeDistinct` | AtomParity | An `<atomParity>` element's `atomRefs4` attribute SHOULD reference four distinct atom ids around a chiral center. Duplicate ids make the parity descriptor meaningless. |
+| `AtomElementTypeShouldBeInPeriodicTable` | Atom | An `<atom>`'s `elementType` attribute SHOULD be one of the XSD elementTypeType enum values (the periodic table plus the special "Du" dummy and "R" group placeholder). Warns |
+| `DictRefShouldResolve` | Atom, Bond, Molecule, Property, Scalar, Array, Matrix, Name, Label | Walks the document and warns on any element whose `dictRef` attribute cannot be resolved against the built-in dictionaries. Catches typos like `dictRef="cml:bpingpoint"`. |
+| `MoleculeIdShouldMatchPattern` | Molecule | A `<molecule>`'s `id` attribute SHOULD match the XSD moleculeIDType pattern (letter/underscore start, alphanumeric body, optional namespace prefix). Warning severity. |
+| `BondIdShouldMatchPattern` | Bond | A `<bond>`'s `id` attribute SHOULD match the XSD idType pattern (letter start, alphanumeric body with dots/dashes). Warning severity. |
+| `AtomParityShouldIncludeParentAtom` | _(document-wide)_ | Walks the document and warns on `<atomParity>` elements whose parent `<atom>`'s id does not appear in atomRefs4. The CML convention requires the parent atom to be one of |
+| `PropertyScalarDataTypeMatchesDictionary` | Property | A `<property>` with a `dictRef` whose dictionary entry declares a `dataType` SHOULD have a child `<scalar>` whose `dataType` attribute matches. Catches inconsistencies like a property |
+
+## convention:simpleUnit
+
+- **Namespace**: `http://www.xml-cml.org/convention/simpleUnit`
+- **Constraint count**: 3
+
+| Constraint | Applies to | Description |
+|---|---|---|
+| `UnitMustHavePower` | Unit | A `<unit>` under simpleUnit MUST declare a `power` attribute (integer). Without a power the unit's exponent is undefined. |
+| `UnitMustHaveSymbol` | Unit | A `<unit>` under simpleUnit MUST declare a non-empty `symbol` attribute. Without a symbol the unit cannot be rendered in formulae. |
+| `RootMustBeUnitList` | _(document-wide)_ | The root of a simpleUnit document MUST be a `<unitList>` declaring `convention="convention:simpleUnit"`. Any other root shape is rejected. |
+
+## convention:spectroscopy
+
+- **Namespace**: `http://www.xml-cml.org/convention/spectroscopy`
+- **Constraint count**: 5
+
+| Constraint | Applies to | Description |
+|---|---|---|
+| `SpectrumMustHaveConvention` | Spectrum | A `<spectrum>` MUST declare its own convention attribute so consumers know how to interpret its format and peaks. Per the molecular convention: "spectrum — any number, each MUST |
+| `SpectrumMustHaveFormat` | Spectrum | A `<spectrum>` MUST have a `format` attribute (e.g. "mass", "ir", "nmr", "uv") so consumers know the measurement type. |
+| `SpectrumMustHaveContent` | Spectrum | A `<spectrum>` MUST contain at least one of: `<xaxis>`, `<yaxis>`, `<peakList>`. An empty spectrum carries no data. |
+| `PeakListMustContainPeaks` | PeakList | A `<peakList>` MUST contain at least one `<peak>` or `<peakGroup>` child. An empty peakList carries no data. |
+| `PeakShouldHaveValues` | Peak | A `<peak>` SHOULD declare at least one of `xValue` or `yValue`. A peak with neither carries no position information. Warning severity — there are edge cases |
+
+## convention:unit-dictionary
+
+- **Namespace**: `http://www.xml-cml.org/convention/unit-dictionary`
+- **Constraint count**: 10
+
+| Constraint | Applies to | Description |
+|---|---|---|
+| `UnitMustHaveSymbolAndUnitType` | Unit | Every unit MUST have `id`, `title`, `symbol`, `parentSI`, at least one of `multiplierToSI`/`constantToSI`, and `unitType` per the unit-dictionary convention. |
+| `UnitMustHaveId` | Unit | A `<unit>` element MUST have an `id` attribute, unique within the unitList. |
+| `UnitMustContainDefinition` | Unit | A `<unit>` element MUST contain a single `<definition>` child element with XHTML content. |
+| `UnitListMustHaveNamespace` | UnitList | A `<unitList>` element MUST have a `namespace` attribute whose value is a valid URI defining the scope within which the unit ids are unique. SHOULD end with `/` or `#`. |
+| `UnitListMustContainAtLeastOneUnit` | UnitList | A `<unitList>` element MUST contain one or more `<unit>` children, and MUST NOT contain any other CML-namespace child elements. |
+| `UnitMustHaveTitle` | Unit | A `<unit>` element MUST have a `title` attribute (the full human-readable name of the unit). Per the unit-dictionary convention spec. |
+| `UnitMustHaveParentSi` | Unit | A `<unit>` element MUST have a `parentSI` attribute — a QName referencing the SI unit it derives from. Per the unit-dictionary convention spec. |
+| `UnitMustHaveMultiplierOrConstantToSi` | Unit | A `<unit>` element MUST have at least one of `multiplierToSI` or `constantToSI` — to define the conversion to the parent SI unit. Per the unit-dictionary convention spec. |
+| `UnitUnitTypeShouldResolve` | Unit | A `<unit>`'s `unitType` attribute SHOULD reference a unitType that exists in a built-in unitType-dictionary. Catches typos like `unitType="unitType:lenght"` (misspelled). |
+| `UnitParentSiShouldResolve` | Unit | A `<unit>`'s `parentSI` attribute SHOULD reference a unit that exists in a built-in dictionary (typically the SI dictionary). Catches typos like `parentSI="si:metr"`. |
+
+## convention:unitType-dictionary
+
+- **Namespace**: `http://www.xml-cml.org/convention/unitType-dictionary`
+- **Constraint count**: 5
+
+| Constraint | Applies to | Description |
+|---|---|---|
+| `UnitTypeMustHaveIdAndName` | UnitType | Every unitType MUST have an `id` and a `name` attribute per the unitType-dictionary convention. |
+| `UnitTypeIdMustMatchPattern` | UnitType | A `<unitType>` `id` MUST match `[A-Za-z][A-Za-z0-9._-]*`. |
+| `UnitTypeMustContainDefinition` | UnitType | A `<unitType>` MUST contain a single `<definition>` child with XHTML content. |
+| `UnitTypeListMustHaveNamespace` | UnitTypeList | A `<unitTypeList>` MUST have a `namespace` attribute (valid URI, SHOULD end with `/` or `#`). |
+| `UnitTypeListMustContainAtLeastOneUnitType` | UnitTypeList | A `<unitTypeList>` MUST contain one or more `<unitType>` children. |