lutaml-model 0.8.56 → 0.8.106

data/lib/lutaml/key_value/transformation.rb

@@ -209,7 +209,10 @@ register = self.register)
       def transform(model_instance, options = {})
         # For key-value formats, we typically don't have a named root
         # Instead, we create an anonymous root that holds all attributes
-        root = Lutaml::KeyValue::DataModel::Element.new("__root__")
+        # Hash-direct emission (TODO.perf 19): the __root__ Element
+        # tree was write-only in production — every consumer flattened
+        # it straight back to a hash. The output hash is built directly.
+        root = {}
 
         # Apply each compiled rule (with filtering support). A
         # when_attribute partition applies once for its whole key.
@@ -230,11 +233,7 @@ register = self.register)
 
         if ENV["DEBUG_KEYED_COLLECTION"]
           puts "=== TRANSFORM COMPLETE ==="
-          puts "root.children.count: #{root.children.count}"
-          root.children.each do |child|
-            puts "  child key=#{child.key.inspect}, value=#{child.value.inspect}, to_hash=#{child.to_hash.inspect}"
-          end
-          puts "root.to_hash: #{root.to_hash.inspect}"
+          puts "root: #{root.inspect}"
         end
 
         root
@@ -289,15 +288,9 @@ register = self.register)
         end
         return unless present
 
-        element = Lutaml::KeyValue::DataModel::Element.new(
-          group.first.serialized_name,
-        )
-        if items.empty?
-          element.value = []
-        else
-          items.each { |item| element.add_child(item) }
-        end
-        parent.add_child(element)
+        # Items are stamped hashes or primitives: the tree's
+        # children_to_array semantics, expressed directly.
+        parent[group.first.serialized_name] = items
       end
 
       def stamp_discriminator(item, rule)
@@ -332,16 +325,33 @@ 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]
+          # Custom methods receive an Element "doc" and populate it
+          # (public contract, TODO.perf 19 keeps it): a scratch element
+          # is merged into the output hash afterwards.
+          doc = Lutaml::KeyValue::DataModel::Element.new("__root__")
+          # Custom methods may write children, or doc.value[key]=, or
+          # nothing at all (pubid 2.0 regression: an empty scratch
+          # flattened to {key => nil} and crashed the merge). Seed the
+          # value hash and merge only hash-shaped results.
+          doc.value = {}
           # 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])
+            model_instance.public_send(to_method, model_instance,
+                                       doc, options[:context])
+          else
+            model_instance.public_send(to_method, model_instance, doc)
           end
-
-          # Call custom method which directly modifies the parent element
-          return model_instance.public_send(to_method, model_instance,
-                                            parent)
+          # The 0.8.68 contract: only the method's doc mutations count —
+          # its return value is ignored. (A mutation-style handler whose
+          # last statement is an assignment returns the assigned inner
+          # value; honoring it merged child content at the wrong level —
+          # lutaml-model#892.) Empty docs serialize as nothing, matching
+          # the pre-0.8.74 behavior.
+          merged = doc.to_hash
+          parent.update(merged["__root__"]) if merged.is_a?(::Hash) &&
+            merged["__root__"].is_a?(::Hash)
+          return
         end
 
         # Handle delegation - extract value from delegated object
@@ -450,17 +460,9 @@ converted_from_empty_to_nil: false, converted_from_nil_to_empty: false)
           to_map = (rule.option(:value_map) || {})[:to] || {}
           nil_mapping = to_map[:nil]
           if nil_mapping == :empty || converted_from_nil_to_empty
-            # Render as empty collection
-            element = Lutaml::KeyValue::DataModel::Element.new(
-              rule.serialized_name, []
-            )
-            parent.add_child(element)
+            parent[rule.serialized_name] = []
           elsif nil_mapping == :nil || converted_from_empty_to_nil
-            # Render nil collection as nil value
-            element = Lutaml::KeyValue::DataModel::Element.new(
-              rule.serialized_name, nil
-            )
-            parent.add_child(element)
+            parent[rule.serialized_name] = nil
           else
             # Skip nil collection
           end
@@ -519,10 +521,10 @@ converted_from_empty_to_nil: false, converted_from_nil_to_empty: false)
                   # Transform the value to a KeyValueElement
                   value_root = value_transformation.transform(attr_value,
                                                               options)
-                  value_hash = value_root.to_hash
 
-                  # Extract the value from the __root__ wrapper
-                  parent.value[key_value.to_s] = value_hash["__root__"]
+                  # transform emits the output hash directly now
+                  # (TODO.perf 19) — no __root__ wrapper to unwrap.
+                  parent[key_value.to_s] = value_root
                   next
                 end
               end
@@ -540,7 +542,7 @@ converted_from_empty_to_nil: false, converted_from_nil_to_empty: false)
                 # Get the child transformation for the collection item type
                 if item_type.is_a?(Class) && item_type < Lutaml::Model::Serialize
                   # Create a temporary parent KeyValueElement to hold the collection
-                  temp_parent = Lutaml::KeyValue::DataModel::Element.new("__temp__")
+                  temp_parent = {}
 
                   # Convert to array
                   coll_items = Array(attr_value)
@@ -577,18 +579,15 @@ converted_from_empty_to_nil: false, converted_from_nil_to_empty: false)
                                                     coll_items, options)
                   end
 
-                  # Extract the value from temp_parent
-                  temp_hash = temp_parent.to_hash
-                  inner_value = temp_hash["__temp__"]
-                  coll_value = inner_value&.[](value_attribute.to_s) if inner_value
+                  coll_value = temp_parent[value_attribute.to_s]
 
-                  parent.value[key_value.to_s] = coll_value
+                  parent[key_value.to_s] = coll_value
                   next
                 end
               end
 
               # Fallback: just use the value directly
-              parent.value[key_value.to_s] = attr_value
+              parent[key_value.to_s] = attr_value
             end
           # Case 2: Only key attribute specified - serialize all other attributes
           elsif key_attribute
@@ -662,7 +661,7 @@ converted_from_empty_to_nil: false, converted_from_nil_to_empty: false)
                 end
               end
 
-              parent.value[key_value.to_s] = item_hash unless item_hash.empty?
+              parent[key_value.to_s] = item_hash unless item_hash.empty?
             end
           end
 
@@ -872,17 +871,7 @@ child_mappings, options)
           puts "  keyed_hash: #{keyed_hash.inspect}"
         end
 
-        # Create element with hash value
-        element = Lutaml::KeyValue::DataModel::Element.new(
-          rule.serialized_name, keyed_hash
-        )
-
-        if ENV["DEBUG_KEYED_COLLECTION"]
-          puts "  element created: key=#{element.key.inspect}, value=#{element.value.inspect}, children.count=#{element.children.count}"
-          puts "  element.to_hash: #{element.to_hash.inspect}"
-        end
-
-        parent.add_child(element)
+        parent[rule.serialized_name] = keyed_hash
       end
 
       # Create an array collection element (default)
@@ -892,23 +881,13 @@ child_mappings, options)
       # @param items [Array] The collection items
       # @param options [Hash] Options
       def create_array_collection_element(parent, rule, items, options)
-        # Create an element for the collection
-        coll_element = Lutaml::KeyValue::DataModel::Element.new(rule.serialized_name)
-
-        if items.empty?
-          # For empty collections, set value to empty array explicitly
-          coll_element.value = []
-        else
-          # Add each item as a child
-          items.each do |item|
-            child_value = create_value_for_item(rule, item, options)
-            # Use explicit nil check - `if child_value` would fail for boolean false!
-            coll_element.add_child(child_value) unless child_value.nil?
-          end
+        # children_to_array semantics directly: always an array,
+        # nil children skipped (explicit nil check — booleans matter).
+        built = items.each_with_object([]) do |item, memo|
+          child_value = create_value_for_item(rule, item, options)
+          memo << child_value unless child_value.nil?
         end
-
-        # Always add collection element
-        parent.add_child(coll_element)
+        parent[rule.serialized_name] = built
       end
 
       # Get the key attribute for a keyed collection from child_mappings
@@ -956,9 +935,7 @@ child_mappings, options)
               # Since we don't have direct access to the parent mapping here,
               # serialize as array for now (default behavior)
               items.map do |item|
-                child_root = child_transformation.transform(item, options)
-                child_hash = child_root.to_hash
-                child_hash["__root__"]
+                child_transformation.transform(item, options)
               end
             end
           else
@@ -970,10 +947,7 @@ child_mappings, options)
           mapping = attr_type.mappings_for(format, register_id)
           child_transformation = self.class.new(attr_type, mapping, format,
                                                 register)
-          child_root = child_transformation.transform(value,
-                                                      options)
-          child_hash = child_root.to_hash
-          child_hash["__root__"]
+          child_transformation.transform(value, options)
         # Use the transformation to serialize the nested model
         elsif attr_type.is_a?(Class) && attr_type < Lutaml::Model::Type::Value
           wrapped_value = attr_type.new(value)
@@ -1001,16 +975,10 @@ child_mappings, options)
           when :omitted
             return
           when :nil
-            element = Lutaml::KeyValue::DataModel::Element.new(
-              rule.serialized_name, nil
-            )
-            parent.add_child(element)
+            parent[rule.serialized_name] = nil
             return
           when :empty
-            element = Lutaml::KeyValue::DataModel::Element.new(
-              rule.serialized_name, ""
-            )
-            parent.add_child(element)
+            parent[rule.serialized_name] = ""
             return
           end
 
@@ -1019,16 +987,10 @@ child_mappings, options)
         elsif Lutaml::Model::Utils.uninitialized?(value)
           omitted_mapping = to_map[:omitted]
           if omitted_mapping == :nil
-            element = Lutaml::KeyValue::DataModel::Element.new(
-              rule.serialized_name, nil
-            )
-            parent.add_child(element)
+            parent[rule.serialized_name] = nil
             return
           elsif omitted_mapping == :empty
-            element = Lutaml::KeyValue::DataModel::Element.new(
-              rule.serialized_name, ""
-            )
-            parent.add_child(element)
+            parent[rule.serialized_name] = ""
             return
           end
           # uninitialized with no/omitted mapping → skip (default behavior)
@@ -1036,10 +998,7 @@ child_mappings, options)
         elsif Lutaml::Model::Utils.empty?(value)
           empty_mapping = to_map[:empty]
           if empty_mapping == :nil
-            element = Lutaml::KeyValue::DataModel::Element.new(
-              rule.serialized_name, nil
-            )
-            parent.add_child(element)
+            parent[rule.serialized_name] = nil
             return
           elsif empty_mapping == :omitted
             return
@@ -1050,12 +1009,7 @@ child_mappings, options)
         # Normal value serialization
         child_value = create_value_for_item(rule, value, options)
 
-        unless child_value.nil?
-          element = Lutaml::KeyValue::DataModel::Element.new(
-            rule.serialized_name, child_value
-          )
-          parent.add_child(element)
-        end
+        parent[rule.serialized_name] = child_value unless child_value.nil?
       end
 
       # Create value for an item (handles nested models and primitives)
@@ -1125,13 +1079,10 @@ child_mappings, options)
 
           if child_transformation
             child_root = child_transformation.transform(value, options)
-            # Return the hash representation of the child
-            # Remove the __root__ wrapper and return just the content
-            child_hash = child_root.to_hash
-            result = child_hash["__root__"]
-            # If the nested model serialized to empty hash, return nil
-            # This allows render_nil: false to work correctly for nested models
-            result.nil? || result.empty? ? nil : result
+            # transform emits the content hash directly (TODO.perf 19);
+            # an empty serialization still returns nil so render_nil:
+            # false keeps working for nested models.
+            child_root.empty? ? nil : child_root
           else
             # Fallback: serialize as primitive
             serialize_value(value, rule)
@@ -1167,15 +1118,12 @@ child_mappings, options)
         # For each key-value pair in the parsed content, add as a child element
         if parsed_content.is_a?(::Hash)
           parsed_content.each do |key, val|
-            element = Lutaml::KeyValue::DataModel::Element.new(key.to_s, val)
-            parent.add_child(element)
+            parent[key.to_s] = val
           end
         elsif parsed_content.is_a?(::Array)
-          # If the parsed content is an array, we can't merge it directly
-          # This shouldn't happen with valid map_all usage, but handle it gracefully
-          element = Lutaml::KeyValue::DataModel::Element.new("__root__",
-                                                             parsed_content)
-          parent.add_child(element)
+          # Graceful handling of unusual map_all content (parity with
+          # the tree's __root__ wrapper)
+          parent["__root__"] = parsed_content
         end
       end
 

data/lib/lutaml/model/adapter_resolver.rb

@@ -163,7 +163,10 @@ module Lutaml
         #
         # @return [void]
         def reset!
-          @metadata = nil
+          # metadata is registration data populated at format-registration
+          # time, not a resolution cache — wiping it here permanently broke
+          # every format's resolution after a reset (adapter_for fell
+          # through to nil). Resolution caches reset; registrations stay.
           @configured_types = nil
           @resolved = nil
           @detected_types = nil
@@ -250,8 +253,9 @@ module Lutaml
                                      adapter, type)
                          end
           require adapter_path
-        rescue LoadError
-          raise UnknownAdapterTypeError.new(adapter, type), cause: nil
+        rescue LoadError => e
+          # Chain the cause so a missing engine gem is named, not masked.
+          raise UnknownAdapterTypeError.new(adapter, type), cause: e
         end
 
         # Load the Moxml adapter for XML and similar formats.

data/lib/lutaml/model/attribute.rb

@@ -9,6 +9,17 @@ module Lutaml
       include DeepDupable
       include RestrictionValidation
 
+      # Symbol interpolation (:"to_#{format}") allocates a String and a
+      # Symbol per call on the serialization hot path; the table serves
+      # the known formats and the fallback keeps exotic ones working.
+      TO_FORMAT_METHODS = {
+        xml: :to_xml,
+        json: :to_json,
+        yaml: :to_yaml,
+        toml: :to_toml,
+        hash: :to_hash,
+      }.freeze
+
       ALLOWED_OPTIONS = %i[
         raw
         default
@@ -35,6 +46,7 @@ module Lutaml
         signed
         min_length
         max_length
+        desc
       ].freeze
 
       # Per-type-class memo of the custom from_xml/from_json probe used by #cast.
@@ -316,6 +328,16 @@ module Lutaml
         @unresolved_type || @type
       end
 
+      def reference_type?
+        (@reference_type ||= unresolved_type == Lutaml::Model::Type::Reference)
+      end
+
+      def value_map_boolean?
+        (@value_map_boolean ||=
+           type == Lutaml::Model::Type::Boolean ||
+           unresolved_type == Lutaml::Model::Type::Boolean)
+      end
+
       def polymorphic?
         @options[:polymorphic_class]
       end
@@ -438,8 +460,7 @@ module Lutaml
 
         option = value_map[key]
         if (option.is_a?(TrueClass) || option.is_a?(FalseClass)) &&
-            (type == Lutaml::Model::Type::Boolean ||
-             unresolved_type == Lutaml::Model::Type::Boolean)
+            value_map_boolean?
           return option
         end
 
@@ -507,7 +528,8 @@ module Lutaml
         return resolved_type.new(value) if value.is_a?(::Hash) && !hash_type?
 
         # Special handling for Reference types - pass the metadata
-        if unresolved_type == Lutaml::Model::Type::Reference
+        # (the comparison is attribute-constant; memoize the verdict)
+        if reference_type?
           return resolved_type.cast_with_metadata(value,
                                                   @options[:ref_model_class], @options[:ref_key_attribute])
         end
@@ -566,10 +588,15 @@ instance_object = nil)
       end
 
       def default_value(register, instance_object = nil)
-        if delegate
-          type(register).attributes(register)[to].default(register,
-                                                          instance_object)
-        elsif options[:default].is_a?(Proc)
+        # The kind is fixed at definition; the common case (no default
+        # at all) paid three option checks per absent attribute per
+        # instantiation before the memo.
+        case (@default_kind ||= _default_kind)
+        when :none
+          Lutaml::Model::UninitializedClass.instance
+        when :static
+          options[:default]
+        when :proc
           if instance_object
             ::Lutaml::Model::Attribute.evaluating_default do
               instance_object.instance_exec(&options[:default])
@@ -577,13 +604,20 @@ instance_object = nil)
           else
             options[:default].call
           end
-        elsif options.key?(:default)
-          options[:default]
-        else
-          Lutaml::Model::UninitializedClass.instance
+        else # :delegate
+          type(register).attributes(register)[to].default(register,
+                                                          instance_object)
         end
       end
 
+      def _default_kind
+        return :delegate if delegate
+        return :proc if options[:default].is_a?(Proc)
+        return :static if options.key?(:default)
+
+        :none
+      end
+
       # Marks the dynamic extent in which a default proc runs against a
       # model instance, so Serialize#method_missing can fall back to the
       # model class for methods the instance does not define (0.7.x
@@ -608,6 +642,12 @@ instance_object = nil)
         options[:pattern]
       end
 
+      # Documentation metadata (#356): the `:desc` attribute option,
+      # consumed by documentation and schema tooling.
+      def desc
+        options[:desc]
+      end
+
       # Performance: Frozen empty array to reduce allocations
       EMPTY_VALUES_ARRAY = [].freeze
 
@@ -816,11 +856,10 @@ instance_object = nil)
         return value if value.nil? || Utils.uninitialized?(value)
 
         resolved_type = options[:resolved_type] || type(register)
-        serialize_options = options.merge(resolved_type: resolved_type)
         value = reference_key(value) if unresolved_type == Lutaml::Model::Type::Reference
         if collection_instance?(value)
           return serialize_array(value, format, register,
-                                 serialize_options)
+                                 options.merge(resolved_type: resolved_type))
         end
         if resolved_type <= Serialize
           return serialize_model(value, format, register,
@@ -1201,8 +1240,28 @@ instance_object = nil)
       end
 
       def serialize_value(value, format, resolved_type)
-        value = wrap_in_type_if_needed(value, resolved_type)
-        value.public_send(:"to_#{format}")
+        # The Value wrapper is a pass-through on the to_ side (its
+        # to_<format> returns the wrapped raw value unless a custom
+        # format serializer is registered), so the common path returns
+        # the raw value and lets the caller stringify — one object
+        # instead of three per serialized scalar. Reference and
+        # custom-serializer rows keep the wrapped path.
+        if resolved_type <= Type::Reference ||
+            (registered_to = Type::Value.format_type_serializer_for(format, resolved_type)&.dig(:to))
+          # String→String under the default :xml serializer is the
+          # identity — the wrapper mint per string value on the XML
+          # serialize path is pure waste. A consumer override of the
+          # serializer disables the fast path via the proc comparison.
+          if resolved_type == Type::String && value.is_a?(::String) &&
+              registered_to == Lutaml::Xml::Type::Serializers::STRING_XML_TO
+            return value
+          end
+
+          value = wrap_in_type_if_needed(value, resolved_type)
+          return value.public_send(TO_FORMAT_METHODS[format] || :"to_#{format}")
+        end
+
+        value
       end
 
       def wrap_in_type_if_needed(value, resolved_type)

data/lib/lutaml/model/cached_type_resolver.rb

@@ -59,14 +59,14 @@ module Lutaml
       # updates so recursive type resolution can populate related keys.
       #
       # @param name [Symbol, String, Class] The type name or class to resolve
-      # @param context [TypeContext] The resolution context
+      # @param context [TypeContext, nil] The resolution context
       # @return [Class] The resolved type class
       # @raise [UnknownTypeError] If type cannot be resolved
       def resolve(name, context, materialize: true)
         return @delegate.resolve(name, context, materialize: false) unless materialize
 
         cache_key = if name.is_a?(Class)
-                      [context.id, name]
+                      [context_id_for(context), name]
                     else
                       build_cache_key(name, context)
                     end
@@ -79,11 +79,11 @@ module Lutaml
       # Check if a type can be resolved, using cache if available.
       #
       # @param name [Symbol, String, Class] The type name or class to check
-      # @param context [TypeContext] The resolution context
+      # @param context [TypeContext, nil] The resolution context
       # @return [Boolean] true if type can be resolved
       def resolvable?(name, context)
         cache_key = if name.is_a?(Class)
-                      [context.id, name]
+                      [context_id_for(context), name]
                     else
                       build_cache_key(name, context)
                     end
@@ -137,10 +137,17 @@ module Lutaml
       # Uses array for faster comparison than string concatenation.
       #
       # @param name [Symbol, String] The type name
-      # @param context [TypeContext] The resolution context
+      # @param context [TypeContext, nil] The resolution context
       # @return [Array] The cache key (faster than string)
       def build_cache_key(name, context)
-        [context.id, name.to_sym]
+        [context_id_for(context), name.to_sym]
+      end
+
+      # A nil context (e.g. a register ID that has no registered type
+      # context) is a legitimate "no namespace" resolution; the cache
+      # key just forgoes the namespace slot.
+      def context_id_for(context)
+        context&.id
       end
     end
   end

data/lib/lutaml/model/configuration.rb

@@ -19,6 +19,17 @@ module Lutaml
       # compilable XML models (Leptris::XML::Descriptor walk). Opt-in
       # while the full semantics audit completes.
       attr_accessor :xml_plan_fast_path
+      # Ordered/mixed-content models on the plan path: opt-in. The
+      # per-node ordered hydration is FASTER than the interpretive
+      # lane on time but allocates above the downstream budget gates
+      # (niso pnas ratio 1.25); it ships dark until the allocation
+      # diet lands.
+      attr_accessor :xml_plan_ordered_path
+      # #909: when false, XML deserialization skips the per-instance
+      # element_order/attribute_order summaries — read-only consumers of
+      # large documents never serialize back and should not pay for
+      # hundreds of thousands of pinned order records.
+      attr_accessor :element_order_tracking
       attr_writer :conversion_cache
 
       def initialize
@@ -26,6 +37,8 @@ module Lutaml
         @conversion_cache = nil
         @configured = false
         @xml_plan_fast_path = true
+        @xml_plan_ordered_path = false
+        @element_order_tracking = true
       end
 
       def configure

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

@@ -3,6 +3,19 @@ module Lutaml
     class Mapping
       include DeepDupable
 
+      # Uniform interface across mapping families: every mapping
+      # answers these, so consumers call them unconditionally. The
+      # families that carry the feature override (KeyValue's
+      # root_mappings, Xml's namespace_class); the base defaults make
+      # the absence explicit instead of probed.
+      def root_mappings?
+        false
+      end
+
+      def namespace_class
+        nil
+      end
+
       attr_writer :mappings
 
       def initialize

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

@@ -182,13 +182,18 @@ module Lutaml
       alias from name
       alias render_default? render_default
 
+      # Frozen default: render? only reads options (render_nil?/render_empty?/
+      # render_omitted? policies); a fresh {} per call is pure churn on the
+      # serialization hot path.
+      EMPTY_RENDER_OPTIONS = {}.freeze
+
       # Whether this rule participates in serialization output. False
       # marks a hydrate-only mapping: consumed by from_* but never
       # rendered by to_*. (The value callback #serialize is separate.)
       def serialize? = @serialize_mapping
       alias attribute? attribute
 
-      def render?(value, instance = nil, options = {})
+      def render?(value, instance = nil, options = EMPTY_RENDER_OPTIONS)
         if invalid_value?(value, options)
           false
         # FIXED: Check if collection was mutated after initialization