lutaml-model 0.8.100 → 0.8.114

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

@@ -15,14 +15,23 @@ module Lutaml
       # (their values echo name and type_tag; native collection values
       # echo neither — leptris-ruby#220).
       module PlanHydrator
+        # Row kinds whose child type/plan resolve once per plan (see
+        # child_row_plans).
+        CHILD_ROW_KINDS = %i[nested ordered_deferred].freeze
+
         class << self
-          # plan: the compiler's entry for model_class
+          # plan: the compiled plan entry for model_class
           # value: the walk root PlanValue (element)
           # node: the parsed source element (leptris); ordered/mixed
           #   plans rebuild element_order from it and ordered children
           #   hydrate natively against their own nodes
+          # declaration_plan_mode: mirrors from_xml's
+          #   :import_declaration_plan option (:skip records nothing;
+          #   :lazy is honored as :eager — the lazy variant pins the
+          #   raw engine DOM, the retention the eager default exists
+          #   to avoid)
           def call(model_class, plan, value, parent: nil, node: nil,
-                   register: nil)
+                   register: nil, declaration_plan_mode: :eager)
             # The child model's declared lutaml_default_register takes
             # precedence over the ambient register — the same
             # resolve_for_child contract the interpretive path applies.
@@ -32,9 +41,11 @@ module Lutaml
             register = Lutaml::Model::Register.resolve_for_child(
               model_class, register || Lutaml::Model::Config.default_register
             )
-            buckets = node && plan[:needs_nodes] ? element_buckets(node) : nil
+            buckets = if node && plan[:needs_nodes]
+                        element_buckets(node, plan[:contested_names])
+                      end
             attr_kwargs = attributes_kwargs(plan, value, node)
-            child_kwargs, children, delegates =
+            child_kwargs, children, delegates, run_children =
               children_kwargs(model_class, plan, value, buckets, register)
             plan[:collection_defaults].each do |name|
               next if attr_kwargs.key?(name) || child_kwargs.key?(name)
@@ -44,27 +55,92 @@ module Lutaml
             # TODO.max-perf/33: the bulk constructor — allocate +
             # compiled writers, from_hash semantics — measured ~30x on
             # hydration-heavy corpora versus the generic constructor.
-            instance = model_class.instantiate(attr_kwargs.merge(child_kwargs),
-                                               register)
+            attr_kwargs.update(child_kwargs)
+            instance = model_class.instantiate(attr_kwargs, register)
             instance.lutaml_parent = parent if parent
             instance.lutaml_root ||= parent&.lutaml_root || parent
+            # Root prefix fidelity (the interpretive transform records
+            # it from the source element): prefixed sources keep their
+            # prefixes through the serialize lane's format
+            # preservation.
+            if parent.nil? && node.respond_to?(:prefix) && node.prefix &&
+                !node.prefix.empty?
+              instance.xml_namespace_prefix = node.prefix
+            end
             # #909: order summaries are per-instance pinned records —
             # read-only consumers skip them via the config.
             if node && plan[:ordered] &&
                 Lutaml::Model::Config.instance.element_order_tracking
               instance.element_order = PlanOrder.build(node)
             end
+            # Root declaration-plan parity (the interpretive
+            # transform's eager mode): consumers and the interpretive
+            # serialize fallback read import_declaration_plan state —
+            # plan-hydrated roots must carry the same in-scope xmlns
+            # declarations or round-trips drop them (#872). The root's
+            # xsi:schemaLocation rides the same state (the
+            # interpretive set_schema_location contract).
+            if parent.nil? && node
+              record_declaration_plan(instance, node, model_class) if declaration_plan_mode != :skip
+              record_schema_location(instance, node)
+            end
             children.each do |child|
               child.lutaml_parent = instance
               child.lutaml_root ||= instance.lutaml_root || instance
             end
-            interpret_deferred(model_class, plan, value, instance, node, buckets)
+            interpret_deferred(model_class, plan, value, instance, node,
+                               buckets, run_children)
             route_delegates(delegates, instance)
             instance
           end
 
           private
 
+          def record_declaration_plan(instance, node, model_class)
+            ns_data = collect_native_namespaces(node)
+            return if ns_data.empty?
+
+            plan = Lutaml::Xml::DeclarationPlan.from_input_with_locations(
+              ns_data, model_class.mappings_for(:xml)
+            )
+            instance.import_declaration_plan = plan if plan
+          end
+
+          # The interpretive parse stores the root's xsi:schemaLocation
+          # verbatim (set_schema_location); the writer re-emits it.
+          def record_schema_location(instance, node)
+            schema_loc = node.attributes.each_value.find do |a|
+              a.name.to_s.split(":", 2).last == "schemaLocation"
+            end
+            instance.raw_schema_location = schema_loc.value if schema_loc
+          end
+
+          # Same ns_data shape as ModelTransform.collect_element_namespaces,
+          # collected straight off the engine nodes — no wrapper tree.
+          # Iterates children with an inline element filter:
+          # element_children materializes a filtered array per node,
+          # which the niso allocation gate caught at scale.
+          def collect_native_namespaces(element, path = [], result = {})
+            own = element.namespace_definitions
+            unless own.empty?
+              namespaces = {}
+              own.each do |ns|
+                key = ns.prefix || :default
+                namespaces[key] = { uri: ns.href, prefix: ns.prefix,
+                                    format: ns.prefix ? :prefix : :default }
+              end
+              result[path.dup] = namespaces
+            end
+            element.children.each do |child|
+              next unless child.is_a?(::Leptris::XML::Element)
+
+              path.push(child.name)
+              collect_native_namespaces(child, path, result)
+              path.pop
+            end
+            result
+          end
+
           def register
             Lutaml::Model::Config.default_register
           end
@@ -73,8 +149,12 @@ module Lutaml
             kwargs = {}
             sole_claimants = sole_claimant_names(plan)
             ns_attr_names = plan[:ns_attr_names]
-            plan_attr_rows(plan).each do |rule, attr, name|
-              v = value.attribute(name)
+            rows = plan_attr_rows(plan)
+            # #1670 batch face (leptris 1.9.351.1): one FFI crossing
+            # per node instead of one per (node x attribute name).
+            bound = value.attributes_snapshot
+            rows.each do |rule, attr, name|
+              v = bound[name]
               if v.nil? && node && sole_claimants.include?(name)
                 # #754/#790 parity: a sole-claimant attribute rule binds
                 # any qualification (the interpretive matcher's lenient
@@ -152,8 +232,8 @@ module Lutaml
           # hydration allocated two or three strings per attribute row
           # per instance.
           def plan_attr_rows(plan)
-            plan[:attr_row_names] ||= plan[:attr_rows].map do |rule, attr|
-              [rule, attr, rule.name.to_s]
+            plan[:attr_row_names] ||= plan[:attr_rows].map do |rule, attr, row_name|
+              [rule, attr, row_name || rule.name.to_s]
             end
           end
 
@@ -164,7 +244,8 @@ module Lutaml
           def children_kwargs(_model_class, plan, value, buckets = nil,
                               register = nil)
             register ||= Lutaml::Model::Config.default_register
-            grouped, tagged = group_children(value, plan[:row_tags])
+            grouped, tagged, run_children = group_children(value,
+                                                           plan[:row_tags])
             buckets = nil unless buckets && plan[:needs_nodes]
             kwargs = {}
             children = []
@@ -173,8 +254,21 @@ module Lutaml
             # the block-backed Hash is a fresh object per hydrated row.
             spellings = nil
             row_tags = plan[:row_tags]
-            plan[:rows].each_with_index do |(rule, attr, kind, spelling, delegate), idx|
+            wire_names = row_wire_names(plan)
+            row_memo = child_row_plans(plan, register)
+            # Array#each with a top-of-loop counter: each_with_index
+            # mints an enumerator per hydrated node — 14.7K allocations
+            # per parse on the pnas guardrail — and next must keep its
+            # continue semantics.
+            rows = plan[:rows]
+            idx = -1
+            # rubocop:disable Metrics/BlockLength -- one row-kind
+            # dispatch table; splitting it would scatter the contract
+            rows.each do |row|
+              idx += 1
+              rule, attr, kind, spelling, delegate, _row_type = row
               tag = row_tags&.[](idx)
+              name = wire_names[idx]
               case kind
               when :scalar
                 # Raw passthrough: the model constructor is the single
@@ -192,7 +286,7 @@ module Lutaml
                   first = if tag
                             tagged[tag]&.first
                           else
-                            grouped.dig(rule.name.to_s, 0)
+                            grouped.dig(name, 0)
                           end
                   v = first&.string_value
                   v = mapped_empty_value(rule) if v.nil? && first
@@ -204,7 +298,7 @@ module Lutaml
               when :wildcard_any
                 # interpreted post-instance (interpret_deferred)
               when :content
-                runs = content_runs(value)
+                runs = content_runs(value, run_children)
                 if runs.empty? && !attr.collection?
                   # An empty element's content binds through the rule's
                   # value map for scalar content attributes: "" for the
@@ -220,13 +314,13 @@ module Lutaml
                 # walk against its own node + element_order from the
                 # node's children. Without one (direct PlanHydrator
                 # use), the subtree fragment-parses interpretively.
-                if buckets
-                  child_type = attr.type(register)
-                  child_plan = PlanCompiler.compile(child_type, register)
-                  items = buckets.fetch(rule.name.to_s, []).map do |n|
+                if buckets && row_memo[idx]
+                  child_type, child_plan, child_register, contested = row_memo[idx]
+                  selected = child_selection(buckets, name, child_plan, contested)
+                  items = (selected || []).map do |n|
                     call(child_type, child_plan,
                          child_plan[:descriptor].walk(n), node: n,
-                                                          register: register)
+                                                          register: child_register)
                   end
                   unless items.empty?
                     children.concat(items)
@@ -234,8 +328,28 @@ module Lutaml
                            attr.collection? ? items : items.first)
                   end
                 end
+              when :child_deferred
+                # Uncompilable child (cycles, opted-out shapes): each
+                # source node casts through the attribute — the full
+                # interpretive machinery on the bridged island,
+                # identical semantics to the interpretive path.
+                contested_uri = if plan[:contested_names]&.include?(name)
+                                  child_type_uri(attr, register)
+                                end
+                elements = deferred_elements(value, name, buckets,
+                                             contested_uri)
+                next if elements.empty?
+
+                results = elements.map do |element|
+                  attr.cast(element, :xml, register)
+                end
+                unless results.empty?
+                  children.concat(results)
+                  assign(kwargs, delegates, delegate, rule, attr,
+                         attr.collection? ? results : results.first)
+                end
               when :collection_cb
-                values = grouped[rule.name.to_s].to_a.map do |item|
+                values = grouped[name].to_a.map do |item|
                   item&.string_value
                 end
                 values = mapped_capture_values(values, rule)
@@ -249,7 +363,7 @@ module Lutaml
                 values = if tag
                            tagged[tag].to_a.map(&:string_value)
                          else
-                           native_collection(value, rule.name.to_s)
+                           native_collection(value, name)
                          end
                 values = mapped_capture_values(values, rule) unless values.nil?
                 unless values.nil?
@@ -259,16 +373,34 @@ module Lutaml
                 spellings ||= Hash.new { |h, k| h[k] = [] }
                 spellings[[rule, attr]] << grouped[spelling.to_s].to_a
               when :nested
-                child_type = attr.type(register)
-                child_plan = PlanCompiler.compile(child_type, register)
-                cursor = if child_plan[:needs_nodes] && buckets
-                           buckets.fetch(rule.name.to_s, [])
-                         end
-                items = grouped.fetch(rule.name.to_s, []).each_with_index
-                  .map do |v, i|
-                    call(child_type, child_plan, v,
-                         node: cursor && cursor[i], register: register)
+                child_type, child_plan, child_register, contested = row_memo[idx]
+                selected = child_selection(buckets, name, child_plan, contested)
+                if selected && contested
+                  # Contested name: the walk's grouped values cross-echo
+                  # every same-name element into every row — dispatch
+                  # per source node instead (the walk is row-scoped).
+                  items = selected.map do |n|
+                    call(child_type, child_plan,
+                         child_plan[:descriptor].walk(n), node: n,
+                                                          register: child_register)
                   end
+                else
+                  values = grouped.fetch(name, [])
+                  cursor = if child_plan[:needs_nodes] && buckets
+                             selected
+                           end
+                  # Indexed loop: each_with_index.map mints an
+                  # enumerator per node with nested rows.
+                  count = values.size
+                  items = Array.new(count)
+                  pos = 0
+                  while pos < count
+                    items[pos] = call(child_type, child_plan, values[pos],
+                                      node: cursor && cursor[pos],
+                                      register: child_register)
+                    pos += 1
+                  end
+                end
                 next if items.empty?
 
                 children.concat(items)
@@ -276,6 +408,7 @@ module Lutaml
                        attr.collection? ? items : items.first)
               end
             end
+            # rubocop:enable Metrics/BlockLength
             unless !spellings || spellings.empty?
               spellings.each do |(rule, attr), groups|
                 # Interpretive order for shared-attribute groups is
@@ -289,7 +422,7 @@ module Lutaml
                        attr.collection? ? values : values.first)
               end
             end
-            [kwargs, children, delegates]
+            [kwargs, children, delegates, run_children]
           end
 
           # Deferred islands: raw subtrees become wrapper elements via a
@@ -300,11 +433,20 @@ module Lutaml
           # node (no fragment parse — the reparse dominated deferred
           # hydration). Ordered children only land here without a node.
           def interpret_deferred(model_class, plan, value, instance, node = nil,
-                                 buckets = nil)
-            plan[:rows].each do |rule, attr, kind, _spelling, _delegate|
+                                 buckets = nil, run_children = nil)
+            # Array#each + top counter: no per-node enumerator (see
+            # children_kwargs).
+            rows = plan[:rows]
+            idx = -1
+            rows.each do |row|
+              idx += 1
+              rule = row[0]
+              attr = row[1]
+              kind = row[2]
+              wire_name = row_wire_names(plan)[idx]
               case kind
               when :content_deferred
-                runs = content_runs(value)
+                runs = content_runs(value, run_children)
                 if runs.empty?
                   # The interpretive pipeline classifies the raw ""
                   # through the rule's value map: the :empty directive
@@ -327,13 +469,13 @@ module Lutaml
                 # concatenated).
                 instance.public_send(:"#{attr.name}=", runs.join)
               when :raw
-                raws = raw_strings(value, rule)
+                raws = raw_strings(value, wire_name)
                 next if raws.empty?
 
                 instance.public_send(:"#{attr.name}=",
                                      attr.collection? ? raws : raws.first)
               when :custom_method
-                elements = deferred_elements(value, rule, buckets)
+                elements = deferred_elements(value, wire_name, buckets)
                 next if elements.empty?
 
                 args = attr.collection? ? elements : elements.first
@@ -343,7 +485,7 @@ module Lutaml
               when :ordered_deferred
                 next if node # hydrated natively in children_kwargs
 
-                results = deferred_elements(value, rule, buckets).map do |element|
+                results = deferred_elements(value, wire_name, buckets).map do |element|
                   attr.cast(element, :xml, register,
                             lutaml_parent: instance,
                             lutaml_root: instance.lutaml_root || instance)
@@ -386,7 +528,7 @@ module Lutaml
                   attr.collection? ? results : results.first,
                 )
               when :polymorphic
-                results = deferred_elements(value, rule, buckets).map do |element|
+                results = deferred_elements(value, wire_name, buckets).map do |element|
                   attr.cast(element, :xml, register,
                             polymorphic: rule.polymorphic,
                             lutaml_parent: instance,
@@ -405,11 +547,30 @@ module Lutaml
           # construction only, no parse), falling back to a fragment
           # parse of the captured subtree when no node is available.
           # Both lists are document-ordered for the row's name.
-          def deferred_elements(value, rule, buckets)
-            nodes = buckets && buckets[rule.name.to_s]
-            return nodes.map { |n| bridge_element(n) } if nodes
+          def deferred_elements(value, name, buckets, contested_uri = nil)
+            return raw_strings(value, name).map { |raw| fragment_element(raw) } unless buckets
+
+            nodes = buckets[name]
+            return [] unless nodes
+
+            if contested_uri
+              # Contested name: bind only the (URI, local) matches —
+              # the type's own mapping namespace is the row identity.
+              nodes = buckets[[contested_uri, name]] || []
+            end
+            nodes.map { |n| bridge_element(n) }
+          end
+
+          def child_type_uri(attr, register)
+            type = attr.type(register)
+            return nil unless type.is_a?(Class) &&
+              type.include?(::Lutaml::Model::Serialize)
 
-            raw_strings(value, rule).map { |raw| fragment_element(raw) }
+            type.mappings_for(:xml, register)&.namespace_uri
+          end
+
+          def contested_name?(plan, rule)
+            plan[:contested_names]&.include?(rule.name.to_s) || false
           end
 
           def bridge_element(node)
@@ -451,15 +612,14 @@ module Lutaml
             end
           end
 
-          def content_runs(value)
-            out = []
-            value.count.times do |i|
-              c = value.at(i)
-              next unless c.name.nil? && c.kind == :collection
-
-              out.concat(Array.new(c.count) { |j| c.at(j).string_value })
+          # Content runs ride the children snapshot: the nil-name
+          # entries ARE the :collection run groups (one crossing per
+          # node via group_children, none here). The per-group
+          # at/count crossings are the drain itself.
+          def content_runs(_value, run_children)
+            (run_children || []).flat_map do |group|
+              Array.new(group.count) { |j| group.at(j).string_value }
             end
-            out
           end
 
           # Native collection rows echo their producing row's name
@@ -474,11 +634,11 @@ module Lutaml
             nil
           end
 
-          def raw_strings(value, rule)
+          def raw_strings(value, name)
             out = []
             value.count.times do |idx|
               child = value.at(idx)
-              if child.name == rule.name.to_s && child.kind == :raw
+              if child.name == name && child.kind == :raw
                 out << child.string_value
               end
             end
@@ -499,7 +659,7 @@ module Lutaml
             # Frozen with the plan: recomputing the tally per hydration
             # showed in the #876-era profile as Enumerable#find/tally churn.
             plan[:sole_claimants] ||= plan[:attr_rows]
-              .map { |rule, _attr| rule.name.to_s }.tally
+              .map { |rule, _attr, row_name| row_name || rule.name.to_s }.tally
               .select { |_n, c| c == 1 }.keys
           end
 
@@ -527,8 +687,14 @@ module Lutaml
             grouped = {}
             want_tags = !row_tags.nil?
             tagged = want_tags ? {} : nil
+            run_children = nil
             names.each_with_index do |name, i|
-              next if name.nil? # content runs, read separately
+              if name.nil?
+                # Content runs: same snapshot pass — at()/count() per
+                # child cost a crossing and a wrapper each.
+                (run_children ||= []) << children[i]
+                next
+              end
 
               child = children[i]
               (grouped[name] ||= []) << child
@@ -536,7 +702,7 @@ module Lutaml
                 (tagged[tags[i]] ||= []) << child
               end
             end
-            [grouped, tagged]
+            [grouped, tagged, run_children]
           end
 
           # Element children bucketed by local name, document order
@@ -544,15 +710,67 @@ module Lutaml
           # ordered-child hydration. Only built when the plan's subtree
           # needs source nodes; namespace-qualified models never get
           # here (the compiler keeps them interpretive).
-          def element_buckets(node)
+          # Contested names need (URI, local) node buckets; every other
+          # plan hydrates from the name view alone — the qualified keys
+          # are one array + hash write per child and measured as an
+          # allocation regression on element-heavy corpora (niso gate).
+          def element_buckets(node, contested_names = nil) 
             buckets = {}
+            qualified = contested_names && !contested_names.empty?
             node.children.each do |child|
               next unless child.is_a?(::Leptris::XML::Element)
 
-              (buckets[child.name] ||= []) << child
+              name = child.name
+              (buckets[name] ||= []) << child
+              if qualified
+                uri = child.namespace&.href
+                (buckets[[uri, name]] ||= []) << child if uri
+              end
             end
             buckets
           end
+
+          # Selected source nodes for a child row: contested names
+          # dispatch by (URI, local); every other row binds the whole
+          # name bucket leniently (any qualification). The pair form
+          # this replaces allocated a fresh array per row per node on
+          # the ordered walk (niso gate).
+          def child_selection(buckets, name, child_plan, contested)
+            all = buckets && buckets[name]
+            return all unless buckets && all && contested
+
+            tree_ns = child_plan[:tree][:ns]
+            exact_uri = tree_ns.is_a?(Hash) ? tree_ns[:exact] : tree_ns
+            exact_uri ? (buckets[[exact_uri, name]] || []) : all
+          end
+
+          # Per-(plan, register) child-row tuples, computed once and
+          # reused across every node the walk hands this plan: the
+          # per-node type lookup, compile hit, child register
+          # resolution, and contested flag were each a measurable slice
+          # of the ordered-lane allocation profile (niso gate).
+          def child_row_plans(plan, register)
+            plan[:child_row_memo] ||= {}
+            plan[:child_row_memo][register] ||= plan[:rows].map do |rule, attr, kind, _spelling, _delegate, row_type|
+              next nil unless CHILD_ROW_KINDS.include?(kind)
+
+              child_type = row_type || attr.type(register)
+              child_plan = PlanCompiler.compile(child_type, register)
+              child_register = Lutaml::Model::Register.resolve_for_child(
+                child_type, register
+              )
+              [child_type, child_plan, child_register,
+               contested_name?(plan, rule)]
+            end
+          end
+
+          # Plan-frozen wire names: rule.name.to_s minted a fresh string
+          # per row per node in the hot loop.
+          def row_wire_names(plan)
+            plan[:row_wire_names] ||= plan[:rows].map do |rule, _attr, _kind, _spelling, _delegate, _row_type|
+              rule.name.to_s
+            end
+          end
         end
       end
     end