lutaml-model 0.8.102 → 0.8.103

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

@@ -18,12 +18,30 @@ module Lutaml
       # order applier — including its content-attr-first text reads
       # (mutations to the model show up) and CDATA flattening. Models
       # without element_order fall back interpretively (return nil).
+      # Writer-added values the order snapshot does not cover ride the
+      # OrderReconciler: the walk consumes the reconciled order and
+      # unplaceable rules emit appended (the interpretive
+      # apply_remaining_rules contract).
       module PlanSerializer
         SERIALIZABLE_KINDS = %i[scalar collection_native collection_cb
                                 nested ordered_deferred raw content
                                 content_deferred].freeze
+        PLAN_SERIALIZABLE_KINDS = SERIALIZABLE_KINDS
         CONTENT_KINDS = %i[content content_deferred].freeze
 
+        # Reconciler host: the interpretive support modules are written
+        # against the Transformation's combined surface (the reconciler
+        # consumes applier helpers such as find_rule_for_element and
+        # rule_discriminator), so the plan lane drives them through a
+        # dedicated host holding both. The helpers are pure functions
+        # of their arguments — the frozen host carries no state.
+        class ReconcilerHost
+          include(TransformationSupport::OrderedApplier)
+          include(TransformationSupport::OrderReconciler)
+          include(TransformationSupport::SkipLogic)
+        end
+        RECONCILER = ReconcilerHost.new.freeze
+
         class << self
           # plan: the compiler's entry for instance's class
           def call(instance, plan, register = nil)
@@ -55,11 +73,25 @@ module Lutaml
             )
             doc.root = root
             ns_ctx.declare_on(root)
-            if plan[:ordered]
-              build_ordered(root, instance, plan, doc, register)
-            else
-              build(root, instance, plan, doc, register, ns_ctx)
+            # The interpretive writer's raw schemaLocation re-emission
+            # (handle_schema_location): the parse-captured string rides
+            # back as xsi:schemaLocation with its declaration.
+            if instance.is_a?(::Lutaml::Model::Serialize) &&
+                instance.raw_schema_location &&
+                !instance.raw_schema_location.empty?
+              root.set_attribute(
+                "xmlns:xsi", "http://www.w3.org/2001/XMLSchema-instance"
+              )
+              root.set_attribute("xsi:schemaLocation",
+                                 instance.raw_schema_location)
             end
+            built = if plan[:ordered]
+                      build_ordered(root, instance, plan, doc, register, ns_ctx)
+                    else
+                      build(root, instance, plan, doc, register, ns_ctx)
+                    end
+            return nil unless built
+
             doc.to_xml(indent: 2, no_decl: true)
           end
 
@@ -115,6 +147,38 @@ module Lutaml
                 @hoisted[uri] = prefix
                 @forms[uri] = { prefix: prefix, uri: uri }
               end
+              # Format preservation (the interpretive writer's
+              # rule): an instance parsed from a PREFIXED source keeps
+              # its prefixes — the model's own namespace hoists with
+              # the instance's recorded prefix even when the fresh
+              # planner preferred the default-ns format.
+              model_uri = plan[:tree][:ns] && plan[:tree][:ns][:exact]
+              if ns_prefix && !ns_prefix.empty? && model_uri &&
+                  @hoisted.key?(model_uri)
+                @hoisted[model_uri] = ns_prefix
+                @forms[model_uri] = { prefix: ns_prefix, uri: model_uri }
+              end
+              # Source declaration preservation (the interpretive
+              # writer's stored-plan merge): prefixes the parsed source
+              # declared are kept for URIs the document emits. The
+              # planner's class-analysis path has no stored-plan
+              # access, so the merge reads the instance's recorded plan
+              # directly.
+              stored = if instance.is_a?(::Lutaml::Model::Serialize)
+                         instance.import_declaration_plan
+                       end
+              if stored.is_a?(Lutaml::Xml::DeclarationPlan) &&
+                  stored.root_node.is_a?(
+                    Lutaml::Xml::DeclarationPlan::ElementNode,
+                  ) && (ns_prefix.nil? || ns_prefix.empty?)
+                original_uris = stored.original_namespace_uris || {}
+                stored.root_node.hoisted_declarations.each do |prefix, uri|
+                  effective_uri = original_uris[uri] || uri
+                  already = @hoisted.value?(effective_uri) ||
+                    @hoisted.value?(uri)
+                  @hoisted[prefix] = uri if already && !@hoisted.key?(prefix)
+                end
+              end
               collect(plan[:tree])
             end
 
@@ -165,14 +229,18 @@ module Lutaml
               ns_form.is_a?(Hash) ? { prefix: @hoisted[ns_form[:exact]], uri: ns_form[:exact] } : @forms[ns_form]
             end
 
+            # Declaration order matches the interpretive writer: the
+            # prefixed namespaces sorted by prefix, the default
+            # namespace last.
             def declare_on(root, _attr_form_prefix = nil)
-              @hoisted.each do |uri, prefix|
-                key = uri
-                next if key.nil? || @declared[key]
+              @hoisted.sort_by { |_uri, prefix| [prefix ? 0 : 1, prefix.to_s] }
+                .each do |uri, prefix|
+                  key = uri
+                  next if key.nil? || @declared[key]
 
-                @declared[key] = true
-                root.add_namespace_definition(prefix, uri)
-              end
+                  @declared[key] = true
+                  root.add_namespace_definition(prefix, uri)
+                end
             end
           end
 
@@ -181,7 +249,7 @@ module Lutaml
           # plain models through plan rows.
           def serializable?(plan)
             plan[:rows].all? do |_rule, _attr, kind, _sp, _del|
-              SERIALIZABLE_KINDS.include?(kind)
+              PLAN_SERIALIZABLE_KINDS.include?(kind)
             end
           end
 
@@ -231,23 +299,33 @@ module Lutaml
                 end
               when :nested, :ordered_deferred
                 Array(value).each do |item|
-                  child_plan = nested_plans[item.class] ||
-                    (nested_plans[item.class] = PlanCompiler.compile(item.class, reg))
+                  # Keyed by [class, row name]: distinct rows (sz, szCs)
+                  # can share one class with different root names.
+                  child_plan = nested_plans[[item.class, rule.name.to_s]] ||
+                    (nested_plans[[item.class, rule.name.to_s]] = PlanCompiler.compile(item.class, reg))
                   child_ns = child_plan[:tree][:ns] || inherited_ns
+                  # The ROW's wire name wins over the child plan's
+                  # root — distinct rows (sz, szCs) share one class.
                   child = element.create_child(
-                    ns_ctx ? ns_ctx.spell(child_plan[:tree][:name], child_ns) : child_plan[:tree][:name],
+                    ns_ctx ? ns_ctx.spell(row_name(rule, spelling), child_ns) : row_name(rule, spelling),
                   )
                   ns_ctx&.collect(child_plan[:tree])
                   if child_plan[:ordered]
-                    next unless build_ordered(child, item, child_plan,
-                                              doc, reg, ns_ctx, child_ns)
-
+                    build_ordered(child, item, child_plan,
+                                  doc, reg, ns_ctx, child_ns) || return
                   else
-                    build(child, item, child_plan, doc, reg, ns_ctx, child_ns)
+                    build(child, item, child_plan, doc, reg, ns_ctx, child_ns) || return
                   end
                 end
               when :raw
                 Array(value).each { |raw| element.add_child(raw.to_s) }
+              when :child_deferred
+                # A plan-less child carrying a value (a cycle point
+                # with data, e.g. bibliography's Author → author):
+                # the interpretive serializer owns the model — the
+                # plan lane has no faithful spelling for it. Empty
+                # deferred rows ride the fast lane untouched.
+                return nil unless Array(value).empty?
               when :content, :content_deferred
                 Array(value).each { |run| append_text(element, run.to_s, doc) }
               end
@@ -273,30 +351,96 @@ module Lutaml
             plan[:nested_plans] ||= {}
           end
 
+          # The row's exact element URI — the child type's namespace,
+          # the same source the interpretive matcher dispatches by for
+          # (URI, local) element identity. Nil for scalar/raw/content
+          # rows (any-qualification binding). Memoized per plan (rules
+          # are stable per compiled plan).
+          def row_exact_uri(rule, attr, kind, type, reg, plan)
+            return nil unless %i[nested ordered_deferred].include?(kind)
+
+            cache = plan[:row_exact_uris] ||= {}.compare_by_identity
+            return cache[rule] if cache.key?(rule)
+
+            child_type = type || attr.type(reg)
+            child_plan = child_type && PlanCompiler.compile(child_type, reg)
+            tree_ns = child_plan && child_plan[:tree][:ns]
+            cache[rule] = tree_ns.is_a?(Hash) ? tree_ns[:exact] : tree_ns
+          end
+
+          def ordered_layout_for(plan, inherited_ns, ns_index, reg)
+            cache = plan[:ordered_layouts] ||= {}.compare_by_identity
+            return cache[inherited_ns] if cache.key?(inherited_ns)
+
+            rows_by_name = {}
+            name_keys = ::Hash.new { |h, k| h[k] = [] }
+            plan[:rows].each do |rule, attr, kind, spelling, delegate, type|
+              next unless rule.name
+
+              exact = row_exact_uri(rule, attr, kind, type, reg, plan)
+              name = rule.name.to_s
+              key = exact ? [exact, name] : [nil, name]
+              rows_by_name[key] ||= [rule, attr, kind, spelling,
+                                     delegate,
+                                     ns_index ? ns_index[name] || inherited_ns : inherited_ns]
+              name_keys[name] << key
+            end
+            name_keys.default = nil
+            cache[inherited_ns] = [rows_by_name, name_keys]
+          end
+
           # Element_order-driven emission (the interpretive order
           # applier's contract): text runs and comments verbatim, each
           # element entry consuming the next item of its collection
           # (document order). Text reads prefer the content attribute
           # when it lines up with the text-node count, so mutations to
           # the model are reflected; element_order text is the fallback.
-          # PIs drop (interpretive parity). Returns nil when a nested
-          # ordered child lacks element_order (caller falls back).
+          # PIs drop (interpretive parity). A nested ordered instance
+          # without element_order (built by Ruby, not parsed) falls
+          # back to declaration order — the interpretive behavior.
           def build_ordered(element, instance, plan, doc, reg = nil,
-                            ns_ctx = nil, _inherited_ns = nil)
+                            ns_ctx = nil, inherited_ns = nil)
+            if instance.element_order.nil?
+              return build(element, instance, plan, doc, reg, ns_ctx,
+                           inherited_ns)
+            end
+
             reg ||= register
             ns_ctx&.collect(plan[:tree])
             write_attributes(element, instance, plan, reg, ns_ctx)
-            rows_by_name = {}
-            plan[:rows].each do |rule, attr, kind, spelling, delegate|
-              next unless rule.name
-
-              rows_by_name[rule.name.to_s] ||= [rule, attr, kind, spelling,
-                                                delegate]
-            end
+            ns_index = ns_ctx ? ns_index_for(plan) : nil
+            # (URI, local) row keys — the interpretive matcher's
+            # typed-element identity: same-name rows in different
+            # namespaces (w14:docId vs w15:docId) must not share one
+            # dispatch slot. Name-keyed rows (no exact URI) bind any
+            # qualification. The layout is static per (plan, inherited
+            # ns) — the reconciliation corpus re-serializes thousands
+            # of same-shaped paragraphs, so it is memoized.
+            rows_by_name, name_keys =
+              ordered_layout_for(plan, inherited_ns, ns_index, reg)
             content_entry = plan[:rows].find do |rule, _attr, kind, _sp, _del|
               CONTENT_KINDS.include?(kind) && rule.name.nil?
             end
-            order = instance.element_order
+            # Writer-added values sit outside the order snapshot — the
+            # reconciler inserts their entries at the interpretive
+            # anchors and returns the rules it could not place for
+            # appended emission (silent drops are data loss). The
+            # reconciler speaks CompiledRule — the interpretive
+            # transformation's memoized set; the plan's MappingRule
+            # rows cannot drive it. Pristine parsed instances skip the
+            # scan entirely: the parse-built order covers every set
+            # value, and the writer-set flag is the only flow that can
+            # produce deficits.
+            rules = if instance.mutated_after_parse?
+                      compiled_rules_for(instance.class, reg)
+                    end
+            if rules
+              order, fallback_rules =
+                RECONCILER.reconciled_element_order(instance, rules, {})
+            else
+              order = instance.element_order
+              fallback_rules = []
+            end
             element_indices = ::Hash.new(0)
             content_attr = content_entry && content_entry[1]
             content_value = content_attr &&
@@ -330,50 +474,132 @@ module Lutaml
               when "Comment"
                 element.add_child(doc.create_comment(object.text_content))
               when "Element"
-                entry = rows_by_name[object.name]
+                # A uniquely-named row absorbs the entry at any
+                # qualification (the interpretive matcher's lenient
+                # binding — order entries written by consumers carry no
+                # namespace). Contested names dispatch strictly by
+                # (URI, local), falling back to URI-less rows.
+                name = object.name
+                keys = name_keys[name]
+                if keys.length == 1
+                  dispatch_key = keys.first
+                  entry = rows_by_name[dispatch_key]
+                else
+                  dispatch_key = [object.namespace_uri, name]
+                  entry = rows_by_name[dispatch_key]
+                  unless entry
+                    dispatch_key = [nil, name]
+                    entry = rows_by_name[dispatch_key]
+                  end
+                end
                 next unless entry
 
-                _, attr, kind, _spelling, delegate = entry
+                _, attr, kind, _spelling, delegate, row_ns = entry
                 value = value_of(instance, attr, delegate)
                 case kind
                 when :collection_native, :collection_cb
-                  index = element_indices[object.name]
+                  index = element_indices[dispatch_key]
                   items = Array(value)
                   next unless index < items.length
 
-                  element_indices[object.name] += 1
-                  add_leaf(element, object.name,
+                  element_indices[dispatch_key] += 1
+                  add_leaf(element,
+                           ns_ctx ? ns_ctx.spell(object.name, row_ns) : object.name,
                            attr.serialize(items[index], :xml, reg), doc)
                 when :nested, :ordered_deferred
                   item = if attr.collection?
-                           index = element_indices[object.name]
-                           element_indices[object.name] += 1
+                           index = element_indices[dispatch_key]
+                           element_indices[dispatch_key] += 1
                            Array(value)[index]
                          else
                            value
                          end
                   next unless item
 
-                  child_plan = nested_plans_for(plan)[item.class] ||
-                    (nested_plans_for(plan)[item.class] = PlanCompiler.compile(item.class, reg))
-                  child = element.create_child(child_plan[:tree][:name])
+                  child_plan = nested_plans_for(plan)[[item.class, object.name]] ||
+                    (nested_plans_for(plan)[[item.class, object.name]] = PlanCompiler.compile(item.class, reg))
+                  child_ns = child_plan[:tree][:ns] || row_ns || inherited_ns
+                  child = element.create_child(
+                    ns_ctx ? ns_ctx.spell(object.name, child_ns) : object.name,
+                  )
                   if child_plan[:ordered]
                     return nil unless build_ordered(child, item, child_plan,
-                                                    doc, reg)
+                                                    doc, reg, ns_ctx, child_ns)
                   else
-                    build(child, item, child_plan, doc, reg)
+                    build(child, item, child_plan, doc, reg, ns_ctx, child_ns) || return
                   end
                 when :raw
                   element.add_child(value.to_s) unless value.nil?
+                when :child_deferred
+                  # Valued cycle-point children: interpretive lane (see
+                  # build).
+                  return nil unless Array(value).empty?
                 when :scalar
-                  add_leaf(element, object.name,
+                  add_leaf(element,
+                           ns_ctx ? ns_ctx.spell(object.name, row_ns) : object.name,
                            attr.serialize(value, :xml, reg), doc)
                 end
               end
             end
+            return nil if !fallback_rules.empty? &&
+              !emit_uncovered_values(element, instance, plan, fallback_rules,
+                                     doc, reg, ns_ctx, inherited_ns)
+
+            true
+          end
+
+          # OrderReconciler fallback: element rules the reconciled order
+          # could not place but that still hold a value — emit them
+          # appended, the ordinary way (the interpretive
+          # apply_remaining_rules contract for the plan row model).
+          def emit_uncovered_values(element, instance, plan, fallback, doc,
+                                    reg, ns_ctx, inherited_ns)
+            by_attr = {}
+            plan[:rows].each { |row| by_attr[row[1].name] ||= row if row[1] }
+            fallback.each do |rule|
+              entry = by_attr[rule.attribute_name]
+              next unless entry
+
+              _rule, attr, kind, _spelling, delegate, row_ns = entry
+              value = value_of(instance, attr, delegate)
+              name = rule.name.to_s
+              Array(value).each do |item|
+                case kind
+                when :collection_native, :collection_cb, :scalar
+                  add_leaf(element,
+                           ns_ctx ? ns_ctx.spell(name, row_ns) : name,
+                           attr.serialize(item, :xml, reg), doc)
+                when :nested, :ordered_deferred
+                  next if item.nil?
+
+                  child_plan =
+                    nested_plans_for(plan)[[item.class, name]] ||
+                    (nested_plans_for(plan)[[item.class, name]] =
+                       PlanCompiler.compile(item.class, reg))
+                  child_ns = child_plan[:tree][:ns] || row_ns || inherited_ns
+                  child = element.create_child(
+                    ns_ctx ? ns_ctx.spell(name, child_ns) : name,
+                  )
+                  if child_plan[:ordered]
+                    return nil unless build_ordered(child, item, child_plan,
+                                                    doc, reg, ns_ctx, child_ns)
+                  else
+                    built = build(child, item, child_plan, doc, reg, ns_ctx,
+                                  child_ns)
+                    return nil unless built
+                  end
+                end
+              end
+              # Valued cycle-point rows keep the walk's contract.
+              return nil if kind == :child_deferred && !Array(value).empty?
+            end
             true
           end
 
+          def compiled_rules_for(klass, reg)
+            klass.transformation_for(:xml, reg)&.compiled_rules
+          end
+
           # Attributes in document order when the instance recorded it
           # (parsed models), else plan row order.
           def write_attributes(element, instance, plan, reg = nil,
@@ -420,9 +646,10 @@ module Lutaml
                               prefix = nil)
             return unless entry
 
-            _rule, attr, delegate = entry
+            rule, attr, delegate = entry
             value = value_of(instance, attr, delegate)
             return if value.nil?
+            return unless rule.render?(value, instance)
 
             spelled = prefix ? "#{prefix}:#{name}" : name
             element.set_attribute(spelled,

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

@@ -12,7 +12,7 @@ module Lutaml
         class << self
           # Build the plan, walk the document, and hydrate the mapped
           # root. Returns nil when the model is not plan-compilable.
-          def call(model_class, xml, _options = {})
+          def call(model_class, xml, options = {})
             register = Lutaml::Model::Config.default_register
             plan = PlanCompiler.compile(model_class, register)
             return nil unless plan
@@ -23,7 +23,11 @@ module Lutaml
 
             PlanHydrator.call(model_class, plan,
                               plan[:descriptor].walk(root),
-                              node: root)
+                              node: root,
+                              declaration_plan_mode:
+                                options.fetch(
+                                  :import_declaration_plan, :eager
+                                ))
           end
         end
       end

data/spec/lutaml/xml/plan_fast_path_spec.rb

@@ -33,15 +33,18 @@ RSpec.describe "XML plan fast path" do
   around do |example|
     old = Lutaml::Model::Config.instance.xml_plan_fast_path
     Lutaml::Model::Config.instance.xml_plan_fast_path = true
+    Lutaml::Model::Config.instance.xml_plan_ordered_path = true
     example.run
   ensure
     Lutaml::Model::Config.instance.xml_plan_fast_path = old
+    Lutaml::Model::Config.instance.xml_plan_ordered_path = false
   end
 
   # Real-corpus crash (niso-jats): sec-in-sec nesting is a
-  # self-referential model — compile must resolve it to nil instead of
-  # recursing to SystemStackError.
-  it "opts self-referential models out instead of recursing" do
+  # self-referential model — compile must not recurse to
+  # SystemStackError. The cycle point defers the child ROW (per-node
+  # interpretive islands) instead of opting the model out.
+  it "defers the self-referential child row instead of recursing" do
     node = Class.new(Lutaml::Model::Serializable) do
       attribute :text, :string
       xml do
@@ -57,7 +60,9 @@ RSpec.describe "XML plan fast path" do
     end
     stub_const("PlanFastPath::SelfRef", node)
 
-    expect(Lutaml::Xml::Leptris::PlanCompiler.compile(node, :default)).to be_nil
+    plan = Lutaml::Xml::Leptris::PlanCompiler.compile(node, :default)
+    expect(plan).not_to be_nil
+    expect(plan[:rows].map { |r| r[2] }).to include(:child_deferred)
 
     xml = "<n>#{'<n>t</n>' * 200}</n>"
     parsed = node.from_xml(xml)