asciichem 0.31.4 → 0.31.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c9c3f297f95612987dbe2a4e7f15bcaa0d4628dbae0d074dce5aeea2fb5e0efa
-  data.tar.gz: 75a1ef4ea31451fccfb37369299d86afa1a08b26c825054de2eda109c636a561
+  metadata.gz: ac2c54a74f212244c74efeb88156c34398cdfe87751de14a597833533f4ccb92
+  data.tar.gz: 8f5614c2703ae6ee1440be65fa2c7654bc3cc12d2c8b1207f43a974ab804e3f2
 SHA512:
-  metadata.gz: cba5c440d3da6c3a436b207d36203f07641ad1b76c61ade69ac5e39697c1b79a81374f7e7106a5764611b3f400f28f9dae89a7054a70c4124b6c21da0d6f8c8a
-  data.tar.gz: e7cb123f63497d962297ea6629e684a0b8af6417c494a7332e02a9729585e977a0c02e2acdd6ee7eb99868fa70475b9a8e57e748eb38fde789957c66a8dc2afa
+  metadata.gz: 487d422ca183453e7e9a82de50aaa1c6e671383047838ca0acab124678520bf08edbe20a115f3c416407683e45b07cc5654b46bdcb71559004ef22271989d90b
+  data.tar.gz: ae81c712c9d31ffd440b8ad49200aea40c52251f8a6017344d0ce6bbd70b3b236ac89c850e2aac57c6866f87cec986a0c26694989b5f4b40eed7ffc147c1bbdb

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/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,50 @@
 All notable changes to AsciiChem are documented here.
 This project follows [Semantic Versioning](https://semver.org/).
 
+## [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
+- 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

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

@@ -91,27 +91,56 @@ module AsciiChem
               .select { |deficit| deficit >= 0 && deficit.modulo(1).zero? }
     end
 
-    # 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.
+    # π-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)
       cyclic_atoms = cycles.flatten.uniq
-      six = cycles.select { |cycle| cycle.length == 6 }
-      six.select { |cycle| cycle.all? { |i| sp2?(i, atoms, edges, cyclic_atoms) } }
+      cycles.select { |cycle| aromatic_cycle?(cycle, atoms, edges, cyclic_atoms) }
     end
 
-    def sp2?(atom_index, atoms, edges, cyclic_atoms)
-      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|
         next false unless edge.from == atom_index || edge.to == atom_index
         next false unless edge.kind == :double

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/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
@@ -71,13 +75,27 @@ module AsciiChem
       # 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.
+      # 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 { |index| @perceived_aromatic[index] = true }
+          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
@@ -85,6 +103,19 @@ module AsciiChem
         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)
@@ -269,8 +300,12 @@ module AsciiChem
         atom = @atoms[index]
         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 =
@@ -280,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 << ']'

data/lib/asciichem/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module AsciiChem
-  VERSION = "0.31.4"
+  VERSION = "0.31.6"
 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.4
+  version: 0.31.6
 platform: ruby
 authors:
 - Ribose Inc.