asciichem 0.22.0 → 0.24.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d1aef5e42c0840b8bff4d291220e84f76f9536a9dba1cca3445deacb696388b1
-  data.tar.gz: 92e28e623dfb7494080a9ee80d3545fa5a593d83d545775d890b7a9a5594c0bd
+  metadata.gz: d733aab290b1e54dfd0139d75a92888dfb8fc2af088544a07cc4395e523e583f
+  data.tar.gz: 5dfe21e949307366a6afbcc94bf2c52f9e9cfedb4a1f328996fbde3a20b5ec99
 SHA512:
-  metadata.gz: bab5532c9007d1a5bd2079b792a66458d411f48af5ac59f04ad9e4a9150c7b53844639e67a46494dac7e6ae05f3451904a8fbe927b711803184749f00ce40e7e
-  data.tar.gz: c0a9cb7f9f01e25dcce78f69894c23c8d5fe75d2d21fd20828d2daafa133186ebeb46d2aeb09bfc4246f43f851a3b982c4691cd013c40c56085634ca54f9db01
+  metadata.gz: cdeb663f26df5189cd73df0d7c5f6a9ad3918d981d924ec08f1a781728415af474840de566a8d8f1075cb0cdc0d7086f41f92b80250efee6f71ebd11cdc62680
+  data.tar.gz: 371e88363eb2e143b2b8a1b3f1a3cbc339d3eb81d5bcd521fdc00d02fd90e6068c769864185198c8e35e5ae6e2fc95b0088885d760844f527118a50469eaa9fb

data/CHANGELOG.md

@@ -3,6 +3,33 @@
 All notable changes to AsciiChem are documented here.
 This project follows [Semantic Versioning](https://semver.org/).
 
+## [0.24.0] - 2026-09-13
+
+### Added
+- `AsciiChem::Citation` (TODO.impl 44): one dataset-type Relaton
+  bibitem per (substance, source) — the citation track's core
+  contract. Source-specific fields live in per-source profiles
+  (PubChem, Common Chemistry); every identifier rides along as a
+  keyword so citations are machine-checkable. Runtime dependency:
+  relaton-bib (classic model).
+- `Resolver::CommonChemistry` (TODO.impl 40, maintainer sign-off
+  2026-09-13): CAS RN lookups against CAS Common Chemistry. CC BY-NC
+  4.0 posture is enforced in code — the adapter never self-registers;
+  users opt in explicitly, and every result carries the required
+  attribution.
+
+## [0.23.0] - 2026-09-12
+
+### Added
+- `AsciiChem::Resolver` — multi-source identifier resolution (TODO.impl
+  38): opt-in adapter registry, one substance per source with
+  provenance, cross-check Conflict on InChIKey disagreement, TTL
+  cache in the user cache dir.
+- `Resolver::PubChem` — keyless PUG-REST adapter with recorded
+  offline fixtures; CAS via the name namespace (TODO.impl 39).
+- CLI `resolve` (networked, cached, `--refresh`) and offline
+  `validate` for identifier annotations (TODO.impl 41).
+
 ## [0.22.0] - 2026-09-12
 
 ### Added
@@ -399,7 +426,9 @@ This project follows [Semantic Versioning](https://semver.org/).
   `version`.
 - Comprehensive RSpec suite with round-trip conformance.
 
-[Unreleased]: https://github.com/asciichem/asciichem-ruby/compare/v0.22.0...HEAD
+[Unreleased]: https://github.com/asciichem/asciichem-ruby/compare/v0.24.0...HEAD
+[0.24.0]: https://github.com/asciichem/asciichem-ruby/compare/v0.23.0...v0.24.0
+[0.23.0]: https://github.com/asciichem/asciichem-ruby/compare/v0.22.0...v0.23.0
 [0.22.0]: https://github.com/asciichem/asciichem-ruby/compare/v0.21.0...v0.22.0
 [0.21.0]: https://github.com/asciichem/asciichem-ruby/compare/v0.20.0...v0.21.0
 [0.20.0]: https://github.com/asciichem/asciichem-ruby/compare/v0.19.0...v0.20.0

data/asciichem.gemspec

@@ -38,6 +38,7 @@ Gem::Specification.new do |spec|
   spec.add_dependency "lutaml-model", ">= 0.8", "< 2"
   spec.add_dependency "nokogiri", "~> 1.16"
   spec.add_dependency "parslet", "~> 2.0"
+  spec.add_dependency "relaton-bib", ">= 0.1", "< 2"
   spec.add_dependency "plurimath", "~> 0.8"
   spec.add_dependency "thor", "~> 1.3"
 

data/lib/asciichem/citation.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require "relaton_bib"
+
+module AsciiChem
+  # Citation track (TODO.v2 08; TODO.impl 44): a bibitem is a function
+  # of (substance, source) — one dataset-type Relaton bibitem per
+  # source the user chooses to cite, because two databases agreeing on
+  # a substance are still two different documents.
+  #
+  # Source-specific fields (link shape, publisher string, docidentifier
+  # scheme) live in PROFILES; adding a source is one entry (OCP).
+  module Citation
+    # Source-specific citation profile. Default fields fall back to
+    # the substance's provenance.
+    Profile = Struct.new(:publisher, :link_for, :identifier_for, keyword_init: true)
+
+    PROFILES = {
+      "pubchem" => Profile.new(
+        publisher: "PubChem, U.S. National Library of Medicine",
+        link_for: ->(substance) do
+          cid = substance.identifier_value("pubchem-cid")
+          "https://pubchem.ncbi.nlm.nih.gov/compound/#{cid}" if cid
+        end,
+        identifier_for: ->(substance) do
+          cid = substance.identifier_value("pubchem-cid")
+          "PubChem CID #{cid}" if cid
+        end
+      ),
+      "common_chemistry" => Profile.new(
+        publisher: "CAS Common Chemistry",
+        link_for: ->(substance) do
+          cas = substance.identifier_value("cas")
+          "https://commonchemistry.cas.org/detail?cas_rn=#{cas}" if cas
+        end,
+        identifier_for: ->(substance) do
+          cas = substance.identifier_value("cas")
+          "CAS RN #{cas}" if cas
+        end
+      )
+    }.freeze
+
+    DEFAULT_PROFILE = Profile.new(
+      publisher: nil,
+      link_for: ->(_substance) { nil },
+      identifier_for: ->(substance) do
+        key = substance.identifiers.first
+        "#{key.convention}: #{key.value}" if key
+      end
+    ).freeze
+    private_constant :DEFAULT_PROFILE
+
+    class << self
+      # Builds a Relaton dataset-type bibitem for the substance as
+      # cited from its recorded source. Raises when the substance
+      # carries no provenance (hand-built, not resolved).
+      def bibitem(substance)
+        provenance = substance.provenance
+        unless provenance&.source
+          raise Error, "substance has no provenance - resolve it first (AsciiChem::Resolver)"
+        end
+
+        profile = PROFILES.fetch(provenance.source, DEFAULT_PROFILE)
+        RelatonBib::BibliographicItem.new(
+          type: "dataset",
+          title: [{ type: "main",
+                    content: "#{title_base(substance)} - #{profile.publisher || provenance.source} substance record" }],
+          docid: [RelatonBib::DocumentIdentifier.new(
+                    id: profile.identifier_for.call(substance) || "#{provenance.source} substance",
+                    type: provenance.source)],
+          contributor: [{ entity: RelatonBib::Organization.new(name: profile.publisher || provenance.source),
+                          role: [{ type: "publisher" }] }],
+          date: [{ type: "accessed", on: accessed_on(provenance) }],
+          link: [{ type: "src", content: profile.link_for.call(substance) }].compact,
+          keyword: substance.identifiers.map { |i| "#{i.convention}=#{i.value}" }
+        )
+      end
+
+      # Convenience: bibitem XML (what a document pipeline embeds).
+      def to_xml(substance)
+        bibitem(substance).to_xml
+      end
+
+      private
+
+      def title_base(substance)
+        substance.preferred_name || substance.identifier_value("cas") ||
+          substance.identifier_value("inchikey") || "Substance"
+      end
+
+      def accessed_on(provenance)
+        return provenance.retrieved_at[0, 10] if provenance.retrieved_at
+
+        Time.now.utc.strftime("%Y-%m-%d")
+      end
+    end
+  end
+end

data/lib/asciichem/cli.rb

@@ -86,6 +86,61 @@ module AsciiChem
       "asciichem #{command.usage}"
     end
 
+    desc "resolve --cas X | --name X | ...", "Resolve a substance from a source (network; cached)"
+    method_option :cas, type: :string, desc: "CAS registry number"
+    method_option :name, type: :string, desc: "Substance name"
+    method_option :cid, type: :string, desc: "PubChem CID"
+    method_option :inchikey, type: :string, desc: "InChIKey"
+    method_option :smiles, type: :string, desc: "SMILES"
+    method_option :source, type: :string, default: "pubchem", desc: "Resolver source"
+    method_option :refresh, type: :boolean, default: false, desc: "Bypass the cache"
+    method_option :format, aliases: "-t", type: :string, default: "model-json",
+                            desc: "Output: model-json | text | smiles"
+    def resolve
+      convention, value = %i[cas name cid inchikey smiles]
+                          .filter_map { |k| [k, options[k.to_s]] if options[k.to_s] }
+                          .first
+      raise AsciiChem::Error, "give one of --cas/--name/--cid/--inchikey/--smiles" unless value
+
+      convention = { cas: "cas", name: "name", cid: "pubchem-cid",
+                     inchikey: "inchikey", smiles: "smiles" }.fetch(convention)
+      substance = AsciiChem::Resolver[options[:source]].new.resolve(
+        value: value, convention: convention, refresh: options[:refresh]
+      )
+      raise AsciiChem::Error, "#{options[:source]} does not know #{value.inspect}" unless substance
+
+      puts case options[:format].to_s
+           when "text" then substance.preferred_name.to_s
+           when "smiles" then substance.identifier_value("canonical-smiles").to_s
+           else substance.to_model_json
+           end
+    rescue AsciiChem::Error => e
+      warn "Resolve error: #{e.message}"
+      exit 3
+    end
+
+    desc "validate -i INPUT", "Offline identifier validation"
+    method_option :input, aliases: "-i", type: :string, required: true
+    def validate
+      formula = AsciiChem.parse(options[:input])
+      annotations = formula.nodes.grep(AsciiChem::Model::Molecule).flat_map(&:identifiers)
+      if annotations.empty?
+        puts "no identifier annotations found"
+        return
+      end
+      annotations.each do |identifier|
+        known = AsciiChem::Identifiers.known?(identifier.convention)
+        valid = known && AsciiChem::Identifiers.valid?(identifier.convention, identifier.value)
+        status = known ? (valid ? "ok" : "INVALID") : "unknown convention"
+        puts format("%-12s %-40s %s", identifier.convention, identifier.value, status)
+      end
+      exit 1 if annotations.any? { |i| AsciiChem::Identifiers.known?(i.convention) &&
+                                      !AsciiChem::Identifiers.valid?(i.convention, i.value) }
+    rescue AsciiChem::ParseError => e
+      warn "Parse error: #{e.message}"
+      exit 1
+    end
+
     private
 
     def read_source

data/lib/asciichem/resolver/adapter.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module AsciiChem
+  module Resolver
+    # A source adapter. Subclasses register themselves:
+    #
+    #   class MySource < Adapter
+    #     source_name :mysource
+    #     supports "name", "inchikey"
+    #     def fetch_record(...); end
+    #   end
+    #
+    # `resolve` handles caching around `fetch_record`; the transport
+    # (`fetch`) is injectable so specs run offline.
+    class Adapter
+      class << self
+        # Declares the source name and registers the adapter (called
+        # from the class body — `inherited` fires before the body
+        # runs, so it cannot see the subclass configuration).
+        # `register: false` for opt-in sources (NC-licensed): the
+        # adapter exists but users must register it explicitly.
+        def source_name(name = nil, register: true)
+          return @source_name if name.nil?
+
+          @source_name = name.to_s
+          AsciiChem::Resolver.register(@source_name, self) if register
+        end
+
+        def supports(*conventions)
+          @supported_conventions = conventions.map(&:to_s)
+        end
+
+        def supported_conventions
+          @supported_conventions || []
+        end
+      end
+
+      def supports?(convention)
+        self.class.supported_conventions.include?(convention.to_s)
+      end
+
+      # Cache-aware resolution. `fetch` must answer #get(url) -> body
+      # String (NetFetch by default; specs inject recorded responses).
+      def resolve(value:, convention:, fetch: nil, cache: nil, refresh: false)
+        cache ||= Cache.default
+        fetch ||= NetFetch.new
+        key = cache.key_for(self.class.source_name, convention, value)
+
+        unless refresh
+          cached = cache.read(key)
+          return cached if cached
+        end
+
+        substance = fetch_record(value: value, convention: convention, fetch: fetch)
+          .tap { |s| s&.identifiers&.each { |i| i.provenance ||= default_provenance } }
+        cache.write(key, substance) if substance
+        substance
+      end
+
+      # Not-found is nil, not an error — sources legitimately answer
+      # "unknown substance" during multi-source resolution.
+      def fetch_record(**)
+        raise NotImplementedError
+      end
+
+      def default_provenance
+        Provenance.new(
+          source: self.class.source_name,
+          retrieved_at: Time.now.utc.strftime("%Y-%m-%dT%H:%M:%SZ"),
+          attribution: attribution
+        )
+      end
+
+      def attribution
+        nil
+      end
+    end
+
+    # Minimal stdlib HTTP transport. No runtime gem dependencies.
+    class NetFetch
+      def get(url, limit = 3)
+        raise Error, "too many redirects" if limit.zero?
+
+        uri = URI(url)
+        response = Net::HTTP.start(uri.host, uri.port, use_ssl: true,
+                                  open_timeout: 5, read_timeout: 10) do |http|
+          http.request(Net::HTTP::Get.new(uri.request_uri, "User-Agent" => "asciichem-resolver"))
+        end
+
+        case response
+        when Net::HTTPSuccess then response.body
+        when Net::HTTPRedirection then get(URI.join(uri, response["location"]).to_s, limit - 1)
+        when Net::HTTPNotFound then nil
+        else
+          raise Error, "HTTP #{response.code}: #{response.message}"
+        end
+      end
+    end
+  end
+end

data/lib/asciichem/resolver/cache.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require "digest"
+require "json"
+require "fileutils"
+
+module AsciiChem
+  module Resolver
+    # Resolution cache in the USER cache dir (never the gem install
+    # dir): entries carry source, retrieved-at, attribution, TTL.
+    class Cache
+      DEFAULT_TTL = 7 * 24 * 60 * 60 # chemistry identifiers are stable
+
+      attr_reader :dir
+
+      def self.default_dir
+        base = ENV.fetch("XDG_CACHE_HOME", nil) || File.join(Dir.home, ".cache")
+        File.join(base, "asciichem", "resolver")
+      end
+
+      def initialize(dir: self.class.default_dir, ttl: DEFAULT_TTL)
+        @dir = dir
+        @ttl = ttl
+      end
+
+      def self.default
+        @default ||= new
+      end
+
+      def key_for(source, convention, value)
+        Digest::SHA256.hexdigest("#{source}:#{convention}:#{value}")
+      end
+
+      def read(key)
+        path = File.join(dir, "#{key}.json")
+        return nil unless File.file?(path)
+
+        entry = JSON.parse(File.read(path))
+        return nil if stale?(entry)
+
+        Substance.from_model_json(JSON.generate(entry["substance"]))
+      rescue JSON::ParserError, StandardError
+        nil
+      end
+
+      def write(key, substance)
+        FileUtils.mkdir_p(dir)
+        File.write(File.join(dir, "#{key}.json"), JSON.pretty_generate(
+          cached_at: Time.now.utc.strftime("%Y-%m-%dT%H:%M:%SZ"),
+          ttl_seconds: @ttl,
+          substance: JSON.parse(substance.to_model_json)
+        ))
+        substance
+      end
+
+      private
+
+      def stale?(entry)
+        cached_at = Time.parse(entry["cached_at"]) rescue nil
+        return true unless cached_at
+
+        Time.now.utc - cached_at > entry.fetch("ttl_seconds", @ttl)
+      end
+    end
+  end
+end

data/lib/asciichem/resolver/common_chemistry.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require "cgi"
+require "json"
+
+module AsciiChem
+  module Resolver
+    # CAS Common Chemistry source adapter (TODO.impl 40; TODO.v2 07).
+    #
+    # License posture (maintainer sign-off 2026-09-13): Common
+    # Chemistry data is CC BY-NC 4.0 — this adapter is OPT-IN and never
+    # self-registers; users register it explicitly:
+    #
+    #   AsciiChem::Resolver.register(:common_chemistry,
+    #                                 AsciiChem::Resolver::CommonChemistry)
+    #
+    # Every result carries the required attribution.
+    class CommonChemistry < Adapter
+      source_name :common_chemistry, register: false
+      supports "cas"
+
+      BASE = "https://commonchemistry.cas.org/api/detail"
+
+      def fetch_record(value:, convention:, fetch:)
+        body = fetch.get("#{BASE}?cas_rn=#{CGI.escape(value.to_s)}")
+        return nil unless body
+
+        data = JSON.parse(body)
+        return nil if data.empty?
+
+        substance_from(data)
+      rescue JSON::ParserError => e
+        raise Error, "common_chemistry returned malformed JSON: #{e.message}"
+      end
+
+      def attribution
+        "CAS Common Chemistry (CC BY-NC 4.0)"
+      end
+
+      private
+
+      def substance_from(data)
+        provenance = default_provenance
+        identifiers = [Identifier.new(value: data["rn"], convention: "cas",
+                                      provenance: provenance)]
+        add_identifier(identifiers, data, "inchikey", "inchikey", provenance)
+        add_identifier(identifiers, data, "smiles", "canonical-smiles", provenance)
+        add_identifier(identifiers, data, "inchi", "inchi", provenance)
+        add_identifier(identifiers, data, "iupacName", "iupac-name", provenance)
+
+        Substance.new(
+          preferred_name: data["name"],
+          formula: data["formula"],
+          identifiers: identifiers,
+          properties: [
+            Property.new(name: "molecular-formula", value: data["formula"], provenance: provenance),
+            Property.new(name: "molecular-weight", value: data["molecularMass"]&.to_s,
+                         units: "g/mol", provenance: provenance)
+          ].compact,
+          # Best effort within the supported SMILES subset; the SMILES
+          # stays as an identifier when stereo keeps it out.
+          structure: parse_structure(data["smiles"])
+        )
+      end
+
+      def add_identifier(list, data, key, convention, provenance)
+        return unless data[key]
+
+        list << Identifier.new(value: data[key], convention: convention,
+                               provenance: provenance)
+      end
+
+      def parse_structure(smiles)
+        return nil unless smiles
+
+        AsciiChem.parse_smiles(smiles).nodes.first
+      rescue AsciiChem::ParseError
+        nil
+      end
+    end
+  end
+end

data/lib/asciichem/resolver/pubchem.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require "cgi"
+require "json"
+require "net/https"
+require "uri"
+
+module AsciiChem
+  module Resolver
+    # PubChem source adapter (TODO.impl 39; TODO.v2 07 Layer 2).
+    # PubChem is the default source: keyless PUG-REST, permissive
+    # terms, and the bulk mirror of Common Chemistry's validated CAS
+    # RNs (CAS numbers are indexed as names). Politeness: one request
+    # per resolution, 5/10s timeouts, no retries — PubChem asks for
+    # max 5 requests/second.
+    #
+    # Citation profile (TODO.v2 08): publisher NCBI, per-access
+    # versioning (retrievedAt provenance), compound link
+    # https://pubchem.ncbi.nlm.nih.gov/compound/{cid}.
+    class PubChem < Adapter
+      source_name :pubchem
+      supports "name", "cas", "pubchem-cid", "inchikey", "inchi", "smiles", "canonical-smiles"
+
+      BASE = "https://pubchem.ncbi.nlm.nih.gov/rest/pug/compound"
+      PROPERTIES = %w[CanonicalSMILES IsomericSMILES MolecularFormula
+                      MolecularWeight IUPACName InChI InChIKey].freeze
+      private_constant :BASE, :PROPERTIES
+
+      def fetch_record(value:, convention:, fetch:)
+        body = fetch.get(url_for(value, convention))
+        return nil unless body
+
+        props = JSON.parse(body).dig("PropertyTable", "Properties", 0)
+        return nil unless props
+
+        substance_from(props)
+      rescue JSON::ParserError => e
+        raise Error, "pubchem returned malformed JSON: #{e.message}"
+      end
+
+      def attribution
+        "PubChem, U.S. National Library of Medicine"
+      end
+
+      private
+
+      # CAS numbers are indexed as PubChem names (Common Chemistry
+      # mirror), so both map to the name namespace.
+      def url_for(value, convention)
+        namespace = { "name" => "name", "cas" => "name", "pubchem-cid" => "cid",
+                      "inchikey" => "inchikey", "inchi" => "inchi",
+                      "smiles" => "smiles", "canonical-smiles" => "smiles" }.fetch(convention.to_s)
+        "#{BASE}/#{namespace}/#{CGI.escape(value.to_s)}/property/#{PROPERTIES.join(',')}/JSON"
+      end
+
+      def substance_from(props)
+        provenance = default_provenance
+        identifiers = []
+        identifiers << Identifier.new(value: props["CID"].to_s, convention: "pubchem-cid", provenance: provenance) if props["CID"]
+        add_identifier(identifiers, props, "InChIKey", "inchikey", provenance)
+        add_identifier(identifiers, props, "InChI", "inchi", provenance)
+        add_identifier(identifiers, props, "CanonicalSMILES", "canonical-smiles", provenance)
+
+        Substance.new(
+          preferred_name: props["IUPACName"],
+          formula: props["MolecularFormula"],
+          molecular_weight: props["MolecularWeight"]&.to_f,
+          identifiers: identifiers,
+          properties: [
+            Property.new(name: "molecular-formula", value: props["MolecularFormula"], provenance: provenance),
+            Property.new(name: "molecular-weight", value: props["MolecularWeight"],
+                         units: "g/mol", provenance: provenance)
+          ].compact,
+          # Best effort: PubChem canonical SMILES may use constructs
+          # outside the supported subset (stereo); then the SMILES
+          # stays as an identifier and structure is nil — no silent loss.
+          structure: parse_structure(props["CanonicalSMILES"])
+        )
+      end
+
+      def add_identifier(list, props, key, convention, provenance)
+        return unless props[key]
+
+        list << Identifier.new(value: props[key], convention: convention, provenance: provenance)
+      end
+
+      def parse_structure(smiles)
+        return nil unless smiles
+
+        AsciiChem.parse_smiles(smiles).nodes.first
+      rescue AsciiChem::ParseError
+        nil
+      end
+    end
+  end
+end

data/lib/asciichem/resolver/substance.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module AsciiChem
+  module Resolver
+    # Domain value objects for resolution results. These are data
+    # carriers; (de)serialization to the canonical wire form goes
+    # through the lutaml-model Wire classes only.
+    Provenance = Struct.new(:source, :retrieved_at, :source_version, :attribution, keyword_init: true)
+    Identifier = Struct.new(:value, :convention, :provenance, keyword_init: true)
+    Property = Struct.new(:name, :value, :units, :provenance, keyword_init: true)
+
+    # A resolved substance: identity + provenance + best-effort
+    # structure. `structure` is a Model::Molecule when the source's
+    # SMILES parses within the supported subset; otherwise nil and the
+    # SMILES stays available as an identifier — nothing is dropped.
+    class Substance
+      attr_reader :preferred_name, :synonyms, :formula, :molecular_weight,
+                  :identifiers, :properties, :structure
+
+      def initialize(preferred_name: nil, synonyms: [], formula: nil,
+                     molecular_weight: nil, identifiers: [], properties: [],
+                     structure: nil)
+        @preferred_name = preferred_name
+        @synonyms = synonyms
+        @formula = formula
+        @molecular_weight = molecular_weight
+        @identifiers = identifiers
+        @properties = properties
+        @structure = structure
+      end
+
+      def identifier_value(convention)
+        identifiers.find { |i| i.convention == convention }&.value
+      end
+
+      def provenance
+        identifiers.first&.provenance
+      end
+
+      # Canonical wire form (asciichem-model v1 substance-record).
+      def to_model_json
+        Wire::SubstanceRecord.new(
+          type: "substance-record",
+          preferred_name: preferred_name,
+          synonyms: synonyms,
+          formula: formula,
+          molecular_weight: molecular_weight,
+          identifiers: identifiers.map do |i|
+            Wire::ProvenancedIdentifier.new(
+              identifier: Wire::Identifier.new(type: "identifier", value: i.value, convention: i.convention),
+              provenance: provenance_wire(i.provenance)
+            )
+          end,
+          properties: properties.map do |p|
+            Wire::ProvenancedProperty.new(
+              name: p.name, value: p.value, units: p.units,
+              provenance: provenance_wire(p.provenance)
+            )
+          end
+        ).to_json
+      end
+
+      # Rebuilds a Substance from the wire form (the cache path).
+      def self.from_model_json(json)
+        wire = Wire::SubstanceRecord.from_json(json)
+        new(
+          preferred_name: wire.preferred_name,
+          synonyms: Array(wire.synonyms),
+          formula: wire.formula,
+          molecular_weight: wire.molecular_weight,
+          identifiers: Array(wire.identifiers).map do |pi|
+            Identifier.new(
+              value: pi.identifier&.value,
+              convention: pi.identifier&.convention,
+              provenance: provenance_domain(pi.provenance)
+            )
+          end,
+          properties: Array(wire.properties).map do |p|
+            Property.new(name: p.name, value: p.value, units: p.units,
+                         provenance: provenance_domain(p.provenance))
+          end
+        )
+      end
+
+      def self.provenance_domain(wire)
+        return nil unless wire
+
+        Provenance.new(source: wire.source, retrieved_at: wire.retrieved_at,
+                       source_version: wire.source_version, attribution: wire.attribution)
+      end
+
+      private
+
+      def provenance_wire(p)
+        return nil unless p
+
+        Wire::Provenance.new(
+          type: "provenance",
+          source: p.source, retrieved_at: p.retrieved_at,
+          source_version: p.source_version, attribution: p.attribution
+        )
+      end
+    end
+  end
+end

data/lib/asciichem/resolver.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require "asciichem/errors"
+
+module AsciiChem
+  # Resolution turns identifiers into substance records (TODO.v2 07
+  # Layer 2; TODO.impl 38). Multi-source by design: every answering
+  # source produces its own record with provenance, because the
+  # citation track (TODO.v2 08) emits one bibitem per (substance,
+  # source) the user chooses to cite.
+  #
+  # Sources are opt-in adapters that self-register (OCP, same pattern
+  # as the linter checks). NC-licensed sources are never registered by
+  # default — Common Chemistry ships only after the maintainer
+  # sign-off recorded in TODO.v2 07.
+  module Resolver
+    autoload :Adapter, "asciichem/resolver/adapter"
+    autoload :Cache, "asciichem/resolver/cache"
+    autoload :PubChem, "asciichem/resolver/pubchem"
+    autoload :CommonChemistry, "asciichem/resolver/common_chemistry"
+    autoload :Substance, "asciichem/resolver/substance"
+
+    # Raised when sources disagree on substance identity (cross-check
+    # mode). The message lists the disagreement — never hidden.
+    class Conflict < AsciiChem::Error; end
+
+    class << self
+      def adapters
+        @adapters ||= {}
+      end
+
+      def register(name, adapter)
+        adapters[name.to_s] = adapter
+      end
+
+      def [](name)
+        adapters.fetch(name.to_s)
+      rescue KeyError
+        raise Error, "unknown resolver source #{name.inspect} (registered: #{adapters.keys.sort.join(', ')})"
+      end
+
+      # Resolves against every opt-in source, returning one Substance
+      # per source that answers (nil entries dropped). Sources answer
+      # in registration order.
+      def resolve_all(value:, convention:, sources: nil, fetch: nil, cache: nil, refresh: false)
+        selected = sources ? Array(sources).map { |s| self[s] } : adapters.values
+        selected.filter_map do |adapter_class|
+          adapter = adapter_class.new
+          next unless adapter.supports?(convention)
+
+          adapter.resolve(value: value, convention: convention, fetch: fetch, cache: cache, refresh: refresh)
+        end
+      end
+
+      # First answering source wins.
+      def resolve(**args)
+        resolve_all(**args).first
+      end
+
+      # Cross-check mode: all sources must agree on the primary key
+      # (InChIKey) when more than one source provides one.
+      def resolve!(**args)
+        substances = resolve_all(**args)
+        keys = substances.filter_map { |s| s.identifier_value("inchikey") }.uniq
+        if keys.length > 1
+          raise Conflict,
+                "sources disagree on substance identity (InChIKeys: #{keys.join(' vs ')})"
+        end
+        substances.first
+      end
+    end
+
+    # Open, permissive sources register eagerly. CommonChemistry is
+    # CC BY-NC 4.0: it loads (autoload) but never self-registers —
+    # users opt in explicitly via Resolver.register.
+    adapters
+    constants.each { |c| const_get(c) unless c == :Conflict }
+  end
+end

data/lib/asciichem/version.rb

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

data/lib/asciichem.rb

@@ -10,6 +10,7 @@ require "plurimath"
 #   AsciiChem::Cli.start    # CLI dispatch
 module AsciiChem
   autoload :Cli, "asciichem/cli"
+  autoload :Citation, "asciichem/citation"
   autoload :Cml, "asciichem/cml"
   autoload :Error, "asciichem/errors"
   autoload :ParseError, "asciichem/errors"
@@ -25,6 +26,7 @@ module AsciiChem
   autoload :Molfile, "asciichem/molfile"
   autoload :Parser, "asciichem/parser"
   autoload :PeriodicTable, "asciichem/periodic_table"
+  autoload :Resolver, "asciichem/resolver"
   autoload :RingBonds, "asciichem/ring_bonds"
   autoload :Smiles, "asciichem/smiles"
   autoload :Structure, "asciichem/structure"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: asciichem
 version: !ruby/object:Gem::Version
-  version: 0.22.0
+  version: 0.24.0
 platform: ruby
 authors:
 - Ribose Inc.
@@ -85,6 +85,26 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: relaton-bib
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
 - !ruby/object:Gem::Dependency
   name: plurimath
   requirement: !ruby/object:Gem::Requirement
@@ -156,6 +176,7 @@ files:
 - benchmarks/benchmark.rb
 - exe/asciichem
 - lib/asciichem.rb
+- lib/asciichem/citation.rb
 - lib/asciichem/cli.rb
 - lib/asciichem/cml.rb
 - lib/asciichem/cml/conditions_extensions.rb
@@ -228,6 +249,12 @@ files:
 - lib/asciichem/molfile/writer.rb
 - lib/asciichem/parser.rb
 - lib/asciichem/periodic_table.rb
+- lib/asciichem/resolver.rb
+- lib/asciichem/resolver/adapter.rb
+- lib/asciichem/resolver/cache.rb
+- lib/asciichem/resolver/common_chemistry.rb
+- lib/asciichem/resolver/pubchem.rb
+- lib/asciichem/resolver/substance.rb
 - lib/asciichem/ring_bonds.rb
 - lib/asciichem/smiles.rb
 - lib/asciichem/smiles/parser.rb