asciichem 0.31.2 → 0.31.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b221962f73e48a95f8d177ffd94fdf051b135f70d014b9b42aaa5d7fb1005840
-  data.tar.gz: b2b40147701ba90d0b8b9ed014202836fbc65cbb22f14fa98f3f1195cdd3b7bd
+  metadata.gz: c9c3f297f95612987dbe2a4e7f15bcaa0d4628dbae0d074dce5aeea2fb5e0efa
+  data.tar.gz: 75a1ef4ea31451fccfb37369299d86afa1a08b26c825054de2eda109c636a561
 SHA512:
-  metadata.gz: 75aa3b257cb79d94a5fb7308b89b4a9ce1fb827dfbe073e96723fdfbe8c8f8991ef1e37d0a0af44b4c8e52c318811f63baf064cb2db646995420f6733e3114da
-  data.tar.gz: a33d70d38648147044a6eedf5a3e0afe171331862a7f08ea561ee52e3438bb3d3750636b85a2cbfd1d4a06e16937bb57f60616ee2a10f415ab479764741ef066
+  metadata.gz: cba5c440d3da6c3a436b207d36203f07641ad1b76c61ade69ac5e39697c1b79a81374f7e7106a5764611b3f400f28f9dae89a7054a70c4124b6c21da0d6f8c8a
+  data.tar.gz: e7cb123f63497d962297ea6629e684a0b8af6417c494a7332e02a9729585e977a0c02e2acdd6ee7eb99868fa70475b9a8e57e748eb38fde789957c66a8dc2afa

data/CHANGELOG.md

@@ -3,6 +3,79 @@
 All notable changes to AsciiChem are documented here.
 This project follows [Semantic Versioning](https://semver.org/).
 
+## [0.31.4] - 2026-10-20
+
+### Changed
+- Canonical SMILES now consumes the perception pass (item 2): atoms
+  in perceived aromatic rings are written lowercase with implicit ring
+  bonds, so Kekulé input canonicalizes — `C1=CC=CC=C1` → `c1ccccc1`,
+  aspirin → `CC(=O)Oc1ccccc1C(=O)O`. Canonical-form stability is a
+  fixed point (`write(parse(write(x))) == write(x)`); composition and
+  connectivity are preserved. Perception's sp2 rule now requires the
+  double-bond partner to itself be in a ring, keeping quinone rings
+  Kekulé — the guard that makes aromatic canonicalization chemically
+  safe. Corpus contract 0.7.0 (`canonicalSmiles` fixture field).
+- `Molecule#stoichiometric_coefficient` is the single coefficient
+  rule shared by `Reaction#stoichiometry`, `BalanceCheck`, and
+  `element_counts`.
+
+### Added
+- Mechanism electron-flow markers (item 4, slice 4c): a step value may
+  carry `| flow: SOURCE > TARGET` clauses (semicolon-separated),
+  typed as `Mechanism::Flow`, carried by `MechanismGraph`, emitted on
+  the wire (`MechanismStep.flows`, asciichem-model v1 additive), and
+  re-emitted in canonical text. Malformed clauses raise; nothing is
+  dropped.
+- Depiction backends (item 7): `AsciiChem::Layout.backend` lets a
+  depiction engine (RDKit, CDK, a Rust layout core) replace the
+  built-in elkrb pipeline without touching the renderer or the model.
+
+### Fixed
+- Mechanism wire emission: the adapter passed raw step/spectator
+  strings to the reaction serializer, so `Mechanism#to_model_json`
+  had never worked. Steps and spectators are now parsed with the same
+  grammar; spectators that are not valid AsciiChem raise clearly.
+- Test isolation: the CLI `--engine parsanol` spec leaked the engine
+  selection into later examples.
+
+## [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/README.adoc

@@ -45,6 +45,28 @@ formula.to_mathml  # => "<math>...</math>"
 formula.to_text    # => "H_2O"  (round trip)
 ----
 
+== Conformance
+
+The reference implementation of https://www.asciichem.org[the AsciiChem
+contract]. Every claim is gated by the shared corpus
+(https://github.com/asciichem/asciichem-tests[asciichem-tests]) in CI —
+a level without the green corpus run behind it does not ship.
+
+[cols="1,1,4"]
+|===
+|Level |Claim |Basis
+
+|L0 notation |yes |parse/reject contract; every `roundTrip` fixture returns its input
+|L1 semantics |yes |wire form validates against the v1 schemas and round-trips; the perception pass (implicit hydrogens, aromatic rings) is corpus-gated
+|L2 render |yes |MathML byte-goldens, canonical text, and the wire form for every construct
+|L3 stereo |yes |tetrahedral chirality, directional bonds, wedge/hash; parity-correct canonical SMILES including ring closures
+|L4 identity |partial |opt-in InChI engine with stereo layers, OPSIN adapter, identifier cross-check, citation bibitems; CAS source decision pending
+|===
+
+TypeScript and Python claim the same levels they pass; see their
+READMEs and the https://www.asciichem.org/guides/conformance-levels/[levels
+document].
+
 == Design
 
 See link:ARCHITECTURE.adoc[] and the specification at

data/lib/asciichem/formatter/text.rb

@@ -199,13 +199,23 @@ module AsciiChem
       def visit_mechanism(mech)
         parts = ["mechanism"]
         unless mech.steps.empty? && mech.spectators.empty?
-          lines = mech.steps.map { |s| "#{s.label}: #{s.reaction}" }
+          lines = mech.steps.map { |s| "#{s.label}: #{mechanism_step_text(s)}" }
           mech.spectators.each { |sp| lines << "spectator: #{sp}" }
           parts << "{\n  #{lines.join("\n  ")}\n}"
         end
         parts.join
       end
 
+      # Reaction plus its electron-flow clauses in canonical form:
+      # ` | flow: SRC > DST; SRC2 > DST2`.
+      def mechanism_step_text(step)
+        flows = step.flows
+        return step.reaction if flows.nil? || flows.empty?
+
+        arrows = flows.map { |f| "#{f.source} > #{f.target}" }.join('; ')
+        "#{step.reaction} | flow: #{arrows}"
+      end
+
       def visit_opaque_cml(opaque)
         %(<!-- opaque: #{opaque.element_name} -->)
       end

data/lib/asciichem/layout.rb

@@ -46,13 +46,40 @@ module AsciiChem
       Result.new(atoms: [], bonds: [], width: 0.0, height: 0.0)
     end
 
-    # Compute 2D positions for a molecule's atoms and bonds.
-    # Returns a `Layout::Result`. Algorithm defaults to `layered`
+    # The built-in backend: elkrb layered layout (or authored
+    # coordinates when present).
+    class BuiltinBackend
+      def layout(molecule, algorithm: 'layered')
+        Layout.builtin_layout(molecule, algorithm: algorithm)
+      end
+    end
+
+    class << self
+      # Depictions are views: a backend maps a molecule to a
+      # Layout::Result and the renderer never learns which engine
+      # placed the atoms. The built-in elkrb backend is the default;
+      # external backends (RDKit, CDK, a Rust layout core) plug in
+      # with `AsciiChem::Layout.backend = backend`, where backend
+      # responds to `layout(molecule, algorithm:)`.
+      attr_writer :backend
+
+      def backend
+        @backend ||= BuiltinBackend.new
+      end
+
+      # Compute 2D positions through the configured backend.
+      def layout(molecule, algorithm: 'layered')
+        backend.layout(molecule, algorithm: algorithm)
+      end
+    end
+
+    # Compute 2D positions for a molecule's atoms and bonds with the
+    # built-in elkrb pipeline. Algorithm defaults to `layered`
     # (Sugiyama-style hierarchical) which is deterministic across
     # runs — essential for visual regression testing. Pass
     # `algorithm: "force"` for organic-looking layouts, with the
     # caveat that output may vary between runs.
-    def self.layout(molecule, algorithm: 'layered')
+    def self.builtin_layout(molecule, algorithm: 'layered')
       walker = MoleculeWalker.new(molecule)
       walk = walker.walk
       return empty_result if walk.atoms.empty?

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,73 @@
+# 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, :flows, 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,
+               flows: step.flows || [])
+    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/mechanism.rb

@@ -7,12 +7,21 @@ module AsciiChem
     # Syntax:
     #   mechanism{
     #     step1: A + B -> C
-    #     step2: C -> D + E
+    #     step2: C -> D + E | flow: C > D; C-B > D
     #     spectator: Na+
     #   }
+    #
+    # A step's value is its reaction, optionally followed by
+    # `| flow: SOURCE > TARGET` clauses (semicolon-separated) naming
+    # the electron-flow arrows drawn for that step. Sources/targets
+    # stay verbatim strings: an atom-level binding needs references
+    # the mechanism text does not yet carry.
     class Mechanism < Node
+      # One electron-flow marker within a step.
+      Flow = Struct.new(:source, :target, keyword_init: true)
+
       # A single step in the mechanism, identified by a label.
-      Step = Struct.new(:label, :reaction, keyword_init: true)
+      Step = Struct.new(:label, :reaction, :flows, keyword_init: true)
 
       attr_accessor :steps, :spectators
 

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,45 +46,78 @@ 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
-    # double bond) or aromatic-flagged — the practical fused-system
-    # rule: per-ring strict alternation can never see both rings of
-    # naphthalene (the shared bond is single), but per-atom sp2 does.
-    # Returns arrays of atom indexes, one per perceived ring, or an
-    # empty list. Full Hückel pi-electron counting is a later slice.
+    # Six-membered cycles where every atom is sp2 — participates in a
+    # double bond to an atom that is itself in a ring, or is
+    # aromatic-flagged. The partner-in-a-ring requirement keeps
+    # quinones out: their carbons are sp2, but the double bonds that
+    # make them so point at exocyclic oxygens, and writing such a
+    # ring as aromatic SMILES would state the wrong bond orders. A
+    # fused system still qualifies — naphthalene's fusion carbons
+    # double-bond to atoms of the neighbouring ring. Per-ring strict
+    # alternation can never see both rings (the shared bond is
+    # single); per-atom sp2-in-the-system does. Full Hückel
+    # pi-electron counting is a later slice.
     def aromatic_rings(atoms, edges)
       cycles = ring_cycles(edges, max_size: 6, atom_count: atoms.length)
-        .select { |cycle| cycle.length == 6 }
-      cycles.select { |cycle| cycle.all? { |i| sp2?(i, atoms, edges) } }
+      cyclic_atoms = cycles.flatten.uniq
+      six = cycles.select { |cycle| cycle.length == 6 }
+      six.select { |cycle| cycle.all? { |i| sp2?(i, atoms, edges, cyclic_atoms) } }
     end
 
-    def sp2?(atom_index, atoms, edges)
+    def sp2?(atom_index, atoms, edges, cyclic_atoms)
       return true if atoms[atom_index].aromatic == true
 
       edges.any? do |edge|
-        (edge.from == atom_index || edge.to == atom_index) && edge.kind == :double
+        next false unless edge.from == atom_index || edge.to == atom_index
+        next false unless edge.kind == :double
+
+        partner = edge.from == atom_index ? edge.to : edge.from
+        cyclic_atoms.include?(partner)
       end
     end
 

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

@@ -36,6 +36,7 @@ module AsciiChem
         raise ParseError, 'molecule has no bonds — a formula is not a structure' if edges.empty? && atoms.length > 1
 
         @atoms = atoms
+        perceive_aromaticity(atoms, edges)
         build_adjacency(edges)
         @visited = {}
         @digits = Array.new(atoms.length) { [] }
@@ -66,6 +67,35 @@ module AsciiChem
 
       private
 
+      # The canonicalizer consumes the perception pass (TODO.v2/13
+      # item 2): atoms in perceived aromatic rings are written as
+      # aromatic (lowercase) and the ring bonds between them carry no
+      # bond symbol — Kekulé benzene canonicalizes to `c1ccccc1`, so
+      # both spellings converge. Perception's in-ring double-bond
+      # rule keeps quinone-like rings out.
+      def perceive_aromaticity(atoms, edges)
+        @perceived_aromatic = {}
+        @perceived_ring_edges = {}
+        AsciiChem::Perception.aromatic_rings(atoms, edges).each do |ring|
+          ring.each { |index| @perceived_aromatic[index] = true }
+          ring.each_with_index do |atom, i|
+            other = ring[(i + 1) % ring.length]
+            @perceived_ring_edges[[atom, other].minmax] = true
+          end
+        end
+      end
+
+      # Aromatic for WRITING: the source flagged the atom, or
+      # perception found it in an aromatic ring.
+      def aromatic?(index)
+        @atoms[index].aromatic == true || @perceived_aromatic.key?(index)
+      end
+
+      def perceived_ring_bond?(from, to)
+        @perceived_ring_edges.key?([from, to].minmax) &&
+          aromatic?(from) && aromatic?(to)
+      end
+
       def build_adjacency(edges)
         @adjacency = Array.new(@atoms.length) { {} }
         @directions = {}
@@ -167,17 +197,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)
@@ -201,6 +235,11 @@ module AsciiChem
         token = BOND_TOKENS[kind]
         raise ParseError, "#{kind} bonds have no SMILES form (v1 subset)" unless token
 
+        # A bond inside a perceived aromatic ring is implied by the
+        # lowercase atoms: writing `=`/`-` there would state Kekulé
+        # alternation the canonical form does not carry.
+        return '' if perceived_ring_bond?(from, to)
+
         return token if kind != :single && kind != :aromatic
 
         if kind == :single
@@ -228,7 +267,7 @@ module AsciiChem
         return @plain_tokens[index] if !stereo && @plain_tokens[index]
 
         atom = @atoms[index]
-        aromatic = atom.aromatic == true
+        aromatic = aromatic?(index)
         lowercase = aromatic && LOWERCASE_AROMATIC.include?(atom.element)
         needs_bracket =
           atom.charge || atom.isotope || atom.hydrogens || atom.chirality ||
@@ -243,7 +282,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 << ']'
@@ -266,10 +306,6 @@ module AsciiChem
 
         "#{sign}#{count}"
       end
-
-      def aromatic?(index)
-        @atoms[index].aromatic == true
-      end
     end
   end
 end

data/lib/asciichem/transform_rules.rb

@@ -441,13 +441,44 @@ module AsciiChem
             if key == 'spectator'
               spectators.concat(value.split(/\s+/).map(&:strip))
             else
-              steps << Model::Mechanism::Step.new(label: key, reaction: value)
+              reaction, flows = split_flows(key, value)
+              steps << Model::Mechanism::Step.new(label: key, reaction: reaction, flows: flows)
             end
           end
           Model::Mechanism.new(steps: steps, spectators: spectators)
         end
-  
+
         private
+
+        # A step value is its reaction, optionally followed by
+        # `| flow: SOURCE > TARGET` clauses (semicolon-separated).
+        # Unknown clause kinds are rejected, never dropped.
+        def split_flows(label, value)
+          clauses = value.split('|').map(&:strip)
+          reaction = clauses.shift
+          flows = clauses.flat_map { |clause| parse_flow_clause(label, clause) }
+          [reaction, flows]
+        end
+
+        def parse_flow_clause(label, clause)
+          kind, payload = clause.split(':', 2)
+          unless kind&.strip == 'flow' && payload
+            raise AsciiChem::ParseError,
+                  "mechanism step #{label.inspect} has an unknown clause: #{clause.inspect} " \
+                  '(supported: "flow: SOURCE > TARGET")'
+          end
+
+          payload.split(';').map(&:strip).reject(&:empty?).map do |arrow|
+            source, target = arrow.split('>', 2).map(&:strip)
+            if source.nil? || target.nil? || source.empty? || target.empty?
+              raise AsciiChem::ParseError,
+                    "mechanism step #{label.inspect} has a malformed flow: #{arrow.inspect} " \
+                    '(expected "SOURCE > TARGET")'
+            end
+
+            Model::Mechanism::Flow.new(source: source, target: target)
+          end
+        end
   
         def parse_entries(str)
           return [] unless str

data/lib/asciichem/version.rb

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

data/lib/asciichem/wire/extended.rb

@@ -6,12 +6,23 @@ module AsciiChem
     # zmatrix, calculation. Emission covers the full v1 schemas;
     # ingestion (from_wire) is currently implemented for the core
     # chemistry set only — see WireAdapter.
+    class MechanismFlow < Lutaml::Model::Serializable
+      attribute :source, :string
+      attribute :target, :string
+      json do
+        map "source", to: :source
+        map "target", to: :target
+      end
+    end
+
     class MechanismStep < Lutaml::Model::Serializable
       attribute :label, :string
       attribute :reaction, "AsciiChem::Wire::Reaction"
+      attribute :flows, MechanismFlow, collection: true
       json do
         map "label", to: :label
         map "reaction", to: :reaction
+        map "flows", to: :flows
       end
     end
 

data/lib/asciichem/wire_adapter.rb

@@ -236,13 +236,46 @@ module AsciiChem
       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) }
+          steps: node.steps.map { |step| mechanism_step_to_wire(step) },
+          spectators: node.spectators.map { |sp| mechanism_spectator_to_wire(sp) }
+        )
+      end
+
+      # Spectators are verbatim strings in the model (the mechanism
+      # body is text); the wire wants molecules, so the same grammar
+      # parses them here — a spectator that is not valid AsciiChem
+      # cannot reach the wire and says so.
+      def mechanism_spectator_to_wire(text)
+        molecule_to_wire(AsciiChem.parse(text).nodes.first)
+      rescue AsciiChem::ParseError
+        raise AsciiChem::ParseError,
+              "mechanism spectator is not valid AsciiChem: #{text.inspect}"
+      end
+
+      def mechanism_step_to_wire(step)
+        AsciiChem::Wire::MechanismStep.new(
+          label: step.label,
+          reaction: mechanism_reaction_to_wire(step.reaction),
+          flows: (step.flows || []).map do |flow|
+            AsciiChem::Wire::MechanismFlow.new(source: flow.source, target: flow.target)
+          end
         )
       end
 
+      # The model keeps a step's reaction as TEXT (the mechanism body
+      # is verbatim); the wire carries the typed node, so the same
+      # grammar parses it here.
+      def mechanism_reaction_to_wire(text)
+        node = AsciiChem.parse(text).nodes.first
+        case node
+        when AsciiChem::Model::Reaction then reaction_to_wire(node)
+        when AsciiChem::Model::ReactionCascade then cascade_to_wire(node)
+        else
+          raise AsciiChem::ParseError,
+                "mechanism step is not a reaction: #{text.inspect}"
+        end
+      end
+
       def spectrum_to_wire(node)
         AsciiChem::Wire::Spectrum.new(
           type: "spectrum",

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.4
 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