asciichem-model 0.3.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: bba211156f3a53f7dd9988918fd567d7e0d396f16bf9a22f92016c5fd27eda5a
+  data.tar.gz: e6c09514b77410c3e55a17dad56b50fa3fb1be870c3172dc9250224c171224b3
+SHA512:
+  metadata.gz: 9749212ecff6cac96f1a307446ee485ad456dcc022546cac3a4f00cc04374c93ab3693607b6d5a77e665323d9deb8fa160e7239d04e457f1b68461b816693f83
+  data.tar.gz: 848fffe56cb6d8a494431899b4d43a5bd200fd68d54bb61df2fbd7147d62bacdeb5b4f592f9fe0b4fb10d4bb1ee038ef85e5eeb2d507f9cc529504acf2df672e

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AsciiChem contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.adoc

@@ -0,0 +1,80 @@
+= AsciiChem Semantic Model
+
+== General
+
+This repository defines the **normative semantic model** for the
+AsciiChem ecosystem: what a parsed chemical *means*, independent of any
+implementation language. Every implementation —
+https://github.com/asciichem/asciichem-ruby[asciichem-ruby] (reference),
+the planned TypeScript and Python APIs, any future Rust core — consumes
+these definitions and conforms to the shared corpus in
+`asciichem-tests`.
+
+The architecture follows the proven
+https://github.com/glossarist/concept-model[glossarist concept-model]
+pattern: LutaML model definitions as the normative source, versioned
+JSON Schemas as the machine-checkable form, numbered examples (positive
+and negative) that seed the conformance corpus, and generated types for
+downstream languages.
+
+The canonical serialisation is a JSON wire form with a node `type`
+discriminator; every implementation must parse and emit it. Identifier
+conventions (CAS RN, InChI, InChIKey, SMILES, …) carry format
+constraints and provenance so that substance identity — validate,
+resolve, cite — is first-class.
+
+== Layout
+
+[cols="1,3"]
+|===
+|Path |Contents
+
+|`models/asciichem/*.lutaml` |Normative LutaML class/data-type definitions
+|`schemas/v1/*.yaml` |JSON Schema (draft 2020-12) in YAML, one per node type, repo-pinned `$id`
+|`schemas/v1/examples/` |Numbered instance examples (positive now; negative-examples validator lands with the generator work)
+|`lib/` |Gem packaging: schema self-checks and the schema→TypeScript type generator
+|`docs/adr/` |Architecture decision records
+|===
+
+== Status
+
+Scaffold (2026-09-09): seed schemas for `atom`, `molecule`,
+`identifier`. The full node inventory (`formula`, `group`, `bond`,
+`reaction`, … plus the identity model `provenance`/`substance-record`)
+is tracked in the ecosystem backlog
+(`asciichem.github.io/TODO.impl/30`, `31`, `32`).
+
+== Versioning and releases
+
+This repo follows semantic versioning. Consumers (asciichem-ruby,
+asciichem-ts, asciichem-py) vendor or depend on the artifacts and pin
+to tags.
+
+[cols="1,3",options="header"]
+|===
+|Bump |When
+
+|MAJOR (vN+1.0.0)
+|Removed or renamed shape, class, property, prefix binding, or enum value
+
+|MINOR (vN.N+1.0)
+|New shapes, classes, properties, enum values; backward-compatible additive
+
+|PATCH (vN.N.N+1)
+|Shape bug fixes, doc/comment-only changes, example updates
+|===
+
+The model version appears in the wire form root
+(`"modelVersion": "1.x"`). Breaking model changes are gated here, not
+in each implementation.
+
+== Consumer protocol
+
+- **Ruby** (asciichem-ruby): depends on the `asciichem-model` gem;
+  model classes serialise via `lutaml-model` mappings against the
+  schemas — never hand-rolled `to_h`.
+- **TypeScript/JS** (asciichem-ts): vendors `schemas/` via a
+  `sync-asciichem-model` script pinned to a git tag; types are
+  generated from the schemas (single source of truth → typed output).
+- **Python** (asciichem-py): consumes the schemas directly or via
+  generated dataclasses.

data/docs/adr/0001-language-bindings.adoc

@@ -0,0 +1,78 @@
+= ADR-0001: Language-binding strategy
+
+Date: 2026-09-09
+Status: Accepted
+
+== Context
+
+AsciiChem needs TypeScript and Python APIs in addition to the Ruby
+reference implementation. Wrapping the Ruby gem (shelling out,
+transpiling) is a non-option: the gem is the reference implementation,
+not a runtime dependency for other ecosystems. Two viable shapes:
+
+*A — Per-language implementations against the shared model + corpus*
+(the CommonMark pattern):: Each language implements the parser, model,
+and formatters natively, conforming to `asciichem-model` schemas and
+passing the `asciichem-tests` corpus.
+
+*B — One Rust core, generated/FFI bindings per language* (the tiktoken
+/ fastembed pattern):: Parser + model + formatters live in Rust; Ruby
+uses rb-sys/magnus, Python PyO3/maturin, TypeScript napi-rs, the
+browser wasm-bindgen.
+
+== Analysis
+
+[cols="1,2,2",options="header"]
+|===
+|Dimension |A — per-language |B — Rust core
+
+|Parity risk
+|Real; mitigated by the corpus, needs discipline
+|Minimal — one implementation
+
+|Effort
+|~2× parser work (TS, PY); Ruby untouched
+|1× Rust rewrite + 3 bindings + native CI matrix; would eventually replace the parslet *reference* parser
+
+|Ruby story
+|None required
+|Large, risky migration of the reference implementation
+
+|Deployment
+|Pure-language packages
+|Native artifacts per platform/arch; compiled gem extension
+
+|Performance
+|Fine at document scale (parslet is not fast and it does not matter)
+|Better, but performance is not a requirement
+
+|Browser
+|TS API suffices for text/MathML
+|WASM enables client-side structural SVG later
+|===
+
+== Decision
+
+**A now; B deferred with explicit triggers.** Ship TypeScript and
+Python as native implementations conforming to the shared model and
+corpus. The single-parser invariant ("the site never reimplements the
+parser") evolves into a *single-contract* rule: every implementation
+passes the same corpus, verified in CI via each implementation's
+`conformance.json` (implementation, version, corpus version, per-level
+pass/total).
+
+Revisit (and only then activate the parked `11-rust-core.md` plan)
+when any of:
+
+. Performance becomes a stated requirement.
+. A third or fourth language lands and per-language drift cost exceeds
+  one Rust rewrite plus bindings.
+. Client-side WASM needs exceed what the TS API provides (e.g.
+  structural SVG in the playground).
+
+== Consequences
+
+- `asciichem-model` and `asciichem-tests` are load-bearing: conformance
+  claims are only as strong as the corpus.
+- The TS/PY scaffolds (TODO.impl 46/47) proceed under strategy A.
+- No Rust work starts as a side effect of any other TODO.

data/exe/generate-types-from-schemas

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "asciichem_model"
+
+exit AsciiChemModel::SchemaTypeGenerator.new(check_mode: ARGV.include?("--check")).run

data/lib/asciichem_model/schema_type_generator.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+require "pathname"
+require "yaml"
+
+module AsciiChemModel
+  # Emits TypeScript interfaces from the v1 JSON Schemas — single
+  # source of truth (schemas) → typed output for downstream TS
+  # consumers. Glossarist's concept-model generator is the
+  # architectural reference.
+  #
+  # Supports the schema features this repository uses: type, const,
+  # enum, required, properties, items, anyOf, $ref (sibling files),
+  # and object-valued properties (emitted as inline structural
+  # types). `check_mode` compares against committed output so CI
+  # fails on drift.
+  class SchemaTypeGenerator
+    SCHEMAS_DIR = Pathname.new(File.join(AsciiChemModel.root, "schemas", "v1"))
+    OUTPUT_DIR = SCHEMAS_DIR.join("types")
+
+    # Schema basenames whose model class spelling differs from the
+    # mechanical kebab→Camel conversion.
+    NAME_EXCEPTIONS = { "zmatrix" => "ZMatrix" }.freeze
+
+    class << self
+      def type_name(schema_basename)
+        NAME_EXCEPTIONS.fetch(schema_basename) do
+          schema_basename.split("-").map(&:capitalize).join
+        end
+      end
+    end
+
+    def initialize(check_mode: false)
+      @check_mode = check_mode
+    end
+
+    def run
+      OUTPUT_DIR.mkpath
+      schema_files.each { |path| emit_one(path) }
+      emit_index
+      @check_mode ? fail_if_drift : 0
+    end
+
+    private
+
+    def schema_files
+      Dir[SCHEMAS_DIR.join("*.yaml").to_s].sort
+    end
+
+    def emit_one(path)
+      basename = File.basename(path, ".yaml")
+      schema = YAML.safe_load_file(path)
+      write_output("#{basename}.ts", render_header(basename) + render_schema(schema))
+    end
+
+    def emit_index
+      names = schema_files.map { |p| self.class.type_name(File.basename(p, ".yaml")) }
+      body = +render_comment("Union of every node type in the v1 model.")
+      body << "export type Node =\n"
+      body << names.map { |n| "  | #{n}" }.join("\n")
+      body << ";\n"
+      write_output("index.ts", body)
+    end
+
+    def render_header(basename)
+      render_comment("Generated from schemas/v1/#{basename}.yaml — do not edit; regenerate.")
+    end
+
+    def render_schema(schema)
+      name = self.class.type_name(schema["$id"].split("/").last)
+      out = +"export interface #{name} {\n"
+      required = schema.fetch("required", [])
+      props = schema.fetch("properties", {})
+      out << render_property("type", props.fetch("type"), true, name) if props.key?("type")
+      props.reject { |key, _| key == "type" }.each do |key, prop|
+        out << render_property(ts_key(key), prop, required.include?(key), name)
+      end
+      out << "}\n"
+    end
+
+    def render_property(key, prop, required, scope)
+      optional = required ? "" : "?"
+      "#{indent}readonly #{key}#{optional}: #{ts_type(prop, scope)};\n"
+    end
+
+    def ts_type(prop, scope)
+      return ts_const(prop["const"]) if prop["const"]
+      return ts_enum(prop["enum"]) if prop["enum"]
+      return ts_ref(prop["$ref"], scope) if prop["$ref"]
+      return ts_array(prop, scope) if prop["type"] == "array"
+      return ts_inline_object(prop, scope) if prop["type"] == "object"
+
+      case prop["type"]
+      when "number" then "number"
+      when "integer" then "number"
+      else "string"
+      end
+    end
+
+    def ts_const(value)
+      value.is_a?(String) ? %("#{value}") : value.to_s
+    end
+
+    def ts_enum(values)
+      values.map { |v| ts_const(v) }.join(" | ")
+    end
+
+    def ts_ref(ref, _scope)
+      self.class.type_name(File.basename(ref.to_s, ".yaml"))
+    end
+
+    def ts_array(prop, scope)
+      items = prop["items"]
+      inner = if items.key?("anyOf")
+                "(#{items["anyOf"].map { |sub| ts_type(sub, scope) }.uniq.join(" | ")})"
+              else
+                ts_type(items, scope)
+              end
+      "#{inner}[]"
+    end
+
+    def ts_inline_object(prop, scope)
+      required = prop.fetch("required", [])
+      members = prop.fetch("properties", {}).map do |key, sub|
+        optional = required.include?(key) ? "" : "?"
+        "#{indent}#{ts_key(key)}#{optional}: #{ts_type(sub, scope)};"
+      end
+      "{\n#{members.map { |m| "  #{m}" }.join("\n")}\n#{indent}}"
+    end
+
+    def ts_key(key)
+      return %("#{key}") unless key.match?(/\A[A-Za-z_$][A-Za-z0-9_$]*\z/)
+
+      key
+    end
+
+    def indent
+      "  "
+    end
+
+    def render_comment(text)
+      "// #{text}\n"
+    end
+
+    def write_output(filename, content)
+      path = OUTPUT_DIR.join(filename)
+      @written ||= {}
+      @written[filename] = content
+      File.write(path, content) unless @check_mode
+    end
+
+    def fail_if_drift
+      drifted = @written.select do |filename, content|
+        path = OUTPUT_DIR.join(filename)
+        !File.exist?(path) || File.read(path) != content
+      end
+      return 0 if drifted.empty?
+
+      warn "Generated types drifted from schemas/v1/types (run `rake generate:types`): #{drifted.keys.join(', ')}"
+      1
+    end
+  end
+end

data/lib/asciichem_model/validators.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require "json_schemer"
+require "yaml"
+
+module AsciiChemModel
+  # Schema self-checks for the model repository: every schema is
+  # loadable and structurally coherent, positive examples validate
+  # against their node's schema, and negative examples (99-*) are
+  # rejected. The same machinery serves downstream consumers that
+  # want to validate canonical-JSON payloads against the shipped
+  # schemas.
+  module Validators
+    SCHEMAS_DIR = File.join(AsciiChemModel.root, "schemas", "v1")
+    NEGATIVE_MARKER = "99-".freeze
+    private_constant :NEGATIVE_MARKER
+
+    class << self
+      # A hash of schema name (file basename) => JSONSchemer schema,
+      # with sibling-file $refs resolvable.
+      def schemers
+        @schemers ||= schema_files.to_h do |path|
+          [File.basename(path, ".yaml"), schemer_for(path)]
+        end
+      end
+
+      def schema_names
+        schemers.keys.sort
+      end
+
+      def schema_file(name)
+        File.join(SCHEMAS_DIR, "#{name}.yaml")
+      end
+
+      # Validates a wire-form node hash against its node schema
+      # (chosen by the `type` discriminator). Returns an Array of
+      # error strings (empty when valid); raises KeyError for an
+      # unknown schema name.
+      def validate(node)
+        schema_name = node.fetch("type").tr("_", "-")
+        schemer = schemers.fetch(schema_name) do
+          raise KeyError, "no schema for node type #{schema_name.inspect}"
+        end
+        schemer.validate(node).map(&:to_s)
+      end
+
+      def example_files
+        Dir[File.join(SCHEMAS_DIR, "examples", "*.yaml")].sort
+      end
+
+      def positive_examples
+        example_files.reject { |p| File.basename(p).start_with?(NEGATIVE_MARKER) }
+      end
+
+      def negative_examples
+        example_files.select { |p| File.basename(p).start_with?(NEGATIVE_MARKER) }
+      end
+
+      private
+
+      def schema_files
+        Dir[File.join(SCHEMAS_DIR, "*.yaml")].sort
+      end
+
+      def schemer_for(path)
+        JSONSchemer.schema(YAML.safe_load_file(path), ref_resolver: method(:resolve_ref))
+      end
+
+      # Sibling-file $refs ("atom.yaml") resolve against the schemas
+      # directory; external pointers are not supported by design.
+      def resolve_ref(uri)
+        candidate = File.join(SCHEMAS_DIR, File.basename(uri.to_s))
+        return YAML.safe_load_file(candidate) if File.exist?(candidate)
+
+        raise KeyError, "unresolvable $ref #{uri} (only sibling schema files are supported)"
+      end
+    end
+  end
+end

data/lib/asciichem_model/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module AsciiChemModel
+  VERSION = "0.3.2"
+end

data/lib/asciichem_model.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+# AsciiChemModel packages the normative semantic model artifacts
+# (LutaML definitions, JSON Schemas, examples) for the AsciiChem
+# ecosystem. The gem's lib currently carries only the version and
+# schema tooling entry points; the schema self-check suite and the
+# schema→TypeScript type generator land with the backlog items
+# tracked in the ecosystem TODO.impl (32).
+module AsciiChemModel
+  autoload :VERSION, "asciichem_model/version"
+  autoload :SchemaTypeGenerator, "asciichem_model/schema_type_generator"
+  autoload :Validators, "asciichem_model/validators"
+
+  # Root path of the gem (schemas/, models/, examples/ live here).
+  def self.root
+    File.expand_path("..", __dir__)
+  end
+end

data/models/asciichem/Atom.lutaml

@@ -0,0 +1,49 @@
+class Atom {
+  definition {
+    A chemical atom: an element symbol with optional isotope (prefix
+    superscript), optional charge, optional subscript multiplicity,
+    and optional annotations. The defining semantic fix over AsciiMath:
+    a prefix superscript binds to the atom (`^14C` is
+    Atom(element: "C", isotope: "14")), never to a phantom carrier.
+  }
+  +element: String {
+    definition {
+      Element symbol from the periodic table (e.g. "C", "Cl").
+    }
+  }
+  +isotope: String {
+    definition {
+      Isotope mass number bound to this atom (e.g. "14" in `^14C`).
+    }
+  }
+  +charge: String {
+    definition {
+      Charge annotation (e.g. "2+" in `Ca^2+`).
+    }
+  }
+  +subscript: String {
+    definition {
+      Subscript multiplicity (e.g. "2" in `H_2O`).
+    }
+  }
+  +oxidationState: String {
+    definition {
+      Oxidation state annotation ("II" in Ca^(II)).
+    }
+  }
+  +lonePairs: Integer {
+    definition {
+      Lewis lone-pair markers ("::O" carries 2).
+    }
+  }
+  +radicalElectrons: Integer {
+    definition {
+      Radical-electron markers ("N." carries 1).
+    }
+  }
+  +ringClosures: String {
+    definition {
+      SMILES-style ring closure digits ("1" in C1...C1).
+    }
+  }
+}

data/models/asciichem/Bond.lutaml

@@ -0,0 +1,24 @@
+class Bond {
+  definition {
+    A bond between adjacent atoms in a linear structure. The kind
+    enum is the single source of truth shared by all implementations.
+  }
+  +kind: BondKind {
+    definition { The bond kind; single by default. }
+  }
+}
+
+enum BondKind {
+  definition {
+    single (-), double (=), triple (#), quadruple (##), wedge (>-),
+    hash (-<), dative (~>), wavy (~~).
+  }
+  single {}
+  double {}
+  triple {}
+  quadruple {}
+  wedge {}
+  hash {}
+  dative {}
+  wavy {}
+}

data/models/asciichem/Calculation.lutaml

@@ -0,0 +1,34 @@
+class Calculation {
+  definition {
+    A computational-chemistry result: method, basis set, and
+    computed properties.
+  }
+  +method: String {
+    definition { The computational method, e.g. "B3LYP". }
+  }
+  +basis: String {
+    definition { The basis set, e.g. "6-31G(d)". }
+  }
+  +properties: CalculatedProperty[0..*] {
+    definition { The computed properties. }
+  }
+
+  class CalculatedProperty {
+    definition { One computed property with units and provenance keys. }
+    +title: String {
+      definition { Property name, e.g. "dipole". }
+    }
+    +value: String {
+      definition { The computed value. }
+    }
+    +units: String {
+      definition { Units of the value. }
+    }
+    +dictRef: String {
+      definition { Optional dictionary reference. }
+    }
+    +convention: String {
+      definition { Optional convention marker. }
+    }
+  }
+}

data/models/asciichem/Crystal.lutaml

@@ -0,0 +1,34 @@
+class Crystal {
+  definition {
+    A crystallographic cell: unit-cell constants, space group, and
+    the asymmetric-unit atoms (fractional coordinates ride on the
+    atoms' coordinate annotations).
+  }
+  +name: String {
+    definition { Mineral or compound name. }
+  }
+  +a: Real {
+    definition { Cell length a in Angstrom. }
+  }
+  +b: Real {
+    definition { Cell length b. }
+  }
+  +c: Real {
+    definition { Cell length c. }
+  }
+  +alpha: Real {
+    definition { Cell angle alpha in degrees. }
+  }
+  +beta: Real {
+    definition { Cell angle beta. }
+  }
+  +gamma: Real {
+    definition { Cell angle gamma. }
+  }
+  +spacegroup: String {
+    definition { Hermann-Mauguin symbol, e.g. "Fm-3m". }
+  }
+  +atoms: Atom[0..*] {
+    definition { Asymmetric-unit atoms. }
+  }
+}

data/models/asciichem/ElectronConfiguration.lutaml

@@ -0,0 +1,35 @@
+class ElectronConfiguration {
+  definition {
+    Orbital occupancy (1s^2 2s^2 2p^6) with an optional atomic term
+    symbol (^{multiplicity}L_J).
+  }
+  +orbitals: OrbitalOccupancy[0..*] {
+    definition { Ordered orbital occupancies. }
+  }
+  +termSymbol: TermSymbol {
+    definition { Optional atomic term symbol. }
+  }
+
+  class OrbitalOccupancy {
+    definition { One orbital and its electron count. }
+    +orbital: String {
+      definition { Orbital label, e.g. "1s", "2p". }
+    }
+    +occupancy: String {
+      definition { Electron count in this orbital. }
+    }
+  }
+
+  class TermSymbol {
+    definition { Atomic term symbol: spin multiplicity, letter, J. }
+    +multiplicity: String {
+      definition { Spin multiplicity (2S+1). }
+    }
+    +letter: String {
+      definition { Orbital angular momentum letter (S, P, D, ...). }
+    }
+    +jValue: String {
+      definition { Total angular momentum J. }
+    }
+  }
+}

data/models/asciichem/EmbeddedMath.lutaml

@@ -0,0 +1,10 @@
+class EmbeddedMath {
+  definition {
+    Math embedded in chemistry (backtick syntax). The wire form
+    carries the AsciiMath source; the parsed formula is an
+    implementation detail.
+  }
+  +source: String {
+    definition { The backticked AsciiMath source text. }
+  }
+}

data/models/asciichem/Formula.lutaml

@@ -0,0 +1,13 @@
+class Formula {
+  definition {
+    The document root of a parsed AsciiChem input: an ordered
+    sequence of top-level nodes. Every implementation emits this as
+    the canonical wire form's root.
+  }
+  +nodes: Node[0..*] {
+    definition {
+      Top-level nodes: molecules, reactions, cascades, groups,
+      electron configurations, embedded math, or text.
+    }
+  }
+}