lutaml-model 0.8.162 → 0.8.164

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 333f71c814c51af046e9e0cfa68eb93dabe046153a74a94ff586ccea9696afae
4
- data.tar.gz: 52e12f6ec98df9bc559029651bf83334297010a2cd772a1cb4611576bb78ba39
3
+ metadata.gz: 275cd9d521b7b596a1ea073bf457229bc274799e8602d402035092d42bf30e4a
4
+ data.tar.gz: becd3ddf02a8cd82046f145795df6ce1cec789352f301f8205a57295d6f2d4f0
5
5
  SHA512:
6
- metadata.gz: 3b2dc878baca82c5de267022e628297de2148bbf5546c9c377ab102d2f31c412f44c688096e4799acaf731a15ef1af4418edb3cfb7ae50d4797d62331eb7ffa8
7
- data.tar.gz: a172603c20219fa5db6c5c5ed54088a4dd9903143d00e9ab8a58a24b806cafbf271f504d286c4db1690a66d11418b2c0e81f283e982ee3e17e41306b09a231be
6
+ metadata.gz: d9b68f5709b5b30252cd052ca137bdbcb68022e94c5a9f35140e940e47f56b85498a9bcb6dbd90be37903aee74eb8c95355bf7aa4020dfcd4d9535442db036aa
7
+ data.tar.gz: cbefb8505a65a71c00b355f9810cf21a0781fbf334f0b0c0bbded775265b77e5c5929b3a942081a793ac3bd1be2c64ddd7fd94ec8869b3b446b5cbeeadab9c5e
data/Gemfile CHANGED
@@ -49,7 +49,7 @@ gem "rexml"
49
49
  # exact-URI attribute rows, nested-attribute capture, wildcard rows,
50
50
  # walk-side ns retention and leniency, :unqualified rows, and the
51
51
  # address-based text attach all ride it.
52
- gem "leptris", ">= 1.9.351.1"
52
+ gem "leptris", ">= 1.9.406.0" # RAW op (leptris#1941): the packet fast path needs PLAN_OP_RAW + row identity
53
53
  gem "teptris"
54
54
  gem "yeptris" unless Gem.win_platform?
55
55
  # TODO: revert rng branch to main when lutaml/rng#32 is merged
@@ -0,0 +1,125 @@
1
+ # frozen_string_literal: true
2
+
3
+ # Deterministic KV materialization/serialization benchmark (campaign
4
+ # instrument; no external corpora). Measures from_yamls and to_yaml on
5
+ # a seeded synthetic corpus shaped like real registry documents:
6
+ # repeatable across machines and independent of downstream-gem drift.
7
+ #
8
+ # Usage: bundle exec ruby bench/bench_kv_materialization.rb [DOCS] [ITERATIONS]
9
+
10
+ require "bundler/setup"
11
+ require "lutaml/model"
12
+ require "lutaml/yaml"
13
+
14
+ Lutaml::Model::Config.configure do |config|
15
+ config.yaml_adapter_type = :standard
16
+ end
17
+
18
+ module KvBench
19
+ class Entry < Lutaml::Model::Serializable
20
+ attribute :name, :string
21
+ attribute :value, :integer
22
+ attribute :active, :boolean
23
+ attribute :tags, :string, collection: true
24
+
25
+ key_value do
26
+ map "name", to: :name
27
+ map "value", to: :value
28
+ map "active", to: :active
29
+ map "tags", to: :tags
30
+ end
31
+ end
32
+
33
+ class Meta < Lutaml::Model::Serializable
34
+ attribute :language, :string
35
+ attribute :source, :string
36
+ attribute :revision, :integer
37
+
38
+ key_value do
39
+ map "language", to: :language
40
+ map "source", to: :source
41
+ map "revision", to: :revision
42
+ end
43
+ end
44
+
45
+ class Doc < Lutaml::Model::Serializable
46
+ attribute :id, :string
47
+ attribute :status, :string, values: %w[draft published withdrawn]
48
+ attribute :score, :float
49
+ attribute :meta, Meta
50
+ attribute :entries, Entry, collection: true
51
+
52
+ key_value do
53
+ map "id", to: :id
54
+ map "status", to: :status
55
+ map "score", to: :score
56
+ map "meta", to: :meta
57
+ map "entries", to: :entries
58
+ end
59
+ end
60
+
61
+ module_function
62
+
63
+ def corpus(docs, seed: 42)
64
+ rng = Random.new(seed)
65
+ Array.new(docs) do |i|
66
+ {
67
+ "id" => "doc-#{i}",
68
+ "status" => %w[draft published withdrawn][rng.rand(3)],
69
+ "score" => (rng.rand * 100).round(3),
70
+ "meta" => {
71
+ "language" => %w[en fr ja][rng.rand(3)],
72
+ "source" => "src-#{rng.rand(20)}",
73
+ "revision" => rng.rand(50),
74
+ },
75
+ "entries" => Array.new(2 + rng.rand(4)) do |j|
76
+ {
77
+ "name" => "entry-#{i}-#{j}",
78
+ "value" => rng.rand(10_000),
79
+ "active" => rng.rand(2).zero?,
80
+ "tags" => Array.new(1 + rng.rand(3)) { |t| "tag-#{rng.rand(30)}-#{t}" },
81
+ }
82
+ end,
83
+ }
84
+ end
85
+ end
86
+
87
+ def measure(label, docs, iterations)
88
+ # Warm caches once (docs are already-serialized YAML strings for
89
+ # the from_yaml lane, model instances for the to_yaml lane).
90
+ docs.first(10).each { |d| d.is_a?(::String) ? Doc.from_yaml(d) : Doc.from_yaml(d.to_yaml) }
91
+
92
+ times = []
93
+ allocs = []
94
+ iterations.times do
95
+ GC.start
96
+ a0 = GC.stat[:total_allocated_objects]
97
+ t0 = Process.clock_gettime(Process::CLOCK_MONOTONIC)
98
+ yield
99
+ t1 = Process.clock_gettime(Process::CLOCK_MONOTONIC)
100
+ a1 = GC.stat[:total_allocated_objects]
101
+ times << (t1 - t0)
102
+ allocs << (a1 - a0)
103
+ end
104
+ ms = times.min * 1000 / docs.size
105
+ alloc = allocs.min.to_f / docs.size
106
+ puts format("%<label>-18s %<ms>7.3f ms/doc %<alloc>8.1f allocs/doc",
107
+ label: label, ms: ms, alloc: alloc)
108
+ end
109
+ end
110
+
111
+ if $PROGRAM_NAME == __FILE__
112
+ docs_n = (ARGV[0] || 400).to_i
113
+ iters = (ARGV[1] || 3).to_i
114
+ raws = KvBench.corpus(docs_n)
115
+ yamls = raws.map(&:to_yaml)
116
+ parsed = yamls.map { |y| KvBench::Doc.from_yaml(y) }
117
+
118
+ puts "kv materialization bench: #{docs_n} docs, #{iters} iters"
119
+ KvBench.measure("from_yaml", yamls, iters) do
120
+ yamls.each { |y| KvBench::Doc.from_yaml(y) }
121
+ end
122
+ KvBench.measure("to_yaml", parsed, iters) do
123
+ parsed.each(&:to_yaml)
124
+ end
125
+ end
@@ -195,6 +195,7 @@ require "lutaml/yaml/format"
195
195
  require "lutaml/yaml/schema"
196
196
  require "lutaml/yamlld/adapter"
197
197
  require "lutaml/yamls/adapter"
198
+ require "lutaml/yamls/adapter_loader"
198
199
  require "lutaml/yamls/format"
199
200
  require "lutaml/hash_format/adapter/document"
200
201
  require "lutaml/hash_format/adapter/mapping"
@@ -437,6 +438,7 @@ require "lutaml/yamls/adapter/standard_adapter"
437
438
  require "lutaml/yamls/adapter/transform"
438
439
  require "lutaml/yamls/adapter/yamls_sequence"
439
440
  require "lutaml/yamls/adapter/yamls_sequence_rule"
441
+ require "lutaml/yamls/adapter/yeptris_adapter"
440
442
  require "lutaml/key_value/adapter/hash/document"
441
443
  require "lutaml/key_value/adapter/hash/mapping"
442
444
  require "lutaml/key_value/adapter/hash/mapping_rule"
@@ -174,6 +174,12 @@ module Lutaml
174
174
  existing << rule
175
175
  end
176
176
  end
177
+ # A later DSL block (e.g. a mixin-installed key_value combined
178
+ # with an in-class one) mutates @mappings directly — the frozen
179
+ # flattened memo must not outlive it (lutaml-model#1122: the
180
+ # InternetDraft "version" rule vanished from to_hash when the
181
+ # memo was built before the second block ran).
182
+ @flattened_mappings = nil
177
183
  end
178
184
 
179
185
  # Index of the prior partition a when_attribute rule replaces
@@ -223,6 +229,7 @@ module Lutaml
223
229
  with: with,
224
230
  delegate: delegate,
225
231
  )]
232
+ @flattened_mappings = nil
226
233
  end
227
234
 
228
235
  alias map_all_content map_all
@@ -263,8 +270,19 @@ module Lutaml
263
270
  end
264
271
 
265
272
  def mappings(register_id = nil)
266
- ensure_mappings_imported!(register_id) if finalized?
267
- mappings_hash(register_id).values.flatten
273
+ unless finalized?
274
+ return mappings_hash(register_id).values.flatten
275
+ end
276
+
277
+ # Post-finalize the rule list is immutable: imports resolve
278
+ # before this memo is built (the guard runs first), the DSL only
279
+ # mutates during class definition, and the writer clears the
280
+ # memo. The per-call `.values.flatten` (plus the merged hash for
281
+ # non-default registers) was the serialize lane's top our-side
282
+ # allocation line on the synthetic KV corpus.
283
+ ensure_mappings_imported!(register_id)
284
+ (@flattened_mappings ||= {})[register_id] ||=
285
+ mappings_hash(register_id).values.flatten.freeze
268
286
  end
269
287
 
270
288
  def mappings_hash(register_id = nil)
@@ -289,6 +307,9 @@ module Lutaml
289
307
  register_id).mappings_hash),
290
308
  )
291
309
  end
310
+ # Import resolution mutates the raw rule store after the memo may
311
+ # have been built by an earlier access.
312
+ @flattened_mappings = nil
292
313
  end
293
314
 
294
315
  def validate!(key, to, with, render_nil, render_empty)
@@ -351,7 +351,9 @@ child_mappings)
351
351
  # index and the pair arrays were the lane's biggest allocation
352
352
  # (~6 arrays per node on hydrate-heavy corpora).
353
353
  values = Array.new(rows.size, MISSING)
354
- children = []
354
+ # Lazy: the scalar hot path never pushes a child; the shared
355
+ # wiring pass tolerates nil.
356
+ children = nil
355
357
  # Lazy: the present-key hot path never pushes, and this runs
356
358
  # once per hydrated model instance.
357
359
  absent = nil
@@ -397,7 +399,7 @@ child_mappings)
397
399
  child_hash, format, { mappings: type.child_rules })
398
400
  end
399
401
  values[i] = built
400
- children.concat(built)
402
+ (children ||= []).concat(built)
401
403
  i += 1
402
404
  next
403
405
  end
@@ -427,7 +429,7 @@ child_hash, format, { mappings: type.child_rules })
427
429
  built << child
428
430
  end
429
431
  values[i] = built
430
- children.concat(built)
432
+ (children ||= []).concat(built)
431
433
  else
432
434
  return nil unless v.is_a?(::Hash)
433
435
 
@@ -437,23 +439,26 @@ child_hash, format, { mappings: type.child_rules })
437
439
  return nil if child.nil?
438
440
 
439
441
  values[i] = child
440
- children << child
442
+ (children ||= []) << child
441
443
  end
442
444
  i += 1
443
445
  end
444
446
  instance = model_class.allocate_for_walk(register)
445
447
  i = 0
446
- rows.each do |rule, _attr, kind, *_rest|
448
+ # Index access, not block-parameter splat: `*_rest` re-sliced a
449
+ # fresh Array per row per instance (the walk's largest our-side
450
+ # allocation line on the synthetic KV corpus).
451
+ rows.each do |row|
447
452
  v = values[i]
448
453
  i += 1
449
- next if v.equal?(MISSING) || kind == :unmapped
454
+ next if v.equal?(MISSING) || row[2] == :unmapped
450
455
 
451
- instance.public_send(rule.kv_setter, v)
456
+ instance.public_send(row[0].kv_setter, v)
452
457
  end
453
458
  absent&.each do |rule|
454
459
  process_mapping_rule(doc, instance, format, rule, options, nil)
455
460
  end
456
- children.each do |child|
461
+ children&.each do |child|
457
462
  child.lutaml_parent = instance
458
463
  child.lutaml_root ||= instance.lutaml_root || instance
459
464
  end
@@ -173,6 +173,14 @@ model_class: nil)
173
173
  if plan[:identity_type] && !value.is_a?(::Lutaml::Model::Serialize) && !value.is_a?(::Hash) && !value.is_a?(::Array)
174
174
  return value
175
175
  end
176
+ # Structured data stored on a builtin-scalar-declared
177
+ # attribute (the #1114 parse tolerance) emits verbatim; a
178
+ # registered custom serializer keeps its shaping contract.
179
+ if value.is_a?(::Hash) &&
180
+ !::Lutaml::Model::Type::Value
181
+ .format_type_serializer_for(format, rule.attribute_type)&.fetch(:to, nil)
182
+ return value
183
+ end
176
184
  if (to_fn = plan[:to_fn])
177
185
  return to_fn.call(rule.attribute_type.new(value))
178
186
  end
@@ -1254,6 +1254,17 @@ child_mappings, options)
1254
1254
  # This allows custom type subclasses to override to_json, to_yaml, etc.
1255
1255
  if rule.attribute_type.is_a?(Class) && rule.attribute_type < Lutaml::Model::Type::Value
1256
1256
  type = rule.attribute_type
1257
+ # Structured data stored on a builtin-scalar-declared
1258
+ # attribute (the #1114 tolerance) emits verbatim — wrapping
1259
+ # it stringifies (to_s of the hash) and destroys it on the
1260
+ # round trip. Custom subclasses with a registered serializer
1261
+ # keep their shaping contract.
1262
+ if value.is_a?(::Hash) &&
1263
+ !::Lutaml::Model::Type::Value
1264
+ .format_type_serializer_for(format, type)&.fetch(:to, nil)
1265
+ return value
1266
+ end
1267
+
1257
1268
  # Identity fast path (TODO.perf/07): a builtin type with no custom
1258
1269
  # to_<format>/from_<format> behavior emits an already-native value
1259
1270
  # unchanged — the wrap only re-casts and re-emits it.
@@ -1265,8 +1276,16 @@ child_mappings, options)
1265
1276
  return value
1266
1277
  end
1267
1278
 
1268
- wrapped_value = type.new(value)
1269
- wrapped_value.public_send(:"to_#{format}")
1279
+ # Known KV formats resolve without allocating (the instance
1280
+ # freezes after compile, so no per-call ivar memo is possible;
1281
+ # the interpolated fallback covers exotic formats).
1282
+ reader = case format
1283
+ when :yaml then :to_yaml
1284
+ when :json then :to_json
1285
+ when :toml then :to_toml
1286
+ else :"to_#{format}"
1287
+ end
1288
+ type.new(value).public_send(reader)
1270
1289
  else
1271
1290
  value
1272
1291
  end
@@ -435,14 +435,39 @@ module Lutaml
435
435
  def detect_yeptris_kv_adapter(format)
436
436
  default = metadata.dig(format, :default)
437
437
  return default if Lutaml::Model.opal?
438
- return default unless yeptris_opted_in?
438
+
439
+ unless yeptris_opted_in?
440
+ warn_yeptris_present_once(format)
441
+ return default
442
+ end
439
443
  return default unless Utils.safe_load("yeptris", :Yeptris)
440
444
 
441
445
  load_adapter(format, :yeptris).available? ? :yeptris : default
442
446
  end
443
447
 
448
+ # The consumer-neutral opt-in; FONTIST_YAML=yeptris stays honored
449
+ # as the legacy spelling fontist and lutaml-store already ship
450
+ # (#1115: glossarist is not fontist — the switch must not carry
451
+ # one consumer's namespace).
444
452
  def yeptris_opted_in?
445
- ENV["FONTIST_YAML"] == "yeptris"
453
+ %w[LUTAML_YAML FONTIST_YAML].any? { |k| ENV[k] == "yeptris" }
454
+ end
455
+
456
+ # Make the gated engine visible (#1115 ask 3): a process whose
457
+ # bundle merely contains yeptris used to get it auto-selected;
458
+ # the gate keeps that from happening silently, but the presence
459
+ # of an unused native engine is exactly the kind of fact an
460
+ # upgrading consumer needs to see once.
461
+ def warn_yeptris_present_once(_format)
462
+ return if Lutaml::Model.opal?
463
+ return if @yeptris_presence_warned
464
+ return unless Utils.safe_load("yeptris", :Yeptris)
465
+
466
+ @yeptris_presence_warned = true
467
+ warn "[Lutaml::Model] yeptris is present in this bundle but the " \
468
+ "native YAML engine is not enabled (its parity fixes are " \
469
+ "still landing, leptris/yeptris#863); the standard adapter " \
470
+ "serves YAML. Enable explicitly with LUTAML_YAML=yeptris."
446
471
  end
447
472
 
448
473
  # Detect available XML adapter.
@@ -607,11 +607,41 @@ module Lutaml
607
607
  cast_element_present(value, register, resolved_type)
608
608
  end
609
609
 
610
+ # Builtin scalars whose parse of structured data passes the data
611
+ # through verbatim (#1114) instead of wrapping it — custom
612
+ # Type::Value subclasses keep the wrapper/shaping contract.
613
+ # Lazy: the Type constants load after this class body.
614
+ def self.native_value_types
615
+ @native_value_types ||= [
616
+ Type::String, Type::Integer, Type::Float, Type::Date,
617
+ Type::Time, Type::DateTime, Type::Symbol
618
+ ].each_with_object({}.compare_by_identity) { |t, h| h[t] = true }
619
+ end
620
+
610
621
  def cast_element_present(value, register, resolved_type = nil)
611
622
  resolved_type ||= type(register)
612
623
 
613
624
  return cast_union(value, nil, register) if union?
614
- return resolved_type.new(value) if value.is_a?(::Hash) && !hash_type?
625
+
626
+ # The Hash branch is the nested-model constructor path: only a
627
+ # Serializable element type builds from a hash document. A
628
+ # builtin scalar Value type receiving structured data keeps the
629
+ # data verbatim — stringifying (Type::String#cast's to_s, or a
630
+ # wrapper holding the raw hash in @value) silently destroyed
631
+ # it (lutaml-model#1114, fontist's Google Fonts files map). A
632
+ # CUSTOM Value subclass keeps the wrapper contract: its custom
633
+ # from-shaping receives the hash deliberately (the value-policy
634
+ # contract).
635
+ if value.is_a?(::Hash) && !hash_type?
636
+ # Builtin scalars keep structured data verbatim (#1114 — a
637
+ # to_s or a raw-hash wrapper silently destroyed it); custom
638
+ # Value subclasses keep the wrapper contract (their
639
+ # constructor shapes the hash deliberately), as do
640
+ # Serializable element types.
641
+ return value if self.class.native_value_types.include?(resolved_type)
642
+
643
+ return resolved_type.new(value)
644
+ end
615
645
 
616
646
  # Special handling for Reference types - pass the metadata
617
647
  # (the comparison is attribute-constant; memoize the verdict)
@@ -16,7 +16,14 @@ module Lutaml
16
16
  nil
17
17
  end
18
18
 
19
- attr_writer :mappings
19
+ # Assignments invalidate the per-register flattened-mapping memo
20
+ # (Key-Value mappings memoize `mappings`; the writer is the only
21
+ # post-construction mutation seam — deep_dup builds a fresh
22
+ # instance and reaches this writer).
23
+ def mappings=(value)
24
+ @flattened_mappings = nil
25
+ @mappings = value
26
+ end
20
27
 
21
28
  def initialize
22
29
  @mappings = []
@@ -2,6 +2,6 @@
2
2
 
3
3
  module Lutaml
4
4
  module Model
5
- VERSION = "0.8.162"
5
+ VERSION = "0.8.164"
6
6
  end
7
7
  end