moxml 0.5.32 → 0.5.33

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 627111c496efca4687eabeeb78989d611d3d308adc5ed32443c7058da51c57c9
-  data.tar.gz: 86d1cc6c471d07084e0d2e0de9412b286b5486b202f9fe677b7417f514c1fe55
+  metadata.gz: 6fcb33efd8969194833ce7ee6b7e3e3bfa6517ec7d216028407d28fbc95b1641
+  data.tar.gz: ec2239b9b5501b208331ce5874764ad99cad357bacec08af6cc47d1f3aa69aff
 SHA512:
-  metadata.gz: f1108c98dc8af92913605dd08b84eb50bbfec92a5dd286e15656c3ecd57937ce56bc186c9393a740f6bd8a8316f06fb059db226f20ffc9f0b84cfb433e1a532d
-  data.tar.gz: 02d109a32659b30fc34ac5d6d3f01bc0d32d9e1ca6a38cfdc2fe3880a02c779ce5ff41fa2f0eda04adc2a9ccd6702f372d29b4d2a6fe33faeb0456cb8852d26b
+  metadata.gz: 18526fb6430f0231b187e888104c4f2fef7e38999d1015d8324ea53b90339de4c0d5d58cb4b591380b5d6cca704014fcb30ca5429f5abeff2a027217e1d47e54
+  data.tar.gz: 206cfe96f4bcac080a134092dac6f305d931d9d589c0dd544cf47e6bceb39d77d023f3b6e6c80deaeba94d10997840c90b583770d8c9d35e81dca65706354c0c

data/Rakefile

@@ -244,6 +244,14 @@ namespace :benchmark do
     ENV.delete("SKIP_BENCHMARKS")
     sh "bundle exec rspec spec/performance/xpath_benchmark_spec.rb"
   end
+  # Consumer-pipeline leg (issue #198): nested document walked into
+  # typed objects — median time + GC.stat allocation deltas, where
+  # engine-level numbers hide wrapper overhead. PIPELINE_ADAPTER and
+  # PIPELINE_REPS env-overridable.
+  desc "Consumer-pipeline benchmark (typed-object walk, issue #198)"
+  task :pipeline do
+    sh "ruby", "benchmark/pipeline_bench.rb"
+  end
 
   desc "Generate adapter benchmark report"
   task :report do

data/benchmark/pipeline_bench.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+# Consumer-pipeline benchmark leg (issue #198): measures a nested
+# document walked into typed objects — the shape consumers actually
+# run, where engine-level numbers hide wrapper overhead (Amdahl).
+# Reports fresh-run medians with GC.stat allocation deltas.
+require "moxml"
+require "nokogiri"
+
+ADAPTER = (ENV["PIPELINE_ADAPTER"] || "leptris").to_sym
+REPS = (ENV["PIPELINE_REPS"] || 7).to_i
+
+parts = [%(<?xml version="1.0"?><catalog>)]
+150.times do |i|
+  parts << %(<record id="r#{i}" kind="k#{i % 3}">)
+  6.times { |j| parts << %(<field name="f#{j}" unit="u#{j}">value #{i}.#{j}</field>) }
+  parts << %(</record>)
+end
+parts << %(</catalog>)
+XML = parts.join
+
+Field = Struct.new(:name, :unit, :value)
+Record = Struct.new(:id, :kind, :fields)
+Catalog = Struct.new(:records)
+
+def walk_document(adapter_name)
+  ctx = Moxml.new(adapter_name)
+  doc = ctx.parse(XML)
+  catalog = Catalog.new([])
+  doc.root.children.each do |rec|
+    next unless rec.is_a?(Moxml::Element)
+
+    record = Record.new(rec["id"], rec["kind"], [])
+    rec.children.each do |f|
+      next unless f.is_a?(Moxml::Element)
+
+      record.fields << Field.new(f["name"], f["unit"], f.text)
+    end
+    catalog.records << record
+  end
+  raise "shape" unless catalog.records.size == 150
+
+  raise "content" unless catalog.records[7].fields[3].value.include?("7.3")
+
+  catalog
+end
+
+def measure(adapter_name)
+  walk_document(adapter_name) # warm: autoloads off the books
+  times = []
+  allocs = nil
+  REPS.times do
+    GC.start
+    a0 = GC.stat(:total_allocated_objects)
+    t0 = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    walk_document(adapter_name)
+    t1 = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    a1 = GC.stat(:total_allocated_objects)
+    times << ((t1 - t0) * 1e6)
+    allocs = a1 - a0
+  end
+  median = times.sort[times.size / 2]
+  [median, allocs]
+end
+
+noko_med, noko_alloc = measure(:nokogiri)
+puts format("pipeline nokogiri: median %<med>7.0fµs  %<allocs>6d allocs", med: noko_med, allocs: noko_alloc)
+target_med, target_alloc = measure(ADAPTER)
+puts format("pipeline %<adapter>-8s: median %<med>7.0fµs  %<allocs>6d allocs  (%<ratio>.2fx, allocs %<aratio>.2fx)",
+            adapter: ADAPTER, med: target_med, allocs: target_alloc,
+            ratio: noko_med / target_med, aratio: noko_alloc.to_f / target_alloc)
+puts format("(one-shot shape: parse + typed walk + content asserts; YJIT=%<yjit>s; load %<load>.1f)",
+            yjit: ENV["RUBY_YJIT_ENABLE"] ? "on" : "off",
+            load: `sysctl -n vm.loadavg`.split[1].to_f)

data/docs/_pages/adapter-protocol.adoc

@@ -91,6 +91,11 @@ the context's wrapper identity map opts out.
 Whether the subtree can contain entity markers; gates the
 post-serialize restore scan.
 
+`digest(node, drop_ws_text:)`::
+The backend's content-defined subtree Merkle hash where one exists
+(leptris >= 1.9.99, engine #869); nil everywhere else. `Node#digest`
+gates on nil — consumers fall back to walking.
+
 `bulk_materialize?`::
 Whether the adapter offers a bulk path for `Moxml::Materializer`;
 `materialize_fields` fills the reused flat buffers and yields the

data/docs/_pages/node-api-reference.adoc

@@ -114,6 +114,32 @@ node.namespace?        # Is it a namespace?
 node.document          # Get owning document
 ----
 
+== Subtree digest
+
+`Node#digest` exposes the backend's content-defined Merkle hash of a
+subtree when one exists — currently only the leptris adapter
+(libleptris >= 1.9.99, leptris#869):
+
+[source,ruby]
+----
+node.digest                       # => Integer (u64) or nil
+node.digest(drop_ws_text: true)   # skip whitespace-only text nodes
+----
+
+Contract:
+
+* `nil` means "no digest support" (every other adapter) — consumers
+  gate on nil and fall back to walking.
+* Equal digests imply subtree equivalence under the flag set;
+  unequal digests imply nothing (descend and compare).
+* The hash covers element prefix + resolved namespace URI + local
+  name, attributes sorted by (URI, local) and first-wins
+  deduplicated, and children in document order. No addresses
+  participate, so identical trees hash equal across parses and
+  processes.
+* Nodes without a backing engine node (documents, attributes,
+  synthetic declarations) answer nil.
+
 
 See also:
 

data/docs/_pages/performance.adoc

@@ -106,6 +106,26 @@ load-immune — use them when the machine is busy:*
 hundreds of iterations — spot checks of 30 have missed 5-30% races
 on this codebase.
 
+*More traps, paid for in this codebase:*
+
+- Optional keyword arguments do NOT allocate on Ruby 3.4 (measured
+  0.000 allocs/call with one and two optional kwargs) — do not
+  "optimize" them into positional arguments expecting an allocation
+  win. An earlier version of this page claimed otherwise: a +601
+  allocation delta attributed to kwargs was actually the write-path
+  cache clears allocating a fresh Hash per write (+500), bundled
+  into the same change as a kwargs edit. The general lesson:
+  attribute allocation deltas per-change, never per-bundle.
+- Engines free attribute natives on removal — reading any native
+  property after `remove_attribute_native` is a use-after-free.
+  The crash only surfaced mid-suite under GC churn (standalone
+  repros passed); read names BEFORE the removal call.
+- Scope invalidation to what the mutation can affect: a
+  non-xmlns attribute write cannot change namespace scope, so it
+  must not bump the document-wide scope generation (which evicts
+  every wrapper's caches). +5-8% on write-heavy mixed workloads,
+  and bulk builds stop thrashing every reader's cache.
+
 === leptris 1.9.105 numbers (reference table)
 
 XML parse 2.4-2.8x, document serialize 2.4x, element queries 32x,
@@ -198,6 +218,29 @@ first access, not at construction — `.size`/`.empty?`/`.first` on a
 (that path also skips the binding's per-node wrapper materialization
 entirely; see `LazyNodeSet` under the leptris adapter).
 
+=== Mint priming and scoped invalidation
+
+`Node.wrap` resolves the adapter and node type once and primes both
+onto the wrapper (positional constructor arguments) — a fresh
+wrapper previously re-paid the context hop and the type probe on
+its first access. Attribute writes that cannot change namespace
+scope (bare and non-`xmlns` prefixed names) invalidate the
+element's caches locally instead of bumping the document-wide scope
+generation; `xmlns` writes keep the global bump.
+
+| path | before | after |
+| Attribute write (`[]=`) | 822ns | 758ns (-8%) |
+| Cold walk (parse + wrapper mint, 752 nodes) | 811µs | 699µs (-14%) |
+| Mixed build+read (nokogiri) | 1355µs / 5267 allocs | 1283µs / 5267 allocs |
+| `Element#text` read | 422ns | 346ns (-18%) |
+| `create_text` allocations | 6/node | 5/node |
+| Bare attribute read `[]` | 714ns | 513ns (-28%) |
+
+Allocations unchanged (the invalidation clears are nil-writes; the
+read cache materializes lazily). The remaining cold-walk gap is
+binding-side (its per-node Ruby wrapper construction) — tracked
+upstream as the TypedData work.
+
 === Prefer bulk paths for per-node conversion
 
 Per-node Ruby iteration pays the wrapper tax per element. When the

data/lib/moxml/adapter/base.rb

@@ -28,6 +28,24 @@ module Moxml
           )
         end
 
+        # Uniform fragment parsing: returns the fragment's top-level
+        # nodes as native objects. Engines without a fragment node
+        # type (everything but Nokogiri) get the wrapper-parse
+        # shape — the same trick Element#append_xml and #inner_xml=
+        # use — with a synthetic root whose children are the
+        # fragment's top-level nodes.
+        def root(_document)
+          raise Moxml::NotImplementedError.new(
+            "root not implemented", feature: "root", adapter: name
+          )
+        end
+
+        def parse_fragment(xml, _context = nil)
+          doc = parse("<m>#{xml}</m>")
+          root = root(doc)
+          root ? children(root) : []
+        end
+
         # Streaming incremental parse (leptris engine): yields each
         # completed element while the parse runs, releasing prior
         # subtrees — memory bounded by the largest subtree, not the
@@ -98,14 +116,19 @@ module Moxml
           )
         end
 
+        # Backends without a native subtree digest answer nil —
+        # the wrapper contract Node#digest gates on (issue #173).
+        def digest(*)
+          nil
+        end
+
         def create_element(name, owner_doc: nil)
           validate_element_name(name)
           create_native_element(name, owner_doc)
         end
 
         def create_text(content, owner_doc: nil)
-          # Ox freezes the content, so we need to dup it
-          create_native_text(normalize_xml_value(content).dup, owner_doc)
+          create_native_text(normalize_xml_value(content), owner_doc)
         end
 
         def create_cdata(content, owner_doc: nil)

data/lib/moxml/adapter/leptris.rb

@@ -34,6 +34,12 @@ module Moxml
       ATTR_RESULT_NATIVE =
         Gem::Version.new(::Leptris::VERSION) >= Gem::Version.new("1.9.105")
 
+      # 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")
+
       # Native C14N delegation probe: the engine's C14N must
       # byte-match the Ruby reference (ported from canon) on a
       # namespace-sorting + attributes + comments shape before
@@ -180,13 +186,12 @@ module Moxml
         # restoration when the document carries them (entity-free
         # documents — the common case — skip the scan; parentless
         # iterparse elements are never bearing).
+        # Raw qualified-name read; the entity-restore decision is
+        # the wrapper's (Element#[] rides its generation memo — the
+        # document-plus-attachment probe here cost more than the
+        # read itself).
         def bare_attr_value(element, name)
-          value = element[name.to_s]
-          if value.is_a?(String) && entity_bearing?(element)
-            restore_entities(value)
-          else
-            value
-          end
+          element[name.to_s]
         end
 
         def native_identity_stable?
@@ -254,6 +259,15 @@ module Moxml
         # elements as the parse runs; each prior subtree is released.
         # Yielded elements are parentless (document nil) and valid
         # only inside the block — the wrapper mirrors that lifetime.
+        # Wrapper-parse: the synthetic root's children are the
+        # fragment's top-level nodes (the append_xml / inner_xml=
+        # trick). Children come through the normal children path so
+        # entity-marker splitting applies.
+        def parse_fragment(xml, _context = nil)
+          doc = parse("<m>#{xml}</m>")
+          children(doc.native.root)
+        end
+
         def iterparse(xml, mode = :top_level, _context = nil, &block)
           raise ArgumentError, "iterparse requires a block" unless block
 
@@ -537,6 +551,18 @@ module Moxml
           end
         end
 
+        # Subtree digest over the binding node (issue #173). Only
+        # binding Nodes carry a C node handle: the synthetic
+        # wrappers (declarations, doctypes, entity markers) and the
+        # lightweight Attr triples answer nil.
+        def digest(node, drop_ws_text: false)
+          return nil unless DIGEST_SUPPORTED
+          return nil unless node.is_a?(::Leptris::XML::Node) &&
+            !node.is_a?(::Leptris::XML::ResultAttr)
+
+          node.digest(drop_ws: drop_ws_text)
+        end
+
         def node_name(node)
           return node.root_name if node.is_a?(::Leptris::XML::DocType)
           return node.target if node.is_a?(CustomizedLeptris::DocumentPI)
@@ -567,19 +593,10 @@ module Moxml
         end
 
         def children(node)
+          # Frequency-ordered: elements dominate every walk and paid
+          # ten failed compares to reach the else arm.
           case node
-          when ::Leptris::XML::Document
-            assemble_document_children(node)
-          when CustomizedLeptris::Declaration, CustomizedLeptris::Doctype,
-               CustomizedLeptris::EntityReference, CustomizedLeptris::TextSegment,
-               CustomizedLeptris::DocumentPI,
-               # Terminal node kinds pay an FFI round trip for an empty
-               # list; unfiltered recursions visit every text node.
-               ::Leptris::XML::Text, ::Leptris::XML::Comment,
-               ::Leptris::XML::CDATA, ::Leptris::XML::ProcessingInstruction,
-               ::Leptris::XML::Attr
-            []
-          else
+          when ::Leptris::XML::Element
             natives = node.children.to_a
             # Parse records whether the preprocessed source held any
             # entity markers, and the ER builder path flips the flag
@@ -592,6 +609,19 @@ module Moxml
               attachments.get(node.document, :entity_markers) == false
 
             split_entity_markers(natives, node)
+          when ::Leptris::XML::Document
+            assemble_document_children(node)
+          when CustomizedLeptris::Declaration, CustomizedLeptris::Doctype,
+               CustomizedLeptris::EntityReference, CustomizedLeptris::TextSegment,
+               CustomizedLeptris::DocumentPI,
+               # Terminal node kinds pay an FFI round trip for an empty
+               # list; unfiltered recursions visit every text node.
+               ::Leptris::XML::Text, ::Leptris::XML::Comment,
+               ::Leptris::XML::CDATA, ::Leptris::XML::ProcessingInstruction,
+               ::Leptris::XML::Attr
+            []
+          else
+            node.children.to_a
           end
         end
 
@@ -766,13 +796,18 @@ module Moxml
         end
 
         def text_content(node)
+          # Frequency-ordered: elements dominate reads; they paid
+          # three failed compares to reach the else arm. The
+          # duplicated branch bodies are the point.
           case node
+          when ::Leptris::XML::Element, ::Leptris::XML::Text
+            node.content.to_s
           when ::Leptris::XML::Document then node.root ? node.root.content : ""
           when CustomizedLeptris::Declaration, CustomizedLeptris::Doctype,
                CustomizedLeptris::EntityReference
             ""
           when CustomizedLeptris::TextSegment then node.content
-          else node.content.to_s
+          else node.content.to_s # rubocop:disable Lint/DuplicateBranch
           end
         end
 

data/lib/moxml/adapter/nokogiri.rb

@@ -23,27 +23,26 @@ module Moxml
           true
         end
 
+        # Nokogiri has a real fragment node type — its children ARE
+        # the fragment's top-level nodes.
+        def parse_fragment(xml, _context = nil)
+          processed = Entity.preprocess_entities(xml)
+          ::Nokogiri::XML::DocumentFragment.parse(processed) do |config|
+            config.strict.nonet
+            config.recover
+          end.children.to_a
+        end
+
         # Fast bare-name read for Element#[]: the native call plus,
         # only when the parse recorded entity markers, their
         # restoration (the resolver path's other real semantic).
         # The marker flag is constant per document — a WeakMap on
         # the adapter beats the per-read document fetch + attachment
         # hash chain.
-        def doc_entity_markers?(doc)
-          cache = (@doc_markers ||= ObjectSpace::WeakMap.new)
-          cached = cache[doc]
-          return cached unless cached.nil?
-
-          cache[doc] = attachments.get(doc, :entity_markers) == true
-        end
-
+        # Raw qualified-name read; the entity-restore decision is
+        # the wrapper's (Element#[] rides its generation memo).
         def bare_attr_value(element, name)
-          value = element[name.to_s]
-          if value.is_a?(String) && doc_entity_markers?(element.document)
-            restore_entities(value)
-          else
-            value
-          end
+          element[name.to_s]
         end
 
         def native_identity_stable?

data/lib/moxml/adapter/oga.rb

@@ -307,6 +307,11 @@ module Moxml
           current
         end
 
+        def parse_fragment(xml, _context = nil)
+          doc = parse("<m>#{xml}</m>").native
+          children(root(doc))
+        end
+
         def root(document)
           document.children.find { |node| node.is_a?(::Oga::XML::Element) }
         end

data/lib/moxml/adapter/ox.rb

@@ -94,8 +94,11 @@ module Moxml
           ::Ox::Element.new(name)
         end
 
+        # Ox stores the Ruby string object itself as the node value —
+        # without the copy, later caller mutations would write through
+        # into the document (ownership shield; see set_text_content).
         def create_native_text(content, _owner_doc = nil)
-          content
+          content.dup
         end
 
         def create_native_entity_reference(name)
@@ -330,6 +333,12 @@ module Moxml
           current
         end
 
+        def parse_fragment(xml, _context = nil)
+          doc = parse("<m>#{xml}</m>").native
+          synthetic = doc.nodes.find { |node| node.is_a?(::Ox::Element) }
+          children(synthetic)
+        end
+
         def root(document)
           document.nodes&.find { |node| node.is_a?(::Ox::Element) }
         end
@@ -357,7 +366,14 @@ module Moxml
             # Ox converts all values to strings
             remove_attribute(element, name)
           else
-            element.attributes[name.to_s] = value
+            key = name.to_s
+            attrs = element.attributes
+            # Ox parses attributes under Symbol keys; a naive
+            # string-keyed write would ADD a second entry instead
+            # of replacing (the parity suite caught reads returning
+            # the stale symbol-keyed value after a write).
+            attrs.delete(key.to_sym)
+            attrs[key] = value
           end
 
           ::Moxml::Adapter::CustomizedOx::Attribute.new(
@@ -569,9 +585,11 @@ module Moxml
         end
 
         def set_text_content(node, content)
+          # Copy on the same ownership contract as create_native_text
+          content = content.to_s.dup
           case node
-          when String then node.replace(content.to_s)
-          when ::Ox::Element then node.replace_text(content.to_s)
+          when String then node.replace(content)
+          when ::Ox::Element then node.replace_text(content)
           else
             node.value = content.to_s
           end
@@ -602,7 +620,11 @@ module Moxml
         end
 
         def namespace_prefix(namespace)
-          namespace.prefix
+          # Ox spells the default namespace's prefix "xmlns"; the
+          # wrapper contract is nil there (parity with the other
+          # adapters' in-scope maps).
+          prefix = namespace.prefix
+          prefix == "xmlns" ? nil : prefix
         end
 
         def namespace_uri(namespace)

data/lib/moxml/adapter/rexml.rb

@@ -258,6 +258,11 @@ module Moxml
           node.document
         end
 
+        def parse_fragment(xml, _context = nil)
+          doc = parse("<m>#{xml}</m>").native
+          children(root(doc))
+        end
+
         def root(document)
           document.root
         end

data/lib/moxml/attribute.rb

@@ -2,8 +2,11 @@
 
 module Moxml
   class Attribute < Node
+    # Immutable between name= writes (which clear it via
+    # clear_native_memo!), unlike element names that can change via
+    # native adoption; the memo removes an adapter read per access.
     def name
-      adapter.attribute_name(@native)
+      @name ||= adapter.attribute_name(@native)
     end
 
     def name=(new_name)
@@ -11,6 +14,7 @@ module Moxml
       # to keep tracking — same object for in-place adapters, fresh
       # object for value-object adapters (leptris).
       context.bump_namespace_scope_generation
+      @name = nil
       @native = adapter.set_attribute_name(@native, new_name)
     end
 
@@ -22,7 +26,16 @@ module Moxml
 
     def value
       val = @native.value.to_s
-      adapter.restore_entities(val)
+      # Same guard as Element#text: entity-free documents skip the
+      # marker restore scans. The memo rides the owning element's
+      # (attr natives have no entity probe); a detached attribute
+      # wrapper falls back to the unconditional restore.
+      parent = @parent_node
+      if parent.nil? || parent.entity_bearing?
+        adapter.restore_entities(val)
+      else
+        val
+      end
     end
 
     alias content value
@@ -33,7 +46,13 @@ module Moxml
     end
 
     def value=(new_value)
-      context.bump_namespace_scope_generation
+      name = self.name
+      if name == "xmlns" || name.start_with?("xmlns:")
+        # Declaration rewrite — namespace scope changed
+        context.bump_namespace_scope_generation
+      else
+        @parent_node&.invalidate_attribute_value_cache!
+      end
       adapter.set_attribute_value(@native, new_value)
     end
 
@@ -59,9 +78,17 @@ module Moxml
     end
 
     def remove
+      # The name must be read before the removal — engines free the
+      # attribute native, and post-removal reads are use-after-free.
+      name = self.name
+      declaration = name == "xmlns" || name.start_with?("xmlns:")
       adapter.remove_attribute_native(@native)
       if @parent_node.is_a?(Moxml::Element)
-        @parent_node.invalidate_attribute_cache!
+        if declaration
+          @parent_node.invalidate_attribute_cache!
+        else
+          @parent_node.invalidate_local_attribute_cache!
+        end
       end
       self
     end

data/lib/moxml/attribute_resolver.rb

@@ -41,7 +41,7 @@ module Moxml
       uri = prefix_uri(element, prefix)
       return nil if uri.nil?
 
-      adapter = element.context.config.adapter
+      adapter = element.adapter
       if adapter.is_a?(Moxml::Adapter::Leptris)
         return adapter.expanded_attr_value(element.native, uri, local)
       end
@@ -105,7 +105,7 @@ module Moxml
     # @return [String] the assigned value
     def assign(element, name, value)
       name = name.to_s
-      adapter = element.context.config.adapter
+      adapter = element.adapter
       if name == "xmlns" || name.start_with?("xmlns:")
         adapter.set_attribute(element.native, name, value)
         element.invalidate_attribute_cache!
@@ -122,7 +122,7 @@ module Moxml
       # writes.
       if !name.include?(":") && adapter.bare_set_qname_safe?
         adapter.set_attribute(element.native, name, value)
-        element.invalidate_attribute_cache!
+        element.invalidate_local_attribute_cache!
         return value
       end
 
@@ -133,7 +133,7 @@ module Moxml
       end
 
       adapter.set_attribute(element.native, name, value)
-      element.invalidate_attribute_cache!
+      element.invalidate_local_attribute_cache!
       value
     end
 
@@ -143,7 +143,7 @@ module Moxml
     # @return [Moxml::Attribute, nil] the removed attribute
     def remove(element, name)
       name = name.to_s
-      adapter = element.context.config.adapter
+      adapter = element.adapter
       if name == "xmlns" || name.start_with?("xmlns:")
         adapter.remove_attribute(element.native, name)
         element.invalidate_attribute_cache!
@@ -154,7 +154,7 @@ module Moxml
       return nil unless attr
 
       adapter.remove_attribute_native(attr.native)
-      element.invalidate_attribute_cache!
+      element.invalidate_local_attribute_cache!
       attr
     end
 

data/lib/moxml/c14n/exclusive.rb

@@ -139,7 +139,7 @@ module Moxml
 
       def bindings_declared_on(element)
         bindings = {}
-        element.namespaces.each do |ns|
+        element.namespace_definitions.each do |ns|
           prefix = ns.prefix
           prefix = "" if prefix.nil? || prefix == "xmlns"
           bindings[prefix] = ns.uri

data/lib/moxml/context.rb

@@ -106,6 +106,18 @@ module Moxml
     # Memory stays bounded by the largest subtree, not the document
     # (iterparse_file streams the file C-side). Yielded elements are
     # parentless and valid only inside the block.
+    # Parse an XML fragment: returns its top-level nodes as an
+    # Array of wrappers, uniformly across adapters (issue #188 —
+    # fragment: true was Nokogiri-only). Engines without a fragment
+    # node type parse inside a synthetic root; the fragment's nodes
+    # are the result either way.
+    def parse_fragment(xml)
+      adapter = config.adapter
+      adapter.parse_fragment(xml, self).map do |native|
+        Moxml::Node.wrap(native, self)
+      end
+    end
+
     def iterparse(xml, mode: :top_level, &block)
       config.adapter.iterparse(xml, mode, self, &block)
     end

data/lib/moxml/document.rb

@@ -4,7 +4,7 @@ module Moxml
   class Document < Node
     attr_accessor :has_xml_declaration
 
-    def initialize(native, context)
+    def initialize(native, context, adapter = nil, node_type = nil)
       super
       @has_xml_declaration = false
     end

data/lib/moxml/element.rb

@@ -63,7 +63,16 @@ module Moxml
       # names, where resolution is real work.
       adapter = self.adapter
       if !key.include?(":") && adapter.bare_get_qname_safe?
-        return adapter.bare_attr_value(@native, key)
+        # The entity-restore decision rides the wrapper's generation
+        # memo (as Element#text) — the adapter-level probe walks to
+        # the document and the attachment store on every read, which
+        # dominated the fast path.
+        value = adapter.bare_attr_value(@native, key)
+        if value.is_a?(String) && entity_bearing?
+          return adapter.restore_entities(value)
+        end
+
+        value
       end
 
       cache = attribute_read_cache
@@ -86,7 +95,11 @@ module Moxml
     # every attribute or namespace mutation anywhere bumps it.
     def attribute_read_cache
       generation = context.namespace_scope_generation
-      if @attribute_cache_generation != generation
+      # @attribute_cache.nil? covers the local invalidation clears —
+      # a value or list change without a scope bump (see
+      # invalidate_local_attribute_cache!) — so writes never allocate
+      # a replacement hash; the next read materializes one lazily.
+      if @attribute_cache.nil? || @attribute_cache_generation != generation
         @attribute_cache = {}
         @attribute_cache_generation = generation
       end
@@ -180,12 +193,25 @@ module Moxml
       invalidate_namespace_cache!
     end
 
+    # All namespaces IN SCOPE for this element — its own
+    # declarations plus everything inherited from ancestors —
+    # matching the Nokogiri #namespaces contract consumers port
+    # against (issue #198: this returned only own declarations,
+    # losing ancestor scope under every backend).
     def namespaces
-      @namespaces ||= adapter.namespace_definitions(@native).map do |ns|
+      in_scope_namespaces
+    end
+
+    # The element's OWN namespace declarations only (not
+    # inherited). C14n's visibly-utilized calculation and the
+    # materializer's declaration pairs want exactly this shape.
+    def namespace_definitions
+      return @namespace_definitions unless @namespace_definitions.nil?
+
+      @namespace_definitions = adapter.namespace_definitions(@native).map do |ns|
         Namespace.new(ns, context)
       end
     end
-    alias namespace_definitions namespaces
 
     # The element's OWN namespace declarations as [prefix, uri]
     # pairs (nil prefix = default namespace) — not the inherited
@@ -217,7 +243,10 @@ module Moxml
 
     def text
       val = adapter.text_content(@native)
-      adapter.restore_entities(val)
+      # Entity-free documents (the common case) skip the marker
+      # restore scans entirely — the per-wrapper entity_bearing?
+      # memo rides the adapter's serialize generation.
+      entity_bearing? ? adapter.restore_entities(val) : val
     end
 
     alias content text
@@ -229,7 +258,7 @@ module Moxml
 
     def inner_text
       text = raw_inner_text
-      adapter.restore_entities(text)
+      entity_bearing? ? adapter.restore_entities(text) : text
     end
 
     # Returns inner text without entity marker restoration.
@@ -291,9 +320,25 @@ module Moxml
       children
     end
 
-    # Called by Attribute#remove and the attribute mutators. Clears
-    # the attribute list and the resolved-read cache, and bumps the
-    # context generation so cross-wrapper reads recompute.
+    # Attribute mutations that cannot change namespace scope (bare
+    # and non-xmlns prefixed names) invalidate locally: the
+    # resolved-read cache alone for value writes, the wrapper list
+    # too when the attribute set changes. No context generation
+    # bump — that would evict every wrapper's caches document-wide
+    # on each write of a bulk build.
+    def invalidate_attribute_value_cache!
+      @attribute_cache = nil
+    end
+
+    def invalidate_local_attribute_cache!
+      @attributes = nil
+      @attribute_cache = nil
+    end
+
+    # Called by the namespace-scoped attribute paths (xmlns writes
+    # and removals) and Attribute#name=. Clears the attribute list
+    # and the resolved-read cache, and bumps the context generation
+    # so cross-wrapper reads recompute.
     def invalidate_attribute_cache!
       @attributes = nil
       @attribute_cache = nil
@@ -305,6 +350,7 @@ module Moxml
     # any children cache — recomputes on next read.
     def invalidate_namespace_cache!
       @namespaces = nil
+      @namespace_definitions = nil
       @in_scope_namespaces = nil
       context.bump_namespace_scope_generation
     end

data/lib/moxml/node.rb

@@ -12,10 +12,16 @@ module Moxml
 
     attr_reader :native, :context
 
-    def initialize(native, context)
+    # adapter/node_type are primed by Node.wrap, which resolves both
+    # before choosing the wrapper class — a fresh wrapper would
+    # otherwise pay the context hop and the type probe again on its
+    # first access.
+    def initialize(native, context, adapter = nil, node_type = nil)
       @context = context
       @native = native
       @parent_node = nil
+      @adapter = adapter
+      @node_type_cached = node_type
     end
 
     # Update native reference after identity-changing operations
@@ -349,6 +355,18 @@ module Moxml
       adapter.line_number(@native)
     end
 
+    # Content-defined Merkle digest of this subtree (issue #173,
+    # companion to leptris#869): a u64 Integer where the backend
+    # computes one, nil everywhere else. Consumers gate on nil and
+    # fall back to walking. Equal digests imply subtree equivalence
+    # under the flag set; unequal digests imply nothing (descend).
+    # +drop_ws_text+ skips whitespace-only text nodes.
+    #
+    # @return [Integer, nil]
+    def digest(drop_ws_text: false)
+      adapter.digest(@native, drop_ws_text: drop_ws_text)
+    end
+
     def outer_xml
       to_xml
     end
@@ -418,10 +436,12 @@ module Moxml
       cached = context.wrapper_for(node)
       return cached if cached
 
-      type = adapter(context).node_type(node)
+      adapter = adapter(context)
+      type = adapter.node_type(node)
       klass = node_type_map[type] || self
 
-      klass.new(node, context).tap { |wrapper| context.register_wrapper(node, wrapper) }
+      klass.new(node, context, adapter, type)
+        .tap { |wrapper| context.register_wrapper(node, wrapper) }
     end
 
     # Internal: Set the parent node for cache invalidation tracking.
@@ -429,14 +449,14 @@ module Moxml
     # relationships. Public to allow cross-class usage within Moxml internals.
     attr_writer :parent_node
 
-    protected
-
     def adapter
       # A context's adapter object is fixed for its lifetime; the
       # chain deref ran on every node access.
       @adapter ||= context.config.adapter
     end
 
+    protected
+
     def self.adapter(context)
       context.config.adapter
     end

data/lib/moxml/text.rb

@@ -4,7 +4,7 @@ module Moxml
   class Text < Node
     def content
       text = raw_content
-      adapter.restore_entities(text)
+      entity_bearing? ? adapter.restore_entities(text) : text
     end
 
     # Returns raw content without entity marker restoration.

data/lib/moxml/version.rb

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

data/spec/integration/contract_parity_spec.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+# Cross-adapter contract parity (issue #198): every bundled adapter
+# runs the same behavioral battery, so parity is CI-enforced rather
+# than discovered by consumers.
+%w[nokogiri leptris ox oga rexml].each do |adapter_name|
+  begin
+    next unless Moxml::Adapter.load_available?(adapter_name.to_sym)
+  rescue StandardError
+    false
+  end
+
+  RSpec.describe "Contract parity: #{adapter_name}", :adapter do
+    around do |example|
+      Moxml.with_config(adapter_name.to_sym, true, "UTF-8") do
+        example.run
+      end
+    end
+
+    let(:ctx) { Moxml.new(adapter_name.to_sym) }
+
+    describe "fragment parsing (issue #188)" do
+      it "returns the fragment's top-level nodes uniformly" do
+        nodes = ctx.parse_fragment(%(<a x="1">t1</a><b/>tail))
+        expect(nodes.map(&:class)).to eq(
+          [Moxml::Element, Moxml::Element, Moxml::Text],
+        )
+        expect(nodes[0]["x"]).to eq("1")
+        expect(nodes[0].text).to eq("t1")
+        expect(nodes[2].content).to eq("tail")
+      end
+
+      it "round-trips entities inside fragments" do
+        nodes = ctx.parse_fragment(%(<p>caf&eacute; &amp; more</p>))
+        # The moxml XML contract preserves entity REFERENCES in
+        # text reads (the entity-preservation design) — uniform
+        # across adapters, fragments included.
+        expect(nodes.first.content).to include("&eacute;")
+        expect(nodes.first.to_xml).to include("&amp;")
+      end
+
+      it "returns [] for an empty fragment" do
+        expect(ctx.parse_fragment("")).to eq([])
+      end
+    end
+
+    describe "nil namespace clearing (issue #164 contract)" do
+      it "accepts namespace = nil without raising" do
+        doc = ctx.parse(%(<r xmlns="urn:d"><c>t</c></r>))
+        child = doc.root.children.first
+        expect { child.namespace = nil }.not_to raise_error
+      end
+    end
+
+    describe "namespace adoption on append" do
+      it "keeps a subtree's own declarations when appended" do
+        doc = ctx.parse(%(<root/>))
+        nodes = ctx.parse_fragment(%(<p:s xmlns:p="urn:p">x</p:s>))
+        doc.root.add_child(nodes.first)
+        out = doc.to_xml
+        expect(out).to include("urn:p")
+        expect(out).to include("x")
+      end
+    end
+
+    describe "namespaces contract (issue #198 comment)" do
+      it "returns the in-scope map including ancestor declarations" do
+        doc = ctx.parse(%(<root xmlns:p="urn:p" xmlns="urn:d"><p:c plain="1"/></root>))
+        child = doc.root.children.first
+        map = child.namespaces.map { |n| [n.prefix, n.uri.to_s] }
+        expect(map).to contain_exactly(["p", "urn:p"], [nil, "urn:d"])
+      end
+
+      it "namespace_definitions stays the element's own declarations" do
+        doc = ctx.parse(%(<root xmlns:p="urn:p"><p:c/></root>))
+        child = doc.root.children.first
+        expect(child.namespace_definitions).to be_empty
+        expect(doc.root.namespace_definitions.map(&:prefix)).to eq(["p"])
+      end
+    end
+
+    describe "subtree digest channel (issue #173)" do
+      it "answers an Integer on digest-capable backends, nil elsewhere" do
+        doc = ctx.parse(%(<r><a x="1">t</a></r>))
+        digest = doc.root.digest
+        expect(digest).to be_nil.or be_a(Integer)
+        # Where non-nil, it is deterministic within the backend
+        doc2 = ctx.parse(%(<r><a x="1">t</a></r>))
+        expect(doc2.root.digest).to eq(digest) unless digest.nil?
+      end
+    end
+
+    describe "attribute channel semantics" do
+      it "reads and writes bare and prefixed attributes" do
+        doc = ctx.parse(%(<r xmlns:p="urn:p"><e a="1" p:b="2"/></r>))
+        e = doc.at_xpath("//e")
+        expect(e["a"]).to eq("1")
+        expect(e["p:b"]).to eq("2")
+        e["a"] = "changed"
+        expect(e["a"]).to eq("changed")
+        expect(e["p:b"]).to eq("2")
+      end
+
+      # Writes invalidate locally (no document-wide scope bump); a
+      # sibling's resolved reads must survive interleaved writes.
+      it "keeps sibling read caches coherent across interleaved writes" do
+        doc = ctx.parse(%(<r><a x="1"/><b x="2"/></r>))
+        first, second = doc.root.children.to_a
+        expect(first["x"]).to eq("1")
+        expect(second["x"]).to eq("2")
+        first["x"] = "one"
+        first["y"] = "fresh"
+        expect(second["x"]).to eq("2")
+        expect(first["x"]).to eq("one")
+        expect(first["y"]).to eq("fresh")
+        second["x"] = "two"
+        expect(first["x"]).to eq("one")
+        expect(first["y"]).to eq("fresh")
+        expect(second["x"]).to eq("two")
+      end
+    end
+  end
+end

data/spec/integration/shared_examples/node_wrappers/namespace_behavior.rb

@@ -134,7 +134,10 @@ RSpec.shared_examples "Moxml::Namespace" do
         child.add_namespace("dc", "http://purl.org/dc/elements/1.1/")
         root.add_child(child)
 
-        ns_defs = child.namespaces
+        # Own declarations (the #namespaces name moved to the
+        # in-scope Nokogiri contract — issue #198; this assertion
+        # pins own-declarations, which is what it always meant).
+        ns_defs = child.namespace_definitions
         prefixes = ns_defs.map(&:prefix)
 
         expect(prefixes).to contain_exactly("dc")

data/spec/moxml/adapter/leptris_spec.rb

@@ -634,4 +634,57 @@ RSpec.describe Moxml::Adapter::Leptris do
       expect(doc.at_xpath("//a").children.to_a.map(&:class)).to include(Moxml::EntityReference)
     end
   end
+
+  describe "subtree digest (issue #173, leptris#869)" do
+    let(:ctx) { Moxml.new(:leptris) }
+
+    it "answers equal integers for identical subtrees parsed separately" do
+      xml = %(<r xmlns:p="urn:p"><a x="1" p:y="2">t</a><b><c/></b></r>)
+      d1 = ctx.parse(xml)
+      d2 = ctx.parse(xml)
+      expect(d1.root.digest).to be_a(Integer)
+      expect(d1.root.digest).to eq(d2.root.digest)
+    end
+
+    it "answers unequal integers when content differs" do
+      d1 = ctx.parse(%(<r><a x="1"/></r>))
+      d2 = ctx.parse(%(<r><a x="2"/></r>))
+      expect(d1.root.digest).not_to eq(d2.root.digest)
+    end
+
+    it "skips whitespace-only text with drop_ws_text" do
+      spaced = ctx.parse(%(<r>\n  <a/>\n</r>))
+      tight = ctx.parse(%(<r><a/></r>))
+      expect(spaced.root.digest).not_to eq(tight.root.digest)
+      expect(spaced.root.digest(drop_ws_text: true))
+        .to eq(tight.root.digest(drop_ws_text: true))
+    end
+
+    it "hashes the prefix as well as the resolved namespace" do
+      same = ctx.parse(%(<r xmlns:p="urn:p"><p:a/></r>))
+      mirror = ctx.parse(%(<r xmlns:p="urn:p"><p:a/></r>))
+      renamed = ctx.parse(%(<r xmlns:q="urn:p"><q:a/></r>))
+      other_uri = ctx.parse(%(<r xmlns:p="urn:z"><p:a/></r>))
+      base = same.root.digest
+      expect(mirror.root.digest).to eq(base)
+      # prefix participates (leptris#869: hash(prefix, URI, local))
+      expect(renamed.root.digest).not_to eq(base)
+      expect(other_uri.root.digest).not_to eq(base)
+    end
+
+    it "answers nil for nodes without a C handle" do
+      doc = ctx.parse(%(<r a="1"><!-- c --><p/><?p instr?></r>))
+      expect(doc.digest).to be_nil
+      expect(doc.root.attributes.first.digest).to be_nil
+      doc.children.select(&:declaration?).each do |decl|
+        expect(decl.digest).to be_nil
+      end
+      # comments and PIs hash in C
+      kinds = doc.root.children.map { |n| [n.class, n.digest] }
+      comment = kinds.find { |n, _| n == Moxml::Comment }
+      pi = kinds.find { |n, _| n == Moxml::ProcessingInstruction }
+      expect(comment[1]).to be_a(Integer)
+      expect(pi[1]).to be_a(Integer)
+    end
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: moxml
 version: !ruby/object:Gem::Version
-  version: 0.5.32
+  version: 0.5.33
 platform: ruby
 authors:
 - Ribose Inc.
@@ -38,6 +38,7 @@ files:
 - LICENSE.md
 - README.adoc
 - Rakefile
+- benchmark/pipeline_bench.rb
 - benchmarks/.gitignore
 - benchmarks/generate_report.rb
 - bin/console
@@ -395,6 +396,7 @@ files:
 - spec/fixtures/xmldsig/sign3-result.xml
 - spec/integration/README.md
 - spec/integration/all_adapters_spec.rb
+- spec/integration/contract_parity_spec.rb
 - spec/integration/headed_ox_integration_spec.rb
 - spec/integration/sax_parity_spec.rb
 - spec/integration/shared_examples/edge_cases.rb