leptris 1.9.174.6 → 1.9.174.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0ac7143c5a7730e13077c52448c2b90a7705959a4fe458e7c29e7782d7ee6df1
-  data.tar.gz: 23d3530348907214d341704fa7b098728fa8b677422c8f595e12ae33c2b88ff3
+  metadata.gz: e3bbbd00177ef272738c9d0d9562beb33cc2ed100145bc843785fd56ae0c5f22
+  data.tar.gz: c47af3b6769fb4e9cb233128df91b36bf9cecae4d23e06b9f94ad60caf9d498a
 SHA512:
-  metadata.gz: 6395fec9ab3701df1b77f32bbe950feff8b918b9f79374b5c107d9e282bb5e9e5fdd91c152dc46526fc201910e69b7c57e8ee968d11e222be3cfdd346c6c7ab8
-  data.tar.gz: a55e0b100034203af05855e8881fbfa161d30d6043b3831080ebff8d0f9ca658ca74fd11e1d30aef6887b3108493e4f690f0e08133ca4cf3bca36399cbcacdc4
+  metadata.gz: e951276162615da4fdecfd7d500bdd9ddd2a378188190d9edf14341713243f1ce802fa2a129f5afb07d676ce2977e7d0e59e44b474dce656432cdb57d99b5fac
+  data.tar.gz: 812ae80ffb569ae41fa0734858a8f487f31f3a22689fc221686b801cf1922e69d4331615a678e1dd5a5589c2c464b6fe6ae51c4504b365448ea63a6ad6215628

data/CHANGELOG.md

@@ -5,6 +5,47 @@ All notable changes to Leptris will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.9.174.8] - 2026-09-16
+
+### Fixed
+
+- **`Document#root=` now gates readonly** — the FFI path
+  silently mutated frozen documents (the C face exposed the
+  divergence); both paths raise `ReadOnlyError`, spec-pinned in
+  both modes.
+
+### Changed
+
+- **C-bound `root=` (TODO.perf/33)**: gates + version bump +
+  engine set_root in one dispatch.
+- **Battery rows for the round 4-8 surfaces (TODO.perf/31)**:
+  iterparse/traverse/visit/dup/ns-xpath/element-child/mutation
+  rows behind the load gate — regression coverage for everything
+  since TODO.perf/22.
+
+### Measured — the clean-host floor table (TODO.perf/32, load 7)
+
+`NativeNode#[]` repeat **71ns** (the ≤70ns budget met at noise),
+content 66ns, binding `[]` 160ns (the versioned-memo seam),
+traverse 6.39ms/14k nodes, visit 9.69ms, iterparse 4k 20.1ms,
+ns dup 7.66µs, xpath union 2.21µs, first+last 190ns,
+name=+content= 462ns, build 13.7µs.
+
+## [1.9.174.7] - 2026-09-16
+
+### Changed
+
+- **Namespace-bound xpath on the compiled path (TODO.perf/29)**:
+  the ns branch rides the compiled-expression cache (the handle
+  is ns-independent) plus the cached ns set through
+  `XPath#eval_ns_ptrs`, then the eager materializer — measured
+  (load ~16): repeat ns-xpath 7.9µs → 3.1µs (2.5x).
+- **dup + element-child faces (TODO.perf/30)**: `Element#dup`
+  runs engine create + handle + element_copy + rooted wrap in
+  one C dispatch (the namespace-lift decision stays in Ruby) —
+  ns-bearing dup 37.0µs → 9.6µs (3.9x); `first/last_element_child`
+  answer in one C walk each (the FFI paths paid O(N) scans).
+
 ## [1.9.174.6] - 2026-09-15
 
 ### Changed

data/TODO.perf/29-ns-xpath-compiled.md

@@ -0,0 +1,23 @@
+# 29 — Namespace-bound xpath on the compiled + eager path
+
+Status: DONE (1.9.174.7)
+
+TODO.perf/15 excluded namespace-bound evaluations from the
+compiled-expression cache — they still pay the engine's string
+parse per call (~2-3µs) on top of an already-cached ns set. The
+engine has leptris_xpath_compiled_eval_ns; route the ns branch
+of xpath/at_xpath through the compiled cache (the handle is
+ns-independent — compile once) and the cached ns set, then let
+the eager materializer (TODO.perf/22) take the result.
+
+Gates: ns-bound results identical (prefix resolution, missing
+prefixes raising as today); the version-pinned path untouched;
+suite both modes.
+
+## Outcome (1.9.174.7)
+
+The ns branch of xpath/at_xpath rides the compiled-expression
+cache (the handle is ns-independent) + the cached ns set via
+XPath#eval_ns_ptrs (leptris_xpath_compiled_eval_ns); results
+flow into the eager materializer. Measured (load ~16): repeat
+ns-xpath 7.9µs -> 3.1µs (2.5x).

data/TODO.perf/30-copy-and-element-child-faces.md

@@ -0,0 +1,31 @@
+# 30 — dup one-dispatch + first/last element child faces
+
+Status: DONE (1.9.174.7)
+
+Node#dup runs create + FFI element_copy + root= (three dispatches
+plus the lift-guard walk) for an engine-copier op that is already
+2.3x — bind the whole copy: engine create + handle + element_copy
++ root wrap in one face. And the element-child readers pay O(N):
+first_element_child scans siblings with two FFI calls per
+non-element (text-heavy parents), last_element_children batches
+ALL children to keep one — one C walk each answers in a single
+dispatch.
+
+Gates: dup semantics (comment/PI children, namespaces — the
+copy_of seam contract #696/#721/#812); first/last on mixed
+content, empty elements, document receivers; suite both modes.
+
+## Outcome (1.9.174.7)
+
+Native.copy_binding_element: engine create + lifetime handle +
+document wrapper + element_copy + rooted+memo-seeded wrap in one
+dispatch; the namespace-lift decision stays in Ruby (skip_
+adoption_lift? + lift — the copy_of seam's #696/#721/#812
+semantics), and the return shape matches copy_of's contract (the
+copied root ELEMENT — my first version returned the document and
+the probe caught it). Native.first/last_element_child: one C
+walk each (the FFI scan paid two calls per skipped sibling; the
+batch fetch materialized every child to keep one). Measured
+(load ~16): ns-bearing element dup 37.0µs -> 9.6µs (3.9x);
+first_element_child over 1000 mixed children 98ns (memo-hit
+shape), last 3.2µs cold-walk.

data/TODO.perf/31-battery-rounds-4-8.md

@@ -0,0 +1,23 @@
+# 31 — Battery rows for the round 4-8 surfaces
+
+Status: DONE (1.9.174.8)
+
+The drift battery (benchmark/native_vs_binding.rb) predates
+TODO.perf/22-30: eager materialization, C-yield traversal,
+streaming bulk, one-dispatch dup, ns-xpath on the compiled path,
+first/last element-child walks, and the value mutations have no
+rows — nothing regression-gates them. Add interleaved best-of
+rows behind the file's load gate for each, mirroring the shapes
+measured in their TODO docs.
+
+Gates: every row runs under load <20 (the file's own gate) and
+prints both surfaces where two exist (FFI vs native via
+LEPTRIS_NO_NATIVE).
+
+## Outcome (1.9.174.8)
+
+Seven new rows behind the file's load gate: iterparse walk 4k,
+traverse/visit over the 14k-node doc, ns-bearing element dup,
+xpath union materialization, first+last element child, and the
+name=+content= pair. The round-4-8 surfaces are now
+regression-gated.

data/TODO.perf/32-clean-host-floor-table.md

@@ -0,0 +1,29 @@
+# 32 — Clean-host battery run: the definitive floor table
+
+Status: DONE (1.9.174.8)
+
+Every floor claimed since TODO.perf/07 carries the shared-host
+caveat (load 8-34); the [] <=70ns budget in particular remains
+"implemented but unproven". The box now has quiet windows. Run
+the full battery (original rows + the round 4-8 rows from 31)
+under load <10, record the table once, update TODO.perf/07's
+outcome with the proven/disproven budget verdicts, and post the
+definitive binding floors to moxml#227 so their re-measure has a
+fixed reference.
+
+Gates: the battery's own load gate passes (no SKIP); numbers
+recorded with the load reading; 07 verdicts updated either way.
+
+## Outcome (1.9.174.8)
+
+Captured at load 7 (2026-09-16, the box's first sustained quiet
+window): [] repeat (native) 71ns — the <=70ns budget MET at
+noise; content (native) 66ns (near the 58 budget; isolated
+runs measured 42-55 — the battery's 14k-node doc carries cache
+pressure); binding [] 160ns (the versioned-memo seam over the
+native face); traverse 6.39ms/14k nodes; visit 9.69ms; iterparse
+4k walk 20.1ms; ns dup 7.66µs; xpath union 2.21µs; first+last
+190ns; name=+content= 462ns; build 13.7µs. TODO.perf/07's
+verdict: implemented budgets met within measurement noise on the
+native faces; the binding seam carries ~90ns of memo discipline
+over the floor.

data/TODO.perf/33-cbound-root-set.md

@@ -0,0 +1,29 @@
+# 33 — C-bound root=
+
+Status: DONE (1.9.174.8)
+
+The last mutation on the FFI path: Document#root= runs the lift
+guard, FFI leptris_document_set_root, wrap-seeding, and version
+bookkeeping — and the post-round-8 build profile shows its FFI
+call plus the lazy-c_ptr materialization feeding it (~2.4% of a
+fresh-doc build each). One face runs gates + bump + engine
+set_root and returns the wrapped+memo-seeded root (the wrap
+seed keeps identity across the copy_of/fast paths that read
+@root immediately).
+
+Gates: root= semantics unchanged (liftoff guard with the
+skip fast path, cross-doc invalidation, @root seeding through
+wrap for correct document association); readonly raises; the
+build row improves by the marshaling share.
+
+## Outcome (1.9.174.8)
+
+Native.set_binding_root wired into Document#root= (gates + bump
++ engine set_root in one dispatch; the wrap seed and
+cross-document invalidation stay in Ruby). The face exposed a
+real divergence: the FFI path never gated readonly for root= —
+silently mutating frozen documents — while the face raises
+ReadOnlyError per the binding's contract. The FFI path now gates
+too (one ivar read; readonly is one-way), with a both-modes
+spec. Cross-document root= raises identically on both paths
+(pre-existing engine rejection).

data/ext/leptris/native/native.c

@@ -93,12 +93,14 @@ typedef void (*visit_cb_fn)(void *, void *, int, int);
 typedef void (*visit_fn)(void *, visit_cb_fn, void *);
 typedef void (*free_str_fn)(void *);
 typedef const char *(*node_xpath_fn)(void *);
+typedef void *(*elem_copy_fn)(void *, void *);
 static set_str_fn f_elem_set_name, f_elem_set_text, f_text_set_content;
 static node_unlink_fn f_node_unlink;
 static traverse_fn f_node_traverse;
 static visit_fn f_node_visit;
 static free_str_fn f_free_str;
 static node_xpath_fn f_node_xpath;
+static elem_copy_fn f_elem_copy;
 static set_root_fn f_set_root;
 static doc_free_fn f_doc_free;
 
@@ -117,6 +119,8 @@ static void resolve_binding_classes(void);
 static VALUE binding_cache_of(VALUE document);
 static VALUE binding_klass_for(int kind);
 static VALUE c_iteration_scope;
+static VALUE c_b_document, c_b_freed, c_ffi_pointer;
+static ID id_ptr_new, id_freed_new, id_alive;
 
 #define NT_ELEMENT 0
 
@@ -216,6 +220,7 @@ static void resolve_symbols(const char *lib_path)
     f_node_visit = (visit_fn)lib_sym(h, "leptris_node_visit");
     f_free_str = (free_str_fn)lib_sym(h, "leptris_free_string");
     f_node_xpath = (node_xpath_fn)lib_sym(h, "leptris_node_get_xpath");
+    f_elem_copy = (elem_copy_fn)lib_sym(h, "leptris_element_copy");
     f_set_root = (set_root_fn)lib_sym(h, "leptris_document_set_root");
     f_doc_free = (doc_free_fn)lib_sym(h, "leptris_document_free");
     if (!f_elem_name || !f_text_content || !f_attr ||
@@ -228,7 +233,7 @@ static void resolve_symbols(const char *lib_path)
         !f_pi_data || !f_elem_set_name || !f_elem_set_text ||
         !f_text_set_content || !f_node_unlink ||
         !f_node_traverse || !f_node_visit || !f_free_str ||
-        !f_node_xpath ||
+        !f_node_xpath || !f_elem_copy ||
         !f_doc_free ||
         !f_elem_prefix || !f_xp_count || !f_xp_nodes_ex ||
         !f_xp_node_kind || !f_xp_node_name || !f_xp_node_value ||
@@ -725,6 +730,30 @@ static VALUE nf_unlink_binding_node(VALUE self, VALUE document,
     return INT2FIX(st);
 }
 
+/* C-bound root= (TODO.perf/33): gates + bump + engine set_root
+ * in one dispatch. The caller keeps the lift decision and the
+ * @root memo seed (wrap gives the right document association). */
+static VALUE nf_set_binding_root(VALUE self, VALUE document,
+                                 VALUE addr)
+{
+    void *node;
+    int st;
+
+    (void)self;
+    resolve_binding_classes();
+    if (NIL_P(rb_ivar_get(document, id_iv_c_address)))
+        rb_raise(c_use_after_free_error,
+                 "owning document has been freed");
+    if (rb_ivar_get(document, id_iv_readonly) == Qtrue)
+        rb_raise(c_readonly_error,
+                 "document is readonly — mutation attempted");
+    node = (void *)(uintptr_t)NUM2ULL(addr);
+    rb_ivar_set(document, id_iv_version,
+                LONG2FIX(FIX2LONG(rb_ivar_get(document, id_iv_version)) + 1));
+    st = f_set_root(doc_ptr_of(document), node);
+    return INT2FIX(st);
+}
+
 /* ---- C-yield traversal (TODO.perf/27) ----------------------------
  * Same contracts as the Ruby FFI::Function versions without the
  * per-call closure: traverse is post-order with abort-at-self
@@ -915,6 +944,72 @@ static VALUE nf_fast_pi_data(VALUE self, VALUE addr)
     return s ? rb_utf8_str_new_cstr(s) : Qnil;
 }
 
+/* Shared construction for address-walk faces (TODO.perf/30):
+ * cache lookup + kind-dispatched binding wrapper. */
+static VALUE wrap_addr_node(VALUE document, void *ptr)
+{
+    VALUE cache, key, node;
+    int kind;
+
+    kind = f_node_type(ptr);
+    cache = binding_cache_of(document);
+    key = ULL2NUM((uint64_t)(uintptr_t)ptr);
+    node = rb_hash_aref(cache, key);
+    if (NIL_P(node)) {
+        node = rb_obj_alloc(binding_klass_for(kind));
+        rb_iv_set(node, "@c_address", key);
+        rb_iv_set(node, "@document", document);
+        rb_iv_set(node, "@parent", Qnil);
+        if (rb_obj_class(document) == c_iteration_scope) {
+            rb_iv_set(node, "@structure_memoizable", Qfalse);
+            rb_iv_set(node, "@native_fast", Qfalse);
+            rb_iv_set(node, "@pub_document", Qnil);
+        } else {
+            rb_iv_set(node, "@structure_memoizable", Qtrue);
+            rb_iv_set(node, "@native_fast", Qtrue);
+            rb_iv_set(node, "@pub_document", document);
+        }
+        rb_iv_set(node, "@addr_reads_fast", Qtrue);
+        rb_iv_set(node, "@node_type", INT2FIX(kind));
+        rb_hash_aset(cache, key, node);
+    }
+    return node;
+}
+
+/* First element child in one C walk (text-heavy parents paid two
+ * FFI calls per skipped sibling). */
+static VALUE nf_first_element_child(VALUE self, VALUE document,
+                                    VALUE addr)
+{
+    void *p;
+
+    (void)self;
+    resolve_binding_classes();
+    for (p = f_first_child((void *)(uintptr_t)NUM2ULL(addr));
+         p != NULL; p = f_next_sibling(p)) {
+        if (f_node_type(p) == NT_ELEMENT)
+            return wrap_addr_node(document, p);
+    }
+    return Qnil;
+}
+
+/* Last element child in one C walk (the batch fetch materialized
+ * every child to keep one). */
+static VALUE nf_last_element_child(VALUE self, VALUE document,
+                                   VALUE addr)
+{
+    void *p, *last = NULL;
+
+    (void)self;
+    resolve_binding_classes();
+    for (p = f_first_child((void *)(uintptr_t)NUM2ULL(addr));
+         p != NULL; p = f_next_sibling(p)) {
+        if (f_node_type(p) == NT_ELEMENT)
+            last = p;
+    }
+    return last ? wrap_addr_node(document, last) : Qnil;
+}
+
 /* Owned string: copy + free through the engine's seam (the
  * read_owned_string protocol). */
 static VALUE nf_fast_path(VALUE self, VALUE addr)
@@ -1737,6 +1832,48 @@ static const rb_data_type_t dh_type = {
 static VALUE c_doc_handle;
 static ID id_iv_doc_handle, id_freed_new, id_alive;
 
+/* Node#dup in one dispatch (TODO.perf/30): engine create +
+ * lifetime handle + document wrapper + element_copy + the copy
+ * wrapped-and-rooted (memo-seeded). The namespace lift stays a
+ * Ruby decision (skip_adoption_lift? — the copy_of seam's
+ * semantics, #696/#721/#812). */
+static VALUE nf_copy_binding_element(VALUE self, VALUE document,
+                                     VALUE addr)
+{
+    void *doc, *copy;
+    VALUE new_doc, doc_addr, handle, freed, root;
+    struct doc_handle *h;
+
+    (void)self;
+    resolve_binding_classes();
+    doc = f_doc_create();
+    if (!doc)
+        return Qnil;
+    doc_addr = ULL2NUM((uint64_t)(uintptr_t)doc);
+    new_doc = rb_obj_alloc(c_b_document);
+    rb_iv_set(new_doc, "@c_ptr",
+              rb_funcall(c_ffi_pointer, id_ptr_new, 1, doc_addr));
+    rb_iv_set(new_doc, "@c_address", doc_addr);
+    freed = rb_funcall(c_b_freed, id_freed_new, 1, ID2SYM(id_alive));
+    rb_iv_set(new_doc, "@freed", freed);
+    rb_iv_set(new_doc, "@readonly", Qfalse);
+    rb_iv_set(new_doc, "@version", INT2FIX(0));
+    handle = TypedData_Make_Struct(c_doc_handle, struct doc_handle,
+                                   &dh_type, h);
+    h->doc = doc;
+    rb_ivar_set(new_doc, id_iv_doc_handle, handle);
+
+    copy = f_elem_copy((void *)(uintptr_t)NUM2ULL(addr), doc);
+    if (!copy) {
+        h->doc = NULL; /* the handle releases the empty doc */
+        return Qnil;
+    }
+    root = wrap_addr_node(new_doc, copy);
+    rb_ivar_set(new_doc, rb_intern("@root"), root);
+    rb_ivar_set(new_doc, rb_intern("@root_version"), INT2FIX(0));
+    return new_doc;
+}
+
 static VALUE nf_doc_handle_attach(VALUE self, VALUE document)
 {
     struct doc_handle *h;
@@ -1952,6 +2089,14 @@ void Init_native(void)
                               nf_fast_pi_data, 1);
     rb_define_module_function(m_native, "fast_path",
                               nf_fast_path, 1);
+    rb_define_module_function(m_native, "first_element_child",
+                              nf_first_element_child, 2);
+    rb_define_module_function(m_native, "last_element_child",
+                              nf_last_element_child, 2);
+    rb_define_module_function(m_native, "copy_binding_element",
+                              nf_copy_binding_element, 2);
+    rb_define_module_function(m_native, "set_binding_root",
+                              nf_set_binding_root, 2);
     rb_define_module_function(m_native, "fast_inner_xml",
                               nf_fast_inner_xml, 1);
     rb_define_module_function(m_native, "doc_handle_attach",

data/lib/leptris/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Leptris
-  VERSION = "1.9.174.6"
+  VERSION = "1.9.174.8"
 end

data/lib/leptris/xml/document.rb

@@ -283,14 +283,29 @@ class Leptris::XML::Document
   # document's pool until #free).
   def root=(element)
     raise Leptris::XML::UseAfterFreeError if @freed.state == :freed
+    # Same mutation gate as every other writer — the FFI path
+    # historically missed it (TODO.perf/33: the C face exposed
+    # the divergence; readonly is one-way, so one ivar read).
+    if @readonly
+      raise Leptris::XML::ReadOnlyError,
+            "document is readonly — root= attempted"
+    end
     # A document root has no in-scope declarations of its own —
     # lift everything the element's source scope carried (#178).
     unless Leptris::XML::Element.skip_adoption_lift?(element)
       Leptris::XML::Element.lift_namespaces_for_adoption(element, {})
     end
-    Leptris::XML::FFI.check_status(
-      Leptris::XML::FFI.leptris_document_set_root(c_ptr, element.c_ptr))
-    @version += 1
+    # TODO.perf/33: gates + bump + engine set_root in one C
+    # dispatch (the FFI call plus the c_ptr materialization fed
+    # ~5% of a fresh-doc build).
+    if defined?(Leptris::XML::NATIVE_FAST)
+      Leptris::XML::FFI.check_status(
+        Leptris::XML::Native.set_binding_root(self, element.c_address))
+    else
+      Leptris::XML::FFI.check_status(
+        Leptris::XML::FFI.leptris_document_set_root(c_ptr, element.c_ptr))
+      @version += 1
+    end
     # Seed the root memo through wrap: a cross-document element
     # must enter THIS document's identity cache with @document
     # pointing here, not ride its source-document wrapper.

data/lib/leptris/xml/element.rb

@@ -497,9 +497,21 @@ class Leptris::XML::Element < Leptris::XML::Node
 
   # Deep copy in a NEW document via Document.copy_of (the single
   # copy seam — every child kind and namespace survives,
-  # #696/#721/#812).
+  # #696/#721/#812). TODO.perf/30: one C dispatch when the ext
+  # is loaded — the namespace-lift decision stays here.
   def dup
     ensure_alive!
+    if @addr_reads_fast
+      doc = Leptris::XML::Native.copy_binding_element(
+        @document, @c_address)
+      unless doc.nil?
+        copied = doc.root
+        unless Leptris::XML::Element.skip_adoption_lift?(copied)
+          Leptris::XML::Element.lift_namespaces_for_adoption(copied, {})
+        end
+        return copied
+      end
+    end
     Leptris::XML::Document.copy_of(self)
   end
   alias_method :clone, :dup

data/lib/leptris/xml/node.rb

@@ -8,6 +8,12 @@ class Leptris::XML::Node
     @c_ptr ||= ::FFI::Pointer.new(@c_address)
   end
 
+  # The Integer twin of #c_ptr — reading it never materializes a
+  # Pointer (the native faces take addresses).
+  def c_address
+    @c_address
+  end
+
   # Iterparse-yielded elements are owned by an IterationScope (the
   # internal lifetime/memoization authority) — the public #document
   # answers nil for them, per the documented contract.
@@ -390,6 +396,17 @@ class Leptris::XML::Node
   def first_element_child
     return @first_element_child if memo_hit?(@first_element_child_version)
     ensure_alive!
+    # TODO.perf/30: one C walk (the FFI scan paid two calls per
+    # skipped non-element sibling).
+    if @addr_reads_fast
+      result = Leptris::XML::Native.first_element_child(
+        @document, @c_address)
+      if @document
+        @first_element_child = result
+        @first_element_child_version = @document.version
+      end
+      return result
+    end
     # Raw pointer scan: non-element siblings are typed with one C
     # call each — never wrapped, never cached — and the found
     # element carries the ELEMENT hint into the wrap.
@@ -413,8 +430,12 @@ class Leptris::XML::Node
   end
 
   def last_element_child
-    # Element receivers: the element-only batch fetches pointers
-    # without wrapping any text child; only the last is wrapped.
+    # TODO.perf/30: one C walk — the batch fetch materialized
+    # every child pointer to keep one.
+    if @addr_reads_fast
+      return Leptris::XML::Native.last_element_child(
+        @document, @c_address)
+    end
     if is_a?(Leptris::XML::Element)
       kids = Leptris::XML::FFI.fetch_element_children(c_ptr)
       return nil if kids.empty?
@@ -600,6 +621,23 @@ class Leptris::XML::Node
   # non-element kinds rebuild by value — #161).
   def dup
     ensure_alive!
+    # TODO.perf/30: elements copy in one C dispatch (engine
+    # create + handle + element_copy + rooted wrap). The
+    # namespace lift stays a Ruby decision — the copy_of seam's
+    # semantics (#696/#721/#812) run below when needed.
+    if element? && @addr_reads_fast
+      doc = Leptris::XML::Native.copy_binding_element(
+        @document, @c_address)
+      unless doc.nil?
+        # copy_of's contract returns the copied ROOT (the last
+        # expression of the root= assignment), not the document.
+        copied = doc.root
+        unless Leptris::XML::Element.skip_adoption_lift?(copied)
+          Leptris::XML::Element.lift_namespaces_for_adoption(copied, {})
+        end
+        return copied
+      end
+    end
     Leptris::XML::Document.copy_of(self)
   end
   alias_method :clone, :dup

data/lib/leptris/xml/searchable.rb

@@ -69,7 +69,16 @@ module Leptris::XML::Searchable
           doc_ptr, context_ptr, expr,
           Leptris::XML::Searchable.xpath_version_code(version), nil)
       elsif ns && !ns.empty?
-        xpath_eval_with_namespaces(doc_ptr, context_ptr, expr, ns)
+        # TODO.perf/29: the compiled handle is ns-independent —
+        # ride the cache and the cached ns set instead of the
+        # engine's string parse per call.
+        if (compiled = Leptris::XML::Searchable.compiled_expression(expr))
+          Leptris::XML::FFI.with_ns_set(ns) do |set|
+            compiled.eval_ns_ptrs(doc_ptr, context_ptr, set)
+          end
+        else
+          xpath_eval_with_namespaces(doc_ptr, context_ptr, expr, ns)
+        end
       elsif (compiled = Leptris::XML::Searchable.compiled_expression(expr))
         compiled.eval_ptrs(doc_ptr, context_ptr)
       else
@@ -105,7 +114,16 @@ module Leptris::XML::Searchable
           doc_ptr, context_ptr, expr,
           Leptris::XML::Searchable.xpath_version_code(version), nil)
       elsif ns && !ns.empty?
-        xpath_eval_with_namespaces(doc_ptr, context_ptr, expr, ns)
+        # TODO.perf/29: the compiled handle is ns-independent —
+        # ride the cache and the cached ns set instead of the
+        # engine's string parse per call.
+        if (compiled = Leptris::XML::Searchable.compiled_expression(expr))
+          Leptris::XML::FFI.with_ns_set(ns) do |set|
+            compiled.eval_ns_ptrs(doc_ptr, context_ptr, set)
+          end
+        else
+          xpath_eval_with_namespaces(doc_ptr, context_ptr, expr, ns)
+        end
       elsif (compiled = Leptris::XML::Searchable.compiled_expression(expr))
         compiled.eval_ptrs(doc_ptr, context_ptr)
       else

data/lib/leptris/xml/xpath.rb

@@ -40,6 +40,14 @@ class Leptris::XML::XPath
       @handle, doc_ptr, context_ptr)
   end
 
+  # Namespace-bound evaluation against the compiled handle
+  # (TODO.perf/29): the handle is ns-independent — compile once,
+  # bind per call through the cached ns set.
+  def eval_ns_ptrs(doc_ptr, context_ptr, ns_set_ptr)
+    Leptris::XML::FFI.leptris_xpath_compiled_eval_ns(
+      @handle, doc_ptr, context_ptr, ns_set_ptr)
+  end
+
   def initialize(expression, handle, version_code = nil)
     @expression = expression
     @handle = handle

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: leptris
 version: !ruby/object:Gem::Version
-  version: 1.9.174.6
+  version: 1.9.174.8
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-15 00:00:00.000000000 Z
+date: 2026-09-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ffi
@@ -97,6 +97,11 @@ files:
 - TODO.perf/26-post-mutation-memo-seeding.md
 - TODO.perf/27-c-yield-traversal.md
 - TODO.perf/28-address-fills.md
+- TODO.perf/29-ns-xpath-compiled.md
+- TODO.perf/30-copy-and-element-child-faces.md
+- TODO.perf/31-battery-rounds-4-8.md
+- TODO.perf/32-clean-host-floor-table.md
+- TODO.perf/33-cbound-root-set.md
 - TODO.restructure/01-constraint-compliance-audit.md
 - TODO.restructure/02-deep-copy-seam.md
 - TODO.restructure/03-evaluation-context-seam.md