lutaml-model 0.8.102 → 0.8.104

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d307b0cf0381619d2f8a8d239a0f0ccdd3bc869b9ece087af504adfc19c1ef1c
-  data.tar.gz: d2b28b3820c8331b45f078325d21492091cbbb15b1240d1750924599ee8ed3ce
+  metadata.gz: bd4d3ab0b184df92ad1d6ef04af5e1e1af9d483d34902f36d94b010477c54841
+  data.tar.gz: 6e5eee3bebcf1b9557b1cf635253b322a5dffc31fcbe1c7e3b07a76143a2100f
 SHA512:
-  metadata.gz: 6d631f610cf9e057a8c23f3e27945d0ac7ca15a9f9633f5e49143a693148f496a1dfb3a99857efea37653f50241a96f6069d6d03839774368c82479c965942fb
-  data.tar.gz: a4bc2ee7e75df18ebda941551972fb85a960503005dbeae0be453f792db53616785209068d38d43eb68e6e84ad85e2e1ac31fcf07acd41780a15adf4b571ed5b
+  metadata.gz: 761158fee8d42f919236179a76b90116183afde1cc7e8beb6921c958c27d03c96a6ada9a04abc0959417e34f1ca7677e99b33c00ef38326fe10cf196c0010e4f
+  data.tar.gz: 96f3e592216d1f0fe4bc6274ea92006e8db8fb67d77b31dbe79868175d1a42cfa17145ea9ac981d2ba6aaecf9cf9888260a1a33675f6aa7b735667d275270e23

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,12 @@ 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
@@ -31,6 +37,7 @@ module Lutaml
         @conversion_cache = nil
         @configured = false
         @xml_plan_fast_path = true
+        @xml_plan_ordered_path = false
         @element_order_tracking = true
       end
 

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

@@ -84,6 +84,26 @@ module Lutaml
           @__order_tracking__ ? true : false
         end
 
+        # Whether any writer setter ran on this instance. Parsed
+        # instances start pristine — every set element value is covered
+        # by the parse-built element_order, so ordered serialization
+        # can skip order reconciliation; the first writer-set marks the
+        # instance and reconciliation engages (writer-added values sit
+        # outside the parse order).
+        # @return [Boolean]
+        def mutated_after_parse?
+          @__mutated_after_parse__ ? true : false
+        end
+
+        # Construction-time reset: hydration routes every attribute
+        # through the generated writers (which mark mutations); a
+        # freshly built instance is definitionally not
+        # mutated-after-parse.
+        # @return [void]
+        def clear_mutated_after_parse!
+          @__mutated_after_parse__ = false
+        end
+
         # Record a singular attribute mutation in element_order.
         #
         # No-op unless order tracking is enabled (i.e. the instance was
@@ -102,6 +122,7 @@ module Lutaml
         #   content for content-mapped attributes, ignored otherwise
         # @return [Object] the passed value
         def record_mutation(attribute_name, value = nil)
+          @__mutated_after_parse__ = true
           return value unless @__order_tracking__
 
           track_order(attribute_name, value, nil)
@@ -122,6 +143,7 @@ module Lutaml
         # @param value [Object, nil] The value assigned to the collection
         # @return [Object] the passed value
         def record_mutation_collection(attribute_name, value)
+          @__mutated_after_parse__ = true
           return value unless @__order_tracking__
           return value if value.nil? || Lutaml::Model::Utils.uninitialized?(value)
 

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

@@ -145,7 +145,11 @@ module Lutaml
 
           Lutaml::Xml::Leptris::PlanHydrator.call(self, plan,
                                          plan[:descriptor].walk(root),
-                                         node: root)
+                                         node: root,
+                                         declaration_plan_mode:
+                                           options.fetch(
+                                             :import_declaration_plan, :eager
+                                           ))
         rescue ::Leptris::XML::ParseError => e
           raise Lutaml::Model::InvalidFormatError.new(:xml, e.message)
         end

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

@@ -455,6 +455,7 @@ module Lutaml
             unknown = attrs.keys.find { |k| !known.include?(k.to_sym) }
             raise Error, "unknown attribute '#{unknown}' for #{self}"
           end
+          instance.clear_mutated_after_parse!
           instance
         end
 

data/lib/lutaml/model/type_resolver.rb

@@ -44,7 +44,9 @@ module Lutaml
       # 5. Raise UnknownTypeError if not found anywhere
       #
       # @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 (nil means
+      #   no primary registry and no fallbacks — an id registered in the
+      #   Register namespace but not as a type context)
       # @return [Class] The resolved type class
       # @raise [UnknownTypeError] If type cannot be resolved
       #
@@ -66,11 +68,11 @@ module Lutaml
         type_name = name.to_sym
 
         # 1. Check primary registry
-        type = context.lookup_local(type_name)
+        type = context&.lookup_local(type_name)
         return apply_substitutions(type, context) if type
 
         # 2. Check fallback contexts in order
-        if context.has_fallbacks?
+        if context&.has_fallbacks?
           context.fallback_contexts.each do |fallback_context|
             type = resolve_from_fallback(type_name, fallback_context)
             return apply_substitutions(type, context) if type
@@ -97,8 +99,8 @@ module Lutaml
         # 5. Type not found - raise error
         raise UnknownTypeError.new(
           type_name,
-          context_id: context.id,
-          available_types: available_type_names(context),
+          context_id: context&.id,
+          available_types: context ? available_type_names(context) : [],
         )
       end
 

data/lib/lutaml/model/version.rb

@@ -2,6 +2,6 @@
 
 module Lutaml
   module Model
-    VERSION = "0.8.102"
+    VERSION = "0.8.104"
   end
 end

data/lib/lutaml/xml/adapter/xml_parser.rb

@@ -23,7 +23,7 @@ module Lutaml
           assert_no_truncated_recovered_parse!(parsed)
           root_element = parsed.root
 
-          raise_empty_document_error if root_element.nil?
+          raise_empty_document_error(parsed.parse_errors) if root_element.nil?
 
           root = self::PARSED_ELEMENT_CLASS.new(root_element)
           doc_pis = extract_document_processing_instructions(parsed)
@@ -112,8 +112,11 @@ module Lutaml
           }
         end
 
-        def raise_empty_document_error
+        def raise_empty_document_error(parse_errors = nil)
           message = self::EMPTY_DOCUMENT_ERROR_MESSAGE
+          if parse_errors && !parse_errors.empty?
+            message += " (the XML engine reported: #{parse_errors.join('; ')})"
+          end
 
           case self::EMPTY_DOCUMENT_ERROR_TYPE
           when :parse_exception

data/lib/lutaml/xml/leptris/native_emission.rb

@@ -97,8 +97,8 @@ module Lutaml
                 next unless child_rel
 
                 Array(value).each do |item|
-                  child_plan = nested_plans_for(plan)[item.class] ||
-                    (nested_plans_for(plan)[item.class] =
+                  child_plan = nested_plans_for(plan)[[item.class, rule.name.to_s]] ||
+                    (nested_plans_for(plan)[[item.class, rule.name.to_s]] =
                        PlanCompiler.compile(item.class, register))
                   ops << { kind: :element, plan_index: my_index,
                            row_index: row_index }

data/lib/lutaml/xml/leptris/plan_compiler.rb

@@ -53,6 +53,10 @@ module Lutaml
         # name and wildcard rows carry their own :any.
         ROW_KINDS_NS_UNQUALIFIED = %i[scalar collection nested callback
                                       raw].freeze
+        # Row kinds whose hydration can dispatch per source node —
+        # the only safe claimants of a contested (multi-row) name.
+        PER_NODE_ROW_KINDS = %i[nested ordered_deferred
+                                child_deferred].freeze
 
         class << self
           def compile(model_class, register)
@@ -104,9 +108,23 @@ module Lutaml
 
             mapping = model_class.mappings_for(:xml, register)
             return nil unless compilable_mapping?(mapping)
+            # Ordered/mixed models ride the plan path only when opted
+            # in: the per-node ordered hydration beats 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.
+            if (mapping.ordered? || mapping.mixed_content?) &&
+                !Lutaml::Model::Config.instance.xml_plan_ordered_path
+              return opt_out!(:ordered_opt_in)
+            end
+            # Processing-instruction mappings (rfcxml's <?rfc toc?>)
+            # have no plan-row spelling — the interpretive path owns
+            # them (compiling here silently dropped pi_settings).
+            return opt_out!(:processing_instruction) unless
+              mapping.processing_instruction_mappings.empty?
 
             rows = []
-            attr_rows = [] # [[rule, attr]] hydration metadata
+            attr_rows = [] # [[rule, attr, row_name]] hydration metadata
             plan_attrs = [] # [{name:, kind:}] rows for the engine plan
             compiled = [] # [rule, attr, kind, spelling, delegate_target]
             ns_attr_names = [] # exact-URI attribute rows (ambiguity guard)
@@ -202,28 +220,26 @@ module Lutaml
                 type = attr.type(register)
                 if serializable_type?(type)
                   child = compile(type, register)
-                  return opt_out!(:child_uncompilable) unless child
-
-                  if child[:ordered]
-                    # Ordered/mixed children need element_order on their
-                    # instances; the walk hands back plan values, not
-                    # source nodes, so the subtree defers interpretively
-                    # (the fragment parse runs the full machinery,
-                    # order included).
-                    return opt_out!(:ordered_child_with_ns) if model_ns
-
-                    needs_nodes = true
-                    compiled << [rule, attr, :ordered_deferred, nil,
-                                 delegate_target]
-                    rows << { name: rule.name.to_s, kind: :raw }
-                  else
-                    compiled << [rule, attr, :nested, nil, delegate_target]
-                    needs_nodes ||= child[:needs_nodes]
-                    nested_row = { name: rule.name.to_s, kind: :nested,
-                                   plan: child[:tree] }
-                    nested_row[:ns] = child_ns(rule, model_ns) if rule.namespace_set?
-                    rows << nested_row
+                  if child.nil? &&
+                      !Lutaml::Model::Config.instance.xml_plan_ordered_path
+                    child_mapping = type.mappings_for(:xml, register)
+                    if child_mapping&.ordered? ||
+                        child_mapping&.mixed_content?
+                      # A child refused ONLY by the ordered opt-in gate
+                      # cascades: the bridged-island deferral drops its
+                      # mixed children (customxml schemaRefs), so the
+                      # parent compiles to nil — main's whole-model
+                      # interpretive shape.
+                      return opt_out!(:ordered_opt_in_cascade)
+                    end
                   end
+                  needs_nodes = true if child.nil? || child[:ordered]
+                  compiled_entry, row = child_row_for(rule, attr, type, child,
+                                                      delegate_target,
+                                                      model_ns)
+                  compiled << compiled_entry
+                  needs_nodes ||= child && child[:needs_nodes]
+                  rows << row
                 elsif rule.multiple_mappings?
                   rule.name.each do |spelling|
                     compiled << [rule, attr, :spelling, spelling.to_s,
@@ -271,6 +287,19 @@ module Lutaml
 
             row_tags = partition_row_tags!(compiled, rows, tag)
 
+            # Same-name rows cross-echo in the engine walk: every source
+            # element of a name lands in every row of that name (two
+            # w14:/w15: docId rows each capture both elements). Names
+            # claimed by more than one element row are contested — they
+            # hydrate per source node (the ordered_deferred pattern)
+            # when every claimant is per-node-dispatchable, and opt the
+            # model out otherwise (the interpretive matcher owns the
+            # (URI, local) dispatch there).
+            contested = contested_element_names(rows, compiled)
+            return opt_out!(:contested_names) if contested == :unsafe
+
+            needs_nodes = true unless contested.empty?
+
             # The plan serializer does not emit namespace declarations —
             # namespaced models serialize through the interpretive
             # writer (lutaml-model#847: standalone to_xml under leptris
@@ -354,6 +383,7 @@ module Lutaml
               ordered: mapping.ordered? || mapping.mixed_content?,
               needs_nodes: needs_nodes,
               collection_defaults: collection_defaults,
+              contested_names: contested.empty? ? nil : contested,
               ns_attr_names: ns_attr_names.empty? ? nil : ns_attr_names,
               wildcard_tag: (wildcard_tag if defined?(wildcard_tag)) }
           end
@@ -375,9 +405,19 @@ module Lutaml
                                     attr_local_claims)
             return :non_scalar unless scalar_type?(attr, register)
 
-            attr_rows << [rule, attr]
+            raw_name = rule.name.to_s
+            # W3C-reserved xml:* attributes bind by raw name — the xml
+            # prefix is implicit (never a model namespace), so form
+            # defaults must not qualify them under the model's URI
+            # (w:t's xml:space under a :qualified WML mapping).
+            if raw_name.start_with?("xml:")
+              attr_local_claims[raw_name][:plain] += 1
+              plan_attrs << { name: raw_name }
+              attr_rows << [rule, attr, raw_name]
+              return nil
+            end
             type_ns = attr.type_namespace_class(register)
-            claim = attr_local_claims[rule.name.to_s]
+            raw_name
             if type_ns.nil?
               # attribute_form_default :qualified on the model's
               # namespace qualifies locally-declared attributes under
@@ -389,29 +429,105 @@ module Lutaml
               ns_class = mapping.namespace_class
               if rule.namespace_param != :blank && ns_class &&
                   ns_class.attribute_form_default == :qualified
-                claim[:ns] += 1
-                plan_attrs << { name: rule.name.to_s,
+                row_name = local_attr_name(raw_name)
+                attr_local_claims[row_name][:ns] += 1
+                plan_attrs << { name: row_name,
                                 ns: { exact: ns_class.uri.to_s,
                                       prefix: ns_class.prefix_default&.to_s } }
-                ns_attr_names << rule.name.to_s
+                ns_attr_names << row_name
+                attr_rows << [rule, attr, row_name]
                 return nil
               end
 
-              claim[:plain] += 1
-              plan_attrs << { name: rule.name.to_s }
+              attr_local_claims[raw_name][:plain] += 1
+              plan_attrs << { name: raw_name }
+              attr_rows << [rule, attr, raw_name]
               return nil
             end
             return :attr_type_ns_symbol if type_ns.is_a?(Symbol)
             return :attr_type_ns_aliases unless type_ns.all_uris.size == 1
 
-            claim[:ns] += 1
-            plan_attrs << { name: rule.name.to_s,
+            # Exact-URI rows match the engine's (URI, local) capture by
+            # the LOCAL name — a prefixed rule spelling (xlink:href)
+            # binds its local part under the row's URI. Plain rows keep
+            # the raw name (matches-any-qualification capture). The
+            # claims tally keys by the effective match key so an exact
+            # row and a plain row claiming the same local name still
+            # opt the model out (#758).
+            row_name = local_attr_name(raw_name)
+            attr_local_claims[row_name][:ns] += 1
+            plan_attrs << { name: row_name,
                             ns: { exact: type_ns.uri.to_s,
                                   prefix: type_ns.prefix_default&.to_s } }
-            ns_attr_names << rule.name.to_s
+            ns_attr_names << row_name
+            attr_rows << [rule, attr, row_name]
             nil
           end
 
+          def local_attr_name(name)
+            name.include?(":") ? name.split(":", 2).last : name
+          end
+
+          # Names claimed by more than one element row (engine-row
+          # view; content and wildcard pseudo-rows are exempt). Returns
+          # the contested name list, or :unsafe when any claimant row
+          # cannot dispatch per node — the model then compiles to nil
+          # and the interpretive matcher owns the dispatch.
+          def contested_element_names(rows, compiled)
+            contested = []
+            pseudo_row_kinds = %i[content wildcard].freeze
+            rows.group_by { |r| r[:name] }.each do |name, group|
+              next if group.length < 2 || name.nil?
+              next if group.any? { |r| pseudo_row_kinds.include?(r[:kind]) }
+              # when_attribute partitions route exclusively by engine
+              # predicate (leptris 1.9.221+ #1272) — same-name partition
+              # groups are engine-managed, not cross-echoed.
+              next if group.any? { |r| r[:when] }
+
+              kinds = compiled.filter_map do |rule, _attr, kind, _spelling, _del|
+                next if rule.nil?
+
+                names = rule.name.is_a?(Array) ? rule.name.map(&:to_s) : [rule.name.to_s]
+                kind if names.include?(name)
+              end
+              return :unsafe unless kinds.all? do |k|
+                PER_NODE_ROW_KINDS.include?(k)
+              end
+
+              contested << name
+            end
+            contested
+          end
+
+          # Row entries for a serializable child. Three shapes:          # - nil child (a cyclic graph, or a shape that opted out):
+          #   :child_deferred — the ROW defers per-node instead of
+          #   opting the whole model out; the buckets chain delivers
+          #   source nodes and the interpretive cast runs the full
+          #   machinery on each island. (The whole-model bail here
+          #   cascaded child_uncompilable up entire trees — uniword's
+          #   Run → pict cycle nilled DocumentRoot.)
+          # - ordered child: :ordered_deferred — the per-node plan
+          #   walk + element_order rebuild (PlanOrder) carry the
+          #   namespace context in the child plan's own exact-URI
+          #   rows; nothing is lost under a namespaced parent.
+          # - otherwise: :nested with the child's tree.
+          # Returns [[compiled tuple], tree row].
+          def child_row_for(rule, attr, type, child, delegate_target,
+                            model_ns)
+            if child.nil?
+              [[rule, attr, :child_deferred, nil, delegate_target, type],
+               { name: rule.name.to_s, kind: :raw }]
+            elsif child[:ordered]
+              [[rule, attr, :ordered_deferred, nil, delegate_target, type],
+               { name: rule.name.to_s, kind: :raw }]
+            else
+              row = { name: rule.name.to_s, kind: :nested,
+                      plan: child[:tree] }
+              row[:ns] = child_ns(rule, model_ns) if rule.namespace_set?
+              [[rule, attr, :nested, nil, delegate_target, type], row]
+            end
+          end
+
           def compilable_mapping?(mapping)
             # Mapping's uniform interface: root_mappings defaults to
             # false on the base (KeyValue overrides with its own).