leptris 1.9.162.7-aarch64-linux → 1.9.162.9-aarch64-linux

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fd7bbeac883e66c231e399cd28012ab81f1b521f975d53cfd5bb6177325f7454
-  data.tar.gz: fc3b8e4f3a7ca3452dbf29fa1a82d6bf779f2cc50889dc7e9ae6019ded764609
+  metadata.gz: 930a88268698162d62816a60f82f19f5258cb5fd14f2b89106e234823d0a5363
+  data.tar.gz: eae4cad381d8792f156210a068c504569b9005963279742d95d842b6750be5ab
 SHA512:
-  metadata.gz: b900b46f8b64857907a949865f26b82835c3e2fd75641673ff2de1c44b3d7e7c7ae97c42c8f89382f87abb9a72d8a46dd5b7258d171e0a2b38964fc26b59e706
-  data.tar.gz: 30c3600e9a9e0595cc2d1f9b2a1c01379ab532bce6818cc869c7ff06e13190e0bf4963afbba7b217ba24625073eab808b1a7bcf692517aa882b627823f72c4d0
+  metadata.gz: edab3b443d0e7ea7ecf664e23f149c49136f1f6c33244712eadc9254685d0143dcb5d9bcf574f0d7ca61d900fef9c7665a81fe13216bd565d6b3ab9338491733
+  data.tar.gz: '012368af4478e4cd8d3d8ba0b5f3789adf5c12c3adf21d939d1c7d87759e74b4c5cd4a475280a64e027f9556f498a4aa1069480352a920677031fae97f0bcfb4'

data/CHANGELOG.md

@@ -5,6 +5,43 @@ 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.162.9] - 2026-09-14
+
+### Performance
+
+- **TODO.perf/01 — ext-accelerated default reads**: with the
+  native layer loaded, the DEFAULT binding classes' hot reads
+  (`Element#name`, `#content`, `#prefix`, `#[]`'s engine lookups)
+  call the ext directly (one C-API dispatch + UTF-8 string build —
+  no FFI marshaling): name 276->84ns, attribute 373->199ns per
+  read. Warm loops are memo-served and unaffected; the win lands
+  on cold one-shot passes (fresh doc, single read per node):
+  13-25% on the #187 workload shape. Scope-owned (iterparse)
+  elements stay on the FFI path (pool addresses recycle).
+- **TODO.perf/02 — auto-enable**: `require "leptris"` quietly
+  activates the native acceleration when the compiled bundle is
+  present (platform gems). Falls back to pure FFI when absent
+  (ruby-variant on TruffleRuby/JRuby). `LEPTRIS_NO_NATIVE=1`
+  forces the FFI path. The explicit `native_layer` require remains
+  the parallel-API entry for NativeNode builders.
+
+## [1.9.162.8] - 2026-09-14
+
+### Added
+
+- **Zero-setup TruffleRuby/JRuby (#160)**: the `ruby`-platform gem
+  now vendors `libleptris` + `libutf8proc` for arm64/x86_64-darwin
+  and x86_64/aarch64-linux (plus musl fallbacks) under
+  `lib/leptris/vendor/<platform>/`; `FFI.libleptris_candidates`
+  probes them first at require time. Both engines activate and
+  load with no system library and no env vars — the release
+  assembly gathers the binaries from every platform build leg.
+  MRI behavior is unchanged (platform gems resolve first); a
+  forced `--platform ruby` MRI install also works via the vendor
+  tree. Fixed a split-library hazard along the way: the native
+  read layer now resolves the exact image the FFI layer loads
+  (two differently-pathed copies split per-document state).
+
 ## [1.9.162.7] - 2026-09-14
 
 ### Added

data/README.adoc

@@ -60,20 +60,21 @@ export LEPTRIS_LIB_PATH=/usr/local/lib/libleptris.dylib
 If Leptris can't find the library at startup, every `parse` call raises
 `LoadError`.
 
-=== Alternative engines: TruffleRuby and JRuby (#160)
+=== Alternative engines: TruffleRuby and JRuby (#160) — zero setup
 
-The gem ships a plain `ruby`-platform variant alongside the precompiled
-platform gems, so Bundler activates `leptris` on TruffleRuby and JRuby
-(the binding is FFI-based — no MRI C extension anywhere). Those engines
-filter out precompiled platform gems at activation and always resolve
-the `ruby` variant, which does not vendor the native library:
+The `ruby`-platform variant (what TruffleRuby and JRuby resolve)
+vendors precompiled `libleptris` + `libutf8proc` binaries for the
+common engine platforms under `lib/leptris/vendor/`:
 
-1. Install `libleptris` on the host — build from source (above) or set
-   `LEPTRIS_LIB_PATH=/path/to/libleptris.{so,dylib}`.
-2. `gem install leptris` (or `bundle install`) — activation succeeds
-   like on MRI, and FFI loads the system library at require time.
+- `arm64-darwin`, `x86_64-darwin`
+- `x86_64-linux`, `aarch64-linux` (glibc; the musl variants are
+  tried as fallback for Alpine hosts)
 
-The startup `LoadError` names this remedy when the library is missing.
+`gem install leptris` just works on both engines — the FFI layer
+selects the matching vendored binary at require time (the binding
+is FFI-based; no MRI C extension anywhere). `LEPTRIS_LIB_PATH`
+still overrides, and a system library remains the fallback for
+OSes the variant does not carry.
 
 == Parsing
 

data/Rakefile

@@ -189,9 +189,15 @@ task "gem:native:any" do
   sh "rake platform:any gem"
 end
 
-desc "Define the gem task to build the pure-Ruby gem"
+desc "Define the gem task to build the ruby-platform gem"
 task "platform:any" do
   spec = Gem::Specification::load("leptris.gemspec").dup
+  # Zero-setup TruffleRuby/JRuby (#160): per-OS binaries staged
+  # under lib/leptris/vendor/<platform>/ by the release assembly
+  # (or by hand: cp from each platform build). Absent on a plain
+  # checkout — the variant then carries no binaries and the
+  # system-library / LEPTRIS_LIB_PATH path applies as before.
+  spec.files += Dir.glob("lib/leptris/vendor/**/*")
   task = Gem::PackageTask.new(spec)
   task.define
 end

data/TODO.perf/01-ext-accelerated-default-reads.md

@@ -0,0 +1,25 @@
+# 01 — Ext-accelerated default reads (no FFI marshaling on hot paths)
+
+Status: SHIPPED (1.9.162.9) — name/content/prefix/[]-cold-path ride
+the ext when the bundle is loaded. Per-read 276->84ns (3.3x,
+pre-address) / attr 373->199ns. HONEST GATE FINDING: warm loops
+cannot see it (memos serve after first touch) — the gate is the
+COLD one-shot pass (fresh doc, one read per node): 13-25% on the
+#187 shape. UTF-8 encoding via rb_utf8_str_new_cstr (suite specs
+run both paths in one process: native_layer_spec sets the flag
+mid-suite). Remaining: children bulk for binding classes.
+
+The default binding's hot reads each pay FFI per-call marshaling
+(:string returns allocate through FFI, args marshal through the
+boundary — ~200-500ns vs ~50ns for a direct ext call). The native
+bundle already dlsyms every reader; add address-based C functions
+the DEFAULT binding classes call when the bundle is loaded:
+
+- Element#name / #content / #[]
+- Node#children / #element_children (bulk: one C pass allocating
+  binding wrappers — the bulk_wrap shape, 1.27-1.30x measured)
+- Element#expanded_name (three out-params today)
+
+Gate: suite green with AND without the bundle; drift-record rows
+(attr reads 1.88x, text 6.18x) must improve; cold-walk gate must
+not regress (cold-walk-regression-gate memory).

data/TODO.perf/02-auto-enable-native-layer.md

@@ -0,0 +1,19 @@
+# 02 — Auto-enable the native layer when the bundle is present
+
+Status: SHIPPED (1.9.162.9) — require "leptris" quietly
+probes for the native bundle and activates when present.
+LEPTRIS_NO_NATIVE=1 forces the FFI path (suite exercises both).
+The explicit native_layer require remains the parallel-API entry
+for NativeNode builders.
+
+Today `require "leptris/xml/native_layer"` is opt-in. End-state:
+`require "leptris"` quietly probes for the vendored native.bundle
+and, when present, activates the acceleration (01 makes the
+default classes benefit). Silent fallback to FFI when absent
+(ruby-variant on TruffleRuby/JRuby, custom builds). The explicit
+native_layer require remains the parallel-API entry
+(NativeNode builders).
+
+Requires: 01 (so auto-enable accelerates the DEFAULT API, not a
+parallel one), and a divergence test — same specs pass in both
+modes (the suite already runs both; make it explicit).

data/TODO.perf/03-bulk-xpath-result-materialization.md

@@ -0,0 +1,13 @@
+# 03 — Bulk XPath result materialization
+
+Status: TODO
+
+NodeSet#fetch materializes results per node (wrap per item +
+ResultText/ResultAttr captures). The #185 profile counted
+NodeSet#initialize at 2.8% and Class#new 11.7% of walk wall —
+result materialization shares that class of cost. Batch via the
+ext: one C pass over leptris_xpath_result_get_node(i) building
+the Ruby array with kinds, capturing text values in C.
+
+Gate: xpath-heavy specs unchanged; xpath row (28,878 ips small)
+improves on the battery.

data/TODO.perf/04-ext-bound-serialization.md

@@ -0,0 +1,11 @@
+# 04 — Serialization buffer cycle in C
+
+Status: TODO
+
+FFI.serialize_into_string does the two-call sized protocol
+(needed probe, then copy) with Ruby-side buffer management per
+to_xml call. Bind the cycle in the ext: one C function taking the
+ffi_function pointer + node address, returning a Ruby String.
+
+Gate: serialize row (3.24x baseline) improves; c14n specs
+byte-identical.

data/TODO.perf/05-native-surface-completion.md

@@ -0,0 +1,12 @@
+# 05 — Complete the NativeNode read surface
+
+Status: TODO
+
+Missing on NativeNode vs Element: #attributes (bulk attr hash),
+#attribute_nodes, #namespaces / #prefix, #line / #byte_offset,
+#inner_html / #to_xml (delegate to binding serialization), write
+faces beyond add_child (set_attribute, set_text, remove). Reads
+first; writes stay FFI (cold) unless measured otherwise.
+
+Gate: native_layer specs mirror the binding feature specs;
+descriptor_walk parity where applicable.

data/TODO.perf/06-perf-battery-native-legs.md

@@ -0,0 +1,10 @@
+# 06 — Native-layer legs in the perf battery + drift record
+
+Status: TODO
+
+benchmark/ gains native-layer legs (walk/build/attr rows via
+NativeNode beside the binding rows) so the drift record tracks
+both surfaces; TODO.restructure/17's record gains a native table.
+
+Gate: one command (rake benchmark:all or the two scripts) emits
+both tables; load-gated per the shared-machine discipline.

data/ext/leptris/native/native.c

@@ -21,6 +21,7 @@ typedef int (*children_ex_fn)(void *, void **, int *, int);
 typedef int (*node_type_fn)(void *);
 typedef void *(*next_sibling_fn)(void *);
 typedef void *(*parent_fn)(void *);
+typedef const char *(*elem_prefix_fn)(void *);
 typedef const char *(*element_text_fn)(void *);
 typedef void *(*doc_create_fn)(void);
 typedef void *(*elem_create_fn)(void *, const char *);
@@ -37,6 +38,7 @@ static children_ex_fn f_children_ex;
 static node_type_fn f_node_type;
 static next_sibling_fn f_next_sibling;
 static parent_fn f_parent;
+static elem_prefix_fn f_elem_prefix;
 static element_text_fn f_element_text;
 static doc_create_fn f_doc_create;
 static elem_create_fn f_elem_create;
@@ -94,6 +96,7 @@ static void resolve_symbols(const char *lib_path)
     f_node_type = (node_type_fn)lib_sym(h, "leptris_node_get_type");
     f_next_sibling = (next_sibling_fn)lib_sym(h, "leptris_node_next_sibling");
     f_parent = (parent_fn)lib_sym(h, "leptris_node_parent");
+    f_elem_prefix = (elem_prefix_fn)lib_sym(h, "leptris_element_prefix");
     f_element_text = (element_text_fn)lib_sym(h, "leptris_element_text");
     f_doc_create = (doc_create_fn)lib_sym(h, "leptris_document_create");
     f_elem_create = (elem_create_fn)lib_sym(h, "leptris_element_create");
@@ -105,7 +108,8 @@ static void resolve_symbols(const char *lib_path)
     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_root || !f_doc_free)
+        !f_create_child || !f_append_child || !f_set_root || !f_doc_free ||
+        !f_elem_prefix)
         rb_raise(rb_eRuntimeError, "libleptris symbols missing");
 }
 
@@ -115,7 +119,7 @@ static VALUE nn_name(VALUE self)
     const char *s;
     TypedData_Get_Struct(self, struct native_node, &nn_type, n);
     s = f_elem_name(n->ptr);
-    return s ? rb_str_new_cstr(s) : Qnil;
+    return s ? rb_utf8_str_new_cstr(s) : Qnil;
 }
 
 static VALUE nn_content(VALUE self)
@@ -127,7 +131,7 @@ static VALUE nn_content(VALUE self)
      * nodes carry it directly. */
     s = f_node_type(n->ptr) == 0 ? f_element_text(n->ptr)
                                  : f_text_content(n->ptr);
-    return s ? rb_str_new_cstr(s) : Qnil;
+    return s ? rb_utf8_str_new_cstr(s) : Qnil;
 }
 
 static VALUE nn_attribute(VALUE self, VALUE name)
@@ -136,7 +140,7 @@ static VALUE nn_attribute(VALUE self, VALUE name)
     const char *s;
     TypedData_Get_Struct(self, struct native_node, &nn_type, n);
     s = f_attr(n->ptr, StringValueCStr(name));
-    return s ? rb_str_new_cstr(s) : Qnil;
+    return s ? rb_utf8_str_new_cstr(s) : Qnil;
 }
 
 static VALUE nn_allocate(VALUE klass)
@@ -355,6 +359,43 @@ static VALUE nn_address(VALUE self)
     return ULL2NUM((uint64_t)(uintptr_t)n->ptr);
 }
 
+/* ---- 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
+ * marshaling. Addresses come from FFI::Pointer#address (a Ruby
+ * ivar read on the ffi gem's Pointer). */
+static VALUE nf_name(VALUE self, VALUE addr)
+{
+    const char *s;
+    (void)self;
+    s = f_elem_name((void *)(uintptr_t)NUM2ULL(addr));
+    return s ? rb_utf8_str_new_cstr(s) : Qnil;
+}
+
+static VALUE nf_element_text(VALUE self, VALUE addr)
+{
+    const char *s;
+    (void)self;
+    s = f_element_text((void *)(uintptr_t)NUM2ULL(addr));
+    return s ? rb_utf8_str_new_cstr(s) : Qnil;
+}
+
+static VALUE nf_attribute(VALUE self, VALUE addr, VALUE name)
+{
+    const char *s;
+    (void)self;
+    s = f_attr((void *)(uintptr_t)NUM2ULL(addr), StringValueCStr(name));
+    return s ? rb_utf8_str_new_cstr(s) : Qnil;
+}
+
+static VALUE nf_prefix(VALUE self, VALUE addr)
+{
+    const char *s;
+    (void)self;
+    s = f_elem_prefix((void *)(uintptr_t)NUM2ULL(addr));
+    return (s && *s) ? rb_utf8_str_new_cstr(s) : Qnil;
+}
+
 static VALUE nn_from(VALUE klass, VALUE document, VALUE element)
 {
     /* Element address comes through the binding's #c_ptr address;
@@ -383,7 +424,7 @@ static VALUE leptris_native_resolve_rb(VALUE self, VALUE lib_path)
 
 void Init_native(void)
 {
-    VALUE m_leptris, m_xml;
+    VALUE m_leptris, m_xml, m_native;
 
     m_leptris = rb_define_module("Leptris");
     m_xml = rb_define_module_under(m_leptris, "XML");
@@ -411,4 +452,10 @@ void Init_native(void)
     rb_define_method(c_native_node, "node_type", nn_type_sym, 0);
     rb_define_singleton_method(c_native_node, "resolve!",
                                leptris_native_resolve_rb, 1);
+
+    m_native = rb_define_module_under(m_xml, "Native");
+    rb_define_module_function(m_native, "fast_name", nf_name, 1);
+    rb_define_module_function(m_native, "fast_element_text", nf_element_text, 1);
+    rb_define_module_function(m_native, "fast_attribute", nf_attribute, 2);
+    rb_define_module_function(m_native, "fast_prefix", nf_prefix, 1);
 }

data/lib/leptris/version.rb

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

data/lib/leptris/xml/element.rb

@@ -1,10 +1,25 @@
 # frozen_string_literal: true
 
 class Leptris::XML::Element < Leptris::XML::Node
+  # TODO.perf/01: with the native bundle loaded, hot reads go
+  # through the ext (one C-API dispatch + rb_str_new_cstr — no FFI
+  # marshaling; ~3x per read). defined? is near-free when absent.
+  # Scope-owned (iterparse-yield) elements stay on the FFI path:
+  # their pool addresses recycle across yields and their lifetime
+  # rules ride the IterationScope seam — the ext fast path is for
+  # document-owned trees.
+  def native_fast?
+    defined?(Leptris::XML::NATIVE_FAST) && !scope_owned?
+  end
+
   def name
     return @name if @name
     ensure_alive!
-    @name = Leptris::XML::FFI.leptris_element_name(@c_ptr)
+    @name = if native_fast?
+              Leptris::XML::Native.fast_name(@c_ptr.address)
+            else
+              Leptris::XML::FFI.leptris_element_name(@c_ptr)
+            end
   end
   alias_method :node_name, :name
 
@@ -19,7 +34,11 @@ class Leptris::XML::Element < Leptris::XML::Node
   def content
     return @content if memo_hit?(@content_version)
     ensure_alive!
-    result = Leptris::XML::FFI.leptris_element_text(@c_ptr)
+    result = if native_fast?
+               Leptris::XML::Native.fast_element_text(@c_ptr.address)
+             else
+               Leptris::XML::FFI.leptris_element_text(@c_ptr)
+             end
     if @document
       @content = result
       @content_version = @document.version
@@ -60,7 +79,11 @@ class Leptris::XML::Element < Leptris::XML::Node
         # engine call resolves it, then the name is cached.
         return v if !v.nil? || @attributes
         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
         values[name] = v
         return v
       end
@@ -203,7 +226,12 @@ class Leptris::XML::Element < Leptris::XML::Node
   # or nil when the element has none.
   def prefix
     ensure_alive!
-    Leptris::XML::FFI.leptris_element_prefix(@c_ptr)
+    if native_fast?
+      Leptris::XML::Native.fast_prefix(@c_ptr.address)
+    else
+      result = Leptris::XML::FFI.leptris_element_prefix(@c_ptr)
+      result if result && !result.empty?
+    end
   end
 
   # The written qualified name — "foo:child" with a prefix, the

data/lib/leptris/xml/ffi.rb

@@ -7,6 +7,50 @@ module Leptris
     module FFI
       extend ::FFI::Library
 
+      # The per-OS vendor directory of the ruby-platform gem
+      # (zero-setup TruffleRuby/JRuby, #160): binaries for the
+      # common engines' OSes under lib/leptris/vendor/<platform>/.
+      # Returns [] in platform gems (no vendor tree) and on
+      # OSes the variant does not carry.
+      # Dir-name candidates for a RUBY_PLATFORM string, in
+      # preference order (glibc before musl — dlopen falls through
+      # on musl hosts).
+      def self.vendor_platforms_for(ruby_platform)
+        case ruby_platform
+        when /arm64.*darwin|aarch64.*darwin/ then %w[arm64-darwin]
+        when /x86_64.*darwin/ then %w[x86_64-darwin]
+        when /aarch64.*linux/ then %w[aarch64-linux aarch64-linux-musl]
+        when /x86_64.*linux/ then %w[x86_64-linux x86_64-linux-musl]
+        else []
+        end
+      end
+
+      def self.vendor_dirs
+        vendor_platforms_for(RUBY_PLATFORM)
+          .map { |d| File.expand_path("../../leptris/vendor/#{d}", __dir__) }
+          .select { |dir| File.directory?(dir) }
+      end
+
+      # THE libleptris candidate list, in order — shared with the
+      # native read layer's resolve!. Single source of truth is
+      # load-bearing: two differently-pathed copies of the library
+      # load as two images with split per-document state.
+      def self.libleptris_candidates
+        [
+          ENV["LEPTRIS_LIB_PATH"],
+          *vendor_dirs.flat_map { |d|
+            %w[libleptris.dylib libleptris.so libleptris.dll]
+              .map { |n| File.join(d, n) }
+          },
+          File.expand_path("../../libleptris.dylib", __dir__),
+          File.expand_path("../../libleptris.so", __dir__),
+          File.expand_path("../../libleptris.dll", __dir__),
+          "/usr/local/lib/libleptris.dylib",
+          "/usr/local/lib/libleptris.so",
+          "leptris",
+        ].compact
+      end
+
       # libleptris links utf8proc via @rpath (TODO.restructure/20
       # — fn:normalize-unicode). dlopen the VENDORED utf8proc
       # FIRST: once its install name is loaded, dyld resolves
@@ -17,6 +61,10 @@ module Leptris
       # never consults it.
       begin
         ffi_lib [
+          *Leptris::XML::FFI.vendor_dirs.flat_map { |d|
+            %w[libutf8proc.3.dylib libutf8proc.so.3 libutf8proc.so
+               utf8proc.dll].map { |n| File.join(d, n) }
+          },
           File.expand_path("../../libutf8proc.3.dylib", __dir__),
           File.expand_path("../../libutf8proc.so.3", __dir__),
           File.expand_path("../../libutf8proc.so", __dir__),
@@ -29,15 +77,7 @@ module Leptris
       # Issue leptris-ruby#49: name the remedy when the library is
       # missing (ruby-platform gem without a vendored libleptris).
       begin
-        ffi_lib [
-          ENV["LEPTRIS_LIB_PATH"],
-          File.expand_path("../../libleptris.dylib", __dir__),
-          File.expand_path("../../libleptris.so", __dir__),
-          File.expand_path("../../libleptris.dll", __dir__),
-          "/usr/local/lib/libleptris.dylib",
-          "/usr/local/lib/libleptris.so",
-          "leptris",
-        ].compact
+        ffi_lib Leptris::XML::FFI.libleptris_candidates
       rescue LoadError => e
         raise LoadError, <<~MSG
           leptris: cannot load the vendored libleptris library.

data/lib/leptris/xml/native_layer.rb

@@ -29,29 +29,30 @@ rescue LoadError => e
 end
 
 module Leptris::XML::Native
-  LIB_CANDIDATES = [
-    ENV["LEPTRIS_LIB_PATH"],
-    File.expand_path("../../libleptris.dylib", __dir__),
-    File.expand_path("../../libleptris.so", __dir__),
-    File.expand_path("../../libleptris.dll", __dir__),
-    "libleptris",
-  ].compact.freeze
+  # FFI.libleptris_candidates is the single source of truth — the
+  # native layer MUST dlsym the exact image the FFI layer loaded,
+  # or two library instances split per-document state.
+  def self.lib_candidates
+    Leptris::XML::FFI.libleptris_candidates
+  end
 end
 
-candidates = Leptris::XML::Native::LIB_CANDIDATES
+# TODO.perf/01: accelerate the DEFAULT binding classes while the
+# bundle is loaded (name/content/prefix/[] hot reads).
+Leptris::XML::NATIVE_FAST = true
+
+candidates = Leptris::XML::Native.lib_candidates
 resolved = candidates.any? do |path|
-  resolved = Leptris::XML::Native::LIB_CANDIDATES.any? do |path|
-    begin
-      Leptris::XML::NativeNode.resolve!(path)
-      true
-    rescue RuntimeError
-      false
-    end
+  begin
+    Leptris::XML::NativeNode.resolve!(path)
+    true
+  rescue RuntimeError
+    false
   end
-  raise LoadError,
-    "leptris: native layer loaded but libleptris could not be " \
-    "resolved from #{candidates.inspect}" unless resolved
 end
+raise LoadError,
+  "leptris: native layer loaded but libleptris could not be " \
+  "resolved from #{candidates.inspect}" unless resolved
 
 class Leptris::XML::Document
   # Separate identity cache for NativeNodes so binding Node.wrap

data/lib/leptris.rb

@@ -31,3 +31,18 @@ rescue LoadError => e
     (Underlying error: #{e.message})
   MSG
 end
+
+# TODO.perf/02: auto-enable the native acceleration layer when the
+# compiled bundle is present (platform gems). Quietly falls back
+# to pure FFI when absent (ruby-variant on TruffleRuby/JRuby,
+# custom builds). LEPTRIS_NO_NATIVE=1 forces the FFI path (the
+# suite uses it to exercise both surfaces). The explicit
+# `require "leptris/xml/native_layer"` remains the parallel-API
+# entry for NativeNode builders.
+unless ENV["LEPTRIS_NO_NATIVE"] == "1"
+  begin
+    require "leptris/xml/native_layer"
+  rescue LoadError
+    nil
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: leptris
 version: !ruby/object:Gem::Version
-  version: 1.9.162.7
+  version: 1.9.162.9
 platform: aarch64-linux
 authors:
 - Ribose Inc.
@@ -69,6 +69,12 @@ files:
 - LICENSE.md
 - README.adoc
 - Rakefile
+- TODO.perf/01-ext-accelerated-default-reads.md
+- TODO.perf/02-auto-enable-native-layer.md
+- TODO.perf/03-bulk-xpath-result-materialization.md
+- TODO.perf/04-ext-bound-serialization.md
+- TODO.perf/05-native-surface-completion.md
+- TODO.perf/06-perf-battery-native-legs.md
 - TODO.restructure/01-constraint-compliance-audit.md
 - TODO.restructure/02-deep-copy-seam.md
 - TODO.restructure/03-evaluation-context-seam.md