moxml 0.5.170 → 0.5.172

data/lib/moxml/adapter/customized_oga/xml_generator.rb

@@ -1,6 +1,6 @@
 # rubocop:disable Style/FrozenStringLiteralComment
 
-require "oga"
+# Lifecycle record: engine gap (upstream oga); see the patched-class URL below.require "oga"
 
 # monkey patch the Oga generator because it's not configurable
 # https://github.com/yorickpeterse/oga/blob/main/lib/oga/xml/generator.rb

data/lib/moxml/adapter/customized_oga.rb

@@ -2,6 +2,10 @@
 
 module Moxml
   module Adapter
+    # Lifecycle record (#495): every override serves the :oga adapter,
+    # deprecated in moxml#491 and deleted with the Opal surface in
+    # moxml#489 phase 4. No separate upstream ask -- the adapter's
+    # fate governs this file.
     module CustomizedOga
       autoload :EntityDecoderOverride, "moxml/adapter/customized_oga/entity_decoder"
       autoload :RawValueOverride, "moxml/adapter/customized_oga/raw_value_override"

data/lib/moxml/adapter/customized_ox/attribute.rb

@@ -1,5 +1,10 @@
 # frozen_string_literal: true
 
+# Engine gap (upstream ox): an ::Ox::Attribute carries no parent
+# back-reference and no prefix slots, so the facade's attribute node
+# contract needs this Node subclass. Upstream tracker:
+# https://github.com/ohler55/ox
+
 module Moxml
   module Adapter
     module CustomizedOx

data/lib/moxml/adapter/customized_ox/entity_reference.rb

@@ -1,5 +1,10 @@
 # frozen_string_literal: true
 
+# Parse-path alias: ox expands the built-in entities at parse time and
+# has no reference nodes, so parsed references are the facade's
+# Moxml::Entity::Reference values. Lifecycle: the :ox adapter is
+# deprecated (#491) — this record dies with it.
+
 module Moxml
   module Adapter
     module CustomizedOx

data/lib/moxml/adapter/customized_ox/namespace.rb

@@ -1,5 +1,10 @@
 # frozen_string_literal: true
 
+# Engine gap (upstream ox): ox has no Namespace node class — prefixes
+# live as attribute spellings — so the facade's namespace node contract
+# needs this value object. Upstream tracker:
+# https://github.com/ohler55/ox
+
 module Moxml
   module Adapter
     module CustomizedOx

data/lib/moxml/adapter/customized_ox/text.rb

@@ -1,5 +1,11 @@
 # frozen_string_literal: true
 
+# Engine gap (upstream ox): Ox uses Strings for text content, but a
+# String cannot carry a @parent back-reference; this ::Ox::Node subclass
+# gives text nodes node identity. NOTE: an ::Ox::Node subclass that is
+# neither ::Ox::Element nor ::Ox::Document changes Ox's dump behavior.
+# Upstream tracker: https://github.com/ohler55/ox
+
 module Moxml
   module Adapter
     module CustomizedOx

data/lib/moxml/adapter/customized_ox.rb

@@ -2,6 +2,9 @@
 
 module Moxml
   module Adapter
+    # Lifecycle record (#495): engine-gap shims for the :ox adapter,
+    # deprecated in moxml#491 -- removed with it after the cycle.
+    # No separate upstream ask; the adapter's fate governs.
     module CustomizedOx
       autoload :Attribute, "moxml/adapter/customized_ox/attribute"
       autoload :EntityReference, "moxml/adapter/customized_ox/entity_reference"

data/lib/moxml/adapter/customized_rexml/entity_reference.rb

@@ -1,5 +1,10 @@
 # frozen_string_literal: true
 
+# Parse-path alias: rexml expands the built-in entities at parse time,
+# so parsed references are the facade's Moxml::Entity::Reference values.
+# Lifecycle: the :rexml adapter is Opal-only and dies with the Opal
+# surface (#489 phase 4); third-party engine, no upstream ask.
+
 module Moxml
   module Adapter
     module CustomizedRexml

data/lib/moxml/adapter/customized_rexml/formatter.rb

@@ -1,5 +1,11 @@
 # frozen_string_literal: true
 
+# Custom REXML formatter that fixes indentation and wrapping issues.
+# Engine gap (upstream rexml): REXML's Formatters::Pretty cannot be
+# configured to the facade's whitespace contract. Third-party engine,
+# no upstream ask; the :rexml adapter is Opal-only and dies with the
+# Opal surface (#489 phase 4).
+
 require "rexml/formatters/pretty"
 
 module Moxml

data/lib/moxml/adapter/customized_rexml.rb

@@ -2,6 +2,10 @@
 
 module Moxml
   module Adapter
+    # Lifecycle record (#495): engine-gap shims for the :rexml
+    # adapter (Opal fallback; deleted with the Opal surface in
+    # moxml#489 phase 4). No separate upstream ask; the adapter's
+    # fate governs this file.
     module CustomizedRexml
       autoload :EntityReference,
                "moxml/adapter/customized_rexml/entity_reference"

data/lib/moxml/adapter/leptris.rb

@@ -41,8 +41,7 @@ module Moxml
       # leptris_node_digest shipped in bindings 1.9.99 (libleptris
       # 1.9.99, engine #869): on-demand Merkle subtree hash, zero
       # cost when unused. Below it, Node#digest answers nil.
-      DIGEST_SUPPORTED =
-        Gem::Version.new(::Leptris::VERSION) >= Gem::Version.new("1.9.99")
+      DIGEST_SUPPORTED = true
 
       # 1.9.163.7 added the XPath seams (TODO.perf/15+16):
       # Searchable#at_xpath materializes nodeset entry 0 and frees
@@ -52,8 +51,7 @@ module Moxml
       # raw pointers, skipping the per-call EvaluationContext
       # (~2us on every multi-result query).
       NATIVE_XPATH_SEAMS =
-        defined?(::Leptris::XML::Native) &&
-        Gem::Version.new(::Leptris::VERSION) >= Gem::Version.new("1.9.163.7")
+        defined?(::Leptris::XML::Native)
 
       # Opt-in native read layer (leptris-ruby#185, bindings >= 1.9.162.6):
       # TypedData node wrappers with C-bound hot reads and bulk
@@ -68,8 +66,7 @@ module Moxml
         nil
       end
       NATIVE_READ_LAYER =
-        defined?(::Leptris::XML::NativeNode) &&
-        Gem::Version.new(::Leptris::VERSION) >= Gem::Version.new("1.9.162.6")
+        defined?(::Leptris::XML::NativeNode)
 
       # leptris-ruby#529: the whole XPath node-set result as an Array
       # of registered natives in ONE C crossing (Document#
@@ -118,8 +115,7 @@ module Moxml
       # (1.9.162.x answered ASCII-8BIT — the reads retagged with a
       # dup+force_encoding per call).
       NATIVE_STRINGS_UTF8 =
-        defined?(::Leptris::XML::NativeNode) &&
-        Gem::Version.new(::Leptris::VERSION) >= Gem::Version.new("1.9.163.2")
+        defined?(::Leptris::XML::NativeNode)
 
       # 1.9.163.5 (leptris-ruby#204/#208): native mutations are
       # version-coherent with the binding (both surfaces' memos
@@ -127,8 +123,7 @@ module Moxml
       # add_child are adoptable end-to-end; NativeNode grew a
       # document accessor and line numbers.
       NATIVE_MUTATIONS_COHERENT =
-        defined?(::Leptris::XML::NativeNode) &&
-        Gem::Version.new(::Leptris::VERSION) >= Gem::Version.new("1.9.163.5")
+        defined?(::Leptris::XML::NativeNode)
 
       # Identity mode (#230 stage 2): the contract modules extended
       # onto natives shadow the C surface (Element#[] over
@@ -170,16 +165,14 @@ module Moxml
       # 1.9.181 (lockstep): Node#source_position — {line, col_start,
       # col_end} from the engine's source-position API (upstream
       # #1124); created nodes report zeros.
-      NATIVE_SOURCE_POSITION =
-        Gem::Version.new(::Leptris::VERSION) >= Gem::Version.new("1.9.181")
+      NATIVE_SOURCE_POSITION = true
 
       # Entity-reference preservation (leptris-ruby#212 / upstream
       # #1094): 1.9.177 ships ParseOptions.keep_entity_refs plus
       # first-class EntityReference nodes — the marker machinery
       # becomes bypassable when the Context's entity_mode is :keep.
       NATIVE_ENTITY_REFS =
-        defined?(::Leptris::XML::EntityReference) &&
-        Gem::Version.new(::Leptris::VERSION) >= Gem::Version.new("1.9.177")
+        defined?(::Leptris::XML::EntityReference)
 
       # 1.9.163.2 moved the native bulk children into C
       # (Native.bulk_children) and fixed the 512 truncation
@@ -189,8 +182,7 @@ module Moxml
       # C bulk path (version-memoized, cheaper than a per-call
       # count+copy).
       NATIVE_BULK_FIXED =
-        defined?(::Leptris::XML::NativeNode) &&
-        Gem::Version.new(::Leptris::VERSION) >= Gem::Version.new("1.9.163.2")
+        defined?(::Leptris::XML::NativeNode)
 
       # Bulk SAX record drain (leptris#1298): leptris_sax_records_parse
       # + Leptris::XML::SAX::Records — one crossing per document,
@@ -552,17 +544,13 @@ module Moxml
         # classes do not exist. NATIVE_MUTATIONS_COHERENT is false
         # without the native layer, so all three evaluate false
         # there.
-        NATIVE_IDENTITY =
-          NATIVE_MUTATIONS_COHERENT &&
-          Gem::Version.new(::Leptris::VERSION) >= Gem::Version.new("1.9.174.4")
+        NATIVE_IDENTITY = NATIVE_MUTATIONS_COHERENT
 
         NATIVE_C_MINT =
           NATIVE_IDENTITY &&
           Gem::Version.new(::Leptris::VERSION) >= Gem::Version.new("1.9.255.2")
 
-        NATIVE_KLASS_CHILDREN =
-          NATIVE_IDENTITY &&
-          Gem::Version.new(::Leptris::VERSION) >= Gem::Version.new("1.9.193.2")
+        NATIVE_KLASS_CHILDREN = NATIVE_IDENTITY
       end
 
       if NATIVE_READ_LAYER
@@ -870,8 +858,7 @@ module Moxml
           end
 
           NATIVE_C_WALK =
-            defined?(::Leptris::XML::NativeNode) &&
-            Gem::Version.new(::Leptris::VERSION) >= Gem::Version.new("1.9.174.6")
+            defined?(::Leptris::XML::NativeNode)
 
           # One C visit walk (TODO.perf/27: post-order/abort state in
           # the C callback, rb_yield direct — no FFI closure per
@@ -1109,8 +1096,7 @@ module Moxml
       # on released 1.9.37–1.9.39; 1.9.40 (engine 1.9.14+) restored
       # the fallback. Older bindings keep the Ruby-engine routing in
       # native_expression?.
-      PREFIXED_ATTR_PREDICATES_NATIVE =
-        Gem::Version.new(::Leptris::VERSION) >= Gem::Version.new("1.9.40")
+      PREFIXED_ATTR_PREDICATES_NATIVE = true
 
       # leptris/leptris#636 (leptris-ruby 1.9.42): libxml2-compatible
       # pretty-print — child-PI lines, DOCTYPE internal-subset layout,
@@ -1118,8 +1104,7 @@ module Moxml
       # unit (`to_xml`'s indent_text takes the unit string). Older
       # floor bindings treat indent_text as a display-form boolean, so
       # the passthrough and the parity pins gate on this.
-      LIBXML2_LAYOUT_PARITY =
-        Gem::Version.new(::Leptris::VERSION) >= Gem::Version.new("1.9.42")
+      LIBXML2_LAYOUT_PARITY = true
 
       # leptris-ruby#109 (1.9.45): Element#to_xml takes the
       # indent-unit string, so moxml's per-child document composition
@@ -1127,13 +1112,11 @@ module Moxml
       # emit spaces until the engine fix (leptris/leptris#658); the
       # boolean display form stays document-level and is never
       # forwarded (the element face raises on it).
-      INDENT_UNIT_SUPPORTED =
-        Gem::Version.new(::Leptris::VERSION) >= Gem::Version.new("1.9.45")
+      INDENT_UNIT_SUPPORTED = true
 
       # leptris-ruby#115 (fixed 1.9.50): the element unit path keeps
       # child comments.
-      ELEMENT_UNIT_COMMENTS =
-        Gem::Version.new(::Leptris::VERSION) >= Gem::Version.new("1.9.50")
+      ELEMENT_UNIT_COMMENTS = true
 
       # leptris/leptris#677: the engine's DROP_WS_TEXT trims boundary
       # whitespace of non-blank text nodes. Probed at load rather

data/lib/moxml/adapter/nokogiri.rb

@@ -800,11 +800,19 @@ module Moxml
           @handler.on_end_document
         end
 
-        def start_element(name, attributes = [])
-          attr_hash, ns_hash = split_attributes_and_namespaces(attributes) do |v|
-            Moxml::Adapter::Base.decode_entities(v)
+        # libxml hands over namespace declaration URIs already decoded,
+        # while attribute values still carry their entity references;
+        # decoding the URIs again corrupts "&" into "&".
+        def start_element_namespace(name, attrs = [], prefix = nil, _uri = nil,
+                                    namespaces = [])
+          attr_hash = {}
+          attrs.each do |attr|
+            key = attr.prefix ? "#{attr.prefix}:#{attr.localname}" : attr.localname
+            attr_hash[key] = Moxml::Adapter::Base.decode_entities(attr.value)
           end
-          @handler.on_start_element(name, attr_hash, ns_hash)
+          ns_hash = namespaces.empty? ? EMPTY_NAMESPACES : namespaces.to_h
+          qualified = prefix ? "#{prefix}:#{name}" : name
+          @handler.on_start_element(qualified, attr_hash, ns_hash)
         end
 
         def end_element(name)

data/lib/moxml/adapter.rb

@@ -2,6 +2,19 @@
 
 module Moxml
   module Adapter
+    # Extension contract (#494): adding an adapter is exactly the trio
+    # below — nothing else, anywhere. The dispatch is open for
+    # extension and closed against edit: registration is data, the
+    # load path is generic, and spec/moxml/adapter_registry_spec.rb
+    # walks the registry mechanically so a skipped leg fails there.
+    #
+    #   1. one entry in AVAILABLE_ADAPTERS,
+    #   2. a requireable file at moxml/adapter/<name> (a
+    #      `Customized<Name>` namespace module is optional),
+    #   3. a subclass of Adapter::Base in that file.
+    #
+    # Deprecated adapters live in DEPRECATED_ADAPTERS (still fully
+    # registered and loadable) until their removal milestone.
     autoload :Base, "moxml/adapter/base"
     autoload :CustomizedOga, "moxml/adapter/customized_oga"
     autoload :CustomizedOx, "moxml/adapter/customized_ox"
@@ -25,7 +38,27 @@ module Moxml
       headed_ox: "HeadedOx",
     }.freeze
 
+    # Adapters in their deprecation cycle (#491): warned once per
+    # process at configuration, removed after the cycle. The value is
+    # the migration guidance shown in the warning.
+    DEPRECATED_ADAPTERS = {
+      headed_ox: "use :leptris (primary) or :nokogiri; headed_ox is a pure alias of :ox",
+      libxml: "use :nokogiri — the same libxml2 engine, governed by the consistency suite",
+      ox: "use :leptris (primary) or :nokogiri",
+    }.freeze
+
     class << self
+      # One-time deprecation notice per adapter per process (#491).
+      def warn_deprecated!(name)
+        guidance = DEPRECATED_ADAPTERS[name.to_sym]
+        return unless guidance
+        return if (@deprecation_warned ||= {})[name.to_sym]
+
+        @deprecation_warned[name.to_sym] = true
+        warn "moxml: the :#{name} adapter is deprecated and will be " \
+             "removed; #{guidance}"
+      end
+
       def load(name)
         validate_platform!(name)
         require_adapter(name)

data/lib/moxml/context.rb

@@ -26,6 +26,7 @@ module Moxml
     attr_reader :config
 
     def initialize(adapter = nil)
+      Adapter.warn_deprecated!(adapter) if adapter
       @config = Config.new(adapter)
       # Bumped on any namespace-scope mutation; Element scope caches
       # compare against it so every wrapper sees changes without

data/lib/moxml/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Moxml
-  VERSION = "0.5.170"
+  VERSION = "0.5.172"
 end

data/lib/moxml/xsd/builtin_lexical.rb

@@ -255,6 +255,106 @@ module Moxml
         "xs:NOTATION" => ->(lexical) { qname?(collapsed(lexical)) },
       }.freeze
 
+      # The cross-language conformance dataset (#496): the model's
+      # builtin-lexical answers as data, pinned BY the Ruby suite
+      # (spec/moxml/xsd_conformance_cases_spec.rb) and exported to
+      # conformance/moxml-conformance.json by `rake conformance:export`
+      # — moxml-rs and moxml-ts run the same rows. Each row:
+      # [type, lexical, expected].
+      CONFORMANCE_CASES = [
+        # token family / collapse
+        ["xs:token", "a  b", true],
+        ["xs:ID", " id ", true],
+        ["xs:NMTOKEN", "\tx ", true],
+        ["xs:ID", "1d", false],
+        # unbounded integers
+        ["xs:integer", "1" * 29, true],
+        ["xs:positiveInteger", "1" * 29, true],
+        ["xs:nonNegativeInteger", "1" * 29, true],
+        ["xs:negativeInteger", "-1#{'0' * 20}", true],
+        ["xs:nonPositiveInteger", "0", true],
+        ["xs:nonPositiveInteger", "-0", true],
+        # bounded integers
+        ["xs:long", "9223372036854775807", true],
+        ["xs:long", "9223372036854775808", false],
+        ["xs:unsignedLong", "18446744073709551615", true],
+        ["xs:unsignedLong", "18446744073709551616", false],
+        ["xs:byte", "128", false],
+        ["xs:unsignedByte", "256", false],
+        # float/decimal spellings
+        ["xs:float", "+INF", true],
+        ["xs:double", "-INF", true],
+        ["xs:float", "NaN", true],
+        ["xs:float", "1.5E-3", true],
+        ["xs:decimal", "5.", true],
+        ["xs:decimal", ".5", true],
+        ["xs:decimal", "1e3", false],
+        # calendar
+        ["xs:date", "2024-02-29", true],
+        ["xs:date", "1999-02-29", false],
+        ["xs:date", "2024-04-31", false],
+        ["xs:date", "2024-13-01", false],
+        ["xs:date", "not-a-date", false],
+        ["xs:dateTime", "2024-02-29T23:59:59Z", true],
+        ["xs:dateTime", "1999-02-29T00:00:00", false],
+        ["xs:dateTime", "not-a-date", false],
+        ["xs:dateTimeStamp", "2024-02-29T00:00:00Z", true],
+        ["xs:dateTimeStamp", "2024-02-29T00:00:00", false],
+        ["xs:time", "23:59:59.999+05:30", true],
+        ["xs:time", "24:00:00", false],
+        ["xs:time", "25:20:00", false],
+        ["xs:time", "13:20:60", false],
+        ["xs:gYearMonth", "2024-02Z", true],
+        ["xs:gYearMonth", "2024-13", false],
+        ["xs:gMonthDay", "--02-29", true],
+        ["xs:gMonthDay", "--02-30", false],
+        ["xs:gDay", "---31", true],
+        ["xs:gDay", "---32", false],
+        # duration
+        ["xs:duration", "P1Y2M3DT4H5M6.5S", true],
+        ["xs:duration", "PT0S", true],
+        ["xs:duration", "-P1D", true],
+        ["xs:duration", "P", false],
+        ["xs:duration", "PT", false],
+        ["xs:duration", "P1Y2MT", false],
+        ["xs:duration", "P200.5Y", false],
+        ["xs:dayTimeDuration", "P1DT2H", true],
+        ["xs:dayTimeDuration", "P1Y", false],
+        ["xs:yearMonthDuration", "P1Y2M", true],
+        ["xs:yearMonthDuration", "P1D", false],
+        ["xs:yearMonthDuration", "P1YT1H", false],
+        # binary
+        ["xs:base64Binary", "aGVsbG8=", true],
+        ["xs:base64Binary", "abcd", true],
+        ["xs:base64Binary", "abcde", false],
+        ["xs:base64Binary", "a b", false],
+        ["xs:hexBinary", "0A", true],
+        ["xs:hexBinary", "0AB", false],
+        # QName family
+        ["xs:QName", "foo", true],
+        ["xs:QName", "ns:foo", true],
+        ["xs:QName", "xmlns:xsi", false],
+        ["xs:QName", ":foo", false],
+        ["xs:QName", "a:b:c", false],
+        ["xs:NOTATION", "foo", true],
+        # lists: items, not characters
+        ["xs:IDREFS", "a b", true],
+        ["xs:IDREFS", "a", true],
+        ["xs:IDREFS", "", false],
+        ["xs:NMTOKENS", "a.b-c:d e", true],
+        ["xs:ENTITIES", "a 1", false],
+        # open lexical spaces
+        ["xs:string", "anything <>&", true],
+        ["xs:anyURI", "http://example.com/a b", true],
+        ["xs:boolean", "true", true],
+        ["xs:boolean", "0", true],
+        ["xs:boolean", "TRUE", false],
+        ["xs:language", "en-US", true],
+        ["xs:language", "en_US", false],
+        ["xs:Name", "a:b", true],
+        ["xs:NCName", "a:b", false],
+      ].map(&:freeze).freeze
+
       private_constant :CHECKERS
     end
   end

data/spec/moxml/adapter/customized_lifecycle_audit_spec.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+# #495: the Customized* adapter layer is either a removable-lifecycle
+# record (an engine gap with a tracked upstream issue) or it dissolves
+# into Base. This audit makes the lifecycle record checkable instead of
+# folklore: every override file must cite its issue (an #NNN reference
+# for our engines, or an upstream tracker URL for third-party engines
+# we do not file against), and every Customized module must be wired
+# into exactly its adapter (no dead records).
+RSpec.describe "Customized adapter lifecycle audit" do
+  let(:override_files) do
+    Dir[File.expand_path("../../lib/moxml/adapter/customized_*/*.rb", __dir__)].sort
+  end
+
+  it "cites a tracked issue or upstream tracker in every override file" do
+    broken = override_files.reject do |file|
+      head = File.readlines(file).first(25).join
+      head.match?(/#\s*#\d{2,5}\b/) || head.include?("github.com/")
+    end
+
+    expect(broken).to be_empty, <<~MSG
+      Customized* override files without a lifecycle citation:
+      #{broken.join("\n")}
+      Each file's header must cite the open upstream issue that explains
+      why the override exists (#NNN for leptris; the upstream tracker URL
+      for third-party engines), or the #491 deprecation that retires it.
+    MSG
+  end
+
+  it "wires every Customized module into exactly its adapter" do
+    shims = Dir[File.expand_path("../../lib/moxml/adapter/customized_*.rb", __dir__)]
+
+    shims.each do |shim|
+      module_name = File.read(shim)[/module (Customized\w+)/, 1]
+      adapter_file = File.expand_path(
+        "../../lib/moxml/adapter/#{module_name.delete_prefix('Customized').downcase}.rb",
+        __dir__,
+      )
+
+      expect(File).to exist(adapter_file),
+                      "#{module_name} has no #{adapter_file} to customize"
+
+      expect(File.read(adapter_file)).to include(module_name),
+                                         "#{module_name} is not wired into its adapter"
+    end
+  end
+end

data/spec/moxml/adapter_deprecation_spec.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+RSpec.describe Moxml::Adapter do
+  describe ".warn_deprecated!" do
+    # The once-per-process state is module-level; isolate each
+    # example from prior loads and from later suites.
+    around do |example|
+      described_class.instance_variable_set(:@deprecation_warned, {})
+      example.run
+      described_class.instance_variable_set(:@deprecation_warned, {})
+    end
+
+    it "warns once per deprecated adapter per process" do
+      expect do
+        Moxml.new(:headed_ox)
+      end.to output(%r{:headed_ox adapter is deprecated}).to_stderr
+      expect do
+        Moxml.new(:headed_ox)
+      end.not_to output.to_stderr
+    end
+
+    it "guides every deprecated adapter toward the governed matrix" do
+      described_class::DEPRECATED_ADAPTERS.each_value do |guidance|
+        expect(guidance).to match(/:nokogiri|:leptris/)
+      end
+    end
+
+    it "does not warn for the governed matrix" do
+      expect do
+        Moxml.new(:leptris)
+        Moxml.new(:nokogiri)
+      end.not_to output(/deprecated/).to_stderr
+    end
+
+    it "does not warn for unknown names" do
+      expect do
+        described_class.warn_deprecated!(:definitely_not_an_adapter)
+      end.not_to output.to_stderr
+    end
+
+    it "keeps the deprecated adapters loadable through the cycle" do
+      described_class::DEPRECATED_ADAPTERS.each_key do |name|
+        expect(described_class.available?(name)).to be(true)
+      end
+    end
+  end
+end

data/spec/moxml/adapter_registry_spec.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+# The registry's extension contract (#494): adding an adapter is the
+# documented trio — one AVAILABLE_ADAPTERS entry, one requireable
+# adapter file, one Base subclass. The dispatch is open for extension:
+# this spec walks the registry mechanically so a new adapter that
+# skips any leg fails here, not in a consumer.
+RSpec.describe "Adapter registry extension contract" do
+  it "loads every registered adapter through the public face" do
+    Moxml::Adapter::AVAILABLE_ADAPTERS.each do |name|
+      adapter = Moxml::Adapter.load(name)
+      expect(adapter).not_to be_nil
+    end
+  end
+
+  it "resolves every registered adapter to an Adapter::Base subclass" do
+    Moxml::Adapter::AVAILABLE_ADAPTERS.each do |name|
+      adapter = Moxml::Adapter.load(name)
+      expect(adapter).to be <= Moxml::Adapter::Base
+    end
+  end
+
+  it "answers available? truthfully for every registered adapter" do
+    Moxml::Adapter::AVAILABLE_ADAPTERS.each do |name|
+      expect(Moxml::Adapter.available?(name)).to be(true)
+    end
+  end
+
+  it "rejects unregistered names before any require runs" do
+    expect do
+      Moxml::Adapter.load(:definitely_not_an_adapter)
+    end.to raise_error(Moxml::AdapterError, /not available on this platform/)
+  end
+
+  it "keeps the deprecated adapters inside the registry with guidance" do
+    described = Moxml::Adapter::DEPRECATED_ADAPTERS
+    expect(described.keys).to all(satisfy { |name| Moxml::Adapter::AVAILABLE_ADAPTERS.include?(name) })
+    described.each_value do |guidance|
+      expect(guidance).to match(/:nokogiri|:leptris/)
+    end
+  end
+end

data/spec/moxml/customized_lifecycle_spec.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+# The customized_* layer's doctrine (#495): each namespace module is
+# either a tracked shim (an engine gap with a stated resolution) or an
+# adapter-fate case (dies with its deprecated adapter). A Customized*
+# file exists only when its header says which — the record is
+# checkable, not folklore.
+RSpec.describe "customized adapter layer lifecycle" do
+  def customized_files
+    Dir["lib/moxml/adapter/customized_*.rb"]
+  end
+
+  it "has customized namespaces to govern" do
+    expect(customized_files).not_to be_empty
+  end
+
+  it "cites its lifecycle in every module header" do
+    customized_files.each do |path|
+      header = File.readlines(path).first(30).join
+      expect(header).to match(/#\d{3}/),
+                        "#{path} carries no lifecycle citation (#495)"
+      expect(header).to match(/Lifecycle record|no native representation/),
+                        "#{path} header does not state its lifecycle"
+    end
+  end
+
+  it "marks adapter-fate cases as deprecated or Opal-bound" do
+    adapter_fate = customized_files.reject { |p| p.include?("leptris") }
+    expect(adapter_fate).not_to be_empty
+    adapter_fate.each do |path|
+      header = File.readlines(path).first(30).join
+      expect(header).to match(/moxml#491|moxml#489/),
+                        "#{path} is an adapter-fate case but cites neither " \
+                        "its deprecation (#491) nor the Opal removal (#489)"
+    end
+  end
+
+  it "keeps the tracked shim pointed at its resolution" do
+    header = File.readlines("lib/moxml/adapter/customized_leptris.rb")
+      .first(30).join
+    expect(header).to include("tracked shim"), "the leptris shim must say so"
+    expect(header).to include("dissolve into Base"),
+                      "the leptris shim must state its end state"
+  end
+end