asciichem 0.5.1 → 0.20.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1edf476bb3d979641172de761d1b2ac906cb4eaf8565e56b0e083e146c09eb1d
-  data.tar.gz: b3394a0709a475df222d6369eac92a1cc6d02fc756a7d3a45ca038c5d6f5155c
+  metadata.gz: 6a77da515ac52e848a4ff0f5855a595cb81d71a36c18b4991d875d682d2c3598
+  data.tar.gz: 70c14be9ddec1e767ddddef09a1ad91a02f996f1fdd22645d0269c4de7e96020
 SHA512:
-  metadata.gz: 5a1ce9a990e507a6f70c91939841766e228b02ae674af39c5fa356b4911f20d0ef3b5aa2f2ec4799663d21da54752ed9b68c6660db23e1b2da9cacd4cc50b2ad
-  data.tar.gz: 6d68778aca7042fce958026033e990e51b87290c24ed3028cf224aa34bd5e03418ef6209b72072d06a14ab3352e2d20290c939b4002a82fdcdbe5c267a17d087
+  metadata.gz: b71e29edd758d5d4393d750a95676dc8007c5850f830b414ca83a2d21e99c1ff39fa88f5f66b54198e442e7d29b9010639c4a55138567cd9dee8160d5b2be3dc
+  data.tar.gz: f08f835457ce6d58b70ff0b3bc502f84f4404684a13ae60ad52bbae44a790dfd66621c15bba73ed2843e0d76ba4ef47545a37e838867b54d12eb9246f11277b6

data/.github/workflows/ci.yml

@@ -14,8 +14,17 @@ jobs:
         ruby: ["3.3", "3.4"]
     steps:
       - uses: actions/checkout@v4
+      - name: Clone conformance corpus (asciichem-tests)
+        run: git clone --depth 1 https://github.com/asciichem/asciichem-tests.git ../asciichem-tests
       - uses: ruby/setup-ruby@v1
         with:
           ruby-version: ${{ matrix.ruby }}
           bundler-cache: true
       - run: bundle exec rspec
+      - name: Publish conformance report
+        if: matrix.ruby == '3.4'
+        uses: actions/upload-artifact@v4
+        with:
+          name: conformance
+          path: conformance.json
+          if-no-files-found: warn

data/.github/workflows/release.yml

@@ -0,0 +1,42 @@
+name: Release
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: "Version to release (must match lib/asciichem/version.rb)"
+        required: true
+        type: string
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    # Trusted publishing (OIDC): the publisher registered on RubyGems.org
+    # is repository asciichem/asciichem-ruby + workflow release.yml, with
+    # no environment — so this job must not claim one.
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: main
+          persist-credentials: false
+      - name: Verify version matches input
+        run: |
+          actual=$(ruby -e 'require "./lib/asciichem/version"; print AsciiChem::VERSION')
+          if [ "$actual" != "${{ inputs.version }}" ]; then
+            echo "Version mismatch: input=${{ inputs.version }}, lib/asciichem/version.rb=$actual"
+            exit 1
+          fi
+          echo "Releasing $actual"
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.4"
+          bundler-cache: true
+      # Builds and pushes using the GitHub OIDC identity — no API keys.
+      - uses: rubygems/release-gem@v1
+      - name: Summary
+        run: |
+          echo "Released asciichem ${{ inputs.version }} to RubyGems"
+          echo "https://rubygems.org/gems/asciichem"

data/.gitignore

@@ -12,3 +12,4 @@
 /.vscode/
 /.idea/
 *.gem
+conformance.json

data/ARCHITECTURE.adoc

@@ -237,3 +237,156 @@ Plurimath handles it.
 * No hand-rolled model serialisation. The model is in-memory only;
   rendering to MathML / HTML / etc. is one-way output via Nokogiri or
   string building, not `(de)serialisation`.
+
+
+== Native CML wire (v0.9-v0.11)
+
+All AsciiChem model classes have native CML wire representations
+(chemicalml 0.3.0+). The mapping is one-way in production: the
+adapter produces native wire objects; the CML Translator enriches
+with aci: extensions only for backwards-compat fallback.
+
+[cols="1,1,2", options="header"]
+|===
+| Model class | Wire container | Native child elements
+| Crystal |  |  with  cells, ,  (fractional coords)
+| Spectrum |  |  with  of  (xValue/yValue/yMultiplicity/title)
+| ZMatrix |  |  (text content; structural length/angle/torsion children are future work)
+| Calculation |  |  of  with  (value, units)
+| Mechanism |  |  (text via title; structural step list is future work)
+| Reaction conditions |  |  with  (above/below)
+|===
+
+== Extension channels (six parallel modules)
+
+Each channel is a MECE module under :
+
+*  — per-atom aci: attributes (FIELDS registry)
+*  — top-level constructs via aci: elements (HANDLERS registry)
+*  —  inside molecules (BRACKETS registry on Group)
+*  — preserves unknown top-level elements verbatim
+*  — per-molecule key/value metadata (aci:meta-*)
+*  — now mostly legacy; native <conditionList> preferred
+
+The  is a thin orchestrator (~80 lines) that calls each
+module's // in pipeline order.
+
+== Model-owned wire codes
+
+Wire-format mappings live on the model classes as the single source
+of truth:
+
+*  /  / 
+*  / 
+*  / 
+*  /  /  / 
+*  (shared by adapter and extension modules)
+
+Adding a new bond kind, bracket kind, arrow kind, or cell parameter
+is one entry on the model; both adapter directions pick it up.
+
+== Linter framework
+
+Ten registered checks (auto-load via ):
+
+*  — stoichiometric atom conservation
+*  — charge conservation (v0.7+)
+*  — group bracket consistency
+*  — cell lengths/angles/fractional coords (v0.6+)
+*  — forward references and geometry (v0.6+)
+*  — peak data validation (v0.6+)
+*  — periodic-table membership
+*  — isotope mass >= atomic number
+*  — unmatched ring-closure digits
+*  — bond order + charge <= max valence
+
+ sorts by severity then deduplicates.
+
+== Convenience methods on Molecule
+
+*  — total atoms (recurses through groups/nested molecules)
+*  — Hill-system canonical formula (C first, H second, alpha)
+*  — sum of atomic_mass × count (v0.13+)
+
+== Native CML wire (v0.9-v0.11)
+
+All AsciiChem model classes have native CML wire representations
+(chemicalml 0.3.0+). The adapter produces native wire objects;
+the CML Translator enriches with aci: extensions only as a
+backwards-compat fallback.
+
+|===
+| Model class | Wire container | Native child elements
+
+| Crystal
+| `<molecule>`
+| `<crystal>` with `<scalar>` cells, `<symmetry>`, `<atomArray>` (fractional coords)
+
+| Spectrum
+| `<molecule>`
+| `<spectrum>` with `<peakList>` of `<peak>` (xValue/yValue/yMultiplicity/title)
+
+| ZMatrix
+| `<molecule>`
+| `<zMatrix>` (text content; structural length/Angle/Torsion children are future work)
+
+| Calculation
+| `<molecule>`
+| `<propertyList>` of `<property>` with `<scalar>` (value, units)
+
+| Mechanism
+| `<reaction>`
+| `<mechanism>` (text via title; structural step list is future work)
+
+| Reaction conditions
+| `<reaction>`
+| `<conditionList>` with `<scalar>` (above/below)
+|===
+
+== Six extension channels (MECE modules under Cml)
+
+* `Extensions::AtomAttributes` — per-atom aci: attributes (FIELDS registry)
+* `Extensions::TopLevel` — top-level constructs via aci: elements (HANDLERS registry)
+* `GroupExtensions` — `<aci:group>` inside molecules
+* `OpaqueExtensions` — preserves unknown top-level elements verbatim
+* `MetadataExtensions` — per-molecule key/value metadata (aci:meta-*)
+* `ConditionsExtensions` — legacy; native <conditionList> preferred (v0.11+)
+
+The `Translator` is a thin orchestrator (~80 lines) that calls each
+module's inject/extract/restore in pipeline order.
+
+== Model-owned wire codes (single source of truth)
+
+Wire-format mappings live on the model classes:
+
+* `Bond::CML_ORDER_CODES` / `KIND_BY_CML_ORDER` / `CML_STEREO_CODES`
+* `Group::BRACKETS` / `BRACKET_BY_WIRE`
+* `Reaction::ARROWS` / `ARROW_BY_WIRE`
+* `Crystal::CELL_PARAMS` / `LENGTH_FIELDS` / `ANGLE_FIELDS` / `CELL_LABELS`
+* `Cml::ID_PREFIXES` (shared by adapter and extension modules)
+
+Adding a new bond kind, bracket kind, arrow kind, or cell parameter
+is one entry on the model; both adapter directions pick it up.
+
+== Linter framework
+
+Ten registered checks (auto-load via `Linter::Base.register`):
+
+* `BalanceCheck` — stoichiometric atom conservation
+* `ChargeBalanceCheck` — charge conservation (v0.7+)
+* `BracketBalanceCheck` — group bracket consistency
+* `CrystalSanityCheck` — cell lengths/angles/fractional coords (v0.6+)
+* `ZMatrixReferenceCheck` — forward references and geometry (v0.6+)
+* `SpectrumPeakCheck` — peak data validation (v0.6+)
+* `ElementValidationCheck` — periodic-table membership
+* `IsotopeSanityCheck` — isotope mass >= atomic number
+* `UnclosedRingCheck` — unmatched ring-closure digits
+* `ValenceCheck` — bond order + charge <= max valence
+
+`Linter.run` sorts by severity (errors first) then deduplicates.
+
+== Convenience methods on Molecule
+
+* `#atom_count` — total atoms (recurses through groups/nested molecules)
+* `#hill_formula` — Hill-system canonical formula (C first, H second, alpha)
+* `#formula_weight` — sum of atomic_mass * count (v0.13+)

data/CHANGELOG.md

@@ -3,15 +3,390 @@
 All notable changes to AsciiChem are documented here.
 This project follows [Semantic Versioning](https://semver.org/).
 
-## [Unreleased]
+## [0.20.0] - 2026-09-12
+
+### Added
+- Canonical JSON wire form (`to_model_json` / `AsciiChem.from_model_json`)
+  per asciichem-model v1: `AsciiChem::Wire` (lutaml-model Serializable
+  classes, json mappings only - no hand-rolled serialization) bridged by
+  `AsciiChem::WireAdapter` (model-to-model conversion, same pattern as
+  the CML ModelAdapter). Emission covers every node type; ingestion
+  covers the lossless core set (beyond-formulas nodes are emission-only
+  until their corpus round-trip acceptance lands).
+- Conformance runner over the shared corpus (asciichem-tests): L0
+  emission + schema validation, L1 Text round-trip, L3 CML round-trip,
+  L4 linter diagnostics, plus the ParseError contract for rejects.
+  Emits conformance.json; CI clones the corpus and publishes the report
+  as an artifact. Current claim: L0 149/149, L1 16/16, L3 23/23, L4 6/6.
+
+## [0.19.0] - 2026-09-09
+
+### Added
+- `AsciiChem::Identifiers` — offline format validators for chemical
+  identifier conventions, self-registering like linter checks
+  (`cas` with check digit, `inchi` with formula-layer analysis,
+  `inchikey` 14-10-1 format, `smiles` structural sanity). Purely
+  lexical; no network, no assignment checking.
+- `IdentifierFormatCheck` (linter) — validates `@cas`/`@inchi`/
+  `@inchikey`/`@smiles` annotation values against the registry;
+  unknown conventions are skipped.
+- `IdentifierConsistencyCheck` (linter) — cross-checks identifier
+  values against the molecule they annotate: InChI formula-layer
+  element counts vs molecule composition (error), SMILES element set
+  vs molecule elements with implicit hydrogens tolerated (warning).
+- `Model::Molecule#element_counts(with_coefficient:)` — public
+  composition API; `#hill_formula` and `#formula_weight` now share it.
+
+### Fixed
+- RSpec suite aborted non-deterministically mid-run (randomly
+  truncated example counts, e.g. 56–748 of 788): CLI commands call
+  `Kernel#exit` even on success, and the cli specs' `run` helper did
+  not trap `SystemExit`, so under random ordering an uncaught exit
+  aborted the suite while reporting "0 failures". The helper now
+  traps it; five consecutive full runs execute all 788 examples.
+- Linter registry re-registration in specs now globs all check files
+  instead of a hardcoded list (new checks no longer vanish from the
+  suite after `Registry.reset`).
+
+## [0.18.1] - 2026-07-21
+
+### Changed
+- Updated gemspec summary and description to mention all
+  beyond-formulas constructs (crystals, spectra, calculations,
+  Z-matrices, reaction mechanisms) and the native CML round-trip
+  via chemicalml.
+- Added `docs_uri` metadata pointing to the AsciiChem documentation
+  site.
+
+## [0.18.0] - 2026-07-21
+
+### Changed
+- Beyond-formulas body validation: MechanismBuilder, SpectrumBuilder,
+  and CalculationBuilder now validate each body line at parse time.
+  Malformed entries (missing `:` separator) raise `ParseError` with
+  the offending line number and content, instead of being silently
+  dropped.
+
+## [0.17.0] - 2026-07-21
+
+### Added
+- `Atom::Point3` value object (Struct with `x`, `y`, `z`, `to_a`,
+  `magnitude`).
+- `Atom#cartesian` and `Atom#fractional` accessors return Point3
+  bundling the flat coordinate fields. Backwards compatible: flat
+  accessors (`x2`/`y2`/`z2`, `x_fract`/`y_fract`/`z_fract`) remain.
+
+## [0.16.0] - 2026-07-21
+
+### Added
+- `Node#to_structural_svg` shortcut — invokes
+  `Formatter::StructuralSvg` for 2D diagram output. For Crystal
+  nodes, projects fractional coordinates onto the ab-plane with a
+  unit cell outline; for molecules with bonds, uses elkrb for
+  graph layout (existing behaviour); falls back to linear Svg
+  otherwise.
+- `Formatter::StructuralSvg#visit_crystal` — renders a Crystal as
+  a 2D projection of fractional coordinates with unit cell outline.
+
+## [0.15.0] - 2026-07-21
+
+### Changed
+- Parser error messages now report `line N, col M` for multi-line
+  inputs instead of `char N`. The caret pointer is positioned on
+  the relevant line. Single-line inputs continue to use the
+  existing char-position format.
+
+## [0.14.0] - 2026-07-21
+
+### Added
+- `lint -f json` CLI option — emits diagnostics as a JSON array for
+  tooling integration (CI, editors, downstream scripts). Each
+  entry has `severity`, `message`, and `node` fields.
+
+## [0.13.0] - 2026-07-21
+
+### Added
+- `Molecule#formula_weight` — sum of `atomic_mass × count` across
+  all atoms (recurses through groups and nested molecules). Returns
+  nil if any element lacks atomic mass data. Examples:
+  `parse("H_2O").nodes.first.formula_weight` returns `18.015`;
+  `parse("C_6H_12O_6")` returns `180.156`.
+- `PeriodicTable.atomic_mass(symbol)` — IUPAC 2021 standard atomic
+  weights for ~50 common elements. Single source of truth for
+  atomic mass data.
+
+### Changed
+- `PeriodicTable::Element` struct gains `atomic_mass` field (nil
+  when unpopulated).
+
+## [0.12.0] - 2026-07-21
+
+### Added
+- `Molecule#hill_formula` — Hill-system canonical formula (C first,
+  then H, then others alphabetically). Useful for indexing and
+  display. `parse("C_2H_6O").nodes.first.hill_formula` returns
+  `"C2H6O"`; `parse("H_2SO_4")` returns `"H2O4S"`.
+
+### Changed
+- `Linter.run` sorts diagnostics by severity (errors first) then by
+  message for stable UX output. Also deduplicates identical
+  (message, node) pairs from different checks.
+- `AsciiChem::Parser` caches `Grammar` and `Transform` instances at
+  the class level instead of allocating per parse. Benchmark: ~15%
+  throughput improvement on repeated parses.
+
+## [0.11.0] - 2026-07-21
+
+### Added
+- **Native CML wire for ZMatrix, Calculation, Mechanism, and
+  reaction conditions.** Completes the native-wire migration arc
+  for all beyond-formulas constructs:
+  - ZMatrix emits as `<molecule>` with `<zMatrix>` child carrying
+    the text form (structural length/angle/torsion children are a
+    future enhancement).
+  - Calculation emits as `<molecule>` with `<propertyList>` of
+    `<property>` children, each with a `<scalar>` carrying value
+    and units.
+  - Mechanism emits as `<reaction>` with `<mechanism>` child.
+    Currently uses the text form via title attribute; structural
+    step-by-step representation is a future enhancement.
+  - Reaction conditions (`<=>[Fe][400C]`) now emit as native
+    `<conditionList>` with `<scalar>` children for above/below,
+    replacing the `aci:conditionsAbove`/`aci:conditionsBelow`
+    attributes used in v0.10.0 and earlier.
+
+### Changed
+- `ConditionsExtensions.inject`: now a no-op when native
+  `<conditionList>` is present (defensive fallback only).
+- `ModelAdapter::FromCanonical`: reads native `<conditionList>`
+  via `conditions_from_canonical`.
+
+## [0.10.0] - 2026-07-21
+
+### Added
+- **Native CML wire for Spectrum.** Spectrum nodes now emit as a
+  `<molecule>` containing a native `<spectrum>` child (with `format`
+  and `condition` attributes) plus a `<peakList>` of `<peak>`
+  elements. Each peak carries `xValue`, `yValue`, `yMultiplicity`,
+  and `title` (assignment) attributes per the CML Schema 3 spec.
+
+### Changed
+- `ModelAdapter::ToCanonical`: new `spectrum_to_canonical` mapper
+  wraps Spectrum in a Molecule wire object with spectrum child.
+- `ModelAdapter::FromCanonical`: detects molecule-with-spectrum and
+  rebuilds as Spectrum node.
+- `Translator::NATIVELY_WIRED`: now includes Spectrum.
+
+## [0.9.0] - 2026-07-21
+
+### Added
+- **Native CML wire for Crystal.** Crystal nodes now emit as a
+  `<molecule>` containing a native `<crystal>` child (with `<scalar>`
+  cells and `<symmetry spaceGroup=...>`) plus an `<atomArray>` with
+  fractional coordinates. Other CML tools can now read AsciiChem
+  crystal output directly without needing the aci: extension
+  namespace. Round-trip preserves all fields. The legacy aci:
+  text-carrier form is still accepted on parse for backwards
+  compatibility.
+
+### Changed
+- `ModelAdapter::ToCanonical`: new `crystal_to_canonical` mapper
+  wraps Crystal in a Molecule wire object.
+- `ModelAdapter::FromCanonical`: detects molecule-with-crystal and
+  rebuilds as Crystal node.
+- `Extensions::TopLevel.collect`: accepts `skip_classes:` parameter
+  to suppress the aci: text carrier for constructs with native wire.
+- `Translator::NATIVELY_WIRED`: registry of construct classes that
+  have been migrated to native wire (currently just Crystal).
+
+## [0.8.0] - 2026-07-21
+
+### Changed
+- `chemicalml` dependency bumped from `~> 0.2.1` to `~> 0.3.0`.
+  chemicalml 0.3.0 fixes the wire serialization gaps that blocked
+  Phases 06-10, 15 (native CML wire for Crystal/Spectrum/ZMatrix/
+  Mechanism/Calculation/conditions). Molecule wire now serializes
+  `<crystal>`, `<spectrum>`, `<zMatrix>`, `<propertyList>` children;
+  Reaction wire now serializes `<conditionList>`, `<spectatorList>`,
+  `<mechanism>` children.
+
+### Added
+- `.github/workflows/release.yml` — manual-dispatch release workflow
+  that pushes the gem to RubyGems. Triggered via `gh workflow run
+  release.yml -f version=X.Y.Z` after the version-bump PR merges.
+  Verifies the input version matches `lib/asciichem/version.rb`.
+
+## [0.7.0] - 2026-07-21
+
+### Added
+- Implicit subscripts on Hydrogen: `H2` now parses as `H_2`, so
+  users can write `H2O`, `CH4`, `NH3` without explicit underscores.
+  Resolves the long-pending feature request without breaking
+  SMILES-style ring closures on other elements (Hydrogen cannot
+  form ring closures — only 1 bond — so bare digits after H are
+  unambiguously subscripts).
+
+### Changed
+- Grammar: new `hydrogen_atom` rule placed before `plain_atom` in
+  the unit dispatch. The `match('[a-z]').absent?` lookahead ensures
+  `He`, `Ho`, etc. fall through to plain_atom unchanged.
+
+## [0.6.0] - 2026-07-20
+
+### Added
+- `Model::OpaqueCml` node + `Cml::OpaqueExtensions` module: preserve
+  unknown CML elements through round-trip as opaque blobs.
+- `Linter::ChargeBalanceCheck`: validates charge conservation in
+  reactions (parallel to BalanceCheck's atom conservation).
+- `Linter::CrystalSanityCheck`, `ZMatrixReferenceCheck`,
+  `SpectrumPeakCheck`: validate cell parameters, ZMatrix references,
+  and spectrum peak data.
+- `Molecule#atom_count`: total atom count recursing through groups
+  and nested molecules with subscripts and multiplicities applied.
+- `Model::Molecule::Property`, `Meta`, `Label`, `Formula` Structs
+  replace Hash-with-magic-keys fields.
+- `Model::Spectrum::Peak`, `Calculation::Property`, `Mechanism::Step`
+  Structs replace Hash-with-magic-keys fields.
+- Formatter visit methods for `Crystal`, `Spectrum`, `Calculation`,
+  `ZMatrix`, `Mechanism`, `OpaqueCml` across MathML, HTML, LaTeX, SVG.
+- CLI smoke coverage for beyond-formulas constructs.
+- Fuzz corpus files 16-20 (crystal, spectrum, calculation, zmatrix,
+  mechanism).
+- Benchmark cases for beyond-formulas constructs.
+
+### Changed
+- `Cml::Extensions` split into `Extensions::AtomAttributes` and
+  `Extensions::TopLevel` sub-modules; facade preserves public API.
+- `Cml::MetadataExtensions` and `Cml::ConditionsExtensions` extracted
+  from inline Translator code as parallel extension channels.
+- `Cml::ID_PREFIXES` is the single source of truth for canonical ID
+  prefixes (atom/bond/molecule/reaction/group).
+- `Extensions.ensure_namespace(root)` shared helper replaces six
+  duplicated `namespace_declared?` / `ensure_namespace` methods.
+- `Model::Bond` owns `CML_ORDER_CODES`, `KIND_BY_CML_ORDER`,
+  `CML_STEREO_CODES` (was duplicated across adapter directions).
+- `Model::Group` owns `BRACKETS` with `{open, close, wire}` attrs.
+- `Model::Reaction` owns `ARROW_BY_WIRE` inverse map.
+- `Model::Crystal` owns `CELL_PARAMS`, `LENGTH_FIELDS`, `ANGLE_FIELDS`,
+  `CELL_LABELS`, `#each_cell_param(format)` as single source for cell
+  parameter labels across formatters.
+- `Extensions::TopLevel::Handler.text_round_trip` and
+  `.source_with_wrapper` factory methods eliminate duplicate lambdas
+  across 8 handlers.
+- `Transform::BuilderHelpers` shared module included by all 5 builder
+  classes.
+- `Linter::Base.register(:name)` pattern — adding a check is one new
+  file + one autoload entry.
+
+### Fixed
+- Empty body braces (`crystal[x]{}`, `spectrum[nmr](){}`, etc.) now
+  parse correctly for all 5 beyond-formulas constructs. Root cause:
+  parslet represents zero-match `.repeat` as `[]` not `""`.
+- Cascade step conditions (`A ->[c1] B ->[c2] C`) now survive CML
+  round-trip. Previously the inline translator code only walked
+  top-level reactions.
+
+## [0.5.1] - 2026-07-16
+
+### Added
+- CML round-trip for all five beyond-formulas constructs via aci:
+  namespace extension elements.
+
+## [0.5.0] - 2026-07-16
+
+### Added
+- Phase 5: reaction mechanism syntax (`mechanism{step1: A -> B;
+  spectator: Na+}`).
+
+## [0.4.1] - 2026-07-16
+
+### Added
+- Phase 3: computational chemistry results (`calc(method/basis){...}`).
+- Phase 4: Z-Matrix internal coordinates (`zmatrix{C1; H2 C1 1.09; ...}`).
+
+## [0.4.0] - 2026-07-16
+
+### Added
+- Phase 1: crystallography syntax (`crystal[NaCl](a=...,sg=...){...}`).
+- Phase 2: spectroscopy syntax (`spectrum[nmr](type=1H,...){...}`).
+
+## [0.3.4] - 2026-07-16
+
+### Added
+- Spin multiplicity (`C@m(2)`), atom title (`C@t("alpha")`), and
+  fractional coordinates (`C@f(0.5,0.5,0.5)`) syntax.
+
+## [0.3.3] - 2026-07-16
+
+### Fixed
+- Property and metadata CML round-trip for chemicalml 0.2.1.
+
+## [0.3.2] - 2026-07-16
+
+### Added
+- Reaction conditions CML round-trip via aci: attributes.
+
+## [0.3.1] - 2026-07-16
+
+### Changed
+- Adapted to chemicalml 0.2.1 (wire classes ARE the model).
+
+## [0.3.0] - 2026-07-15
+
+### Added
+- Full CML support via chemicalml gem.
+- aci: extension namespace for fields CML doesn't natively carry.
+- New syntax: spin multiplicity, atom titles, fractional coordinates,
+  molecule annotations (`@name`, `@inchi`, `@meta`, `@formula`,
+  `@label`, `@mw`, `@title`).
+- Group preservation through CML round-trip via `<aci:group>`.
+- ElectronConfiguration and EmbeddedMath top-level constructs via aci:.
+- `parse-cml` CLI subcommand.
+
+## [0.2.0] - 2026-07-14
+
+### Added
+- Layout module (MoleculeWalker / GraphBuilder / ResultExtractor)
+  using elkrb for 2D structural SVG.
+- StructuralSvg formatter with bond-kind renderer registry.
+- Ring closures (SMILES-style): `C1-C-C-C-C-C1` is cyclohexane.
+
+## [0.1.0] - 2026-07-10
 
 ### Added
 - Initial gem scaffold: autoload tree, version, errors.
-- Core model: `Formula`, `Atom`, `Molecule`, `Group`, `Bond`, `Reaction`,
-  `ElectronConfiguration`, `EmbeddedMath`, `Text`.
+- Core model: `Formula`, `Atom`, `Molecule`, `Group`, `Bond`,
+  `Reaction`, `ElectronConfiguration`, `EmbeddedMath`, `Text`.
 - Parslet parser and transform for v1 constructs.
-- Formatters: MathML and Text (round-trip).
-- Thor-based CLI: `convert`, `roundtrip`, `version`.
+- Formatters: MathML, Text (round-trip), HTML, LaTeX, SVG.
+- Thor-based CLI: `convert`, `roundtrip`, `lint`, `parse-cml`,
+  `version`.
 - Comprehensive RSpec suite with round-trip conformance.
 
-[Unreleased]: https://github.com/asciichem/asciichem-ruby/commits/main
+[Unreleased]: https://github.com/asciichem/asciichem-ruby/compare/v0.20.0...HEAD
+[0.20.0]: https://github.com/asciichem/asciichem-ruby/compare/v0.19.0...v0.20.0
+[0.18.1]: https://github.com/asciichem/asciichem-ruby/compare/v0.18.0...v0.18.1
+[0.18.0]: https://github.com/asciichem/asciichem-ruby/compare/v0.17.0...v0.18.0
+[0.17.0]: https://github.com/asciichem/asciichem-ruby/compare/v0.16.0...v0.17.0
+[0.16.0]: https://github.com/asciichem/asciichem-ruby/compare/v0.15.0...v0.16.0
+[0.15.0]: https://github.com/asciichem/asciichem-ruby/compare/v0.14.0...v0.15.0
+[0.14.0]: https://github.com/asciichem/asciichem-ruby/compare/v0.13.0...v0.14.0
+[0.13.0]: https://github.com/asciichem/asciichem-ruby/compare/v0.12.0...v0.13.0
+[0.12.0]: https://github.com/asciichem/asciichem-ruby/compare/v0.11.0...v0.12.0
+[0.11.0]: https://github.com/asciichem/asciichem-ruby/compare/v0.10.0...v0.11.0
+[0.10.0]: https://github.com/asciichem/asciichem-ruby/compare/v0.9.0...v0.10.0
+[0.9.0]: https://github.com/asciichem/asciichem-ruby/compare/v0.8.0...v0.9.0
+[0.8.0]: https://github.com/asciichem/asciichem-ruby/compare/v0.7.0...v0.8.0
+[0.7.0]: https://github.com/asciichem/asciichem-ruby/compare/v0.6.0...v0.7.0
+[0.6.0]: https://github.com/asciichem/asciichem-ruby/compare/v0.5.1...v0.6.0
+[0.5.1]: https://github.com/asciichem/asciichem-ruby/compare/v0.5.0...v0.5.1
+[0.5.0]: https://github.com/asciichem/asciichem-ruby/compare/v0.4.1...v0.5.0
+[0.4.1]: https://github.com/asciichem/asciichem-ruby/compare/v0.4.0...v0.4.1
+[0.4.0]: https://github.com/asciichem/asciichem-ruby/compare/v0.3.4...v0.4.0
+[0.3.4]: https://github.com/asciichem/asciichem-ruby/compare/v0.3.3...v0.3.4
+[0.3.3]: https://github.com/asciichem/asciichem-ruby/compare/v0.3.2...v0.3.3
+[0.3.2]: https://github.com/asciichem/asciichem-ruby/compare/v0.3.1...v0.3.2
+[0.3.1]: https://github.com/asciichem/asciichem-ruby/compare/v0.3.0...v0.3.1
+[0.3.0]: https://github.com/asciichem/asciichem-ruby/compare/v0.2.0...v0.3.0
+[0.2.0]: https://github.com/asciichem/asciichem-ruby/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/asciichem/asciichem-ruby/releases/tag/v0.1.0

data/RELEASING.md

@@ -83,10 +83,15 @@ tag.
 
 == Publish to RubyGems
 
-[source,sh]
-----
-gem push pkg/asciichem-0.X.Y.gem
-----
+The Release workflow (`.github/workflows/release.yml`) publishes via
+https://guides.rubygems.org/trusted-publishing/[RubyGems trusted publishing]
+(OIDC) — there are no API keys. Its trusted publisher is registered on
+https://rubygems.org (repository `asciichem/asciichem-ruby`, workflow
+`release.yml`, no environment).
+
+On the repository's Actions tab, run the "Release" workflow with the
+version number. It verifies the version matches `version.rb`, builds
+the gem, and pushes it using the workflow's GitHub OIDC identity.
 
 Verify at https://rubygems.org/gems/asciichem.