lutaml-model 0.8.47 → 0.8.49

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c4ba22dbb3a53b5ba0cdb11840f7940507da76da3d3b7b3ccd64e52f597bdfe1
-  data.tar.gz: '09d45f38541abb51224c9af9a4aff11d3207a99c4c9f79206cc0a6041caa382e'
+  metadata.gz: 2dab1dcbc2ea77cfd1c61d9ffba4717521b9e97e1f3f6c8dd6f9ce6c7014222f
+  data.tar.gz: ed16efadd94ce85b9e52a5c7de822f9c7de7e3c581203280120630e8cdb389ff
 SHA512:
-  metadata.gz: 2a9fa0ec81775e5b928dbeb8d75b8b812d8e00c076176c1f6367e024d0bd85fd10ea27b3361160211dc47d275edff90b6d569e2ebf87b63a2f8bbba1ebf12024
-  data.tar.gz: '089b06566a9ec168c0491b7c584e95e68dc0bcb2c219b8932062aa3b33c3e5d696445e26782107c292c405cdead641ba33ad6571ac31f59403b2ac90d5f9a71d'
+  metadata.gz: cd6bbdebb2c812eb849774ac168fe2c194bc21113521be6b4ca8b389ab5f6ebb2743b951478077332a18a2c214f458962c0a89d54e1a26447b3b103b7c2bb153
+  data.tar.gz: fddad44bad334a640facc5f6869b91c2a12134da6c79e58b7bed1787e14c03702d5ffd0ffcece27e435fe2f9387a7d13040e45794d178424cd7e56acbf9bb36c

data/.github/workflows/performance.yml

@@ -55,4 +55,50 @@ jobs:
         run: rake vendor:compile
 
       - name: Run performance benchmarks
-        run: bundle exec rake performance:compare
+        run: bundle exec rake performance:compare
+  # TODO.max-perf/36: YJIT moves exactly the interpretive paths the
+  # model layer still runs. Sequential off/on probes on one runner give
+  # a directly comparable pair per commit - a measurement leg, not a
+  # gate. The plan fast path shrinks the YJIT win; watch both.
+  performance-yjit:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          submodules: "recursive"
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.4'
+          bundler-cache: false
+
+      - name: Install ragel
+        run: sudo apt-get update && sudo apt-get install -y ragel
+
+      - name: Install ruby-ll (for rake vendor:prepare)
+        run: gem install ruby-ll --no-document
+
+      - name: Generate ragel / ruby-ll outputs in vendored forks
+        run: rake vendor:prepare
+
+      - name: Configure bundler
+        run: |
+          mkdir -p .bundle
+          echo "---" > .bundle/config
+          echo 'BUNDLE_BUILD__RUBY___LL: "--with-cflags=-std=gnu17"' >> .bundle/config
+
+      - name: Install dependencies
+        run: bundle install
+
+      - name: Compile liboga / libll native extensions
+        run: rake vendor:compile
+
+      - name: Probe YJIT off
+        run: bundle exec rake performance:probe
+
+      - name: Probe YJIT on
+        env:
+          RUBY_YJIT_ENABLE: "1"
+        run: bundle exec rake performance:probe

data/README.adoc

@@ -2693,6 +2693,41 @@ references:
 ====
 
 
+==== Attribute-value dispatch on a shared name (`when_attribute`)
+
+Polymorphism selects the *class* of each item. The other dispatch axis
+selects *which attribute* an occurrence belongs to, keyed by a sibling
+value — every `<component>` below goes to a different attribute by its
+`type`:
+
+[source,ruby]
+----
+class Requirement < Lutaml::Model::Serializable
+  attribute :guidance, Component, collection: true
+  attribute :purpose, Component, collection: true
+
+  xml do
+    element "requirement"
+    map_element "component", when_attribute: "type",
+                             to: { "guidance" => :guidance,
+                                   "purpose" => :purpose }
+  end
+end
+----
+
+The same declaration works for key-value formats (`json`/`yaml`/`toml`/
+`hsh` blocks use `map`), where the discriminator is an object key's
+value. Every occurrence is captured exactly once, the discriminator is
+re-emitted on serialization, `unmatched: :raise` fails the parse on
+values no rule claims, and `ordered` XML mappings round-trip the
+original interleaving. The two axes compose on one rule — partition by
+value while dispatching classes with `polymorphic`.
+
+See
+link:docs/_guides/advanced-mapping.adoc[the advanced mapping guide]
+for the full semantics.
+
+
 
 === Union attributes
 

data/docs/_guides/index.adoc

@@ -23,6 +23,10 @@ Task-oriented guides for accomplishing specific goals with Lutaml::Model.
 * link:../keyvalue-serialization[Key-Value Serialization] - JSON/YAML/TOML/Hash
 * link:../collection-serialization[Collection Serialization] - JSONL and YAML Stream
 
+== Advanced mapping
+
+* link:../advanced-mapping[Advanced Attribute Mapping] - Same-name dispatch on attribute values (`when_attribute`), grouped declarations, custom methods, delegation
+
 == Performance
 
 * link:../native-engines[Native engines (leptris / yeptris / teptris)] - Drop-in XML/YAML/JSON/TOML engine upgrades via bundle opt-in

data/docs/_guides/keyvalue-serialization.adoc

@@ -116,6 +116,40 @@ desc: A ceramic with a navy blue color and clear glaze.
 ----
 ====
 
+=== Dispatching a shared key by a discriminator value
+
+When one wire key holds a list of objects distinguished by a sibling
+key's value, `when_attribute` routes each item to its own attribute —
+one declaration covers the whole partition:
+
+[source,ruby]
+----
+class Requirement < Lutaml::Model::Serializable
+  attribute :guidance, Component, collection: true
+  attribute :purpose, Component, collection: true
+
+  json do
+    map "component", when_attribute: "type",
+                     to: { "guidance" => :guidance, "purpose" => :purpose }
+  end
+end
+----
+
+[source,json]
+----
+{ "component": [
+  { "type": "guidance", "text": "g1" },
+  { "type": "purpose",  "text": "p1" }
+] }
+----
+
+`guidance` holds `g1`, `purpose` holds `p1`. Serialization merges the
+items back under the one key, each stamped with its discriminator.
+`unmatched: :raise` fails the parse on items no rule claims. Works for
+all key-value formats. See
+link:advanced-mapping.adoc[the advanced mapping guide] for the full
+semantics, including the per-rule form.
+
 === Specific format mappings
 
 Specific key value formats can be mapping independently of other formats.

data/docs/_guides/native-engines.adoc

@@ -31,6 +31,36 @@ leptris and yeptris ship prebuilt platform gems for Linux and macOS
 every platform, including Windows. When a gem is absent, lutaml-model
 automatically falls back to the standard engine for that format.
 
+== YJIT doubles the model pipeline
+
+The model layer's own work — mapping dispatch, casts, hydration — is
+plain Ruby and exactly the code shape YJIT compiles well; the native
+engines' C work is unaffected either way. On a controlled runner
+(ubuntu-latest, Ruby 3.4, the repository's performance probe):
+
+|===
+| op | YJIT off | YJIT on | change
+
+| from_yaml | 75.1 i/s | 129.7 i/s | +73%
+| to_yaml | 67.3 i/s | 145.1 i/s | +116%
+| from_json | 73.2 i/s | 128.4 i/s | +75%
+| to_json | 115.4 i/s | 255.5 i/s | +121%
+|===
+
+Enable it like any Ruby application does — this is the application's
+call, never a gem's:
+
+[source,sh]
+----
+RUBY_YJIT_ENABLE=1 ruby app.rb
+# or in code, before heavy work:
+RubyVM::YJIT.enable
+----
+
+The opt-in XML plan fast path (see below) moves work out of Ruby and
+into the engine, which shrinks the YJIT win — enabling both is still
+net faster than either alone.
+
 == Selecting adapters explicitly
 
 The engines register as ordinary adapter types, so explicit selection and

data/lib/lutaml/key_value/transform.rb

@@ -5,9 +5,12 @@ module Lutaml
         # Use child's own default register if it has one
         # This ensures versioned schemas (e.g., MML v2 with lutaml_default_register = :mml_v2)
         # are instantiated with their native context
-        child_register = Lutaml::Model::Register.resolve_for_child(
-          model_class, lutaml_register
-        )
+        # TODO.max-perf/32: constant per (model class, register) — the
+        # transform itself is cached per that pair, so resolve once.
+        child_register = @kv_child_register ||= Lutaml::Model::Register
+          .resolve_for_child(
+            model_class, lutaml_register
+          )
 
         if model_class.include?(Lutaml::Model::Serialize)
           instance = model_class.new(lutaml_register: child_register)
@@ -449,7 +452,7 @@ partition = nil)
         if partitioned.nil? && (plan = kv_rule_plan(format, rule, attr)) &&
             (value = kv_fast_extract(doc, plan))
           rule.deserialize(instance, kv_fast_cast(value, plan, instance),
-                           attributes, self, options[:context])
+                           attributes, self, options[:context], pre_cast: true)
           return
         end
 
@@ -485,6 +488,10 @@ partition = nil)
         if attr.collection? || !instance.is_a?(Lutaml::Model::Serialize)
           attr.valid_collection!(value, context)
         end
+        # No pre_cast here: the interpretive attr.cast is not the full
+        # cast chain — whole-value Type policies (e.g. a custom
+        # Type::Value that receives the whole hash) are shaped by the
+        # setter's cast_value, which must still run.
         rule.deserialize(instance, value, attributes, self,
                          options[:context])
       end

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

@@ -324,13 +324,15 @@ module Lutaml
       end
 
       def deserialize(model, value, attributes, mapper_class = nil,
-context = nil)
+context = nil, pre_cast: false)
         if @needs_full_deserialize
           handle_custom_method(model, value, mapper_class, context) ||
             handle_delegate(model, value, attributes) ||
-            handle_transform_method(model, value, attributes, context)
+            handle_transform_method(model, value, attributes, context,
+                                    pre_cast: pre_cast)
         else
-          handle_transform_method(model, value, attributes, context)
+          handle_transform_method(model, value, attributes, context,
+                                  pre_cast: pre_cast)
         end
       end
 
@@ -446,6 +448,24 @@ context = nil)
       # :import — hash/proc transformers go through ImportTransformer.
       TRANSFORM_DISPATCH = {}.compare_by_identity
 
+      def self.parsed_assign_writer(model_class, target)
+        key = [model_class, target]
+        writer = PARSED_ASSIGN_WRITERS[key]
+        return writer unless writer.nil?
+
+        name = :"__assign_parsed_#{target}="
+        writer = model_class.method_defined?(name) ? name : false
+        PARSED_ASSIGN_WRITERS[key] = writer
+        writer
+      end
+
+      # [model class, target] -> the parsed-assign writer compiled for
+      # that class's attribute, or nil when only a casting writer
+      # exists (custom writers, reflective names, enum shorthands).
+      # Class-level because mapping rules may be frozen (see the
+      # name-string note above TRANSFORM_DISPATCH).
+      PARSED_ASSIGN_WRITERS = {}.compare_by_identity
+
       def self.transform_dispatch(rule, attr)
         per_attr = TRANSFORM_DISPATCH[rule]
         if per_attr.nil?
@@ -556,7 +576,8 @@ context = nil)
                           attributes[delegate].type(model.lutaml_register).new)
       end
 
-      def handle_transform_method(model, value, attributes, context = nil)
+      def handle_transform_method(model, value, attributes, context = nil,
+pre_cast: false)
         attr = attributes[to]
         # The transform verdict (none / class-based already applied /
         # hash-proc via ImportTransformer) is static per (rule, attr) —
@@ -566,12 +587,28 @@ context = nil)
           transformed = ImportTransformer.call(value, self, attr,
                                                context: context)
           assign_value(model, transformed)
+        elsif pre_cast && collection_shaped?(value, attr) &&
+            (writer = self.class.parsed_assign_writer(model.class, to))
+          # TODO.max-perf/31: the deserializing transform already cast
+          # the value through the format-aware path — assign without
+          # repeating the cast. Custom writers and reflective names
+          # resolve nil here and keep the casting setter.
+          model.public_send(writer, value)
         else
           assign_value(model, value)
         end
         true
       end
 
+      # Whether the value already carries the attribute's final shape:
+      # a bare single occurrence still owes the setter's one-element
+      # collection coercion, so only collection instances (and every
+      # singular value, whose cast is complete) take the no-recast lane.
+      def collection_shaped?(value, attr)
+        attr.nil? || !attr.collection? || value.is_a?(::Array) ||
+          value.is_a?(Lutaml::Model::Collection)
+      end
+
       def assign_value(model, value)
         model.public_send(@setter_name, value)
       end

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

@@ -297,6 +297,21 @@ module Lutaml
                 end
                 record_mutation_collection(:#{name}, value)
               end
+
+              # TODO.max-perf/31: the deserialization transforms already
+              # cast through the format-aware path; this writer skips the
+              # setter's re-cast while keeping value_set_for marking and
+              # mutation recording. Public assignment keeps the caster.
+              def __assign_parsed_#{name}=(value)
+                value_set_for(:#{name})
+                current = @#{name}
+                if current.equal?(Lutaml::Model::Serialize::LAZY_EMPTY_COLLECTION) &&
+                    (value.nil? || Lutaml::Model::Utils.uninitialized?(value))
+                else
+                  @#{name} = value
+                end
+                record_mutation_collection(:#{name}, value)
+              end
             RUBY
           else
             class_eval(<<~RUBY, __FILE__, __LINE__ + 1) # rubocop:disable Style/DocumentDynamicEvalDefinition
@@ -306,6 +321,13 @@ module Lutaml
                 @#{name} = value
                 record_mutation(:#{name}, value)
               end
+
+              # TODO.max-perf/31: see the collection branch above.
+              def __assign_parsed_#{name}=(value)
+                value_set_for(:#{name})
+                @#{name} = value
+                record_mutation(:#{name}, value)
+              end
             RUBY
           end
         end

data/lib/lutaml/model/version.rb

@@ -2,6 +2,6 @@
 
 module Lutaml
   module Model
-    VERSION = "0.8.47"
+    VERSION = "0.8.49"
   end
 end

data/lib/lutaml/xml/model_transform.rb

@@ -48,9 +48,12 @@ module Lutaml
         # Use child's own default register if it has one
         # This ensures versioned schemas (e.g., MML v2 with lutaml_default_register = :mml_v2)
         # are instantiated with their native context
-        child_register = Lutaml::Model::Register.resolve_for_child(
-          model_class, lutaml_register
-        )
+        # TODO.max-perf/32: constant per (model class, register) — the
+        # transform itself is cached per that pair, so resolve once.
+        child_register = @xml_child_register ||= Lutaml::Model::Register
+          .resolve_for_child(
+            model_class, lutaml_register
+          )
 
         instance_is_serialize = model_class.include?(::Lutaml::Model::Serialize)
         if instance_is_serialize

data/lib/lutaml/xml/plan_compiler.rb

@@ -200,7 +200,14 @@ module Lutaml
 
         def compilable_mapping?(mapping)
           mapping.root_element &&
-            !(mapping.respond_to?(:root_mappings) && mapping.root_mappings)
+            !(mapping.respond_to?(:root_mappings) && mapping.root_mappings) &&
+            # lutaml-model#88: when_attribute partitions route same-name
+            # occurrences by attribute value — name-keyed plan rows would
+            # hydrate every occurrence into EVERY partition attribute
+            # (verified double-capture under the flag). The interpretive
+            # filter is the only correct path until the descriptor ABI
+            # grows row predicates.
+            mapping.mappings.none?(&:when_attribute?)
         end
 
         # Attribute for a rule — delegate rules resolve against their

data/spec/lutaml/xml/plan_fast_path_spec.rb

@@ -517,6 +517,83 @@ RSpec.describe "XML plan fast path" do
       expect(model.to_xml).to eq(interpretive)
     end
 
+    # lutaml-model#88: name-keyed plan rows would hydrate every
+    # same-name occurrence into EVERY partition attribute (verified
+    # double-capture) — discriminator models must take the interpretive
+    # path, and a partitioned CHILD model must opt its parent out too.
+    it "falls back to the interpretive path for when_attribute models" do
+      component = Class.new(Lutaml::Model::Serializable) do
+        attribute :text, :string
+
+        xml do
+          element "component"
+          map_element "text", to: :text
+        end
+      end
+      stub_const("PlanFastPath::Component", component)
+
+      partitioned = Class.new(Lutaml::Model::Serializable) do
+        attribute :guidance, component, collection: true
+        attribute :purpose, component, collection: true
+
+        xml do
+          element "requirement"
+          map_element "component", when_attribute: "type",
+                                   to: { "guidance" => :guidance,
+                                         "purpose" => :purpose }
+        end
+      end
+      stub_const("PlanFastPath::Partitioned", partitioned)
+
+      req = partitioned.from_xml(<<~XML)
+        <requirement>
+          <component type="guidance"><text>g1</text></component>
+          <component type="purpose"><text>p1</text></component>
+          <component type="guidance"><text>g2</text></component>
+        </requirement>
+      XML
+
+      expect(req.guidance.map(&:text)).to eq(%w[g1 g2])
+      expect(req.purpose.map(&:text)).to eq(["p1"])
+
+      expect(Lutaml::Xml::PlanCompiler.compile(partitioned,
+                                               :default)).to be_nil
+    end
+
+    it "opts a parent out when a child model partitions with when_attribute" do
+      component = Class.new(Lutaml::Model::Serializable) do
+        attribute :text, :string
+
+        xml do
+          element "component"
+          map_element "text", to: :text
+        end
+      end
+      inner = Class.new(Lutaml::Model::Serializable) do
+        attribute :guidance, component, collection: true
+
+        xml do
+          element "req"
+          map_element "component", to: :guidance,
+                                   when_attribute: { "type" => "guidance" }
+        end
+      end
+      outer = Class.new(Lutaml::Model::Serializable) do
+        attribute :req, inner
+
+        xml do
+          element "holder"
+          map_element "req", to: :req
+        end
+      end
+      stub_const("PlanFastPath::Nested", outer)
+
+      doc = outer.from_xml(
+        "<holder><req><component type=\"guidance\"><text>g1</text></component></req></holder>",
+      )
+      expect(doc.req.guidance.map(&:text)).to eq(["g1"])
+    end
+
     it "round-trips through both fast paths" do
       item = Class.new(Lutaml::Model::Serializable) do
         attribute :id, :integer

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lutaml-model
 version: !ruby/object:Gem::Version
-  version: 0.8.47
+  version: 0.8.49
 platform: ruby
 authors:
 - Ribose Inc.