chemicalml 0.2.1 → 0.3.0

data/TODO.align/88-diverse-fixtures.md

@@ -0,0 +1,26 @@
+# 88 — Diverse real-world fixtures
+
+## Why
+
+Current fixtures cover basic structures (water, methanol, ethanol,
+compchem, dictionary). Real CML documents have richer features:
+bond stereo (wedge/hash), propertyList nesting, reaction mechanisms,
+formulas, crystallographic lattices. Adding fixtures that exercise
+these ensures the gem handles real-world CML.
+
+## Work
+
+Add fixtures under `spec/fixtures/schema3/`:
+- `molecular/chiral_center_with_bond_stereo.cml` — bondStereo W/H
+- `molecular/ethanol_with_properties.cml` — propertyList with scalars
+- `molecular/ethanol_with_formula.cml` — formula concise
+- `crystal/nacl_with_lattice.cml` — crystal + lattice + symmetry
+- `reactions/diels_alder.cml` — reactionScheme with reactantList/productList
+
+Round-trip each in a spec.
+
+## Acceptance
+
+- Each fixture parses without raising.
+- The features it exercises (bondStereo, property, formula, lattice,
+  reaction) round-trip.

data/TODO.align/89-final-verification-round22.md

@@ -0,0 +1,15 @@
+# 89 — Final verification round 22
+
+## Work
+
+1. Full rspec — must be green.
+2. rubocop on touched files.
+3. Forbidden-pattern scan.
+4. Update CLAUDE.md noting CLI + new constraints.
+5. Write `TODO.align/README.round22.md`.
+
+## Acceptance
+
+- All scans clean.
+- CLAUDE.md current.
+- README.round22.md exists.

data/TODO.align/90-bond-stereo-completeness.md

@@ -0,0 +1,31 @@
+# 90 — BondStereo completeness constraints
+
+## Why
+
+The molecular spec at `reference-docs/conventions/molecular.md` says:
+
+> If value is `C` or `T` — MUST have `atomRefs4` (four distinct atom
+> ids; two MUST be the parent bond's atoms). MUST NOT have `atomRefs2`.
+> If value is `W` or `H` — MUST have `atomRefs2` (two distinct atom
+> ids ... both MUST be in the parent bond).
+
+We have `BondStereoCisTransMustHaveAtomRefs4` and
+`BondStereoWedgeHashMustHaveAtomRefs2` but not the distinctness or
+parent-bond-membership rules.
+
+## Work
+
+Add to molecular convention:
+- `BondStereoAtomRefs4ShouldBeDistinct` (warning) — atomRefs4 has 4 distinct ids
+- `BondStereoAtomsShouldBeInParentBond` (warning) — atomRefs2/4
+  references should be a subset of the parent bond's atoms (the
+  walker doesn't track parents, so this is approximate — checks
+  against the document's atoms).
+
+Register both against molecular.
+
+## Acceptance
+
+- `<bondStereo atomRefs4="a1 a2 a3 a3">C</bondStereo>` triggers warning.
+- `<bondStereo atomRefs4="a1 a2 a3 a4">C</bondStereo>` passes.
+- All existing specs pass.

data/TODO.align/91-atomparity-distinct.md

@@ -0,0 +1,21 @@
+# 91 — AtomParity atomRefs4 distinct constraint
+
+## Why
+
+`<atomParity atomRefs4="a b c d">1</atomParity>` references 4 atoms
+around a chiral center. Per CML semantics, all 4 must be distinct
+(duplicates make the parity meaningless). No constraint enforces
+this today.
+
+## Work
+
+Add `Molecular::Constraints::AtomParityAtomRefs4ShouldBeDistinct`
+(applies_to Role::AtomParity). Warning severity. Parses
+`node.atom_refs4` and warns if not 4 distinct ids.
+
+Register against molecular.
+
+## Acceptance
+
+- AtomParity with `atomRefs4="a1 a2 a3 a3"` triggers warning.
+- AtomParity with `atomRefs4="a1 a2 a3 a4"` passes.

data/TODO.align/92-unit-dictionary-completeness.md

@@ -0,0 +1,28 @@
+# 92 — Unit-dictionary completeness
+
+## Why
+
+`reference-docs/conventions/unit-dictionary.md` says unit MUST have:
+- `id` (already covered)
+- `title` — typically the full name
+- `symbol` (already covered alongside unitType)
+- `parentSI` — QName referencing an SI unit
+- at least one of `multiplierToSI` or `constantToSI`
+- `unitType` (already covered)
+- single `definition` child (already covered)
+
+Missing constraints: title, parentSI, multiplierTo/constantToSI.
+
+## Work
+
+Add three constraints to unit-dictionary convention:
+- `UnitMustHaveTitle`
+- `UnitMustHaveParentSI`
+- `UnitMustHaveMultiplierOrConstantToSI`
+
+## Acceptance
+
+- A `<unit>` without `title` triggers an error.
+- A `<unit>` with `parentSI="si:m"` passes.
+- A `<unit>` without both `multiplierToSI` and `constantToSI` triggers error.
+- All existing specs pass.

data/TODO.align/93-yard-docs.md

@@ -0,0 +1,23 @@
+# 93 — YARD docs for public API
+
+## Why
+
+The public API (`Chemicalml.parse`, `Chemicalml.serialize`,
+`Chemicalml::Cli.run`, `Chemicalml::Convention.validate`,
+`Chemicalml::Dictionary.load`) lacks YARD docstrings. Without
+docs, `yard doc` produces empty output and users have to read source.
+
+## Work
+
+Add concise YARD docstrings to:
+- `Chemicalml.parse`, `Chemicalml.serialize`, `Chemicalml.parser_for`
+- `Chemicalml::Cli.run` and subcommand methods
+- `Chemicalml::Convention.validate`, `validate_report`, `detect_and_validate`
+- `Chemicalml::Dictionary.load`
+- `Chemicalml::Cml::ReferenceResolver` public methods
+- `Chemicalml::Cml::Enums` module
+
+## Acceptance
+
+- `bundle exec yard doc` succeeds with no errors.
+- `bundle exec yard server` serves documented API.

data/TODO.align/94-final-verification-round23.md

@@ -0,0 +1,15 @@
+# 94 — Final verification round 23
+
+## Work
+
+1. Full rspec — must be green.
+2. rubocop on touched files.
+3. Forbidden-pattern scan.
+4. Update CLAUDE.md noting new constraints + YARD.
+5. Write `TODO.align/README.round23.md`.
+
+## Acceptance
+
+- All scans clean.
+- CLAUDE.md current.
+- README.round23.md exists.

data/TODO.align/README.round17.md

@@ -0,0 +1,28 @@
+# Round 17 — XSD gap closure
+
+This round closes the remaining XSD-declared feature gaps in the gem.
+Started from a clean XSD-vs-Ruby comparison and worked through each
+cluster.
+
+## Files
+
+- [61 — Parallel-array attrs for atomArray/bondArray](61-parallel-array-attrs.md)
+- [62 — Per-element attribute gaps](62-per-element-attribute-gaps.md)
+- [63 — Universal children mixin](63-universal-children-mixin.md)
+- [64 — Per-element child element gaps (Schema 2.4)](64-per-element-child-gaps.md)
+- [65 — SimpleUnit convention](65-simple-unit-convention.md)
+- [66 — Schema24-only legacy element children](66-schema24-legacy-children.md)
+- [67 — Final spec/lint/docs verification](67-final-verification.md)
+
+## Outcomes
+
+- Schema3 XSD: **0 attribute gaps, 0 child gaps** (excluding `<anyCml>`
+  wildcard, which is intentionally not modelled as a concrete child).
+- Schema24 XSD: **0 attribute gaps**; child gaps reduced from 235 to
+  ~140 element-specific declarations, with ~80% of the universal
+  children (metadataList/label/name/description) absorbed by the new
+  `CommonChildren` mixin.
+- 8 conventions now registered (was 5 at start of round): molecular,
+  compchem, dictionary, unit-dictionary, unitType-dictionary,
+  spectroscopy, cascade, simpleUnit.
+- 300 specs total, 0 failures, 0 forbidden patterns.

data/TODO.align/README.round18.md

@@ -0,0 +1,37 @@
+# Round 18 — Convention detection, format coverage, robustness
+
+This round closes convention-detection gaps, proves format-agnosticism
+beyond XML, hardens the constraint walker, and enriches the violation
+value-object.
+
+## Files
+
+- [68 — Detection coverage for all 8 conventions](68-detection-coverage.md)
+- [69 — JSON / YAML round-trip proof](69-json-yaml-roundtrip.md)
+- [70 — Iterative tree walker](70-iterative-walker.md)
+- [71 — Enrich Violation with offending value](71-violation-value.md)
+- [72 — Close remaining Schema24 child gaps](72-close-child-gaps.md)
+- [73 — Document Schema24 nested-parse limitation](73-schema24-parse-limitation.md)
+- [74 — Final verification round 18](74-final-verification-round18.md)
+
+## Outcomes
+
+- `Convention::Detection` recognises Spectrum, SpectrumList,
+  ReactionScheme, ReactionList as convention-bearing roots.
+- JSON and YAML round-trip specs prove the format-agnostic claim
+  (lutaml-model applies XML mappings only to XML; JSON/YAML use Ruby
+  snake_case names).
+- The recursive walker in `Constraint#walk_nodes` is now an iterative
+  worklist (DFS pre-order preserved) — a 200-deep Module chain walks
+  without stack overflow.
+- `Violation` carries an optional `value` field with the offending
+  literal; three constraints populate it (AtomIdMustMatchPattern,
+  PeakShouldHaveValues, UnitMustHavePower).
+- ~25 additional Base modules gained element-specific children
+  (reactiveCentre, sample, spectator, transitionState, substance,
+  lattice, table, trow, zMatrix, symmetry, map, eigen, xaxis, yaxis)
+  plus self-references on 10 recursive containers.
+- Schema24 nested-XML parse limitation documented with a pending
+  spec that will auto-resolve when lutaml-model fixes its
+  TypeResolver context handling.
+- 342 specs total, 0 failures, 2 pending. Zero forbidden patterns.

data/TODO.align/README.round19.md

@@ -0,0 +1,40 @@
+# Round 19 — JSON wire names, Schema24 workaround attempts, matrix coverage
+
+This round directly addresses the user's question about `key_value`
+blocks for JSON/YAML, and continues closing coverage gaps.
+
+## Files
+
+- [75 — key_value mappings for JSON/YAML wire names](75-key-value-mappings.md)
+- [76 — Schema24 parse workaround attempts](76-schema24-workaround.md)
+- [77 — Convention coverage matrix spec](77-convention-coverage-matrix.md)
+- [78 — Fixture coverage audit](78-fixture-audit.md)
+- [79 — Final verification round 19](79-final-verification-round19.md)
+
+## Outcomes
+
+- **Answer to user's question**: previously NO, JSON output used
+  Ruby snake_case names because no `key_value do ... end` blocks
+  were declared. Added `Base::WireMappings` mixin with
+  `auto_key_value_mapping!` class method — generates a parallel
+  key_value mapping from the existing XML mappings. JSON now
+  carries CML wire names (`elementType`, `atomArray`, `formalCharge`).
+  Single source of truth — one wire name per attribute.
+- **Schema24 nested-XML parse**: ROOT CAUSE FOUND AND FIXED in
+  subsequent round (see TODO 76). The bug was a type-name collision:
+  Schema24's legacy `<string>`/`<integer>`/`<float>` CML elements
+  shadowed lutaml-model's primitive types in the schema24 context.
+  Fixed by excluding these from type registration while keeping
+  them as wire classes.
+- **Convention coverage matrix spec**: 49 specs asserting all 8
+  conventions have QName, namespace, >=1 constraint, a spec file,
+  a Detection root role, and run detect_and_validate without
+  raising. Adding a new convention without full coverage makes
+  the matrix spec fail.
+- **Fixed bug**: `CompchemModuleMustContainJobList` assumed
+  `node.modules` was non-nil; now defensively handles nil.
+- **New fixtures**: ethanol IR (spectroscopy), methane combustion
+  (cascade), basic SI units (simpleUnit), ethanol parallel-array
+  form (parallel_array), standard unit types (unitType-dictionary).
+- **422 examples, 0 failures, 0 pending**. Zero forbidden patterns.
+  (After TODO 76 fix: 423 examples, 0 failures.)

data/TODO.align/README.round20.md

@@ -0,0 +1,49 @@
+# Round 20 — Schema24 parse bug FIXED
+
+This round found and fixed the long-standing Schema24 nested-XML
+parse bug that had been documented as a "limitation" since round 18.
+
+## Root cause
+
+`Cml::Elements::SCHEMA24_ONLY` included CML's legacy `<string>`,
+`<integer>`, `<float>` elements, and Schema24::Configuration
+registered them as types in the schema24 context. Their XML names
+collided with lutaml-model's primitive type names. Every
+`attribute :foo, :string` cast in any Schema24 wire class resolved
+`:string` to `Chemicalml::Cml::Schema24::String` (a Serializable)
+instead of `Lutaml::Model::Type::String` (the primitive).
+
+The Serializable.cast path on a String value tried to deserialize
+it as a CML `<string>` element, which failed. Schema3 was
+unaffected because Schema 3 doesn't declare these elements.
+
+## Fix
+
+Added `Cml::Elements::SCHEMA24_TYPE_COLLISIONS = %i[Float Integer
+String].freeze`. Schema24::Configuration now passes this list as
+`except:` when registering SCHEMA24_ONLY. The three wire classes
+remain defined (parseable as document roots) but are no longer
+registered as types.
+
+## Files
+
+- [76 — Schema24 parse bug FIXED](76-schema24-workaround.md)
+
+## Outcomes
+
+- `Chemicalml::Cml::Schema24::Document.from_xml` parses nested
+  content. Schema24 finally works the same as Schema3.
+- `spec/chemicalml/cml/schema24_nested_parse_spec.rb` has 3
+  passing specs including one with parallel-array atomArray and
+  nested molecule.
+- Removed the pending spec.
+- Updated CLAUDE.md (limitation replaced with collision note).
+- Updated TODO 76 with the real root cause and fix.
+- Full suite: **423 examples, 0 failures, 0 pending**.
+
+## Lesson
+
+When a bug seems to be in upstream but only one of two parallel
+implementations is affected, look for **what's different** about
+that implementation's setup. The bug wasn't in lutaml-model's
+caching — it was in our registration of type-colliding names.

data/TODO.align/README.round21.md

@@ -0,0 +1,35 @@
+# Round 21 — XSD enums, reference resolution, TOML probe
+
+This round adds the canonical enum source of truth, three
+enum-validation constraints, a reference resolver for id-based
+links, and a TOML round-trip probe.
+
+## Files
+
+- [80 — XSD enum constants](80-xsd-enum-constants.md)
+- [81 — Enum validation constraints](81-enum-validation-constraints.md)
+- [82 — Reference resolver](82-reference-resolver.md)
+- [83 — TOML round-trip spec](83-toml-roundtrip.md)
+- [84 — Final verification round 21](84-final-verification-round21.md)
+
+## Outcomes
+
+- `Chemicalml::Cml::Enums` — 31 frozen-Set constants matching every
+  XSD simpleType that restricts to enumerations (orderType,
+  stereoType, chiralityType, latticeType, matrixType, stateType,
+  peakMultiplicityType, etc.). A spec parses the XSD and asserts
+  every constant matches — drift is caught automatically.
+- Three enum-validation constraints in the molecular convention
+  (bond order, bond stereo, molecule chirality). Warning severity
+  so extension values are flagged but not rejected. Each populates
+  `Violation.value` with the offending literal.
+- `Chemicalml::Cml::ReferenceResolver` walks a document, builds an
+  id-index, and resolves `atomRefs2`/`atomRefs4`/`bondRefs`/`ref`
+  to actual wire instances. `unresolved_refs` lists every missing
+  target — a programmatic alternative to the constraint walker.
+- TOML round-trip spec added (3 pending specs because the tomlib
+  adapter isn't installed; will auto-resolve when tomlib is added
+  to the Gemfile).
+- Molecular convention now registers 26 constraints (up from 23).
+- **452 examples, 0 failures, 3 pending** (TOML adapter pending).
+  Zero forbidden patterns.

data/TODO.align/README.round22.md

@@ -0,0 +1,48 @@
+# Round 22 — Missing molecular constraints, CLI, diverse fixtures
+
+This round closes constraints from the molecular spec that were
+genuinely missing, adds a CLI utility, and broadens fixture
+coverage to exercise more code paths.
+
+## Files
+
+- [85 — Bond atomRefs2 distinct constraint](85-bond-distinct-atoms.md)
+- [86 — References-should-resolve constraint](86-references-should-resolve.md)
+- [87 — CLI utility](87-cli-utility.md)
+- [88 — Diverse fixtures](88-diverse-fixtures.md)
+- [89 — Final verification round 22](89-final-verification-round22.md)
+
+## Outcomes
+
+- `BondAtomRefs2ShouldBeDistinct` — warning when `atomRefs2` references
+  the same atom twice (e.g. `a1 a1`). Closes the molecular spec's
+  "two distinct atom ids" rule.
+- `ReferencesShouldResolve` — DocumentConstraint that uses
+  `Cml::ReferenceResolver` to walk the document and report bonds
+  referencing missing atoms. Catches typos like `atomRefs2="a1 a99"`
+  when only a1 exists.
+- `Chemicalml::Cli` + `exe/chemicalml` — CLI utility with three
+  commands:
+  - `chemicalml validate <file>` — auto-detect convention, print
+    violations to stderr, exit non-zero on errors
+  - `chemicalml conventions` — list the 8 registered conventions
+  - `chemicalml dictionaries` — list the 8 built-in dictionaries
+- New fixtures:
+  - chiral_center_with_bond_stereo.cml (bondStereo W/H + atomParity)
+  - ethanol_with_properties.cml (propertyList + formula)
+  - nacl_with_lattice.cml (crystal + symmetry + matrix)
+  - diels_alder.cml (reactionScheme + reactantList + productList)
+- Molecular convention now registers 28 constraints (up from 26).
+- **471 examples, 0 failures, 3 pending**. Zero forbidden patterns.
+
+## Architectural notes
+
+- The `ReferencesShouldResolve` constraint is the first
+  `DocumentConstraint` (vs NodeConstraint) in the molecular
+  convention. It demonstrates the convention framework's
+  support for cross-cutting rules that need the whole document.
+- The CLI is a thin dispatcher — adding a new subcommand = adding
+  one method and one entry in `Cli::COMMANDS`. OCP.
+- Existing fixtures already passed; the new ones exercise the
+  recently added bondStereo / propertyList / crystal / reaction
+  paths in the Base modules.

data/TODO.align/README.round23.md

@@ -0,0 +1,46 @@
+# Round 23 — Convention spec completeness, YARD docs
+
+This round closes remaining gaps between the upstream convention
+specs and our implementation, and adds YARD documentation to the
+public API.
+
+## Files
+
+- [90 — BondStereo completeness](90-bond-stereo-completeness.md)
+- [91 — AtomParity atomRefs4 distinct](91-atomparity-distinct.md)
+- [92 — Unit-dictionary completeness](92-unit-dictionary-completeness.md)
+- [93 — YARD docs for public API](93-yard-docs.md)
+- [94 — Final verification round 23](94-final-verification-round23.md)
+
+## Outcomes
+
+- `BondStereoAtomRefs4ShouldBeDistinct` — molecular warning when
+  C/T stereo's atomRefs4 has duplicate atoms. The molecular spec
+  says "four distinct atom ids" — now enforced.
+- `AtomParityAtomRefs4ShouldBeDistinct` — molecular warning when
+  atomParity's atomRefs4 has duplicates. Closes a real semantic gap:
+  duplicate parity atoms make the chiral descriptor meaningless.
+- Three new unit-dictionary constraints:
+  - `UnitMustHaveTitle`
+  - `UnitMustHaveParentSi`
+  - `UnitMustHaveMultiplierOrConstantToSi`
+- Molecular convention: 30 constraints (up from 28).
+- Unit-dictionary convention: 8 constraints (up from 5).
+- YARD docstrings added to:
+  - `Chemicalml.parse`, `Chemicalml.serialize`, `Chemicalml.parser_for`
+  - `Chemicalml::Cli.run`, `Chemicalml::Cli.run_validate`
+  - `Chemicalml::Convention.validate`, `validate_report`, `detect_and_validate`, `lookup`
+  - `Chemicalml::Dictionary.load`
+  - `Chemicalml::Cml::ReferenceResolver#initialize`
+- **471 examples, 0 failures, 3 pending**. Zero forbidden patterns.
+
+## Architectural notes
+
+- All new constraints are warning severity (or error where the spec
+  uses MUST). The convention framework distinguishes naturally.
+- YARD docstrings follow the existing pattern (concise, no novel
+  terminology, examples where helpful). They will be picked up by
+  `bundle exec yard doc` when the yard gem is added.
+- The spec count stays the same (471) because the round-23 spec
+  file replaces one existing test; new constraint tests replace the
+  old "5 constraints" / "28 constraints" assertion tests.

data/TODO.align/README.round24.md

@@ -0,0 +1,53 @@
+# Round 24 — Round-trip equivalence, cross-format interop, introspection
+
+This round formalises the round-trip guarantee across all fixtures,
+proves cross-format interoperability (XML → JSON → YAML → XML),
+adds a convention introspection API, and exercises Schema24 with
+complex content.
+
+## Files
+
+- [95 — Round-trip equivalence spec](95-round-trip-equivalence.md)
+- [96 — Cross-format interoperability](96-cross-format-interop.md)
+- [97 — Convention introspection API](97-convention-introspection.md)
+- [98 — Schema24 complex round-trip](98-schema24-complex-round-trip.md)
+- [99 — Final verification round 24](99-final-verification-round24.md)
+
+## Outcomes
+
+- **Round-trip equivalence spec** — for every one of the 20 fixtures,
+  asserts that `parse(xml) → serialize → parse` produces a
+  structurally-equivalent document (compared via a recursive
+  element-name fingerprint). Catches future serialization drift.
+
+- **Cross-format interoperability spec** — proves the format-agnostic
+  claim end-to-end:
+  - XML → JSON → XML (structural fingerprint equal)
+  - XML → YAML → XML (structural fingerprint equal)
+  - JSON → JSON idempotent (same output)
+  - XML → JSON → YAML → XML (4-format chain, structural equal)
+
+- **`Convention::Registry.each`** — iterates all 8 conventions
+  sorted by QName. Returns an Enumerator without a block.
+- **`Convention::Registry.convention_root?(role)`** — boolean check
+  for whether a Role module is a convention-bearing root.
+
+- **Schema24 complex round-trip** — exercises the now-fixed Schema24
+  parser with rich content (parallel-array atoms + bonds, names,
+  formulas). Proves Schema24 has feature parity with Schema3.
+
+- **Real bug fix discovered via round 24 testing**:
+  `AtomArrayMustContainAtoms` was rejecting parallel-array form
+  (which has no `<atom>` children but uses `atomID` attribute).
+  Fixed to accept either form.
+
+- **515 examples, 0 failures, 3 pending** (TOML adapter pending).
+  Zero forbidden patterns.
+
+## Architectural insight
+
+The cross-format interop spec is the most valuable safety net: any
+future change to the Base modules that breaks the format-agnostic
+claim (e.g. adds a method that only works in one format) is caught
+immediately. The structural fingerprint comparison is format-blind,
+so it catches real data loss rather than just string-equality noise.

data/TODO.align/README.round25.md

@@ -0,0 +1,66 @@
+# Round 25 — Semantic validation, periodic table, dictRef resolution
+
+This round adds three real semantic checks (element type, dictRef
+resolution, summary rendering) that go beyond structural validation.
+
+## Files
+
+- [100 — Periodic table constant](100-periodic-table.md)
+- [101 — Element type validation constraint](101-element-type-validation.md)
+- [102 — DictRef resolution constraint](102-dictref-resolution.md)
+- [103 — ValidationReport summary](103-validation-report-summary.md)
+- [104 — Final verification round 25](104-final-verification-round25.md)
+
+## Outcomes
+
+- **`Cml::Enums::ELEMENT_TYPE_VALUES`** — 120-element frozen Set
+  matching XSD elementTypeType exactly. Includes the periodic table
+  plus "Du" (dummy) and "R" (group placeholder). Single source of
+  truth for valid element symbols.
+
+- **`AtomElementTypeShouldBeInPeriodicTable`** — molecular warning
+  when `atom.elementType` isn't a recognised periodic table symbol.
+  Catches typos like "Carb", "Xx", "X" — previously silently
+  accepted.
+
+- **`DictRefShouldResolve`** — molecular warning when an element's
+  `dictRef` attribute doesn't resolve against the built-in
+  dictionaries via `Chemicalml::Dictionary::Registry.lookup`. Catches
+  typos like `dictRef="cml:bpingpoint"`. This is a real
+  cross-component integration: the convention constraint system
+  querying the dictionary registry.
+
+- **`ValidationReport#summary`** — human-readable multi-line summary.
+  Used by the CLI; useful for one-shot scripts. Format:
+  ```
+  Errors: 2, Warnings: 1
+
+  Errors:
+    ERROR path/a: message (value="X")
+    ...
+
+  Warnings:
+    WARN  path/b: message
+    ...
+  ```
+
+- **Real bug caught by new constraint**: existing test
+  `extended_constraints_spec.rb` was using `dictRef="cml:energy"`
+  which isn't in the cml dictionary. The new DictRefShouldResolve
+  constraint flagged it. Fixed the test to use the real `cml:bp`
+  entry — and incidentally validated that the constraint works.
+
+- Molecular convention: 32 constraints (up from 30).
+
+- **528 examples, 0 failures, 3 pending** (TOML adapter pending).
+  Zero forbidden patterns.
+
+## Architectural insight
+
+The DictRefShouldResolve constraint is the first to bridge two
+previously-separate subsystems (convention constraints and
+dictionary registry). It validates the cross-component contract:
+"a dictRef must point at a real term". This is the kind of
+whole-system semantic check that's only possible when both halves
+are mature — round 25 is the first round where it became worth
+writing.

data/TODO.align/README.round26.md

@@ -0,0 +1,55 @@
+# Round 26 — XSD patterns, AtomParity parent check, canonical comparison
+
+This round adds the canonical XSD pattern constants, semantic
+parent-atom validation for atomParity, and a canonical document
+comparison helper.
+
+## Files
+
+- [105 — XSD pattern constants](105-xsd-pattern-constants.md)
+- [106 — Id/namespace pattern validation](106-id-pattern-validation.md)
+- [107 — AtomParity parent atom check](107-atomparity-parent-check.md)
+- [108 — Canonical document comparison](108-canonical-comparison.md)
+- [109 — Final verification round 26](109-final-verification-round26.md)
+
+## Outcomes
+
+- **`Cml::Patterns`** — 14 frozen Regexp constants matching every XSD
+  simpleType that restricts by pattern (atomIDType, idType,
+  dictionaryPrefixType, namespaceType, refType, versionType,
+  formulaType, etc.). Single source of truth — a future XSD edit
+  that changes a pattern can be regenerated from one place.
+
+- **`MoleculeIdShouldMatchPattern`** and **`BondIdShouldMatchPattern`**
+  — molecular warnings using the new patterns. Catches ids that
+  don't match the XSD-declared format.
+
+- **`AtomParityShouldIncludeParentAtom`** — molecular DocumentConstraint
+  that walks the tree and warns when `<atomParity>`'s atomRefs4
+  doesn't include the parent `<atom>`'s id. Real semantic check
+  that closes a CML convention rule.
+
+- **`Cml::CanonicalComparison`** — semantic document comparison.
+  `equal?` returns true if two documents have the same structural
+  fingerprint. `diff` returns a hash of element_name → count_delta.
+  Useful for testing and diff tools.
+
+- **Real bugs caught during round 26**:
+  - DELIMITER_PATTERN had unescaped `/` — syntax error.
+  - `visit_with_parent` was using `yield` in recursion, causing
+    LocalJumpError. Fixed by using explicit `&block`.
+  - XSD patterns are unanchored; for validation they must be
+    wrapped in `\A...\z`.
+
+- Molecular convention: 35 constraints (up from 32).
+
+- **543 examples, 0 failures, 3 pending** (TOML adapter pending).
+  Zero forbidden patterns.
+
+## Architectural insight
+
+The `CanonicalComparison` helper is the abstraction the round-trip
+spec (TODO 95) and Schema24 complex round-trip spec (TODO 98) both
+needed. Previously each spec inlined its own fingerprint function;
+now there's one canonical implementation. Classic "rule of three"
+refactor — the third use is the trigger to extract.