lutaml-model 0.8.118 → 0.8.120

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c5849a4dbcad4fe94ec8f0da69f267dd03eb3d4fdba34515dbc7bad37362e31e
-  data.tar.gz: 0f3b29692d38dc196c88721d7fbb3d05839f405701e3863f0ced62cc693ca1a6
+  metadata.gz: 5a2f85724acebb5e00bf61091dfd3da178b087700420af1f9c8168ea1eb7e579
+  data.tar.gz: 0220370237df57218c474fdc97f72dda7ca0e7183eff0d3aecea6397e7d56232
 SHA512:
-  metadata.gz: 4dccd043421013a6d07dfe20eb2082cc08187d1775dfdb8a3480ce8c1733df06c651c133e9114f94f18a3e1747a038cc22e2a5182f7f6212b263e7da15b7a17d
-  data.tar.gz: c2167269f36cd4d01af8595f4e0a8465614702aa66cb2881bb8cdbf497f0760b4397afee288c93355febdd1f2ffba1f76466ddbc6e3420bec6df35f4169bffae
+  metadata.gz: 6c2dfe1999803b5a232318a871fe71c07ccf7bb8050aa31691918e405b67d1b9bfdd41661f6ec6e7a9e3764c0d6124ed3e1d8d84dc0627dab28698d3f6ce615f
+  data.tar.gz: dc85cfcf2a10c301e80b533a679877f43df5e018428a5b1e19c8e2f50f545064088a955956bbbb6bd19462da5db995e16052ea6b4268fda05b8805a1f3ccb0d6

data/.github/workflows/dependent-repos-tools.json

@@ -0,0 +1,9 @@
+{
+  "repo": [
+    "metanorma/docbook",
+    "metanorma/metanorma-cli",
+    "metanorma/rfcxml",
+    "metanorma/uniword",
+    "ukiryu/ukiryu"
+  ]
+}

data/.github/workflows/dependent-repos.json

@@ -14,22 +14,17 @@
     "lutaml/unibuf",
     "lutaml/xmi",
     "metanorma/atmospheric",
-    "metanorma/docbook",
-    "metanorma/metanorma-cli",
     "metanorma/modspec-ruby",
     "metanorma/niso-jats",
     "metanorma/prosereflect",
     "metanorma/revix",
-    "metanorma/rfcxml",
     "metanorma/sts-ruby",
-    "metanorma/uniword",
     "plurimath/mml",
     "plurimath/plurimath",
     "relaton/ieee-idams",
     "relaton/loc_mods",
     "relaton/w3c_api",
-    "ukiryu/ukiryu",
     "unitsml/unitsdb-ruby",
     "unitsml/unitsml-ruby"
   ]
-}
+}

data/.github/workflows/dependent-tests.yml

@@ -18,10 +18,29 @@ on:
     types: [ release-passed ]
 
 jobs:
+  # Most dependents are pure data/format gems: their suites invoke no
+  # external tools, so skipping the tool install removes the Windows
+  # Chocolatey flake surface (choco CDN 504s killed cells pre-rspec,
+  # e.g. the ukiryu Windows leg) for the majority of the matrix.
   rake:
     uses: metanorma/ci/.github/workflows/dependent-rake.yml@main
     with:
       command: bundle exec rspec
+      repos-json-file: .github/workflows/dependent-repos.json
+      after-setup-ruby: |
+        if [ -f frontend/package.json ]; then cd frontend && npm install && npm run build; fi
+    secrets:
+      pat_token: ${{ secrets.LUTAML_CI_PAT_TOKEN }}
+
+  # Dependents whose suites invoke the tools: ukiryu wraps
+  # inkscape/imagemagick/ghostscript and raises if absent, and its
+  # smoke suite exercises exiftool, yq and ffmpeg too; the metanorma
+  # renderers run full document renders.
+  rake-with-tools:
+    uses: metanorma/ci/.github/workflows/dependent-rake.yml@main
+    with:
+      command: bundle exec rspec
+      repos-json-file: .github/workflows/dependent-repos-tools.json
       setup-tools: 'inkscape,ghostscript,exiftool,ffmpeg,imagemagick,yq'
       after-setup-ruby: |
         if [ -f frontend/package.json ]; then cd frontend && npm install && npm run build; fi

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

@@ -27,16 +27,35 @@ module Lutaml
         private_class_method :require_engine
 
         # True where the yeptris engine loads (libyeptris present for
-        # this platform). Idempotent; a missing or broken install
-        # reports false instead of raising, so optional-engine callers
-        # can gate on it.
+        # this platform) AND answers a probe parse. A require alone
+        # does not prove the engine: a half-initialized Yeptris
+        # constant (the poison-process state the gem documents)
+        # passes const_defined? and require while every parse fails,
+        # and the native parse error then surfaces on valid input.
+        # Any failure — missing native, engine error, or a binding and
+        # native binary out of sync (NameError on a missing FFI surface,
+        # yeptris 0.6.34.2 x64-mingw-ucrt) — reports false instead of
+        # raising, so optional-engine callers (detection) gate on it and
+        # fall back to the standard lane.
         def self.available?
           require_engine
-          true
+          native_ready?
         rescue LoadError
           false
         end
 
+        def self.native_ready?
+          return @native_ready unless @native_ready.nil?
+
+          @native_ready = begin
+            ::Yeptris::JSON.load('{"native_probe": 1}')
+            true
+          rescue StandardError
+            false
+          end
+        end
+        private_class_method :native_ready?
+
         # The parse-error contract is the standard adapter's: invalid
         # input raises JSON::ParserError regardless of the engine, so
         # consumers' rescue ladders (and this gem's own

data/lib/lutaml/model/adapter_resolver.rb

@@ -387,13 +387,21 @@ module Lutaml
         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.
+        # when its gem is in the bundle AND the native engine answers a
+        # probe, else the format's standard adapter. Opt-in by bundle
+        # contents — nothing is required of consumers that do not add
+        # yeptris. The probe matters because a half-initialized Yeptris
+        # constant (the poison-process state the gem documents) passes
+        # const_defined? and require while every parse fails; without
+        # it the lane selection flips with process load order and the
+        # failure surfaces as a native parse error on valid input
+        # instead of a clean standard-lane parse (#978).
         def detect_yeptris_kv_adapter(format)
-          return metadata.dig(format, :default) if Lutaml::Model.opal?
+          default = metadata.dig(format, :default)
+          return default if Lutaml::Model.opal?
+          return default unless Utils.safe_load("yeptris", :Yeptris)
 
-          Utils.safe_load("yeptris", :Yeptris) ? :yeptris : metadata.dig(format, :default)
+          load_adapter(format, :yeptris).available? ? :yeptris : default
         end
 
         # Detect available XML adapter.

data/lib/lutaml/model/union.rb

@@ -154,12 +154,15 @@ module Lutaml
             member.is_a?(::Class) && member.include?(Serialize)
           end
 
-          # Structural (key-coverage) selection: every input key maps to one of
-          # the member's mapped fields, with no input key left unmapped. Once
-          # selected, field values cast leniently via the member's normal path.
-          # An existing member instance conforms as-is, keeping conformance
-          # idempotent — values can re-enter casting (e.g. a value transformer
-          # builds the member before the cast runs).
+          # Structural selection: at least one input key maps to one of the
+          # member's mapped fields. Keys no rule claims are ignored exactly
+          # as they are when the same hash reaches the model outside a
+          # union — extension keys (x-** vendor keywords, forward-compatible
+          # vocabularies) must not defeat dispatch (#987). Once selected,
+          # field values cast leniently via the member's normal path. An
+          # existing member instance conforms as-is, keeping conformance
+          # idempotent — values can re-enter casting (e.g. a value
+          # transformer builds the member before the cast runs).
           def conform_model(member, value, format, register)
             return value if value.is_a?(member)
 
@@ -167,7 +170,7 @@ module Lutaml
             return :no_match if keys.nil? || keys.empty?
 
             field_names = member_field_names(member, format, register)
-            return :no_match unless keys.all? do |key|
+            return :no_match unless keys.any? do |key|
               field_names.include?(key)
             end
 

data/lib/lutaml/model/version.rb

@@ -2,6 +2,6 @@
 
 module Lutaml
   module Model
-    VERSION = "0.8.118"
+    VERSION = "0.8.120"
   end
 end

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

@@ -41,16 +41,36 @@ module Lutaml
         private_class_method :require_engine
 
         # True where the yeptris engine loads (libyeptris present for
-        # this platform). Idempotent; a missing or broken install
-        # reports false instead of raising, so optional-engine callers
-        # can gate on it.
+        # this platform) AND answers a probe parse. A require alone
+        # does not prove the engine: a half-initialized Yeptris
+        # constant (the poison-process state the gem documents)
+        # passes const_defined? and require while every parse fails,
+        # and the native parse error then surfaces on valid input.
+        # Any failure — missing native, engine error, or a binding and
+        # native binary out of sync (NameError on a missing FFI surface,
+        # yeptris 0.6.34.2 x64-mingw-ucrt) — reports false instead of
+        # raising, so optional-engine callers (detection) gate on it and
+        # fall back to the standard lane.
         def self.available?
           require_engine
-          true
+          native_ready?
         rescue LoadError
           false
         end
 
+        def self.native_ready?
+          return @native_ready unless @native_ready.nil?
+
+          @native_ready = begin
+            # rubocop:disable-next Naming/VariableNumber -- upstream schema literal
+            ::Yeptris::YAML.load("native_probe: 1", schema: :compat_11)
+            true
+          rescue StandardError
+            false
+          end
+        end
+        private_class_method :native_ready?
+
         # The parse-error contract is the standard adapter's: invalid
         # input raises Psych::SyntaxError regardless of the engine, so
         # consumers' rescue ladders (and this gem's own

data/spec/lutaml/model/union_attribute_spec.rb

@@ -214,6 +214,25 @@ module UnionAttributeSpec
   end
 end
 
+# Union members for the #987 dispatch contract: an extension-carrying
+# model (keys no rule maps must not defeat dispatch) and a holder
+# mixing it with a scalar member.
+class ExtendedShape < Lutaml::Model::Serializable
+  attribute :type, :string
+
+  key_value do
+    map "type", to: :type
+  end
+end
+
+class ExtendedHolder < Lutaml::Model::Serializable
+  attribute :value, [ExtendedShape, :boolean]
+
+  key_value do
+    map "value", to: :value
+  end
+end
+
 RSpec.describe "Union-typed attributes (issue #190)" do
   describe "deserialization — member resolution by shape" do
     it "resolves a scalar string to the :string member" do
@@ -646,6 +665,38 @@ RSpec.describe "Union-typed attributes (issue #190)" do
     end
   end
 
+  describe "unmapped keys do not defeat model dispatch (#987)" do
+    # ExtendedShape / ExtendedHolder: extension-carrying objects (JSON
+    # Schema vocabularies, OpenAPI x-** keywords) carry keys no rule
+    # maps; the same hash reaches the model member fine outside a
+    # union, so it must inside one too.
+
+    it "selects the model member when mapped and unmapped keys mix" do
+      parsed = ExtendedHolder.from_json(
+        '{"value":{"type":"string","x-ext":1}}',
+      )
+
+      expect(parsed.value).to be_a(ExtendedShape)
+      expect(parsed.value.type).to eq("string")
+    end
+
+    it "still falls through when no key maps to any model member" do
+      parsed = ExtendedHolder.from_json('{"value":true}')
+
+      expect(parsed.value).to be(true)
+    end
+
+    it "returns nil only when no member conforms at all" do
+      holder = Class.new(Lutaml::Model::Serializable) do
+        attribute :value, [ExtendedShape, :boolean]
+        key_value { map "value", to: :value }
+      end
+      stub_const("ExtendedHolderNinetyEight", holder)
+
+      expect(holder.from_json('{"value":{"unrelated":1}}').value).to be_nil
+    end
+  end
+
   describe "value transformers (cast idempotence)" do
     it "keeps a model member built by transform: before the cast runs" do
       reading = UnionAttributeSpec::TransformedReading.from_yaml(<<~YAML)

data/spec/lutaml/model/yeptris_error_parity_spec.rb

@@ -70,7 +70,17 @@ RSpec.describe "yeptris adapter error parity" do
     RUBY
   end
 
-  before { skip "yeptris is not installed" unless yeptris_installed? }
+  # Installed is not enough: a binding/native desync (yeptris
+  # 0.6.34.2 x64-mingw-ucrt) leaves the gem resolvable while every
+  # parse raises. The parity contract only holds when the engines
+  # actually answer a probe — detection then selects them.
+  def yeptris_usable?
+    yeptris_installed? &&
+      Lutaml::Json::Adapter::YeptrisAdapter.available? &&
+      Lutaml::Yaml::Adapter::YeptrisAdapter.available?
+  end
+
+  before { skip "yeptris is not usable on this platform" unless yeptris_usable? }
 
   it "prefers the yeptris adapters when the engine is installed" do
     expect(outcomes).to include("yaml-adapter: Lutaml::Yaml::Adapter::YeptrisAdapter")

data/spec/lutaml/model/yeptris_native_detection_spec.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+require "open3"
+require "lutaml/json/adapter/yeptris_adapter"
+
+# Surface 1 of #978: the yeptris lane was selected from a bare
+# constant check, so a process holding a half-initialized Yeptris
+# module (the poison-process state the gem documents) committed to
+# the native lane and failed pre-mapping on valid JSON — while other
+# processes fell back to the standard lane, flipping the adapter
+# choice across runs. Detection now probes the native engine; a
+# broken native deterministically rides the standard lane.
+RSpec.describe Lutaml::Model::AdapterResolver, ".adapter_for yeptris native detection" do
+  let(:parse_probe) do
+    <<~RUBY
+      require "lutaml/model"
+
+      klass = Class.new(Lutaml::Model::Serializable) do
+        attribute :v, :string
+        key_value { map "v", to: :v }
+      end
+
+      model = klass.from_json('{"v": "scalar"}')
+      adapter = Lutaml::Model::AdapterResolver.adapter_for(:json)
+      puts "ADAPTER=\#{adapter.name.split('::').last} PARSED=\#{model.v}"
+    RUBY
+  end
+
+  # The gem resolving is not enough: a binding/native desync leaves
+  # yeptris loadable while every parse raises. The healthy-lane spec
+  # is only meaningful where the native answers a probe.
+  def subprocess_yeptris_capable?
+    probe = <<~RUBY
+      begin
+        require "yeptris"
+        require "lutaml/json/adapter/yeptris_adapter"
+        exit(Lutaml::Json::Adapter::YeptrisAdapter.available? ? 0 : 1)
+      rescue LoadError, StandardError
+        exit(1)
+      end
+    RUBY
+    _out, _err, status = Open3.capture3(RbConfig.ruby, "-I", "lib", "-e", probe)
+    status.success?
+  end
+
+  it "resolves the yeptris lane when the native engine answers a probe" do
+    skip "optional yeptris engine not resolvable outside the bundle" unless subprocess_yeptris_capable?
+
+    stdout, stderr, status = Open3.capture3(RbConfig.ruby, "-I", "lib", "-e", parse_probe)
+    expect(status).to be_success, stderr
+    expect(stdout).to include("ADAPTER=YeptrisAdapter")
+    expect(stdout).to include("PARSED=scalar")
+  end
+
+  it "falls back to the standard lane when the native engine cannot parse" do
+    poison = <<~RUBY
+      require "lutaml/model"
+      require "yeptris"
+      require "lutaml/json/adapter/yeptris_adapter"
+
+      # The poison state: the module is defined and require succeeds,
+      # but every native parse fails. Whatever the cause (a stale
+      # libyeptris, a half-initialized load), the lane must not be
+      # selected.
+      Lutaml::Json::Adapter::YeptrisAdapter
+        .define_singleton_method(:native_ready?) { false }
+
+      #{parse_probe}
+    RUBY
+
+    stdout, stderr, status = Open3.capture3(RbConfig.ruby, "-I", "lib", "-e", poison)
+    expect(status).to be_success, stderr
+    expect(stdout).to include("ADAPTER=StandardAdapter")
+    expect(stdout).to include("PARSED=scalar")
+  end
+
+  it "reports the adapter unavailable when the native probe fails" do
+    allow(Lutaml::Json::Adapter::YeptrisAdapter)
+      .to receive(:native_ready?).and_return(false)
+
+    expect(Lutaml::Json::Adapter::YeptrisAdapter.available?).to be(false)
+  ensure
+    allow(Lutaml::Json::Adapter::YeptrisAdapter)
+      .to receive(:native_ready?).and_call_original
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: lutaml-model
 version: !ruby/object:Gem::Version
-  version: 0.8.118
+  version: 0.8.120
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-10-20 00:00:00.000000000 Z
+date: 2026-10-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base64
@@ -155,6 +155,7 @@ files:
 - ".envrc"
 - ".github/scripts/test_installed_gem.rb"
 - ".github/workflows/dependent-repos-todo.json"
+- ".github/workflows/dependent-repos-tools.json"
 - ".github/workflows/dependent-repos.json"
 - ".github/workflows/dependent-tests.yml"
 - ".github/workflows/docs.yml"
@@ -1900,6 +1901,7 @@ files:
 - spec/lutaml/model/yamls_sequence_spec.rb
 - spec/lutaml/model/yamls_spec.rb
 - spec/lutaml/model/yeptris_error_parity_spec.rb
+- spec/lutaml/model/yeptris_native_detection_spec.rb
 - spec/lutaml/model_spec.rb
 - spec/lutaml/rdf/context_spec.rb
 - spec/lutaml/rdf/graph_serialization_spec.rb