lutaml-model 0.8.37 → 0.8.39

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ec31a25915a5fd6ceeb31c2e61456c90ae223e565eab14051f8ddb40e373fe9e
-  data.tar.gz: a2e6027e8684bfcc63e58650f979d880e43836ea5521f0ee0ba5e30205bd89cf
+  metadata.gz: 15f9489eb4db353b481f160703e848e35b730cef179d32874941fc537ed962d3
+  data.tar.gz: f0067a5ffc4d66c8312d9cc478d9bd7d1771d9b639111c3158956b2d98e4468e
 SHA512:
-  metadata.gz: a101732ad5730070d1c7629b9bf0e72e6573d01a716cf165846b8474f5b7dca7e2415d80ed7a1f8d526fea61363ecbba414e9ecb819f8f2b42b9f09636e81d03
-  data.tar.gz: 42e60f78f63d5d8033edba244858479c95dc1147cf9cc2698ab410d259bd8485a2d2df9825482dc3f895d673177212c1e686a143b5afdde2850d78a706241170
+  metadata.gz: 9f1372cbf492e141015524382a3ac98cdc5f484441d70c593b7ad67b9021bfa959732700679534bb3690f86c064e3a1a82269833c5c73794fe87af24f21d239b
+  data.tar.gz: '048d412becdba7a8a99070740663d0d0a33e88d02018708818ce816d1ba4669a1f26efbf08d0c67390818c5efede0e362ef8f1785536c4233a2fa6dadd07da61'

data/bench/gate_config.rb

@@ -57,10 +57,11 @@ module GateConfig
       "iso-13849-1MB" => {
         alloc_ratio: 1.05,
         time_ratio: 1.15,
-        # GH-hosted ubuntu runners run this fixture at ~12s min_time
-        # (observed across moxml 0.1–0.5); 5.0 never passed there and
-        # fired on every run. 15.0 keeps the 2x-catastrophe safety net.
-        absolute_max: 15.0,
+        # Post-TODO.max-perf/01-03 the fixture sits at ~4.88M allocs and
+        # 14.5-16.5s on GH-hosted ubuntu runners (runner-variance band);
+        # the old 15.0 missed by 0.06s on a healthy run. 30.0 keeps the
+        # 2x-catastrophe safety net over the healthy band (#313).
+        absolute_max: 30.0,
       },
       "din-iso-1.1MB" => {
         alloc_ratio: 1.05,

data/docs/_guides/custom-methods.adoc

@@ -0,0 +1,71 @@
+= Custom serialization methods
+
+:toc:
+
+Lutaml::Model maps serialization constructs (`map_element`, `map_attribute`, `map_content`, key-value `map`) to *model attributes*. When the wire shape and the model shape disagree, custom methods bridge the gap at the mapping site instead of hand-rolled `to_h`/`from_h` code.
+
+== `with:` — per-rule custom methods
+
+Declare both directions on the rule. The methods live on the model (instance methods); the names are symbols.
+
+[source,ruby]
+----
+class Requirement
+  include Lutaml::Model::Serialize
+
+  attribute :guidance, :string
+  attribute :purpose, :string
+
+  xml do
+    element "requirement"
+    map_element "component", to: :guidance,
+      with: { from: :component_from_guidance, to: :component_to_guidance }
+  end
+
+  def component_from_guidance(model, value, ctx = nil)
+    # `from` receives (model, value[, context]); assign the model attribute
+    model.guidance = value
+  end
+
+  def component_to_guidance(model, parent, doc = nil, ctx = nil)
+    # `to` receives (model, parent[, doc[, context]]); write into parent/doc
+    parent.add_element("component", model.guidance, type: "guidance")
+  end
+end
+----
+
+Notes:
+
+* The `from` method *assigns* the attribute (it receives the whole model); the `to` method *writes* the output document.
+* The optional trailing `context` parameter receives the options hash passed to `Model.from_xml(data, context: {...})` / `model.to_xml(context: {...})` — it is forwarded when the method declares it (lutaml-model#550).
+* Callables work in key-value mappings: `with: { from: ->(value) { ... } }` maps and assigns the return value; an exact-arity-2 callable receives the context as its second argument.
+
+== `transform:` — value-level transforms
+
+`transform:` converts values (not documents). A Hash form (`transform: { from: ->(v) {...}, to: ->(v) {...} }`) wraps the value in both directions without touching assignment; a `ValueTransformer` subclass receives `from(value, format)` / `to(value, format)` and is shared by every rule that references it.
+
+== Type-level serialization
+
+A *type class* (a `Lutaml::Model::Type::Value` subclass) can carry its own format behavior, so reuse lives on the type rather than the parent mapping:
+
+[source,ruby]
+----
+class XmiNsType < Lutaml::Model::Type::String
+  xml do
+    namespace XmiNs # bind the type's own namespace
+  end
+end
+----
+
+`Lutaml::Model::Type::Value.register_format_type_serializer(format, type_class, to:, from:)` registers per-format serialize/deserialize procs for a type class; resolution walks the hierarchy.
+
+== `of_*` and the conversion entry points
+
+`Model.of_<format>(parsed_document, options)` is the documented seam between adapter parsing and mapping application: the adapter (`from_<format>`) parses the wire data into a document object, and `of_<format>` (class method) applies the mappings to build instances. It is public API for tooling that already holds a parsed document — e.g. re-applying mappings to a reparsed tree — and is what `from_<format>` delegates to.
+
+The per-instance counterparts are `to_<format>` (serialize through the mappings) and `as_<format>` (render without register-specific side effects). Prefer the generated `from_*/to_*` methods; reach for `of_*` only when you interpose between parse and mapping.
+
+== Common recipes
+
+* One wire element, several attributes dispatched by an attribute value (`component/@type`): one `with:` pair per attribute whose `from` inspects the dispatch attribute and whose `to` emits only for its type. (Polymorphic *class* dispatch has first-class support via `polymorphic:`.)
+* Key remapping, nesting shifts, delimiter splitting: prefer `transform:`, `child_mappings`, and `root`/`prefix` options before custom methods — the mapping stays declarative and reviewable.

data/docs/_guides/index.adoc

@@ -19,6 +19,7 @@ Task-oriented guides for accomplishing specific goals with Lutaml::Model.
 
 == Key-value serialization
 
+* link:../custom-methods[Custom Serialization Methods] - with:/transform:, type-level serialization, of_* entry points
 * link:../keyvalue-serialization[Key-Value Serialization] - JSON/YAML/TOML/Hash
 * link:../collection-serialization[Collection Serialization] - JSONL and YAML Stream
 

data/lib/compat/opal/lutaml_model_boot.rb

@@ -146,6 +146,7 @@ require "lutaml/xml/encoding_normalizer"
 require "lutaml/xml/format"
 require "lutaml/xml/format_chooser"
 require "lutaml/xml/hoisting_algorithm"
+require "lutaml/xml/html_entities"
 require "lutaml/xml/listener"
 require "lutaml/xml/mapping"
 require "lutaml/xml/mapping_rule"

data/lib/lutaml/key_value/transform.rb

@@ -68,10 +68,33 @@ module Lutaml
 
       def process_mapping_for_instance(instance, hash, format, rule, options)
         if rule.custom_methods[:to]
-          return instance.public_send(rule.custom_methods[:to], instance, hash)
+          to_method = rule.custom_methods[:to]
+          # lutaml-model#550: custom methods may declare a third context
+          # parameter to receive the options passed to `to_*`.
+          if instance.method(to_method).parameters.size >= 3
+            return instance.public_send(to_method, instance, hash,
+                                        options[:context])
+          end
+
+          return instance.public_send(to_method, instance, hash)
         end
 
         attribute = attributes[rule.to]
+
+        # TODO.max-perf/10: plain scalar/collection rules take a fast
+        # lane — memoized wire name, shared render? semantics, one
+        # serialize dispatch — collapsing the interpretive branch
+        # probes below. Rules with any special feature stay on the
+        # full path.
+        if (plan = kv_serialize_plan(rule, attribute, instance))
+          value = instance.public_send(attribute.name)
+          if rule.render?(value, instance)
+            hash[plan.wire] = attribute.serialize(value, format,
+                                                  lutaml_register, options)
+          end
+          return
+        end
+
         value = rule.serialize(instance)
 
         if rule.can_transform_to?(attribute, format)
@@ -90,7 +113,9 @@ module Lutaml
         end
 
         # Use the format parameter passed in instead of hardcoding to :json
-        value = ExportTransformer.call(value, rule, attribute, format: format)
+        value = ExportTransformer.call(value, rule, attribute,
+                                       format: format,
+                                       context: options[:context])
 
         value = serialize_value(value, rule, attribute, format, options)
 
@@ -247,7 +272,7 @@ format)
         if (plan = kv_rule_plan(format, rule, attr)) &&
             (value = kv_fast_extract(doc, plan))
           rule.deserialize(instance, kv_fast_cast(value, plan, instance),
-                           attributes, self)
+                           attributes, self, options[:context])
           return
         end
 
@@ -261,7 +286,8 @@ format)
           # only nil (non-existent) skips it (lutaml-model#746).
           return if value.nil?
 
-          return rule.deserialize(instance, value, attributes, model_class)
+          return rule.deserialize(instance, value, attributes, model_class,
+                                  options[:context])
         end
 
         value = rule.transform_value(attr, value, :from, format)
@@ -279,7 +305,8 @@ format)
         if attr.collection? || !instance.is_a?(Lutaml::Model::Serialize)
           attr.valid_collection!(value, context)
         end
-        rule.deserialize(instance, value, attributes, self)
+        rule.deserialize(instance, value, attributes, self,
+                         options[:context])
       end
 
       # Compiled rule plans (TODO.perf/07): for plain scalar rules the
@@ -291,6 +318,25 @@ format)
       # unions, polymorphism) return nil and keep the interpretive path.
       KvRulePlan = ::Struct.new(:wire, :klass, :collection)
 
+      # Memoized (per transform) wire name for plain rules — the from
+      # spelling never changes after definition.
+      KvSerializePlan = ::Struct.new(:wire)
+
+      def kv_serialize_plan(rule, attr, _instance)
+        return nil if rule.delegate || rule.raw_mapping? || rule.root_mapping? ||
+          rule.hash_mappings || rule.child_mappings ||
+          rule.has_custom_method_for_serialization? ||
+          rule.multiple_mappings? || polymorphic_rule?(rule) ||
+          (rule.transform.is_a?(Hash) && !rule.transform.empty?) ||
+          rule.transform.is_a?(Class) || attr.nil? || attr.derived? ||
+          attr.union? || attr.polymorphic? || attr.custom_collection? ||
+          attr.transform ||
+          rule.value_map(:to) != Lutaml::Model::Serialize::DEFAULT_VALUE_MAP
+
+        @kv_serialize_plans ||= {}.compare_by_identity
+        @kv_serialize_plans[rule] ||= KvSerializePlan.new(rule_from_name(rule))
+      end
+
       def kv_rule_plan(format, rule, attr)
         @kv_rule_plans ||= {}
         @kv_rule_plans[[format, rule]] ||= build_kv_rule_plan(format, rule,

data/lib/lutaml/key_value/transformation.rb

@@ -220,9 +220,17 @@ register = self.register)
 
         # Handle custom serialization methods (e.g., with: { to: ... })
         if rule.has_custom_methods? && rule.custom_methods[:to]
+          to_method = rule.custom_methods[:to]
+          # lutaml-model#550: custom methods may declare a third context
+          # parameter to receive the options passed to `to_*`.
+          if model_instance.method(to_method).parameters.size >= 3
+            return model_instance.public_send(to_method, model_instance,
+                                              parent, options[:context])
+          end
+
           # Call custom method which directly modifies the parent element
-          return model_instance.public_send(rule.custom_methods[:to],
-                                            model_instance, parent)
+          return model_instance.public_send(to_method, model_instance,
+                                            parent)
         end
 
         # Handle delegation - extract value from delegated object

data/lib/lutaml/model/attribute.rb

@@ -471,7 +471,11 @@ module Lutaml
                                                   @options[:ref_model_class], @options[:ref_key_attribute])
         end
 
-        validate_attr_type!(resolved_type)
+        # The castability verdict is a class-hierarchy fact, immutable
+        # per resolved type — check once, not per value (TODO.max-perf/15).
+        checked = (@castable_types ||= {}.compare_by_identity)
+        validate_attr_type!(resolved_type) unless checked[resolved_type]
+        checked[resolved_type] = true
 
         resolved_type.cast(value)
       end

data/lib/lutaml/model/compiled_rule.rb

@@ -208,6 +208,15 @@ module Lutaml
       # @param args [Array] Arguments (ignored for options)
       # @param block [Proc] Block (ignored for options)
       # @return [Object] The option value or nil
+      # Static per rule (see MappingRule#custom_method_only?). Compiled
+      # rules are frozen, so the answer is recomputed with a single
+      # to_s instead of the historical two.
+      def custom_method_only?
+        name = attribute_name.to_s
+        (name.start_with?("__") && name.end_with?("__")) ||
+          (!custom_methods.empty? && attribute_type.nil?)
+      end
+
       def method_missing(method_name, *args, &block)
         # Check if this is an option key
         if options.key?(method_name)

data/lib/lutaml/model/format_registry.rb

@@ -23,7 +23,8 @@ module Lutaml
         # @param adapter_options [Hash, nil] { available: [...], default: :name }
         def register(format, mapping_class:, adapter_class:, transformer:,
                      adapter_loader: nil, castable_type: nil, key_value: nil,
-                     rdf: nil, error_types: nil, adapter_options: nil)
+                     rdf: nil, error_types: nil, adapter_options: nil,
+                     stream_methods: false)
           validate_registration!(format, mapping_class, transformer)
 
           registered_formats[format] = {
@@ -44,6 +45,7 @@ module Lutaml
           ::Lutaml::Model::Serialize.register_format_mapping_method(format)
           ::Lutaml::Model::Serialize.register_from_format_method(format)
           ::Lutaml::Model::Serialize.register_to_format_method(format)
+          ::Lutaml::Model::Serialize.register_stream_methods(format) if stream_methods
 
           ::Lutaml::Model::Attribute.format_specific_warn_names.push(:"to_#{format}")
 

data/lib/lutaml/model/mapping/mapping_rule.rb

@@ -268,9 +268,16 @@ module Lutaml
         end
       end
 
-      def serialize(model, parent = nil, doc = nil)
+      def serialize(model, parent = nil, doc = nil, context = nil)
         if custom_methods[:to]
-          model.public_send(custom_methods[:to], model, parent, doc)
+          to_method = custom_methods[:to]
+          # lutaml-model#550: custom methods may declare a fourth
+          # context parameter to receive the options passed to `to_*`.
+          if model.method(to_method).parameters.size >= 4
+            model.public_send(to_method, model, parent, doc, context)
+          else
+            model.public_send(to_method, model, parent, doc)
+          end
         else
           value = to_value_for(model)
 
@@ -289,16 +296,29 @@ module Lutaml
         end
       end
 
-      def deserialize(model, value, attributes, mapper_class = nil)
+      def deserialize(model, value, attributes, mapper_class = nil,
+context = nil)
         if @needs_full_deserialize
-          handle_custom_method(model, value, mapper_class) ||
+          handle_custom_method(model, value, mapper_class, context) ||
             handle_delegate(model, value, attributes) ||
-            handle_transform_method(model, value, attributes)
+            handle_transform_method(model, value, attributes, context)
         else
-          handle_transform_method(model, value, attributes)
+          handle_transform_method(model, value, attributes, context)
         end
       end
 
+      # Static per rule: placeholder `__name__` targets and inferred
+      # custom-method targets without an attribute type never change —
+      # the applier asked this per element and paid two to_s strings
+      # each time (240k allocations on the ISO-13849 serialize profile).
+      # Rules may be frozen, so no per-instance memo: one to_s instead
+      # of two is the frozen-safe diet.
+      def custom_method_only?
+        name = attribute_name.to_s
+        (name.start_with?("__") && name.end_with?("__")) ||
+          (has_custom_methods? && attribute_type.nil?)
+      end
+
       def has_custom_method_for_serialization?
         !custom_methods.empty? && custom_methods[:to]
       end
@@ -416,10 +436,29 @@ module Lutaml
         end
       end
 
-      def handle_custom_method(model, value, mapper_class)
-        return if !custom_methods[:from] || value.nil?
+      def handle_custom_method(model, value, mapper_class, context = nil)
+        custom = custom_methods[:from]
+        return if !custom || value.nil?
 
-        mapper_class.new.public_send(custom_methods[:from], model, value)
+        if custom.is_a?(String) || custom.is_a?(Symbol)
+          target = mapper_class.new
+          # lutaml-model#550: custom methods may declare a third context
+          # parameter to receive the options passed to `from_*`.
+          if target.method(custom).parameters.size >= 3
+            target.public_send(custom, model, value, context)
+          else
+            target.public_send(custom, model, value)
+          end
+        else
+          # Callable (proc/lambda): transforms the value and the rule
+          # assigns it. Exact arity 2 receives the `from_*` context.
+          transformed = if custom.arity == 2
+                          custom.call(value, context)
+                        else
+                          custom.call(value)
+                        end
+          assign_value(model, transformed)
+        end
         true
       end
 
@@ -439,7 +478,7 @@ module Lutaml
                           attributes[delegate].type(model.lutaml_register).new)
       end
 
-      def handle_transform_method(model, value, attributes)
+      def handle_transform_method(model, value, attributes, context = nil)
         attr = attributes[to]
         # Fast path: no transforms at all (covers 95%+ of rules)
         # transform defaults to {} which is truthy but semantically empty
@@ -460,7 +499,8 @@ module Lutaml
           assign_value(model, value)
         else
           # Hash/proc transformers need ImportTransformer
-          transformed = ImportTransformer.call(value, self, attr)
+          transformed = ImportTransformer.call(value, self, attr,
+                                               context: context)
           assign_value(model, transformed)
         end
         true

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

@@ -17,16 +17,28 @@ module Lutaml
         # LAZY_EMPTY_COLLECTION, scalars share the UninitializedClass
         # singleton. Compiled once instead of walked per instance — the
         # grammars-compile-don't-interpret rule applied to object state.
-        # Compile (per class, on demand) the method that seeds every
-        # attribute with its "no data arrived" sentinel: collections share
-        # the frozen LAZY_EMPTY_COLLECTION, scalars share the
-        # UninitializedClass singleton. Compiled once instead of walked
-        # per instance — grammars compile, they don't interpret.
-        def compile_state_defaults!(_register = nil)
-          attrs = attributes
+        # Compile (per class and register, on demand) the method that
+        # seeds every attribute with its "no data arrived" sentinel:
+        # collections share the frozen LAZY_EMPTY_COLLECTION, scalars
+        # share the UninitializedClass singleton. Compiled once instead
+        # of walked per instance — grammars compile, they don't
+        # interpret.
+        def compiled_state_defaults_name!(register_id)
+          @state_defaults_names ||= {}
+          name = @state_defaults_names[register_id]
+          return name if name
+
+          method_name = :"__init_state_defaults_#{register_id}"
+          compile_state_defaults!(method_name, register_id)
+          @state_defaults_names[register_id] = method_name
+          method_name
+        end
+
+        def compile_state_defaults!(method_name, register_id = nil)
+          attrs = attributes(register_id)
 
           if attrs.empty?
-            define_method(:__init_deserialized_state_defaults) do
+            define_method(method_name) do
               # no attributes to seed
             end
             return
@@ -41,28 +53,57 @@ module Lutaml
           end.join("\n")
 
           # class_eval interpolates per-attribute `@name = <sentinel>` lines:
-          #   def __init_deserialized_state_defaults
+          #   def __init_state_defaults_default
           #     @id = Lutaml::Model::UninitializedClass.instance
           #     @items = Lutaml::Model::Serialize::LAZY_EMPTY_COLLECTION
           #   end
           class_eval(<<~RUBY, __FILE__, __LINE__ + 1) # rubocop:disable Style/DocumentDynamicEvalDefinition
-            def __init_deserialized_state_defaults
+            def #{method_name}
             #{lines}
             end
           RUBY
         end
 
+        # Historical getter shape for punctuation-named attributes and
+        # any name the compiled form cannot express.
+        def define_reflective_attribute_methods(name, attr)
+          if attr.collection?
+            define_method(name) do |*args|
+              if args.empty?
+                materialize_lazy_collection(name)
+              else
+                # Builder-style: g.member(item) appends to collection
+                value = args.first
+                current = instance_variable_get(:"@#{name}") || []
+                new_value = current.is_a?(Array) ? current + [value] : value
+                instance_variable_set(:"@#{name}", new_value)
+                record_mutation(name, value)
+                value
+              end
+            end
+          else
+            define_method(name) do |*args|
+              if args.empty?
+                instance_variable_get(:"@#{name}")
+              else
+                public_send(:"#{name}=", args.first)
+                args.first
+              end
+            end
+          end
+        end
+
         def invalidate_state_defaults!
           # Opal's method_defined? takes no inherit flag (see the
           # setter_defined check in define_regular_attribute_methods).
-          defined_now = if Lutaml::Model.opal?
-                          method_defined?(:__init_deserialized_state_defaults)
-                        else
-                          method_defined?(:__init_deserialized_state_defaults, false)
-                        end
-          return unless defined_now
-
-          remove_method(:__init_deserialized_state_defaults)
+          (@state_defaults_names ||= {}).each_key do |compiled|
+            defined_now = if Lutaml::Model.opal?
+                            method_defined?(compiled)
+                          else
+                            method_defined?(compiled, false)
+                          end
+            remove_method(compiled) if defined_now
+          end
         end
 
         def define_attribute_methods(attr, register = nil)
@@ -159,35 +200,54 @@ module Lutaml
         #
         # @param name [Symbol] The attribute name
         # @param attr [Attribute] The attribute definition
+        # Plain identifier names compile to `@name` reads; punctuation
+        # names (`mixed?`) keep the reflective path (@name is not valid
+        # Ruby for them).
+        PLAIN_NAME = /\A[a-zA-Z_][a-zA-Z0-9_]*\z/
+
         def define_regular_attribute_methods(name, attr)
-          # For collection attributes, the getter accepts an optional argument
-          # for builder-style syntax: g.member(item) appends to the collection
+          unless name.to_s.match?(PLAIN_NAME)
+            return define_reflective_attribute_methods(name, attr)
+          end
+
+          # Getters compile with a sentinel default argument instead of a
+          # `*args` splat: the splat allocated an (almost always empty)
+          # 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?
-            define_method(name) do |*args|
-              if args.empty?
-                materialize_lazy_collection(name)
-              else
-                # Builder-style: g.member(item) appends to collection
-                value = args.first
-                current = instance_variable_get(:"@#{name}") || []
-                new_value = current.is_a?(Array) ? current + [value] : value
-                instance_variable_set(:"@#{name}", new_value)
-                record_mutation(name, value)
-                value
+            # class_eval interpolates, e.g.:
+            #   def items(arg = Lutaml::Model::Serialize::NO_ARG)
+            #     if arg.equal?(Lutaml::Model::Serialize::NO_ARG)
+            #       materialize_lazy_collection(:items)
+            #     else
+            #       ... builder append ...
+            #     end
+            #   end
+            class_eval(<<~RUBY, __FILE__, __LINE__ + 1) # rubocop:disable Style/DocumentDynamicEvalDefinition
+              def #{name}(arg = Lutaml::Model::Serialize::NO_ARG)
+                if arg.equal?(Lutaml::Model::Serialize::NO_ARG)
+                  materialize_lazy_collection(:#{name})
+                else
+                  current = @#{name} || []
+                  new_value = current.is_a?(Array) ? current + [arg] : arg
+                  @#{name} = new_value
+                  record_mutation(:#{name}, arg)
+                  arg
+                end
               end
-            end
+            RUBY
           else
-            # For non-collection attributes, getter accepts optional argument
-            # for builder-style syntax: g.description(value) sets the value.
-            # Tracking happens inside the setter, so no duplicate call here.
-            define_method(name) do |*args|
-              if args.empty?
-                instance_variable_get(:"@#{name}")
-              else
-                public_send(:"#{name}=", args.first)
-                args.first
+            class_eval(<<~RUBY, __FILE__, __LINE__ + 1) # rubocop:disable Style/DocumentDynamicEvalDefinition
+              def #{name}(arg = Lutaml::Model::Serialize::NO_ARG)
+                if arg.equal?(Lutaml::Model::Serialize::NO_ARG)
+                  @#{name}
+                else
+                  public_send(:"#{name}=", arg)
+                  arg
+                end
               end
-            end
+            RUBY
           end
 
           enum_shorthand_names = instance_variable_get(:@__enum_shorthand_names__) || Set.new
@@ -199,35 +259,53 @@ module Lutaml
                            else
                              method_defined?(:"#{name}=", false)
                            end
-          unless setter_defined && !enum_shorthand_names.include?(name.to_s)
-            if attr.collection?
-              define_method(:"#{name}=") do |value|
-                value_set_for(name)
-                value = attr.cast_value(value, lutaml_register)
-                # Preserve the frozen sentinel when the deserialization pipeline
-                # would overwrite it with nil/UninitializedClass (meaning "no data
-                # found for this collection"). This maintains the zero-allocation
-                # guarantee for unused collections. The sentinel is replaced with
-                # a real Array only when actual data is set.
-                current = instance_variable_get(:"@#{name}")
-                if current.equal?(LAZY_EMPTY_COLLECTION) &&
+          return if setter_defined && !enum_shorthand_names.include?(name.to_s)
+
+          # class_eval'd bodies cannot close over locals; a hidden
+          # define_method accessor holds the Attribute handle.
+          attr_reader_method = :"__attribute_definition_#{name}"
+          reader_defined = if Lutaml::Model.opal?
+                             method_defined?(attr_reader_method)
+                           else
+                             method_defined?(attr_reader_method, false)
+                           end
+          define_method(attr_reader_method) { attr } unless reader_defined
+
+          if attr.collection?
+            # class_eval interpolates, e.g.:
+            #   def items=(value)
+            #     value_set_for(:items)
+            #     value = ATTR.cast_value(value, lutaml_register)
+            #     current = @items
+            #     ... sentinel preservation ...
+            #     record_mutation_collection(:items, value)
+            #   end
+            # The compiled body writes @items directly: the define_method
+            # form interpolated "@items" name strings per call — one per
+            # setter invocation on instance-heavy parses (TODO.max-perf/06).
+            class_eval(<<~RUBY, __FILE__, __LINE__ + 1) # rubocop:disable Style/DocumentDynamicEvalDefinition
+              def #{name}=(value)
+                value_set_for(:#{name})
+                value = __attribute_definition_#{name}.cast_value(value, lutaml_register)
+                current = @#{name}
+                if current.equal?(Lutaml::Model::Serialize::LAZY_EMPTY_COLLECTION) &&
                     (value.nil? || Lutaml::Model::Utils.uninitialized?(value))
                   # Sentinel stays — no allocation for truly empty collections
                 else
-                  instance_variable_set(:"@#{name}", value)
+                  @#{name} = value
                 end
-                # Track one entry per item so element_order reflects the
-                # number of <name> elements that will be emitted.
-                record_mutation_collection(name, value)
+                record_mutation_collection(:#{name}, value)
               end
-            else
-              define_method(:"#{name}=") do |value|
-                value_set_for(name)
-                value = attr.cast_value(value, lutaml_register)
-                instance_variable_set(:"@#{name}", value)
-                record_mutation(name, value)
+            RUBY
+          else
+            class_eval(<<~RUBY, __FILE__, __LINE__ + 1) # rubocop:disable Style/DocumentDynamicEvalDefinition
+              def #{name}=(value)
+                value_set_for(:#{name})
+                value = __attribute_definition_#{name}.cast_value(value, lutaml_register)
+                @#{name} = value
+                record_mutation(:#{name}, value)
               end
-            end
+            RUBY
           end
         end