leptris 1.9.163.5 → 1.9.163.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fc446877d41a4725feaa4ac5a451398395c2b74888ecbe6b89bd15c07586c5b1
-  data.tar.gz: e86fb2e1ad7af3a32ca07f5fdb93936b88c2910d61618f4c5e3afb9fe8828a21
+  metadata.gz: ed19c6383e8e83433ffcc99c8843337eb64ba48ac4f40349d5c5e0a537a31ab9
+  data.tar.gz: 3096440c8ba68d7eb54bfb2fd133098c795b025ec74389d09fd09cacd12f6311
 SHA512:
-  metadata.gz: 49705259500bd74522dbfbdd2f9703249eed074148f73d7207f430072e531194740232ba6caa27eb7e21d5a67a14f25a06b9fe5b82f1e10fb6b65e394c1f7c2a
-  data.tar.gz: fbea087c956ce35ba6e30f274db4c9db2f7b194e61e4f78633a9510fe85d6151c35f4758ade380d8a1397d261756fbd415d78b0587b628965b8ca82b9179af5f
+  metadata.gz: 5bef6e81be43ea7d536252201a4a59477d6c296a14ef186f9adb28fd304a13fb533218d46ac4d2245e55b724a62d13ab6d39088f82a750bbdfdb797c26c64c93
+  data.tar.gz: 9a61e4f09d0df6fc73479e1a25b83a146e77e28bae50b1d4dd82e5ed3b5f10be0e9b879e866d70f1207ac0abeda302d32f92c7b7efb4a27da8ee1958c6c63edd

data/CHANGELOG.md

@@ -5,6 +5,46 @@ 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.163.6] - 2026-09-15
+
+### Changed
+
+- **Document lifetime in C (TODO.perf/12)**: a TypedData DocHandle
+  (dfree -> leptris_document_free) replaces the ObjectSpace
+  finalizer whenever the native layer is enabled — no Ruby
+  finalizer invocation, no FFI dispatch from finalizer context,
+  for every parsed and created document. `Document.create` runs
+  as one C dispatch (engine create + ivar-seeded wrapper +
+  handle). The proc finalizer remains for `LEPTRIS_NO_NATIVE`.
+- **Structural memos (TODO.perf/13)**: `Document#root`,
+  `Node#parent`, `#next_sibling`, `#previous_sibling` keep
+  version-stamped memos (~72-82ns hits vs ~300-500ns deriving,
+  measured under host load 17). Fixes a real FFI-mode bug: the
+  children walk seeded `@parent`, and a later move left the stale
+  parent answering. Cross-document moves clear the moved node's
+  stamps and advance the source document's version; the
+  adoption-lift ancestor walk derives unstamped (a stamped
+  derive between the version bump and the engine move would
+  record post-bump versions carrying pre-move truth); scope-owned
+  iterparse elements never memoize.
+- **C-bound insert family (TODO.perf/14)**: `prepend_child`,
+  `add_next_sibling`, `add_previous_sibling` dispatch through
+  `Native.insert_binding_child` (gates + predicate + version bump
+  + engine insert in one call; lift fallback preserved). The
+  cold `Element#[]` first-touch fill rides the native face.
+- **Compiled-expression cache (TODO.perf/15)**: plain
+  `xpath`/`at_xpath` evaluate a bounded LRU (64) of compiled
+  handles — repeat expressions measured 3.7µs -> ~1.9µs (~2x);
+  CSS rides it automatically. Failed compiles never cache;
+  version-pinned and namespace-bound entries unchanged.
+
+### Added
+
+- `Leptris::XML::DocHandle` (internal), `Native.doc_handle_attach/
+  release/create_binding_document/insert_binding_child`,
+  `XPath#eval_ptrs`, `Searchable.compiled_expression`, and
+  `Node#unstamped_parent` (protected ancestor-walk seam).
+
 ## [1.9.163.5] - 2026-09-15
 
 ### Changed

data/TODO.perf/12-document-lifetime-in-c.md

@@ -0,0 +1,47 @@
+# 12 — Document lifetime in C: TypedData handle replaces the ObjectSpace finalizer
+
+Status: DONE (1.9.163.6)
+
+Every document (parsed AND created) registers an ObjectSpace
+finalizer: a per-document proc allocation (~110ns), the
+define_finalizer call (~315ns), the Freed struct, and — the real
+cost — a Ruby finalizer invocation at GC time that must dispatch
+back through FFI to leptris_document_free (~1-2µs per document
+inside GC pauses). Fresh-document build loops measured 7.1µs per
+Document.create in-loop, ~4-5µs of it GC/finalizer amortization
+(stackprof: GC ~19% of a build loop, define_finalizer+proc in the
+top frames).
+
+Fix: a TypedData DocHandle (struct { void *doc; }) whose dfree
+calls leptris_document_free directly — no Ruby finalizer, no FFI
+from finalizer context, no proc. The handle is referenced only by
+the Document's @doc_handle ivar, so its lifetime IS the
+Document's. Document#free keeps its explicit path (FFI free +
+release the handle's pointer so dfree no-ops — the same
+double-free protocol Freed enforces today, in C). The proc
+finalizer stays for LEPTRIS_NO_NATIVE mode.
+
+Companion: Native.create_binding_document — the full
+Document.create in one C dispatch (engine create + wrapper
+allocation + @c_ptr/@c_address/@freed/@readonly/@version + handle
+attach). Document.create today pays FFI marshaling + wrap frames
+(~250-600ns) on top of the engine call.
+
+Gates: lifetime_contract_spec + memory_spec green in both modes;
+double-free impossible (free → dfire no-op, finalizer-mode
+unchanged); Document.create and fresh-doc build rows improve.
+
+## Outcome (1.9.163.6)
+
+DocHandle TypedData (struct { void *doc; }, RUBY_TYPED_FREE_IMMEDIATELY,
+dfree -> leptris_document_free) attached as @doc_handle on every
+wrap() when native is enabled; Document#free detaches it (dfree
+no-ops). Native.create_binding_document does engine create +
+ivar-seeded wrapper + handle in one dispatch (Document.create
+routes through it). Freed stays the shared free-state; the proc
+finalizer remains for LEPTRIS_NO_NATIVE. 3,000-doc GC-reclamation
+and explicit-free-then-GC specs green; 647/0 both modes. Measured
+under host load 14-30: GC-amortized Document.create ~5.0us (the
+Ruby-finalizer invocation and FFI-dispatch-at-GC are gone from
+every document lifecycle; clean-load numbers pending the battery
+— the box never dropped under load 13 this session).

data/TODO.perf/13-structural-memos.md

@@ -0,0 +1,49 @@
+# 13 — Version-stamped structural memos: root/parent/siblings (+ FFI-mode stale-@parent fix)
+
+Status: DONE (1.9.163.6)
+
+Document#root re-derives (FFI + wrap) on every call — every
+pipeline entry pays it. Node#parent and the sibling hops
+(next_sibling/previous_sibling) pay FFI + Node.wrap per call, so
+Nokogiri-style sibling-advancement loops pay ~300ns/hop.
+
+BUG found while designing this: in FFI mode the children walk
+seeds @parent, and a later move (add_child to another parent)
+leaves the stale @parent — child.parent answers the OLD parent.
+Native mode masks it (the bulk path does not seed @parent). The
+version-stamped memo fixes both modes: derive once, stamp with
+the owning document's mutation version, re-derive after any
+mutation that bumps it.
+
+Design: parent memoizes only for document-owned nodes
+(scope-owned iterparse elements keep deriving — a scope element
+adopted into a document moves without its scope's version
+advancing, so a stamp would lie). Cross-document adoption bumps
+BOTH documents' versions (the source document's other nodes hold
+sibling/parent stamps that the move invalidates); the moved
+node's stamps clear at the mutation site. next_sibling /
+previous_sibling memoize the same way. Document#root memoizes
+against the document's own version (root= bumps it; free clears).
+
+Gates: parent correct after same-doc and cross-doc moves in BOTH
+modes (the FFI staleness becomes a spec); sibling chains correct
+around unlink/insert; root identity stable; traversal-loop rows
+improve.
+
+## Outcome (1.9.163.6)
+
+Version-stamped memos on Document#root (pure ivar compare, ~82ns
+under load 17), Node#parent / next_sibling / previous_sibling
+(~72-76ns memo hits vs ~300-500ns deriving; @structure_memoizable
+computed once at construction — including the C-constructed
+wrappers — keeping the hit path free of method dispatch). The
+FFI-mode stale-@parent bug is FIXED (spec-pinned: parent correct
+after same-doc and cross-doc moves; the seed stamps only
+constructor-KNOWN parents — nil constructor parent means unknown,
+because the engine may attach during creation, e.g. create_child).
+Cross-document moves clear the moved node's stamps and advance
+the SOURCE document's version. The adoption-lift ancestor walk
+uses Node#unstamped_parent: deriving a stamped parent between the
+version bump and the engine move would record post-bump versions
+carrying pre-move truth. Scope-owned iterparse elements never
+memoize.

data/TODO.perf/14-insert-family-c-bound.md

@@ -0,0 +1,31 @@
+# 14 — C-bound insert family + cold-[] native fill
+
+Status: DONE (1.9.163.6)
+
+add_child and []= are C-bound (TODO.perf/08-09); prepend_child,
+add_next_sibling, and add_previous_sibling still run the full
+Ruby path (ensure_writable + eager-namespace guard ordering +
+FFI). One C face with a mode int covers all engine insertions
+(append/prepend/insert_after/insert_before — same
+int(void*, void*) ABI): gates + predicate + version bump + engine
+insert in one dispatch, Qnil fallback when the child needs the
+namespace lift, exactly like append_binding_child.
+
+Also: the completely-cold branch of Element#[] fills through
+leptris_element_attribute (FFI) while the partial-memo branch
+above it uses the native face — the cold path should ride the
+native face too (~150ns per first-touch attribute read).
+
+Gates: insert semantics unchanged (specs exist for sibling
+inserts); namespaced children still lift; readonly raises.
+
+## Outcome (1.9.163.6)
+
+Native.insert_binding_child(document, anchor, child, mode): 1
+prepend / 2 after / 3 before — gates + predicate + version bump +
+engine insert in one dispatch, Qnil fallback to the Ruby lift
+path. prepend_child / add_next_sibling / add_previous_sibling
+carry the fast branch + cross-document invalidation. The
+completely-cold Element#[] first-touch fill rides the native face
+(matching the partial-memo branch). Specs: ordering, lift
+fallback, readonly raise.

data/TODO.perf/15-compiled-expression-cache.md

@@ -0,0 +1,35 @@
+# 15 — Compiled-expression cache for Searchable#xpath / #at_xpath
+
+Status: DONE (1.9.163.6)
+
+Searchable#xpath passes the expression STRING to
+leptris_xpath_eval each call. The engine caches compiled
+expressions by string (measured: repeat-string eval 7.0µs vs
+varied-string 34.98µs — the ~28µs is per-call parsing), but the
+string path still pays cache lookup + hashing per call. A
+compiled handle evaluated directly measured 4.58µs on the same
+shape — 34% under the string path.
+
+The binding already exposes XPath.compile (parse once, eval
+many). Add a bounded LRU keyed on the expression string inside
+Searchable: plain (no version pin, no ns bindings) xpath/at_xpath
+evaluations route through cached compiled handles. Cache only
+successful compiles; bounded (~64 entries, Hash#shift eviction);
+GVL makes the Hash ops safe.
+
+Gates: xpath/at_xpath results identical (nodesets, scalars,
+empty results); invalid expressions still raise XPathError;
+namespace-bound and version-pinned paths unchanged; repeat-call
+rows improve ~30%.
+
+## Outcome (1.9.163.6)
+
+Searchable.compiled_expression: bounded LRU (64 entries, Hash#shift
+eviction, LRU refresh on hit) keyed on the expression string;
+plain xpath/at_xpath evaluate cached compiled handles via
+XPath#eval_ptrs (leptris_xpath_compiled_eval). Failed compiles
+never cache (fall back to the string entry so the error surface
+is unchanged); version-pinned and namespace-bound paths keep
+their dedicated entries. Measured: repeat at_xpath 3.7us ->
+1.9us under load 17-30 (~2x); CSS rides it automatically
+(deterministic translation -> same key).

data/ext/leptris/native/native.c

@@ -74,6 +74,7 @@ static elem_create_fn f_elem_create;
 static text_create_fn f_text_create;
 static create_child_fn f_create_child;
 static append_child_fn f_append_child;
+static append_child_fn f_prepend_child, f_insert_after, f_insert_before;
 static set_attr_fn f_set_attr;
 static set_root_fn f_set_root;
 static doc_free_fn f_doc_free;
@@ -171,13 +172,17 @@ static void resolve_symbols(const char *lib_path)
     f_text_create = (text_create_fn)lib_sym(h, "leptris_text_node_create");
     f_create_child = (create_child_fn)lib_sym(h, "leptris_element_create_child");
     f_append_child = (append_child_fn)lib_sym(h, "leptris_element_append_child");
+    f_prepend_child = (append_child_fn)lib_sym(h, "leptris_element_prepend_child");
+    f_insert_after = (append_child_fn)lib_sym(h, "leptris_element_insert_after");
+    f_insert_before = (append_child_fn)lib_sym(h, "leptris_element_insert_before");
     f_set_attr = (set_attr_fn)lib_sym(h, "leptris_element_set_attribute");
     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 ||
         !f_children_ex || !f_node_type || !f_next_sibling || !f_parent ||
         !f_element_text || !f_doc_create || !f_elem_create || !f_text_create ||
-        !f_create_child || !f_append_child || !f_set_attr || !f_set_root ||
+        !f_create_child || !f_append_child || !f_prepend_child ||
+        !f_insert_after || !f_insert_before || !f_set_attr || !f_set_root ||
         !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 ||
@@ -602,6 +607,48 @@ static VALUE nf_set_binding_attribute(VALUE self, VALUE document,
     return INT2FIX(st);
 }
 
+/* C-bound insert family (TODO.perf/14): prepend / insert-after /
+ * insert-before share append's gates + predicate + bump shape.
+ * mode: 1 prepend, 2 after, 3 before (anchor = receiver). */
+static VALUE nf_insert_binding_child(VALUE self, VALUE document,
+                                     VALUE anchor_addr, VALUE child_addr,
+                                     VALUE mode)
+{
+    void *anchor, *child;
+    const char *uri;
+    int st, m;
+
+    (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");
+    anchor = (void *)(uintptr_t)NUM2ULL(anchor_addr);
+    child = (void *)(uintptr_t)NUM2ULL(child_addr);
+    m = FIX2INT(mode);
+    if (f_node_type(child) == NT_ELEMENT) {
+        if (f_elem_ns_count(child) > 0)
+            return Qnil;
+        uri = f_elem_ns(child);
+        if (uri && *uri)
+            return Qnil;
+    }
+    rb_ivar_set(document, id_iv_version,
+                LONG2FIX(FIX2LONG(rb_ivar_get(document, id_iv_version)) + 1));
+    switch (m) {
+    case 1:  st = f_prepend_child(anchor, child); break;
+    case 2:  st = f_insert_after(anchor, child);  break;
+    case 3:  st = f_insert_before(anchor, child); break;
+    default:
+        rb_raise(rb_eArgError, "invalid insert mode %d", m);
+        return Qnil;
+    }
+    return INT2FIX(st);
+}
+
 /* Builder factories (#149): create in C, wrap as NativeNode — no
  * FFI::Pointer, no Ruby wrap_fresh path. */
 static VALUE nn_create_element(VALUE klass, VALUE document, VALUE name)
@@ -726,7 +773,7 @@ static VALUE nn_address(VALUE self)
  * disappear. */
 static VALUE c_b_element = Qundef, c_b_text, c_b_comment, c_b_cdata,
              c_b_pi, c_b_node, c_b_result_text, c_b_result_attr,
-             c_b_attr, c_ffi_pointer;
+             c_b_attr, c_ffi_pointer, c_b_document, c_b_freed;
 static ID id_ptr_new;
 
 /* Binding classes resolve LAZILY: Init_native can run before the
@@ -746,6 +793,8 @@ static void resolve_binding_classes(void)
     c_b_result_attr = rb_path2class("Leptris::XML::ResultAttr");
     c_ffi_pointer = rb_path2class("FFI::Pointer");
     c_b_attr = rb_path2class("Leptris::XML::Attr");
+    c_b_document = rb_path2class("Leptris::XML::Document");
+    c_b_freed = rb_path2class("Leptris::XML::Document::Freed");
     id_ptr_new = rb_intern("new");
     rb_gc_register_mark_object(c_b_element);
     rb_gc_register_mark_object(c_b_text);
@@ -757,6 +806,8 @@ static void resolve_binding_classes(void)
     rb_gc_register_mark_object(c_b_result_attr);
     rb_gc_register_mark_object(c_ffi_pointer);
     rb_gc_register_mark_object(c_b_attr);
+    rb_gc_register_mark_object(c_b_document);
+    rb_gc_register_mark_object(c_b_freed);
 }
 
 static VALUE binding_klass_for(int kind)
@@ -801,6 +852,7 @@ static VALUE bulk_children_impl(VALUE document, VALUE parent_addr,
             rb_iv_set(node, "@c_ptr", ptr);
             rb_iv_set(node, "@document", document);
             rb_iv_set(node, "@parent", Qnil);
+            rb_iv_set(node, "@structure_memoizable", Qtrue);
             rb_iv_set(node, "@node_type", INT2FIX(kinds[i]));
             rb_hash_aset(cache, key, node);
         }
@@ -874,6 +926,7 @@ static VALUE nf_bulk_xpath(VALUE self, VALUE document, VALUE result_ptr_val)
                 rb_iv_set(node, "@c_ptr", ptr);
                 rb_iv_set(node, "@document", document);
                 rb_iv_set(node, "@parent", Qnil);
+                rb_iv_set(node, "@structure_memoizable", Qtrue);
                 rb_iv_set(node, "@node_type", INT2FIX(0));
                 rb_hash_aset(cache, key, node);
             }
@@ -913,6 +966,7 @@ static VALUE nf_bulk_xpath(VALUE self, VALUE document, VALUE result_ptr_val)
                         rb_iv_set(node, "@c_ptr", ptr);
                         rb_iv_set(node, "@document", document);
                         rb_iv_set(node, "@parent", Qnil);
+                        rb_iv_set(node, "@structure_memoizable", Qtrue);
                         rb_iv_set(node, "@node_type", INT2FIX(nt));
                         rb_hash_aset(cache, key, node);
                     }
@@ -972,6 +1026,7 @@ static VALUE nf_create_binding_element(VALUE self, VALUE document,
                          ULL2NUM((uint64_t)(uintptr_t)ptr)));
     rb_iv_set(node, "@document", document);
     rb_iv_set(node, "@parent", Qnil);
+    rb_iv_set(node, "@structure_memoizable", Qtrue);
     rb_iv_set(node, "@node_type", INT2FIX(0));
     cache = binding_cache_of(document);
     key = ULL2NUM((uint64_t)(uintptr_t)ptr);
@@ -996,6 +1051,7 @@ static VALUE nf_create_binding_text(VALUE self, VALUE document,
                          ULL2NUM((uint64_t)(uintptr_t)ptr)));
     rb_iv_set(node, "@document", document);
     rb_iv_set(node, "@parent", Qnil);
+    rb_iv_set(node, "@structure_memoizable", Qtrue);
     rb_iv_set(node, "@node_type", INT2FIX(1));
     cache = binding_cache_of(document);
     key = ULL2NUM((uint64_t)(uintptr_t)ptr);
@@ -1113,6 +1169,99 @@ static VALUE nf_fast_element_xml(VALUE self, VALUE addr,
  * predicate answers in ONE dispatch: false when the node carries
  * no namespace declarations AND its name has no prefix — the
  * common programmatic-build shape (bare names, no namespaces). */
+/* ---- Document lifetime in C (TODO.perf/12) ----------------------
+ * A TypedData handle holding the C document pointer, referenced
+ * only by the binding Document's @doc_handle ivar — its lifetime
+ * IS the document's. dfree releases the C document directly: no
+ * Ruby finalizer, no FFI dispatch from finalizer context.
+ * Document#free releases the pointer first, so dfree no-ops —
+ * the same double-free protocol the Freed struct enforces on the
+ * Ruby-finalizer path (which stays for LEPTRIS_NO_NATIVE). */
+struct doc_handle {
+    void *doc;
+};
+
+static void dh_free(void *p)
+{
+    struct doc_handle *h = p;
+    if (h->doc) {
+        f_doc_free(h->doc);
+        h->doc = NULL;
+    }
+}
+
+static size_t dh_size(const void *p)
+{
+    (void)p;
+    return sizeof(struct doc_handle);
+}
+
+static const rb_data_type_t dh_type = {
+    "Leptris/XML/DocHandle",
+    { 0, dh_free, dh_size, },
+    0, 0, RUBY_TYPED_FREE_IMMEDIATELY
+};
+
+static VALUE c_doc_handle;
+static ID id_iv_doc_handle, id_freed_new, id_alive;
+
+static VALUE nf_doc_handle_attach(VALUE self, VALUE document)
+{
+    struct doc_handle *h;
+    VALUE handle;
+
+    (void)self;
+    handle = TypedData_Make_Struct(c_doc_handle, struct doc_handle,
+                                   &dh_type, h);
+    h->doc = doc_ptr_of(document);
+    rb_ivar_set(document, id_iv_doc_handle, handle);
+    return handle;
+}
+
+/* Document#free already released the C memory through the FFI
+ * seam; detach so the GC-pass dfree no-ops. */
+static VALUE nf_doc_handle_release(VALUE self, VALUE document)
+{
+    VALUE handle = rb_ivar_get(document, id_iv_doc_handle);
+    (void)self;
+    if (handle != Qnil) {
+        struct doc_handle *h;
+        TypedData_Get_Struct(handle, struct doc_handle, &dh_type, h);
+        h->doc = NULL;
+    }
+    return Qnil;
+}
+
+/* The full Document.create in one dispatch: engine create,
+ * binding wrapper (ivar-seeded, bypassing initialize), and the
+ * lifetime handle. Returns Qnil when the engine refuses. */
+static VALUE nf_create_binding_document(VALUE self)
+{
+    void *doc;
+    VALUE document, addr, handle, freed;
+    struct doc_handle *h;
+
+    (void)self;
+    resolve_binding_classes();
+    doc = f_doc_create();
+    if (!doc)
+        return Qnil;
+    addr = ULL2NUM((uint64_t)(uintptr_t)doc);
+    document = rb_obj_alloc(c_b_document);
+    rb_iv_set(document, "@c_ptr",
+              rb_funcall(c_ffi_pointer, id_ptr_new, 1, addr));
+    rb_iv_set(document, "@c_address", addr);
+    freed = rb_funcall(c_b_freed, id_freed_new, 1, ID2SYM(id_alive));
+    rb_iv_set(document, "@freed", freed);
+    rb_iv_set(document, "@readonly", Qfalse);
+    rb_iv_set(document, "@version", INT2FIX(0));
+    handle = TypedData_Make_Struct(c_doc_handle, struct doc_handle,
+                                   &dh_type, h);
+    h->doc = doc;
+    rb_ivar_set(document, id_iv_doc_handle, handle);
+    return document;
+}
+
 /* ---- Address-based fast readers (TODO.perf/01) -----------------
  * The DEFAULT binding classes call these when the bundle is
  * loaded: one C-API dispatch + rb_utf8_str_new_cstr — no FFI
@@ -1198,6 +1347,9 @@ void Init_native(void)
     id_iv_nn_content_ver = rb_intern("@nn_content_ver");
     id_iv_nn_attrs = rb_intern("@nn_attrs");
     id_iv_nn_attrs_ver = rb_intern("@nn_attrs_ver");
+    id_iv_doc_handle = rb_intern("@doc_handle");
+    id_freed_new = rb_intern("new");
+    id_alive = rb_intern("alive");
     c_readonly_error = rb_path2class("Leptris::XML::ReadOnlyError");
     c_use_after_free_error =
         rb_path2class("Leptris::XML::UseAfterFreeError");
@@ -1240,6 +1392,16 @@ void Init_native(void)
                               nf_append_binding_child, 3);
     rb_define_module_function(m_native, "set_binding_attribute",
                               nf_set_binding_attribute, 4);
+    rb_define_module_function(m_native, "insert_binding_child",
+                              nf_insert_binding_child, 4);
+    rb_define_module_function(m_native, "doc_handle_attach",
+                              nf_doc_handle_attach, 1);
+    rb_define_module_function(m_native, "doc_handle_release",
+                              nf_doc_handle_release, 1);
+    rb_define_module_function(m_native, "create_binding_document",
+                              nf_create_binding_document, 0);
+    c_doc_handle = rb_define_class_under(m_xml, "DocHandle", rb_cObject);
+    rb_undef_alloc_func(c_doc_handle);
     rb_define_module_function(m_native, "bulk_attributes", nf_bulk_attributes, 1);
     rb_define_module_function(m_native, "bulk_attr_faces",
                               nf_bulk_attr_faces, 2);

data/lib/leptris/version.rb

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

data/lib/leptris/xml/document.rb

@@ -129,6 +129,15 @@ class Leptris::XML::Document
   # pool. Elements for the tree are created against it via
   # #create_element and friends, then attached with #root=.
   def self.create
+    # One C dispatch (TODO.perf/12): engine create + wrapper
+    # (ivar-seeded) + lifetime handle. The FFI+wrap shape stays
+    # for LEPTRIS_NO_NATIVE.
+    if defined?(Leptris::XML::NATIVE_FAST)
+      doc = Leptris::XML::Native.create_binding_document
+      raise Leptris::XML::Error,
+        "leptris_document_create failed" if doc.nil?
+      return doc
+    end
     raw = Leptris::XML::FFI.leptris_document_create
     raise Leptris::XML::Error,
       "leptris_document_create failed" if raw.null?
@@ -178,7 +187,14 @@ class Leptris::XML::Document
     ptr = ::FFI::Pointer.new(addr)
     freed = Freed.new(:alive)
     doc = new(ptr, freed)
-    ObjectSpace.define_finalizer(doc, finalizer(addr, freed))
+    if defined?(Leptris::XML::NATIVE_FAST)
+      # TypedData dfree owns the release at GC (TODO.perf/12): no
+      # Ruby finalizer, no FFI dispatch from finalizer context.
+      # Freed stays the shared free-state for #freed?/#free.
+      Leptris::XML::Native.doc_handle_attach(doc)
+    else
+      ObjectSpace.define_finalizer(doc, finalizer(addr, freed))
+    end
     doc
   end
 
@@ -194,9 +210,16 @@ class Leptris::XML::Document
   def root
     raise Leptris::XML::UseAfterFreeError if @freed.state == :freed
     return nil if @c_ptr.nil?
+    # Version-stamped memo (TODO.perf/13): root changes only
+    # through mutations that advance @version (root=, unlink) or
+    # #free (which nils @c_ptr above) — the entry point of every
+    # pipeline stops paying FFI + wrap per call.
+    return @root if @root_version == @version
     ptr = Leptris::XML::FFI.leptris_document_root(@c_ptr)
-    return nil if ptr.null?
-    Leptris::XML::Node.wrap(ptr, self)
+    result = ptr.null? ? nil : Leptris::XML::Node.wrap(ptr, self)
+    @root = result
+    @root_version = @version
+    result
   end
 
   # The document node — navigation head over the whole tree chain
@@ -268,6 +291,12 @@ class Leptris::XML::Document
     Leptris::XML::FFI.check_status(
       Leptris::XML::FFI.leptris_document_set_root(@c_ptr, element.c_ptr))
     @version += 1
+    # 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.
+    @root = Leptris::XML::Node.wrap(element.c_ptr, self)
+    @root_version = @version
+    Leptris::XML::Node.invalidate_cross_document!(element, self)
     element
   end
 
@@ -391,6 +420,9 @@ class Leptris::XML::Document
     @c_ptr = nil
     @c_address = nil
     @wrapper_cache&.clear
+    # Detach the lifetime handle (TODO.perf/12): the memory is
+    # already released above — the GC-pass dfree must no-op.
+    Leptris::XML::Native.doc_handle_release(self) if defined?(Leptris::XML::NATIVE_FAST)
   end
 
   # Enable the first-party EXSLT-style extension pack on this

data/lib/leptris/xml/element.rb

@@ -87,12 +87,16 @@ class Leptris::XML::Element < Leptris::XML::Node
         values[name] = v
         return v
       end
-      # Completely cold: one FFI, start a partial values hash.
+      # Completely cold: one read, start a partial values hash.
       # Drop any full-face memos from a prior version — otherwise a
       # post-mutation cold [] would stamp the new version onto a
       # stale @attributes hash and attributes would serve it.
       ensure_alive!
-      v = Leptris::XML::FFI.leptris_element_attribute(@c_ptr, name)
+      v = if native_fast?
+            Leptris::XML::Native.fast_attribute(@c_ptr.address, name)
+          else
+            Leptris::XML::FFI.leptris_element_attribute(@c_ptr, name)
+          end
       @attr_values = { name => v }
       @attributes = nil
       @attribute_nodes = nil
@@ -315,32 +319,71 @@ class Leptris::XML::Element < Leptris::XML::Node
   end
 
   def prepend_child(node)
+    # C-bound insert (TODO.perf/14): gates + predicate + version
+    # bump + engine insert in one dispatch; Qnil = the child needs
+    # the namespace lift — the full path below handles it.
+    if native_fast_children?
+      st = Leptris::XML::Native.insert_binding_child(
+        @document, @c_ptr.address, node.c_ptr.address, 1)
+      unless st.nil?
+        Leptris::XML::FFI.check_status(st)
+        Leptris::XML::Node.invalidate_cross_document!(node, @document)
+        return node
+      end
+    end
     ensure_writable!
     unless Leptris::XML::Element.skip_adoption_lift?(node)
       Leptris::XML::Element.lift_namespaces_for_adoption(node, namespaces)
     end
     Leptris::XML::FFI.check_status(
       Leptris::XML::FFI.leptris_element_prepend_child(@c_ptr, node.c_ptr))
+    Leptris::XML::Node.invalidate_cross_document!(node, @document)
     node
   end
 
   def add_next_sibling(node)
+    # C-bound insert (TODO.perf/14): gates + predicate + version
+    # bump + engine insert in one dispatch; Qnil = the child needs
+    # the namespace lift — the full path below handles it.
+    if native_fast_children?
+      st = Leptris::XML::Native.insert_binding_child(
+        @document, @c_ptr.address, node.c_ptr.address, 2)
+      unless st.nil?
+        Leptris::XML::FFI.check_status(st)
+        Leptris::XML::Node.invalidate_cross_document!(node, @document)
+        return node
+      end
+    end
     ensure_writable!
     unless Leptris::XML::Element.skip_adoption_lift?(node)
       Leptris::XML::Element.lift_namespaces_for_adoption(node, namespaces)
     end
     Leptris::XML::FFI.check_status(
       Leptris::XML::FFI.leptris_element_insert_after(@c_ptr, node.c_ptr))
+    Leptris::XML::Node.invalidate_cross_document!(node, @document)
     node
   end
 
   def add_previous_sibling(node)
+    # C-bound insert (TODO.perf/14): gates + predicate + version
+    # bump + engine insert in one dispatch; Qnil = the child needs
+    # the namespace lift — the full path below handles it.
+    if native_fast_children?
+      st = Leptris::XML::Native.insert_binding_child(
+        @document, @c_ptr.address, node.c_ptr.address, 3)
+      unless st.nil?
+        Leptris::XML::FFI.check_status(st)
+        Leptris::XML::Node.invalidate_cross_document!(node, @document)
+        return node
+      end
+    end
     ensure_writable!
     unless Leptris::XML::Element.skip_adoption_lift?(node)
       Leptris::XML::Element.lift_namespaces_for_adoption(node, namespaces)
     end
     Leptris::XML::FFI.check_status(
       Leptris::XML::FFI.leptris_element_insert_before(@c_ptr, node.c_ptr))
+    Leptris::XML::Node.invalidate_cross_document!(node, @document)
     node
   end
 
@@ -437,6 +480,7 @@ class Leptris::XML::Element < Leptris::XML::Node
           @document, @c_ptr.address, node_or_markup.c_ptr.address)
         unless st.nil?
           Leptris::XML::FFI.check_status(st)
+          Leptris::XML::Node.invalidate_cross_document!(node_or_markup, @document)
           return node_or_markup
         end
       end
@@ -445,6 +489,7 @@ class Leptris::XML::Element < Leptris::XML::Node
       end
       Leptris::XML::FFI.check_status(
         Leptris::XML::FFI.leptris_element_append_child(@c_ptr, node_or_markup.c_ptr))
+      Leptris::XML::Node.invalidate_cross_document!(node_or_markup, @document)
       node_or_markup
     when String
       frag = Leptris::XML::DocumentFragment.parse(node_or_markup, @document)
@@ -546,7 +591,10 @@ class Leptris::XML::Element < Leptris::XML::Node
         key = ns.prefix ? "xmlns:#{ns.prefix}" : "xmlns"
         scopes[key] ||= ns.href
       end
-      node = node.parent
+      # unstamped: this walk also runs inside the adoption lift,
+      # between the version bump and the engine move (see
+      # Node#unstamped_parent).
+      node = node.unstamped_parent
     end
     if @document
       @namespaces = scopes

data/lib/leptris/xml/node.rb

@@ -14,6 +14,19 @@ class Leptris::XML::Node
     @c_ptr = c_ptr
     @document = document
     @parent = parent
+    # Structural-memo stamp (TODO.perf/13): a constructor-seeded
+    # @parent is true AS OF the document's current version; any
+    # mutation advances the version and forces re-derivation. A
+    # NIL constructor parent means UNKNOWN, not "no parent" — the
+    # engine may attach during creation (create_child), so an
+    # unstamped memo must derive rather than trust nil.
+    @parent_version = parent ? document&.version : nil
+    # Computed once: structural stamps apply to document-owned
+    # nodes only (scope-owned iterparse elements move without
+    # their scope's version advancing — see #parent). An ivar
+    # keeps the memo-hit path free of method dispatch.
+    @structure_memoizable =
+      !document.nil? && !document.is_a?(Leptris::XML::IterationScope)
     # wrap() already calls leptris_node_get_type for dispatch; reusing
     # the result makes every predicate and #type call FFI-free.
     @node_type = node_type
@@ -157,12 +170,60 @@ class Leptris::XML::Node
   end
   alias_method :pi?, :processing_instruction?
 
+  # Version-stamped structural memo (TODO.perf/13): derive once,
+  # re-derive after any mutation that advances the owning
+  # document's version. Fixes the stale seeded @parent after a
+  # move (FFI children walks seed it; the move never cleared it).
+  # Scope-owned (iterparse) elements never memoize: a scope element
+  # adopted into a document moves without its scope's version
+  # advancing, so a stamp would lie.
   def parent
-    return @parent if @parent
+    if @structure_memoizable && @parent_version == @document.version
+      return @parent
+    end
     ensure_alive!
     ptr = Leptris::XML::FFI.leptris_node_parent(@c_ptr)
-    return nil if ptr.null?
-    Leptris::XML::Node.wrap(ptr, @document)
+    result = ptr.null? ? nil : Leptris::XML::Node.wrap(ptr, @document)
+    if @document
+      @parent = result
+      @parent_version = @document.version
+    end
+    result
+  end
+
+  # Derive the parent WITHOUT stamping the structural memo. The
+  # adoption lift reads the child's source scope BETWEEN the
+  # mutation gate's version bump and the engine move — a stamped
+  # #parent there would record post-bump versions carrying
+  # pre-move truth. Ancestor walks that run inside mutations use
+  # this; #namespaces itself is memoized, so stable trees pay the
+  # unstamped derivation at most once per version.
+  def unstamped_parent
+    ensure_alive!
+    ptr = Leptris::XML::FFI.leptris_node_parent(@c_ptr)
+    ptr.null? ? nil : Leptris::XML::Node.wrap(ptr, @document)
+  end
+
+  # Mutation sites move nodes ACROSS documents: the moved node's
+  # stamps reference the source document's version, which the move
+  # does not advance. Clear them and advance the source version
+  # (its other nodes hold parent/sibling stamps the move invalidates).
+  def invalidate_structural_stamps!
+    @parent_version = nil
+    @next_sibling_version = nil
+    @previous_sibling_version = nil
+  end
+
+  # Mutation-site helper: when +node+ moves into +target_document+
+  # from a different one, the move invalidates the node's own
+  # structural stamps (stamped against the SOURCE version) and the
+  # source document's sibling/parent stamps. Scope-owned nodes
+  # answer nil from #document and never memoize — nothing to do.
+  def self.invalidate_cross_document!(node, target_document)
+    source = node.document
+    return if source.nil? || source.equal?(target_document)
+    node.invalidate_structural_stamps!
+    source.advance_version
   end
 
   # Borrowed-handle lifetime: every c_ptr dereference is valid only
@@ -267,18 +328,32 @@ class Leptris::XML::Node
   end
 
   def next_sibling
+    if @structure_memoizable && @next_sibling_version == @document.version
+      return @next_sibling
+    end
     ensure_alive!
     ptr = Leptris::XML::FFI.leptris_node_next_sibling(@c_ptr)
-    return nil if ptr.null?
-    Leptris::XML::Node.wrap(ptr, @document, parent: @parent)
+    result = ptr.null? ? nil : Leptris::XML::Node.wrap(ptr, @document, parent: @parent)
+    if @document
+      @next_sibling = result
+      @next_sibling_version = @document.version
+    end
+    result
   end
   alias_method :next, :next_sibling
 
   def previous_sibling
+    if @structure_memoizable && @previous_sibling_version == @document.version
+      return @previous_sibling
+    end
     ensure_alive!
     ptr = Leptris::XML::FFI.leptris_node_previous_sibling(@c_ptr)
-    return nil if ptr.null?
-    Leptris::XML::Node.wrap(ptr, @document, parent: @parent)
+    result = ptr.null? ? nil : Leptris::XML::Node.wrap(ptr, @document, parent: @parent)
+    if @document
+      @previous_sibling = result
+      @previous_sibling_version = @document.version
+    end
+    result
   end
   alias_method :previous, :previous_sibling
 

data/lib/leptris/xml/searchable.rb

@@ -5,6 +5,30 @@ module Leptris::XML::Searchable
   # mirroring leptris-py#105); anything else is a namespace prefix.
   VERSION_SELECTORS = ["1.0", "3.1", :xpath10, :xpath31].freeze
 
+  # Compiled-expression cache (TODO.perf/15): the engine caches
+  # compiled strings internally, but the string path still pays
+  # lookup + hashing per call — a direct handle eval measured 34%
+  # under it on repeat expressions. Bounded LRU keyed on the
+  # expression string; only successful compiles cache; GVL makes
+  # the Hash operations safe. Version-pinned and namespace-bound
+  # evaluations keep their dedicated string entries.
+  COMPILED_CACHE_LIMIT = 64
+
+  def self.compiled_expression(expr)
+    cache = (@compiled_expressions ||= {})
+    if (hit = cache[expr])
+      cache.delete(expr)
+      cache[expr] = hit # LRU refresh
+      return hit
+    end
+    compiled = Leptris::XML::XPath.compile(expr)
+    cache.shift while cache.size >= COMPILED_CACHE_LIMIT
+    cache[expr] = compiled
+    compiled
+  rescue Leptris::XML::XPathError
+    nil # fall back to the string path — its error surface is the contract
+  end
+
   def xpath(*paths)
     handler, ns, version = parse_search_args(paths)
     raise ArgumentError, "custom XPath handlers not supported" if handler
@@ -25,6 +49,8 @@ module Leptris::XML::Searchable
           Leptris::XML::Searchable.xpath_version_code(version), nil)
       elsif ns && !ns.empty?
         xpath_eval_with_namespaces(doc_ptr, context_ptr, expr, ns)
+      elsif (compiled = Leptris::XML::Searchable.compiled_expression(expr))
+        compiled.eval_ptrs(doc_ptr, context_ptr)
       else
         Leptris::XML::FFI.leptris_xpath_eval(doc_ptr, context_ptr, expr)
       end
@@ -56,6 +82,8 @@ module Leptris::XML::Searchable
           Leptris::XML::Searchable.xpath_version_code(version), nil)
       elsif ns && !ns.empty?
         xpath_eval_with_namespaces(doc_ptr, context_ptr, expr, ns)
+      elsif (compiled = Leptris::XML::Searchable.compiled_expression(expr))
+        compiled.eval_ptrs(doc_ptr, context_ptr)
       else
         Leptris::XML::FFI.leptris_xpath_eval(doc_ptr, context_ptr, expr)
       end

data/lib/leptris/xml/xpath.rb

@@ -32,6 +32,14 @@ class Leptris::XML::XPath
     new(expression.to_s, CompiledHandle.new(raw), version_code)
   end
 
+  # Raw-pointer evaluation for Searchable's compiled cache
+  # (TODO.perf/15): the same entry the string path uses, against
+  # the compiled handle — no per-call parse/cache lookup.
+  def eval_ptrs(doc_ptr, context_ptr)
+    Leptris::XML::FFI.leptris_xpath_compiled_eval(
+      @handle, doc_ptr, context_ptr)
+  end
+
   def initialize(expression, handle, version_code = nil)
     @expression = expression
     @handle = handle

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: leptris
 version: !ruby/object:Gem::Version
-  version: 1.9.163.5
+  version: 1.9.163.6
 platform: ruby
 authors:
 - Ribose Inc.
@@ -80,6 +80,10 @@ files:
 - TODO.perf/09-adoption-lift-fast-path.md
 - TODO.perf/10-bulk-attribute-materialization.md
 - TODO.perf/11-moxml-gap-battery.md
+- TODO.perf/12-document-lifetime-in-c.md
+- TODO.perf/13-structural-memos.md
+- TODO.perf/14-insert-family-c-bound.md
+- TODO.perf/15-compiled-expression-cache.md
 - TODO.restructure/01-constraint-compliance-audit.md
 - TODO.restructure/02-deep-copy-seam.md
 - TODO.restructure/03-evaluation-context-seam.md