refactor: tighten architecture around contributed Opal payload work

.gitignore

@@ -9,5 +9,14 @@
 
 # rspec failure tracking
 .rspec_status
+
+# Local planning / scratch files — never ship in the gem
+TODO*
+NOTES*
+
+# Editor / OS noise
+.DS_Store
+/.ruby-lsp/
+
 Gemfile.lock
 /vendor/bundle/

.rubocop_todo.yml

@@ -1,31 +1,84 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2026-04-15 09:29:09 UTC using RuboCop version 1.86.1.
+# on 2026-06-29 02:49:40 UTC using RuboCop version 1.88.0.
 # The point is for the user to remove these configuration records
 # one by one as the offenses are removed from the code base.
 # Note that changes in the inspected code, or installation of new
 # versions of RuboCop, may require this file to be generated again.
 
+# Offense count: 2
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: TreatCommentsAsGroupSeparators, ConsiderPunctuation.
+Gemspec/OrderedDependencies:
+  Exclude:
+    - 'unitsml.gemspec'
+
 # Offense count: 1
 Gemspec/RequiredRubyVersion:
   Exclude:
     - 'unitsml.gemspec'
 
-# Offense count: 1
+# Offense count: 3
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: EnforcedStyle, IndentationWidth.
 # SupportedStyles: with_first_argument, with_fixed_indentation
 Layout/ArgumentAlignment:
   Exclude:
-    - 'lib/unitsml/unit.rb'
+    - 'lib/unitsml/formula.rb'
+    - 'lib/unitsml/utility.rb'
+
+# Offense count: 2
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyleAlignWith.
+# SupportedStylesAlignWith: either, start_of_block, start_of_line
+Layout/BlockAlignment:
+  Exclude:
+    - 'lib/unitsml/utility.rb'
 
-# Offense count: 76
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+Layout/BlockEndNewline:
+  Exclude:
+    - 'lib/unitsml/utility.rb'
+
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+Layout/ElseAlignment:
+  Exclude:
+    - 'lib/unitsml/utility.rb'
+
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyleAlignWith.
+# SupportedStylesAlignWith: keyword, variable, start_of_line
+Layout/EndAlignment:
+  Exclude:
+    - 'lib/unitsml/utility.rb'
+
+# Offense count: 2
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: AllowMultipleStyles, EnforcedHashRocketStyle, EnforcedColonStyle, EnforcedLastArgumentHashStyle.
+# SupportedHashRocketStyles: key, separator, table
+# SupportedColonStyles: key, separator, table
+# SupportedLastArgumentHashStyles: always_inspect, always_ignore, ignore_implicit, ignore_explicit
+Layout/HashAlignment:
+  Exclude:
+    - 'lib/unitsml/utility.rb'
+
+# Offense count: 4
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: Width, EnforcedStyleAlignWith, AllowedPatterns.
+# SupportedStylesAlignWith: start_of_line, relative_to_receiver
+Layout/IndentationWidth:
+  Exclude:
+    - 'lib/unitsml/utility.rb'
+
+# Offense count: 78
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: Max, AllowHeredoc, AllowURI, AllowQualifiedName, URISchemes, AllowRBSInlineAnnotation, AllowCopDirectives, AllowedPatterns, SplitStrings.
 # URISchemes: http, https
 Layout/LineLength:
   Exclude:
-    - 'lib/unitsml/fenced.rb'
     - 'lib/unitsml/formula.rb'
     - 'lib/unitsml/intermediate_exp_rules.rb'
     - 'lib/unitsml/parse.rb'
@@ -41,20 +94,15 @@ Layout/LineLength:
     - 'spec/unitsml/conv/xml_spec.rb'
     - 'unitsml.gemspec'
 
-# Offense count: 1
+# Offense count: 2
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: AllowInHeredoc.
 Layout/TrailingWhitespace:
   Exclude:
-    - 'lib/unitsml/unit.rb'
-
-# Offense count: 3
-Lint/ReturnInVoidContext:
-  Exclude:
-    - 'lib/unitsml/unitsdb/si_derived_base.rb'
-    - 'lib/unitsml/unitsdb/unit.rb'
+    - 'lib/unitsml/formula.rb'
+    - 'lib/unitsml/utility.rb'
 
-# Offense count: 19
+# Offense count: 17
 # Configuration parameters: AllowedMethods, AllowedPatterns, CountRepeatedAttributes, Max.
 Metrics/AbcSize:
   Exclude:
@@ -74,7 +122,7 @@ Metrics/CyclomaticComplexity:
     - 'lib/unitsml/parser.rb'
     - 'lib/unitsml/utility.rb'
 
-# Offense count: 14
+# Offense count: 18
 # Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
 Metrics/MethodLength:
   Max: 20
@@ -84,11 +132,10 @@ Metrics/MethodLength:
 Metrics/ParameterLists:
   Max: 6
 
-# Offense count: 9
+# Offense count: 8
 # Configuration parameters: AllowedMethods, AllowedPatterns, Max.
 Metrics/PerceivedComplexity:
   Exclude:
-    - 'lib/unitsml/formula.rb'
     - 'lib/unitsml/parse.rb'
     - 'lib/unitsml/parser.rb'
     - 'lib/unitsml/utility.rb'
@@ -132,12 +179,12 @@ RSpec/ContextWording:
     - 'spec/unitsml/parse_spec.rb'
     - 'spec/unitsml/parser_spec.rb'
 
-# Offense count: 5
+# Offense count: 15
 # Configuration parameters: CountAsOne.
 RSpec/ExampleLength:
   Max: 7
 
-# Offense count: 15
+# Offense count: 36
 RSpec/MultipleExpectations:
   Max: 6
 
@@ -170,9 +217,20 @@ RSpec/SpecFilePathFormat:
 
 # Offense count: 1
 # This cop supports safe autocorrection (--autocorrect).
-Style/MultilineIfModifier:
+# Configuration parameters: EnforcedStyle, ProceduralMethods, FunctionalMethods, AllowedMethods, AllowedPatterns, AllowBracesOnProceduralOneLiners, BracesRequiredMethods.
+# SupportedStyles: line_count_based, semantic, braces_for_chaining, always_braces
+# ProceduralMethods: benchmark, bm, bmbm, create, each_with_object, measure, new, realtime, tap, with_object
+# FunctionalMethods: let, let!, subject, watch
+# AllowedMethods: lambda, proc, it
+Style/BlockDelimiters:
   Exclude:
-    - 'lib/unitsml/unit.rb'
+    - 'lib/unitsml/utility.rb'
+
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+Style/MultilineTernaryOperator:
+  Exclude:
+    - 'lib/unitsml/utility.rb'
 
 # Offense count: 2
 # Configuration parameters: AllowedMethods.

Gemfile

@@ -6,12 +6,11 @@ source "https://rubygems.org"
 gemspec
 
 gem "canon"
-gem "lutaml-model", github: "lutaml/lutaml-model", branch: "main"
 gem "nokogiri"
 gem "oga"
 gem "opal", "~> 1.8"
 gem "ox"
-gem "plurimath", github: "plurimath/plurimath", branch: "main"
+gem "plurimath", "~> 0.11.3"
 gem "pry"
 gem "rake"
 gem "rspec"

lib/unitsml.rb

@@ -21,12 +21,14 @@ module Unitsml
   autoload :Parse, "unitsml/parse"
   autoload :Parser, "unitsml/parser"
   autoload :Prefix, "unitsml/prefix"
+  autoload :PrefixAdapter, "unitsml/prefix_adapter"
   autoload :Sqrt, "unitsml/sqrt"
   autoload :Transform, "unitsml/transform"
   autoload :Unit, "unitsml/unit"
   autoload :Unitsdb, "unitsml/unitsdb"
   autoload :Utility, "unitsml/utility"
   autoload :VERSION, "unitsml/version"
+  autoload :Xml, "unitsml/xml"
 
   def parse(string)
     Unitsml::Parser.new(string).parse

lib/unitsml/configuration.rb

@@ -20,6 +20,10 @@ def context(force_populate: false)
     end
 
     def register_model(klass, id:)
+      unless unitsdb_model_subclass?(klass)
+        raise Unitsml::Errors::InvalidModelError, klass
+      end
+
       registered_models[id.to_sym] = klass
     end
 
@@ -30,11 +34,8 @@ def registered_models
     def build_context
       ::Unitsdb::Config.context # ensure unitsdb context exists
 
-      substitutions = registered_models.each_value.filter_map do |klass|
-        parent = klass.superclass
-        next if parent == Object
-
-        { from_type: parent, to_type: klass }
+      substitutions = registered_models.each_value.map do |klass|
+        { from_type: klass.superclass, to_type: klass }
       end
 
       ::Unitsdb::Config.populate_context(
@@ -43,5 +44,14 @@ def build_context
         substitutions: substitutions,
       )
     end
+
+    def unitsdb_model_subclass?(klass)
+      return false unless klass.is_a?(Class)
+
+      parent = klass.superclass
+      return false if parent.nil? || parent == Object
+
+      parent.name&.start_with?("Unitsdb::")
+    end
   end
 end

lib/unitsml/dimension.rb

@@ -22,7 +22,7 @@ def dim_instance
     end
 
     def dim_symbols
-      dim_instance.send(dim_instance.processed_keys.last).symbols.first
+      dim_instance.public_send(dim_instance.processed_keys.last).symbols.first
     end
 
     def to_mathml(options)

lib/unitsml/errors.rb

@@ -3,8 +3,11 @@
 module Unitsml
   module Errors
     autoload :BaseError, "unitsml/errors/base_error"
+    autoload :InvalidModelError, "unitsml/errors/invalid_model_error"
     autoload :OpalPayloadNotBundledError,
              "unitsml/errors/opal_payload_not_bundled_error"
     autoload :PlurimathLoadError, "unitsml/errors/plurimath_load_error"
+    autoload :UnsupportedPayloadTypeError,
+             "unitsml/errors/unsupported_payload_type_error"
   end
 end

lib/unitsml/errors/invalid_model_error.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Unitsml
+  module Errors
+    class InvalidModelError < Unitsml::Errors::BaseError
+      def initialize(klass)
+        class_name = display_name(klass)
+        parent = klass.is_a?(Class) ? klass.superclass : nil
+        super("[unitsml] Error: #{class_name} cannot be registered as a " \
+              "UnitsML model. register_model expects a subclass of " \
+              "::Unitsdb::*, got superclass #{parent}.")
+      end
+
+      private
+
+      def display_name(klass)
+        return klass.inspect unless klass.is_a?(Class)
+        return klass.name unless klass.name.nil?
+
+        klass.inspect
+      end
+    end
+  end
+end

lib/unitsml/errors/unsupported_payload_type_error.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Unitsml
+  module Errors
+    class UnsupportedPayloadTypeError < Unitsml::Errors::BaseError
+      def initialize(actual_class)
+        super("[unitsml] Error: Unsupported Opal payload type " \
+              "#{actual_class}. PayloadGenerator only emits Hash, Array, " \
+              "String, Symbol, Integer, Float, true, false, and nil.")
+      end
+    end
+  end
+end

lib/unitsml/fenced.rb

@@ -92,7 +92,7 @@ def xml_order_element(tag_name)
     end
 
     def fenced_conversion_for(lang:, options:)
-      lang_value = value.send(:"to_#{lang}", options)
+      lang_value = value.public_send(:"to_#{lang}", options)
       return lang_value unless options[:explicit_parenthesis]
 
       "#{open_paren}#{lang_value}#{close_paren}"

lib/unitsml/formula.rb

@@ -81,7 +81,8 @@ def to_plurimath(options = {})
                                      :asciimath)
       end
 
-      Plurimath::Math.parse(compact_mathml_for_plurimath(to_mathml(options)), :mathml)
+      Plurimath::Math.parse(compact_mathml_for_plurimath(to_mathml(options)),
+                            :mathml)
     end
 
     def dimensions_extraction

lib/unitsml/mathml_helper.rb

@@ -36,7 +36,7 @@ def mml_v4_class_for(klass_ref)
     private
 
     def coerce_mml_v4_collection_attributes!(klass, attributes)
-      return unless klass.respond_to?(:attributes)
+      return unless klass.is_a?(Class) && klass <= Lutaml::Model::Serializable
 
       attributes.each do |name, value|
         attribute = klass.attributes[name]

lib/unitsml/opal.rb

@@ -33,8 +33,10 @@
 require "unitsml/version"
 require "unitsml/errors"
 require "unitsml/errors/base_error"
+require "unitsml/errors/invalid_model_error"
 require "unitsml/errors/opal_payload_not_bundled_error"
 require "unitsml/errors/plurimath_load_error"
+require "unitsml/errors/unsupported_payload_type_error"
 
 require "unitsml/opal/database_payload"
 
@@ -44,6 +46,7 @@
 require "unitsml/unitsdb"
 require "unitsml/unitsdb/database"
 require "unitsml/unitsdb/dimension_details"
+require "unitsml/unitsdb/finders"
 require "unitsml/unitsdb/prefix_reference"
 require "unitsml/unitsdb/dimension"
 require "unitsml/unitsdb/dimensions"
@@ -90,7 +93,10 @@
 require "unitsml/parse"
 require "unitsml/parser"
 require "unitsml/prefix"
+require "unitsml/prefix_adapter"
 require "unitsml/sqrt"
 require "unitsml/transform"
 require "unitsml/unit"
 require "unitsml/utility"
+require "unitsml/xml"
+require "unitsml/xml/formatter"