asciichem 0.19.0 → 0.20.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 49f3af36729edc3293bb97099d74298533a509ae26aa3c14151a7cef743f654f
-  data.tar.gz: 24f5d0778e9f7dce477423b27b1ec5ebcab08472452389f126473234e8500a19
+  metadata.gz: 6a77da515ac52e848a4ff0f5855a595cb81d71a36c18b4991d875d682d2c3598
+  data.tar.gz: 70c14be9ddec1e767ddddef09a1ad91a02f996f1fdd22645d0269c4de7e96020
 SHA512:
-  metadata.gz: 599beaeb33d3bf776076632c83d2c92c16a08571088f3bb272163f61a9082e250af150b3300a80821fc3bb6ab5ffa8d65cc8b5007b4860f0dace0a94b70aaf83
-  data.tar.gz: 6fbc557626b9767110bc142c54ae6858b644d563af73f431bd48d8dbd7dabdfeeb79b7ecbb498474d791b35f1717b9ae28689ee1630f352fa48a3e0abcf966a6
+  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

@@ -11,14 +11,17 @@ on:
 jobs:
   release:
     runs-on: ubuntu-latest
-    environment: release
+    # 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
-      packages: write
+      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')
@@ -31,21 +34,8 @@ jobs:
         with:
           ruby-version: "3.4"
           bundler-cache: true
-      - name: Build gem
-        run: bundle exec rake build
-      - name: Set up RubyGems credentials
-        env:
-          RUBYGEMS_API_KEY: ${{ secrets.RUBYGEMS_API_KEY }}
-        run: |
-          mkdir -p $HOME/.gem
-          cat > $HOME/.gem/credentials <<EOF
-          ---
-          :rubygems_api_key: ${RUBYGEMS_API_KEY}
-          EOF
-          chmod 0600 $HOME/.gem/credentials
-      - name: Push to RubyGems
-        run: |
-          gem push pkg/asciichem-${{ inputs.version }}.gem
+      # 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"

data/.gitignore

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

data/CHANGELOG.md

@@ -3,6 +3,22 @@
 All notable changes to AsciiChem are documented here.
 This project follows [Semantic Versioning](https://semver.org/).
 
+## [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
@@ -347,7 +363,8 @@ This project follows [Semantic Versioning](https://semver.org/).
   `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

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.
 

data/asciichem.gemspec

@@ -35,8 +35,11 @@ Gem::Specification.new do |spec|
 
   spec.add_dependency "chemicalml", "~> 0.3.0"
   spec.add_dependency "elkrb", "~> 1.0"
+  spec.add_dependency "lutaml-model", ">= 0.8", "< 2"
   spec.add_dependency "nokogiri", "~> 1.16"
   spec.add_dependency "parslet", "~> 2.0"
   spec.add_dependency "plurimath", "~> 0.8"
   spec.add_dependency "thor", "~> 1.3"
+
+  spec.add_development_dependency "asciichem-model", "~> 0.3.4"
 end

data/lib/asciichem/model/node.rb

@@ -62,6 +62,14 @@ module AsciiChem
         AsciiChem::Cml.from_asciichem(self)
       end
 
+      # Canonical JSON wire form (asciichem-model v1). The Text
+      # formatter canonicalises AsciiChem text; this canonicalises
+      # the semantic model itself — the interchange format every
+      # implementation must parse and emit.
+      def to_model_json
+        AsciiChem::WireAdapter.to_model_json(self)
+      end
+
       # Subclasses override to expose the attributes that participate in
       # equality. Default: empty (so two bare Nodes are equal).
       def value_attributes

data/lib/asciichem/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module AsciiChem
-  VERSION = "0.19.0"
+  VERSION = "0.20.0"
 end

data/lib/asciichem/wire/base.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module AsciiChem
+  module Wire
+    # Common base for wire nodes: declares the `type` discriminator
+    # attribute and registers the class under its wire type string.
+    # The converter sets `type` explicitly on construction because
+    # lutaml-model omits default values on serialisation.
+    class Base < Lutaml::Model::Serializable
+      class << self
+        def wire_type(name = nil)
+          return @wire_type if name.nil?
+
+          @wire_type = name.to_s
+          AsciiChem::Wire::REGISTRY[name.to_s] = self
+        end
+      end
+
+      attribute :type, :string
+      json do
+        map "type", to: :type
+      end
+    end
+  end
+end

data/lib/asciichem/wire/chemistry.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module AsciiChem
+  module Wire
+    # Chemistry document wire classes: formula (root), reactions,
+    # electron configurations, embedded math, text.
+    class Formula < Base
+      wire_type "formula"
+
+      attribute :nodes, Base, collection: true
+      json do
+        map "nodes", to: :nodes
+      end
+    end
+
+    class ReactionConditions < Lutaml::Model::Serializable
+      attribute :above, :string
+      attribute :below, :string
+      json do
+        map "above", to: :above
+        map "below", to: :below
+      end
+    end
+
+    class Reaction < Base
+      wire_type "reaction"
+
+      attribute :reactants, "AsciiChem::Wire::Molecule", collection: true
+      attribute :products, "AsciiChem::Wire::Molecule", collection: true
+      attribute :arrow, :string
+      attribute :conditions, ReactionConditions
+      json do
+        map "reactants", to: :reactants
+        map "products", to: :products
+        map "arrow", to: :arrow
+        map "conditions", to: :conditions
+      end
+    end
+
+    class ReactionCascade < Base
+      wire_type "reaction-cascade"
+
+      attribute :steps, "AsciiChem::Wire::Reaction", collection: true
+      json do
+        map "steps", to: :steps
+      end
+    end
+
+    class OrbitalOccupancy < Lutaml::Model::Serializable
+      attribute :orbital, :string
+      attribute :occupancy, :string
+      json do
+        map "orbital", to: :orbital
+        map "occupancy", to: :occupancy
+      end
+    end
+
+    class TermSymbol < Lutaml::Model::Serializable
+      attribute :multiplicity, :string
+      attribute :letter, :string
+      attribute :j_value, :string
+      json do
+        map "multiplicity", to: :multiplicity
+        map "letter", to: :letter
+        map "jValue", to: :j_value
+      end
+    end
+
+    class ElectronConfiguration < Base
+      wire_type "electron-configuration"
+
+      attribute :orbitals, OrbitalOccupancy, collection: true
+      attribute :term_symbol, TermSymbol
+      json do
+        map "orbitals", to: :orbitals
+        map "termSymbol", to: :term_symbol
+      end
+    end
+
+    class EmbeddedMath < Base
+      wire_type "embedded-math"
+
+      attribute :source, :string
+      json do
+        map "source", to: :source
+      end
+    end
+
+    class Text < Base
+      wire_type "text"
+
+      attribute :content, :string
+      json do
+        map "content", to: :content
+      end
+    end
+  end
+end

data/lib/asciichem/wire/core.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module AsciiChem
+  module Wire
+    # Core node wire classes: atom, identifier, name, molecule,
+    # group, bond. Field-for-field with schemas/v1. Order matters:
+    # referenced classes are declared before their referrers.
+    class Atom < Base
+      wire_type "atom"
+
+      attribute :element, :string
+      attribute :isotope, :string
+      attribute :charge, :string
+      attribute :subscript, :string
+      attribute :oxidation_state, :string
+      attribute :lone_pairs, :integer
+      attribute :radical_electrons, :integer
+      attribute :ring_closures, :string
+      json do
+        map "element", to: :element
+        map "isotope", to: :isotope
+        map "charge", to: :charge
+        map "subscript", to: :subscript
+        map "oxidationState", to: :oxidation_state
+        map "lonePairs", to: :lone_pairs
+        map "radicalElectrons", to: :radical_electrons
+        map "ringClosures", to: :ring_closures
+      end
+    end
+
+    class Identifier < Base
+      wire_type "identifier"
+
+      attribute :value, :string
+      attribute :convention, :string
+      attribute :dict_ref, :string
+      json do
+        map "value", to: :value
+        map "convention", to: :convention
+        map "dictRef", to: :dict_ref
+      end
+    end
+
+    class Name < Base
+      wire_type "name"
+
+      attribute :content, :string
+      attribute :convention, :string
+      attribute :dict_ref, :string
+      json do
+        map "content", to: :content
+        map "convention", to: :convention
+        map "dictRef", to: :dict_ref
+      end
+    end
+
+    class Molecule < Base
+      wire_type "molecule"
+
+      attribute :nodes, Base, collection: true
+      attribute :coefficient, :string
+      attribute :identifiers, Identifier, collection: true
+      json do
+        map "nodes", to: :nodes
+        map "coefficient", to: :coefficient
+        map "identifiers", to: :identifiers
+      end
+    end
+
+    class Group < Base
+      wire_type "group"
+
+      attribute :nodes, Base, collection: true
+      attribute :multiplicity, :string
+      attribute :bracket, :string
+      json do
+        map "nodes", to: :nodes
+        map "multiplicity", to: :multiplicity
+        map "bracket", to: :bracket
+      end
+    end
+
+    class Bond < Base
+      wire_type "bond"
+
+      attribute :kind, :string
+      json do
+        map "kind", to: :kind
+      end
+    end
+  end
+end

data/lib/asciichem/wire/extended.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+module AsciiChem
+  module Wire
+    # Beyond-formulas wire classes: mechanism, spectrum, crystal,
+    # zmatrix, calculation. Emission covers the full v1 schemas;
+    # ingestion (from_wire) is currently implemented for the core
+    # chemistry set only — see WireAdapter.
+    class MechanismStep < Lutaml::Model::Serializable
+      attribute :label, :string
+      attribute :reaction, "AsciiChem::Wire::Reaction"
+      json do
+        map "label", to: :label
+        map "reaction", to: :reaction
+      end
+    end
+
+    class Mechanism < Base
+      wire_type "mechanism"
+
+      attribute :steps, MechanismStep, collection: true
+      attribute :spectators, "AsciiChem::Wire::Molecule", collection: true
+      json do
+        map "steps", to: :steps
+        map "spectators", to: :spectators
+      end
+    end
+
+    class SpectrumPeak < Lutaml::Model::Serializable
+      attribute :position, :string
+      attribute :intensity, :string
+      attribute :multiplicity, :string
+      attribute :assignment, :string
+      json do
+        map "position", to: :position
+        map "intensity", to: :intensity
+        map "multiplicity", to: :multiplicity
+        map "assignment", to: :assignment
+      end
+    end
+
+    class Spectrum < Base
+      wire_type "spectrum"
+
+      attribute :technique, :string
+      attribute :params, Lutaml::Model::Type::Hash
+      attribute :peaks, SpectrumPeak, collection: true
+      json do
+        map "technique", to: :technique
+        map "params", to: :params
+        map "peaks", to: :peaks
+      end
+    end
+
+    class Crystal < Base
+      wire_type "crystal"
+
+      attribute :name, :string
+      attribute :a, :float
+      attribute :b, :float
+      attribute :c, :float
+      attribute :alpha, :float
+      attribute :beta, :float
+      attribute :gamma, :float
+      attribute :spacegroup, :string
+      attribute :atoms, Atom, collection: true
+      json do
+        map "name", to: :name
+        map "a", to: :a
+        map "b", to: :b
+        map "c", to: :c
+        map "alpha", to: :alpha
+        map "beta", to: :beta
+        map "gamma", to: :gamma
+        map "spacegroup", to: :spacegroup
+        map "atoms", to: :atoms
+      end
+    end
+
+    class ZRow < Lutaml::Model::Serializable
+      attribute :atom, :string
+      attribute :ref1, :string
+      attribute :distance, :string
+      attribute :ref2, :string
+      attribute :angle, :string
+      attribute :ref3, :string
+      attribute :dihedral, :string
+      json do
+        map "atom", to: :atom
+        map "ref1", to: :ref1
+        map "distance", to: :distance
+        map "ref2", to: :ref2
+        map "angle", to: :angle
+        map "ref3", to: :ref3
+        map "dihedral", to: :dihedral
+      end
+    end
+
+    class ZMatrix < Base
+      wire_type "zmatrix"
+
+      attribute :rows, ZRow, collection: true
+      json do
+        map "rows", to: :rows
+      end
+    end
+
+    class CalculatedProperty < Lutaml::Model::Serializable
+      attribute :title, :string
+      attribute :value, :string
+      attribute :units, :string
+      attribute :dict_ref, :string
+      attribute :convention, :string
+      json do
+        map "title", to: :title
+        map "value", to: :value
+        map "units", to: :units
+        map "dictRef", to: :dict_ref
+        map "convention", to: :convention
+      end
+    end
+
+    class Calculation < Base
+      wire_type "calculation"
+
+      attribute :method, :string
+      attribute :basis, :string
+      attribute :properties, CalculatedProperty, collection: true
+      json do
+        map "method", to: :method
+        map "basis", to: :basis
+        map "properties", to: :properties
+      end
+    end
+  end
+end

data/lib/asciichem/wire/identity.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module AsciiChem
+  module Wire
+    # Identity wire classes: provenance and the resolved substance
+    # record produced by resolver sources (TODO.impl 38+).
+    class Provenance < Base
+      wire_type "provenance"
+
+      attribute :source, :string
+      attribute :retrieved_at, :string
+      attribute :source_version, :string
+      attribute :attribution, :string
+      json do
+        map "source", to: :source
+        map "retrievedAt", to: :retrieved_at
+        map "sourceVersion", to: :source_version
+        map "attribution", to: :attribution
+      end
+    end
+
+    class ProvenancedIdentifier < Lutaml::Model::Serializable
+      attribute :identifier, Identifier
+      attribute :provenance, Provenance
+      json do
+        map "identifier", to: :identifier
+        map "provenance", to: :provenance
+      end
+    end
+
+    class ProvenancedProperty < Lutaml::Model::Serializable
+      attribute :name, :string
+      attribute :value, :string
+      attribute :units, :string
+      attribute :provenance, Provenance
+      json do
+        map "name", to: :name
+        map "value", to: :value
+        map "units", to: :units
+        map "provenance", to: :provenance
+      end
+    end
+
+    class SubstanceRecord < Base
+      wire_type "substance-record"
+
+      attribute :preferred_name, :string
+      attribute :synonyms, :string, collection: true
+      attribute :formula, :string
+      attribute :molecular_weight, :float
+      attribute :identifiers, ProvenancedIdentifier, collection: true
+      attribute :properties, ProvenancedProperty, collection: true
+      json do
+        map "preferredName", to: :preferred_name
+        map "synonyms", to: :synonyms
+        map "formula", to: :formula
+        map "molecularWeight", to: :molecular_weight
+        map "identifiers", to: :identifiers
+        map "properties", to: :properties
+      end
+    end
+  end
+end

data/lib/asciichem/wire.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+
+module AsciiChem
+  # Canonical wire form of the semantic model (the JSON interchange
+  # format defined by asciichem-model v1). Wire classes are
+  # lutaml-model Serializables: every (de)serialization goes through
+  # the framework's `json do map ... end` declarations — never
+  # hand-rolled key manipulation. AsciiChem::WireAdapter converts
+  # between the domain Model::* tree and this wire tree, exactly as
+  # ModelAdapter bridges AsciiChem::Model and Chemicalml::Model.
+  module Wire
+    # Discriminator ("atom", "molecule", ...) => wire class. Filled
+    # by Base.wire_type at class-definition time.
+    REGISTRY = {}
+
+    autoload :Base, "asciichem/wire/base"
+    autoload :Atom, "asciichem/wire/core"
+    autoload :Molecule, "asciichem/wire/core"
+    autoload :Group, "asciichem/wire/core"
+    autoload :Bond, "asciichem/wire/core"
+    autoload :Identifier, "asciichem/wire/core"
+    autoload :Name, "asciichem/wire/core"
+    autoload :Formula, "asciichem/wire/chemistry"
+    autoload :Reaction, "asciichem/wire/chemistry"
+    autoload :ReactionConditions, "asciichem/wire/chemistry"
+    autoload :ReactionCascade, "asciichem/wire/chemistry"
+    autoload :ElectronConfiguration, "asciichem/wire/chemistry"
+    autoload :OrbitalOccupancy, "asciichem/wire/chemistry"
+    autoload :TermSymbol, "asciichem/wire/chemistry"
+    autoload :EmbeddedMath, "asciichem/wire/chemistry"
+    autoload :Text, "asciichem/wire/chemistry"
+    autoload :Mechanism, "asciichem/wire/extended"
+    autoload :MechanismStep, "asciichem/wire/extended"
+    autoload :Spectrum, "asciichem/wire/extended"
+    autoload :SpectrumPeak, "asciichem/wire/extended"
+    autoload :Crystal, "asciichem/wire/extended"
+    autoload :ZMatrix, "asciichem/wire/extended"
+    autoload :ZRow, "asciichem/wire/extended"
+    autoload :Calculation, "asciichem/wire/extended"
+    autoload :CalculatedProperty, "asciichem/wire/extended"
+    autoload :Provenance, "asciichem/wire/identity"
+    autoload :SubstanceRecord, "asciichem/wire/identity"
+    autoload :ProvenancedIdentifier, "asciichem/wire/identity"
+    autoload :ProvenancedProperty, "asciichem/wire/identity"
+
+    # Eagerly trigger every autoload so wire classes register their
+    # discriminators before any lookup (same pattern as Linter).
+    constants.each { |name| const_get(name) unless name == :REGISTRY }
+  end
+end

data/lib/asciichem/wire_adapter.rb

@@ -0,0 +1,361 @@
+# frozen_string_literal: true
+
+module AsciiChem
+  # Converts between the domain semantic model (AsciiChem::Model::*)
+  # and the canonical wire form (AsciiChem::Wire::*). This is a
+  # model-to-model translation in the spirit of ModelAdapter — every
+  # (de)serialisation to/from JSON itself is performed by lutaml-model
+  # on the Wire classes; this adapter only routes types and maps
+  # fields.
+  #
+  # Emission (to_wire/to_model_json) covers every wire type.
+  # Ingestion (from_wire/from_model_json) currently covers the
+  # lossless core set: formula, atom, molecule, group, bond,
+  # identifier, name, reaction (+conditions), reaction-cascade,
+  # electron-configuration, embedded-math, text. The beyond-formulas
+  # nodes (mechanism, spectrum, crystal, zmatrix, calculation) are
+  # emission-only until their round-trip acceptance lands in the
+  # corpus.
+  module WireAdapter
+    CORE_INGEST_TYPES = %w[
+      formula atom molecule group bond identifier name reaction
+      reaction-cascade electron-configuration embedded-math text
+    ].freeze
+
+    class << self
+      def to_model_json(formula)
+        to_wire(formula).to_json
+      end
+
+      def from_model_json(json)
+        from_wire(wire_tree_from_hash(JSON.parse(json)))
+      end
+
+      # domain -> wire ------------------------------------------------
+
+      def to_wire(node)
+        case node
+        when AsciiChem::Model::Formula then formula_to_wire(node)
+        when AsciiChem::Model::Molecule then molecule_to_wire(node)
+        when AsciiChem::Model::Group then group_to_wire(node)
+        when AsciiChem::Model::Atom then atom_to_wire(node)
+        when AsciiChem::Model::Bond then bond_to_wire(node)
+        when AsciiChem::Model::Identifier then identifier_to_wire(node)
+        when AsciiChem::Model::Name then name_to_wire(node)
+        when AsciiChem::Model::Reaction then reaction_to_wire(node)
+        when AsciiChem::Model::ReactionCascade then cascade_to_wire(node)
+        when AsciiChem::Model::ElectronConfiguration then econfig_to_wire(node)
+        when AsciiChem::Model::EmbeddedMath then math_to_wire(node)
+        when AsciiChem::Model::Text then text_to_wire(node)
+        when AsciiChem::Model::Mechanism then mechanism_to_wire(node)
+        when AsciiChem::Model::Spectrum then spectrum_to_wire(node)
+        when AsciiChem::Model::Crystal then crystal_to_wire(node)
+        when AsciiChem::Model::ZMatrix then zmatrix_to_wire(node)
+        when AsciiChem::Model::Calculation then calculation_to_wire(node)
+        else raise ArgumentError, "no wire form for #{node.class}"
+        end
+      end
+
+      # wire -> domain ------------------------------------------------
+
+      def from_wire(wire)
+        type = wire.type
+        unless CORE_INGEST_TYPES.include?(type)
+          raise ArgumentError, "wire ingestion not implemented for #{type.inspect}"
+        end
+
+        send(:"#{type.tr('-', '_')}_from_wire", wire)
+      end
+
+      # Discriminator-routed tree construction from a parsed JSON
+      # hash. Per-node deserialisation stays in lutaml-model; this
+      # only routes `type` and re-injects routed children into
+      # polymorphic collections (which lutaml deserialises flat).
+      def wire_tree_from_hash(hash)
+        type = hash.fetch("type") { raise KeyError, "wire node missing type discriminator" }
+        klass = AsciiChem::Wire::REGISTRY.fetch(type) do
+          raise KeyError, "unknown wire node type #{type.inspect}"
+        end
+
+        wire = klass.from_json(JSON.generate(hash))
+        case type
+        when "formula", "molecule", "group"
+          wire.nodes = hash.fetch("nodes", []).map { |child| wire_tree_from_hash(child) }
+        when "reaction"
+          wire.reactants = hash.fetch("reactants", []).map { |child| wire_tree_from_hash(child) }
+          wire.products = hash.fetch("products", []).map { |child| wire_tree_from_hash(child) }
+        when "reaction-cascade"
+          wire.steps = hash.fetch("steps", []).map { |child| wire_tree_from_hash(child) }
+        end
+        wire
+      end
+
+      private
+
+      def formula_to_wire(node)
+        AsciiChem::Wire::Formula.new(type: "formula", nodes: node.nodes.map { |n| to_wire(n) })
+      end
+
+      def atom_to_wire(atom)
+        AsciiChem::Wire::Atom.new(
+          type: "atom",
+          element: atom.element,
+          isotope: digits_or_nil(atom.isotope), charge: str_or_nil(atom.charge),
+          subscript: digits_or_nil(atom.subscript),
+          oxidation_state: str_or_nil(atom.oxidation_state),
+          lone_pairs: int_or_nil(atom.lone_pairs),
+          radical_electrons: int_or_nil(atom.radical_electrons),
+          ring_closures: str_or_nil(atom.ring_closures)
+        )
+      end
+
+      # Fuzz corpus inputs like `H_{2a}O` parse with the raw braced
+      # text in the subscript field (the Text formatter round-trips it
+      # verbatim by design). The canonical wire form carries only
+      # schema-clean values; junk never enters the wire.
+      def digits_or_nil(value)
+        str_or_nil(value)&.then { |s| s.match?(/\A\d+\z/) ? s : nil }
+      end
+
+      def str_or_nil(value)
+        value.is_a?(String) ? value : nil
+      end
+
+      def int_or_nil(value)
+        value.is_a?(Integer) ? value : nil
+      end
+
+      def molecule_to_wire(node)
+        AsciiChem::Wire::Molecule.new(
+          type: "molecule",
+          nodes: node.nodes.map { |n| to_wire(n) },
+          coefficient: node.coefficient,
+          identifiers: node.identifiers.map { |i| identifier_to_wire(i) }
+        )
+      end
+
+      def group_to_wire(node)
+        AsciiChem::Wire::Group.new(
+          type: "group",
+          nodes: node.nodes.map { |n| to_wire(n) },
+          multiplicity: node.multiplicity,
+          bracket: node.bracket.to_s
+        )
+      end
+
+      def bond_to_wire(node)
+        AsciiChem::Wire::Bond.new(type: "bond", kind: node.kind.to_s)
+      end
+
+      def identifier_to_wire(node)
+        AsciiChem::Wire::Identifier.new(
+          type: "identifier",
+          value: node.value, convention: node.convention.to_s, dict_ref: node.dict_ref
+        )
+      end
+
+      def name_to_wire(node)
+        AsciiChem::Wire::Name.new(
+          type: "name",
+          content: node.content, convention: node.convention, dict_ref: node.dict_ref
+        )
+      end
+
+      def reaction_to_wire(node)
+        AsciiChem::Wire::Reaction.new(
+          type: "reaction",
+          reactants: node.reactants.map { |m| molecule_to_wire(m) },
+          products: node.products.map { |m| molecule_to_wire(m) },
+          arrow: node.arrow.to_s,
+          conditions: conditions_to_wire(node.conditions)
+        )
+      end
+
+      def conditions_to_wire(conditions)
+        return nil unless conditions
+
+        AsciiChem::Wire::ReactionConditions.new(above: conditions.above, below: conditions.below)
+      end
+
+      def cascade_to_wire(node)
+        AsciiChem::Wire::ReactionCascade.new(
+          type: "reaction-cascade",
+          steps: node.steps.map { |r| reaction_to_wire(r) }
+        )
+      end
+
+      def econfig_to_wire(node)
+        AsciiChem::Wire::ElectronConfiguration.new(
+          type: "electron-configuration",
+          orbitals: node.orbitals.map do |(label, count)|
+            AsciiChem::Wire::OrbitalOccupancy.new(orbital: label.to_s, occupancy: count.to_s)
+          end,
+          term_symbol: term_symbol_to_wire(node.term_symbol)
+        )
+      end
+
+      def term_symbol_to_wire(term)
+        return nil unless term
+
+        AsciiChem::Wire::TermSymbol.new(
+          multiplicity: term.multiplicity.to_s, letter: term.letter.to_s, j_value: term.j_value.to_s
+        )
+      end
+
+      def math_to_wire(node)
+        AsciiChem::Wire::EmbeddedMath.new(type: "embedded-math", source: node.source)
+      end
+
+      def text_to_wire(node)
+        AsciiChem::Wire::Text.new(type: "text", content: node.content)
+      end
+
+      def mechanism_to_wire(node)
+        AsciiChem::Wire::Mechanism.new(
+          type: "mechanism",
+          steps: node.steps.map do |step|
+            AsciiChem::Wire::MechanismStep.new(label: step.label, reaction: reaction_to_wire(step.reaction))
+          end,
+          spectators: node.spectators.map { |m| molecule_to_wire(m) }
+        )
+      end
+
+      def spectrum_to_wire(node)
+        AsciiChem::Wire::Spectrum.new(
+          type: "spectrum",
+          technique: node.type,
+          params: node.params,
+          peaks: node.peaks.map do |peak|
+            AsciiChem::Wire::SpectrumPeak.new(
+              position: peak.position, intensity: peak.intensity,
+              multiplicity: peak.multiplicity, assignment: peak.assignment
+            )
+          end
+        )
+      end
+
+      def crystal_to_wire(node)
+        AsciiChem::Wire::Crystal.new(
+          type: "crystal",
+          name: node.name, a: node.a, b: node.b, c: node.c,
+          alpha: node.alpha, beta: node.beta, gamma: node.gamma,
+          spacegroup: node.spacegroup,
+          atoms: node.atoms.map { |atom| atom_to_wire(atom) }
+        )
+      end
+
+      def zmatrix_to_wire(node)
+        AsciiChem::Wire::ZMatrix.new(
+          type: "zmatrix",
+          rows: node.rows.map do |row|
+            AsciiChem::Wire::ZRow.new(
+              atom: row.atom, ref1: row.ref1, distance: row.distance,
+              ref2: row.ref2, angle: row.angle, ref3: row.ref3, dihedral: row.dihedral
+            )
+          end
+        )
+      end
+
+      def calculation_to_wire(node)
+        AsciiChem::Wire::Calculation.new(
+          type: "calculation",
+          method: node.method, basis: node.basis,
+          properties: node.properties.map do |prop|
+            AsciiChem::Wire::CalculatedProperty.new(
+              title: prop.title, value: prop.value, units: prop.units,
+              dict_ref: prop.dict_ref, convention: prop.convention
+            )
+          end
+        )
+      end
+
+      # -- ingestion (core set) ----------------------------------------
+
+      def formula_from_wire(wire)
+        AsciiChem::Model::Formula.new(nodes: wire.nodes.map { |n| from_wire(n) })
+      end
+
+      def atom_from_wire(wire)
+        AsciiChem::Model::Atom.new(
+          element: wire.element, isotope: wire.isotope, subscript: wire.subscript,
+          charge: wire.charge, oxidation_state: wire.oxidation_state,
+          lone_pairs: wire.lone_pairs, radical_electrons: wire.radical_electrons,
+          ring_closures: wire.ring_closures
+        )
+      end
+
+      def molecule_from_wire(wire)
+        AsciiChem::Model::Molecule.new(
+          nodes: Array(wire.nodes).map { |n| from_wire(n) },
+          coefficient: wire.coefficient,
+          identifiers: Array(wire.identifiers).map { |i| identifier_from_wire(i) }
+        )
+      end
+
+      def group_from_wire(wire)
+        AsciiChem::Model::Group.new(
+          nodes: wire.nodes.map { |n| from_wire(n) },
+          multiplicity: wire.multiplicity,
+          bracket: wire.bracket&.to_sym
+        )
+      end
+
+      def bond_from_wire(wire)
+        AsciiChem::Model::Bond.new(kind: wire.kind.to_sym)
+      end
+
+      def identifier_from_wire(wire)
+        AsciiChem::Model::Identifier.new(
+          value: wire.value, convention: wire.convention, dict_ref: wire.dict_ref
+        )
+      end
+
+      def name_from_wire(wire)
+        AsciiChem::Model::Name.new(
+          content: wire.content, convention: wire.convention, dict_ref: wire.dict_ref
+        )
+      end
+
+      def reaction_from_wire(wire)
+        conditions = wire.conditions &&
+                     AsciiChem::Model::Reaction::Conditions.new(above: wire.conditions.above,
+                                                                below: wire.conditions.below)
+        AsciiChem::Model::Reaction.new(
+          reactants: Array(wire.reactants).map { |m| molecule_from_wire(m) },
+          products: Array(wire.products).map { |m| molecule_from_wire(m) },
+          arrow: wire.arrow.to_sym,
+          conditions: conditions
+        )
+      end
+
+      def reaction_cascade_from_wire(wire)
+        AsciiChem::Model::ReactionCascade.new(
+          steps: Array(wire.steps).map { |r| reaction_from_wire(r) }
+        )
+      end
+
+      def electron_configuration_from_wire(wire)
+        AsciiChem::Model::ElectronConfiguration.new(
+          orbitals: Array(wire.orbitals).map { |o| [o.orbital, o.occupancy] },
+          term_symbol: wire.term_symbol &&
+                       AsciiChem::Model::ElectronConfiguration::TermSymbol.new(
+                         multiplicity: wire.term_symbol.multiplicity,
+                         letter: wire.term_symbol.letter,
+                         j_value: wire.term_symbol.j_value
+                       )
+        )
+      end
+
+      def embedded_math_from_wire(wire)
+        AsciiChem::Model::EmbeddedMath.new(
+          formula: Plurimath::Asciimath.new(wire.source).to_formula,
+          source: wire.source
+        )
+      end
+
+      def text_from_wire(wire)
+        AsciiChem::Model::Text.new(content: wire.content)
+      end
+    end
+  end
+end

data/lib/asciichem.rb

@@ -27,9 +27,18 @@ module AsciiChem
   autoload :RingBonds, "asciichem/ring_bonds"
   autoload :Transform, "asciichem/transform"
   autoload :VERSION, "asciichem/version"
+  autoload :Wire, "asciichem/wire"
+  autoload :WireAdapter, "asciichem/wire_adapter"
   autoload :XmlBuilder, "asciichem/xml_builder"
 
   def self.parse(text)
     Parser.new(text).parse
   end
+
+  # Rebuilds the semantic model from the canonical JSON wire form
+  # (asciichem-model v1) — the interchange format every
+  # implementation emits.
+  def self.from_model_json(json)
+    WireAdapter.from_model_json(json)
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: asciichem
 version: !ruby/object:Gem::Version
-  version: 0.19.0
+  version: 0.20.0
 platform: ruby
 authors:
 - Ribose Inc.
@@ -37,6 +37,26 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: lutaml-model
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.8'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.8'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
 - !ruby/object:Gem::Dependency
   name: nokogiri
   requirement: !ruby/object:Gem::Requirement
@@ -93,6 +113,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: asciichem-model
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.3.4
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.3.4
 description: AsciiChem is an ASCII syntax for representing chemical formulae, reactions,
   electron configurations, bonds, crystals, spectra, calculations, Z-matrices, and
   reaction mechanisms. It parses to a semantic model and renders to MathML, HTML,
@@ -194,6 +228,13 @@ files:
 - lib/asciichem/ring_bonds.rb
 - lib/asciichem/transform.rb
 - lib/asciichem/version.rb
+- lib/asciichem/wire.rb
+- lib/asciichem/wire/base.rb
+- lib/asciichem/wire/chemistry.rb
+- lib/asciichem/wire/core.rb
+- lib/asciichem/wire/extended.rb
+- lib/asciichem/wire/identity.rb
+- lib/asciichem/wire_adapter.rb
 - lib/asciichem/xml_builder.rb
 homepage: https://www.asciichem.org
 licenses:
@@ -218,7 +259,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.16
+rubygems_version: 3.6.9
 specification_version: 4
 summary: ASCII syntax for chemistry formulae, reactions, structures, and spectroscopy.
 test_files: []