moxml 0.5.35 → 0.5.41

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f80e7825989e8653fcc4037f6e6a538ca28da7c6637d6bb941985bcc98d4dabf
-  data.tar.gz: 974854c0f42279c86e404e48920a2fd6e92cebbac22a7c6781bae023fa017fde
+  metadata.gz: d96e7e77957533fdb65727e5d244d038a6947b30a46563463b995114e4594faf
+  data.tar.gz: 11940d59f145433f37e0a5ea286055cf6d30167614291d007ff2d41dc68606a5
 SHA512:
-  metadata.gz: 7749417f017a166425fb18e896e6c0346475dd78cb32792fe725153512b64c384f60cf026e5d8503e7fb0878f22a3e6f92221126f98f08550a7b58ba1e65e2a4
-  data.tar.gz: 6545711a0dec77522f2965c5239c7cb8632878170e0fd6ea024be4d64515e49cd26550cf40b9dab7dda1ed2faa5e98caa0e076e0fda6781f7cc64463c520fd59
+  metadata.gz: 25d5f4a19555bd8802f978a3586d2d4c7fc9770d918fbfee1777203d548c6ed8d0d67fa42fd4dcddc047675f2034482f1323542379fe61193358209a4f8670d0
+  data.tar.gz: be203488271f744cb405f70a48af237408870c433a7b5922c8cafb1f303b2a4a451d0b0f6c3c80ce249a9fe75ec98904c330ff3a0cda212587fb231aac255f53

data/docs/_pages/performance.adoc

@@ -232,10 +232,20 @@ generation; `xmlns` writes keep the global bump.
 | 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%) |
+| `Element#text` read | 422ns | 249ns |
 | `create_text` allocations | 6/node | 5/node |
-| Bare attribute read `[]` | 714ns | 513ns (-28%) |
-| Consumer pipeline (parse + typed walk) | 6112µs (0.50x) | 4915µs (0.67x) |
+| Bare attribute read `[]` | 714ns | 385ns |
+| Consumer pipeline (parse + typed walk) | 6112µs (0.50x) | 3536µs (1.07x) |
+
+The 1.9.163.2 round added: UTF-8 native strings (the per-read
+dup+force_encoding retag dropped — 3000 allocations per pipeline
+run), the serialize generation as an attr_reader (the entity guard
+consults it on every read), and a per-wrapper capability memo for
+the bare-qname predicate. Reads sit at ~0.5x of raw Nokogiri with
+the binding floor (`NativeNode#[]` 110ns, `#content` 85ns)
+accounting for the budget's remainder — the 2x-per-operation ask
+for reads, writes, and create+append is filed with the floor table
+as leptris-ruby#204.
 
 The pipeline jump has two causes: leptris 1.9.157-1.9.162 (inline
 attribute values, TLS hoist, inline edge encoding, O(this-document)
@@ -253,6 +263,54 @@ read cache materializes lazily). The remaining cold-walk gap is
 binding-side (its per-node Ruby wrapper construction) — tracked
 upstream as the TypedData work.
 
+=== Native read layer (leptris >= 1.9.162.6)
+
+The leptris adapter adopts the binding's opt-in native read layer
+(leptris-ruby#185): TypedData node wrappers with C-bound hot reads
+and bulk children construction — one wrapper-cache round-trip for a
+whole child list, zero per-node FFI. Element natives minted from
+`#root` and `children` are native-layer nodes; the C tree is shared
+with the binding, so writes made through the bridged binding nodes
+(a `to_binding` wrap over the same pointer) are visible to native
+reads. Engines without the layer, or ruby-platform installs without
+the compiled bundle, stay on the binding path unchanged.
+
+| path | binding path | native layer |
+| Consumer pipeline (parse + typed walk) | 6112µs (0.50x nokogiri) | **3380µs (1.00-1.04x)** |
+| Pipeline allocations | 13564 | **9813 (0.69x nokogiri)** |
+| Cold walk (parse + mint) | 738µs | **509µs** |
+| Raw walk (binding vs native, upstream's fixture) | 64.3µs/doc | 22.8µs/doc |
+
+Entity-marker documents fall back to the binding children path (the
+marker split materializes TextSegments); the wrapper's
+`entity_bearing?` memo decides, so the check costs no per-call
+climb. `Node#==` and the adapter protocol's `same_node?` compare
+C-node addresses — two wrapper classes over one node compare equal.
+
+The 1.9.162.6–163.1 bindings truncate bulk children at 512
+(leptris-ruby#202): moxml fetches with its own count-then-copy
+scratch there. 1.9.163.2 moved the bulk into C and fixed the
+truncation — newer bindings use their C path (version-memoized,
+cheaper than a per-call count+copy).
+
+The native *builder* factories (native_create_element/text) are
+deliberately not adopted: native mutations do not advance the
+binding's document version, so the binding's memoized reads over
+the same tree go stale, and attaching the created natives pays a
+per-node `to_binding` bridge that costs more than the factory
+saves (create+attach measured 5816 -> 7697ns vs nokogiri 1750).
+
+Serialize (document, 30KB): passing `encoding: "UTF-8"` when it
+equals the document's own ran a conversion pass for byte-identical
+output (~21µs, skipped on 1.9.163.2+); the legacy
+unescaped-ampersand probe (Linux 1.9.50 platform gem) stood down
+below 1.9.60. 175 -> 149µs (~1.6x raw nokogiri). The dominant
+remaining overhead is CRuby itself: a two-byte
+`String#include?("/>")` costs ~34µs on 31KB — no memchr fast path
+exists for multi-byte needles, and `match?` is slower still. A C
+containment probe or a document-face `expand_empty` option would
+close it (leptris-ruby#204, ask 4).
+
 === 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

@@ -116,6 +116,27 @@ module Moxml
           )
         end
 
+        # Whether this adapter's #children accepts the
+        # entity_bearing: keyword (the built-ins do; downstream
+        # overrides may keep the pre-0.5.36 one-argument signature —
+        # issue #218). Reflected once per adapter class.
+        def children_accepts_entity_flag?
+          return @children_accepts_entity_flag unless @children_accepts_entity_flag.nil?
+
+          kinds = %i[key keyrest keyreq]
+          @children_accepts_entity_flag =
+            method(:children).parameters.any? do |kind, _name|
+              kinds.include?(kind)
+            end
+        end
+
+        # Protocol-level native equality; engines with more than one
+        # wrapper class over one C node override (leptris native
+        # read layer). Shared adapter examples compare through this.
+        def same_node?(one, other)
+          one == other
+        end
+
         # Backends without a native subtree digest answer nil —
         # the wrapper contract Node#digest gates on (issue #173).
         def digest(*)
@@ -272,7 +293,7 @@ namespace_validation_mode: :strict)
         # Marker-tracking adapters override this so the post-serialize
         # restore can skip its full-output scans on marker-free
         # documents; the default stays conservative.
-        def entity_bearing?(_native)
+        def entity_bearing?(_native, _doc = nil)
           true
         end
 

data/lib/moxml/adapter/leptris/document_parts.rb

@@ -38,6 +38,15 @@ module Moxml
 
           texts = attachments.get(doc, :document_text)
           children.concat(texts) if texts
+
+          # Canonicalize through the doc's address-keyed native
+          # cache: #root mints a NativeNode for the document
+          # element, and an uncanonicalized list would hand the
+          # binding twin instead — two wrappers over one node, and
+          # equal?-based exclusion (canon's document-element skip)
+          # silently breaks (issue #219). Mint-on-miss converges
+          # both accessors on the same native object.
+          children.map! { |child| canonical_native(doc, child) } if NATIVE_READ_LAYER
           children
         end
 
@@ -164,10 +173,18 @@ module Moxml
             return nil
           end
 
+          # Passing encoding when it equals the document's own is a
+          # no-op conversion the serializer still pays (~20% of a
+          # 31KB document serialize); nil skips it. Byte-equality of
+          # both forms verified on 1.9.163.2 — gate to those builds.
+          encoding = options[:encoding]
+          if NATIVE_STRINGS_UTF8 && encoding.to_s.casecmp?("UTF-8")
+            encoding = nil
+          end
           kwargs = {
             indent: options.fetch(:indent, 0),
             no_decl: !include_decl,
-            encoding: options[:encoding],
+            encoding: encoding,
           }
           if INDENT_UNIT_SUPPORTED && options[:indent_text].is_a?(String)
             kwargs[:indent_text] = options[:indent_text]

data/lib/moxml/adapter/leptris/markers.rb

@@ -8,7 +8,16 @@ module Moxml
         # the ER builder path flips it, and the split/restore scans
         # consult it. Customized natives only exist as split products
         # of marker-bearing text, so they always report true.
-        def entity_bearing?(native)
+        # doc is the binding document when the wrapper could resolve
+        # it through its parent chain; the C climb is the fallback.
+        def entity_bearing?(native, doc = nil)
+          if NATIVE_READ_LAYER && native.is_a?(::Leptris::XML::NativeNode)
+            doc ||= doc_for(native)
+            return false if doc.nil?
+
+            return attachments.get(doc, :entity_markers) != false
+          end
+
           case native
           when CustomizedLeptris::Declaration, CustomizedLeptris::Doctype,
              CustomizedLeptris::EntityReference, CustomizedLeptris::TextSegment,

data/lib/moxml/adapter/leptris/materialize.rb

@@ -39,16 +39,26 @@ module Moxml
         end
 
         def materialize_fields(native, buffers, &block)
-          doc = native.is_a?(::Leptris::XML::Document) ? native : native.document
-          # Marker-bearing text needs the split pipeline (children-level
-          # ER expansion); the bulk path has no marker handling.
-          return nil if doc.nil? || attachments.get(doc, :entity_markers)
-
-          root_ptr = if native.is_a?(::Leptris::XML::Document)
-                       doc.root&.c_ptr
-                     else
-                       native.c_ptr
-                     end
+          if NATIVE_READ_LAYER && native.is_a?(::Leptris::XML::NativeNode)
+            # The native read layer mints NativeNodes from #root and
+            # #children; they expose address, not document/c_ptr
+            # (issue #213 — the wrapper-level materialize path).
+            doc = doc_for(native)
+            return nil if doc.nil? || attachments.get(doc, :entity_markers)
+
+            root_ptr = ::FFI::Pointer.new(native.address)
+          else
+            doc = native.is_a?(::Leptris::XML::Document) ? native : native.document
+            # Marker-bearing text needs the split pipeline (children-level
+            # ER expansion); the bulk path has no marker handling.
+            return nil if doc.nil? || attachments.get(doc, :entity_markers)
+
+            root_ptr = if native.is_a?(::Leptris::XML::Document)
+                         doc.root&.c_ptr
+                       else
+                         native.c_ptr
+                       end
+          end
           return nil unless root_ptr
 
           walk_fields(root_ptr, 0, buffers,

data/lib/moxml/adapter/leptris/serialize.rb

@@ -30,6 +30,7 @@ module Moxml
         EMPTY_ELEMENT_RE = %r{<([A-Za-z_][\w.:-]*+)((?:"[^"]*+"|'[^']*+'|[^<>"'/]++)*+)/>}
 
         def serialize(node, options = {})
+          node = to_binding(node) if NATIVE_READ_LAYER
           # Entity restoration belongs to the wrapper layer
           # (Node#to_xml runs adapter.restore_entities for every
           # adapter); doing it here scanned the output a second time.
@@ -134,6 +135,13 @@ module Moxml
         # platform gem) emit text-content ampersands unescaped; the
         # detection below is a no-op on correct builds.
         RAW_AMP_RE = /&(?!#{Entity::NAME_PATTERN};|#\d+;|#x[0-9A-Fa-f]+;)/
+        # The unescaped-ampersand emission was observed on the Linux
+        # 1.9.50 platform gem; correct builds make the probe a
+        # no-op that still pays its scan (~2µs per document
+        # serialize). Stand it down on modern engines — the
+        # consistency round-trips fail loudly on any regression.
+        RAW_AMP_GUARD_ACTIVE =
+          Gem::Version.new(::Leptris::VERSION) < Gem::Version.new("1.9.60")
 
         # A raw "<" in text position — the engine intermittently
         # lost the escape when parsing under allocation pressure
@@ -158,7 +166,8 @@ module Moxml
           # Corruption guards: the 1-char ampersand probe is ~1µs
           # (memchr-class); the raw-< scan runs only on builds that
           # still carry the parse race (leptris-ruby#131).
-          needs_amp = xml.include?("&") && xml.match?(RAW_AMP_RE)
+          needs_amp = RAW_AMP_GUARD_ACTIVE &&
+            xml.include?("&") && xml.match?(RAW_AMP_RE)
           needs_lt = RAW_LT_GUARD_ACTIVE && xml.match?(RAW_LT_TRIGGER_RE)
           return xml unless needs_apos || needs_expand || needs_amp || needs_lt
 

data/lib/moxml/adapter/leptris.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "ffi"
+
 return if RUBY_ENGINE == "opal"
 
 require "stringio"
@@ -40,6 +42,106 @@ module Moxml
       DIGEST_SUPPORTED =
         Gem::Version.new(::Leptris::VERSION) >= Gem::Version.new("1.9.99")
 
+      # Opt-in native read layer (leptris-ruby#185, bindings >= 1.9.162.6):
+      # TypedData node wrappers with C-bound hot reads and bulk
+      # children construction. Minted from #root downward; the C
+      # tree is shared with the binding, so writes made through the
+      # bridged binding nodes are visible to native reads. Installs
+      # without the compiled bundle (ruby-platform gem) simply stay
+      # on the binding path.
+      begin
+        require "leptris/xml/native_layer"
+      rescue LoadError, StandardError
+        nil
+      end
+      NATIVE_READ_LAYER =
+        defined?(::Leptris::XML::NativeNode) &&
+        Gem::Version.new(::Leptris::VERSION) >= Gem::Version.new("1.9.162.6")
+
+      # 1.9.163.2's native layer returns UTF-8, unfrozen strings
+      # (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")
+
+      # 1.9.163.2 moved the native bulk children into C
+      # (Native.bulk_children) and fixed the 512 truncation
+      # (leptris-ruby#202). The 162.6-163.1 window carries the
+      # binding-side truncation, so moxml fetches with its own
+      # count-then-copy scratch there; newer bindings use their
+      # 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 unconditionally: the body self-guards, and call
+      # sites must never depend on the layer having loaded
+      # (issue #217 — binding-only installs crashed on the
+      # unguarded bridges).
+      class << self
+        # Binding node for any native: identity for binding nodes
+        # (and on installs without the native layer — the constant
+        # check short-circuits), a Node.wrap over the shared C
+        # pointer for NativeNodes.
+        def to_binding(node)
+          return node unless NATIVE_READ_LAYER &&
+            node.is_a?(::Leptris::XML::NativeNode)
+
+          doc = doc_for(node)
+          ptr = ::FFI::Pointer.new(node.address)
+          return ::Leptris::XML::Node.wrap(ptr, doc) if doc
+
+          ::Leptris::XML::Node.wrap(ptr, nil)
+        end
+      end
+
+      if NATIVE_READ_LAYER
+        # root NativeNode -> binding document (recorded at #root
+        # mint; the native layer exposes no document accessor).
+        @native_doc_roots = ObjectSpace::WeakMap.new
+
+        class << self
+          def record_native_doc(root_native, doc)
+            @native_doc_roots[root_native] = doc
+          end
+
+          # Protocol-level node equality: one engine can hand out
+          # two wrapper classes over the same C node (native layer +
+          # binding), so raw == is not identity across the seam.
+          def same_node?(one, other)
+            return true if one.equal?(other)
+
+            if NATIVE_READ_LAYER
+              native_one = one.is_a?(::Leptris::XML::NativeNode)
+              native_other = other.is_a?(::Leptris::XML::NativeNode)
+              if native_one || native_other
+                address_one = native_one ? one.address : one.c_ptr.address
+                address_other = native_other ? other.address : other.c_ptr.address
+                return address_one == address_other
+              end
+            end
+
+            one == other
+          end
+
+          # Binding document for a NativeNode subtree: climb parents
+          # to the root (C-bound reads) and look the doc up in the
+          # root registry. Detached subtrees answer nil.
+          def doc_for(node)
+            current = node
+            current = current.parent while current&.parent
+            @native_doc_roots[current]
+          end
+        end
+      end
+
+      # Binding node for any native: identity for binding nodes, a
+      # Node.wrap over the shared C pointer for NativeNodes (used by
+      # the write/serialize/namespace paths the native layer does
+      # not carry).
+
       # 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
@@ -73,12 +175,15 @@ module Moxml
       # Bumped whenever a document's :entity_markers flag is written
       # (parse, parse_html, entity-reference mint) so wrapper-level
       # entity_bearing? memos invalidate.
-      def self.serialize_generation
-        @serialize_generation ||= 0
+      # attr_reader beats the ||= memo on every guarded read (the
+      # entity guard consults this per bare read / text read).
+      class << self
+        attr_reader :serialize_generation
       end
+      @serialize_generation = 0
 
       def self.bump_serialize_generation
-        @serialize_generation = serialize_generation + 1
+        @serialize_generation += 1
       end
 
       # leptris-ruby#103: prefixed attribute tests inside predicates
@@ -191,7 +296,14 @@ module Moxml
         # document-plus-attachment probe here cost more than the
         # read itself).
         def bare_attr_value(element, name)
-          element[name.to_s]
+          value = element[name.to_s]
+          if !NATIVE_STRINGS_UTF8 && NATIVE_READ_LAYER &&
+              element.is_a?(::Leptris::XML::NativeNode) &&
+              value.is_a?(String)
+            return value.dup.force_encoding(Encoding::UTF_8)
+          end
+
+          value
         end
 
         def native_identity_stable?
@@ -365,6 +477,13 @@ module Moxml
           ::Leptris::XML::Document.create
         end
 
+        # The native builder factories (native_create_element/text)
+        # are deliberately NOT adopted: native mutations do not
+        # advance the binding's document version, so the binding's
+        # memoized reads over the same tree go stale; attaching the
+        # created natives also pays a per-node to_binding bridge
+        # that costs more than the factory saves (create+attach
+        # measured 5816 -> 7697ns vs nokogiri 1750).
         def create_native_element(name, owner_doc = nil)
           (owner_doc || create_document).create_element(name.to_s)
         end
@@ -428,10 +547,12 @@ module Moxml
         end
 
         def create_native_namespace(element, prefix, uri)
+          element = to_binding(element) if NATIVE_READ_LAYER
           element.add_namespace_definition(prefix, uri)
         end
 
         def set_namespace(node, namespace)
+          node = to_binding(node) if NATIVE_READ_LAYER
           return set_attribute_namespace(node, namespace) if node.is_a?(::Leptris::XML::Attr)
 
           element = node
@@ -498,6 +619,8 @@ module Moxml
         end
 
         def namespace(node)
+          node = to_binding(node) if NATIVE_READ_LAYER
+
           # The binding resolves Attr#namespace to the declaration but
           # without the prefix; when the qualified name carries one,
           # prefer the in-scope declaration that binds it so wrappers
@@ -549,6 +672,16 @@ module Moxml
         end
 
         def node_type(node)
+          if NATIVE_READ_LAYER &&
+              node.is_a?(::Leptris::XML::NativeNode)
+            type = node.node_type
+            # The native layer spells PIs :pi; the wrapper contract
+            # (node_type_map) says :processing_instruction.
+            return :processing_instruction if type == :pi
+
+            return type
+          end
+
           # Frequency-ordered: elements and text dominate every real
           # document, and Node.wrap dispatches here once per cold
           # wrap. CDATA must precede Text (CDATA < Text in the
@@ -574,6 +707,9 @@ module Moxml
         # lightweight Attr triples answer nil.
         def digest(node, drop_ws_text: false)
           return nil unless DIGEST_SUPPORTED
+          if NATIVE_READ_LAYER && node.is_a?(::Leptris::XML::NativeNode)
+            return to_binding(node).digest(drop_ws: drop_ws_text)
+          end
           return nil unless node.is_a?(::Leptris::XML::Node) &&
             !node.is_a?(::Leptris::XML::ResultAttr)
 
@@ -584,10 +720,20 @@ module Moxml
           return node.root_name if node.is_a?(::Leptris::XML::DocType)
           return node.target if node.is_a?(CustomizedLeptris::DocumentPI)
 
+          if NATIVE_READ_LAYER && node.is_a?(::Leptris::XML::NativeNode)
+            # PIs expose no name through the native layer.
+            return to_binding(node).target.to_s if node.node_type == :pi
+
+            return node.name if NATIVE_STRINGS_UTF8
+
+            node.name.dup.force_encoding(Encoding::UTF_8)
+          end
+
           node.name.to_s.dup.force_encoding("UTF-8")
         end
 
         def set_node_name(node, name)
+          node = to_binding(node) if NATIVE_READ_LAYER
           case node
           when ::Leptris::XML::ProcessingInstruction, CustomizedLeptris::DocumentPI then node.target = name
           else node.name = name
@@ -595,6 +741,7 @@ module Moxml
         end
 
         def duplicate_node(node)
+          node = to_binding(node) if NATIVE_READ_LAYER
           case node
           when CustomizedLeptris::Declaration
             CustomizedLeptris::Declaration.new(node.version, node.encoding, node.standalone)
@@ -609,12 +756,42 @@ module Moxml
           end
         end
 
-        def children(node)
+        def children(node, entity_bearing: false)
+          if NATIVE_READ_LAYER && node.is_a?(::Leptris::XML::NativeNode)
+            # Bulk C children through moxml's own scratch (see
+            # NATIVE_READ_LAYER note above). Entity-marker documents
+            # bridge each child for the marker split — the
+            # TextSegment reconstruction reads binding text nodes;
+            # the wrapper's memo supplies the flag, so deriving it
+            # here costs no C parent climb per call.
+            natives = if NATIVE_BULK_FIXED
+                        node.children.to_a
+                      else
+                        bulk_native_children(node)
+                      end
+            return natives unless entity_bearing
+
+            # Entity-marker documents: bridge for the marker split
+            # (TextSegment reconstruction reads binding text nodes).
+            doc = doc_for(node)
+            bound_children = natives.map { |child| to_binding(child) }
+            if doc && attachments.get(doc, :entity_markers) == false
+              return bound_children
+            end
+
+            return split_entity_markers(bound_children, to_binding(node))
+          end
           # Frequency-ordered: elements dominate every walk and paid
           # ten failed compares to reach the else arm.
           case node
           when ::Leptris::XML::Element
             natives = node.children.to_a
+            if NATIVE_READ_LAYER && natives.size == 512
+              # Binding scratch truncation (leptris-ruby#202): a
+              # full batch is ambiguous — refetch through moxml's
+              # own buffers to be sure.
+              natives = bulk_binding_children(node)
+            end
             # Parse records whether the preprocessed source held any
             # entity markers, and the ER builder path flips the flag
             # when it mints one. A false flag lets traversal skip the
@@ -643,6 +820,16 @@ module Moxml
         end
 
         def parent(node)
+          if NATIVE_READ_LAYER && node.is_a?(::Leptris::XML::NativeNode)
+            parent = node.parent
+            return parent if parent
+
+            doc = doc_for(node)
+            return doc if doc&.root && doc.root.c_ptr.address == node.address
+
+            return nil
+          end
+
           # Frequency-ordered: elements dominate navigation and paid
           # three failed compares to reach the else arm.
           case node
@@ -657,6 +844,99 @@ module Moxml
           end
         end
 
+        # Fallback for natives without a registered document: walk
+        # first_child/next_sibling at the FFI level and wrap binding
+        # nodes over the raw pointers.
+        def sibling_walk_children(node)
+          ptr = ::FFI::Pointer.new(node.address)
+          first = ::Leptris::XML::FFI.leptris_node_first_child(ptr)
+          children = []
+          current = first
+          until current.null?
+            children << ::Leptris::XML::Node.wrap(current, nil)
+            current = ::Leptris::XML::FFI.leptris_node_next_sibling(current)
+          end
+          children
+        end
+
+        # Native twin for a binding node through the document's
+        # address-keyed native cache — minting on miss so every
+        # accessor converges on one native per node (issue #219).
+        # Binding natives (Attribute/Attr, synthetic wrappers) and
+        # docless nodes pass through unchanged.
+        def canonical_native(doc, node)
+          return node unless node.is_a?(::Leptris::XML::Element)
+
+          cache = doc.native_cache
+          cache[node.c_ptr.address] ||=
+            ::Leptris::XML::NativeNode.from(doc, node.c_ptr)
+        end
+
+        # The binding-node twin of bulk_native_children (identity via
+        # the binding's wrap cache).
+        def bulk_binding_children(node)
+          copied, pointers = bulk_child_buffers(node.c_ptr)
+          return node.children.to_a if copied.zero?
+
+          doc = node.document
+          Array.new(copied) do |i|
+            ::Leptris::XML::Node.wrap(pointers.get_pointer(i * 8), doc)
+          end
+        end
+
+        # Bulk child fetch with moxml's own grow-to-fit thread-local
+        # scratch: count first (exact), size the buffers to it, wrap
+        # each pointer as a native-layer node. Correct on every
+        # binding version — the binding's own scratch truncates at
+        # 512 on 1.9.163.x (leptris-ruby#202).
+        def bulk_native_children(node)
+          copied, pointers = bulk_child_buffers(::FFI::Pointer.new(node.address))
+          return [] if copied.zero?
+
+          doc = doc_for(node)
+          if doc.nil?
+            # Unregistered native (adapter-level use outside #root):
+            # the 163.2 binding's bulk needs a document, so walk
+            # siblings instead of crashing through a doc-less wrap.
+            return sibling_walk_children(node)
+          end
+
+          # Share the layer's per-document identity cache (keyed by
+          # node address): NativeNode.from alone mints fresh objects
+          # per call on 1.9.163.x, which would fork moxml wrappers.
+          cache = doc.native_cache
+          Array.new(copied) do |i|
+            child_ptr = pointers.get_pointer(i * 8)
+            cache[child_ptr.address] ||=
+              ::Leptris::XML::NativeNode.from(doc, child_ptr)
+          end
+        end
+
+        # Shared count-then-copy fetch over moxml's grow-to-fit
+        # thread-local scratch — the layer above the binding's
+        # (buggy on 1.9.163.x) own buffers. Returns [copied, pointers].
+        def bulk_child_buffers(ptr)
+          total = ::Leptris::XML::FFI.leptris_node_children_ex(ptr, nil, nil, 0)
+          return [0, nil] if total.zero?
+
+          scratch = (Thread.current[:moxml_leptris_children] ||= {})
+          pointers = scratch[:pointers]
+          if pointers.nil? || pointers.size / 8 < total
+            pointers&.free
+            pointers = scratch[:pointers] =
+              ::FFI::MemoryPointer.new(:pointer, total)
+          end
+          kinds = scratch[:kinds]
+          if kinds.nil? || kinds.size / 4 < total
+            kinds&.free
+            kinds = scratch[:kinds] = ::FFI::MemoryPointer.new(:int, total)
+          end
+          copied = ::Leptris::XML::FFI.leptris_node_children_ex(
+            ptr, pointers, kinds, total
+          )
+          [copied, pointers]
+        end
+
         # The binding reports the root element as parentless; the
         # moxml contract roots at the document.
         def root_parent(node)
@@ -664,14 +944,25 @@ module Moxml
         end
 
         def next_sibling(node)
+          return node.next_sibling if NATIVE_READ_LAYER &&
+            node.is_a?(::Leptris::XML::NativeNode)
+
           node.next_sibling if node.is_a?(::Leptris::XML::Node)
         end
 
         def previous_sibling(node)
+          # Bridged, not the native sibling walk: the native layer
+          # exposes next_sibling only, and its children batch
+          # truncates at 512 — the predecessor beyond that would be
+          # wrong.
+          node = to_binding(node)
           node.previous_sibling if node.is_a?(::Leptris::XML::Node)
         end
 
         def document(node)
+          return doc_for(node) if NATIVE_READ_LAYER &&
+            node.is_a?(::Leptris::XML::NativeNode)
+
           case node
           when ::Leptris::XML::Document then node
           when CustomizedLeptris::Declaration, CustomizedLeptris::Doctype then node.parent_doc
@@ -680,7 +971,18 @@ module Moxml
         end
 
         def root(document)
-          document.root
+          r = document.root
+          return nil if r.nil?
+
+          if NATIVE_READ_LAYER
+            # Through the same address-keyed cache as the children
+            # path: NativeNode.from alone mints a fresh object per
+            # call on 1.9.163.x, splitting the wrappers (issue #219).
+            native = canonical_native(document, r)
+            record_native_doc(native, document)
+            return native
+          end
+          r
         end
 
         def line_number(node)
@@ -691,6 +993,7 @@ module Moxml
         end
 
         def attributes(element)
+          element = to_binding(element)
           element.attribute_nodes
         end
 
@@ -707,6 +1010,7 @@ module Moxml
         end
 
         def set_attribute(element, name, value)
+          element = to_binding(element) if NATIVE_READ_LAYER
           element[name.to_s] = value.to_s
         end
 
@@ -726,14 +1030,17 @@ module Moxml
         end
 
         def get_attribute(element, name)
+          element = to_binding(element)
           element.attribute_nodes.find { |attr| attr.name == name.to_s }
         end
 
         def get_attribute_value(element, name)
+          element = to_binding(element)
           element[name.to_s]
         end
 
         def remove_attribute(element, name)
+          element = to_binding(element)
           element.remove_attribute(name.to_s)
         end
 
@@ -743,6 +1050,10 @@ module Moxml
         end
 
         def add_child(parent, child)
+          if NATIVE_READ_LAYER
+            parent = to_binding(parent)
+            child = to_binding(child)
+          end
           case parent
           when ::Leptris::XML::Document then add_document_child(parent, child)
           else
@@ -759,6 +1070,7 @@ module Moxml
         end
 
         def add_previous_sibling(node, new_node)
+          node = to_binding(node) if NATIVE_READ_LAYER
           # A PI inserted before the root lives at document level in
           # libleptris's model, not in the element tree.
           if new_node.is_a?(::Leptris::XML::ProcessingInstruction) &&
@@ -770,10 +1082,12 @@ module Moxml
         end
 
         def add_next_sibling(node, new_node)
+          node = to_binding(node) if NATIVE_READ_LAYER
           node.add_next_sibling(new_node)
         end
 
         def remove(node)
+          node = to_binding(node) if NATIVE_READ_LAYER
           case node
           when CustomizedLeptris::Declaration
             remove_declaration(node.parent_doc) if node.parent_doc
@@ -793,6 +1107,10 @@ module Moxml
         end
 
         def replace(node, new_node)
+          if NATIVE_READ_LAYER
+            node = to_binding(node)
+            new_node = to_binding(new_node)
+          end
           return node.replace(new_node) if node.is_a?(::Leptris::XML::Element)
 
           # libleptris only offers element-anchored insertion, so a
@@ -817,10 +1135,20 @@ module Moxml
         end
 
         def replace_children(node, new_children)
+          if NATIVE_READ_LAYER
+            node = to_binding(node)
+            new_children = new_children.map { |child| to_binding(child) }
+          end
           node.children = new_children
         end
 
         def text_content(node)
+          if NATIVE_READ_LAYER && node.is_a?(::Leptris::XML::NativeNode)
+            return node.content if NATIVE_STRINGS_UTF8
+
+            return node.content.dup.force_encoding(Encoding::UTF_8)
+          end
+
           # Frequency-ordered: elements dominate reads; they paid
           # three failed compares to reach the else arm. The
           # duplicated branch bodies are the point.
@@ -837,6 +1165,7 @@ module Moxml
         end
 
         def inner_text(node)
+          node = to_binding(node) if NATIVE_READ_LAYER
           # moxml semantic: direct text children only — no descendant
           # text (that is #text), no comments. Entity references
           # contribute their serialized form.
@@ -851,6 +1180,7 @@ module Moxml
         end
 
         def set_text_content(node, content)
+          node = to_binding(node) if NATIVE_READ_LAYER
           case node
           when ::Leptris::XML::Document
             node.root&.content = content.to_s
@@ -899,6 +1229,7 @@ module Moxml
         end
 
         def namespace_definitions(element)
+          element = to_binding(element) if NATIVE_READ_LAYER
           element.namespace_definitions
         end
 
@@ -929,6 +1260,7 @@ module Moxml
         NATIVE_GATE_CACHE = XPath::Cache.new(100)
 
         def xpath(node, expression, namespaces = {})
+          node = to_binding(node) if NATIVE_READ_LAYER
           native = native_xpath(node, expression, namespaces)
           return native unless native.nil?
 

data/lib/moxml/adapter/libxml.rb

@@ -312,7 +312,7 @@ module Moxml
           # Native documents are read-only, do nothing for them
         end
 
-        def children(node)
+        def children(node, **_entity_bearing)
           native_node = unpatch_node(node)
           return [] unless native_node
 

data/lib/moxml/adapter/nokogiri.rb

@@ -248,7 +248,7 @@ module Moxml
           node.name = name
         end
 
-        def children(node)
+        def children(node, **_entity_bearing)
           node.children
         end
 

data/lib/moxml/adapter/oga.rb

@@ -232,7 +232,7 @@ module Moxml
           node.name = name
         end
 
-        def children(node)
+        def children(node, **_entity_bearing)
           all_children = []
 
           if node.is_a?(::Oga::XML::Document)

data/lib/moxml/adapter/ox.rb

@@ -298,7 +298,7 @@ module Moxml
           end
         end
 
-        def children(node)
+        def children(node, **_entity_bearing)
           return [] unless node.is_a?(::Ox::Element) || node.is_a?(::Ox::Document)
 
           result = node.nodes || []

data/lib/moxml/adapter/rexml.rb

@@ -188,7 +188,7 @@ module Moxml
           end
         end
 
-        def children(node)
+        def children(node, **_entity_bearing)
           return [] unless node.is_a?(::REXML::Parent)
 
           # Return all children preserving whitespace text nodes

data/lib/moxml/c14n.rb

@@ -66,7 +66,7 @@ module Moxml
       return nil unless adapter == Moxml::Adapter::Leptris &&
         Moxml::Adapter::Leptris.native_c14n_byte_safe?
 
-      node_or_xml.native.canonicalize(
+      Moxml::Adapter::Leptris.to_binding(node_or_xml.native).canonicalize(
         ::Leptris::XML::FFI::C14N_1_0, nil,
         mode: ::Leptris::XML::FFI::C14N_MODE_CANONICAL
       )

data/lib/moxml/element.rb

@@ -62,7 +62,10 @@ module Moxml
       # resolver's expanded-name semantics only pay for prefixed
       # names, where resolution is real work.
       adapter = self.adapter
-      if !key.include?(":") && adapter.bare_get_qname_safe?
+      # Capability memo: the adapter predicate is a per-read
+      # dispatch for a lifetime constant.
+      if !key.include?(":") &&
+          ((@bare_qname_safe ||= adapter.bare_get_qname_safe?) == true)
         # 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

data/lib/moxml/node.rb

@@ -54,7 +54,17 @@ module Moxml
 
     def children
       @children ||= begin
-        natives = adapter.children(@native)
+        # The wrapper's entity memo decides the marker split; the
+        # adapter would otherwise re-derive it per call (a C parent
+        # climb on the native layer). The kwarg rides along only
+        # for adapters that accept it — downstream overrides with
+        # the pre-0.5.36 one-argument signature raise ArgumentError
+        # otherwise (issue #218).
+        natives = if adapter.children_accepts_entity_flag?
+                    adapter.children(@native, entity_bearing: entity_bearing?)
+                  else
+                    adapter.children(@native)
+                  end
         natives = natives.map { adapter.patch_node(_1, @native) } if adapter.patches_children?
         NodeSet.new(natives, context, self)
       end
@@ -150,10 +160,24 @@ module Moxml
         @entity_bearing
       else
         @entity_bearing_gen = gen
-        @entity_bearing = adapter.entity_bearing?(@native)
+        @entity_bearing = adapter.entity_bearing?(@native, document_native_for_markers)
       end
     end
 
+    # Binding document through the wrapper parent chain — pure Ruby
+    # attr reads; the native-layer fallback climbs C parents per
+    # call (the doc_for walk was the largest wrapper-layer cost on
+    # the consumer pipeline after the native adoption).
+    def document_native_for_markers
+      node = self
+      while node
+        return node.native if node.document?
+
+        node = node.parent_node
+      end
+      nil
+    end
+
     def xpath(expression, namespaces = {})
       result = adapter.xpath(@native, expression, namespaces)
       # Adapter contract: Array<native> | LazyNodeSet | scalar.
@@ -384,7 +408,11 @@ module Moxml
     end
 
     def ==(other)
-      self.class == other.class && @native == other.native
+      # Native equality goes through the adapter: engines with a
+      # native read layer hand out two wrapper classes over one C
+      # node, and raw native == is false across that seam.
+      self.class == other.class &&
+        adapter.same_node?(@native, other.native)
     end
 
     TYPES.each do |node_type|
@@ -447,7 +475,7 @@ module Moxml
     # Internal: Set the parent node for cache invalidation tracking.
     # Called by NodeSet, Document, Element when establishing parent-child
     # relationships. Public to allow cross-class usage within Moxml internals.
-    attr_writer :parent_node
+    attr_accessor :parent_node
 
     def adapter
       # A context's adapter object is fixed for its lifetime; the

data/lib/moxml/version.rb

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

data/spec/integration/contract_parity_spec.rb

@@ -91,6 +91,16 @@
       end
     end
 
+    describe "document-element wrapper unification (issue #219)" do
+      it "hands the same wrapper from #root and #children in both call orders" do
+        doc = ctx.parse(%(<catalog><book/></catalog>))
+        expect(doc.root).to equal(doc.children.grep(Moxml::Element).first)
+
+        doc2 = ctx.parse(%(<catalog><book/></catalog>))
+        expect(doc2.children.grep(Moxml::Element).first).to equal(doc2.root)
+      end
+    end
+
     describe "qname create + namespace assignment (issue #208)" do
       it "does not double the prefix when the name is already qualified" do
         doc = ctx.parse(%(<r xmlns:p="urn:p"/>))

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

@@ -43,7 +43,7 @@ RSpec.shared_examples "Moxml::NodeSet" do
       it "compares nodes" do
         xpath_results = doc.xpath("//child")
         element_children = doc.root.children.grep(Moxml::Element)
-        expect(xpath_results.map(&:native)).to eq(element_children.map(&:native))
+        expect(xpath_results.to_a).to eq(element_children)
       end
     end
 

data/spec/moxml/adapter/base_spec.rb

@@ -24,4 +24,27 @@ RSpec.describe Moxml::Adapter::Base do
       skip "Serialize is adapter-specific, not in Base"
     end
   end
+
+  describe "children compatibility (issue #218)" do
+    it "calls one-argument downstream overrides without the keyword" do
+      legacy = Class.new(Moxml::Adapter::Nokogiri) do
+        class << self
+          # The override exists for its one-argument signature —
+          # the pre-0.5.36 downstream shape.
+          # rubocop:disable-next Lint/UselessMethodDefinition
+          def children(node)
+            super
+          end
+        end
+      end
+      expect(legacy.children_accepts_entity_flag?).to be(false)
+      node = Moxml.new(:nokogiri).parse(%(<r><e>x</e></r>)).root.native
+      expect(legacy.children(node).length).to eq(1)
+    end
+
+    it "passes the keyword to built-in adapters" do
+      expect(Moxml::Adapter::Leptris.children_accepts_entity_flag?).to be(true)
+      expect(Moxml::Adapter::Nokogiri.children_accepts_entity_flag?).to be(true)
+    end
+  end
 end

data/spec/moxml/adapter/leptris_spec.rb

@@ -635,6 +635,28 @@ RSpec.describe Moxml::Adapter::Leptris do
     end
   end
 
+  describe "to_binding is defined regardless of the native layer (issue #217)" do
+    it "is the identity for binding nodes" do
+      ctx = Moxml.new(:leptris)
+      doc = ctx.parse(%(<r><a x="1"><b/></a></r>))
+      element = described_class.to_binding(doc.native.root)
+      expect(element).to equal(doc.native.root)
+      # every bridged entry point answers on binding natives
+      expect(doc.root.children.first.attributes.length).to eq(1)
+      expect(doc.root.children.first["x"]).to eq("1")
+    end
+  end
+
+  describe "materialize through the wrapper (issue #213)" do
+    it "materializes a native-layer root without NoMethodError" do
+      ctx = Moxml.new(:leptris)
+      doc = ctx.parse(%(<r><a x="1">t1</a><b><c y="2">t2</c></b></r>))
+      count = 0
+      doc.root.materialize_fields { |*_record| count += 1 }
+      expect(count).to be > 0
+    end
+  end
+
   describe "subtree digest (issue #173, leptris#869)" do
     let(:ctx) { Moxml.new(:leptris) }
 

data/spec/moxml/adapter/shared_examples/adapter_contract.rb

@@ -79,22 +79,20 @@ RSpec.shared_examples "xml adapter" do
       first = children[0]
       second = children[1]
 
-      expect(described_class.next_sibling(first)).to eq(second)
-      expect(described_class.previous_sibling(second)).to eq(first)
+      expect(described_class.same_node?(described_class.next_sibling(first), second)).to be(true)
+      expect(described_class.same_node?(described_class.previous_sibling(second), first)).to be(true)
     end
 
     it "adds child" do
       element = described_class.create_element("new")
       described_class.add_child(root, element)
-      expect(described_class.children(root).last).to eq(element)
+      expect(described_class.same_node?(described_class.children(root).last, element)).to be(true)
     end
 
     it "adds text child" do
       described_class.add_child(root, "text")
-      # a workaround for Rexml until we convert tests to work with Moxml wrappers
       last_child = described_class.children(root).last
-      last_text = last_child.respond_to?(:text) ? last_child.text : last_child.to_s
-      expect(last_text).to eq("text")
+      expect(described_class.text_content(last_child)).to eq("text")
     end
   end
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: moxml
 version: !ruby/object:Gem::Version
-  version: 0.5.35
+  version: 0.5.41
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-09-14 00:00:00.000000000 Z
+date: 2026-09-15 00:00:00.000000000 Z
 dependencies: []
 description: |
   Moxml is a unified XML manipulation library that provides a common API