lutaml-model 0.8.50 → 0.8.51

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f2f88962ec380d731bd7a31ce5ff62f9aec9dcef4b7783aebfb128b6b5c86bbb
-  data.tar.gz: b282edc8ccf91c2381315e58a34d54a15642153e673ba31bbbd46c084c7634c4
+  metadata.gz: bd76b1c0377a6e86d547f5ca29fe5d164d390bc7f1d88ba7051a5930b119911f
+  data.tar.gz: 22e2dea3ad97c502647a49ec748113e939234b9136c02634b99c722ce443df10
 SHA512:
-  metadata.gz: f92f932e37bed4d355b3a41c1d2599bf23a5f0907f2ba18967f27cb5a572a4be11d080d54d0a73787055b6e9143414928e87086f2269f42acfb77665e9cccda6
-  data.tar.gz: a5801daa0947b0a2308fc720412d0add3cd5956f6a902cf20aa62b0ece6d883ec801dc4c4112319ab161a5d68934d54aac0253d601515823d04440df52011400
+  metadata.gz: '0883bebaf58efeeda222ddc83f74661f396184786944f48f1a9ae2ecb5cbb4c15059cb5dd93df791d101acd734ca597e849b5c0d4488b104c59b7afa01f05e40'
+  data.tar.gz: 46e13698b95bff244e8d31627bbd3c1fd2a9fc667b3741a9707bac2a85256be426a9606c3c38ac848722ae668c488da39643154f5387aa6a60ee006dd57056b3

data/lib/lutaml/key_value/transform.rb

@@ -12,6 +12,20 @@ module Lutaml
             model_class, lutaml_register
           )
 
+        # TODO.max-perf/37: eligible models hydrate in one pass —
+        # collect raw values per rule, recurse into eligible child
+        # models, build every instance through the bulk constructor.
+        # Falls back to the per-rule walk for anything ineligible.
+        if !options.key?(:mappings) && data.is_a?(::Hash) &&
+            %i[json yaml toml hash].include?(format) &&
+            (group = self.class.kv_group_plan(model_class, format,
+                                              lutaml_register)) &&
+            (instance = kv_group_build(group, data, format, child_register,
+                                       options))
+          root_and_parent_assignment(instance, options)
+          return instance
+        end
+
         if model_class.include?(Lutaml::Model::Serialize)
           instance = model_class.new(lutaml_register: child_register)
         else
@@ -76,6 +90,189 @@ module Lutaml
         hash.keys == [""] ? hash[""] : hash
       end
 
+      # ---- TODO.max-perf/37: group-then-instantiate fast path ----
+
+      # [model class, format, register] -> rows or false (ineligible).
+      # Rows: [[rule, attr, kind, child_rows]] with kind :scalar or
+      # :model; child_rows is the child model's own row set. Cycle-safe:
+      # an in-progress model resolves false, so self-referential models
+      # take the interpretive walk.
+      # Concurrent::Map under threaded MRI, plain Hash under Opal
+      # (Concurrent is unavailable there) — the RULE_RECORDS pattern.
+      # Writes are idempotent (the same deterministic plan is computed),
+      # so a lost race costs a duplicate build, never a wrong value.
+      KV_GROUP_PLANS = if Lutaml::Model.opal?
+                         {}
+                       else
+                         Lutaml::Model::RuntimeCompatibility
+                           .require_native("concurrent")
+                         Concurrent::Map.new
+                       end
+
+      def self.kv_group_plan(model_class, format, register)
+        # Context generation: specs (and apps) reset registers between
+        # parses; a plan cached across a reset references dead attribute
+        # objects. The generation key retires stale plans for free.
+        key = [model_class, format, register,
+               Lutaml::Model::GlobalContext.context_generation]
+        plan = KV_GROUP_PLANS[key]
+        return plan unless plan.nil?
+
+        # Cycle detection rides a THREAD-LOCAL recursion stack: a shared
+        # in-progress set races (a concurrent same-key build would cache
+        # false permanently), and the stack is per-build by definition.
+        # The false at the cycle point is NOT cached — the outermost
+        # build completes and caches the model's real verdict.
+        stack = (Thread.current[:kv_group_plan_stack] ||= [])
+        return false if stack.include?(key)
+
+        stack.push(key)
+        begin
+          KV_GROUP_PLANS[key] = build_kv_group_plan(model_class, format,
+                                                    register)
+        ensure
+          stack.pop
+        end
+      end
+
+      def self.build_kv_group_plan(model_class, format, register)
+        return false unless model_class.is_a?(Class) &&
+          model_class.include?(Lutaml::Model::Serialize)
+
+        mapping = model_class.mappings_for(format, register)
+        return false if mapping.nil?
+
+        attrs = model_class.attributes(register)
+        rows = nil
+        mapping.mappings(register).each do |rule|
+          eligible = !rule.name.nil? && !rule.multiple_mappings? &&
+            rule.delegate.nil? &&
+            !rule.has_custom_method_for_deserialization? &&
+            !rule.raw_mapping? && !rule.root_mapping? &&
+            !rule.hash_mappings && rule.child_mappings.nil? &&
+            rule.when_attribute.empty? &&
+            !(if rule.polymorphic.is_a?(::Hash)
+                !rule.polymorphic.empty?
+              else
+                !!rule.polymorphic
+              end) &&
+            rule.transform.is_a?(::Hash) && rule.transform.empty? &&
+            rule.value_map(:from) ==
+              Lutaml::Model::Serialize::DEFAULT_VALUE_MAP
+          return false unless eligible
+
+          attr = attrs[rule.to]
+          return false if attr.nil? || attr.derived?
+          # Declared ranges keep their eager validation on the
+          # interpretive walk; polymorphic/union/custom-collection
+          # dispatch and registered type substitutions own their cast
+          # (the per-rule walk threads them through cast options).
+          return false if attr.collection? && attr.collection.is_a?(Range)
+          return false if attr.polymorphic? || attr.union? ||
+            attr.custom_collection?
+
+          type = attr.type(register)
+          return false if Lutaml::Model::GlobalContext.context(register)
+            .substitution_for(type).any?
+
+          if type.is_a?(Class) && type.include?(Lutaml::Model::Serialize)
+            child_rows = kv_group_plan(type, format,
+                                       Lutaml::Model::Register
+                                         .resolve_for_child(type, register))
+            return false unless child_rows
+
+            rows ||= []
+            rows << [rule, attr, :model, type, child_rows]
+          elsif type.is_a?(Class) && type < Lutaml::Model::Type::Value &&
+              !attr.value_policy.whole_value?(type) &&
+              !Lutaml::Model::Attribute.custom_from_probe?(type)
+            rows ||= []
+            rows << [rule, attr, :scalar, nil, nil]
+          else
+            return false
+          end
+        end
+        # No eligible rows at all (empty mapping) — nothing to gain.
+        rows
+      end
+
+      # Build values bottom-up, then ONE instance per model: present
+      # keys through the casting setters, ABSENT rules through the real
+      # per-rule walk (their extractor/defaults/sentinel semantics are
+      # the walk's own — reproducing them here would fork them). The
+      # per-rule walk is eliminated exactly for the present-key hot
+      # path. Returns nil (caller falls back) on any shape the plan
+      # does not cover, e.g. a non-Hash item where a model was expected.
+      def kv_group_build(rows, doc, format, register, options)
+        setters = []
+        children = []
+        absent = []
+        rows.each do |rule, attr, kind, type, child_rows|
+          unless Lutaml::Model::Utils.string_or_symbol_key?(doc, rule.name)
+            absent << rule
+            next
+          end
+          v = Lutaml::Model::Utils.fetch_str_or_sym(doc, rule.name)
+
+          if kind == :scalar
+            setters << [:"#{rule.to}=", v]
+            next
+          end
+
+          child_register = Lutaml::Model::Register.resolve_for_child(type,
+                                                                     register)
+          if attr.collection?
+            # A present-but-nil collection reaches the per-rule walk,
+            # which owns the sentinel interplay for that edge
+            # (render_nil :as_empty semantics).
+            return nil if v.nil?
+
+            items = v.is_a?(::Array) ? v : [v]
+            built = []
+            items.each do |item|
+              return nil unless item.is_a?(::Hash)
+
+              child = self.class.kv_group_instance(type, child_rows, item,
+                                                   format, child_register,
+                                                   options)
+              return nil if child.nil?
+
+              built << child
+            end
+            setters << [:"#{rule.to}=", built]
+            children.concat(built)
+          else
+            return nil unless v.is_a?(::Hash)
+
+            child = self.class.kv_group_instance(type, child_rows, v,
+                                                 format, child_register,
+                                                 options)
+            return nil if child.nil?
+
+            setters << [:"#{rule.to}=", child]
+            children << child
+          end
+        end
+        instance = model_class.new(lutaml_register: register)
+        setters.each { |name, value| instance.public_send(name, value) }
+        absent.each do |rule|
+          process_mapping_rule(doc, instance, format, rule, options, nil)
+        end
+        children.each do |child|
+          child.lutaml_parent = instance
+          child.lutaml_root ||= instance.lutaml_root || instance
+        end
+        instance
+      end
+
+      def self.kv_group_instance(model_class, rows, doc, format, register,
+options)
+        # cached_transform is per (class, register); format rides the
+        # call, not the cache.
+        cached_transform(model_class, register)
+          .kv_group_build(rows, doc, format, register, options)
+      end
+
       private
 
       def process_rule!(instance, rule, hash, format, _mappings, options)

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

@@ -463,8 +463,16 @@ context = nil, pre_cast: false)
       # 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
+      # name-string note above TRANSFORM_DISPATCH). Concurrent::Map
+      # under threaded MRI, plain identity Hash under Opal — writes are
+      # idempotent (the same verdict is recomputed).
+      PARSED_ASSIGN_WRITERS = if Lutaml::Model.opal?
+                                {}.compare_by_identity
+                              else
+                                Lutaml::Model::RuntimeCompatibility
+                                  .require_native("concurrent")
+                                Concurrent::Map.new
+                              end
 
       def self.transform_dispatch(rule, attr)
         per_attr = TRANSFORM_DISPATCH[rule]

data/lib/lutaml/model/version.rb

@@ -2,6 +2,6 @@
 
 module Lutaml
   module Model
-    VERSION = "0.8.50"
+    VERSION = "0.8.51"
   end
 end

data/spec/lutaml/key_value/group_instantiate_spec.rb

@@ -0,0 +1,302 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+# TODO.max-perf/37: eligible models hydrate in ONE pass — present keys
+# collected per rule, child models recursed, one instance per model.
+# Absent rules keep the real per-rule walk; anything ineligible keeps
+# the whole walk.
+class KvGroupPart < Lutaml::Model::Serializable
+  attribute :label, :string
+  attribute :count, :integer
+
+  json do
+    map "label", to: :label
+    map "count", to: :count
+  end
+
+  hsh do
+    map "label", to: :label
+    map "count", to: :count
+  end
+end
+
+class KvGroupWidget < Lutaml::Model::Serializable
+  attribute :name, :string
+  attribute :flag, :boolean
+  attribute :part, KvGroupPart
+  attribute :parts, KvGroupPart, collection: true
+  attribute :tags, :string, collection: true
+
+  json do
+    map "name", to: :name
+    map "flag", to: :flag
+    map "part", to: :part
+    map "parts", to: :parts
+    map "tags", to: :tags
+  end
+
+  hsh do
+    map "name", to: :name
+    map "flag", to: :flag
+    map "part", to: :part
+    map "parts", to: :parts
+    map "tags", to: :tags
+  end
+end
+
+RSpec.describe "KV group-then-bulk hydration" do
+  before do
+    stub_const("KvGroup::Part", KvGroupPart)
+    stub_const("KvGroup::Widget", KvGroupWidget)
+  end
+
+  let(:doc) do
+    {
+      "name" => "w",
+      "flag" => true,
+      "part" => { "label" => "p", "count" => 2 },
+      "parts" => [{ "label" => "a" }, { "label" => "b", "count" => 5 }],
+      "tags" => %w[x y],
+    }
+  end
+
+  it "hydrates nested models through the group path" do
+    widget = KvGroupWidget.from_hash(doc)
+
+    expect(widget.name).to eq("w")
+    expect(widget.flag).to be(true)
+    expect(widget.part.label).to eq("p")
+    expect(widget.part.count).to eq(2)
+    expect(widget.parts.map(&:label)).to eq(%w[a b])
+    expect(widget.parts.map(&:count)).to eq([nil, 5])
+    expect(widget.tags).to eq(%w[x y])
+  end
+
+  it "threads parent and root links like the per-rule walk" do
+    widget = KvGroupWidget.from_hash(doc)
+
+    expect(widget.part.lutaml_parent).to equal(widget)
+    expect(widget.parts.first.lutaml_parent).to equal(widget)
+    expect(widget.parts.first.lutaml_root).to equal(widget)
+  end
+
+  it "leaves absent attributes exactly as the per-rule walk does" do
+    empty = KvGroupWidget.from_hash({})
+    # The walk's own contract for absent keys: values seeded by the
+    # constructor's defaults, marked set-by-parse (not default) — the
+    # group path runs the same absent-rule walk, so it matches.
+    expect(empty.name).to be_nil
+    expect(empty.part).to be_nil
+
+    named = KvGroupWidget.from_hash("name" => "q")
+    expect(named.name).to eq("q")
+    expect(named.part).to be_nil
+  end
+
+  it "engages the group path (wiring proves engagement)" do
+    counted = Class.new(KvGroupPart) do
+      @built = 0
+      class << self
+        attr_reader :built
+
+        def new(*args)
+          @built += 1
+          super
+        end
+      end
+    end
+    holder = Class.new(Lutaml::Model::Serializable) do
+      attribute :parts, counted, collection: true
+
+      json { map "parts", to: :parts }
+      hsh { map "parts", to: :parts }
+    end
+    stub_const("KvGroup::Counted", counted)
+    stub_const("KvGroup::Holder", holder)
+
+    holder.from_hash("parts" => [{ "label" => "a" }, { "label" => "b" }])
+    # 2 parts = 2 constructions, one per instance, no per-rule walk
+    expect(counted.built).to eq(2)
+  end
+
+  it "works through json and yaml" do
+    json = KvGroupWidget.from_json(doc.to_json)
+    yaml = KvGroupWidget.from_yaml(doc.to_yaml)
+
+    expect(json.to_hash).to eq(yaml.to_hash)
+    expect(json.parts.map(&:label)).to eq(%w[a b])
+  end
+
+  it "wraps a single object into a model collection" do
+    widget = KvGroupWidget.from_hash("parts" => { "label" => "solo" })
+
+    expect(widget.parts.map(&:label)).to eq(["solo"])
+  end
+
+  it "falls back and matches the per-rule walk for junk items" do
+    # The interpretive walk rejects a non-object item in a model row
+    # with InvalidFormatError; the group path must behave identically
+    # after falling back — same data in, same outcome, either path.
+    expect do
+      KvGroupWidget.from_hash("parts" => [{ "label" => "a" }, "junk"])
+    end.to raise_error(Lutaml::Model::InvalidFormatError)
+  end
+
+  describe "eligibility" do
+    it "rejects custom methods and still parses" do
+      custom = Class.new(KvGroupWidget) do
+        json do
+          map "name", to: :name
+          map "flag", to: :flag
+          map "part", to: :part
+          map "parts", to: :parts
+          map "tags", to: :tags
+          map "name", to: :name, with: { to: :n_to, from: :n_from }
+        end
+
+        def n_from(model, _value)
+          model.name = "from-custom"
+        end
+
+        def n_to(_model, _doc); end
+      end
+      stub_const("KvGroup::Custom", custom)
+
+      expect(Lutaml::KeyValue::Transform.kv_group_plan(custom, :json,
+                                                       :default)).to be(false)
+      # Falls back to the per-rule walk; whatever it produces for the
+      # custom rule is that path's contract, unchanged by this feature.
+      expect(custom.from_hash(doc)).to be_a(custom)
+    end
+
+    it "rejects when_attribute partitions" do
+      partitioned = Class.new(KvGroupWidget) do
+        attribute :guidance, KvGroupPart, collection: true
+
+        json do
+          map "guidance", to: :guidance,
+                          when_attribute: { "type" => "guidance" }
+        end
+      end
+      stub_const("KvGroup::Partitioned", partitioned)
+
+      expect(Lutaml::KeyValue::Transform.kv_group_plan(partitioned, :json,
+                                                       :default)).to be(false)
+    end
+
+    it "rejects rule-level polymorphic dispatch" do
+      animal = Class.new(Lutaml::Model::Serializable) do
+        attribute :name, :string
+        json { map "name", to: :name }
+      end
+      zoo = Class.new(Lutaml::Model::Serializable) do
+        attribute :animals, animal, collection: true
+        json do
+          map "animals", to: :animals, polymorphic: { attribute: "type" }
+        end
+      end
+      stub_const("KvGroup::Zoo", zoo)
+
+      expect(Lutaml::KeyValue::Transform.kv_group_plan(zoo, :json,
+                                                       :default)).to be(false)
+    end
+
+    it "rejects range collections" do
+      ranged = Class.new(Lutaml::Model::Serializable) do
+        attribute :tags, :string, collection: 1..3
+
+        json { map "tags", to: :tags }
+      end
+      stub_const("KvGroup::Ranged", ranged)
+
+      expect(Lutaml::KeyValue::Transform.kv_group_plan(ranged, :json,
+                                                       :default)).to be(false)
+      expect(ranged.from_hash("tags" => %w[a b]).tags).to eq(%w[a b])
+    end
+
+    it "rejects self-referential models (cycle)" do
+      node = Class.new(Lutaml::Model::Serializable) do
+        attribute :name, :string
+        json { map "name", to: :name }
+      end
+      node.attribute :child, node
+      node.json do 
+        map "name", to: :name
+        map "child", to: :child
+      end
+      stub_const("KvGroup::Node", node)
+
+      expect(Lutaml::KeyValue::Transform.kv_group_plan(node, :json,
+                                                       :default)).to be(false)
+      parsed = node.from_hash("name" => "n", "child" => { "name" => "c" })
+      expect(parsed.child.name).to eq("c")
+    end
+
+    it "rejects delegates" do
+      holder = Class.new(Lutaml::Model::Serializable) do
+        attribute :label, :string
+        json { map "label", to: :label }
+      end
+      delegating = Class.new(Lutaml::Model::Serializable) do
+        attribute :part, holder
+        json { map "label", to: :label, delegate: :part }
+      end
+      stub_const("KvGroup::Delegating", delegating)
+
+      expect(Lutaml::KeyValue::Transform.kv_group_plan(delegating, :json,
+                                                       :default)).to be(false)
+    end
+  end
+
+  
+  describe "cache thread safety" do
+    it "survives concurrent first-builds with correct plans (no false caching)" do
+      part = Class.new(Lutaml::Model::Serializable) do
+        attribute :label, :string
+        json { map "label", to: :label }
+      end
+      widget = Class.new(Lutaml::Model::Serializable) do
+        attribute :part, part
+        json { map "part", to: :part }
+      end
+      stub_const("KvGroup::ThreadPart", part)
+      stub_const("KvGroup::ThreadWidget", widget)
+
+      # Clear any warm cache so every thread races the first build.
+      Lutaml::KeyValue::Transform::KV_GROUP_PLANS.clear
+
+      verdicts = Array.new(8) do
+        Thread.new do
+          Lutaml::KeyValue::Transform.kv_group_plan(widget, :json, :default)
+        end
+      end.map(&:value)
+
+      expect(verdicts).to all(be_truthy)
+      expect(verdicts.uniq.length).to eq(1)
+    end
+
+    it "keeps the cycle verdict per-build across threads" do
+      node = Class.new(Lutaml::Model::Serializable) do
+        attribute :name, :string
+        json { map "name", to: :name }
+      end
+      node.attribute :child, node
+      node.json do
+        map "name", to: :name
+        map "child", to: :child
+      end
+      stub_const("KvGroup::ThreadNode", node)
+
+      Lutaml::KeyValue::Transform::KV_GROUP_PLANS.clear
+      verdicts = Array.new(4) do
+        Thread.new do
+          Lutaml::KeyValue::Transform.kv_group_plan(node, :json, :default)
+        end
+      end.map(&:value)
+
+      expect(verdicts).to all(be(false))
+    end
+  end
+  
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: lutaml-model
 version: !ruby/object:Gem::Version
-  version: 0.8.50
+  version: 0.8.51
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-09-20 00:00:00.000000000 Z
+date: 2026-09-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base64
@@ -1684,6 +1684,7 @@ files:
 - spec/lutaml/json/yeptris_adapter_spec.rb
 - spec/lutaml/jsonld/adapter_spec.rb
 - spec/lutaml/key_value/adapter/toml/teptris_adapter_spec.rb
+- spec/lutaml/key_value/group_instantiate_spec.rb
 - spec/lutaml/key_value/transformation/collection_serializer_spec.rb
 - spec/lutaml/key_value/transformation/rule_compiler_spec.rb
 - spec/lutaml/key_value/transformation/value_serializer_spec.rb