lutaml-model 0.8.22 → 0.8.24

data/lib/lutaml/key_value/adapter/json/standard_adapter.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "json"
+require_relative "../../../json/generator_options"
 
 # Backward compatibility - delegates to Lutaml::Json::Adapter
 # @deprecated Use Lutaml::Json::Adapter::StandardAdapter instead
@@ -13,12 +14,16 @@ module Lutaml
           FORMAT_SYMBOL = :json
 
           def self.parse(json, _options = {})
-            JSON.parse(json, create_additions: false)
+            JSON.parse(json)
           end
 
-          def to_json(*args)
-            options = args.first || {}
+          # This adapter hands its payload to the stdlib generator, so a
+          # JSON::State carrying the outer formatting is meaningful here.
+          def accepts_generator_state?
+            true
+          end
 
+          def to_json(*args)
             # Handle KeyValueElement input (new symmetric architecture)
             attributes_to_serialize = if @attributes.is_a?(Lutaml::KeyValue::DataModel::Element)
                                         # Unwrap __root__ wrapper to get actual content
@@ -28,10 +33,17 @@ module Lutaml
                                         @attributes
                                       end
 
+            unless Lutaml::Json::GeneratorOptions.lutaml_options?(args.first)
+              return JSON.generate(attributes_to_serialize, args.first)
+            end
+
+            options = args.first || {}
+            generator_options = Lutaml::Json::GeneratorOptions.filter(options)
+
             if options[:pretty]
-              JSON.pretty_generate(attributes_to_serialize, *args)
+              JSON.pretty_generate(attributes_to_serialize, generator_options)
             else
-              JSON.generate(attributes_to_serialize, *args)
+              JSON.generate(attributes_to_serialize, generator_options)
             end
           end
         end

data/lib/lutaml/key_value/adapter/json/yeptris_adapter.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require_relative "../../../json/adapter/yeptris_adapter"
+
+module Lutaml
+  module KeyValue
+    module Adapter
+      module Json
+        # Backward-compatibility entry for the adapter resolver's default
+        # load path; the implementation lives in Lutaml::Json::Adapter.
+        YeptrisAdapter = Lutaml::Json::Adapter::YeptrisAdapter
+      end
+    end
+  end
+end

data/lib/lutaml/key_value/adapter/jsonl/standard_adapter.rb

@@ -15,7 +15,7 @@ module Lutaml
               next if line.strip.empty?
 
               begin
-                results << JSON.parse(line, create_additions: false)
+                results << JSON.parse(line)
               rescue JSON::ParserError => e
                 warn "Skipping invalid line: #{e.message}"
               end

data/lib/lutaml/key_value/adapter/toml/teptris_adapter.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+# TOML over the teptris engine (libteptris via FFI). teptris ships
+# prebuilt platform gems for every platform we support — including
+# mingw-ucrt — which retires the "no native TOML on Windows" gap that
+# keeps tomlib off Windows. Value semantics mirror tomlib: offset and
+# local datetimes become Time, dates become Date, local times stay
+# String. Parse failures raise Teptris::ParseError (line/column).
+
+module Lutaml
+  module KeyValue
+    module Adapter
+      module Toml
+        class TeptrisAdapter < Document
+          # teptris is required lazily (in parse/to_toml), NOT at file
+          # load: a platform gem whose native library is broken must
+          # degrade to detection-fallback + skipped specs, never crash
+          # unrelated loads. The gem's own require raises a clear
+          # LoadError ("no fallback by design") for that case.
+          def self.parse(toml, _options = {})
+            require "teptris"
+            Teptris::TOML.load(toml)
+          end
+
+          def to_toml(*)
+            require "teptris"
+            # Handle KeyValueElement input (new symmetric architecture)
+            attributes_to_serialize = if @attributes.is_a?(Lutaml::KeyValue::DataModel::Element)
+                                        # Unwrap __root__ wrapper to get actual content
+                                        @attributes.to_hash["__root__"]
+                                      else
+                                        # Legacy Hash input (backward compatibility)
+                                        @attributes
+                                      end
+
+            Teptris::TOML.dump(attributes_to_serialize)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/lutaml/key_value/adapter/toml.rb

@@ -12,6 +12,7 @@ module Lutaml
         autoload :Transform, "#{__dir__}/toml/transform"
         Lutaml::Model::RuntimeCompatibility.autoload_native(
           self,
+          TeptrisAdapter: "#{__dir__}/toml/teptris_adapter",
           TomlibAdapter: "#{__dir__}/toml/tomlib_adapter",
           TomlRbAdapter: "#{__dir__}/toml/toml_rb_adapter",
         )

data/lib/lutaml/key_value/adapter/yaml/yeptris_adapter.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require_relative "../../../yaml/adapter/yeptris_adapter"
+
+module Lutaml
+  module KeyValue
+    module Adapter
+      module Yaml
+        # Backward-compatibility entry for the adapter resolver's default
+        # load path; the implementation lives in Lutaml::Yaml::Adapter.
+        YeptrisAdapter = Lutaml::Yaml::Adapter::YeptrisAdapter
+      end
+    end
+  end
+end

data/lib/lutaml/key_value/transform.rb

@@ -244,6 +244,13 @@ format)
           rule, attr
         )
 
+        if (plan = kv_rule_plan(format, rule, attr)) &&
+            (value = kv_fast_extract(doc, plan))
+          rule.deserialize(instance, kv_fast_cast(value, plan, instance),
+                           attributes, self)
+          return
+        end
+
         value = rule_value_extractor_class.call(rule, doc, format, attr,
                                                 lutaml_register, options, instance)
         value = apply_value_map(value, rule.value_map(:from, options), attr)
@@ -269,6 +276,81 @@ format)
         rule.deserialize(instance, value, attributes, self)
       end
 
+      # Compiled rule plans (TODO.perf/07): for plain scalar rules the
+      # per-value interpretation (extraction dispatch, type resolution,
+      # per-element probes, validation inside casts) collapses to a
+      # precomputed wire name, target class, and identity-guard cast.
+      # Guard + cached target — an inline cache per rule. Complex rules
+      # (custom methods, transforms, value maps, delegates, hash mappings,
+      # unions, polymorphism) return nil and keep the interpretive path.
+      KvRulePlan = ::Struct.new(:wire, :klass, :collection)
+
+      def kv_rule_plan(format, rule, attr)
+        @kv_rule_plans ||= {}
+        @kv_rule_plans[[format, rule]] ||= build_kv_rule_plan(format, rule,
+                                                              attr)
+      end
+
+      # `rule.polymorphic` defaults to an empty Hash, which is truthy —
+      # presence is emptiness-based, mirroring MappingRule#polymorphic_mapping?.
+      def polymorphic_rule?(rule)
+        poly = rule.polymorphic
+        poly.respond_to?(:empty?) ? !poly.empty? : !!poly
+      end
+
+      def build_kv_rule_plan(_format, rule, attr)
+        return nil if rule.raw_mapping? ||
+          rule.has_custom_method_for_deserialization? ||
+          rule.hash_mappings || rule.multiple_mappings? ||
+          polymorphic_rule?(rule) || rule.delegate ||
+          (rule.transform.is_a?(Hash) && !rule.transform.empty?) ||
+          rule.transform.is_a?(Class) ||
+          attr.derived? ||
+          attr.union? || attr.polymorphic? ||
+          attr.custom_collection?
+
+        type = attr.type(lutaml_register)
+        return nil unless type.is_a?(Class) &&
+          type < ::Lutaml::Model::Type::Value &&
+          !attr.value_policy.whole_value?(type) &&
+          !Lutaml::Model::Attribute.custom_from_probe?(type)
+
+        KvRulePlan.new(rule.name.to_s, type, attr.collection?)
+      end
+
+      # Extraction fast path: plain hash fetch for a present, non-blank
+      # value. nil/blank values keep the interpretive path — their
+      # value-map/missing-value semantics must not be duplicated here.
+      def kv_fast_extract(doc, plan)
+        return nil unless doc.is_a?(::Hash)
+
+        v = doc[plan.wire]
+        return nil if v.nil?
+        return nil if v.is_a?(::String) && v.empty?
+        return nil if v.is_a?(::Array) && (v.empty? || !plan.collection)
+        # Structured values on scalar plans keep the interpretive path —
+        # its collection guidance error and cast semantics own them.
+        return nil if v.is_a?(::Hash)
+
+        v
+      end
+
+      # Cast fast path: identity when the value already has the target
+      # class (the overwhelming case for engine-typed scalars), the type's
+      # cast otherwise. Collections cast per element.
+      def kv_fast_cast(value, plan, _instance)
+        if plan.collection
+          unless value.is_a?(::Array)
+            return value.is_a?(plan.klass) ? value : plan.klass.cast(value)
+          end
+
+          klass = plan.klass
+          value.map { |e| e.is_a?(klass) ? e : klass.cast(e) }
+        else
+          value.is_a?(plan.klass) ? value : plan.klass.cast(value)
+        end
+      end
+
       def cast_value(value, attr, format, rule, instance)
         cast_options = rule.polymorphic ? { polymorphic: rule.polymorphic } : {}
         cast_options[:lutaml_parent] = instance if instance

data/lib/lutaml/key_value/transformation/value_serializer.rb

@@ -57,6 +57,14 @@ model_class: nil)
           return nil if value.nil?
           return nil if Lutaml::Model::Utils.uninitialized?(value)
 
+          # Compiled serialize plan (TODO.perf/07): builtin scalars whose
+          # type registers no custom to_<format> serializer serialize as the
+          # value itself — Type::Value#to_<format>'s default — without the
+          # wrap-allocate-cast ceremony per field. Computed once per rule.
+          if (fast = serialize_plan(rule)) && value.instance_of?(fast)
+            return value
+          end
+
           # Check for Reference type first - even if value is a Serializable,
           # it should be serialized as a key, not as a nested model
           if reference_type?(rule)
@@ -151,6 +159,23 @@ model_class: nil)
           end
         end
 
+        # Per-rule serialize plan: the type class for builtin scalars with
+        # no custom to_<format> serializer (identity serialization), nil
+        # otherwise. Memoized per [rule].
+        def serialize_plan(rule)
+          @serialize_plans ||= {}
+          @serialize_plans[rule] ||= begin
+            type = rule.attribute_type
+            if type.is_a?(::Class) && type < ::Lutaml::Model::Type::Value
+              serializer = ::Lutaml::Model::Type::Value
+                .format_type_serializer_for(@format, type)
+              has_custom_to = serializer && serializer[:to]
+              has_custom_from = ::Lutaml::Model::Attribute.custom_from_probe?(type)
+              type unless has_custom_to || has_custom_from
+            end
+          end
+        end
+
         private
 
         # Validate that a nested model value matches the expected type.

data/lib/lutaml/key_value/transformation.rb

@@ -16,6 +16,18 @@ module Lutaml
     # This is a critical step toward symmetric OOP architecture
     # across all serialization formats.
     class Transformation < Lutaml::Model::Transformation
+      # Builtin Value types whose cast of an already-native value is the
+      # identity — used by the serialize_value fast path.
+      NATIVE_VALUE_CLASS = {
+        ::Lutaml::Model::Type::String => ::String,
+        ::Lutaml::Model::Type::Integer => ::Integer,
+        ::Lutaml::Model::Type::Float => ::Float,
+        ::Lutaml::Model::Type::Date => ::Date,
+        ::Lutaml::Model::Type::Time => ::Time,
+        ::Lutaml::Model::Type::DateTime => ::DateTime,
+        ::Lutaml::Model::Type::Symbol => ::Symbol,
+      }.freeze
+
       include Lutaml::Model::RenderPolicy
 
       autoload :RuleCompiler, "#{__dir__}/transformation/rule_compiler"
@@ -1082,7 +1094,19 @@ child_mappings, options)
         # Wrap value in type and call to_#{format} instance method (like legacy Attribute#serialize_value)
         # This allows custom type subclasses to override to_json, to_yaml, etc.
         if rule.attribute_type.is_a?(Class) && rule.attribute_type < Lutaml::Model::Type::Value
-          wrapped_value = rule.attribute_type.new(value)
+          type = rule.attribute_type
+          # Identity fast path (TODO.perf/07): a builtin type with no custom
+          # to_<format>/from_<format> behavior emits an already-native value
+          # unchanged — the wrap only re-casts and re-emits it.
+          native = NATIVE_VALUE_CLASS[type]
+          if native && value.instance_of?(native) &&
+              !::Lutaml::Model::Type::Value
+                  .format_type_serializer_for(format, type)&.fetch(:to, nil) &&
+              !::Lutaml::Model::Attribute.custom_from_probe?(type)
+            return value
+          end
+
+          wrapped_value = type.new(value)
           wrapped_value.public_send(:"to_#{format}")
         else
           value

data/lib/lutaml/model/adapter_resolver.rb

@@ -286,7 +286,7 @@ module Lutaml
           if format == :toml && type_name == :tomlib && RuntimeCompatibility.windows?
             raise ArgumentError,
                   "The `:tomlib` adapter is not supported on Windows due to " \
-                  "segmentation fault issues. Please use `:toml_rb` instead."
+                  "segmentation fault issues. Please use `:teptris` or `:toml_rb` instead."
           end
 
           available = adapter_config[:available]
@@ -363,11 +363,23 @@ module Lutaml
             detect_xml_adapter
           when :toml
             detect_toml_adapter
+          when :yaml, :json
+            detect_yeptris_kv_adapter(format)
           else
             metadata.dig(format, :default)
           end
         end
 
+        # Native key-value engine preference: yeptris (libyeptris C11)
+        # when its gem is in the bundle, else the format's standard
+        # adapter. Opt-in by bundle contents — nothing is required of
+        # consumers that do not add yeptris.
+        def detect_yeptris_kv_adapter(format)
+          return metadata.dig(format, :default) if Lutaml::Model.opal?
+
+          Utils.safe_load("yeptris", :Yeptris) ? :yeptris : metadata.dig(format, :default)
+        end
+
         # Detect available XML adapter.
         #
         # Delegates to moxml which is the authority on XML adapter
@@ -380,17 +392,22 @@ module Lutaml
 
         # Detect available TOML adapter.
         #
-        # @return [Symbol, nil] :tomlib, :toml_rb, or nil
+        # @return [Symbol, nil] :teptris, :tomlib, :toml_rb, or nil
         def detect_toml_adapter
           return nil if Lutaml::Model.opal?
 
-          if RuntimeCompatibility.windows?
-            return :toml_rb if Utils.safe_load("toml-rb", :TomlRb)
+          # teptris 0.2.12+ parses ~3x and dumps ~8x faster than
+          # tomlib and ships prebuilts for every platform (mingw-ucrt
+          # restored in 0.2.4+) — native TOML on Windows retires the
+          # tomlib segfault workaround (previously pure-Ruby toml-rb
+          # only).
+          return :teptris if Utils.safe_load("teptris", :Teptris)
 
-            return nil
+          if !RuntimeCompatibility.windows? &&
+              Utils.safe_load("tomlib", :Tomlib)
+            return :tomlib
           end
 
-          return :tomlib if Utils.safe_load("tomlib", :Tomlib)
           return :toml_rb if Utils.safe_load("toml-rb", :TomlRb)
 
           nil

data/lib/lutaml/model/attribute.rb

@@ -31,6 +31,29 @@ module Lutaml
         union_member_types
       ].freeze
 
+      # Per-type-class memo of the custom from_xml/from_json probe used by #cast.
+      # Isolated cache holder: enclosing-class freezes (some suites freeze
+      # Lutaml::Model::Attribute) would freeze a constant Hash with it.
+      TypeProbeCache = ::Class.new do
+        class << self
+          def cache
+            @cache ||= {}
+          end
+        end
+      end
+
+      class << self
+        # Public reader for compiled rule plans: does this type class carry a
+        # custom from_xml/from_json (answer static, probed once)?
+        def custom_from_probe?(type)
+          TypeProbeCache.cache[type] ||= begin
+            base = Lutaml::Model::Type::Value.singleton_class
+            type.method(:from_xml).owner != base ||
+              type.method(:from_json).owner != base
+          end
+        end
+      end
+
       MODEL_STRINGS = [
         Lutaml::Model::Type::String,
         "String",
@@ -252,7 +275,9 @@ module Lutaml
       end
 
       def union?
-        unresolved_type == Lutaml::Model::Type::Union
+        return @union unless @union.nil?
+
+        @union = unresolved_type == Lutaml::Model::Type::Union
       end
 
       def union_member_types
@@ -687,11 +712,11 @@ instance_object = nil)
 
         # Fast path for Type::Value subclasses (String, Integer, Boolean, etc.)
         # These are never Serializable, so skip expensive can_serialize? and needs_conversion? checks
-        # Skip if type has custom from_xml/from_json methods (defined on the class itself, not inherited)
-        if resolved_type.is_a?(Class) && resolved_type < Lutaml::Model::Type::Value
-          has_custom_from_xml = resolved_type.method(:from_xml).owner != Lutaml::Model::Type::Value
-          has_custom_from_json = resolved_type.method(:from_json).owner != Lutaml::Model::Type::Value
-          return resolved_type.cast(value) unless has_custom_from_xml || has_custom_from_json
+        # Skip if type has custom from_xml/from_json methods (defined on the class itself, not inherited).
+        # The probe allocated two Method objects per cast call; the answer is
+        # static per type class, so it is resolved once.
+        if resolved_type.is_a?(Class) && resolved_type < Lutaml::Model::Type::Value && !self.class.custom_from_probe?(resolved_type)
+          return resolved_type.cast(value)
         end
 
         klass = resolve_polymorphic_class(resolved_type, value, options)

data/lib/lutaml/model/collection.rb

@@ -308,6 +308,10 @@ module Lutaml
         end
 
         def to(format, instance, options = {})
+          # Wrap before the branch, not inside it: only XML reaches the
+          # unwrapped path today, but a raw JSON::State must never survive
+          # into either arm.
+          options = Lutaml::Model::Serialize.wrap_generator_state(options)
           mappings = mappings_for(format)
 
           if mappings.no_root? && collection_unwrapped_to?(format)
@@ -456,6 +460,7 @@ lutaml_register: Lutaml::Model::Config.default_register)
       end
 
       def to_format(format, options = {})
+        options = Lutaml::Model::Serialize.wrap_generator_state(options)
         super(format, options.merge(collection: true))
       end
 

data/lib/lutaml/model/configuration.rb

@@ -15,10 +15,15 @@ module Lutaml
     #
     class Configuration
       attr_reader :default_register
+      # Experimental: whole-document native materialization for plan-
+      # compilable XML models (Leptris::XML::Descriptor walk). Opt-in
+      # while the full semantics audit completes.
+      attr_accessor :xml_plan_fast_path
 
       def initialize
         @default_register = :default
         @configured = false
+        @xml_plan_fast_path = false
       end
 
       def configure

data/lib/lutaml/model/error/unknown_adapter_type_error.rb

@@ -3,10 +3,10 @@ module Lutaml
     class UnknownAdapterTypeError < Error
       # Available adapters by format
       AVAILABLE_ADAPTERS = {
-        xml: %w[nokogiri ox oga rexml],
-        json: %w[standard multi_json oj],
-        yaml: %w[standard],
-        toml: %w[tomlib toml_rb],
+        xml: %w[nokogiri ox oga rexml leptris],
+        json: %w[standard multi_json oj yeptris],
+        yaml: %w[standard yeptris],
+        toml: %w[teptris tomlib toml_rb],
         hash: %w[standard],
         jsonl: %w[standard],
         yamls: %w[standard],

data/lib/lutaml/model/serialization_adapter.rb

@@ -17,7 +17,7 @@ module Lutaml
       end
 
       def self.parse(data, _options = {})
-        document_class.parse(data, create_additions: false)
+        document_class.parse(data)
       end
     end
   end

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

@@ -45,6 +45,11 @@ module Lutaml
         # @param options [Hash] Additional options
         # @return [Object] The deserialized model instance
         def from(format, data, options = {})
+          if format == :xml && Lutaml::Model::Config.instance.xml_plan_fast_path
+            fast = xml_plan_fast_path(data, options)
+            return fast if fast
+          end
+
           Instrumentation.instrument(:from, model: name, format: format) do
             adapter = resolve_adapter(format, options.delete(:adapter))
 
@@ -76,6 +81,36 @@ module Lutaml
           # No-op by default; XML overrides via prepend
         end
 
+        # Whole-document native materialization (Phase 5): compile the
+        # mapping into a Leptris descriptor plan and hydrate from one
+        # plan walk. Only when the resolved XML adapter is leptris-
+        # backed, the model fully compiles, and no path-affecting
+        # options are present; anything else falls back to the
+        # interpretive pipeline.
+        def xml_plan_fast_path(data, options)
+          return nil unless defined?(::Leptris::XML::Descriptor)
+          return nil if options.key?(:adapter) || options.key?(:only) ||
+            options.key?(:except) || options.key?(:mappings) ||
+            options.key?(:register)
+
+          adapter_name = Lutaml::Model::Config.adapter_for(:xml)
+          adapter_name = adapter_name&.name
+          return nil unless adapter_name.to_s.end_with?("LeptrisAdapter")
+
+          register = Lutaml::Model::Config.default_register
+          plan = Lutaml::Xml::PlanCompiler.compile(self, register)
+          return nil unless plan
+
+          root = ::Leptris::XML.parse(data.to_s).root
+          return nil if root.nil?
+          return nil unless root.name == plan[:tree][:name]
+
+          Lutaml::Xml::PlanHydrator.call(self, plan,
+                                         plan[:descriptor].walk(root))
+        rescue ::Leptris::XML::ParseError => e
+          raise Lutaml::Model::InvalidFormatError.new(:xml, e.message)
+        end
+
         # Get list of error types that can be raised during format parsing.
         # Core errors are always included; format-specific errors come from
         # FormatRegistry registrations.
@@ -119,6 +154,8 @@ module Lutaml
           toml_errors = Array(toml_errors)
           tomllib_err = compatibility.safe_constantize("Tomlib::ParseError")
           toml_errors << tomllib_err if tomllib_err
+          teptris_err = compatibility.safe_constantize("Teptris::ParseError")
+          toml_errors << teptris_err if teptris_err
 
           @format_error_types_base + toml_errors
         end
@@ -192,24 +229,55 @@ module Lutaml
         #   is always preserved when available, regardless of this option.
         # @return [String] The serialized output
         def to(format, instance, options = {})
+          # Ruby's JSON generator hands #to_json its own JSON::State rather
+          # than an options hash. It carries no LutaML options, but it does
+          # carry the surrounding indent context, so it is forwarded to the
+          # adapter unchanged instead of being read like a Hash -- json 3.0
+          # removed JSON::State#[].
+          options = Serialize.wrap_generator_state(options)
+          generator_state = options.delete(Serialize::GENERATOR_STATE_KEY)
+
           Instrumentation.instrument(:to, model: name, format: format) do
-            adapter_override = options.is_a?(Hash) && options.delete(:adapter)
-            if adapter_override && options.is_a?(Hash)
-              options[:_adapter_override] =
-                true
-            end
+            adapter_override = options.delete(:adapter)
+            options[:_adapter_override] = true if adapter_override
             value = public_send(:"as_#{format}", instance, options)
             adapter = resolve_adapter(format, adapter_override)
 
             # Hook for format-specific options preparation (e.g., XML prefix/namespace/declaration)
             options = prepare_to_options(format, instance, options)
 
-            adapter.new(value, register: options[:register]).public_send(
-              :"to_#{format}", options
+            document = adapter.new(value, register: options[:register])
+
+            document.public_send(
+              :"to_#{format}",
+              forward_options(document, generator_state, options),
             )
           end
         end
 
+        # Main's behaviour differs per ADAPTER, not per option, so this follows
+        # the adapter rather than trying to translate option names:
+        #   stdlib  honours script_safe / ascii_only / pretty -> give it the state
+        #   Oj      ignores them all and uses its own escape_mode -> give it none
+        #   others  reach the stdlib generator underneath -> give them the options
+        def forward_options(document, generator_state, options)
+          return options if generator_state.nil?
+
+          if declares?(document, :accepts_generator_state?)
+            generator_state
+          elsif declares?(document, :ignores_generator_options?)
+            options
+          elsif generator_state.respond_to?(:to_h)
+            options.merge(generator_state.to_h)
+          else
+            options
+          end
+        end
+
+        def declares?(document, predicate)
+          document.respond_to?(predicate) && document.public_send(predicate)
+        end
+
         # Hook for format-specific options preparation before serialization.
         # XML overrides to handle prefix, namespace overrides, declaration plan.
         #

data/lib/lutaml/model/serialize.rb

@@ -225,7 +225,25 @@ module Lutaml
         self.class.as_yaml(self)
       end
 
+      # Ruby's JSON generator hands #to_json its own JSON::State instead of an
+      # options hash. It carries no LutaML options, but it does carry the
+      # surrounding indent context, so it travels IN BAND under a private key
+      # rather than replacing the options hash. Wrapping rather than returning
+      # early keeps every later step -- register propagation, root-mapping
+      # validation, Collection's `collection: true` merge -- working on a real
+      # Hash. json 3.0 removed JSON::State#[] and rejects unknown keys in
+      # State#merge, so nothing may treat it as a Hash.
+      GENERATOR_STATE_KEY = :_generator_state
+
+      def self.wrap_generator_state(options)
+        return options if options.is_a?(::Hash)
+
+        { GENERATOR_STATE_KEY => options }
+      end
+
       def to_format(format, options = {})
+        options = Lutaml::Model::Serialize.wrap_generator_state(options)
+
         # Hook for format-specific validation (e.g., XML root mapping check)
         validate_root_mapping!(format, options)