lutaml-model 0.8.49 → 0.8.51

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2dab1dcbc2ea77cfd1c61d9ffba4717521b9e97e1f3f6c8dd6f9ce6c7014222f
-  data.tar.gz: ed16efadd94ce85b9e52a5c7de822f9c7de7e3c581203280120630e8cdb389ff
+  metadata.gz: bd76b1c0377a6e86d547f5ca29fe5d164d390bc7f1d88ba7051a5930b119911f
+  data.tar.gz: 22e2dea3ad97c502647a49ec748113e939234b9136c02634b99c722ce443df10
 SHA512:
-  metadata.gz: cd6bbdebb2c812eb849774ac168fe2c194bc21113521be6b4ca8b389ab5f6ebb2743b951478077332a18a2c214f458962c0a89d54e1a26447b3b103b7c2bb153
-  data.tar.gz: fddad44bad334a640facc5f6869b91c2a12134da6c79e58b7bed1787e14c03702d5ffd0ffcece27e435fe2f9387a7d13040e45794d178424cd7e56acbf9bb36c
+  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/serialize/initialization.rb

@@ -350,6 +350,59 @@ module Lutaml
           instance
         end
 
+        # Fast bulk constructor for deserialization-heavy callers
+        # (native extensions building object trees bottom-up).
+        #
+        # Allocates without running #initialize and applies each present
+        # attribute through its compiled writer, which casts the value
+        # and marks it as explicitly set — so defaults, to_hash output,
+        # and using_default? behave exactly as if the instance had been
+        # produced by from_hash. Values may be primitives or already
+        # built instances (instances pass through casting unchanged);
+        # absent keys keep their defaults. Unknown keys raise.
+        #
+        # @param attrs [Hash] attribute names (String or Symbol) to
+        #   pre-cast values
+        # @param register [Symbol, nil] The register context
+        # @return [Object] The hydrated instance
+        def instantiate(attrs = {}, register = nil)
+          instance = allocate_for_deserialization(register)
+          register_id = instance.lutaml_register
+          given = {}
+          attrs.each do |key, value|
+            name = key.to_sym
+            next if name == :lutaml_register
+
+            unless attributes(register_id).key?(name)
+              raise Error, "unknown attribute '#{name}' for #{self}"
+            end
+
+            given[name] = value
+          end
+          attributes(register_id).each do |name, attr|
+            next if attr.derived?
+
+            if given.key?(name)
+              instance.public_send(:"#{name}=", given[name])
+            else
+              # Absent keys seed their default explicitly, mirroring
+              # initialize_attributes: every mapped attribute ends up
+              # set (nil when no default), never left as the
+              # uninitialized sentinel — readers and formatters touch
+              # absent attributes freely.
+              default = attr.default_value(register_id, instance)
+              value = if Lutaml::Model::Utils.uninitialized?(default)
+                        nil
+                      else
+                        attr.cast_value(default, register_id)
+                      end
+              instance.public_send(:"#{name}=", value)
+              instance.using_default_for(name)
+            end
+          end
+          instance
+        end
+
         # Define register-specific attribute methods on the class itself.
         #
         # Called once per (class, register) combination. Replaces per-instance

data/lib/lutaml/model/version.rb

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

data/lib/lutaml/xml/plan_hydrator.rb

@@ -30,7 +30,11 @@ module Lutaml
 
             child_kwargs[name] = []
           end
-          instance = model_class.new(**attr_kwargs, **child_kwargs)
+          # TODO.max-perf/33: the bulk constructor — allocate +
+          # compiled writers, from_hash semantics — measured ~30x on
+          # hydration-heavy corpora versus the generic constructor.
+          instance = model_class.instantiate(attr_kwargs.merge(child_kwargs),
+                                             register)
           instance.lutaml_parent = parent if parent
           instance.lutaml_root ||= parent&.lutaml_root || parent
           instance.element_order = PlanOrder.build(node) if node && plan[:ordered]

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

data/spec/lutaml/model/serializable_instantiate_spec.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+require_relative "../../../lib/lutaml/model"
+
+module InstantiateMapping
+  class Part < Lutaml::Model::Serializable
+    attribute :label, :string
+    attribute :count, :integer
+  end
+
+  class Widget < Lutaml::Model::Serializable
+    attribute :name, :string
+    attribute :flag, :boolean
+    attribute :part, Part
+    attribute :tags, :string, collection: true
+
+    key_value do
+      map "name", to: :name
+      map "flag", to: :flag
+      map "part", to: :part
+      map "tags", to: :tags
+    end
+  end
+end
+
+RSpec.describe "Serializable.instantiate" do
+  it "hydrates attributes from primitives" do
+    widget = InstantiateMapping::Widget.instantiate("name" => "w", "flag" => true,
+                                                    "tags" => %w[a b])
+    expect(widget.name).to eq("w")
+    expect(widget.flag).to be(true)
+    expect(widget.tags).to eq(%w[a b])
+  end
+
+  it "accepts pre-built instances for typed attributes" do
+    part = InstantiateMapping::Part.instantiate(label: "p", count: 2)
+    widget = InstantiateMapping::Widget.instantiate(name: "w", part: part)
+
+    expect(widget.part).to equal(part)
+  end
+
+  it "keeps defaults for absent keys and reports them as defaults" do
+    widget = InstantiateMapping::Widget.instantiate
+    # Absent scalars read as the uninitialized sentinel, exactly like the
+    # XML fast path; serialization omits them either way.
+    expect(Lutaml::Model::Utils.uninitialized?(widget.name) ||
+           widget.name.nil?).to be(true)
+    expect(widget).to be_using_default(:name)
+  end
+
+  it "marks set attributes as explicitly set" do
+    widget = InstantiateMapping::Widget.instantiate(name: "w")
+    expect(widget).not_to be_using_default(:name)
+  end
+
+  it "serializes identically to from_hash" do
+    input = { "name" => "w", "flag" => false,
+              "part" => { "label" => "p", "count" => 3 },
+              "tags" => ["x"] }
+    from_hash = InstantiateMapping::Widget.from_hash(input)
+
+    part = InstantiateMapping::Part.instantiate(input["part"])
+    fast = InstantiateMapping::Widget.instantiate(
+      name: "w", flag: false, part: part, tags: ["x"],
+    )
+
+    expect(fast.to_hash).to eq(from_hash.to_hash)
+  end
+
+  it "raises on unknown attribute names" do
+    expect { InstantiateMapping::Widget.instantiate(bogus: 1) }
+      .to raise_error(Lutaml::Model::Error, /unknown attribute/)
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: lutaml-model
 version: !ruby/object:Gem::Version
-  version: 0.8.49
+  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
@@ -1797,6 +1798,7 @@ files:
 - spec/lutaml/model/schema/yaml_schema_spec.rb
 - spec/lutaml/model/sequence_choice_compositor_spec.rb
 - spec/lutaml/model/sequence_spec.rb
+- spec/lutaml/model/serializable_instantiate_spec.rb
 - spec/lutaml/model/serializable_spec.rb
 - spec/lutaml/model/serializable_validation_spec.rb
 - spec/lutaml/model/serialize/builder_spec.rb