moxml 0.5.150 → 0.5.152

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 73b67b633933c60095bdeafd744a8f7a827066edf478245e9c2f49aadf1d75e6
-  data.tar.gz: 92320b13e8bb745cd5b650e85d4fa7b8397e082871a7c255cb61f637595c6048
+  metadata.gz: 5a384caeb57d40002410d3ebfb5ef9a22eed2793caab5db918d9bfeacaacbdee
+  data.tar.gz: 166f445cae5e401f0cf5be6a3f766eb9232809fe1217e3e90e46f2e315afce8e
 SHA512:
-  metadata.gz: c34b4df4cf09797b5a28ec909e0df41c970897676154fa1b66dc9ebbd18cdccb13408b83f5647c44d41cfda7ebcbf09571314d0bfe71b572a58dde972e78994b
-  data.tar.gz: d926c442a8b0dc0f9d159f27f42772a3af48358fbbd67d62d7cec1cdd51c609110def03466fa93c5b95b2eccfdaa7ab34e26c818b30b2651a996b9879c63d699
+  metadata.gz: cc19f58546f479a713b3039295b2eac40b5c83166dacc77af0017e83b40f2d3f8bffb028767f744ef29dae5688c3c5d3c34a248e9d3f75bede910b444c04b675
+  data.tar.gz: 9f9a64184feb0ba0a0eba61300a014339b81c7a58d69a1b1ff0dd4610abb7c239a6184e260253542f4643410fcfe3b15e54470b72cdb72283e7bf5a85f3d1639

data/docs/_pages/ecosystem.adoc

@@ -21,7 +21,7 @@ validation target, never a stand-in.
 
 | `lutaml/lutaml-model` | — | 6213+ examples green on the released pair
 
-| `lutaml/canon` | — | 2573 examples, 0 failures locally; in CI the Windows leg fails one JSON-engine parity example (`yaml_engine_parity_spec.rb:123`, the resolved json gem's duplicate-key verdict) — unrelated to XML processing, owner-held in canon
+| `lutaml/canon` | — | 2573 examples, 0 failures (a transient Windows failure of one JSON-engine parity example — yeptris 0.6.34.2's undefined `MARSHAL_STRICT_DUP_KEYS` under json 3 — cleared with yeptris 0.6.34.3)
 
 | `metanorma/metanorma-standoc` | ghostscript | 627 examples green in CI on main (the boilerplate-fixture failure seen during the 04/05 validation was resolved by the 06 adapter fixes; a few local-only failures still need generated assets)
 
@@ -42,7 +42,7 @@ a declared, decided lane.
 |===
 | Consumer | Use | Disposition
 
-| canon | HTML5 parse-lint (`parse_html(collect_errors:)`) | **Facade capability shipped**: `Moxml::Context#parse_html` forwards `collect_errors` and `Document#parse_diagnostics` answers the §13.2.5 token stream with code/line/column. canon adopts it in canon#281, which is owner-held (moxml does not merge canon PRs).
+| canon | HTML5 parse-lint (`parse_html(collect_errors:)`) | **Retired** (canon#281, merged): `Moxml::Context#parse_html` forwards `collect_errors` and `Document#parse_diagnostics` answers the §13.2.5 token stream with code/line/column; canon rides the facade.
 
 | canon | c14n native delegation (`doc.native.c14n`) | **Decided lane**: canon owns the c14n reference implementation and byte-probes the engine against its Ruby path; it is the backend behind moxml's own native delegation.
 

data/lib/moxml/adapter/base.rb

@@ -580,6 +580,13 @@ namespace_validation_mode: :strict)
           false
         end
 
+        # Whether the mint pre-writes the consumer's contract ivars
+        # in C (create_primed_element), letting Document#create_element
+        # skip its Ruby prime pass. Base: never.
+        def mints_primed?
+          false
+        end
+
         # Whether add_child can keep tracking the same native —
         # adapters that may recreate the node on attach (libxml's
         # doc.root=) override to false so the wrapper refresh path
@@ -588,6 +595,15 @@ namespace_validation_mode: :strict)
           false
         end
 
+        # Whether attach_child records the wrapper-side parent link
+        # (@parent_node) on the attached node. Adapters whose natives
+        # cannot resolve a parent through the adapter layer (raw-text
+        # natives, re-mints) need the link for remove/replace to find
+        # the tree — leave it on unless the adapter proves otherwise.
+        def attach_sets_parent_link?
+          true
+        end
+
         # Whether a BARE-name attribute READ addresses only the
         # no-namespace attribute (qualified-name semantics) — the
         # gate for Element#[]'s fast path (bare_attr_value).

data/lib/moxml/adapter/leptris.rb

@@ -71,6 +71,18 @@ module Moxml
         defined?(::Leptris::XML::NativeNode) &&
         Gem::Version.new(::Leptris::VERSION) >= Gem::Version.new("1.9.162.6")
 
+      # leptris-ruby#529: the whole XPath node-set result as an Array
+      # of registered natives in ONE C crossing (Document#
+      # xpath_result_rows_bulk). The eager lane below crosses once and
+      # mints one wrapper per row on iterate-every-result. Probed on
+      # the Document binding class (the class-level respond_to? for
+      # instance surfaces) AND on the compiled ext face — a fresh
+      # native_layer over a stale ext would NoMethodError mid-query.
+      BULK_XPATH_ROWS =
+        defined?(::Leptris::XML::Native) &&
+        ::Leptris::XML::Native.respond_to?(:xpath_result_rows_bulk) &&
+        ::Leptris::XML::Document.method_defined?(:xpath_result_rows_bulk)
+
       # leptris-ruby#460: set-text by document+address, kind-dispatched
       # in C — no binding twin mint per write. Face-probed, not
       # version-gated (the floor admits bindings without it).
@@ -78,6 +90,21 @@ module Moxml
         defined?(::Leptris::XML::Native) &&
         ::Leptris::XML::Native.respond_to?(:set_binding_text)
 
+      # leptris-ruby#532 (engine ride 1.9.379.x): Native.walk_columnar —
+      # a whole subtree's walk data ([names, handles, depths]; preorder,
+      # receiver at depth 0 — document/doctype receivers walk their
+      # children at depth 0) in ONE C crossing. The children face primes
+      # a per-document {native => children} map from that single call,
+      # so a consumer walk pays one crossing per cold subtree instead of
+      # one per node (leptris-ruby#527 measured the per-node
+      # children+name crossing at ~23% of cold-walk samples). Handles
+      # mint through the document's native-cache identity, so cached
+      # entries ARE the children_read wrappers. Face-probed, not
+      # version-gated.
+      COLUMNAR_WALK =
+        defined?(::Leptris::XML::Native) &&
+        ::Leptris::XML::Native.respond_to?(:walk_columnar)
+
       # 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).
@@ -1193,14 +1220,29 @@ module Moxml
         # entry are correct; upstream bug filed). Track the state per
         # binding document and route XPath to the reference Ruby
         # engine until a child insertion rebuilds the engine index.
+        #
+        # FIXED upstream in libleptris 1.9.378 (leptris/leptris#1802):
+        # every splice path invalidates the index, so the guard is
+        # dead weight on modern engines — and it sat on the builder
+        # hot path (one Monitor-synchronized attachment set plus a
+        # document hop per add_child). Retirement is probed, not
+        # version-gated: any build that passes the #519 repro opts
+        # itself out, no moxml release needed.
         XPATH_INDEX_STALE = :xpath_index_stale
 
+        # Attachment key for the columnar children map (COLUMNAR_WALK).
+        COLUMNAR_CHILDREN = :columnar_children_map
+
         def mark_xpath_index_stale(node)
+          return if native_xpath_index_fixed?
+
           doc = xpath_index_document(node)
           attachments.set(doc, XPATH_INDEX_STALE, true) if doc
         end
 
         def clear_xpath_index_stale(node)
+          return if native_xpath_index_fixed?
+
           doc = xpath_index_document(node)
           attachments.set(doc, XPATH_INDEX_STALE, false) if doc
         end
@@ -1241,6 +1283,8 @@ module Moxml
         end
 
         def set_root(doc, element)
+          drop_columnar_children(doc)
+          drop_columnar_children(element)
           to_binding(doc).root = to_binding(element)
         end
 
@@ -1319,6 +1363,19 @@ module Moxml
           true
         end
 
+        # Identity-stable natives resolve their parent through the
+        # adapter (remove/replace fall back to that resolution when
+        # the wrapper-side link is unset), and every mutation bumps
+        # the children generation — so recording the link on attach
+        # only materializes a fourth ivar per attached node
+        # (object-shape transition, ~6% of the build row). Adapters
+        # whose natives cannot self-resolve keep the link via
+        # Base#attach_sets_parent_link?; parse_fragment mints its own
+        # lifetime chain (#245) either way.
+        def attach_sets_parent_link?
+          false
+        end
+
         # Our at_xpath falls back to the model's Ruby engine when the
         # native lane answers nothing — the engine's node-set XPath
         # index is stale after sibling insertion, so `at` must not be
@@ -1627,6 +1684,7 @@ module Moxml
         # re-indented). Raw-pointer walk over the root subtree — the
         # same batch child-pointer pattern the materializer uses.
         def strip_blank_text_nodes!(doc)
+          drop_columnar_children(doc)
           binding_ffi = ::Leptris::XML::FFI
           root = binding_ffi.leptris_document_root(doc.c_ptr)
           return unless root && !root.null?
@@ -1762,6 +1820,27 @@ module Moxml
           (owner_doc || create_document).create_element(name.to_s)
         end
 
+        # MINT_PRIMED: the compiled ext's create_element takes
+        # optional (context, adapter) and pre-writes the contract
+        # ivars in C — arity -1 vs the old 2. Self-gating: no
+        # version floor, the probe reads the loaded ext.
+        MINT_PRIMED = defined?(::Leptris::XML::NativeNode) &&
+          ::Leptris::XML::NativeNode
+            .method(:create_element).arity == -1
+
+        def mints_primed?
+          MINT_PRIMED
+        end
+
+        def create_primed_element(name, owner_doc:, context:, adapter:)
+          validate_element_name(name)
+          # One dispatch: the compiled mint IS the wrapper factory.
+          # The binding's native_create_element hop added a Ruby frame
+          # (plus a redundant to_s and nil-branch) around a C call
+          # that takes the same four arguments.
+          ::Leptris::XML::NativeNode.create_element(owner_doc, name.to_s, context, adapter)
+        end
+
         def create_native_text(content, owner_doc = nil)
           if NATIVE_MUTATIONS_COHERENT && owner_doc
             return owner_doc.native_create_text(content)
@@ -2103,6 +2182,8 @@ module Moxml
         # source. Answer the installed binding element; callers re-point
         # wrappers at it.
         def adopt_root(doc, element)
+          drop_columnar_children(doc)
+          drop_columnar_children(element)
           return nil unless NATIVE_ROOT_ADOPT
 
           binding_doc = to_binding(doc)
@@ -2141,6 +2222,18 @@ module Moxml
             # TextSegment reconstruction reads binding text nodes;
             # the wrapper's memo supplies the flag, so deriving it
             # here costs no C parent climb per call.
+            # Plain children-of-node read (no entity-marker split): the
+            # columnar map answers from the last cold-subtree crossing —
+            # one walk_columnar primes every child list under the asked
+            # node, so a top-down consumer walk pays one crossing at the
+            # root and none below it (COLUMNAR_WALK above).
+            if COLUMNAR_WALK && !entity_bearing
+              hit = columnar_children_hit(node)
+              return hit if hit
+
+              return prime_columnar_children(node)
+            end
+
             natives = if NATIVE_BULK_FIXED
                         NN_CHILDREN.bind_call(node).to_a
                       else
@@ -2195,6 +2288,80 @@ module Moxml
           end
         end
 
+        # Map hit for a primed node (see COLUMNAR_WALK). Served dup'd so
+        # no consumer can mutate the cached list in place.
+        def columnar_children_hit(node)
+          doc = doc_for(node)
+          return nil unless doc
+
+          map = attachments.get(doc, COLUMNAR_CHILDREN)
+          return nil unless map&.key?(node)
+
+          map[node].dup
+        end
+
+        # One walk_columnar crossing over node's subtree; stores a
+        # children list for every visited node and returns node's own
+        # list. Preorder + depths rebuild the parent chain on a stack;
+        # the receiver's child depth is read off the first row (the
+        # binding walks document/doctype receivers' children at depth
+        # 0). Docless detached subtrees answer the receiver's list
+        # unprimed.
+        def prime_columnar_children(node)
+          _names, handles, depths =
+            ::Leptris::XML::Native.walk_columnar(node)
+          return [] if handles.empty?
+
+          child_depth =
+            if handles[0].equal?(node)
+              depths[0] + 1
+            else
+              depths[0]
+            end
+          doc = doc_for(node)
+          map = doc ? {} : nil
+          mine = []
+          stack = []
+          handles.each_with_index do |handle, i|
+            depth = depths[i]
+            stack[depth] = handle
+            map[handle] = [] if map
+            if depth >= child_depth && map
+              parent = stack[depth - 1]
+              map[parent] << handle if map.key?(parent)
+            end
+            mine << handle if depth == child_depth
+          end
+          attachments.set(doc, COLUMNAR_CHILDREN, map) if map
+          mine
+        end
+
+        # Structural seams drop the columnar map wholesale; the next
+        # children read re-primes it (see COLUMNAR_WALK). Cheap no-op
+        # when no map is live: one lock-free attachment probe.
+        def drop_columnar_children(node)
+          return unless COLUMNAR_WALK
+
+          doc =
+            case node
+            when ::Leptris::XML::NativeNode
+              doc_for(node)
+            when ::Leptris::XML::Document
+              node
+            else
+              begin
+                node.document
+              rescue StandardError
+                nil
+              end
+            end
+          return if doc.nil?
+
+          return if attachments.get(doc, COLUMNAR_CHILDREN).nil?
+
+          attachments.delete(doc, COLUMNAR_CHILDREN)
+        end
+
         def native_keep_entity_refs?(node)
           return false unless NATIVE_READ_LAYER &&
             node.is_a?(::Leptris::XML::NativeNode)
@@ -2408,6 +2575,8 @@ module Moxml
         # callers fall back to create_element + set_attribute +
         # add_child when absent.
         def create_element_with_attrs(parent, name, attrs)
+          drop_columnar_children(parent)
+          validate_element_name(name)
           binding_parent = to_binding(parent)
           doc = binding_parent.document or return nil
           return nil unless ::Leptris::XML::Native.respond_to?(:create_element_with_attrs)
@@ -2487,7 +2656,22 @@ module Moxml
           attr.name.to_s.dup.force_encoding("UTF-8")
         end
 
+        # Self-gating by method_defined? — older exts fall through to
+        # the to_binding bridge below.
+        SET_ATTRIBUTE_NATIVE =
+          NATIVE_READ_LAYER && NN.method_defined?(:set_attribute)
+
         def set_attribute(element, name, value)
+          # Native write face (leptris-ruby#204's nn_set_attribute):
+          # gates + version bump + engine set in one C frame on the
+          # TypedData self — the builder hot path skips the to_binding
+          # bridge (FFI::Pointer + wrapper mint + registry) entirely.
+          # Cache coherence stays at the resolver: callers invalidate
+          # after this returns, exactly as for the bridge.
+          if SET_ATTRIBUTE_NATIVE && element.is_a?(::Leptris::XML::NativeNode)
+            return element.set_attribute(name.to_s, value.to_s)
+          end
+
           element = to_binding(element) if NATIVE_READ_LAYER
           element[name.to_s] = value.to_s
         end
@@ -2698,6 +2882,8 @@ module Moxml
         # on the source, so a living source can never outlive the
         # memory its reads still touch.
         def absorb_source_document(dest, owner)
+          drop_columnar_children(dest)
+          drop_columnar_children(owner)
           return nil unless NATIVE_DOC_ABSORB
           return :direct if attachments.get(dest, :absorbed_sources)&.include?(owner)
 
@@ -2743,6 +2929,8 @@ module Moxml
         end
 
         def add_child(parent, child)
+          drop_columnar_children(parent)
+          drop_columnar_children(child)
           result = add_child_impl(parent, child)
           # A successful child insertion rebuilds the engine's
           # document index; the upstream sibling-insert bug leaves it
@@ -2864,6 +3052,8 @@ module Moxml
         end
 
         def add_previous_sibling(node, new_node)
+          drop_columnar_children(node)
+          drop_columnar_children(new_node)
           result = add_previous_sibling_impl(node, new_node)
           mark_xpath_index_stale(node)
           result
@@ -2910,6 +3100,8 @@ module Moxml
         end
 
         def add_next_sibling(node, new_node)
+          drop_columnar_children(node)
+          drop_columnar_children(new_node)
           result = add_next_sibling_impl(node, new_node)
           mark_xpath_index_stale(node)
           result
@@ -2963,6 +3155,7 @@ module Moxml
         end
 
         def remove(node)
+          drop_columnar_children(node)
           node = to_binding(node) if NATIVE_READ_LAYER
           case node
           when CustomizedLeptris::Declaration
@@ -2994,6 +3187,8 @@ module Moxml
         end
 
         def replace(node, new_node)
+          drop_columnar_children(node)
+          drop_columnar_children(new_node)
           if NATIVE_READ_LAYER
             node = to_binding(node)
             new_node = to_binding(new_node)
@@ -3050,6 +3245,7 @@ module Moxml
           Gem::Version.new(::Leptris::VERSION) >= Gem::Version.new("1.9.290.0")
 
         def replace_children(node, new_children)
+          drop_columnar_children(node)
           # Cross-pool children: the binding's bulk face adopts per
           # node and fails on mixed kinds (inner_xml= with
           # text+elements died with Memory allocation failed —
@@ -3129,7 +3325,33 @@ module Moxml
           end.join
         end
 
+        # SET_TEXT_NATIVE: bindings with the unshadowed C alias
+        # (the add_child_native pattern — set_text_native aliases
+        # content= on the TypedData self) take the one-frame write:
+        # no doc_for climb, no address read, no module dispatch.
+        # Self-gating by respond_to? — older exts fall through to
+        # the set_binding_text face.
+        SET_TEXT_NATIVE = defined?(::Leptris::XML::NativeNode) &&
+          ::Leptris::XML::NativeNode.method_defined?(:set_text_native)
+
         def set_text_content(node, content)
+          drop_columnar_children(node)
+          if SET_TEXT_NATIVE && node.is_a?(::Leptris::XML::NativeNode)
+            begin
+              node.set_text_native(content.to_s)
+              return
+            rescue ::Leptris::XML::Error => e
+              # Same #401 contract as the fallback below: a detached
+              # (parentless) node re-raises as the named Moxml::Error.
+              raise if node.parent
+
+              raise Moxml::Error,
+                    "cannot set text content on a detached " \
+                    "(parentless) node — attach it to a document " \
+                    "first (issue #401): #{e.message}"
+            end
+          end
+
           # Native-layer fast path (leptris-ruby#460): the C setter
           # takes document+address directly — no binding twin mint
           # per write. The Identity wrapper's own content= would
@@ -3411,6 +3633,22 @@ module Moxml
             )
           end
 
+          # leptris-ruby#529 bulk face: the whole nodeset as an Array
+          # of registered natives in ONE crossing — the eager lane
+          # below crosses once per row (the scoreboard's iterate-
+          # every-result row). Real rows mint through the registered
+          # klasses with native-cache identity; attr/sequence rows
+          # arrive as the ResultAttr/ResultText wrappers the eager
+          # mint produces, so NodeSet's per-row wrap sees one shape
+          # and the result contract is unchanged. The face CONSUMES
+          # the pointer for nodesets; a non-nodeset result answers
+          # nil and leaves the pointer — fall through to the scalar
+          # wrap, whose free owns it.
+          if BULK_XPATH_ROWS
+            rows = document.xpath_result_rows_bulk(result_ptr)
+            return rows unless rows.nil?
+          end
+
           # The binding's #to_a mints one Ruby wrapper per result
           # node; hand the native set through so .size/.first stay
           # native-side (LazyNodeSet holds it unmaterialized).

data/lib/moxml/attribute_resolver.rb

@@ -109,6 +109,10 @@ module Moxml
       # over-invalidate (global bump instead of local) — a no-op
       # for correctness.
       if name.start_with?("xmlns")
+        # Introducing (or rewriting) a namespace declaration: mark the
+        # context BEFORE the invalidation, so this write's generation
+        # bump fans out to every wrapper's memoized scope reads.
+        element.context.mark_namespaces_active!
         adapter.set_attribute(element.native, name, value)
         element.invalidate_attribute_cache!
         return value

data/lib/moxml/context.rb

@@ -90,7 +90,10 @@ module Moxml
     end
 
     def bump_children_generation
-      @children_generation = children_generation + 1
+      # One dispatch, not two: children_generation re-dispatched just
+      # to default nil. Shared counter — node wrappers' children memos
+      # key on it.
+      @children_generation = @children_generation.to_i + 1
     end
 
     def namespace_scope_generation
@@ -101,6 +104,22 @@ module Moxml
       @namespace_scope_generation += 1
     end
 
+    # Namespace scopes only need the per-mutation generation bump
+    # while namespaces can exist. A builder-only document (no parse,
+    # no xmlns write) never has one, and the bump sat on the attach
+    # hot path (deletion experiment: build row 2.128x -> 1.923x).
+    # Every namespace introduction route marks the context active
+    # first — parse faces and the xmlns attribute-write face — so
+    # the sticky flag never misses an introduction.
+    def namespace_scopes_active?
+      @namespace_scopes_active = false if @namespace_scopes_active.nil?
+      @namespace_scopes_active
+    end
+
+    def mark_namespaces_active!
+      @namespace_scopes_active = true
+    end
+
     def entity_registry
       @entity_registry ||= build_entity_registry
     end
@@ -128,6 +147,7 @@ module Moxml
       # Parse with adapter, passing self (context) so adapter can use our config
       parsed_options = default_options.merge(options)
       doc = config.adapter.parse(xml_string, parsed_options, self)
+      mark_namespaces_active!
 
       # Set declaration flag on Document wrapper (proper OOP)
       doc.has_xml_declaration = has_declaration if doc.is_a?(Document)
@@ -233,7 +253,9 @@ module Moxml
     # are the result either way.
     def parse_fragment(xml)
       adapter = config.adapter
-      adapter.parse_fragment(xml, self).map do |node|
+      nodes = adapter.parse_fragment(xml, self)
+      mark_namespaces_active!
+      nodes.map do |node|
         # Adapters that tie a parent_node lifetime chain (#245)
         # return wrapped nodes — pass them through untouched;
         # re-wrapping would race the weak wrapper map.
@@ -242,6 +264,7 @@ module Moxml
     end
 
     def iterparse(xml, mode: :top_level, &block)
+      mark_namespaces_active!
       config.adapter.iterparse(xml, mode, self, &block)
     end
 

data/lib/moxml/document.rb

@@ -163,12 +163,26 @@ module Moxml
     end
 
     def create_element(name)
-      native = adapter.create_element(name, owner_doc: @native)
+      # The mint path dereferenced `adapter` three times and re-probed
+      # `mints_primed?` twice per element; the probe reads a class
+      # constant, so its verdict is fixed for the context's lifetime —
+      # deref once into a local and memoize the probe (the accessor's
+      # context hop ran on every mint otherwise).
+      a = @adapter || (@adapter = context.config.adapter)
+      primed = @mints_primed
+      primed = (@mints_primed = a.mints_primed?) if primed.nil?
+      native = if primed
+                 a.create_primed_element(name, owner_doc: @native,
+                                               context: context, adapter: a)
+               else
+                 a.create_element(name, owner_doc: @native)
+               end
       # leptris-ruby#508 mints registered klasses at create: the node
       # IS a contract-carrying identity (@native is self) — prime it
       # in place instead of shelling a second wrapper (a raw mint
       # reaching ==/adapter dies on the nil @context).
-      return native.prime_contract(native, context, adapter) if native.is_a?(Moxml::Node)
+      return native if primed && native.is_a?(Moxml::Node)
+      return native.prime_contract(native, context, a) if native.is_a?(Moxml::Node)
 
       Wrappers::Element.new(native, context)
     end

data/lib/moxml/element.rb

@@ -276,6 +276,7 @@ module Moxml
     def add_namespace(prefix, uri)
       adapter.create_namespace(@native, prefix, uri,
                                namespace_validation_mode: context.config.namespace_validation_mode)
+      context.mark_namespaces_active!
       invalidate_namespace_cache!
       self
     rescue ValidationError => e
@@ -530,8 +531,19 @@ module Moxml
 
     # Clear the namespace caches and bump the context's scope
     # generation so every wrapper — including ones not reachable from
-    # any children cache — recomputes on next read.
+    # any children cache — recomputes on next read. While namespaces
+    # cannot exist (context.namespace_scopes_active? is false) the
+    # memos can only hold namespace-free reads, so skipping the whole
+    # body is exact — and the nil-assignment form would MATERIALIZE
+    # three unset ivars per attached node, which is the cost this
+    # gate exists to remove. Every introduction route — parse faces
+    # and the xmlns write face — marks the context BEFORE its own
+    # invalidation, so the introducing mutation still clears and
+    # bumps; in-scope reads are generation-keyed, so other wrappers
+    # recompute on the bump.
     def invalidate_namespace_cache!
+      return unless context.namespace_scopes_active?
+
       @namespaces = nil
       @namespace_definitions = nil
       @in_scope_namespaces = nil

data/lib/moxml/node.rb

@@ -30,9 +30,11 @@ module Moxml
     def prime_contract(native, context, adapter = nil, node_type = nil)
       @context = context
       @native = native
-      @parent_node = nil
-      @adapter = adapter
-      @node_type_cached = node_type
+      # @parent_node and @node_type_cached stay UNSET when empty —
+      # every reader is nil-tolerant, and a nil write materializes the
+      # ivar (object-shape transition) on every created node.
+      @adapter = adapter unless adapter.nil?
+      @node_type_cached = node_type unless node_type.nil?
       self
     end
 
@@ -213,15 +215,42 @@ module Moxml
 
     def attach_child(node)
       context.bump_children_generation
-      node = prepare_node(node)
-      adapter.add_child(@native, node.native)
+      # Inlined prepare_node: the per-attach dispatch frame measured
+      # ~4.4% on the builder hot path (deletion experiment). Same
+      # contract — String operands mint literal text nodes, foreign
+      # types raise.
+      node = case node
+             when Node then node
+             when String then Moxml::Node.wrap(adapter.create_text(node), context)
+             else
+               raise Moxml::DocumentStructureError.new(
+                 "Invalid node type: #{node.class}. Expected String or Moxml::Node",
+                 operation: "attach_child",
+                 state: "node_type: #{node.class}",
+               )
+             end
+      oc = node.context
+      if !oc.nil? && !oc.equal?(context) &&
+          oc.namespace_scopes_active?
+        context.mark_namespaces_active!
+      end
+      a = adapter
+      a.add_child(@native, node.native)
       # Refresh native in case adapter changed identity (e.g., LibXML
       # doc.root=); stable-identity adapters skip the round trip.
-      unless adapter.native_identity_stable?
+      unless a.native_identity_stable?
         refreshed = adapter.actual_native(node.native, @native)
         node.refresh_native!(refreshed) if refreshed && refreshed != node.native
       end
-      node.parent_node = self
+      # The wrapper-side parent link rides the adapter's capability
+      # gate: adapters whose natives cannot resolve a parent through
+      # the adapter layer need it for remove/replace to find the tree
+      # (ox's raw-text natives, for one); identity-stable adapters
+      # skip the write, which otherwise materializes a fourth ivar on
+      # every attached node (object-shape transition per attach).
+      # Wrappers that need the link anyway get it where they are
+      # minted with one — NodeSet#each re-points them.
+      node.parent_node = self if a.attach_sets_parent_link?
       # The adopted subtree's in-scope namespaces changed
       node.invalidate_namespace_cache!
       invalidate_children_cache!
@@ -231,6 +260,7 @@ module Moxml
     def attach_previous_sibling(node)
       context.bump_children_generation
       node = prepare_node(node)
+      absorb_namespace_activity(node)
       inserted = adapter.add_previous_sibling(@native, node.native)
       refresh_inserted_native(node, inserted)
       # Invalidate the parent's memoized children list. The wrapper-side
@@ -245,6 +275,7 @@ module Moxml
     def attach_next_sibling_to(anchor, node)
       context.bump_children_generation
       node = prepare_node(node)
+      absorb_namespace_activity(node)
       inserted = adapter.add_next_sibling(anchor.native, node.native)
       refresh_inserted_native(node, inserted)
       anchor.parent&.invalidate_children_cache!
@@ -252,6 +283,16 @@ module Moxml
       self
     end
 
+    # A node adopted from ANOTHER context can carry namespaces this
+    # context's own faces (parse, xmlns writes) never saw; import the
+    # source context's activity flag so the gated scope-generation
+    # bump stays armed here too.
+    def absorb_namespace_activity(node)
+      oc = node.context
+      return if oc.nil? || oc.equal?(context)
+      context.mark_namespaces_active! if oc.namespace_scopes_active?
+    end
+
     def refresh_inserted_native(node, inserted)
       return unless adapter.add_sibling_returns_inserted?
       return if inserted.nil? || inserted.equal?(node.native)
@@ -773,7 +814,10 @@ module Moxml
     protected
 
     def invalidate_children_cache!
-      @children = nil
+      # Only nil an EXISTING memo: nil-assignment materializes an
+      # unset ivar (object-shape transition), and the builder hot
+      # path invalidates parents whose children memo was never read.
+      @children = nil unless @children.nil?
     end
 
     # Invalidate parent's cached children when this node

data/lib/moxml/version.rb

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

data/spec/moxml/adapter/leptris_children_columnar_spec.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+begin
+  require "leptris"
+rescue LoadError
+  # Leptris gem not available - skip all specs in this file
+  return
+end
+return unless Leptris::XML::Document.respond_to?(:create)
+# The columnar children lane rides the binding's walk_columnar face
+# (leptris-ruby#527/#532); older bindings keep the per-node children
+# crossing, so the routing cannot be pinned there.
+return unless defined?(Leptris::XML::Native) &&
+  Leptris::XML::Native.respond_to?(:walk_columnar)
+
+require "moxml/adapter/leptris"
+
+RSpec.describe "Moxml::Adapter::Leptris columnar children (SOTA B2 walk row)" do
+  around do |example|
+    Moxml.with_config(:leptris, true, "UTF-8") do
+      example.run
+    end
+  end
+
+  let(:xml) do
+    <<~XML
+      <?xml version="1.0"?><r><a x="1">t</a><b/><c><d/></c><tail>z</tail></r>
+    XML
+  end
+
+  let(:doc) { Moxml.parse(xml) }
+  let(:root) { doc.root }
+  let(:root_native) { root.native }
+
+  # Counts real Native.walk_columnar C crossings inside the block —
+  # no stubs, the actual boundary traffic the walk row pays.
+  def with_crossing_count
+    calls = 0
+    tp = TracePoint.new(:c_call) do |t|
+      calls += 1 if t.method_id == :walk_columnar
+    end
+    result = nil
+    tp.enable { result = yield }
+    [calls, result]
+  end
+
+  describe "the columnar gate" do
+    it "face-probes walk_columnar on the binding" do
+      expect(Moxml::Adapter::Leptris::COLUMNAR_WALK).to be(true)
+      expect(Leptris::XML::Native.respond_to?(:walk_columnar)).to be(true)
+    end
+  end
+
+  describe "plain children reads" do
+    it "answer natives identical to the native children face" do
+      got = Moxml::Adapter::Leptris.children(root_native)
+      expected = Leptris::XML::NativeNode
+        .instance_method(:children).bind_call(root_native).to_a
+      expect(got.size).to eq(expected.size)
+      expect(got.map { |n| Moxml::Adapter::Leptris.node_name(n) })
+        .to eq(expected.map(&:name))
+      got.each_with_index do |native, i|
+        # native-cache identity: cached handles ARE the children_read
+        # wrappers, so the NodeSet contract holds.
+        expect(native).to equal(expected[i])
+      end
+    end
+
+    # Parsed-document wrappers mint with Identity::ChildReads above
+    # Moxml::Node, so consumer iteration on those wrappers dispatches
+    # to the binding's C read layer. The children FACE is pinned by
+    # driving it for every node of the cold subtree: one walk_columnar
+    # crossing primes the whole map, every deeper face read hits it.
+    it "pay ONE columnar crossing for a whole cold subtree" do
+      calls, = with_crossing_count do
+        walk_face = lambda do |native|
+          Moxml::Adapter::Leptris.children(native).each do |child|
+            walk_face.call(child)
+          end
+        end
+        walk_face.call(root_native)
+      end
+      expect(calls).to eq(1)
+    end
+
+    it "serve repeat face reads from the primed map without a crossing" do
+      calls, first = with_crossing_count do
+        Moxml::Adapter::Leptris.children(root_native)
+      end
+      expect(calls).to eq(1)
+      first_names = first.map { |n| Moxml::Adapter::Leptris.node_name(n) }
+      calls2, second = with_crossing_count do
+        Moxml::Adapter::Leptris.children(root_native)
+      end
+      expect(calls2).to eq(0)
+      expect(second.map { |n| Moxml::Adapter::Leptris.node_name(n) })
+        .to eq(first_names)
+    end
+  end
+
+  describe "mutation invalidation" do
+    # Read back through the adapter face: the map must never serve a
+    # list a mutation has invalidated.
+    def face_children_names
+      Moxml::Adapter::Leptris.children(root_native)
+        .map { |n| Moxml::Adapter::Leptris.node_name(n) }
+    end
+
+    it "sees children added after the map was primed" do
+      face_children_names # prime the map
+      root.add_child(doc.create_element("late"))
+      expect(face_children_names).to include("late")
+    end
+
+    it "sees children removed after the map was primed" do
+      face_children_names # prime the map
+      root.children.to_a.first.remove
+      expect(face_children_names).not_to include("a")
+    end
+
+    it "sees sibling insertions after the map was primed" do
+      face_children_names # prime the map
+      anchor = root.children.to_a.first
+      anchor.add_previous_sibling(doc.create_element("before2"))
+      expect(face_children_names).to include("before2")
+    end
+
+    it "sees replace after the map was primed" do
+      face_children_names # prime the map
+      victim = root.children.to_a.find { |n| n.name == "b" }
+      victim.replace(doc.create_element("swapped"))
+      expect(face_children_names).to include("swapped")
+      expect(face_children_names).not_to include("b")
+    end
+
+    it "sees content rewrites after the map was primed" do
+      face_children_names # prime the map
+      target = root.children.to_a.find { |n| n.name == "a" }
+      target.content = "rewritten"
+      names = face_children_names
+      expect(names).to include("a")
+      expect(root.children.to_a.find { |n| n.name == "a" }.text)
+        .to eq("rewritten")
+    end
+  end
+end

data/spec/moxml/adapter/leptris_spec.rb

@@ -865,5 +865,95 @@ RSpec.describe Moxml::Adapter::Leptris do
       expect(native).not_to be_nil
       expect(native.to_a.map { |n| n.name.to_s }).to eq(%w[a c b])
     end
+
+    it "never arms the guard on engines that invalidate on splice" do
+      skip "requires an engine whose node-set index survives sibling insertion (leptris-ruby#519)" unless described_class.native_xpath_index_fixed?
+
+      doc = ctx.parse("<root><anchor/></root>")
+      doc.xpath("//ext") # prime the engine index
+      doc.root.add_child(doc.create_element("ext"))
+      expect(doc.xpath("//ext").size).to eq(1)
+
+      expect(
+        described_class.attachments.get(
+          described_class.xpath_index_document(doc.root.native),
+          described_class.singleton_class.const_get(:XPATH_INDEX_STALE),
+        ),
+      ).to be_nil
+    end
+  end
+
+  describe "namespace scope-generation gate" do
+    let(:ctx) { Moxml.new(:leptris) }
+
+    # The per-attach scope-generation bump only matters once
+    # namespaces exist; the builder hot path must not pay it.
+    it "does not bump the scope generation while namespaces are absent" do
+      doc = ctx.create_document
+      root = doc.create_element("r")
+      doc.root = root
+      gen = ctx.namespace_scope_generation
+      root.add_child(doc.create_element("a"))
+      root.add_child(doc.create_element("b"))
+      expect(ctx.namespace_scope_generation).to eq(gen)
+      expect(ctx.namespace_scopes_active?).to be(false)
+    end
+
+    it "arms the gate when a write introduces a namespace" do
+      doc = ctx.create_document
+      root = doc.create_element("r")
+      doc.root = root
+      root["xmlns:foo"] = "urn:x"
+      expect(ctx.namespace_scopes_active?).to be(true)
+      expect(root.namespaces.map { |n| [n.prefix, n.uri] })
+        .to include(%w[foo urn:x])
+    end
+
+    it "is armed by parsed documents" do
+      doc = ctx.parse("<r xmlns:foo='urn:x'><foo:a/></r>")
+      expect(ctx.namespace_scopes_active?).to be(true)
+      expect(doc.xpath("//foo:a", "foo" => "urn:x").size).to eq(1)
+    end
+
+    it "imports the flag from a foreign context on adoption" do
+      donor_ctx = Moxml.new(:leptris)
+      donor = donor_ctx.parse("<x xmlns:foo='urn:x'/>")
+      doc = ctx.create_document
+      root = doc.create_element("r")
+      doc.root = root
+      expect(ctx.namespace_scopes_active?).to be(false)
+      root.add_child(donor.root)
+      expect(ctx.namespace_scopes_active?).to be(true)
+      expect(root.children.first.namespaces.map(&:uri))
+        .to include("urn:x")
+    end
+  end
+
+  # The README error-handling contract: an invalid element name must
+  # raise Moxml::ValidationError at CREATE time. The adapter's native
+  # fast paths (create_primed_element, create_element_with_attrs) mint
+  # from a name without passing through Base#create_element, where
+  # validate_element_name lives — the failure then surfaced late, at
+  # add_child, as Moxml::Error "Document already has a root element".
+  describe "element name validation on the create seam" do
+    let(:ctx) { Moxml.new(:leptris) }
+
+    it "raises ValidationError when create_element mints an invalid name" do
+      doc = ctx.parse("<root/>")
+      expect { doc.create_element("wrong,name") }
+        .to raise_error(Moxml::ValidationError, /Invalid XML element name/)
+    end
+
+    it "raises ValidationError when add_element mints an invalid name" do
+      doc = ctx.create_document
+      expect { doc.add_element("bad,name", id: "1") }
+        .to raise_error(Moxml::ValidationError, /Invalid XML element name/)
+    end
+
+    it "still mints valid names with punctuation allowed in XML Names" do
+      doc = ctx.parse("<root/>")
+      element = doc.create_element("ns:my-element.v2")
+      expect(element).to be_a(Moxml::Element)
+    end
   end
 end

data/spec/moxml/adapter/leptris_xpath_bulk_rows_spec.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+begin
+  require "leptris"
+rescue LoadError
+  # Leptris gem not available - skip all specs in this file
+  return
+end
+
+require "moxml/adapter/leptris"
+
+# leptris-ruby#529: the multi-result native XPath lane routes through
+# Document#xpath_result_rows_bulk when the binding answers it — the
+# whole node-set in ONE C crossing instead of one crossing per row.
+# The rows keep the eager lane's contract (registered wrapper
+# klasses, ResultAttr/ResultText synthetic rows, scalar pass-through
+# on non-node-set results), so every consumer-visible shape is
+# unchanged; what pins here is the routing gate and those shapes.
+RSpec.describe "leptris xpath bulk rows routing" do
+  let(:ctx) { Moxml.new(:leptris) }
+  let(:doc) do
+    ctx.parse(<<~XML)
+      <root>
+        <item id="1">alpha</item>
+        <item id="2">beta</item>
+        <!-- note -->
+      </root>
+    XML
+  end
+
+  it "arms the gate on the current binding" do
+    expect(Leptris::XML::Native.respond_to?(:xpath_result_rows_bulk)).to be(true)
+    expect(Leptris::XML::Document.method_defined?(:xpath_result_rows_bulk)).to be(true)
+    expect(Moxml::Adapter::Leptris::BULK_XPATH_ROWS).to be(true)
+  end
+
+  it "answers multi-result queries with wrapped natives in order" do
+    set = doc.xpath("//item")
+    expect(set).to be_a(Moxml::NodeSet)
+    expect(set.size).to eq(2)
+    expect(set.map(&:name)).to eq(%w[item item])
+    expect(set.map(&:text)).to eq(%w[alpha beta])
+    expect(set.first).to be_a(Moxml::Element)
+  end
+
+  it "keeps attribute rows as Attribute wrappers" do
+    attrs = doc.xpath("//item/@id")
+    expect(attrs.map(&:name)).to eq(%w[id id])
+    expect(attrs.map(&:value)).to eq(%w[1 2])
+    expect(attrs.first).to be_a(Moxml::Attribute)
+  end
+
+  it "keeps mixed element and comment rows in document order" do
+    set = doc.xpath("/root/node()").grep_v(Moxml::Text)
+    expect(set.map { |n| n.is_a?(Moxml::Comment) ? :comment : n.name.to_sym })
+      .to eq(%i[item item comment])
+  end
+
+  it "passes scalars through unwrapped" do
+    expect(doc.xpath("count(//item)")).to eq(2.0)
+    expect(doc.xpath("string(//item)")).to eq("alpha")
+    expect(doc.xpath("//item[@id='9']")).to be_a(Moxml::NodeSet)
+    expect(doc.xpath("//item[@id='9']").empty?).to be(true)
+  end
+
+  it "resolves one address to one Ruby object across queries" do
+    first = doc.xpath("//item").first
+    again = doc.xpath("//item").first
+    expect(again).to be(first)
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: moxml
 version: !ruby/object:Gem::Version
-  version: 0.5.150
+  version: 0.5.152
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-10-21 00:00:00.000000000 Z
+date: 2026-10-22 00:00:00.000000000 Z
 dependencies: []
 description: |
   Moxml is a unified XML manipulation library that provides a common API
@@ -481,6 +481,7 @@ files:
 - spec/moxml/adapter/leptris_append_gc_spec.rb
 - spec/moxml/adapter/leptris_attribute_snapshot_spec.rb
 - spec/moxml/adapter/leptris_binding_cap_spec.rb
+- spec/moxml/adapter/leptris_children_columnar_spec.rb
 - spec/moxml/adapter/leptris_contract_reads_spec.rb
 - spec/moxml/adapter/leptris_detached_text_spec.rb
 - spec/moxml/adapter/leptris_doc_parts_spec.rb
@@ -493,6 +494,7 @@ files:
 - spec/moxml/adapter/leptris_sax_records_spec.rb
 - spec/moxml/adapter/leptris_spec.rb
 - spec/moxml/adapter/leptris_strict_mismatch_spec.rb
+- spec/moxml/adapter/leptris_xpath_bulk_rows_spec.rb
 - spec/moxml/adapter/leptris_xpath_identity_spec.rb
 - spec/moxml/adapter/libxml_internals_spec.rb
 - spec/moxml/adapter/libxml_spec.rb