lutaml-model 0.8.100 → 0.8.119

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

@@ -0,0 +1,187 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Xml
+    module Leptris
+      # The native emission lane of the plan fast path: instead of
+      # minting the output DOM node-by-node through the Ruby
+      # create_child chain, build a plan RESULT from ops
+      # (leptris_plan_result_build), render it through the engine's
+      # plan serializer, reparse the compact output, and write it with
+      # the engine's indented document writer. Both renderings are
+      # pure C; measured 2.4x faster than the DOM-mint loop on the
+      # 500-row audit at a modest allocation increase.
+      #
+      # Byte-parity with the DOM lane holds because both lanes end at
+      # the same document writer over structurally identical
+      # documents: the compact emission escapes exactly as the DOM
+      # text nodes do, and reparsing yields one text node per leaf,
+      # matching the minted tree. The reparse is an engine-internal
+      # cost, not a Ruby one.
+      #
+      # Emission is enabled for the provably static subset: trees with
+      # no namespace form anywhere (every spelling is the unwritten
+      # local name, nothing to declare, no instance-dependent
+      # prefix/default flips) and the non-ordered build() shapes
+      # (attributes, scalars, collections, nested models). Wildcard,
+      # raw, callback, and content rows and ordered models keep the
+      # DOM lane — their emission shapes are not expressible as ops
+      # (or not verified to be) and the DOM lane is byte-exact.
+      module NativeEmission
+        ROOT_ROW = 0xFFFF_FFFF
+        EMITTABLE_KINDS = %i[scalar collection nested].freeze
+
+        class << self
+          def compatible?(plan)
+            !plan[:ordered] && tree_emittable?(plan[:tree])
+          end
+
+          # Pre-order depth-first, children in row order — the same
+          # walk Descriptor.flatten_plan performs, so the plan_index
+          # counters here match the engine's flattened plans array.
+          def tree_emittable?(tree)
+            return false if tree[:ns]
+            return false if (tree[:attributes] || []).any? { |a| a[:ns].is_a?(Hash) }
+
+            (tree[:children] || []).all? do |row|
+              EMITTABLE_KINDS.include?(row[:kind]) &&
+                (row[:kind] != :nested || !row[:plan] || tree_emittable?(row[:plan]))
+            end
+          end
+
+          def emit(instance, plan, register)
+            ops = [{ kind: :element, row_index: ROOT_ROW }]
+            emit_element(ops, instance, plan, register, 0)
+            ops << { kind: :end }
+            compact = plan[:descriptor].serialize(
+              plan[:descriptor].build_result(ops),
+            )
+            ::Leptris::XML.parse(compact).to_xml(indent: 2, no_decl: true)
+          end
+
+          private
+
+          # plan_index: this plan's flattened index. The engine's
+          # flatten_plan pushes each nested row's child plan exactly
+          # once — collection members share that slot — so child flat
+          # indices come from a static per-plan layout (relative to
+          # this plan's index), never from a runtime counter.
+          def emit_element(ops, instance, plan, register, plan_index)
+            my_index = plan_index
+            layout = flat_layout_for(plan)
+
+            emit_attributes(ops, instance, plan, my_index, register)
+
+            plan[:rows].each_with_index do |(rule, attr, kind, _spelling, delegate), row_index|
+              value = value_of(instance, attr, delegate)
+              next unless rule.render?(value, instance)
+
+              case kind
+              when :scalar
+                # Multi-capture parity: an attribute that collected
+                # several occurrences serializes one element per item,
+                # as the DOM lane does.
+                if value.is_a?(::Array)
+                  value.each do |item|
+                    ops << scalar_op(my_index, row_index, attr, item, register)
+                  end
+                else
+                  ops << scalar_op(my_index, row_index, attr, value, register)
+                end
+              when :collection_native, :collection_cb
+                Array(value).each do |item|
+                  ops << scalar_op(my_index, row_index, attr, item, register)
+                end
+              when :nested
+                _tree, child_rel = layout[row_index]
+                next unless child_rel
+
+                Array(value).each do |item|
+                  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 }
+                  emit_element(ops, item, child_plan,
+                               register, my_index + child_rel)
+                  ops << { kind: :end }
+                end
+              end
+            end
+          end
+
+          # {nested row_index => [child tree, relative flat index]} —
+          # children of this plan occupy slots my_index+1 .. in row
+          # order, each nested row's subtree sized once.
+          def flat_layout_for(plan)
+            plan[:flat_layout] ||= begin
+              layout = {}
+              rel = 1
+              (plan[:tree][:children] || []).each_with_index do |row, i|
+                next unless row[:kind] == :nested && row[:plan]
+
+                layout[i] = [row[:plan], rel]
+                rel += subtree_size(row[:plan])
+              end
+              layout
+            end
+          end
+
+          def subtree_size(tree)
+            1 + (tree[:children] || []).sum do |row|
+              row[:kind] == :nested && row[:plan] ? subtree_size(row[:plan]) : 0
+            end
+          end
+
+          def emit_attributes(ops, instance, plan, plan_index, register)
+            recorded = instance.attribute_order
+            attr_rows = plan[:attr_rows]
+            if recorded && !recorded.empty?
+              by_name = {}
+              attr_rows.each { |rule, attr, _sp, delegate| by_name[rule.name.to_s] = [rule, attr, delegate] }
+              names = recorded | attr_rows.map { |rule, _a, _s, _d| rule.name.to_s }
+            else
+              names = attr_rows.map { |rule, _a, _s, _d| rule.name.to_s }
+              by_name = {}
+              attr_rows.each { |rule, attr, _sp, delegate| by_name[rule.name.to_s] = [rule, attr, delegate] }
+            end
+            tree_attrs = plan[:tree][:attributes] || []
+            names.each do |name|
+              entry = by_name[name]
+              next unless entry
+
+              _rule, attr, delegate = entry
+              value = value_of(instance, attr, delegate)
+              next if value.nil?
+
+              row_index = tree_attrs.index { |a| a[:name] == name }
+              next unless row_index
+
+              ops << { kind: :attr, plan_index: plan_index,
+                       row_index: row_index, name: name,
+                       value: attr.serialize(value, :xml, register).to_s }
+            end
+          end
+
+          def scalar_op(plan_index, row_index, attr, value, register)
+            { kind: :scalar, plan_index: plan_index, row_index: row_index,
+              value: attr.serialize(value, :xml, register).to_s }
+          end
+
+          def value_of(instance, attr, delegate)
+            if delegate
+              target = instance.public_send(delegate)
+              target&.public_send(attr.name)
+            else
+              instance.public_send(attr.name)
+            end
+          end
+
+          def nested_plans_for(plan)
+            plan[:nested_plans] ||= {}
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -53,12 +53,16 @@ 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)
-            # Version gate, not a capability probe: the plan path needs
-            # leptris >= 1.9.273.0 (the child-handles snapshot). Older
-            # gems take the interpretive path via the nil opt-out.
+            # Version gate: below MIN_LEPTRIS_VERSION (the single
+            # capability floor) gems take the interpretive path via
+            # the nil opt-out.
             return nil unless Leptris.plan_path_compatible?
 
             # A child model's declared lutaml_default_register takes
@@ -96,58 +100,31 @@ module Lutaml
             end
           end
 
-          # Two engine walk defects gate walk-side consumers here; both
-          # bail models to the interpretive matcher, whose exact-first-
-          # then-any-qualification precedence binds what the walk drops.
-          # The serialize side (PlanSerializer) reads the Ruby tree and
-          # stays on the fast path. leptris 1.9.320.0 (#1587) fixes
-          # both defects — the scan is skipped there and every model
-          # rides the walk again.
-          #
-          # leptris#1585: exact-URI CHILD-row ns_uri strings are not
-          # retained engine-side — once the build anchors are GC'd (a
-          # warm walk plus one GC suffices), those rows stop matching
-          # and hydration silently answers nil.
-          #
-          # leptris#1586: plain attribute rows do not leniently match
-          # namespace-qualified wire attributes (uniword fontTable:
-          # every w:name/w:val against a plain attr row hydrates nil).
-          # A plan level carrying plain attr rows under a namespaced
-          # chain therefore cannot be trusted on the walk; attribute
-          # rows with an exact URI (or :any) and plans without any
-          # namespace form are unaffected.
-          def engine_walk_safe?(plan)
-            return true if Leptris.walk_ns_safety_compatible?
-
-            tree_safe?(plan[:tree], false)
-          end
-
           private
 
-          def tree_safe?(tree, ancestor_ns)
-            namespaced = ancestor_ns || tree[:ns].is_a?(Hash)
-            attrs = tree[:attributes] || []
-            return false if namespaced &&
-              attrs.any? { |a| !a[:ns].is_a?(Hash) && a[:ns] != :any }
-
-            (tree[:children] || []).all? do |row|
-              return false if row[:ns].is_a?(Hash)
-
-              next true unless row[:kind] == :nested && row[:plan]
-
-              tree_safe?(row[:plan], namespaced)
-            end
-          end
-
           def build(model_class, register)
             return nil unless model_class.is_a?(Class) &&
               model_class.include?(::Lutaml::Model::Serialize)
 
             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)
@@ -243,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,
@@ -312,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
@@ -335,13 +323,13 @@ module Lutaml
             flags << :ns_lenient
 
             # Namespace-less model child rows bind the strict unwritten
-            # spelling (bare, or inherited default xmlns) on engines
-            # with the leptris#1560 :unqualified form — the interpretive
-            # matcher's exact no-namespace semantic, refusing prefixed
-            # spellings where the ns_lenient superset bound them.
-            # Rows with an explicit form (rule ns, type ns, :none, :any)
-            # are untouched; name-matched element row kinds only.
-            if model_ns.nil? && Leptris.ns_unqualified_rows_compatible?
+            # spelling (bare, or inherited default xmlns) — the
+            # interpretive matcher's exact no-namespace semantic,
+            # refusing prefixed spellings where the ns_lenient
+            # superset bound them. Rows with an explicit form (rule ns,
+            # type ns, :none, :any) are untouched; name-matched element
+            # row kinds only.
+            if model_ns.nil?
               rows.each do |r|
                 next if r[:ns]
 
@@ -373,14 +361,6 @@ module Lutaml
             # must receive one through the buckets chain.
             needs_nodes = true unless ns_attr_names.empty?
 
-            # A model combining exact-URI attribute rows with nested
-            # child rows needs the walk's nested attribute capture
-            # (leptris#1563, fixed 1.9.313.0): older engines drop the
-            # children's attribute capture under such plans, so they
-            # stay interpretive. Leaf models are unaffected.
-            return opt_out!(:attr_type_ns_nested) if plan_attrs.any? { |a| a[:ns] } &&
-              rows.any? && !Leptris.nested_attr_capture_compatible?
-
             # The catch-all row: kind :wildcard with an explicit :any ns
             # form (pad0) — the two-pass walk routes every child no
             # named row claimed here, tagged for hydrator routing.
@@ -403,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
@@ -424,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
@@ -438,39 +429,108 @@ 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 Leptris.attr_ns_rows_compatible? &&
-              type_ns.all_uris.size == 1
-
-            claim[:ns] += 1
-            plan_attrs << { name: rule.name.to_s,
+            return :attr_type_ns_aliases unless type_ns.all_uris.size == 1
+
+            # 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).
-            # The map_any_element catch-all rides the engine's wildcard
-            # row (leptris#1552, named rows take precedence); engines
-            # without the kind keep the interpretive refusal.
-            return false if mapping.any_element_rule &&
-              !Leptris.wildcard_rows_compatible?
-
             mapping.root_element && !mapping.root_mappings?
           end
 
@@ -548,8 +608,7 @@ module Lutaml
             type_ns = attr.type_namespace_class(register)
             return nil if type_ns.nil? || type_ns == :inherit
             return :bail_symbol if type_ns.is_a?(Symbol)
-            return :bail_aliases unless Leptris.attr_ns_rows_compatible? &&
-              type_ns.all_uris.size == 1
+            return :bail_aliases unless type_ns.all_uris.size == 1
 
             form = { exact: type_ns.uri.to_s,
                      prefix: type_ns.prefix_default&.to_s }