lutaml-model 0.8.23 → 0.8.24

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 22cdfc7334bab60076fc98d5153c5770789f2670dc41eeabfee4df3dc6265f99
-  data.tar.gz: fcb7ed45d08960bc739e7b0401771c96cc295a79f0d5236d60c0b8c7edfc54bb
+  metadata.gz: c8aca94b467fe681429ee9863355555d3aa003d9deda8543a74fd1424087bcc8
+  data.tar.gz: 02db8dceef19fc7ef7abd3a54f0936e00ef162a1ee6477191a8b1d3477ba7860
 SHA512:
-  metadata.gz: c2642f2aba35a1eff18d1cc69c3dd44c95f88c80ebb8b76937c10202f0f2527e9c8365be6730fdbd69ee34b44641707714e4d6e0bd2c1cb062176a8d735b7398
-  data.tar.gz: 5cb5c0079ac4d8cb578cab080641e2d4f3d6a6445c1f212080aba556133b8b707afdf86a8508a4df488c859b3fabbe52adf26f324ddaecd1988f4d79338dc2b9
+  metadata.gz: 4da87513ed839ba070c32b28de27411ffe12ccc92f879a0dbe433aad85ea3a32a76759b36112958a131b09a747b1618c0ff8a95e92238aca40f45b736dd46950
+  data.tar.gz: ff488be2b79ef92c3017d63ee0a9bf4ac3b183549be5b17a59efcb42ea31ae00cacb2b63995f9b69fbe3628af9bd65f30dfedb2fb5d2722fe15189c7e964a93b

data/.github/workflows/performance.yml

@@ -16,7 +16,7 @@ permissions:
 jobs:
   performance:
     runs-on: ubuntu-latest
-    timeout-minutes: 20
+    timeout-minutes: 30
     steps:
       - uses: actions/checkout@v6
         with:

data/Gemfile

@@ -19,6 +19,7 @@ gem "benchmark-ips"
 gem "bigdecimal"
 gem "canon" # , path: "../canon"
 gem "json-ld"
+gem "leptris"
 gem "liquid", "~> 5"
 gem "multi_json"
 gem "nokogiri"
@@ -26,8 +27,11 @@ gem "oj"
 gem "openssl", "~> 3.0"
 gem "ox"
 gem "rake"
+# yeptris ships prebuilt platform gems for linux/darwin only; a source
+# build is not wired for windows runners.
 gem "rdf-turtle"
 gem "rexml"
+gem "yeptris" unless Gem.win_platform?
 # TODO: revert rng branch to main when lutaml/rng#32 is merged
 gem "rng", git: "https://github.com/lutaml/rng", branch: "main"
 gem "rspec"
@@ -35,6 +39,8 @@ gem "rubocop"
 gem "rubocop-performance", require: false
 gem "rubocop-rake", require: false
 gem "rubocop-rspec", require: false
+# teptris ships prebuilt gems for every platform (incl. mingw-ucrt)
+gem "teptris"
 gem "tomlib"
 gem "toml-rb"
 

data/README.adoc

@@ -16223,7 +16223,7 @@ Adapters are auto-detected on first use. The defaults when gems are available:
 * YAML: `:standard` (alias: `:standard_yaml`)
 * JSON: `:standard` (alias: `:standard_json`)
 * Hash: `:standard` (alias: `:standard_hash`)
-* TOML: `:tomlib` on non-Windows, `:toml_rb` on Windows
+* TOML: `:teptris` if available, else `:tomlib` on non-Windows, `:toml_rb` on Windows
 
 
 ==== Configure adapters through symbol choices
@@ -16246,7 +16246,7 @@ Lutaml::Model::Config.configure do |config|
   config.hash_adapter = :standard
   config.yaml_adapter = :standard
   config.json_adapter = :standard # can be one of [:standard, :multi_json, :oj]
-  config.toml_adapter = :toml_rb # can be one of [:toml_rb, :tomlib]
+  config.toml_adapter = :toml_rb # can be one of [:teptris, :toml_rb, :tomlib]
 end
 ----
 
@@ -16388,22 +16388,29 @@ end
 
 Lutaml::Model supports the following TOML adapters:
 
+Teptris::
+(default when the `teptris` gem is in the bundle — every platform)
+The native TOML engine (libteptris via FFI). Value semantics mirror
+tomlib: offset and local datetimes become `Time`, dates become `Date`,
+local times stay `String`.
+Requires the `teptris` gem.
+
 Toml-rb::
-(default on Windows)
+(default on Windows without teptris)
 A TOML parser and serializer for Ruby that is compatible with the TOML v1.0.0
 specification.
 Requires the `toml-rb` gem.
 
 Tomlib::
-(default on non-Windows platforms)
+(default on non-Windows platforms without teptris)
 Toml-rb fork that is compatible with the TOML v1.0.0 specification, but with
 additional features.
 Requires the `tomlib` gem.
 
 IMPORTANT: The Tomlib adapter is not available on Windows due to segmentation
-fault issues. On Windows, the `toml-rb` adapter is used automatically as the
-default. If you explicitly configure `tomlib` on Windows, a
-`ConfigurationError` will be raised.
+fault issues. On Windows, the `teptris` adapter (when bundled) or the
+`toml-rb` adapter is used automatically as the default. If you explicitly
+configure `tomlib` on Windows, a `ConfigurationError` will be raised.
 
 
 .Using a TOML adapter
@@ -16412,6 +16419,8 @@ default. If you explicitly configure `tomlib` on Windows, a
 require 'lutaml/model'
 
 Lutaml::Model::Config.configure do |config|
+  config.toml_adapter = :teptris
+  # or
   config.toml_adapter = :toml_rb
   # or (not available on Windows)
   config.toml_adapter = :tomlib

data/docs/_guides/index.adoc

@@ -22,6 +22,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
 
+== Performance
+
+* link:../native-engines[Native engines (leptris / yeptris / teptris)] - Drop-in XML/YAML/JSON/TOML engine upgrades via bundle opt-in
+
 == Linked Data serialization
 
 * link:../rdf-serialization[Unified RDF Serialization] - One `rdf` block for both JSON-LD and Turtle

data/docs/_guides/native-engines.adoc

@@ -0,0 +1,61 @@
+= Native engines (leptris / yeptris / teptris)
+
+By default, `lutaml-model` serializes through the same engines every Ruby
+install already has: Nokogiri (via moxml) for XML, Psych for YAML, the
+`json` gem for JSON.
+
+The leptris family of native engines is a drop-in performance upgrade:
+
+* **leptris** — the XML engine moxml drives. When the `leptris` gem is in
+  your bundle, moxml prefers it over Nokogiri for parsing and
+  serialization.
+* **yeptris** — the YAML/JSON engine. When the `yeptris` gem is in your
+  bundle, lutaml-model's YAML and JSON adapters resolve to the yeptris
+  engine.
+* **teptris** — the TOML engine. When the `teptris` gem is in your
+  bundle it becomes the TOML default on every platform (0.2.12+ parses
+  ~3x and dumps ~8x faster than tomlib, and the Windows mingw-ucrt
+  prebuilts are back), giving Windows native TOML and retiring the
+  tomlib-segfault workaround (previously pure-Ruby toml-rb only).
+
+Opting in is purely a bundle decision — no code changes, no gemspec
+requirements:
+
+[source,sh]
+----
+bundle add leptris yeptris teptris
+----
+
+leptris and yeptris ship prebuilt platform gems for Linux and macOS
+(yeptris has no Windows prebuilts). teptris ships prebuilt gems for
+every platform, including Windows. When a gem is absent, lutaml-model
+automatically falls back to the standard engine for that format.
+
+== Selecting adapters explicitly
+
+The engines register as ordinary adapter types, so explicit selection and
+the availability error messages work as usual:
+
+[source,ruby]
+----
+Lutaml::Model::Config.xml_adapter_type = :leptris
+Lutaml::Model::Config.yaml_adapter_type = :yeptris
+Lutaml::Model::Config.json_adapter_type = :yeptris
+Lutaml::Model::Config.toml_adapter_type = :teptris
+----
+
+== Semantics notes
+
+* **YAML**: the yeptris adapter uses the engine's `compat_11` schema, so
+  implicit typing matches Psych (parity-verified across the scalar
+  battery: dates, timestamps, octal, sexagesimal, `yes`/`no`, `.inf`).
+  Two deliberate differences: anchors and aliases always resolve, and a
+  tagged value without a core type materializes as plain data instead of
+  raising `Psych::DisallowedClass`.
+* **JSON**: `yeptris` parsing targets exact `JSON.parse` semantics;
+  generation stays on the `json` gem.
+* **TOML**: the teptris adapter mirrors tomlib value semantics — offset
+  and local datetimes become `Time`, dates become `Date`, local times
+  stay `String`. Parse failures raise `Teptris::ParseError` with line
+  and column, wrapped as `InvalidFormatError` like the other TOML
+  adapters.

data/docs/_pages/configuration.adoc

@@ -23,7 +23,7 @@ The auto-detection order for each format:
 |===
 | Format | Detection order
 | XML | `:nokogiri` → `:ox` → `:oga` → `:rexml`
-| TOML | `:tomlib` → `:toml_rb` (Windows: `:toml_rb` only)
+| TOML | `:teptris` → `:tomlib` → `:toml_rb` (Windows: `:teptris` → `:toml_rb`)
 | JSON | `:standard` (always available)
 | YAML | `:standard` (always available)
 | Hash | `:standard` (always available)
@@ -109,14 +109,17 @@ When an adapter is needed for a format, `AdapterResolver` follows this chain:
 |===
 | Adapter | Description
 
+| `:teptris` (default when bundled)
+| Native engine (libteptris via FFI), all platforms including Windows. tomlib-compatible value semantics.
+
 | `:tomlib` (default on non-Windows)
 | Enhanced fork. Better performance on non-Windows platforms.
 
-| `:toml_rb` (default on Windows)
-| Pure Ruby. TOML v1.0.0 compatible. Required on Windows.
+| `:toml_rb` (default on Windows without teptris)
+| Pure Ruby. TOML v1.0.0 compatible.
 |===
 
-NOTE: The `:tomlib` adapter is not available on Windows due to segmentation fault issues. On Windows, `:toml_rb` is automatically used as the default.
+NOTE: The `:tomlib` adapter is not available on Windows due to segmentation fault issues. On Windows, `:teptris` (when bundled) or `:toml_rb` is used as the default.
 
 == Per-operation adapter override
 
@@ -226,7 +229,7 @@ If not explicitly configured, Lutaml::Model auto-detects on first use:
 * JSON: `:standard` (alias: `:standard_json`)
 * YAML: `:standard` (alias: `:standard_yaml`)
 * Hash: `:standard` (alias: `:standard_hash`)
-* TOML: `:tomlib` on non-Windows, `:toml_rb` on Windows
+* TOML: `:teptris` if available, else `:tomlib` on non-Windows, `:toml_rb` on Windows
 
 == When to configure
 
@@ -272,8 +275,9 @@ end
 
 === Choose TOML adapter based on
 
-* **Tomlib**: Most projects on non-Windows (better performance)
-* **TomlRb**: Windows platforms (required due to tomlib incompatibility)
+* **Teptris**: Bundled native engine — ~3x faster parse, ~8x faster dump than tomlib, every platform
+* **Tomlib**: Non-Windows projects without teptris (better performance)
+* **TomlRb**: Windows platforms without teptris (required due to tomlib incompatibility)
 
 == Opal runtime compatibility
 

data/docs/_pages/serialization_adapters.adoc

@@ -48,7 +48,7 @@ more information.
 Adapters are resolved lazily on first use. If no adapter is explicitly configured, `AdapterResolver` probes for available gems in a preferred order:
 
 * **XML**: `:nokogiri` → `:ox` → `:oga` → `:rexml`
-* **TOML**: `:tomlib` → `:toml_rb` (Windows: `:toml_rb` only)
+* **TOML**: `:teptris` → `:tomlib` → `:toml_rb` (Windows: `:teptris` → `:toml_rb`)
 * **JSON/YAML/Hash**: `:standard` (always available)
 
 The detection result is cached after the first probe, so it only runs once per format.
@@ -84,7 +84,7 @@ There is a default configuration for adapters for commonly used formats:
 * YAML: `:standard` (alias: `:standard_yaml`)
 * JSON: `:standard` (alias: `:standard_json`)
 * Hash: `:standard` (alias: `:standard_hash`)
-* TOML: `:tomlib` on non-Windows, `:toml_rb` on Windows
+* TOML: `:teptris` if available, else `:tomlib` on non-Windows, `:toml_rb` on Windows
 
 
 ==== Configure adapters through symbol choices
@@ -107,7 +107,7 @@ Lutaml::Model::Config.configure do |config|
   config.hash_adapter = :standard
   config.yaml_adapter = :standard
   config.json_adapter = :standard # can be one of [:standard, :multi_json, :oj]
-  config.toml_adapter = :toml_rb # can be one of [:toml_rb, :tomlib] (tomlib not available on Windows)
+  config.toml_adapter = :toml_rb # can be one of [:teptris, :toml_rb, :tomlib] (tomlib not available on Windows)
 end
 ----
 
@@ -285,8 +285,16 @@ end
 
 Lutaml::Model supports the following TOML adapters:
 
+Teptris::
+(default when the `teptris` gem is in the bundle — every platform)
+The native TOML engine (libteptris via FFI). Value semantics mirror
+tomlib: offset and local datetimes become `Time`, dates become `Date`,
+local times stay `String`. Parse failures raise `Teptris::ParseError`
+with line and column.
+Requires the `teptris` gem.
+
 Tomlib::
-(default on non-Windows)
+(default on non-Windows when teptris is absent)
 Toml-rb fork that is compatible with the TOML v1.0.0 specification, with
 additional features and better performance.
 Requires the `tomlib` gem.
@@ -348,4 +356,5 @@ raised to indicate that the input format is malformed and cannot be parsed.
 
 NOTE: The `:tomlib` TOML adapter is disabled on Windows due to segmentation
 fault issues. Attempting to configure `:tomlib` on Windows will raise an
-`ArgumentError`. Use `:toml_rb` on Windows instead.
+`ArgumentError`. Use `:teptris` (native, all platforms) or `:toml_rb` on
+Windows instead.

data/lib/compat/opal/lutaml_model_boot.rb

@@ -167,6 +167,8 @@ require "lutaml/xml/oga"
 require "lutaml/xml/parse_session"
 require "lutaml/xml/parsed_namespace_declaration"
 require "lutaml/xml/parsed_namespace_set"
+require "lutaml/xml/plan_compiler"
+require "lutaml/xml/plan_hydrator"
 require "lutaml/xml/polymorphic_value_handler"
 require "lutaml/xml/qualified_inheritance_strategy"
 require "lutaml/xml/rexml"

data/lib/lutaml/json/adapter/multi_json_adapter.rb

@@ -16,6 +16,8 @@ module Lutaml
                 "multi_json gem is not available. Please add 'multi_json' to your Gemfile."
         end
 
+        INTERNAL_LUTAML_KEYS = %i[register adapter _adapter_override].freeze
+
         # rubocop:disable Style/ArgumentsForwarding -- anonymous * requires Ruby 3.2+
         def to_json(*args)
           require "multi_json"
@@ -28,7 +30,16 @@ module Lutaml
                                       @attributes
                                     end
 
-          MultiJson.dump(attributes_to_serialize, *args)
+          # LutaML's own threading keys must not reach the backend; the
+          # rest (e.g. :pretty) are meaningful to multi_json. The json
+          # gem 3.x and Oj raise on unknown generator options, unlike
+          # json 2.x which ignored them.
+          dump_args = args.map do |arg|
+            next arg unless arg.is_a?(::Hash)
+
+            arg.except(*INTERNAL_LUTAML_KEYS)
+          end
+          MultiJson.dump(attributes_to_serialize, *dump_args)
         # rubocop:enable Style/ArgumentsForwarding
         rescue LoadError
           raise LoadError,

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

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require "yeptris"
+require_relative "standard_adapter"
+
+module Lutaml
+  module Json
+    module Adapter
+      # JSON parsing over the yeptris engine: Yeptris::JSON.load targets
+      # exact JSON.parse semantics (spec-pinned upstream), with a fused
+      # native materializer when the loaded libyeptris build carries it.
+      # Generation stays on the json gem (the yeptris JSON surface is
+      # load-only), so everything else inherits from the standard adapter.
+      class YeptrisAdapter < StandardAdapter
+        def self.parse(json, _options = {})
+          ::Yeptris::JSON.load(json)
+        end
+      end
+    end
+  end
+end

data/lib/lutaml/json/adapter.rb

@@ -14,6 +14,7 @@ module Lutaml
         self,
         OjAdapter: "#{__dir__}/adapter/oj_adapter",
         MultiJsonAdapter: "#{__dir__}/adapter/multi_json_adapter",
+        YeptrisAdapter: "#{__dir__}/adapter/yeptris_adapter",
       )
     end
   end

data/lib/lutaml/json/format.rb

@@ -52,7 +52,7 @@ Lutaml::Model::FormatRegistry.register(
   transformer: Lutaml::Json::Adapter::Transform,
   key_value: true,
   adapter_options: {
-    available: %i[standard standard_json multi_json oj],
+    available: %i[standard standard_json multi_json oj yeptris],
     default: :standard,
   },
 )

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

@@ -20,6 +20,8 @@ module Lutaml
                   "multi_json gem is not available. Please add 'multi_json' to your Gemfile."
           end
 
+          INTERNAL_LUTAML_KEYS = %i[register adapter _adapter_override].freeze
+
           # rubocop:disable Style/ArgumentsForwarding -- anonymous * requires Ruby 3.2+
           def to_json(*args)
             require "multi_json"
@@ -32,7 +34,20 @@ module Lutaml
                                         @attributes
                                       end
 
-            MultiJson.dump(attributes_to_serialize, *args)
+            # LutaML's own options must not reach the backend: the json
+            # gem 3.x and Oj both raise on unknown generator options
+            # (multi_json's backend choice shifts with the resolved json
+            # version), unlike json 2.x which ignored them.
+            # LutaML's own threading keys must not reach the backend; the
+            # rest (e.g. :pretty) are meaningful to multi_json. The json
+            # gem 3.x and Oj raise on unknown generator options, unlike
+            # json 2.x which ignored them.
+            dump_args = args.map do |arg|
+              next arg unless arg.is_a?(::Hash)
+
+              arg.except(*INTERNAL_LUTAML_KEYS)
+            end
+            MultiJson.dump(attributes_to_serialize, *dump_args)
           # rubocop:enable Style/ArgumentsForwarding
           rescue LoadError
             raise LoadError,

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/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