lutaml-model 0.8.94 → 0.8.96

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '082f3275306fcd89a94f69f68b53d38b0c4c644de743dff261b6bc5166b12ec7'
-  data.tar.gz: 968f9d94e179035695be49649bd9c0b0c2e7e83192661ba3f6d95bbd5803a813
+  metadata.gz: 7b4bd8b10dc92c3a53f615bb3e13c907d1cc4976eb547a5a2da41aa2837bef17
+  data.tar.gz: e1e5eacb6d80dc8108d65a5264d5e9d872d4259103672f6a88e0d912b437002f
 SHA512:
-  metadata.gz: 4f06573be9b9da0d12a561522a63d2d14b771a3ff7357fdb92c8d06213fa997efe19470f0d6b6ab39d9c672038715cc6efa1d607cb77dce5487e2134b56335a1
-  data.tar.gz: 275f2d2c74931c84024278dbc5bddcfe18cc267990c0516080605ce1fd2170c5513efcdd141ffbb72b9967cb91fd7ed74b338936a0e1a793aeba2411f8405d09
+  metadata.gz: efa1a2368c6f2f0352dd928eb33c4c45c9580a431ca3847fe709fcb1026f29deaf2f55e7ec52eafaebdac537ef0c5d55588b22d37d6f6bb27d332165ad9a795a
+  data.tar.gz: 5380981def9666c4ec1fa0f4cb7f977dcba141a5278003a96486d814e7c812d2083339baa3d9d8079c3029d7aef0e84226be40eb188315bd5270c974baed1dda

data/.github/workflows/downstream-performance.yml

@@ -116,9 +116,16 @@ jobs:
             File.write("Gemfile", out.join)
           ' /tmp/main-checkout
           bundle install --jobs=4
-          bundle exec ruby ${{ github.workspace }}/bench/bench_${{ matrix.downstream }}.rb || \
-            { echo "::warning::baseline gate failed — re-running once under less contention (#834)"; \
-              sleep 30; bundle exec ruby ${{ github.workspace }}/bench/bench_${{ matrix.downstream }}.rb; }
+          # lutaml-model#834: min-of-N across attempts — contention
+          # inflates single-shot timings, so run three attempts and let
+          # the merge keep the least-interfered measurement per fixture.
+          for i in 1 2 3; do
+            bundle exec ruby ${{ github.workspace }}/bench/bench_${{ matrix.downstream }}.rb || \
+              echo "::warning::baseline attempt $i errored (#834) — continuing with remaining attempts"
+            cp "$BENCH_JSON" "$BENCH_JSON.attempt$i" 2>/dev/null || true
+          done
+          ruby ${{ github.workspace }}/bench/bench_merge_attempts.rb \
+            "$BENCH_JSON" "$BENCH_JSON.attempt1" "$BENCH_JSON.attempt2" "$BENCH_JSON.attempt3"
 
       - name: Run current benchmark (PR branch)
         env:
@@ -146,9 +153,13 @@ jobs:
             File.write("Gemfile", out.join)
           ' ${{ github.workspace }}
           bundle install --jobs=4
-          bundle exec ruby ${{ github.workspace }}/bench/bench_${{ matrix.downstream }}.rb || \
-            { echo "::warning::gate failed — re-running once under less contention (#834)"; \
-              sleep 30; bundle exec ruby ${{ github.workspace }}/bench/bench_${{ matrix.downstream }}.rb; }
+          for i in 1 2 3; do
+            bundle exec ruby ${{ github.workspace }}/bench/bench_${{ matrix.downstream }}.rb || \
+              echo "::warning::current attempt $i errored (#834) — continuing with remaining attempts"
+            cp "$BENCH_JSON" "$BENCH_JSON.attempt$i" 2>/dev/null || true
+          done
+          ruby ${{ github.workspace }}/bench/bench_merge_attempts.rb \
+            "$BENCH_JSON" "$BENCH_JSON.attempt1" "$BENCH_JSON.attempt2" "$BENCH_JSON.attempt3"
 
       - name: Compare baseline vs current
         run: |

data/bench/bench_merge_attempts.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+# lutaml-model#834: merge N benchmark-attempt JSONs into one result set,
+# taking the per-fixture minimum of every metric. Contention inflates
+# timings; the minimum across attempts is the least-interfered
+# measurement, so gates evaluated on merged output misfire only when
+# EVERY attempt was slow.
+#
+# Usage: ruby bench_merge_attempts.rb <merged.json> <attempt1.json> [attempt2.json ...]
+#
+# Attempt files may be missing (crashed attempt): missing files are
+# skipped; if none exist, nothing is written and the caller's compare
+# step fails on the missing merged file.
+if ARGV.length < 3
+  warn "Usage: #{$PROGRAM_NAME} <merged.json> <attempt1.json> [attempt2.json ...]"
+  exit 1
+end
+
+merged_path = ARGV[0]
+attempt_paths = ARGV[1..]
+
+require "json"
+
+best = {}
+attempt_paths.each do |path|
+  next unless File.exist?(path)
+
+  results = JSON.parse(File.read(path))
+  results.each do |label, metrics|
+    cur = best[label]
+    if cur
+      cur["avg_time"] = [cur["avg_time"], metrics["avg_time"]].min
+      cur["min_time"] = [cur["min_time"], metrics["min_time"]].min
+      cur["max_time"] = [cur["max_time"], metrics["max_time"]].min
+      cur["allocations"] = [cur["allocations"], metrics["allocations"]].min
+      cur["ips"] = [cur["ips"], metrics["ips"]].max
+    else
+      best[label] = metrics.dup
+    end
+  end
+end
+
+if best.nil? || best.empty?
+  warn "No attempt JSONs found among: #{attempt_paths.join(', ')}"
+  exit 1
+end
+
+File.write(merged_path, JSON.pretty_generate(best))
+puts "Merged #{attempt_paths.size} attempt file(s) into #{merged_path} (#{best.size} fixtures)"

data/docs/_guides/grammar-backed-formats.adoc

@@ -0,0 +1,69 @@
+= Grammar-backed string formats
+
+A serialization format whose input is a *grammar*, not a data structure:
+identifier strings, query languages, DSLs — text that is parsed, not
+decoded. lutaml-model supports registering these as first-class formats
+through the same `FormatRegistry` extension point as xml/json/yaml; the
+parse side is implemented by a grammar engine (the reference
+implementation is https://github.com/parsanol/parsanol-ruby[Parsanol]'s
+`Parsanol::PARG::Lutaml.register`, which consumes a compiled PARG
+artifact plus its bindings).
+
+== The contract
+
+A grammar-backed format needs three things:
+
+* a *parse* — text → attribute hash (the grammar engine's job)
+* *bindings* — capture names → model attributes (the artifact's
+  bindings section)
+* a *model class* — a regular `Serializable` with attributes; no
+  hand-written `from_h`/`to_h` anywhere
+
+== Reference implementation (Parsanol)
+
+[source,ruby]
+----
+require "parsanol/parg/lutaml"
+
+Parsanol::PARG::Lutaml.register(
+  IsoIdentifier,
+  format_name: :pubid_iso,
+  artifact: "artifacts/iso.json", # compiled grammar + bindings + tests
+  entry: "identifier",
+)
+
+IsoIdentifier.from_pubid_iso("ISO/IEC 12345-1:2020")
+# => #<IsoIdentifier number: "12345-1", year: 2020, ...>
+----
+
+What `register` does:
+
+. loads the checksummed artifact (parse failures raise the engine's
+  error type — register it via `error_types:` so users can rescue it);
+. registers the format through `FormatRegistry.register` with an
+  adapter whose `parse` is artifact-parse-then-bind;
+. defines `from_<format>` on the model class.
+
+The artifact is the parser of record: it carries the grammar, the
+bindings, and the conformance tests (the grammar's own test block is
+baked in and can be re-run by consumers), and its checksum pins the
+pinned version of the language.
+
+== Writing the grammar side
+
+Grammars are authored in PARG (`.parg` — ABNF-flavoured surface, PEG
+semantics, one rule per line) and compiled with the `parsanol` CLI:
+
+----
+parsanol compile grammars/iso.parg --tables tables
+----
+
+The compile-time lint rejects left recursion and shadowed
+alternatives; the embedded test block runs at compile time, so a
+grammar that stops accepting its documented inputs fails the build
+rather than the consumer.
+
+== See also
+
+* parsanol-ruby `docs/pg-language-guide.md` — the PARG language
+* `Parsanol::PARG::Lutaml.register` — the bridge (reference implementation)

data/docs/_guides/index.adoc

@@ -26,6 +26,7 @@ Task-oriented guides for accomplishing specific goals with Lutaml::Model.
 == Advanced mapping
 
 * link:../advanced-mapping[Advanced Attribute Mapping] - Same-name dispatch on attribute values (`when_attribute`), grouped declarations, custom methods, delegation
+* link:../grammar-backed-formats[Grammar-Backed String Formats] - Register a grammar engine as a serialization format (identifier strings, DSLs)
 
 == Performance
 
@@ -47,6 +48,7 @@ See link:../references/rdf-namespaces[RDF Namespaces] for namespace classes,
 * link:../value-transformations[Value Transformations] - Transform values during serialization
 * link:../missing-values-handling[Missing Values Handling] - Handle nil/empty/omitted
 * link:../advanced-mapping[Advanced Mapping] - Custom methods and delegation
+* link:../grammar-backed-formats[Grammar-Backed String Formats] - Grammar engines as serialization formats
 * link:../schema-generation[Schema Generation] - Generate schemas from models
 * link:../creating-xsd[Creating XSD Schemas] - Complete reference for XSD generation from LutaML models
 * link:../schema-import[Schema Import] - Import schemas to create models

data/lib/lutaml/model/serialize/attribute_definition.rb

@@ -8,6 +8,24 @@ module Lutaml
       # Extracted from serialize.rb to improve code organization.
       # Provides methods for defining and validating model attributes.
       module AttributeDefinition
+        # Whether the per-class accessors and the state-defaults seed are
+        # compiled from Ruby source with a String class_eval (the fast
+        # path). Opal has no runtime compiler unless opal-parser is
+        # bundled, so there every such method is defined from a block
+        # with define_method instead.
+        # Core dispatch for the block-form methods, bound per call so an
+        # attribute or method a model defines with one of these names
+        # (send, __send__, instance_variable_get, const_get, ...) is never invoked;
+        # the compiled form reads ivars and calls methods directly.
+        IVAR_GET = ::Kernel.instance_method(:instance_variable_get)
+        IVAR_SET = ::Kernel.instance_method(:instance_variable_set)
+        SEND = ::BasicObject.instance_method(:__send__)
+        CONST_GET = ::Module.instance_method(:const_get)
+
+        def self.source_compilation?
+          !Lutaml::Model.opal?
+        end
+
         # Define attribute methods on the model class
         #
         # @param attr [Attribute] The attribute to define methods for
@@ -44,6 +62,26 @@ module Lutaml
             return
           end
 
+          unless AttributeDefinition.source_compilation?
+            seeds = attrs.map do |name, attr|
+              sentinel = if attr.collection?
+                           Lutaml::Model::Serialize::LAZY_EMPTY_COLLECTION
+                         else
+                           Lutaml::Model::UninitializedClass.instance
+                         end
+              [:"@#{name}", sentinel]
+            end
+            # Raw readers for every attribute the register sees, as the
+            # compiled form below does (#933).
+            attrs.each_key { |name| define_raw_state_reader(name) }
+            define_method(method_name) do
+              # Returns the last seeded value, as the compiled form's final
+              # assignment does.
+              seeds.reduce(nil) { |_, (ivar, sentinel)| IVAR_SET.bind_call(self, ivar, sentinel) }
+            end
+            return
+          end
+
           lines = attrs.map do |name, attr|
             if attr.collection?
               "@#{name} = Lutaml::Model::Serialize::LAZY_EMPTY_COLLECTION"
@@ -63,18 +101,14 @@ module Lutaml
             end
           RUBY
 
-          # lutaml-model#922: raw readers for the deserializer's
-          # unmatched-rule handling. A custom writer that assigns a
-          # *different* attribute mid-parse (relaton's ICS Isoics
-          # fallback; any derived-value pattern) is invisible to the
-          # value_set tracker -- public setters don't mark it -- so the
-          # tracked "still default" state lies. The deserializer needs
-          # the raw stored state to know whether an attribute was
-          # writer-populated: an attribute still holding its
-          # initialized marker (sentinel / lazy collection) is unset;
-          # anything else was written since init and must never be
-          # overwritten by an unmatched rule's default assignment.
-          raw_lines = attrs.map do |name, _attr|
+          # Raw readers compiled alongside the seeding so every
+          # attribute the register can see — including late-merged
+          # imports that bypass define_attribute_methods — carries
+          # one (#933). Idempotent with the declaration-time
+          # definition.
+          raw_lines = attrs.filter_map do |name, _attr|
+            next unless name.to_s.match?(PLAIN_NAME)
+
             <<~RUBY
               def __lutaml_raw_#{name}
                 @#{name}
@@ -86,6 +120,14 @@ module Lutaml
           RUBY
         end
 
+        # Block-form raw-state reader (no String eval), defined on self.
+        def define_raw_state_reader(name)
+          ivar = :"@#{name}"
+          define_method(:"__lutaml_raw_#{name}") do
+            IVAR_GET.bind_call(self, ivar)
+          end
+        end
+
         # Historical getter shape for punctuation-named attributes and
         # any name the compiled form cannot express.
         def define_reflective_attribute_methods(name, attr)
@@ -126,6 +168,9 @@ module Lutaml
                           end
             remove_method(compiled) if defined_now
           end
+          # The names cache must go with the methods: the memoized
+          # lookup answers stale names for removed methods otherwise.
+          @state_defaults_names.clear
         end
 
         def define_attribute_methods(attr, register = nil)
@@ -146,8 +191,17 @@ module Lutaml
           # the state-defaults compilation) so late declarations get it
           # too -- XMI's extension loader declares attributes after
           # first parse.
-          if name.to_s.match?(PLAIN_NAME)
-            model.class_eval(<<~RUBY, __FILE__, __LINE__ + 1) # rubocop:disable Style/DocumentDynamicEvalDefinition
+          # Without a source compiler, compile_state_defaults! defines
+          # its raw readers from blocks; define one for every name here
+          # too (define_method takes any name, not only plain ones).
+          # Both forms define on self: a bare `model` receiver resolves
+          # through the host class's own namespace (omml's Base answers
+          # a Store model) and defined the reader on the wrong object
+          # (#933).
+          if !AttributeDefinition.source_compilation?
+            define_raw_state_reader(name)
+          elsif name.to_s.match?(PLAIN_NAME)
+            class_eval(<<~RUBY, __FILE__, __LINE__ + 1) # rubocop:disable Style/DocumentDynamicEvalDefinition
               def __lutaml_raw_#{name}
                 @#{name}
               end
@@ -260,7 +314,9 @@ module Lutaml
           # Array on EVERY read — the largest per-call allocation source
           # on instance-heavy parses (TODO.max-perf/06). The optional-arg
           # form allocates nothing, and the read is a direct @ivar.
-          if attr.collection?
+          if !AttributeDefinition.source_compilation?
+            define_block_attribute_getter(name, attr)
+          elsif attr.collection?
             # class_eval interpolates, e.g.:
             #   def items(arg = Lutaml::Model::Serialize::NO_ARG)
             #     if arg.equal?(Lutaml::Model::Serialize::NO_ARG)
@@ -316,7 +372,9 @@ module Lutaml
                            end
           define_method(attr_reader_method) { attr } unless reader_defined
 
-          if attr.collection?
+          if !AttributeDefinition.source_compilation?
+            define_block_attribute_setters(name, attr)
+          elsif attr.collection?
             # class_eval interpolates, e.g.:
             #   def items=(value)
             #     value_set_for(:items)
@@ -376,6 +434,77 @@ module Lutaml
           end
         end
 
+        # Block form of the compiled getter in define_regular_attribute_methods,
+        # for runtimes without a source compiler (see source_compilation?).
+        def define_block_attribute_getter(name, attr)
+          name = name.to_sym # the compiled form passes :name literals
+          ivar = :"@#{name}"
+          if attr.collection?
+            # The compiled getter resolves Array in the model class's scope.
+            scope = self
+            define_method(name) do |arg = Lutaml::Model::Serialize::NO_ARG|
+              if arg.equal?(Lutaml::Model::Serialize::NO_ARG)
+                materialize_lazy_collection(name)
+              else
+                current = IVAR_GET.bind_call(self, ivar) || []
+                new_value = current.is_a?(CONST_GET.bind_call(scope, :Array)) ? current + [arg] : arg
+                IVAR_SET.bind_call(self, ivar, new_value)
+                record_mutation(name, arg)
+                arg
+              end
+            end
+          else
+            define_method(name) do |arg = Lutaml::Model::Serialize::NO_ARG|
+              if arg.equal?(Lutaml::Model::Serialize::NO_ARG)
+                IVAR_GET.bind_call(self, ivar)
+              else
+                public_send(:"#{name}=", arg)
+                arg
+              end
+            end
+          end
+        end
+
+        # Block form of the compiled setters in define_regular_attribute_methods.
+        # The Attribute is read through the same hidden accessor the
+        # compiled form calls, not captured: a setter redefined over an
+        # enum shorthand keeps casting with the accessor's Attribute.
+        def define_block_attribute_setters(name, attr)
+          name = name.to_sym # the compiled form passes :name literals
+          ivar = :"@#{name}"
+          handle = :"__attribute_definition_#{name}"
+          if attr.collection?
+            assign = lambda do |model, value|
+              current = IVAR_GET.bind_call(model, ivar)
+              unless current.equal?(Lutaml::Model::Serialize::LAZY_EMPTY_COLLECTION) &&
+                  (value.nil? || Lutaml::Model::Utils.uninitialized?(value))
+                IVAR_SET.bind_call(model, ivar, value)
+              end
+              SEND.bind_call(model, :record_mutation_collection, name, value)
+            end
+            define_method(:"#{name}=") do |value|
+              value_set_for(name)
+              assign.call(self, SEND.bind_call(self, handle).cast_value(value, lutaml_register))
+            end
+            define_method(:"__assign_parsed_#{name}=") do |value|
+              value_set_for(name)
+              assign.call(self, value)
+            end
+          else
+            define_method(:"#{name}=") do |value|
+              value_set_for(name)
+              value = SEND.bind_call(self, handle).cast_value(value, lutaml_register)
+              IVAR_SET.bind_call(self, ivar, value)
+              record_mutation(name, value)
+            end
+            define_method(:"__assign_parsed_#{name}=") do |value|
+              value_set_for(name)
+              IVAR_SET.bind_call(self, ivar, value)
+              record_mutation(name, value)
+            end
+          end
+        end
+
         # Define an attribute for the model
         #
         # @param name [Symbol] The attribute name

data/lib/lutaml/model/serialize/format_conversion.rb

@@ -103,9 +103,14 @@ module Lutaml
 
           register = Lutaml::Model::Config.default_register
           plan = Lutaml::Xml::Leptris::PlanCompiler.compile(self, register)
-          return nil unless plan && !plan[:namespaced] &&
+          return nil unless plan &&
             Lutaml::Xml::Leptris::PlanSerializer.serializable?(plan)
 
+          # Namespaced plans ride the plan serializer too: the DOM
+          # emission spells prefixed names and hoists declarations
+          # (the #847 xmlns drop is fixed in PlanSerializer); any
+          # unspellable shape answers nil there and falls back
+          # interpretively.
           Lutaml::Xml::Leptris::PlanSerializer.call(instance, plan)
         end
 

data/lib/lutaml/model/serialize/initialization.rb

@@ -345,8 +345,20 @@ module Lutaml
         # @param register [Symbol, nil] The register context
         # @return [Object] The allocated instance
         def allocate_for_deserialization(register = nil)
-          instance = allocate
           register_id = extract_register_id(register)
+          # Deferred imports (symbol-form import_model_attributes) must
+          # resolve before state defaults compile: the compiled seeding
+          # and the raw readers cover the post-import attribute set, and
+          # the transform's records already carry the mapping's rules
+          # for imported names — CTR's <m:br> parsed before resolution
+          # had no reader (#933). The constructor path ensures the same
+          # way (initialize_attributes). Guarded: deep object graphs
+          # (XSD schema trees) allocate recursively, and the ensure
+          # chain's frames per level pushed that recursion past the
+          # stack limit — models without pending deferred imports skip
+          # it entirely.
+          ensure_imports!(register_id) if finalized? && deferred_imports_pending?
+          instance = allocate
           instance.finalize_deserialization(register_id)
           instance
         end

data/lib/lutaml/model/serialize/model_import.rb

@@ -60,6 +60,10 @@ module Lutaml
           model.attributes.each_value { |attr| define_attribute_methods(attr) }
           @attributes.merge!(Utils.deep_dup(model.attributes))
           @choice_attributes.concat(deep_duplicate_choice_attributes(model))
+          # Imported attributes grow the state-defaults surface (the
+          # raw readers live there) — a first use may already have
+          # compiled it for the pre-import attribute set (#933).
+          invalidate_state_defaults!
           # Ensure @models_imported is a hash; migrate from legacy nil/false state
           @models_imported ||= {}
           @models_imported[reg] = true
@@ -122,6 +126,9 @@ module Lutaml
             deep_duplicate_choice_attributes(model, register_id),
           )
           @merged_attributes_cache = nil
+          # See import_model_attributes: late-registered attributes
+          # must recompile the register's state defaults (#933).
+          invalidate_state_defaults!
         end
         private :register_only_import_model_attributes
 
@@ -153,6 +160,15 @@ module Lutaml
         # Ensure all model imports are resolved for a specific register
         #
         # @param register_id [Symbol, nil] The register context
+        # Whether deferred (symbol-form) imports are still pending —
+        # gates the allocation-time ensure chain (#933).
+        def deferred_imports_pending?
+          importable_models.any? { |_method, models| models.any? } ||
+            importable_choices.any? do |_choice, imports|
+              imports.any? { |_method, models| models.any? }
+            end || restrict_attributes.any?
+        end
+
         def ensure_model_imports!(register_id = nil)
           register_id ||= Lutaml::Model::Config.default_register
           @models_imported = {} if @models_imported.nil? || @models_imported == false
@@ -197,6 +213,7 @@ module Lutaml
           @choices_imported[register_id] = true
           all_resolved = true
 
+          resolved_any = false
           importable_choices.each do |choice, choice_imports|
             choice_imports.each do |method, models|
               models.uniq.each do |model|
@@ -216,11 +233,19 @@ module Lutaml
                 end
 
                 choice.public_send(method, model_class, register_id)
+                resolved_any = true
               end
             end
           end
 
           @choices_imported[register_id] = true if all_resolved
+          # Choice imports can add attributes without passing through
+          # define_attribute_methods — recompile state defaults so the
+          # seeding and raw readers cover them (#933). Only when an
+          # import actually resolved: ensure_choice_imports! runs on
+          # every ensure_imports! (allocation-time), and a recompile
+          # per allocation would churn.
+          invalidate_state_defaults! if resolved_any
         end
 
         # Ensure all restrict attributes are applied
@@ -243,6 +268,11 @@ module Lutaml
         # Uses TracePoint to detect when a class definition is complete,
         # allowing deferred import resolution.
         def setup_trace_point
+          # Opal has no TracePoint. Symbol imports still resolve lazily
+          # on first use (ensure_imports!), so there the class is marked
+          # finalized at once instead of at the end of its body.
+          return @finalized = true if Lutaml::Model.opal?
+
           @trace ||= TracePoint.new(:end) do |_tp|
             if include?(Lutaml::Model::Serialize)
               @finalized = true

data/lib/lutaml/model/version.rb

@@ -2,6 +2,6 @@
 
 module Lutaml
   module Model
-    VERSION = "0.8.94"
+    VERSION = "0.8.96"
   end
 end

data/lib/lutaml/model.rb

@@ -294,3 +294,10 @@ require "#{__dir__}/xml/format"
 # Builder must be prepended AFTER XML so its initialize runs first
 # (Builder -> XML InstanceMethods -> Serialize)
 Lutaml::Model::Serialize.prepend(Lutaml::Model::Serialize::Builder)
+
+# Opal does not propagate a module prepended into an already-included
+# module to classes that included it earlier (see lib/lutaml/xml/format.rb).
+# Serializable included Serialize at boot, so Builder goes onto it directly.
+if Lutaml::Model.opal?
+  Lutaml::Model::Serializable.prepend(Lutaml::Model::Serialize::Builder)
+end

data/lib/lutaml/xml/format.rb

@@ -243,9 +243,11 @@ Lutaml::Model::Serialize.prepend(
 #
 # Anonymous model classes (Class.new { include Serialize }) extend
 # Serialize::ClassMethods rather than inheriting from Serializable, so the
-# ModelImportExt override (root?) must land on ClassMethods too. The other
-# two (FormatConversion, InstanceMethods) are already prepended unconditionally
-# above, so Opal's no-double-prepend rule means we don't repeat them here.
+# ModelImportExt override (root?) must land on ClassMethods too.
+#
+# On Opal (and TruffleRuby, below) the ClassMethods.prepend(FormatConversion)
+# above does not reach Serializable's singleton chain, which extended
+# ClassMethods before it ran, so it is prepended onto that singleton directly.
 #
 # TruffleRuby (34.0.1) has the same propagation gap, on both the include
 # side and the extend/singleton side — a module prepended into an
@@ -273,13 +275,9 @@ if Lutaml::Model.opal? || RUBY_ENGINE == "truffleruby"
     Lutaml::Xml::Serialization::ModelImportExt,
   )
 
-  # TruffleRuby only: Opal's no-double-prepend rule makes the unconditional
-  # ClassMethods.prepend(FormatConversion) above sufficient there.
-  if RUBY_ENGINE == "truffleruby"
-    Lutaml::Model::Serializable.singleton_class.prepend(
-      Lutaml::Xml::Serialization::FormatConversion,
-    )
-  end
+  Lutaml::Model::Serializable.singleton_class.prepend(
+    Lutaml::Xml::Serialization::FormatConversion,
+  )
 end
 
 # Register XML-specific attribute override warning names