asciichem 0.31.3 → 0.31.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ab5305dc2ec00320b62efbfae105108d23c90b6f5704c64e0f2ef59ec8c85983
-  data.tar.gz: 7bee58c136c5590646a736c42b900c4c4322fc7beeefcc9980b4ca5bfae6c4b8
+  metadata.gz: 6c9a131b0a052014c60f5be8b74972de24db882f7db088b82bdea1c506709a46
+  data.tar.gz: 9b280851bdc1fb8c4f4681f1887796f2eb688298f8c495cd81a766a879fd8a09
 SHA512:
-  metadata.gz: a59410198a58a61ff195ed6ca2e4a5a7d20d751af9dc8690e1d38405e68a81ff3470ac532c9cd4517ed470fe814dab34db1221357a09ab63919bab78b57795b4
-  data.tar.gz: e1da749ccc43b3b1e00db74640e761b249d2445159026729780c11fa8b54d18c6c9d51f0655317229a9cd35cc1ffa727477f0c5be9033438be25fb8388acfa35
+  metadata.gz: d5580a3f5f314447b3f1f932b37396bb5741bd5363d96e4ae97cc95fcbcf7cfbcd0690ae16253c532d21b2c790093fda0652cd3d1a330f3bcbce9e1801c66e66
+  data.tar.gz: 44a0d45dfca800429e648a5a3c3adab685c5813c7c23d5be68afb55c7dc4cf34410b8cb16ff43681a439d9ec258c7e4f71aa141e7d3561a6a05c0ccc2cbc3f5b

data/ARCHITECTURE.adoc

@@ -390,3 +390,81 @@ Ten registered checks (auto-load via `Linter::Base.register`):
 * `#atom_count` — total atoms (recurses through groups/nested molecules)
 * `#hill_formula` — Hill-system canonical formula (C first, H second, alpha)
 * `#formula_weight` — sum of atomic_mass * count (v0.13+)
+
+== Perception pass (v0.31+)
+
+`AsciiChem::Perception` derives the chemistry the syntax leaves
+implicit, as pure functions over the neutral graph pair
+(`Structure::Graph.build` returns `[atoms, edges]`):
+
+* `bond_order_sum` — valence-feasibility sum (aromatic orders as 1);
+  consumed by the linter's `ValenceCheck`.
+* `hydrogen_valence_sum` — hydrogen-counting sum (aromatic orders as
+  1.5, Hückel); paired with `implicit_hydrogens`, which returns a
+  whole, non-negative count or declines (`nil`): stated hydrogens win,
+  charged atoms and non-integral/over-valent sums decline.
+* `aromatic_rings` — π-electron counting for 5- and 6-membered cycles
+  (in-system double = 1, lone-pair donor N/O/S/P/Se/As = 2,
+  exocyclic-double carbon = 0; aromatic at totals 6 or 10). Charged
+  rings decline; aromatic-flagged rings are taken as stated. This
+  perceives furan/pyrrole/thiophene, fused systems, keeps quinones
+  Kekulé, and rejects four-π and three-membered rings.
+
+Semantics are shared through the corpus (`fixtures/perception.json`) —
+per-atom implicit hydrogens plus perceived ring indexes, declines
+included — and mirrored in TypeScript and Python.
+
+== Canonical SMILES (v0.31+)
+
+`Smiles::Writer` is a deterministic serialiser that consumes the
+perception pass: perceived aromatic rings are written lowercase with
+their ring bonds implicit, so Kekulé input canonicalizes
+(`C1=CC=CC=C1` → `c1ccccc1`, pyrrole → `c1c[nH]cc1`). Ring-closure
+digits stay out of branches (a closure-bearing child continues the
+chain). Stated-zero hydrogens emit `H0`. The canonical form is a fixed
+point; corpus fixtures whose input is not canonical state the expected
+output in `canonicalSmiles`.
+
+== Reactions as semantics (v0.31+)
+
+* `Reaction::Conditions#entries` — typed role entries
+  (`[cat: Pd; solv: THF]`) derived from the verbatim bracket text;
+  `ReactionRoles.roles_for` prefers explicit roles, falls back to the
+  above/below convention for free text.
+* `Reaction#stoichiometry` and `Molecule#stoichiometric_coefficient` —
+  coefficient-free species → integer coefficient, one rule shared by
+  the reaction, `BalanceCheck`, and `element_counts`.
+* `MechanismGraph.for(mechanism)` — parsed steps, catalysts (species on
+  both sides), inter-step links (product → later reactant), and the
+  step's electron-flow markers.
+* `Mechanism::Flow` — `| flow: SOURCE > TARGET` clauses on a step
+  (semicolon-separated), verbatim names, carried on the wire as
+  `steps[].flows`; unknown clauses and malformed arrows raise.
+* `Rxn::Writer` — MDL RXN V2000 emission (species, not
+  stoichiometry); `Rinchi::BinaryEngine` wraps the opt-in `rinchi-1`
+  binary for reaction identity (same contract as the InChI engine:
+  install guidance, `EngineMissingError`, nothing vendored).
+
+== Depiction backends (v0.31+)
+
+`AsciiChem::Layout.backend` is the depiction seam: a backend responds
+to `layout(molecule, algorithm:)` and returns a `Layout::Result`.
+`Layout::BuiltinBackend` (authored coordinates or deterministic elkrb
+layered layout) is the default; external engines (RDKit, CDK, a Rust
+layout core) plug in with one assignment. The renderer, the model, and
+the wire form never learn which engine placed the atoms.
+
+== Conformance contracts (v0.31+)
+
+Two sibling repositories are normative, not the implementation:
+
+* `asciichem-model` — versioned wire schemas (additive changes only),
+  LUTAML definitions, generated TS types; the gem vendors the schemas
+  into `spec/schemas` via `scripts/update-model-schemas.sh`.
+* `asciichem-tests` — the shared corpus. Fixture families: parser
+  acceptance/rejection, canonical-text round-trip, CML, MathML
+  goldens, identifiers, linter expectations, SMILES/molfile
+  interchange, perception (`implicitHydrogens`, `aromaticRings`),
+  condition entries, mechanism flows, and 300 seeded generated models
+  shared across implementations. Contract changes are versioned and
+  state new expectations; fixtures are never weakened.

data/CHANGELOG.md

@@ -3,6 +3,64 @@
 All notable changes to AsciiChem are documented here.
 This project follows [Semantic Versioning](https://semver.org/).
 
+## [0.31.5] - 2026-10-20
+
+### Changed
+- Aromaticity perception is now **Hückel counting** (TODO.v2/13 item 2,
+  finishing the documented later slice): 5- and 6-membered cycles
+  count π electrons — in-system double = 1, lone-pair donor
+  (N/O/S/P/Se/As) with no double = 2, exocyclic-double carbon = 0 —
+  and are aromatic at totals 6 or 10. Charged rings decline;
+  aromatic-flagged rings are taken as stated. Furan, pyrrole, and
+  thiophene are perceived from Kekulé bond orders; quinones remain
+  excluded, as do four-π and three-membered rings.
+- Canonical SMILES covers the five-membered heteroaromatics:
+  `C1=COC=C1` → `c1cocc1`, `C1=CNC=C1` → `c1c[nH]cc1`,
+  `C1=CSC=C1` → `c1cscc1`. A perceived pyrrole nitrogen is written
+  `[nH]` (bare aromatic `n` implies no hydrogen); inferred heteroatom
+  hydrogens apply only to rings perceived from Kekulé orders, so
+  source-aromatic thiophene never gains a phantom H.
+- Corpus contract 0.8.0 (`asciichem-tests`): Hückel fixtures for
+  furan/pyrrole/thiophene, cyclopentadiene and cyclopropene pinned as
+  not aromatic, plus `canonicalSmiles` expectations. TS and Python
+  parity merged; the Python writer also emits `H0` for stated-zero
+  hydrogens.
+
+## [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

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/mechanism_graph.rb

@@ -12,7 +12,7 @@ module AsciiChem
   # 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)
+    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)
 
@@ -27,7 +27,8 @@ module AsciiChem
       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)
+      Step.new(label: step.label, reaction: reaction, catalysts: catalysts,
+               flows: step.flows || [])
     end
 
     def links(steps)

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/perception.rb

@@ -91,23 +91,62 @@ module AsciiChem
               .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.
+    # π-electron-donating heteroatoms: a ring atom with no double bond
+    # of its own contributes its lone pair (pyrrole N, furan O,
+    # thiophene S) — the 2 electrons that make those five-membered
+    # rings 4n+2.
+    LONE_PAIR_DONORS = %w[N O S P Se As].freeze
+
+    # Aromatic rings by Hückel counting: 5- and 6-membered cycles whose
+    # π-electron contributions total 6 or 10 (4n+2 with n >= 1; the
+    # n = 0 case is a charged three-membered ring, which perception
+    # declines, and a 2π six-ring would otherwise misread a diene as
+    # aromatic). Per
+    # atom: an in-system double bond contributes 1; a lone-pair donor
+    # with no double contributes 2; a carbon with only single bonds or
+    # an exocyclic double contributes 0. Charged atoms make the count
+    # undecidable and the ring is declined; aromatic-flagged rings are
+    # taken as stated.
+    #
+    # This sees fused systems (naphthalene's shared bond is single, but
+    # each atom's double bond lies in the ring system) and keeps
+    # quinones out (their carbons' only double bonds point at
+    # exocyclic oxygens, so the ring counts 5, not 4n+2).
     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
+      cycles.select { |cycle| aromatic_cycle?(cycle, atoms, edges, cyclic_atoms) }
     end
 
-    def sp2?(atom_index, atoms, edges)
-      return true if atoms[atom_index].aromatic == true
+    def aromatic_cycle?(cycle, atoms, edges, cyclic_atoms)
+      return true if cycle.any? { |i| atoms[i].aromatic == true }
+      return false unless [5, 6].include?(cycle.length)
 
+      contributions = cycle.map do |i|
+        ring_pi_electrons(atoms[i], i, edges, cyclic_atoms)
+      end
+      return false if contributions.any?(&:nil?)
+
+      [6, 10].include?(contributions.sum)
+    end
+
+    # π electrons one ring atom contributes, or nil when the count is
+    # undecidable (charged atom).
+    def ring_pi_electrons(atom, atom_index, edges, cyclic_atoms)
+      return nil if atom.charge
+      return 1 if in_system_double?(atom_index, edges, cyclic_atoms)
+      return 2 if LONE_PAIR_DONORS.include?(atom.element)
+
+      0
+    end
+
+    def in_system_double?(atom_index, edges, cyclic_atoms)
       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/smiles/writer.rb

@@ -25,6 +25,10 @@ module AsciiChem
       }.freeze
       CONTINUATION_BONDS = %i[single aromatic].freeze
 
+      # Aromatic lowercase heteroatoms with an implicit hydrogen need
+      # brackets: bare `n`/`o`/`s` imply none.
+      HETERO_IMPLICIT_H = %w[N O S P Se As].freeze
+
       def initialize(molecule)
         @molecule = molecule
       end
@@ -36,6 +40,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 +71,62 @@ 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 Hückel counting keeps
+      # quinone-like rings out.
+      #
+      # Hydrogens are inferred for lowercase carbon but NOT for
+      # heteroatoms: pyrrole's N must be written `[nH]` or the SMILES
+      # states a pyridine-type nitrogen instead. The perceived
+      # implicit count for ring atoms is recorded for that decision.
+      def perceive_aromaticity(atoms, edges)
+        @perceived_aromatic = {}
+        @perceived_ring_edges = {}
+        @perceived_hydrogens = {}
+        AsciiChem::Perception.aromatic_rings(atoms, edges).each do |ring|
+          ring.each do |index|
+            @perceived_aromatic[index] = true
+            next if atoms[index].aromatic == true
+
+            @perceived_hydrogens[index] = AsciiChem::Perception.implicit_hydrogens(
+              atoms[index],
+              AsciiChem::Perception.hydrogen_valence_sum(index, edges)
+            )
+          end
+          ring.each_with_index do |atom, i|
+            other = ring[(i + 1) % ring.length]
+            @perceived_ring_edges[[atom, other].minmax] = true
+          end
+        end
+      end
+
+      # Hydrogens the written token must state: the source's own count
+      # wins; otherwise only a ring PERCEIVED from Kekulé bond orders
+      # gets perception's implicit count. A source-aromatic atom
+      # already states its hydrogens the way SMILES does (`[nH]`), and
+      # aromatic 1.5 bond orders do not map onto heteroatom valences
+      # (thiophene's S would otherwise acquire a phantom H).
+      def writing_hydrogens(index)
+        stated = @atoms[index].hydrogens
+        return stated unless stated.nil?
+
+        @perceived_hydrogens[index]
+      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 = {}
@@ -205,6 +266,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
@@ -232,10 +298,14 @@ 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)
+        hyd = writing_hydrogens(index)
+        hetero_needs_h = aromatic && lowercase && hyd&.positive? &&
+                         HETERO_IMPLICIT_H.include?(atom.element)
         needs_bracket =
-          atom.charge || atom.isotope || atom.hydrogens || atom.chirality ||
+          atom.charge || atom.isotope || !atom.hydrogens.nil? || atom.chirality ||
+          hetero_needs_h ||
           (!ORGANIC.include?(atom.element) && !lowercase) ||
           (aromatic && !lowercase)
         token =
@@ -245,10 +315,10 @@ module AsciiChem
             t << atom.isotope if atom.isotope
             t << symbol
             t << chirality_token(index) if stereo && atom.chirality
-            if atom.hydrogens
+            if !atom.hydrogens.nil? || hetero_needs_h
               t << 'H'
               # Stated zero is H0, not a bare H (which means one).
-              t << atom.hydrogens.to_s unless atom.hydrogens == 1
+              t << hyd.to_s unless hyd == 1
             end
             t << charge_suffix(atom.charge) if atom.charge
             t << ']'
@@ -271,10 +341,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.3"
+  VERSION = "0.31.5"
 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",

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: asciichem
 version: !ruby/object:Gem::Version
-  version: 0.31.3
+  version: 0.31.5
 platform: ruby
 authors:
 - Ribose Inc.