asciichem 0.31.3 → 0.31.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ab5305dc2ec00320b62efbfae105108d23c90b6f5704c64e0f2ef59ec8c85983
-  data.tar.gz: 7bee58c136c5590646a736c42b900c4c4322fc7beeefcc9980b4ca5bfae6c4b8
+  metadata.gz: c9c3f297f95612987dbe2a4e7f15bcaa0d4628dbae0d074dce5aeea2fb5e0efa
+  data.tar.gz: 75a1ef4ea31451fccfb37369299d86afa1a08b26c825054de2eda109c636a561
 SHA512:
-  metadata.gz: a59410198a58a61ff195ed6ca2e4a5a7d20d751af9dc8690e1d38405e68a81ff3470ac532c9cd4517ed470fe814dab34db1221357a09ab63919bab78b57795b4
-  data.tar.gz: e1da749ccc43b3b1e00db74640e761b249d2445159026729780c11fa8b54d18c6c9d51f0655317229a9cd35cc1ffa727477f0c5be9033438be25fb8388acfa35
+  metadata.gz: cba5c440d3da6c3a436b207d36203f07641ad1b76c61ade69ac5e39697c1b79a81374f7e7106a5764611b3f400f28f9dae89a7054a70c4124b6c21da0d6f8c8a
+  data.tar.gz: e7cb123f63497d962297ea6629e684a0b8af6417c494a7332e02a9729585e977a0c02e2acdd6ee7eb99868fa70475b9a8e57e748eb38fde789957c66a8dc2afa

data/CHANGELOG.md

@@ -3,6 +3,41 @@
 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

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,33 @@ 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.
+    # 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/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 = {}
@@ -205,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
@@ -232,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 ||
@@ -271,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.3"
+  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",

metadata

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