asciichem 0.31.5 → 0.31.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6c9a131b0a052014c60f5be8b74972de24db882f7db088b82bdea1c506709a46
-  data.tar.gz: 9b280851bdc1fb8c4f4681f1887796f2eb688298f8c495cd81a766a879fd8a09
+  metadata.gz: 64f4629dc9bbc023f63f306a064c9657564557ed8c4b52bbda18ca15b253aaeb
+  data.tar.gz: f9f3534aada7d42cd45c22469557e554cd6ea1d2e35af17229fd306140dff24c
 SHA512:
-  metadata.gz: d5580a3f5f314447b3f1f932b37396bb5741bd5363d96e4ae97cc95fcbcf7cfbcd0690ae16253c532d21b2c790093fda0652cd3d1a330f3bcbce9e1801c66e66
-  data.tar.gz: 44a0d45dfca800429e648a5a3c3adab685c5813c7c23d5be68afb55c7dc4cf34410b8cb16ff43681a439d9ec258c7e4f71aa141e7d3561a6a05c0ccc2cbc3f5b
+  metadata.gz: 5a172b80e7f6d433f20da0c9d741f999f84699ce9a71b0c96319d30ce8e73928dfcd7ac5e02eebd61466a3500430f64733007c7714ffd7a87ea0b3c4d0e34464
+  data.tar.gz: 367240a813ebb1fd22f35dd4421245f5d66f57c4af3000ed51c874b664d4fb4bb9ddf665a3e956bcfef74fc61767ed0711e1cc8c0d2df9db4239be9dcc3a0aa0

data/.github/workflows/ci.yml

@@ -5,6 +5,12 @@ on:
   push:
     branches: [main]
 
+env:
+  # Hermetic CI: the corpus ref is pinned, never floating. Bump this
+  # one line deliberately with each corpus release (the tag carries
+  # what changed).
+  CORPUS_REF: v0.8.0
+
 jobs:
   test:
     runs-on: ubuntu-latest
@@ -18,12 +24,12 @@ jobs:
         uses: actions/checkout@v7
         with:
           repository: asciichem/asciichem-tests
+          ref: ${{ env.CORPUS_REF }}
           path: .asciichem-tests
       - name: Point the suite at the corpus and record its version
         run: |
           echo "ASCIICHEM_CORPUS=$(pwd)/.asciichem-tests/corpus/fixtures" >> "$GITHUB_ENV"
-          git -C .asciichem-tests fetch --depth 1 --tags --quiet
-          echo "ASCIICHEM_CORPUS_VERSION=$(git -C .asciichem-tests describe --tags --abbrev=0 2>/dev/null || echo main)" >> "$GITHUB_ENV"
+          echo "ASCIICHEM_CORPUS_VERSION=${{ env.CORPUS_REF }}" >> "$GITHUB_ENV"
       - uses: ruby/setup-ruby@v1
         with:
           ruby-version: ${{ matrix.ruby }}

data/CHANGELOG.md

@@ -3,6 +3,55 @@
 All notable changes to AsciiChem are documented here.
 This project follows [Semantic Versioning](https://semver.org/).
 
+## [0.31.7] - 2026-10-22
+
+### Fixed
+- **InChI engine matches the distributed binary's real contract**
+  (found by the TODO.v2/16 oracle work): `-STDIO` is not part of the
+  standard `inchi-1` interface — the engine now stages the molfile to
+  a temp file and reads the output file, the same shape as the RInChI
+  engine. Verified against the brew 1.07.5 build.
+- **Tetrahedral stereo actually reaches the oracle now**: the writer
+  emits a wedge on the stereocentre's first bond (TH1 up, TH2 down);
+  the V2000 atom-parity field alone is ignored by `inchi-1` for 2D
+  input, so the previous parity-only claim never produced stereo
+  InChIs. Enantiomers now derive distinct standard InChIs
+  (`N[C@H](C)C(=O)O` → the published L-alanine key), gated by the
+  real-binary spec (`ASCIICHEM_INCHI_BIN`).
+- **Molfile round-trip folds chirality wedges back**: a wedge/hash
+  bond on a parity-chiral atom reads as the plain single bond it was
+  written from, instead of re-entering the model as a wedge/hash
+  bond kind.
+- **Structure writers decline formula-style adjacency instead of
+  silently fragmenting**: `CCO` and undashed mixtures
+  (`C1=CC=CC=C1` — only its double bonds + one ring closure are
+  explicit) used to write disconnected graphs and garbage SMILES;
+  `Structure::Graph.build!` now declines with guidance while the
+  tolerant `build` stays available to the linter. SMILES-ingested
+  models are unaffected (their branch reconnection crosses as a
+  ring-closure digit, so the graph is connected).
+
+## [0.31.6] - 2026-10-21
+
+### Added
+- **Mechanism wire ingestion** (TODO.v2/13 item 4): `from_model_json`
+  restores mechanisms — steps return as canonical reaction text, flows
+  and spectators intact; cascade steps have no wire form and raise
+  instead of silently flattening. Mechanism round-trip is asserted
+  corpus-wide (the `modelJsonRoundTrip` flag is gone).
+
+### Changed
+- **BalanceCheck diagnostics carry structured details**: each
+  imbalance reports `element => [reactants, products]` deltas for
+  every element whose counts differ, alongside the message.
+- **RInChI engine matches the real `rinchi_cmdline` contract**
+  (validated end-to-end against the IUPAC binary built from source):
+  the RXN file is the positional argument (no flags), direction-distinct
+  identities for a reaction and its reverse.
+- Hermetic CI: the conformance corpus is pinned (`CORPUS_REF: v0.8.0`)
+  and the schema re-vendor script defaults to the released
+  asciichem-model tag (v0.6.0) — CI inputs no longer float at `main`.
+
 ## [0.31.5] - 2026-10-20
 
 ### Changed

data/lib/asciichem/inchi/binary_engine.rb

@@ -6,13 +6,20 @@ module AsciiChem
   module Inchi
     # Engine that shells out to the standalone IUPAC `inchi-1`
     # binary. The binary is a documented external dependency — nothing
-    # is vendored (vendoring the InChI library requires the licence
-    # review recorded in TODO.v2 10, a maintainer decision).
+    # is vendored (TODO.v2 16 keeps it that way; the native path is a
+    # separate engine).
+    #
+    # Contract: the distributed binary's file interface
+    # (`inchi-1 input.mol output.txt [flags]`). `-STDIO` is NOT part
+    # of it — the standard distribution ignores it and prints usage
+    # (caught against the brew 1.07.5 build), so the engine stages the
+    # molfile to a temp file and reads the output file back, the same
+    # shape as the RInChI engine.
     #
     #   AsciiChem::Inchi.engine = AsciiChem::Inchi::BinaryEngine.new
     #   AsciiChem::Inchi.engine = AsciiChem::Inchi::BinaryEngine.new(bin: "/usr/local/bin/inchi-1")
     class BinaryEngine < Engine
-      DEFAULT_FLAGS = %w[-STDIO -AuxNone -NoLabels -Key].freeze
+      DEFAULT_FLAGS = %w[-AuxNone -NoLabels -Key].freeze
 
       attr_reader :bin, :flags
 
@@ -39,13 +46,21 @@ module AsciiChem
 
       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
+      def execute(molfile)
+        require 'tmpdir'
+        Dir.mktmpdir('asciichem-inchi') do |dir|
+          input = File.join(dir, 'structure.mol')
+          output = File.join(dir, 'structure.txt')
+          File.write(input, molfile)
+          _out, err, status = Open3.capture3(bin, input, output, *flags)
+          unless status.success?
+            raise AsciiChem::Error, "#{bin} failed (exit #{status.exitstatus}): #{err.strip[0, 500]}"
+          end
 
-        out
+          # A clean run with no output file means no structure output;
+          # the caller's InChI= regex raises the no-InChI error.
+          File.exist?(output) ? File.read(output) : ''
+        end
       rescue Errno::ENOENT
         raise EngineMissingError, "InChI engine binary #{bin.inspect} not found — #{AsciiChem::Inchi::INSTALL_GUIDE}"
       end

data/lib/asciichem/linter/balance_check.rb

@@ -33,7 +33,8 @@ module AsciiChem
         diffs = compute_diffs(reactants, products)
         diagnostics << error(
           "Reaction is not balanced: #{diffs}",
-          node: reaction
+          node: reaction,
+          details: element_deltas(reactants, products)
         )
       end
 
@@ -87,6 +88,16 @@ module AsciiChem
         result
       end
 
+      # Element => [reactant_count, product_count] for every element
+      # whose counts differ — the numbers behind the message.
+      def element_deltas(reactants, products)
+        (reactants.keys | products.keys).sort.each_with_object({}) do |element, out|
+          r = reactants.fetch(element, 0)
+          p = products.fetch(element, 0)
+          out[element] = [r, p] if r != p
+        end
+      end
+
       def compute_diffs(reactants, products)
         all_elements = (reactants.keys + products.keys).uniq.sort
         all_elements.map do |element|

data/lib/asciichem/linter/base.rb

@@ -22,16 +22,16 @@ module AsciiChem
 
       protected
 
-      def error(message, node: nil)
-        Diagnostic.new(severity: :error, message: message, node: node)
+      def error(message, node: nil, details: nil)
+        Diagnostic.new(severity: :error, message: message, node: node, details: details)
       end
 
-      def warning(message, node: nil)
-        Diagnostic.new(severity: :warning, message: message, node: node)
+      def warning(message, node: nil, details: nil)
+        Diagnostic.new(severity: :warning, message: message, node: node, details: details)
       end
 
-      def info(message, node: nil)
-        Diagnostic.new(severity: :info, message: message, node: node)
+      def info(message, node: nil, details: nil)
+        Diagnostic.new(severity: :info, message: message, node: node, details: details)
       end
 
       # Depth-first walk over every node in the formula. Yields each

data/lib/asciichem/linter/diagnostic.rb

@@ -2,7 +2,12 @@
 
 module AsciiChem
   module Linter
-    Diagnostic = Struct.new(:severity, :message, :node, keyword_init: true) do
+    # `details` carries optional structured data behind the message
+    # (e.g. BalanceCheck's per-element [reactants, products] counts)
+    # for consumers that want the numbers, not the prose. Human-facing
+    # output stays the message.
+    Diagnostic = Struct.new(:severity, :message, :node, :details,
+                            keyword_init: true) do
       def to_s
         context = node&.diagnostic_label
         if context

data/lib/asciichem/molfile/parser.rb

@@ -26,6 +26,22 @@ module AsciiChem
         bonds = parse_bonds(bond_count)
         properties = parse_properties
 
+        # A wedge/hash bond on an atom whose parity field already
+        # carries chirality is that chirality's wedge (our writer
+        # emits exactly that pair), not an independent bond kind —
+        # fold it back to its plain single bond.
+        chiral = atoms.each_with_index
+                      .select { |atom, _| atom.chirality }
+                      .map { |_, i| i }
+        bonds = bonds.map do |bond|
+          if %i[wedge hash].include?(bond[:kind]) &&
+             (chiral.include?(bond[:from]) || chiral.include?(bond[:to]))
+            bond.merge(kind: :single)
+          else
+            bond
+          end
+        end
+
         apply_legacy_charge!(atoms)
         apply_charges!(atoms, properties[:charges])
         apply_isotopes!(atoms, properties[:isotopes])

data/lib/asciichem/molfile/writer.rb

@@ -8,13 +8,14 @@ module AsciiChem
     # 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.
+    # Tetrahedral chirality crosses as a WEDGE on the stereocentre's
+    # first bond (TH1 → up, TH2 → down), oriented centre → neighbour:
+    # the oracle ignores the V2000 atom-parity field for 2D input
+    # (verified against inchi-1 1.07.5 — enantiomers only separate
+    # through the wedge), so the parity field alone never carries
+    # stereo. 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,
@@ -29,7 +30,7 @@ module AsciiChem
       end
 
       def write
-        atoms, edges = Structure::Graph.build(@molecule)
+        atoms, edges = Structure::Graph.build!(@molecule)
         raise ParseError, "molecule has no bonds — a formula is not a structure" if edges.empty? && atoms.length > 1
 
         lines = []
@@ -47,13 +48,18 @@ module AsciiChem
                           hcount_code(atom))
         end
 
+        wedges = wedge_bonds(atoms, edges)
         edges.each do |edge|
           type = BOND_TYPES.fetch(edge.kind) do
             raise ParseError, "#{edge.kind} bonds have no molfile V2000 type"
           end
           stereo = BOND_STEREO.fetch(edge.kind, 0)
+          from, to = edge.from, edge.to
+          if (wedge = wedges[edge.object_id])
+            from, to, stereo = wedge
+          end
           lines << format("%3d%3d%3d%3d  0  0  0  0  0  0  0",
-                          edge.from + 1, edge.to + 1, type, stereo)
+                          from + 1, to + 1, type, stereo)
         end
 
         lines << property_line("M  CHG", charge_pairs(atoms))
@@ -64,6 +70,28 @@ module AsciiChem
 
       private
 
+      # One wedge per chiral atom, on its first bond, oriented
+      # centre → neighbour: TH1 rises (stereo 1), TH2 falls (6).
+      # Returns { edge.object_id => [from, to, stereo] }.
+      def wedge_bonds(atoms, edges)
+        wedges = {}
+        atoms.each_with_index do |atom, index|
+          next unless CHIRALITY_PARITY.key?(atom.chirality)
+
+          edge = edges.find { |e| e.from == index || e.to == index }
+          next unless edge
+
+          stereo = atom.chirality == 'TH1' ? 1 : 6
+          wedges[edge.object_id] =
+            if edge.from == index
+              [index, edge.to, stereo]
+            else
+              [index, edge.from, stereo]
+            end
+        end
+        wedges
+      end
+
       # 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)

data/lib/asciichem/rinchi/binary_engine.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'open3'
+require 'tempfile'
 
 module AsciiChem
   module Rinchi
@@ -10,24 +11,28 @@ module AsciiChem
     # 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")
+    #   AsciiChem::Rinchi.engine = AsciiChem::Rinchi::BinaryEngine.new(bin: "/usr/local/bin/rinchi_cmdline")
+    # The reference CLI (IUPAC-InChI/RInChI's `rinchi_cmdline`) takes a
+    # FILE argument, not stdin, needs no flags, and prints RInChI=,
+    # RAuxInfo=, Long-RInChIKey=, Short-RInChIKey= and Web-RInChIKey=
+    # lines. The engine writes the RXN to a temp file, runs the binary
+    # on it, and reads the identity lines back.
     class BinaryEngine
-      DEFAULT_FLAGS = %w[-STDIO -AuxNone -NoLabels -Key].freeze
+      DEFAULT_FLAGS = [].freeze
 
       attr_reader :bin, :flags
 
-      def initialize(bin: 'rinchi-1', flags: DEFAULT_FLAGS)
+      def initialize(bin: 'rinchi_cmdline', 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
+      # reaction → RXN → rinchi binary → 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)
+        out = execute(AsciiChem::Rxn.write(reaction))
         rinchi = out[/^RInChI=\S+/]
         raise AsciiChem::Error, "#{bin} produced no RInChI:\n#{out}" unless rinchi
 
@@ -40,16 +45,26 @@ module AsciiChem
 
       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]}"
+      def execute(rxn)
+        out = err = nil
+        status = nil
+        Tempfile.create(['asciichem', '.rxn']) do |file|
+          file.write(rxn)
+          file.flush
+          out, err, status = Open3.capture3(bin, file.path, *flags)
         end
-
+        report_failure(status, err, out)
         out
       rescue Errno::ENOENT
         raise EngineMissingError, "RInChI engine binary #{bin.inspect} not found — #{AsciiChem::Rinchi::INSTALL_GUIDE}"
       end
+
+      def report_failure(status, err, out)
+        return if status&.success?
+
+        raise AsciiChem::Error,
+              "#{bin} failed (exit #{status&.exitstatus}): #{((err || '') + (out || '')).strip[0, 500]}"
+      end
     end
   end
 end

data/lib/asciichem/rinchi.rb

@@ -15,9 +15,11 @@ module AsciiChem
     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")'
+                    '(https://github.com/IUPAC-InChI/RInChI — build ' \
+                    'src/example_apps/rinchi_cmdline against InChI v1.07.5) ' \
+                    'and set AsciiChem::Rinchi.engine = ' \
+                    'AsciiChem::Rinchi::BinaryEngine.new ' \
+                    '(or pass bin: "path/to/rinchi_cmdline")'
 
     class << self
       attr_accessor :engine

data/lib/asciichem/structure/graph.rb

@@ -9,12 +9,46 @@ module AsciiChem
       Edge = Struct.new(:from, :to, :kind, :direction, keyword_init: true)
 
       class << self
-        # Returns [atoms, edges] where atoms is the atom array in
-        # walk order and edges is an array of Edge with array indexes.
+        # Returns [atoms, edges] where atoms is the atom array in walk
+        # order and edges is an array of Edge with array indexes.
+        #
+        # Tolerant on purpose: the linter counts exactly the bonds that
+        # are written. Structure writers use `build!`, which declines
+        # formula-style adjacency (see there).
         def build(molecule)
+          atoms, edges, = build_with_adjacency(molecule)
+          [atoms, edges]
+        end
+
+        # Structure writers only. Text adjacency — atoms with no bond
+        # token between them (`CCO`, the undashed spacers in
+        # `C1=CC=CC=C1`) — is formula notation, not a bond; mixing it
+        # with explicit bonds silently fragments the graph (a benzene
+        # ring written as a disconnected C4+C2 pair), so the strict
+        # build declines when adjacency is present and the final graph
+        # is disconnected. SMILES models never trip this: their parser
+        # always bonds every continuation (branch reconnection crosses
+        # as a ring-closure digit), so the graph is connected even
+        # though the flat node list has token-less boundaries — and an
+        # explicit multi-component model (a salt written `A.B`) has no
+        # adjacency at all.
+        def build!(molecule)
+          atoms, edges, adjacency_pairs = build_with_adjacency(molecule)
+          return [atoms, edges] if adjacency_pairs.empty? || connected?(atoms.length, edges)
+
+          raise ParseError,
+                'adjacent atoms have no explicit bond token — a formula ' \
+                'is not a structure. Write explicit bonds (C-C) or ingest ' \
+                'the structure from SMILES/molfile.'
+        end
+
+        private
+
+        def build_with_adjacency(molecule)
           atoms = []
           edges = []
           index_by_object_id = {}
+          adjacency_pairs = []
           pending = nil
           last = nil
 
@@ -28,9 +62,11 @@ module AsciiChem
                 # same as the Layout walker.
                 index_by_object_id[node.object_id] = index
                 atoms << node
-                if pending && last
+                if pending
                   edges << Edge.new(from: last, to: index, kind: pending.kind,
-                                    direction: pending.direction)
+                                    direction: pending.direction) if last
+                elsif last
+                  adjacency_pairs << [last, index]
                 end
                 last = index
                 pending = nil
@@ -55,7 +91,30 @@ module AsciiChem
             edges << Edge.new(from: from, to: to, kind: kind)
           end
 
-          [atoms, edges]
+          [atoms, edges, adjacency_pairs]
+        end
+
+        def connected?(atom_count, edges)
+          return true if atom_count <= 1
+
+          neighbours = Array.new(atom_count) { [] }
+          edges.each do |edge|
+            neighbours[edge.from] << edge.to
+            neighbours[edge.to] << edge.from
+          end
+          seen = [false] * atom_count
+          seen[0] = true
+          queue = [0]
+          until queue.empty?
+            current = queue.shift
+            neighbours[current].each do |n|
+              next if seen[n]
+
+              seen[n] = true
+              queue << n
+            end
+          end
+          seen.all?
         end
       end
     end

data/lib/asciichem/version.rb

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

data/lib/asciichem/wire_adapter.rb

@@ -9,17 +9,19 @@ module AsciiChem
   # fields.
   #
   # Emission (to_wire/to_model_json) covers every wire type.
-  # Ingestion (from_wire/from_model_json) currently covers the
-  # lossless core set: formula, atom, molecule, group, bond,
+  # Ingestion (from_wire/from_model_json) covers the lossless core
+  # set plus mechanism: formula, atom, molecule, group, bond,
   # identifier, name, reaction (+conditions), reaction-cascade,
-  # electron-configuration, embedded-math, text. The beyond-formulas
-  # nodes (mechanism, spectrum, crystal, zmatrix, calculation) are
+  # electron-configuration, embedded-math, text, mechanism (steps as
+  # canonical reaction text, flows, spectators; cascade steps have no
+  # wire form). Spectrum, crystal, zmatrix and calculation remain
   # emission-only until their round-trip acceptance lands in the
   # corpus.
   module WireAdapter
     CORE_INGEST_TYPES = %w[
       formula atom molecule group bond identifier name reaction
       reaction-cascade electron-configuration embedded-math text
+      mechanism
     ].freeze
 
     class << self
@@ -72,20 +74,27 @@ module AsciiChem
       # only routes `type` and re-injects routed children into
       # polymorphic collections (which lutaml deserialises flat).
       def wire_tree_from_hash(hash)
-        type = hash.fetch("type") { raise KeyError, "wire node missing type discriminator" }
+        type = hash.fetch('type') { raise KeyError, 'wire node missing type discriminator' }
         klass = AsciiChem::Wire::REGISTRY.fetch(type) do
           raise KeyError, "unknown wire node type #{type.inspect}"
         end
 
         wire = klass.from_json(JSON.generate(hash))
         case type
-        when "formula", "molecule", "group"
-          wire.nodes = hash.fetch("nodes", []).map { |child| wire_tree_from_hash(child) }
-        when "reaction"
-          wire.reactants = hash.fetch("reactants", []).map { |child| wire_tree_from_hash(child) }
-          wire.products = hash.fetch("products", []).map { |child| wire_tree_from_hash(child) }
-        when "reaction-cascade"
-          wire.steps = hash.fetch("steps", []).map { |child| wire_tree_from_hash(child) }
+        when 'formula', 'molecule', 'group'
+          wire.nodes = hash.fetch('nodes', []).map { |child| wire_tree_from_hash(child) }
+        when 'reaction'
+          wire.reactants = hash.fetch('reactants', []).map { |child| wire_tree_from_hash(child) }
+          wire.products = hash.fetch('products', []).map { |child| wire_tree_from_hash(child) }
+        when 'reaction-cascade'
+          wire.steps = hash.fetch('steps', []).map { |child| wire_tree_from_hash(child) }
+        when 'mechanism'
+          wire.steps = hash.fetch('steps', []).map do |step_hash|
+            step = AsciiChem::Wire::MechanismStep.from_json(JSON.generate(step_hash))
+            step.reaction = wire_tree_from_hash(step_hash.fetch('reaction'))
+            step
+          end
+          wire.spectators = hash.fetch('spectators', []).map { |child| wire_tree_from_hash(child) }
         end
         wire
       end
@@ -93,12 +102,12 @@ module AsciiChem
       private
 
       def formula_to_wire(node)
-        AsciiChem::Wire::Formula.new(type: "formula", nodes: node.nodes.map { |n| to_wire(n) })
+        AsciiChem::Wire::Formula.new(type: 'formula', nodes: node.nodes.map { |n| to_wire(n) })
       end
 
       def atom_to_wire(atom)
         AsciiChem::Wire::Atom.new(
-          type: "atom",
+          type: 'atom',
           element: atom.element,
           isotope: digits_or_nil(atom.isotope), charge: str_or_nil(atom.charge),
           subscript: digits_or_nil(atom.subscript),
@@ -134,7 +143,7 @@ module AsciiChem
 
       def molecule_to_wire(node)
         AsciiChem::Wire::Molecule.new(
-          type: "molecule",
+          type: 'molecule',
           nodes: node.nodes.map { |n| to_wire(n) },
           coefficient: node.coefficient,
           stereo: stereo_to_wire(node.stereo),
@@ -158,7 +167,7 @@ module AsciiChem
 
       def group_to_wire(node)
         AsciiChem::Wire::Group.new(
-          type: "group",
+          type: 'group',
           nodes: node.nodes.map { |n| to_wire(n) },
           multiplicity: node.multiplicity,
           bracket: node.bracket.to_s
@@ -166,27 +175,27 @@ module AsciiChem
       end
 
       def bond_to_wire(node)
-        AsciiChem::Wire::Bond.new(type: "bond", kind: node.kind.to_s,
+        AsciiChem::Wire::Bond.new(type: 'bond', kind: node.kind.to_s,
                                   direction: str_or_nil(node.direction&.to_s))
       end
 
       def identifier_to_wire(node)
         AsciiChem::Wire::Identifier.new(
-          type: "identifier",
+          type: 'identifier',
           value: node.value, convention: node.convention.to_s, dict_ref: node.dict_ref
         )
       end
 
       def name_to_wire(node)
         AsciiChem::Wire::Name.new(
-          type: "name",
+          type: 'name',
           content: node.content, convention: node.convention, dict_ref: node.dict_ref
         )
       end
 
       def reaction_to_wire(node)
         AsciiChem::Wire::Reaction.new(
-          type: "reaction",
+          type: 'reaction',
           reactants: node.reactants.map { |m| molecule_to_wire(m) },
           products: node.products.map { |m| molecule_to_wire(m) },
           arrow: node.arrow.to_s,
@@ -202,14 +211,14 @@ module AsciiChem
 
       def cascade_to_wire(node)
         AsciiChem::Wire::ReactionCascade.new(
-          type: "reaction-cascade",
+          type: 'reaction-cascade',
           steps: node.steps.map { |r| reaction_to_wire(r) }
         )
       end
 
       def econfig_to_wire(node)
         AsciiChem::Wire::ElectronConfiguration.new(
-          type: "electron-configuration",
+          type: 'electron-configuration',
           orbitals: node.orbitals.map do |(label, count)|
             AsciiChem::Wire::OrbitalOccupancy.new(orbital: label.to_s, occupancy: count.to_s)
           end,
@@ -226,16 +235,16 @@ module AsciiChem
       end
 
       def math_to_wire(node)
-        AsciiChem::Wire::EmbeddedMath.new(type: "embedded-math", source: node.source)
+        AsciiChem::Wire::EmbeddedMath.new(type: 'embedded-math', source: node.source)
       end
 
       def text_to_wire(node)
-        AsciiChem::Wire::Text.new(type: "text", content: node.content)
+        AsciiChem::Wire::Text.new(type: 'text', content: node.content)
       end
 
       def mechanism_to_wire(node)
         AsciiChem::Wire::Mechanism.new(
-          type: "mechanism",
+          type: 'mechanism',
           steps: node.steps.map { |step| mechanism_step_to_wire(step) },
           spectators: node.spectators.map { |sp| mechanism_spectator_to_wire(sp) }
         )
@@ -264,12 +273,16 @@ module AsciiChem
 
       # 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.
+      # grammar parses it here. A cascade step has no wire form —
+      # MechanismStep.reaction is typed Reaction — and says so instead
+      # of silently flattening the chain.
       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)
+        when AsciiChem::Model::ReactionCascade
+          raise AsciiChem::ParseError,
+                "mechanism step cascades have no wire form: #{text.inspect}"
         else
           raise AsciiChem::ParseError,
                 "mechanism step is not a reaction: #{text.inspect}"
@@ -278,7 +291,7 @@ module AsciiChem
 
       def spectrum_to_wire(node)
         AsciiChem::Wire::Spectrum.new(
-          type: "spectrum",
+          type: 'spectrum',
           technique: node.type,
           params: node.params,
           peaks: node.peaks.map do |peak|
@@ -292,7 +305,7 @@ module AsciiChem
 
       def crystal_to_wire(node)
         AsciiChem::Wire::Crystal.new(
-          type: "crystal",
+          type: 'crystal',
           name: node.name, a: node.a, b: node.b, c: node.c,
           alpha: node.alpha, beta: node.beta, gamma: node.gamma,
           spacegroup: node.spacegroup,
@@ -302,7 +315,7 @@ module AsciiChem
 
       def zmatrix_to_wire(node)
         AsciiChem::Wire::ZMatrix.new(
-          type: "zmatrix",
+          type: 'zmatrix',
           rows: node.rows.map do |row|
             AsciiChem::Wire::ZRow.new(
               atom: row.atom, ref1: row.ref1, distance: row.distance,
@@ -314,7 +327,7 @@ module AsciiChem
 
       def calculation_to_wire(node)
         AsciiChem::Wire::Calculation.new(
-          type: "calculation",
+          type: 'calculation',
           method: node.method, basis: node.basis,
           properties: node.properties.map do |prop|
             AsciiChem::Wire::CalculatedProperty.new(
@@ -394,6 +407,26 @@ module AsciiChem
         )
       end
 
+      def mechanism_from_wire(wire)
+        AsciiChem::Model::Mechanism.new(
+          steps: Array(wire.steps).map { |s| mechanism_step_from_wire(s) },
+          spectators: Array(wire.spectators).map { |sp| molecule_from_wire(sp).to_text }
+        )
+      end
+
+      # The model keeps a step's reaction as TEXT; the wire carries the
+      # typed node, so ingestion renders it back through the canonical
+      # text form.
+      def mechanism_step_from_wire(step)
+        AsciiChem::Model::Mechanism::Step.new(
+          label: step.label,
+          reaction: from_wire(step.reaction).to_text,
+          flows: Array(step.flows).map do |flow|
+            AsciiChem::Model::Mechanism::Flow.new(source: flow.source, target: flow.target)
+          end
+        )
+      end
+
       def electron_configuration_from_wire(wire)
         AsciiChem::Model::ElectronConfiguration.new(
           orbitals: Array(wire.orbitals).map { |o| [o.orbital, o.occupancy] },

data/scripts/update-model-schemas.sh

@@ -1,9 +1,10 @@
 #!/usr/bin/env bash
 # Re-vendor the asciichem-model v1 JSON Schemas (YAML) and examples.
-# Usage: scripts/update-model-schemas.sh [model-tag] (default: main).
+# Usage: scripts/update-model-schemas.sh [model-tag]. Default is the
+# released tag — vendored schemas stay hermetic, never floating.
 set -euo pipefail
 
-tag="${1:-main}"
+tag="${1:-v0.6.0}"
 work="$(mktemp -d)"
 trap 'rm -rf "$work"' EXIT
 

metadata

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