asciichem 0.31.2 → 0.31.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b221962f73e48a95f8d177ffd94fdf051b135f70d014b9b42aaa5d7fb1005840
-  data.tar.gz: b2b40147701ba90d0b8b9ed014202836fbc65cbb22f14fa98f3f1195cdd3b7bd
+  metadata.gz: ab5305dc2ec00320b62efbfae105108d23c90b6f5704c64e0f2ef59ec8c85983
+  data.tar.gz: 7bee58c136c5590646a736c42b900c4c4322fc7beeefcc9980b4ca5bfae6c4b8
 SHA512:
-  metadata.gz: 75aa3b257cb79d94a5fb7308b89b4a9ce1fb827dfbe073e96723fdfbe8c8f8991ef1e37d0a0af44b4c8e52c318811f63baf064cb2db646995420f6733e3114da
-  data.tar.gz: a33d70d38648147044a6eedf5a3e0afe171331862a7f08ea561ee52e3438bb3d3750636b85a2cbfd1d4a06e16937bb57f60616ee2a10f415ab479764741ef066
+  metadata.gz: a59410198a58a61ff195ed6ca2e4a5a7d20d751af9dc8690e1d38405e68a81ff3470ac532c9cd4517ed470fe814dab34db1221357a09ab63919bab78b57795b4
+  data.tar.gz: e1da749ccc43b3b1e00db74640e761b249d2445159026729780c11fa8b54d18c6c9d51f0655317229a9cd35cc1ffa727477f0c5be9033438be25fb8388acfa35

data/CHANGELOG.md

@@ -3,6 +3,44 @@
 All notable changes to AsciiChem are documented here.
 This project follows [Semantic Versioning](https://semver.org/).
 
+## [0.31.3] - 2026-10-20
+
+### Added
+- Perception in the shared corpus (TODO.v2/13 item 2, slice C):
+  implicit hydrogens order aromatic bonds at 1.5 (Hückel) and declare
+  a value only when a default valence fits integrally — so
+  `c1ccccc1` and `C1=CC=CC=C1` perceive identically, and
+  aromatic-schematic fusion atoms decline rather than invent. Gated
+  by `fixtures/perception.json` in all three implementations.
+- Structured condition entries (item 4, slice 1):
+  `Conditions#entries` derives typed `cat:`/`solv:`/`reag:` entries
+  (semicolon-separated) from the verbatim bracket text; free text and
+  unknown prefixes stay lossless, and the wire form is unchanged.
+  `ReactionRoles` prefers explicit roles over the above/below
+  heuristic.
+- Reaction stoichiometry as model data (slice 2):
+  `Reaction#stoichiometry` and `Molecule#stoichiometric_coefficient`
+  — one coefficient rule shared by the reaction, `BalanceCheck`, and
+  composition counting.
+- Mechanism step graph (slice 4a): `MechanismGraph.for` derives
+  parsed steps, catalysts (species on both sides), and inter-step
+  links from the verbatim `mechanism{}` entries.
+- Reaction identity via RInChI (slice 4b): `Rxn::Writer` emits MDL
+  RXN V2000 and `Rinchi::BinaryEngine` wraps the opt-in `rinchi-1`
+  binary (install guidance, `EngineMissingError`, nothing vendored).
+- Molfile stereo (L3 slice 6): `Atom#chirality` crosses as MDL atom
+  parity and stated hydrogens as the H-count field, so the identity
+  pipe derives stereoisomer-distinct InChIs; `IdentityCrossCheck`
+  covers stereo-layer mismatches.
+
+### Fixed
+- SMILES writer ring-closure emission (#103): a closure-bearing
+  child continues the chain, so the digit lands at the end of the
+  traversal — `parse(write(parse(s))) == parse(s)` and writer
+  stability now hold for ring structures such as `C1=CCC(C)C(C)C1`.
+- SMILES writer rendered stated zero hydrogens as a bare `H` (one);
+  it now emits `H0`.
+
 ## [0.31.2] - 2026-10-20
 
 ### Added

data/lib/asciichem/linter/balance_check.rb

@@ -51,11 +51,10 @@ module AsciiChem
       end
 
       def count_molecule(molecule)
-        coefficient = molecule.coefficient.to_i
-        coefficient = 1 if coefficient.zero?
         raw = enumerate(molecule, 1)
         return nil if raw.nil?
 
+        coefficient = molecule.stoichiometric_coefficient
         raw.transform_values { |v| v * coefficient }
       end
 

data/lib/asciichem/mechanism_graph.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module AsciiChem
+  # The mechanism step graph (TODO.v2/13 item 4): `mechanism{}` entries
+  # stay verbatim (label + reaction text) in the model; this service
+  # derives the graph the text implies — each step's reaction parsed
+  # with the same grammar, species that appear on both sides of a step
+  # recognised as catalysts, and steps linked where a product species
+  # of an earlier step is a reactant of a later one.
+  #
+  # Everything is computed; nothing mutates. A step whose value is not
+  # a reaction (prose, "proton transfer") keeps a nil reaction and
+  # takes part in no links — never an error.
+  module MechanismGraph
+    Step = Struct.new(:label, :reaction, :catalysts, keyword_init: true)
+    Link = Struct.new(:from, :to, :species, keyword_init: true)
+    Graph = Struct.new(:steps, :links, keyword_init: true)
+
+    module_function
+
+    def for(mechanism)
+      steps = mechanism.steps.map { |step| graph_step(step) }
+      Graph.new(steps: steps, links: links(steps))
+    end
+
+    def graph_step(step)
+      reaction = parse_reaction(step.reaction)
+      sides = sides_of(reaction)
+      catalysts = sides ? sides[:reactants].keys & sides[:products].keys : []
+      Step.new(label: step.label, reaction: reaction, catalysts: catalysts)
+    end
+
+    def links(steps)
+      steps.each_with_index.flat_map do |from, i|
+        next [] unless from.reaction
+
+        from_products = sides_of(from.reaction)[:products].keys
+        steps[(i + 1)..].filter_map { |to| link_between(from, to, from_products) }
+      end
+    end
+
+    def link_between(from, to, from_products)
+      return nil unless to.reaction
+
+      shared = from_products & sides_of(to.reaction)[:reactants].keys
+      Link.new(from: from.label, to: to.label, species: shared) unless shared.empty?
+    end
+
+    def parse_reaction(text)
+      node = AsciiChem.parse(text).nodes.first
+      node if node.is_a?(AsciiChem::Model::Reaction) ||
+              node.is_a?(AsciiChem::Model::ReactionCascade)
+    rescue AsciiChem::ParseError
+      nil
+    end
+
+    # Coefficient-free species names per side; a cascade's entry side
+    # is its head and its exit side is its last step.
+    def sides_of(reaction)
+      case reaction
+      when AsciiChem::Model::Reaction
+        reaction.stoichiometry
+      when AsciiChem::Model::ReactionCascade
+        steps = reaction.steps
+        return nil if steps.empty?
+
+        { reactants: steps.first.stoichiometry[:reactants],
+          products: steps.last.stoichiometry[:products] }
+      end
+    end
+  end
+end

data/lib/asciichem/model/molecule.rb

@@ -124,15 +124,21 @@ module AsciiChem
       # describe the substance, not the stoichiometric multiplier.
       def element_counts(with_coefficient: true)
         tally = Hash.new(0)
-        multiplier = 1
-        if with_coefficient
-          own = coefficient&.to_i
-          multiplier = own if own && own.positive?
-        end
+        multiplier = with_coefficient ? stoichiometric_coefficient : 1
         nodes.each { |node| tally_element(node, tally, multiplier) }
         tally
       end
 
+      # The integer stoichiometric coefficient: the authored leading
+      # number, or 1 when absent or not positive. Single source for
+      # every consumer (reaction stoichiometry, the balance check,
+      # composition) — coefficients are model data, not per-caller
+      # parsing.
+      def stoichiometric_coefficient
+        own = coefficient&.to_i
+        own && own.positive? ? own : 1
+      end
+
       private
 
       def tally_element(node, tally, multiplier)

data/lib/asciichem/model/reaction.rb

@@ -5,8 +5,49 @@ module AsciiChem
     # A chemical reaction: reactants, an arrow, and products. Conditions
     # render above and below the arrow per IUPAC.
     class Reaction < Node
+      # Conditions carry the bracket text verbatim (the round-trip
+      # source) and derive typed entries from it: `[cat: Pd]` is a
+      # catalyst entry, `[water]` stays free text. `;` separates
+      # entries inside one bracket; unknown role prefixes are free text
+      # (lossless — never an error).
       Conditions = Struct.new(:above, :below, keyword_init: true)
 
+      class Conditions
+        ROLE_PREFIXES = {
+          'cat' => :catalyst, 'catalyst' => :catalyst,
+          'solv' => :solvent, 'solvent' => :solvent,
+          'reag' => :reagent, 'reagent' => :reagent
+        }.freeze
+        ENTRY_SEPARATOR = ';'
+        Entry = Struct.new(:role, :value, :side, keyword_init: true)
+
+        def entries
+          [[:above, above], [:below, below]].flat_map do |side, text|
+            entries_for(side, text)
+          end
+        end
+
+        private
+
+        def entries_for(side, text)
+          return [] if text.nil? || text.strip.empty?
+
+          text.split(ENTRY_SEPARATOR).filter_map do |chunk|
+            chunk = chunk.strip
+            next if chunk.empty?
+
+            role, value = split_role(chunk)
+            Entry.new(role: role, value: value, side: side)
+          end
+        end
+
+        def split_role(chunk)
+          prefix, rest = chunk.split(':', 2)
+          role = ROLE_PREFIXES[prefix.strip.downcase] unless rest.nil?
+          role ? [role, rest.strip] : [nil, chunk]
+        end
+      end
+
       ARROWS = {
         forward:     { ascii: '->',   mathml_entity: '→', wire: 'forward' },
         reverse:     { ascii: '<-',   mathml_entity: '←', wire: 'reverse' },
@@ -72,9 +113,7 @@ module AsciiChem
 
       def side_stoichiometry(side)
         side.each_with_object(Hash.new(0)) do |molecule, out|
-          coefficient = (molecule.coefficient || '1').to_i
-          coefficient = 1 if coefficient.zero?
-          out[molecule.to_text.sub(/\A\d+/, '')] += coefficient
+          out[molecule.to_text.sub(/\A\d+/, '')] += molecule.stoichiometric_coefficient
         end
       end
     end

data/lib/asciichem/molfile/parser.rb

@@ -73,7 +73,9 @@ module AsciiChem
           Model::Atom.new(
             element: element,
             x2: x, y2: y, z2: z,
-            isotope: isotope_from_mass_diff(element, mass_diff)
+            isotope: isotope_from_mass_diff(element, mass_diff),
+            chirality: chirality_from_parity(line[39, 3].to_i),
+            hydrogens: hydrogens_from_hcount(line[42, 3].to_i)
           )
         end
       end
@@ -153,6 +155,20 @@ module AsciiChem
       def isotope_from_mass_diff(_element, mass_diff)
         nil
       end
+
+      # MDL atom parity: 1 odd, 2 even, 0/3 not stereo (or either).
+      # The parity is relative to the neighbour order in the bond
+      # block, which the linearizer preserves — the same ordering the
+      # SMILES TH1/TH2 convention uses.
+      def chirality_from_parity(parity)
+        { 1 => 'TH1', 2 => 'TH2' }[parity]
+      end
+
+      # MDL H-count code: 0 default, 1 H0, 2 H1, 3 H2, ...
+      def hydrogens_from_hcount(code)
+        code >= 1 ? code - 1 : nil
+      end
+
       def atoms_count
         field(3, 0, 3).to_i
       end

data/lib/asciichem/molfile/writer.rb

@@ -7,12 +7,21 @@ module AsciiChem
     # computed (Layout walks atoms in the same order as
     # Structure::Graph, so positions map by index). Charges and
     # isotopes are emitted as `M  CHG` / `M  ISO` property lines.
+    #
+    # Tetrahedral chirality crosses as the atom parity field
+    # (TH1 → 1 odd, TH2 → 2 even) relative to the neighbour order in
+    # the bond block, which is the model's linear order — the InChI
+    # binary consumes it when wedges or coordinates are absent.
+    # Directional bonds (`/`, `\`, E/Z) have no V2000 field: the
+    # model's Bond#direction is documented as a molfile loss rather
+    # than silently invented from geometry.
     class Writer
       BOND_TYPES = {
         single: 1, double: 2, triple: 3, aromatic: 4,
         wedge: 1, hash: 1
       }.freeze
       BOND_STEREO = { wedge: 1, hash: 6 }.freeze
+      CHIRALITY_PARITY = { 'TH1' => 1, 'TH2' => 2 }.freeze
 
       def initialize(molecule, name: nil)
         @molecule = molecule
@@ -21,7 +30,7 @@ module AsciiChem
 
       def write
         atoms, edges = Structure::Graph.build(@molecule)
-        raise ParseError, "molecule has no bonds — a formula is not a structure" if edges.empty?
+        raise ParseError, "molecule has no bonds — a formula is not a structure" if edges.empty? && atoms.length > 1
 
         lines = []
         lines << @name.to_s
@@ -32,8 +41,10 @@ module AsciiChem
         layout = nil
         atoms.each_with_index do |atom, index|
           x, y = coordinates(atom, index, atoms)
-          lines << format("%10.4f%10.4f%10.4f %-3s 0  0  0  0  0  0  0  0  0  0  0  0",
-                          x, y, atom.z2 || 0.0, atom.element)
+          lines << format("%10.4f%10.4f%10.4f %-3s 0  0%3d%3d  0  0  0  0  0  0  0  0  0",
+                          x, y, atom.z2 || 0.0, atom.element,
+                          CHIRALITY_PARITY.fetch(atom.chirality, 0),
+                          hcount_code(atom))
         end
 
         edges.each do |edge|
@@ -53,6 +64,12 @@ module AsciiChem
 
       private
 
+      # MDL H-count code: 0 default, 1 H0, 2 H1, 3 H2, ... — so a
+      # stated count n crosses as n + 1.
+      def hcount_code(atom)
+        atom.hydrogens.nil? ? 0 : atom.hydrogens + 1
+      end
+
       # Authored coordinates win; otherwise positions from the
       # deterministic 2D layout (same walk order as the graph).
       def coordinates(atom, index, atoms)

data/lib/asciichem/perception.rb

@@ -36,6 +36,8 @@ module AsciiChem
     # Sum of explicit bond orders at an atom (wedge/hash/dative/wavy
     # bonds order as single; aromatic orders as 1 — Hückel alternation
     # is a ring-perception concern, not a bond-order sum concern).
+    # This is the valence-feasibility sum: the linter's max-valence
+    # check consumes it.
     def bond_order_sum(atom_index, edges)
       edges.sum do |edge|
         next 0 unless edge.from == atom_index || edge.to == atom_index
@@ -44,26 +46,49 @@ module AsciiChem
       end
     end
 
+    # Hydrogen-counting sum: aromatic bonds order as 1.5 (Hückel), so
+    # both spellings of benzene sum to 3.0 at every carbon and perceive
+    # one implicit hydrogen — the two syntaxes share semantics. Whole
+    # numbers only: a fractional remainder means the Hückel arithmetic
+    # cannot decide (fused aromatic-schematic atoms), and perception
+    # declines rather than invents.
+    def hydrogen_valence_sum(atom_index, edges)
+      edges.sum do |edge|
+        next 0 unless edge.from == atom_index || edge.to == atom_index
+
+        edge.kind == :aromatic ? 1.5 : BOND_ORDER.fetch(edge.kind, 1)
+      end
+    end
+
     # Implicit hydrogens for an atom: the smallest default valence
-    # that the explicit bond order fits, minus the bond order.
+    # that the hydrogen-valence sum fits, minus that sum. The sum must
+    # come from #hydrogen_valence_sum (aromatic-aware).
     # - Atoms that STATE hydrogens ([NH4+], [CH4]) return 0 — never
     #   add to what the source said.
     # - Charged atoms return nil: charge algebra on valence is
     #   element-specific and deferred until the perception pass grows
     #   one (wrong implicit hydrogens are worse than none).
-    # - Elements without a table entry, or explicit orders exceeding
-    #   every default, return nil — never invent.
-    def implicit_hydrogens(atom, bond_order_sum)
+    # - Elements without a table entry, non-integral or over-valent
+    #   sums return nil — never invent.
+    def implicit_hydrogens(atom, valence_sum)
       return 0 if atom.hydrogens
       return nil if atom.charge
 
-      valences = DEFAULT_VALENCES[atom.element]
-      return nil if valences.nil?
+      deficits = valence_deficits(atom.element, valence_sum)
+      return nil if deficits.empty?
+
+      deficits.min.to_i
+    end
 
-      fitting = valences.select { |v| v >= bond_order_sum }
-      return nil if fitting.empty?
+    # Whole-number, non-negative gaps between each default valence and
+    # the hydrogen-valence sum; empty when the element is unknown or
+    # no valence fits integrally.
+    def valence_deficits(element, valence_sum)
+      valences = DEFAULT_VALENCES[element]
+      return [].freeze if valences.nil?
 
-      fitting.min - bond_order_sum
+      valences.map { |v| v - valence_sum }
+              .select { |deficit| deficit >= 0 && deficit.modulo(1).zero? }
     end
 
     # Six-membered cycles where every atom is sp2 (participates in a

data/lib/asciichem/reaction_roles.rb

@@ -1,13 +1,11 @@
 # frozen_string_literal: true
 
 module AsciiChem
-  # Reaction-roles perception (TODO.v2/13 item 4, slice A): the
-  # chemistry-writing convention puts catalysts and light reagents
-  # ABOVE the arrow and solvents/conditions BELOW; the conditions
-  # text carries them free-form. This derives structured role hints
-  # from that convention — pure functions, nothing mutates. A full
-  # roles syntax (structured entries in the grammar) is the later
-  # slice.
+  # Reaction-role derivation (TODO.v2/13 item 4): explicit typed
+  # entries (`[cat: Pd]`, `[solv: THF]`, `[reag: NaH]`) win; free-text
+  # entries fall back to the writing convention — catalysts and light
+  # reagents ABOVE the arrow, solvents BELOW — classified by hint
+  # matching. Pure functions, nothing mutates.
   module ReactionRoles
     CATALYST_HINTS = %w[pd pt ni fe catalyst cat].freeze
     SOLVENT_HINTS = %w[h2o thf dmso dmf etoh meoh toluene solvent sol water].freeze
@@ -15,19 +13,37 @@ module AsciiChem
     module_function
 
     # Returns { catalysts: [strings], solvents: [strings],
-    # reagents: [strings], other_above: [strings], other_below: [] }
-    # — entries split from the conditions text by whitespace, each
-    # classified by hint matching against the role vocabularies.
+    # reagents: [strings], other_below: [strings] }. Explicit roles
+    # route to their bucket regardless of side; free-text entries are
+    # split and classified by the above/below convention.
     def roles_for(reaction)
-      conditions = reaction.conditions
-      above = split_entries(conditions&.above)
-      below = split_entries(conditions&.below)
-      {
-        catalysts: above.select { |e| matches?(e, CATALYST_HINTS) },
-        reagents: above.reject { |e| matches?(e, CATALYST_HINTS) },
-        solvents: below.select { |e| matches?(e, SOLVENT_HINTS) },
-        other_below: below.reject { |e| matches?(e, SOLVENT_HINTS) }
-      }
+      roles = { catalysts: [], reagents: [], solvents: [], other_below: [] }
+      entries = reaction.conditions ? reaction.conditions.entries : []
+      entries.each { |entry| assign(entry, roles) }
+      roles
+    end
+
+    def assign(entry, roles)
+      case entry.role
+      when :catalyst then roles[:catalysts] << entry.value
+      when :solvent then roles[:solvents] << entry.value
+      when :reagent then roles[:reagents] << entry.value
+      else classify_free(entry, roles)
+      end
+    end
+
+    def classify_free(entry, roles)
+      split_entries(entry.value).each do |value|
+        roles[bucket(value, entry.side)] << value
+      end
+    end
+
+    def bucket(value, side)
+      if matches?(value, CATALYST_HINTS) then :catalysts
+      elsif matches?(value, SOLVENT_HINTS) then :solvents
+      elsif side == :above then :reagents
+      else :other_below
+      end
     end
 
     def split_entries(text)

data/lib/asciichem/rinchi/binary_engine.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require 'open3'
+
+module AsciiChem
+  module Rinchi
+    # Engine that shells out to the standalone IUPAC `rinchi-1`
+    # binary. The binary is a documented external dependency — nothing
+    # is vendored (vendoring requires the licence review recorded in
+    # TODO.v2/10, a maintainer decision).
+    #
+    #   AsciiChem::Rinchi.engine = AsciiChem::Rinchi::BinaryEngine.new
+    #   AsciiChem::Rinchi.engine = AsciiChem::Rinchi::BinaryEngine.new(bin: "/usr/local/bin/rinchi-1")
+    class BinaryEngine
+      DEFAULT_FLAGS = %w[-STDIO -AuxNone -NoLabels -Key].freeze
+
+      attr_reader :bin, :flags
+
+      def initialize(bin: 'rinchi-1', flags: DEFAULT_FLAGS)
+        super()
+        @bin = bin
+        @flags = flags.freeze
+      end
+
+      # reaction → RXN → rinchi-1 → Identity. The RXN emission is the
+      # pipe: reactants and products cross into the engine as V2000
+      # mol blocks inside one $RXN container.
+      def identity(reaction)
+        rxn = AsciiChem::Rxn.write(reaction)
+        out = execute(rxn)
+        rinchi = out[/^RInChI=\S+/]
+        raise AsciiChem::Error, "#{bin} produced no RInChI:\n#{out}" unless rinchi
+
+        Identity.new(
+          rinchi: rinchi,
+          short_rinchikey: out[/^Short-RInChIKey=(\S+)/, 1],
+          long_rinchikey: out[/^Long-RInChIKey=(\S+)/, 1]
+        )
+      end
+
+      private
+
+      def execute(input)
+        out, err, status = Open3.capture3(bin, *flags, stdin_data: input)
+        unless status.success?
+          raise AsciiChem::Error, "#{bin} failed (exit #{status.exitstatus}): #{(err + out).strip[0, 500]}"
+        end
+
+        out
+      rescue Errno::ENOENT
+        raise EngineMissingError, "RInChI engine binary #{bin.inspect} not found — #{AsciiChem::Rinchi::INSTALL_GUIDE}"
+      end
+    end
+  end
+end

data/lib/asciichem/rinchi/identity.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module AsciiChem
+  module Rinchi
+    # Derived identity of a reaction: the standard RInChI string and
+    # its long/short InChIKeys. Value object returned by engines.
+    Identity = Struct.new(:rinchi, :short_rinchikey, :long_rinchikey,
+                          keyword_init: true)
+  end
+end

data/lib/asciichem/rinchi.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module AsciiChem
+  # Reaction identity via RInChI (TODO.v2/13 item 4; TODO.v2/10 pattern).
+  #
+  # Like InChI, the algorithm is never reimplemented: engines wrap the
+  # IUPAC RInChI software (`rinchi-1`). The pipe is
+  # Model::Reaction → RXN → engine → RInChI keys.
+  #
+  # Engines are opt-in: set `AsciiChem::Rinchi.engine` (or pass one
+  # per call). Without an engine every derivation raises
+  # EngineMissingError with install guidance — no silent fallback.
+  module Rinchi
+    autoload :BinaryEngine, 'asciichem/rinchi/binary_engine'
+    autoload :Identity, 'asciichem/rinchi/identity'
+
+    INSTALL_GUIDE = 'install the IUPAC RInChI software ' \
+                    '(https://github.com/IUPAC-InChI/RInChI) and set ' \
+                    'AsciiChem::Rinchi.engine = AsciiChem::Rinchi::BinaryEngine.new ' \
+                    '(or pass bin: "path/to/rinchi-1")'
+
+    class << self
+      attr_accessor :engine
+
+      # Derives the identity of one reaction. Falls back to the
+      # configured engine when none is passed; raises
+      # EngineMissingError when neither exists.
+      def identity_for(reaction, engine: nil)
+        selected = engine || self.engine
+        raise EngineMissingError, "no RInChI engine configured — #{INSTALL_GUIDE}" if selected.nil?
+
+        selected.identity(reaction)
+      end
+    end
+  end
+end

data/lib/asciichem/rxn/writer.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module AsciiChem
+  module Rxn
+    # Model reaction → MDL RXN V2000. Layout: `$RXN`, name, program,
+    # comment, counts (`%3d%3d` = reactant count, product count), then
+    # `$MOL` + one V2000 molfile per species (reactants first, then
+    # products).
+    class Writer
+      def initialize(reaction, name: nil)
+        @reaction = reaction
+        @name = name
+      end
+
+      def write
+        reactants = @reaction.reactants
+        products = @reaction.products
+        lines = ['$RXN', @name.to_s, '  AsciiChem', '',
+                 format('%<reactants>3d%<products>3d',
+                        reactants: reactants.length, products: products.length)]
+        (reactants + products).each do |molecule|
+          lines << '$MOL'
+          lines << AsciiChem::Molfile.write(molecule).chomp
+        end
+        lines.join("\n") << "\n"
+      end
+    end
+  end
+end

data/lib/asciichem/rxn.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module AsciiChem
+  # MDL RXN (reaction file) emission (TODO.v2/13 item 4, RInChI): a
+  # reaction as one $RXN container holding each reactant and product
+  # as a V2000 mol block. RXN carries species, not stoichiometry —
+  # the coefficient is model data with no place in the file, so it is
+  # not invented there.
+  module Rxn
+    autoload :Writer, 'asciichem/rxn/writer'
+
+    class << self
+      def write(reaction, name: nil)
+        Writer.new(reaction, name: name).write
+      end
+    end
+  end
+end

data/lib/asciichem/smiles/writer.rb

@@ -167,17 +167,21 @@ module AsciiChem
         emit(continuation, index, @adjacency[index][continuation])
       end
 
-      # Lower sorts first: single/aromatic bonds continue the chain,
-      # then larger subtrees, then the lexicographically smallest atom
-      # token (order-independent, so the canonical form does not
-      # depend on how the input happened to number the atoms).
+      # Lower sorts first. A closure-bearing child continues the chain
+      # (SMILES writes ring-closure digits at the end of a traversal —
+      # this also keeps the written atom order equal to the model's,
+      # so re-parsing yields an equal model), then single/aromatic
+      # bonds, then larger subtrees, then the lexicographically
+      # smallest atom token (order-independent, so the canonical form
+      # does not depend on how the input happened to number the atoms).
       def continuation_rank(index, child)
         kind = @adjacency[index][child]
         priority = CONTINUATION_BONDS.include?(kind) ? 0 : 1
+        closure_first = @closures[child].empty? ? 1 : 0
         # The order-independent token: this rank runs inside the
         # written-order pre-pass, where stereo tokens are not yet
         # computable (and stereo does not affect the order).
-        [priority, -@tree_size[child], atom_token_for(child, stereo: false)]
+        [closure_first, priority, -@tree_size[child], atom_token_for(child, stereo: false)]
       end
 
       def ring_digit_for(a, b)
@@ -243,7 +247,8 @@ module AsciiChem
             t << chirality_token(index) if stereo && atom.chirality
             if atom.hydrogens
               t << 'H'
-              t << atom.hydrogens.to_s if atom.hydrogens > 1
+              # Stated zero is H0, not a bare H (which means one).
+              t << atom.hydrogens.to_s unless atom.hydrogens == 1
             end
             t << charge_suffix(atom.charge) if atom.charge
             t << ']'

data/lib/asciichem/version.rb

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

data/lib/asciichem.rb

@@ -29,11 +29,14 @@ module AsciiChem
   autoload :ModelAdapter, "asciichem/model_adapter"
   autoload :Molfile, "asciichem/molfile"
   autoload :Parser, "asciichem/parser"
+  autoload :MechanismGraph,    'asciichem/mechanism_graph'
   autoload :Perception,        'asciichem/perception'
   autoload :ReactionRoles,     'asciichem/reaction_roles'
   autoload :PeriodicTable, "asciichem/periodic_table"
   autoload :Resolver, "asciichem/resolver"
   autoload :RingBonds, "asciichem/ring_bonds"
+  autoload :Rinchi, "asciichem/rinchi"
+  autoload :Rxn, "asciichem/rxn"
   autoload :Smiles, "asciichem/smiles"
   autoload :Structure, "asciichem/structure"
   autoload :Transform, "asciichem/transform"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: asciichem
 version: !ruby/object:Gem::Version
-  version: 0.31.2
+  version: 0.31.3
 platform: ruby
 authors:
 - Ribose Inc.
@@ -238,6 +238,7 @@ files:
 - lib/asciichem/linter/unclosed_ring_check.rb
 - lib/asciichem/linter/valence_check.rb
 - lib/asciichem/linter/zmatrix_reference_check.rb
+- lib/asciichem/mechanism_graph.rb
 - lib/asciichem/model.rb
 - lib/asciichem/model/atom.rb
 - lib/asciichem/model/bond.rb
@@ -275,7 +276,12 @@ files:
 - lib/asciichem/resolver/opsin.rb
 - lib/asciichem/resolver/pubchem.rb
 - lib/asciichem/resolver/substance.rb
+- lib/asciichem/rinchi.rb
+- lib/asciichem/rinchi/binary_engine.rb
+- lib/asciichem/rinchi/identity.rb
 - lib/asciichem/ring_bonds.rb
+- lib/asciichem/rxn.rb
+- lib/asciichem/rxn/writer.rb
 - lib/asciichem/smiles.rb
 - lib/asciichem/smiles/parser.rb
 - lib/asciichem/smiles/writer.rb