asciichem 0.31.5 → 0.31.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6c9a131b0a052014c60f5be8b74972de24db882f7db088b82bdea1c506709a46
-  data.tar.gz: 9b280851bdc1fb8c4f4681f1887796f2eb688298f8c495cd81a766a879fd8a09
+  metadata.gz: ac2c54a74f212244c74efeb88156c34398cdfe87751de14a597833533f4ccb92
+  data.tar.gz: 8f5614c2703ae6ee1440be65fa2c7654bc3cc12d2c8b1207f43a974ab804e3f2
 SHA512:
-  metadata.gz: d5580a3f5f314447b3f1f932b37396bb5741bd5363d96e4ae97cc95fcbcf7cfbcd0690ae16253c532d21b2c790093fda0652cd3d1a330f3bcbce9e1801c66e66
-  data.tar.gz: 44a0d45dfca800429e648a5a3c3adab685c5813c7c23d5be68afb55c7dc4cf34410b8cb16ff43681a439d9ec258c7e4f71aa141e7d3561a6a05c0ccc2cbc3f5b
+  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/CHANGELOG.md

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

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

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