leptris 1.9.197.2-arm-linux

data/lib/leptris/xml/ffi.rb

@@ -0,0 +1,1527 @@
+# frozen_string_literal: true
+
+require "ffi"
+
+module Leptris
+  module XML
+    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]
+        # 32-bit ARM (armv[567l]: "arm-linux", "armv7l-linux",
+        # "armeb-linux", ...). Never matches aarch64 ("aarch" has
+        # no "arm" substring).
+        when /arm.*linux/ then %w[arm-linux arm-linux-musl]
+        # POWER8+ little-endian and IBM Z (qemu-built platform gems)
+        when /ppc64le.*linux/ then %w[ppc64le-linux]
+        when /s390x.*linux/ then %w[s390x-linux s390x-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
+      # libleptris's dependent image from this image instead of
+      # searching system paths. Absent (pure-ruby fallback gem,
+      # UTF8PROC-less custom builds) is not an error — the loader
+      # tries and moves on, and libleptris without the dependency
+      # 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__),
+          File.expand_path("../../utf8proc.dll", __dir__),
+        ].compact
+      rescue LoadError
+        nil
+      end
+
+      # Issue leptris-ruby#49: name the remedy when the library is
+      # missing (ruby-platform gem without a vendored libleptris).
+      begin
+        ffi_lib Leptris::XML::FFI.libleptris_candidates
+      rescue LoadError => e
+        raise LoadError, <<~MSG
+          leptris: cannot load the vendored libleptris library.
+          You may have installed the ruby-platform variant of this
+          gem (#{Gem.loaded_specs["leptris"]&.full_name rescue "unknown"}),
+          which does not vendor the native library. Fix:
+
+            bundle update leptris        # force platform gems
+            # or: gem install leptris --platform ruby is unsupported
+            # or: set LEPTRIS_LIB_PATH=/path/to/libleptris.so
+
+          Original error: #{e.message}
+        MSG
+      end
+
+      typedef :pointer, :leptris_document
+      typedef :pointer, :leptris_element
+      typedef :pointer, :leptris_node_ref
+      typedef :pointer, :leptris_attribute
+      typedef :pointer, :leptris_doctype
+      typedef :pointer, :leptris_xpath_result
+      typedef :pointer, :leptris_xpath_ns_set
+      typedef :pointer, :leptris_xpath_compiled
+      typedef :pointer, :leptris_relaxng
+      typedef :pointer, :leptris_xslt
+      typedef :pointer, :leptris_xquery
+      typedef :pointer, :leptris_schematron
+      typedef :pointer, :leptris_diff
+      typedef :pointer, :leptris_plan
+      typedef :pointer, :leptris_plan_result
+      typedef :pointer, :leptris_sax_recorder
+      typedef :pointer, :leptris_pull_parser
+      typedef :pointer, :leptris_iterparse
+      typedef :pointer, :leptris_xpath_var_set
+      typedef :pointer, :leptris_sax_parser
+      typedef :int, :leptris_status
+
+      class SAXHandler < ::FFI::Struct
+        layout \
+          :start_document, :pointer,
+          :end_document, :pointer,
+          :start_element, :pointer,
+          :end_element, :pointer,
+          :characters, :pointer,
+          :comment, :pointer,
+          :cdata, :pointer,
+          :processing_instruction, :pointer,
+          :start_prefix_mapping, :pointer,
+          :end_prefix_mapping, :pointer,
+          :error, :pointer
+      end
+
+      class SerializeOptions < ::FFI::Struct
+        layout \
+          :indent, :int,
+          :xml_declaration, :int,
+          :encoding, :pointer
+      end
+
+      # LeptrisSerializeExtOptions (1.9.9 #129 display form; 1.9.22
+      # #633/#109 indent unit): knobs beyond the ABI-frozen options
+      # struct. MAY grow — always pass its size through the sized
+      # entry.
+      class SerializeExtStruct < ::FFI::Struct
+        layout :indent_text, :int,
+               :indent_unit, :pointer,
+               :expand_empty, :int
+      end
+
+      # Mirrors LeptrisParseOptions (libleptris >= 1.9.0 carries the
+      # recover field; earlier fields unchanged since v1.6.0).
+      class ParseOptionsStruct < ::FFI::Struct
+        layout \
+          :flags, :int,
+          :strict_mode, :int,
+          :max_depth, :int,
+          :recover, :int
+      end
+
+      # LeptrisSaxEventRecord (types.h, issue #585): fixed layout the
+      # header explicitly freezes for FFI mirrors. Strings are NOT
+      # inline — name/text/attrs slice the recorder's arena.
+      class SaxEventRecord < ::FFI::Struct
+        layout :kind, :uint8,
+               :reserved, [:uint8, 7],
+               :name_off, :uint32, :name_len, :uint32,
+               :text_off, :uint32, :text_len, :uint32,
+               :attrs_off, :uint32, :attr_count, :uint32,
+               :line, :uint32, :column, :uint32
+      end
+
+      SAX_EVENT_START_DOCUMENT = 0
+      SAX_EVENT_END_DOCUMENT   = 1
+      SAX_EVENT_START_ELEMENT  = 2
+      SAX_EVENT_END_ELEMENT    = 3
+      SAX_EVENT_CHARACTERS     = 4
+      SAX_EVENT_COMMENT        = 5
+      SAX_EVENT_CDATA          = 6
+      SAX_EVENT_PI             = 7
+      SAX_EVENT_START_PREFIX   = 8
+      SAX_EVENT_END_PREFIX     = 9
+      SAX_EVENT_ERROR          = 10
+
+      ITERPARSE_TOP_LEVEL      = 0
+      ITERPARSE_FULL_DOCUMENT  = 1
+
+      # struct LeptrisPullEvent (leptris/sax.h): FFI::Struct derives
+      # the field offsets from the layout, so ABI changes are a
+      # one-line edit here instead of silent offset drift in callers.
+      class PullEventStruct < ::FFI::Struct
+        layout \
+          :type, :int,
+          :name, :pointer,
+          :text, :pointer,
+          :text_len, :size_t
+      end
+
+      # Tree-shaped schema-descriptor materialization (1.9.162,
+      # upstream #1039): hosts compile a plan tree once, then
+      # leptris_plan_walk materializes a whole subtree in one
+      # native pass. The plan/result structs mirror descriptor.h
+      # — POD, ABI-frozen at v1 (leptris_plan_abi_version).
+      class AttrPlan < ::FFI::Struct
+        layout :wire_name, :pointer,
+               :kind, :uint8,
+               :type_tag, :uint8
+      end
+      class ChildPlan < ::FFI::Struct
+        layout :wire_name, :pointer,
+               :kind, :uint8,
+               :type_tag, :uint8,
+               :child_plan_index, :int32,
+               # libleptris 1.9.178 (#1114/#1115): rule-level ns
+               # forms on ChildPlan (additive to the frozen v1 ABI).
+               :ns_form, :uint8,
+               :pad0, :uint8,
+               :ns_uri, :pointer
+      end
+      class ElementPlan < ::FFI::Struct
+        layout :element_name, :pointer,
+               :ns_form, :uint8,
+               :pad0, :uint8,
+               :ns_uri, :pointer,
+               :attribute_count, :uint32,
+               :child_count, :uint32,
+               :attribute_plans, :pointer,
+               :child_plans, :pointer,
+               :flags, :uint16,
+               :pad1, :uint16
+      end
+      class PlanSpec < ::FFI::Struct
+        layout :abi_version, :uint32,
+               :plan_count, :uint32,
+               :plans, :pointer
+      end
+
+      PLAN_ABI_VERSION = 1
+
+      PLAN_KIND_SCALAR = 1
+      PLAN_KIND_COLLECTION = 2
+      PLAN_KIND_NESTED = 3
+      PLAN_KIND_RAW = 4
+      PLAN_KIND_CONTENT = 5
+      PLAN_KIND_CALLBACK = 6
+
+      PLAN_FLAG_MIXED_CONTENT = 0x1
+      PLAN_FLAG_ORDERED = 0x2
+      PLAN_FLAG_CDATA = 0x4
+      PLAN_FLAG_NS_LENIENT = 0x8
+
+      PLAN_NS_NONE = 0
+      PLAN_NS_EXACT = 1
+      PLAN_NS_ANY = 2
+
+      PLAN_VALUE_ELEMENT = 0
+      PLAN_VALUE_SCALAR = 1
+      PLAN_VALUE_COLLECTION = 2
+      PLAN_VALUE_RAW = 3
+      PLAN_VALUE_CALLBACK = 4
+
+      # Byte offset of parse-created nodes (1.9.162, #1039): the
+      # position descriptor CALLBACK rows echo; 0 when unknown.
+      attach_function :leptris_node_byte_offset,
+        [:leptris_node_ref], :size_t
+
+      attach_function :leptris_plan_abi_version, [], :uint32
+      attach_function :leptris_plan_build,
+        [:pointer, :pointer], :leptris_plan
+      attach_function :leptris_plan_free, [:leptris_plan], :void
+      attach_function :leptris_plan_walk,
+        [:leptris_document, :leptris_element, :leptris_plan, :pointer],
+        :leptris_plan_result
+      attach_function :leptris_plan_result_free,
+        [:leptris_plan_result], :void
+      attach_function :leptris_plan_value_kind,
+        [:leptris_plan_result], :int
+      attach_function :leptris_plan_value_name,
+        [:leptris_plan_result], :string
+      attach_function :leptris_plan_value_type_tag,
+        [:leptris_plan_result], :uint8
+      attach_function :leptris_plan_value_string,
+        [:leptris_plan_result], :string
+      attach_function :leptris_plan_value_length,
+        [:leptris_plan_result], :size_t
+      attach_function :leptris_plan_value_position,
+        [:leptris_plan_result], :size_t
+      attach_function :leptris_plan_value_count,
+        [:leptris_plan_result], :size_t
+      attach_function :leptris_plan_value_at,
+        [:leptris_plan_result, :size_t], :leptris_plan_result
+      attach_function :leptris_plan_value_attribute,
+        [:leptris_plan_result, :string], :string
+
+      attach_function :leptris_version, [], :string
+      attach_function :leptris_version_components, [:pointer, :pointer, :pointer], :void
+
+            # Tolerant HTML4/5 parse into the STANDARD DOM (libleptris
+      # 1.9.75, #659): implied end tags, void elements, raw-text
+      # script/style, case-insensitive (lowercased) names, the HTML
+      # named-entity table. Document shape — html/head/body
+      # synthesized; no implied tbody. Malformed input never fails
+      # the parse; only an entirely empty result is an error.
+      attach_function :leptris_parse_html_string,
+        [:string, :size_t, :pointer], :leptris_document
+      # HTML4/libxml2-compatibility mode (1.9.104, #659): the same
+      # tolerant tokenizer and Nokogiri document shape, except
+      # leading script/style stay in <body> (libxml2's shape —
+      # title/meta/link/base still lift). Bindings matching
+      # Nokogiri byte-for-byte pin this; _html_string is the
+      # WHATWG-conformant engine (implied-head full set, foster
+      # parenting from 1.9.105).
+      attach_function :leptris_parse_html4_string,
+        [:string, :size_t, :pointer], :leptris_document
+
+attach_function :leptris_parse_string,
+        [:string, :size_t, :pointer], :leptris_document
+      attach_function :leptris_parse_string_flags,
+        [:string, :size_t, :uint, :pointer], :leptris_document
+      attach_function :leptris_parse_string_inplace,
+        [:pointer, :size_t, :pointer], :leptris_document
+      attach_function :leptris_parse_string_with_encoding,
+        [:string, :size_t, :pointer], :leptris_document
+      attach_function :leptris_parse_file,
+        [:string, :pointer], :leptris_document
+      attach_function :leptris_load_file,
+        [:string, :pointer], :pointer
+      attach_function :leptris_document_free,
+        [:leptris_document], :void
+      attach_function :leptris_document_create,
+        [], :leptris_document
+      attach_function :leptris_document_set_root,
+        [:leptris_document, :leptris_element], :leptris_status
+      attach_function :leptris_document_root,
+        [:leptris_document], :leptris_element
+      # The document node — navigation head over the whole tree
+      # chain [prolog comments/PIs, root, epilog...] (libleptris
+      # 1.9.7, upstream #580; the libxml2 model).
+      attach_function :leptris_document_node,
+        [:leptris_document], :leptris_node_ref
+      # First node of the document child chain in one call — the
+      # prolog head (libleptris 1.9.174; document_node +
+      # node_first_child without the intermediate handle).
+      attach_function :leptris_document_first_child,
+        [:leptris_document], :leptris_node_ref
+      # Node-surface parity (libleptris 1.9.176, upstream #1094,
+      # leptris-ruby#212): entity references, the XML declaration,
+      # programmatic DOCTYPE, and document-PI identity/removal.
+      attach_function :leptris_entity_ref_node_create,
+        [:leptris_document, :string], :leptris_node_ref
+      attach_function :leptris_entity_ref_node_name,
+        [:leptris_node_ref], :string
+      attach_function :leptris_document_version,
+        [:leptris_document], :string
+      attach_function :leptris_document_standalone,
+        [:leptris_document], :int
+      attach_function :leptris_document_set_version,
+        [:leptris_document, :string], :leptris_status
+      attach_function :leptris_document_set_encoding,
+        [:leptris_document, :string], :leptris_status
+      attach_function :leptris_document_set_standalone,
+        [:leptris_document, :int], :leptris_status
+      attach_function :leptris_document_set_doctype,
+        [:leptris_document, :string, :string, :string], :leptris_doctype
+      attach_function :leptris_document_append_pi,
+        [:leptris_document, :string, :string], :leptris_node_ref
+      attach_function :leptris_document_remove_child,
+        [:leptris_document, :leptris_node_ref], :leptris_status
+      # Wrap-free subtree visitation (1.9.20, upstream #645a):
+      # enter/leave pairs for elements, depth from the walk's root,
+      # one C call — no NodeSet/Array churn per level. The document
+      # node walks the document child chain.
+      attach_function :leptris_node_visit,
+        [:leptris_node_ref, :pointer, :pointer], :void
+      # Document-level PIs (v1.6.0): not tree nodes — enumerate via
+      # these accessors only.
+      attach_function :leptris_document_pi_count,
+        [:leptris_document], :size_t
+      attach_function :leptris_document_pi_target,
+        [:leptris_document, :size_t], :string
+      attach_function :leptris_document_pi_data,
+        [:leptris_document, :size_t], :string
+      # Document-level PI removal by target or index (1.9.9, #612):
+      # unlinks from the child chain; the node is pool-owned and
+      # stays valid until document free.
+      attach_function :leptris_document_remove_pi,
+        [:leptris_document, :string, :size_t], :leptris_node_ref
+      attach_function :leptris_document_add_pi,
+        [:leptris_document, :string, :string], :pointer
+      # Document-level comment writer (libleptris 1.9.160, #1032):
+      # epilog append, the add_pi shape.
+      attach_function :leptris_document_add_comment,
+        [:leptris_document, :string], :leptris_node_ref
+      # Document-level comments (libleptris 1.9.3, #578): parsed
+      # <!-- ... --> outside the root, prolog then epilog, in
+      # document order. Read-only surface (no add_comment yet).
+      attach_function :leptris_document_comment_count,
+        [:leptris_document], :size_t
+      attach_function :leptris_document_comment_content,
+        [:leptris_document, :size_t], :string
+      # Options-struct parse (v1.6.0): supersedes the flags variants;
+      # the flags path remains bound for compatibility.
+      attach_function :leptris_parse_string_ex,
+        [:string, :size_t, :pointer, :pointer], :leptris_document
+      attach_function :leptris_document_encoding,
+        [:leptris_document], :string
+      attach_function :leptris_document_finalize_strings,
+        [:leptris_document], :int
+      attach_function :leptris_document_adopt_child,
+        [:leptris_document, :leptris_document], :void
+      attach_function :leptris_document_set_strict,
+        [:leptris_document, :int], :leptris_status
+      attach_function :leptris_document_get_strict,
+        [:leptris_document], :int
+      attach_function :leptris_document_freeze,
+        [:leptris_document], :leptris_status
+      attach_function :leptris_document_is_frozen,
+        [:leptris_document], :int
+      attach_function :leptris_set_strict_mode, [:int], :void
+      attach_function :leptris_get_strict_mode, [], :int
+      attach_function :leptris_set_max_depth, [:int], :void
+      attach_function :leptris_get_max_depth, [], :int
+      attach_function :leptris_xinclude_process,
+        [:leptris_document, :string], :leptris_status
+      attach_function :leptris_xinclude_is_include_element,
+        [:leptris_element], :int
+      attach_function :leptris_xinclude_is_fallback_element,
+        [:leptris_element], :int
+      attach_function :leptris_xinclude_get_href, [:leptris_element], :string
+      attach_function :leptris_xinclude_get_parse, [:leptris_element], :string
+      attach_function :leptris_xinclude_get_xpointer, [:leptris_element], :string
+      attach_function :leptris_xinclude_get_encoding, [:leptris_element], :string
+
+      attach_function :leptris_node_get_type,
+        [:leptris_node_ref], :int
+      attach_function :leptris_node_first_child,
+        [:leptris_node_ref], :leptris_node_ref
+      attach_function :leptris_node_last_child,
+        [:leptris_node_ref], :leptris_node_ref
+      attach_function :leptris_node_next_sibling,
+        [:leptris_node_ref], :leptris_node_ref
+      attach_function :leptris_node_previous_sibling,
+        [:leptris_node_ref], :leptris_node_ref
+      attach_function :leptris_node_child_count,
+        [:leptris_node_ref], :size_t
+      # libleptris 1.7.0: all-kind child batch — out_nodes=NULL is a
+      # count-only query returning the TOTAL across every child kind.
+      attach_function :leptris_node_children,
+        [:leptris_node_ref, :pointer, :size_t], :size_t
+      # Children with out_kinds (1.9.18, upstream #617): the kind
+      # rides the batch, so wrappers skip the per-child get_type.
+      attach_function :leptris_node_children_ex,
+        [:leptris_node_ref, :pointer, :pointer, :size_t], :size_t
+      # Element-only batch; mirror-only — fetch_children rides the
+      # all-kind node_children above.
+      # Raw qname-ordered attribute list INCLUDING xmlns
+      # declarations at their byte positions (1.9.18, upstream
+      # #635) — the streaming SAX contract's mixed view.
+      attach_function :leptris_element_attributes_raw,
+        [:leptris_element, :pointer, :pointer, :size_t], :size_t
+      attach_function :leptris_element_children,
+        [:leptris_element, :pointer, :size_t], :size_t
+      attach_function :leptris_node_as_element,
+        [:leptris_node_ref], :leptris_element
+      attach_function :leptris_element_as_node,
+        [:leptris_element], :leptris_node_ref
+      attach_function :leptris_node_get_binding_wrapper,
+        [:leptris_node_ref], :pointer
+      attach_function :leptris_node_set_binding_wrapper,
+        [:leptris_node_ref, :pointer], :void
+      attach_function :leptris_node_parent,
+        [:leptris_node_ref], :leptris_element
+      attach_function :leptris_node_unlink,
+        [:leptris_node_ref], :leptris_status
+      attach_function :leptris_node_line,
+        [:leptris_node_ref], :int
+      # Parser-recorded source position (libleptris 1.9.180,
+      # #1124): {line, col_start, col_end} — Jing's diagnostic
+      # convention (column after the start tag's '>' / the
+      # element's final '>').
+      class SourcePosition < ::FFI::Struct
+        layout :line, :int,
+               :col_start, :int,
+               :col_end, :int
+      end
+      attach_function :leptris_node_source_position,
+        [:leptris_node_ref, :pointer], :void
+      attach_function :leptris_node_compare,
+        [:leptris_node_ref, :leptris_node_ref], :int
+      attach_function :leptris_node_traverse,
+        [:leptris_node_ref, :int, :pointer, :pointer], :int
+
+      attach_function :leptris_text_node_get_content,
+        [:leptris_node_ref], :string
+      attach_function :leptris_comment_node_get_content,
+        [:leptris_node_ref], :string
+      attach_function :leptris_cdata_node_get_content,
+        [:leptris_node_ref], :string
+      attach_function :leptris_pi_node_get_target,
+        [:leptris_node_ref], :string
+      attach_function :leptris_pi_node_get_data,
+        [:leptris_node_ref], :string
+      attach_function :leptris_text_node_create,
+        [:leptris_document, :string], :leptris_node_ref
+      attach_function :leptris_comment_node_create,
+        [:leptris_document, :string], :leptris_node_ref
+      attach_function :leptris_cdata_node_create,
+        [:leptris_document, :string], :leptris_node_ref
+      attach_function :leptris_pi_node_create,
+        [:leptris_document, :string, :string], :leptris_node_ref
+      attach_function :leptris_text_node_set_content,
+        [:leptris_node_ref, :string], :leptris_status
+      attach_function :leptris_comment_node_set_content,
+        [:leptris_node_ref, :string], :leptris_status
+      attach_function :leptris_cdata_node_set_content,
+        [:leptris_node_ref, :string], :leptris_status
+      attach_function :leptris_pi_node_set_target,
+        [:leptris_node_ref, :string], :leptris_status
+      attach_function :leptris_pi_node_set_data,
+        [:leptris_node_ref, :string], :leptris_status
+
+      attach_function :leptris_element_name,
+        [:leptris_element], :string
+      attach_function :leptris_element_text,
+        [:leptris_element], :string
+      attach_function :leptris_element_text_int,
+        [:leptris_element, :int], :int
+      attach_function :leptris_element_text_uint,
+        [:leptris_element, :uint], :uint
+      attach_function :leptris_element_text_double,
+        [:leptris_element, :double], :double
+      attach_function :leptris_element_text_float,
+        [:leptris_element, :float], :float
+      attach_function :leptris_element_text_bool,
+        [:leptris_element, :int], :int
+      attach_function :leptris_element_attribute,
+        [:leptris_element, :string], :string
+      attach_function :leptris_element_attribute_string,
+        [:leptris_element, :string, :string], :string
+      attach_function :leptris_element_attribute_int,
+        [:leptris_element, :string, :int], :int
+      attach_function :leptris_element_attribute_uint,
+        [:leptris_element, :string, :uint], :uint
+      attach_function :leptris_element_attribute_double,
+        [:leptris_element, :string, :double], :double
+      attach_function :leptris_element_attribute_float,
+        [:leptris_element, :string, :float], :float
+      attach_function :leptris_element_attribute_bool,
+        [:leptris_element, :string, :int], :int
+      attach_function :leptris_element_has_attribute,
+        [:leptris_element, :string], :int
+      # libleptris 1.8.0: expanded-name lookup — (uri, local) with
+      # XML Namespaces 1.0 semantics; NULL/"" uri matches only
+      # no-namespace attributes, xmlns declarations never match.
+      attach_function :leptris_element_attribute_ns,
+        [:leptris_element, :string, :string], :string
+      attach_function :leptris_element_has_attribute_ns,
+        [:leptris_element, :string, :string], :int
+      # libleptris 1.8.0: per-attribute prefix (name-derived) and
+      # namespace URI (resolved through the owning element's
+      # in-scope declarations at read time).
+      attach_function :leptris_attribute_prefix,
+        [:leptris_attribute], :string
+      attach_function :leptris_attribute_namespace_uri,
+        [:leptris_attribute], :string
+      attach_function :leptris_element_first_attribute,
+        [:leptris_element], :leptris_attribute
+      attach_function :leptris_attribute_next,
+        [:leptris_attribute], :leptris_attribute
+      attach_function :leptris_attribute_get_name,
+        [:leptris_attribute], :string
+      attach_function :leptris_attribute_get_value,
+        [:leptris_element, :leptris_attribute], :string
+      attach_function :leptris_element_prefix,
+        [:leptris_element], :string
+      attach_function :leptris_element_attribute_count,
+        [:leptris_element], :size_t
+      attach_function :leptris_element_attribute_name_at,
+        [:leptris_element, :size_t], :string
+      attach_function :leptris_element_attribute_value_at,
+        [:leptris_element, :size_t], :string
+      attach_function :leptris_element_remove_all_attributes,
+        [:leptris_element], :leptris_status
+
+      attach_function :leptris_element_child_count,
+        [:leptris_element], :size_t
+      attach_function :leptris_element_child,
+        [:leptris_element, :size_t], :leptris_element
+      attach_function :leptris_element_parent,
+        [:leptris_element], :leptris_element
+      attach_function :leptris_element_root,
+        [:leptris_element], :leptris_element
+      attach_function :leptris_element_child_value,
+        [:leptris_element], :string
+      attach_function :leptris_element_hash_value,
+        [:leptris_element], :size_t
+      attach_function :leptris_element_find_child,
+        [:leptris_element, :string], :leptris_element
+      attach_function :leptris_element_find_child_by_attr,
+        [:leptris_element, :string, :string, :string], :leptris_element
+      attach_function :leptris_element_next_sibling,
+        [:leptris_element, :string], :leptris_element
+      attach_function :leptris_element_previous_sibling,
+        [:leptris_element, :string], :leptris_element
+      attach_function :leptris_element_first_child,
+        [:leptris_element, :string], :leptris_element
+      attach_function :leptris_element_last_child,
+        [:leptris_element, :string], :leptris_element
+      attach_function :leptris_element_first_child_any,
+        [:leptris_element], :leptris_element
+      attach_function :leptris_element_last_child_any,
+        [:leptris_element], :leptris_element
+      attach_function :leptris_element_next_sibling_any,
+        [:leptris_element], :leptris_element
+      attach_function :leptris_element_previous_sibling_any,
+        [:leptris_element], :leptris_element
+
+      attach_function :leptris_element_create,
+        [:leptris_document, :string], :leptris_element
+      attach_function :leptris_element_set_name,
+        [:leptris_element, :string], :leptris_status
+      attach_function :leptris_element_set_text,
+        [:leptris_element, :string], :leptris_status
+      attach_function :leptris_element_set_attribute,
+        [:leptris_element, :string, :string], :leptris_status
+      attach_function :leptris_element_set_attribute_bool,
+        [:leptris_element, :string, :int], :leptris_status
+      attach_function :leptris_element_set_attribute_double,
+        [:leptris_element, :string, :double], :leptris_status
+      attach_function :leptris_element_set_attribute_float,
+        [:leptris_element, :string, :float], :leptris_status
+      attach_function :leptris_element_set_attribute_int,
+        [:leptris_element, :string, :int], :leptris_status
+      attach_function :leptris_element_set_attribute_uint,
+        [:leptris_element, :string, :uint], :leptris_status
+      attach_function :leptris_element_remove_attribute,
+        [:leptris_element, :string], :leptris_status
+      attach_function :leptris_element_append_child,
+        [:leptris_element, :leptris_element], :leptris_status
+      # Fused create+append (libleptris 1.9.153): one document
+      # resolution, identical tree semantics to the two-call pair.
+      attach_function :leptris_element_create_child,
+        [:leptris_element, :string], :leptris_element
+      attach_function :leptris_element_prepend_child,
+        [:leptris_element, :leptris_element], :leptris_status
+      attach_function :leptris_element_insert_before,
+        [:leptris_element, :leptris_element], :leptris_status
+      attach_function :leptris_element_insert_after,
+        [:leptris_element, :leptris_element], :leptris_status
+      attach_function :leptris_element_remove_child,
+        [:leptris_element, :leptris_element], :leptris_status
+      attach_function :leptris_element_remove_children,
+        [:leptris_element], :leptris_status
+      attach_function :leptris_element_append_copy,
+        [:leptris_element, :leptris_element], :leptris_element
+      attach_function :leptris_element_prepend_copy,
+        [:leptris_element, :leptris_element], :leptris_element
+      attach_function :leptris_element_insert_copy_before,
+        [:leptris_element, :leptris_element], :leptris_element
+      attach_function :leptris_element_insert_copy_after,
+        [:leptris_element, :leptris_element], :leptris_element
+
+      attach_function :leptris_element_copy,
+        [:leptris_element, :leptris_document], :leptris_element
+      attach_function :leptris_document_copy,
+        [:leptris_document], :leptris_document
+      attach_function :leptris_node_get_xpath,
+        [:leptris_node_ref], :pointer
+      attach_function :leptris_parse_fragment,
+        [:string, :size_t, :leptris_document, :pointer], :leptris_element
+
+      # Nokogiri node.namespace= parity (libleptris 1.9.76, #817):
+      # NULL (or "") detaches — link + prefix clear, xmlns=""
+      # undeclaration added; a URI rebinds to an IN-SCOPE
+      # declaration carrying it (NOT_FOUND if there is none — this
+      # entry does not invent declarations).
+      attach_function :leptris_element_set_namespace,
+        [:leptris_element, :string], :leptris_status
+      attach_function :leptris_element_namespace,
+        [:leptris_element], :string
+      attach_function :leptris_element_namespace_for_prefix,
+        [:leptris_element, :string], :string
+      attach_function :leptris_element_namespace_count,
+        [:leptris_element], :size_t
+      attach_function :leptris_element_namespace_decl_prefix,
+        [:leptris_element, :size_t], :string
+      attach_function :leptris_element_namespace_decl_uri,
+        [:leptris_element, :size_t], :string
+      attach_function :leptris_element_add_namespace_definition,
+        [:leptris_element, :string, :string], :leptris_status
+      attach_function :leptris_element_set_default_namespace,
+        [:leptris_element, :string], :leptris_status
+      attach_function :leptris_element_remove_namespace_definition,
+        [:leptris_element, :string], :leptris_status
+      attach_function :leptris_namespace_uri, [:string], :string
+      attach_function :leptris_namespace_prefix, [:string], :string
+
+      attach_function :leptris_xpath_eval,
+        [:leptris_document, :leptris_element, :string], :leptris_xpath_result
+      attach_function :leptris_xpath_eval_with_vars,
+        [:leptris_document, :string, :leptris_xpath_var_set], :leptris_xpath_result
+      # Union semantics (NodeSet#xpath): N contexts, ONE call — the
+      # engine merges the per-context results into a de-duplicated,
+      # document-ordered nodeset (libleptris 1.9.7, upstream #589).
+      attach_function :leptris_xpath_eval_nodeset,
+        [:leptris_document, :pointer, :size_t, :string], :leptris_xpath_result
+      attach_function :leptris_xpath_compiled_eval_nodeset,
+        [:leptris_document, :pointer, :size_t, :leptris_xpath_compiled],
+        :leptris_xpath_result
+      attach_function :leptris_xpath_eval_with_vars_context,
+        [:leptris_document, :leptris_element, :string, :leptris_xpath_var_set],
+        :leptris_xpath_result
+      attach_function :leptris_xpath_result_type,
+        [:leptris_xpath_result], :int
+      attach_function :leptris_xpath_result_count,
+        [:leptris_xpath_result], :size_t
+      # Mixed nodesets (v1.1.0): unlike result_get (elements only),
+      # get_node returns the node whatever its kind; node_kind reports
+      # which (element / synthetic attribute / text / other).
+      attach_function :leptris_xpath_result_node_kind,
+        [:leptris_xpath_result, :size_t], :int
+      # Pre-_ex variants, superseded by xpath_result_get_nodes_ex /
+      # xpath_result_get_node; mirror-only (ADR 0001).
+      attach_function :leptris_xpath_result_get,
+        [:leptris_xpath_result, :size_t], :leptris_element
+      attach_function :leptris_xpath_result_get_nodes,
+        [:leptris_xpath_result, :pointer, :size_t], :size_t
+      attach_function :leptris_xpath_result_get_node,
+        [:leptris_xpath_result, :size_t], :leptris_node_ref
+      attach_function :leptris_xpath_result_node_name,
+        [:leptris_xpath_result, :size_t], :string
+      attach_function :leptris_xpath_result_node_value,
+        [:leptris_xpath_result, :size_t], :string
+      # Document-scoped custom XPath functions. The callback receives
+      # (const char* const* args, int argc, void* user_data) and returns
+      # a heap string the library frees.
+      attach_function :leptris_xpath_register_function,
+        [:leptris_document, :string, :pointer, :pointer], :leptris_status
+      # v1.3.0: copies ALL node kinds in one call, optionally
+      # reporting per-entry kinds.
+      attach_function :leptris_xpath_result_get_nodes_ex,
+        [:leptris_xpath_result, :pointer, :pointer, :size_t], :size_t
+      attach_function :leptris_xpath_result_boolean,
+        [:leptris_xpath_result], :int
+      attach_function :leptris_xpath_result_number,
+        [:leptris_xpath_result], :double
+      attach_function :leptris_xpath_result_string,
+        [:leptris_xpath_result], :pointer
+      attach_function :leptris_xpath_result_free,
+        [:leptris_xpath_result], :void
+      attach_function :leptris_xpath_function_supported, [:string], :int
+      attach_function :leptris_xpath_supported_functions, [], :pointer
+
+      attach_function :leptris_xpath_variable_set_new,
+        [], :leptris_xpath_var_set
+      attach_function :leptris_xpath_variable_set_free,
+        [:leptris_xpath_var_set], :void
+      attach_function :leptris_xpath_variable_set_boolean,
+        [:leptris_xpath_var_set, :string, :int], :leptris_status
+      attach_function :leptris_xpath_variable_set_number,
+        [:leptris_xpath_var_set, :string, :double], :leptris_status
+      attach_function :leptris_xpath_variable_set_string,
+        [:leptris_xpath_var_set, :string, :string], :leptris_status
+
+      # Namespace-bound XPath (v1.2.0): expression prefixes resolve to
+      # caller-supplied URIs regardless of the document's declarations.
+      attach_function :leptris_xpath_ns_set_new,
+        [], :leptris_xpath_ns_set
+      attach_function :leptris_xpath_ns_set_free,
+        [:leptris_xpath_ns_set], :void
+      # One-call constructor: flat array of 2*pair_count alternating
+      # prefix/URI strings.
+      # Per-pair add; superseded by ns_set_new_from_pairs (one call);
+      # mirror-only (ADR 0001).
+      attach_function :leptris_xpath_ns_set_add,
+        [:leptris_xpath_ns_set, :string, :string], :leptris_status
+      attach_function :leptris_xpath_ns_set_new_from_pairs,
+        [:pointer, :size_t], :leptris_xpath_ns_set
+      attach_function :leptris_xpath_eval_ns,
+        [:leptris_document, :leptris_element, :string, :leptris_xpath_ns_set],
+        :leptris_xpath_result
+      # Compiled expressions (v1.6.0): parse once, evaluate many.
+      attach_function :leptris_xpath_compile,
+        [:string], :leptris_xpath_compiled
+      attach_function :leptris_xpath_compiled_eval,
+        [:leptris_xpath_compiled, :leptris_document, :leptris_element],
+        :leptris_xpath_result
+      attach_function :leptris_xpath_compiled_eval_ns,
+        [:leptris_xpath_compiled, :leptris_document, :leptris_element,
+         :leptris_xpath_ns_set], :leptris_xpath_result
+      attach_function :leptris_xpath_compiled_eval_vars,
+        [:leptris_xpath_compiled, :leptris_document, :leptris_element,
+         :leptris_xpath_var_set], :leptris_xpath_result
+      # Combined namespaces + variables (1.9.18, upstream #608).
+      attach_function :leptris_xpath_compiled_eval_ns_vars,
+        [:leptris_xpath_compiled, :leptris_document, :leptris_element,
+         :leptris_xpath_ns_set, :leptris_xpath_var_set],
+        :leptris_xpath_result
+      # Source text of a compiled expression (owned by the handle).
+      attach_function :leptris_xpath_compiled_text,
+        [:leptris_xpath_compiled], :string
+      attach_function :leptris_xpath_compiled_free,
+
+        [:leptris_xpath_compiled], :void
+      attach_function :leptris_sax_parse,
+        [:string, :size_t, :pointer, :pointer], :int
+      attach_function :leptris_sax_parser_create,
+        [:pointer, :pointer], :leptris_sax_parser
+      attach_function :leptris_sax_parser_feed,
+        [:leptris_sax_parser, :string, :size_t, :int], :int
+      # Chunked event recorder (libleptris 1.9.4, #585): buffers
+      # events C-side (fixed records + packed arena); the host
+      # drains in bulk — callbacks become O(chunks), not O(events).
+      attach_function :leptris_sax_recorder_new,
+        [], :leptris_sax_recorder
+      attach_function :leptris_sax_recorder_feed,
+        [:leptris_sax_recorder, :string, :size_t, :int], :int
+      attach_function :leptris_sax_recorder_records,
+        [:leptris_sax_recorder, :pointer], :pointer
+      attach_function :leptris_sax_recorder_arena,
+        [:leptris_sax_recorder, :pointer], :pointer
+      # Reuse across documents (1.9.10, #594): swaps in fresh parser
+      # state, RETAINS the record/arena buffers — a
+      # one-document-per-parse loop stops paying new/free churn.
+      attach_function :leptris_sax_recorder_reset,
+        [:leptris_sax_recorder], :int
+      attach_function :leptris_sax_recorder_free,
+        [:leptris_sax_recorder], :void
+      attach_function :leptris_sax_parser_free,
+        [:leptris_sax_parser], :void
+      attach_function :leptris_sax_parser_set_streaming,
+        [:leptris_sax_parser, :int], :int
+
+      # Pull parsing (v1.6.0): StAX-style cursor over a document.
+      attach_function :leptris_pull_new,
+        [:string, :size_t], :leptris_pull_parser
+      attach_function :leptris_pull_new_file,
+        [:string], :leptris_pull_parser
+      attach_function :leptris_pull_next,
+        [:leptris_pull_parser], :pointer
+      attach_function :leptris_pull_next_batch,
+        [:leptris_pull_parser, :pointer, :size_t], :size_t
+      attach_function :leptris_pull_attr_count,
+        [:leptris_pull_parser], :size_t
+      attach_function :leptris_pull_attr_name,
+        [:leptris_pull_parser, :size_t], :string
+      attach_function :leptris_pull_attr_value,
+        [:leptris_pull_parser, :size_t], :string
+      attach_function :leptris_pull_attrs,
+        [:leptris_pull_parser, :pointer, :size_t], :size_t
+      attach_function :leptris_pull_free,
+        [:leptris_pull_parser], :void
+
+      # Iterparse (v1.6.0): yields each completed top-level child
+      # element; the previous subtree is released on each next call.
+      attach_function :leptris_iterparse_new,
+        [:string, :size_t], :leptris_iterparse
+      attach_function :leptris_iterparse_new_file,
+        [:string], :leptris_iterparse
+      attach_function :leptris_iterparse_next,
+        [:leptris_iterparse], :leptris_element
+      # iterparse v2 (libleptris 1.9.4, #586): explicit yield mode
+      # (top-level children or full-document post-order), namespace
+      # resolution on the last yielded element, error channel.
+      attach_function :leptris_iterparse_new_ex,
+        [:string, :size_t, :int], :leptris_iterparse
+      attach_function :leptris_iterparse_new_file_ex,
+        [:string, :int], :leptris_iterparse
+      attach_function :leptris_iterparse_ns_count,
+        [:leptris_iterparse], :size_t
+      attach_function :leptris_iterparse_ns_uri,
+        [:leptris_iterparse, :string], :string
+      attach_function :leptris_iterparse_error,
+        [:leptris_iterparse], :string
+      attach_function :leptris_iterparse_free,
+        [:leptris_iterparse], :void
+
+      attach_function :leptris_document_serialize,
+        [:leptris_document, :pointer], :pointer
+      # Deprecated automatic-options alias (header: prefer
+      # leptris_document_serialize); mirror-only.
+      attach_function :leptris_serialize_document,
+        [:leptris_document], :pointer
+      # libleptris >= 1.9.0: caller-buffer serialization with options
+      # (leptris#541). buf=NULL is a size query; the size-query +
+      # fill pair reuses one serialization through a per-document
+      # cache invalidated on mutation.
+      # Display-form variant (1.9.9, #129): the ext struct carries
+      # indent_text; returns an OWNED string — read via
+      # read_owned_string (the seam frees it).
+      attach_function :leptris_document_serialize_ext,
+        [:leptris_document, :pointer, :pointer], :pointer
+      # Sized variant (1.9.19, upstream #644 — leptris-ruby PR #107):
+      # passing our ext-struct size keeps the engine from reading
+      # past this binding's allocation (the MSVC segfault).
+      attach_function :leptris_document_serialize_ext_sized,
+        [:leptris_document, :pointer, :pointer, :size_t], :pointer
+      attach_function :leptris_document_serialize_into,
+        [:leptris_document, :pointer, :size_t, :pointer, :pointer], :size_t
+      attach_function :leptris_document_get_dtd,
+        [:leptris_document], :pointer
+      # Element-level ext serialization (libleptris 1.9.95, #882):
+      # the document ext option surface (indent_text, indent_unit,
+      # expand_empty) at element level. The sized twin is the
+      # FFI-safe form (older ext allocations read within bounds).
+      attach_function :leptris_element_serialize_ext,
+        [:leptris_element, :pointer, :pointer], :pointer
+      attach_function :leptris_element_serialize_ext_sized,
+        [:leptris_element, :pointer, :pointer, :size_t], :pointer
+
+      # Content-defined Merkle digest of a subtree (libleptris
+      # 1.9.99, #869): equal flags + equal digests imply structural
+      # equivalence (descend to decide on inequality); flags bit 1
+      # (DROP_WS_TEXT) skips whitespace-only text nodes.
+      attach_function :leptris_node_digest,
+        [:leptris_node_ref, :int], :uint64
+
+      attach_function :leptris_element_serialize,
+        [:leptris_element, :pointer], :pointer
+      attach_function :leptris_element_serialize_into,
+        [:leptris_element, :pointer, :size_t, :pointer, :pointer], :size_t
+      attach_function :leptris_document_save_file,
+        [:leptris_document, :string, :pointer], :leptris_status
+      # XSLT 1.0 engine (libleptris 1.9.1): compile once, apply many.
+      # XQuery 1.0 core (libleptris 1.9.64-1.9.66): orchestration
+      # over the XPath engine — prolog (declare variable/namespace/
+      # function local:*), FLWOR, computed and direct constructors.
+      # Results reuse the XPath result handle (free with
+      # leptris_xpath_result_free); context_node NULL = document.
+      attach_function :leptris_xquery_parse,
+        [:string, :size_t], :leptris_xquery
+      attach_function :leptris_xquery_eval,
+        [:leptris_xquery, :leptris_document, :leptris_element],
+        :leptris_xpath_result
+      # External-variable XQuery evaluation (libleptris 1.9.133):
+      # names[i]/selects[i] bind `declare variable $name external`
+      # — each select is an XPath expression in an empty context
+      # (QT3 <param select> semantics), overriding any default
+      # initializer. An external with neither binding nor default
+      # fails evaluation.
+      attach_function :leptris_xquery_eval_params,
+        [:leptris_xquery, :leptris_document, :leptris_element,
+         :pointer, :pointer, :size_t], :leptris_xpath_result
+      attach_function :leptris_xquery_free, [:leptris_xquery], :void
+
+      # Schematron validation (libleptris >= 1.9.126 family):
+      # parse once (optionally selecting a PHASE), validate any
+      # number of documents — #validate returns the SVRL report as
+      # a Document; #valid? answers through the SVRL root name.
+      attach_function :leptris_schematron_parse,
+        [:string, :size_t, :pointer], :leptris_schematron
+      attach_function :leptris_schematron_parse_file,
+        [:string, :pointer], :leptris_schematron
+      attach_function :leptris_schematron_parse_phase,
+        [:string, :size_t, :string, :pointer], :leptris_schematron
+      attach_function :leptris_schematron_free,
+        [:leptris_schematron], :void
+      attach_function :leptris_schematron_valid,
+        [:leptris_schematron, :leptris_document], :int
+      attach_function :leptris_schematron_validate,
+        [:leptris_schematron, :leptris_document], :leptris_document
+      attach_function :leptris_schematron_error,
+        [:leptris_schematron], :string
+
+      # Tree diff (libleptris >= 1.9.126 family): equal subtrees
+      # prune in O(1) by the #869 Merkle digest; diverging regions
+      # align via LCS on child digests, then recurse by name.
+      attach_function :leptris_diff,
+        [:leptris_document, :leptris_document, :int, :pointer],
+        :leptris_diff
+      attach_function :leptris_diff_free, [:leptris_diff], :void
+      attach_function :leptris_diff_op_count, [:leptris_diff], :size_t
+      attach_function :leptris_diff_op_type,
+        [:leptris_diff, :size_t], :int
+      attach_function :leptris_diff_op_name,
+        [:leptris_diff, :size_t], :string
+      attach_function :leptris_diff_op_path,
+        [:leptris_diff, :size_t], :string
+      attach_function :leptris_diff_op_before,
+        [:leptris_diff, :size_t], :string
+      attach_function :leptris_diff_op_after,
+        [:leptris_diff, :size_t], :string
+      attach_function :leptris_diff_serialize,
+        [:leptris_diff], :pointer
+
+      # One-call expanded name (libleptris 1.9.144): local name +
+      # prefix + resolved namespace URI in a single entry — the
+      # FFI-adapter fan-out read.
+      attach_function :leptris_element_expanded_name,
+        [:leptris_element, :pointer, :pointer, :pointer], :void
+
+      # Versioned XPath evaluation (libleptris lane 15): XPATH_10
+      # keeps the strict 1.0 surface (3.x syntax rejected with
+      # INVALID_ARG); XPATH_31 evaluates the full grammar.
+      attach_function :leptris_xpath_eval_versioned,
+        [:leptris_document, :leptris_element, :string, :int, :pointer],
+        :leptris_xpath_result
+      XPATH_10 = 1 # strict XPath 1.0: the 3.x surface is rejected
+      XPATH_31 = 3 # the full grammar (the default entry's surface)
+
+      # One-pass entity pre-scan (libleptris 1.9.62, leptris#745):
+      # 1 when the buffer holds a named entity that is not one of
+      # the five predefined XML entities (nor numeric) — the moxml
+      # pre-scan at C speed instead of a Ruby regex.
+      attach_function :leptris_str_has_nonstandard_entity,
+        [:string, :size_t], :int
+
+      attach_function :leptris_rng_parse,
+        [:string, :size_t, :pointer], :leptris_relaxng
+      attach_function :leptris_rng_parse_file,
+        [:string, :pointer], :leptris_relaxng
+      attach_function :leptris_rng_free,
+        [:leptris_relaxng], :void
+      # 1 valid; 0 invalid (detail via leptris_rng_error)
+      attach_function :leptris_rng_validate,
+        [:leptris_relaxng, :leptris_document], :int
+      attach_function :leptris_rng_error,
+        [:leptris_relaxng], :string
+      # Accumulated validation errors (libleptris 1.9.179, #878):
+      # the validator no longer stops at the first failure;
+      # leptris_rng_error keeps returning the first (back-compat).
+      attach_function :leptris_rng_error_count,
+        [:leptris_relaxng], :size_t
+      attach_function :leptris_rng_error_message,
+        [:leptris_relaxng, :size_t], :string
+      attach_function :leptris_rng_error_line,
+        [:leptris_relaxng, :size_t], :int
+      attach_function :leptris_rng_error_column,
+        [:leptris_relaxng, :size_t], :int
+
+      # Whole-report face (libleptris 1.9.190): one call returns
+      # every record — kind (the #1126 failure-class taxonomy) and
+      # offender were unreachable through the per-index accessors.
+      # Record array is handle-owned; strings live until the next
+      # validate call or leptris_rng_free.
+      class RngErrorRecord < ::FFI::Struct
+        layout :kind, :string,
+               :message, :string,
+               :offender, :string,
+               :line, :uint,
+               :column, :uint
+      end
+      attach_function :leptris_rng_error_report,
+        [:leptris_relaxng, :pointer], :size_t
+
+      attach_function :leptris_xslt_parse,
+        [:string, :size_t], :leptris_xslt
+      attach_function :leptris_xslt_parse_file,
+        [:string], :leptris_xslt
+      attach_function :leptris_xslt_free,
+        [:leptris_xslt], :void
+      # Result tree is a document (free with document_free); errors
+      # surface via document_last_error on NULL.
+      attach_function :leptris_xslt_apply,
+        [:leptris_xslt, :leptris_document], :leptris_document
+      # apply + serialize in one call, keeping top-level text nodes
+      # and result fragments the tree API would flatten.
+      attach_function :leptris_xslt_apply_string,
+        [:leptris_xslt, :leptris_document], :pointer
+      attach_function :leptris_c14n_canonicalize,
+
+        [:leptris_document, :int, :int], :pointer
+      attach_function :leptris_c14n_canonicalize_subtree,
+        [:leptris_element, :int, :int], :pointer
+      attach_function :leptris_c14n_canonicalize_ex,
+        [:leptris_document, :int, :int, :pointer, :int], :pointer
+      attach_function :leptris_c14n_canonicalize_subtree_ex,
+        [:leptris_element, :int, :int, :pointer, :int], :pointer
+
+      attach_function :leptris_document_internal_subset,
+        [:leptris_document], :leptris_doctype
+      attach_function :leptris_doctype_get_name,
+        [:leptris_doctype], :string
+      attach_function :leptris_doctype_get_root_name,
+        [:leptris_doctype], :string
+      attach_function :leptris_doctype_get_public_id,
+        [:leptris_doctype], :string
+      attach_function :leptris_doctype_get_system_id,
+        [:leptris_doctype], :string
+      attach_function :leptris_doctype_get_internal_subset,
+        [:leptris_doctype], :string
+
+      attach_function :leptris_free_string, [:pointer], :void
+      attach_function :leptris_explicit_cleanup, [], :void
+      attach_function :leptris_set_memory_management_functions,
+        [:pointer, :pointer], :void
+      attach_function :leptris_get_memory_allocation_function, [], :pointer
+      attach_function :leptris_get_memory_deallocation_function, [], :pointer
+      attach_function :leptris_document_set_allocators,
+        [:leptris_document, :pointer, :pointer], :leptris_status
+      attach_function :leptris_status_string, [:leptris_status], :string
+      attach_function :leptris_error_message, [:leptris_status], :string
+      # Thread-global last-failure position (error.h): companion to
+      # leptris_last_error; populated by recover parses (#547).
+      attach_function :leptris_last_error_position,
+        [:pointer, :pointer], :void
+      # Thread-local since v1.3.0; reliable under the
+      # one-document-per-thread contract.
+      attach_function :leptris_last_error, [], :string
+      attach_function :leptris_document_last_error,
+        [:leptris_document], :string
+      # Optional: release per-thread registry entries when a worker
+      # thread exits (long-lived threads never need it).
+      attach_function :leptris_thread_cleanup, [], :void
+      # First-party EXSLT-style extension pack (str:/set:/math:),
+      # registered natively on one document.
+      attach_function :leptris_exslt_enable,
+        [:leptris_document], :leptris_status
+
+      LEPTRIS_OK = 0
+      LEPTRIS_ERROR_MEMORY = -1
+      LEPTRIS_ERROR_PARSE = -2
+      LEPTRIS_ERROR_XPATH = -3
+      LEPTRIS_ERROR_NULL_ARG = -4
+      LEPTRIS_ERROR_INVALID_ARG = -5
+      LEPTRIS_ERROR_NOT_FOUND = -6
+      LEPTRIS_ERROR_IO = -7
+      LEPTRIS_ERROR_NOT_IMPLEMENTED = -8
+
+      XPATH_NODESET = 0
+      XPATH_BOOLEAN = 1
+      XPATH_NUMBER = 2
+      XPATH_STRING = 3
+      # XPath 3.0 function item (libleptris TODO 07 lane): a closure
+      # or named function reference. Not callable across the FFI
+      # boundary yet — wrap_xpath_result raises explicitly.
+      XPATH_FUNCTION = 4
+
+      XPATH_NODE_ELEMENT = 0
+      XPATH_NODE_ATTRIBUTE = 1
+      XPATH_NODE_TEXT = 2
+      XPATH_NODE_OTHER = 3
+
+      NODE_ELEMENT = 0
+      NODE_TEXT = 1
+      NODE_COMMENT = 2
+      NODE_CDATA = 3
+      NODE_PI = 4
+      NODE_ENTITY_REF = 10
+      # Internal XPath-synthetic text node (leptris/types.h): the
+      # carrier for sequence/map/array items in result nodesets —
+      # readable only through the result handle, so the binding
+      # captures the value at materialization (ResultText).
+      NODE_SYNTHETIC_TEXT = 8
+      # #1094: &name; references stay unexpanded first-class nodes
+      # when this flag parses (character references still expand).
+      LEPTRIS_PARSE_KEEP_ENTITY_REFS = 4
+      NODE_DOCTYPE = 5
+      NODE_ATTRIBUTE = 6
+
+      C14N_1_0 = 0
+      C14N_1_1 = 1
+
+      C14N_MODE_CANONICAL = 0
+      C14N_MODE_EXCLUSIVE = 1
+
+      TRAVERSE_PRE_ORDER = 0
+      TRAVERSE_POST_ORDER = 1
+
+      PULL_START_ELEMENT = 0
+      PULL_END_ELEMENT   = 1
+      PULL_TEXT          = 2
+      PULL_COMMENT       = 3
+      PULL_CDATA         = 4
+      PULL_PI            = 5
+      PULL_END_DOCUMENT  = 6
+      PULL_ERROR         = 7
+      # Prefix events (types.h LeptrisPullEventType 8/9): the
+      # default namespace's prefix is legitimately "".
+      PULL_START_PREFIX  = 8
+      PULL_END_PREFIX    = 9
+
+      LEPTRIS_PARSE_DEFAULT = 0
+      LEPTRIS_PARSE_DROP_WS_TEXT = 1
+      # libleptris >= 1.9.8 (#606): apply DTD ATTLIST default (and
+      # #FIXED) attribute values at parse time — libxml2
+      # XML_PARSE_DTDATTR opt-in parity.
+      LEPTRIS_PARSE_DTDATTR = 2
+
+      # The headers' contract is UTF-8 for every C string, but FFI's
+      # read_string hands back ASCII-8BIT — the platform default
+      # leaks through the seam. Every string-returning attached
+      # function this binding CALLS is wrapped here so its result
+      # arrives as UTF-8; mirror-only attachments stay raw (add the
+      # name here when a call site starts using its string).
+      UTF8_RETURNS = %i[
+        leptris_version
+        leptris_status_string leptris_last_error
+        leptris_document_last_error leptris_document_encoding
+        leptris_document_pi_target leptris_document_pi_data
+        leptris_document_comment_content
+        leptris_element_name leptris_element_text leptris_element_prefix
+        leptris_element_namespace
+        leptris_element_attribute leptris_element_attribute_ns
+        leptris_attribute_get_name leptris_attribute_get_value
+        leptris_attribute_namespace_uri
+        leptris_element_namespace_decl_prefix
+        leptris_element_namespace_decl_uri
+        leptris_text_node_get_content leptris_comment_node_get_content
+        leptris_cdata_node_get_content
+        leptris_pi_node_get_target leptris_pi_node_get_data
+        leptris_pull_attr_name leptris_pull_attr_value
+      ].freeze
+      private_constant :UTF8_RETURNS
+
+      UTF8_RETURNS.each do |name|
+        raw = method(name)
+        define_singleton_method(name) do |*args|
+          str = raw.call(*args)
+          str.nil? ? nil : str.force_encoding(Encoding::UTF_8)
+        end
+      end
+
+      # Reads an libleptris-owned char* result and frees it as one unit,
+      # so a call site can neither leak nor double-free.
+      def self.read_owned_string(ptr)
+        return "" if ptr.nil? || ptr.null?
+        ptr.read_string.tap { leptris_free_string(ptr) }
+          .force_encoding(Encoding::UTF_8)
+      end
+
+      # Single status seam: turns a C status code into a Ruby error,
+      # appending the library's last-error detail when present. The
+      # detail is a library-global string, so it can only be treated
+      # as best-effort context.
+      def self.check_status(status)
+        unless status == LEPTRIS_OK
+          raise Leptris::XML::Error, status_message(status)
+        end
+        status
+      end
+
+      def self.status_message(status)
+        base = leptris_status_string(status).to_s
+        detail = leptris_last_error.to_s
+        detail.empty? ? base : "#{base} (#{detail})"
+      end
+
+      # Namespace-binding lifecycle, written once: flatten the
+      # prefix/URI hash into the alternating CStringArray wire
+      # format and build the C set. Sets are cached per distinct
+      # vocabulary: the XPath VM reads the set as a const map
+      # during evaluation (vm.c) and never mutates it, so one set
+      # serves the process across queries and threads — building
+      # the wire format plus a C set per query cost ~6.7 µs, 2.6×
+      # a no-namespace query on a small document. Cached sets are
+      # never freed (bounded by the process's distinct namespace
+      # vocabularies — the same trade the CSS translation cache
+      # makes). Failed builds raise before caching.
+      NS_SET_CACHE = {}
+
+      def self.with_ns_set(hash)
+        yield ns_set_for(hash)
+      end
+
+      def self.ns_set_for(hash)
+        pairs = hash.map { |prefix, uri| [prefix.to_s, uri.to_s] }
+        key = if pairs.size == 1
+                "#{pairs[0][0]}\x00#{pairs[0][1]}"
+              else
+                pairs.sort.join("\x00")
+              end
+        NS_SET_CACHE.fetch(key) do
+          flat = pairs.flatten
+          buffer, _anchors = Leptris::XML::CStringArray.to_c(flat)
+          set = leptris_xpath_ns_set_new_from_pairs(buffer, flat.length / 2)
+          if set.null?
+            raise Leptris::XML::Error,
+              "leptris_xpath_ns_set_new_from_pairs failed"
+          end
+          NS_SET_CACHE[key] = set
+        end
+      end
+
+      # Caller-buffer serialization cycle: size query (buf=NULL),
+      # allocate exactly, fill, read. Since libleptris 1.9.0 the
+      # pair reuses one serialization through the per-document
+      # cache. +ffi_function+ is leptris_document_serialize_into or
+      # leptris_element_serialize_into. The buffer holds the
+      # serialization + NUL and XML output is NUL-free, so the
+      # bounded read is exact.
+      # snprintf contract (leptris.h #535): the return is ALWAYS the
+      # bytes needed incl. the NUL; the copy happens only when the
+      # buffer fits. So the size probe is paid only when the child
+      # outgrows the grow-only scratch — one dispatch per call on
+      # the fast path instead of two (inner_html serializes each
+      # child; the probe was most of the per-child FFI cost).
+      SERIALIZE_INITIAL = 256
+      private_constant :SERIALIZE_INITIAL
+
+      def self.serialize_into_string(ffi_function, c_ptr, options)
+        scratch = (Thread.current[:leptris_scratch] ||= {})
+        buffer = scratch[:bytes]
+        if buffer.nil?
+          buffer = scratch[:bytes] =
+            ::FFI::MemoryPointer.new(:char, SERIALIZE_INITIAL)
+        end
+        needed = ffi_function.call(c_ptr, buffer, buffer.size, nil, options)
+        if needed > buffer.size
+          buffer = scratch_bytes(needed)
+          needed = ffi_function.call(c_ptr, buffer, buffer.size, nil, options)
+        end
+        return "" if needed <= 1
+        buffer.read_string(needed - 1).force_encoding(Encoding::UTF_8)
+      end
+
+      # Byte scratch for serialize-into cycles: the size+fill pair
+      # allocated and freed a buffer per call — inner_html
+      # serializes each child, and the allocation was most of the
+      # per-child cost. Grows to the largest serialization seen;
+      # no Ruby reentrancy during a serialize call.
+      def self.scratch_bytes(need)
+        scratch = (Thread.current[:leptris_scratch] ||= {})
+        ptr = scratch[:bytes]
+        if ptr.nil? || ptr.size < need
+          ptr&.free
+          ptr = scratch[:bytes] = ::FFI::MemoryPointer.new(:char, need)
+        end
+        ptr
+      end
+
+      # All-kind child handle batch (libleptris 1.7.0). Opportunistic
+      # single dispatch: the C call copies up to the capacity handed
+      # it and returns what fit, so the count query is paid only when
+      # the buffer fills exactly (a possible truncation) — families
+      # that fit the scratch buffer cost ONE dispatch, not two.
+      FETCH_INITIAL = 32
+      private_constant :FETCH_INITIAL
+
+      # Returns [pointers, kinds] — the kinds ride the batch
+      # (leptris_node_children_ex, 1.9.18 #617) so wrappers skip
+      # the per-child get_type dispatch.
+      def self.fetch_children(c_ptr)
+        # One thread-local access serves both buffers (the helper
+        # re-looked it up); the kinds buffer sizes from the POINTERS
+        # buffer's capacity — it may have grown past FETCH_INITIAL on
+        # earlier use, and C writes one kind per copied child.
+        scratch = (Thread.current[:leptris_scratch] ||= {})
+        buffer = scratch[:pointers]
+        if buffer.nil?
+          buffer = scratch[:pointers] =
+            ::FFI::MemoryPointer.new(:pointer, FETCH_INITIAL)
+        end
+        cap = buffer.size / PTR_BYTES
+        kinds = scratch[:ints]
+        if kinds.nil? || kinds.size / INT_BYTES < cap
+          kinds&.free
+          kinds = scratch[:ints] = ::FFI::MemoryPointer.new(:int, cap)
+        end
+        copied = leptris_node_children_ex(c_ptr, buffer, kinds, cap)
+        if copied == cap
+          total = leptris_node_children_ex(c_ptr, nil, nil, 0)
+          if total > cap
+            buffer.free
+            buffer = scratch[:pointers] =
+              ::FFI::MemoryPointer.new(:pointer, total)
+            kinds.free
+            kinds = scratch[:ints] =
+              ::FFI::MemoryPointer.new(:int, total)
+            copied = leptris_node_children_ex(c_ptr, buffer, kinds, total)
+          end
+        end
+        [buffer.get_array_of_pointer(0, copied),
+         kinds.get_array_of_int(0, copied)]
+      end
+
+      # Raw qname-ordered attribute pairs INCLUDING xmlns at their
+      # byte positions (leptris_element_attributes_raw, 1.9.18
+      # #635) — the streaming SAX contract's mixed view.
+      def self.fetch_attributes_raw(el_ptr)
+        total = leptris_element_attributes_raw(el_ptr, nil, nil, 0)
+        return [] if total.zero?
+        scratch = (Thread.current[:leptris_scratch] ||= {})
+        names = scratch[:attr_names]
+        if names.nil? || names.size / PTR_BYTES < total
+          names&.free
+          names = scratch[:attr_names] =
+            ::FFI::MemoryPointer.new(:pointer, total)
+        end
+        values = scratch[:attr_values]
+        if values.nil? || values.size / PTR_BYTES < total
+          values&.free
+          values = scratch[:attr_values] =
+            ::FFI::MemoryPointer.new(:pointer, total)
+        end
+        copied = leptris_element_attributes_raw(
+          el_ptr, names, values, total)
+        Array.new(copied) do |i|
+          [utf8(names.get_pointer(i * PTR_BYTES).read_string),
+           utf8(values.get_pointer(i * PTR_BYTES).read_string)]
+        end
+      end
+
+      # Attribute strings cross the seam UTF-8 on both faces
+      # (ADR-0002).
+      def self.utf8(str)
+        str.nil? ? nil : str.force_encoding(Encoding::UTF_8)
+      end
+
+      # Element-only child batch (the mirror of fetch_children over
+      # leptris_element_children): element receivers skip wrapping —
+      # and paying for — the text/comment children they will filter
+      # out anyway; every wrap carries the ELEMENT hint so the
+      # per-child get_type dispatch disappears too.
+      def self.fetch_element_children(el_ptr)
+        scratch = (Thread.current[:leptris_scratch] ||= {})
+        buffer = scratch[:pointers]
+        if buffer.nil?
+          buffer = scratch[:pointers] =
+            ::FFI::MemoryPointer.new(:pointer, FETCH_INITIAL)
+        end
+        cap = buffer.size / PTR_BYTES
+        copied = leptris_element_children(el_ptr, buffer, cap)
+        if copied == cap
+          # leptris_element_children has NO count-only mode (NULL
+          # returns 0, unlike leptris_node_children) — size the
+          # regrow from the dedicated counter.
+          total = leptris_element_child_count(el_ptr)
+          if total > cap
+            buffer.free
+            buffer = scratch[:pointers] =
+              ::FFI::MemoryPointer.new(:pointer, total)
+            copied = leptris_element_children(el_ptr, buffer, total)
+          end
+        end
+        buffer.get_array_of_pointer(0, copied)
+      end
+
+      # XPath result-set batch (leptris_xpath_result_get_nodes_ex):
+      # the call fills out_kinds in the 4-value XPATH_NODE space
+      # (ELEMENT/ATTRIBUTE/TEXT/OTHER). ELEMENT is the only value
+      # that maps unambiguously — XPath's data model reports CDATA
+      # as TEXT, so a TEXT hint cannot distinguish Text from CDATA
+      # (different content getters) — everything else falls back to
+      # get_type in the wrapper. Returns [pointers, element_hints].
+      XPATH_KIND_HINT = { XPATH_NODE_ELEMENT => NODE_ELEMENT }.freeze
+
+      # Returns [pointers, element_hints, raw_kinds] — the raw
+      # XPATH_NODE-space kinds ride along so the materializer can
+      # spot TEXT items (synthetic sequence carriers) and capture
+      # their values while the result handle is alive.
+      def self.fetch_result_nodes(result_ptr, count)
+        return [[], nil, nil] if count.zero?
+        buffer = scratch_pointers(count)
+        kinds = scratch_ints(count)
+        copied = leptris_xpath_result_get_nodes_ex(
+          result_ptr, buffer, kinds, count)
+        raw = kinds.get_array_of_int(0, copied)
+        hints = raw.map { |k| XPATH_KIND_HINT[k] }
+        [buffer.get_array_of_pointer(0, copied), hints, raw]
+      end
+
+      # Fragment parse with the status out-param read: returns
+      # [document-or-fragment pointer, status].
+      def self.parse_fragment_with_status(xml, document_ptr)
+        status = ::FFI::MemoryPointer.new(:int)
+        raw = leptris_parse_fragment(
+          xml, xml.bytesize, document_ptr, status)
+        [raw, status.read_int]
+      end
+
+      # libxml2 consumes the whole whitespace run following the PI
+      # target when parsing; the engine retains it as data
+      # (leptris-ruby#85). Every Ruby-facing PI-data read normalizes
+      # here — whitespace-only data becomes "" so
+      # "pi-without-data" PIs report empty consistently. Read-time
+      # only: PI#data= stores verbatim.
+      def self.read_pi_data(data)
+        data&.sub(/\A[ \t\r\n]+/, "")
+      end
+
+      # Thread-local scratch buffers for batch handle fetches (round
+      # XX): the per-call MemoryPointer new/free was pure cold-path
+      # overhead — two allocations and a GC visit per children() /
+      # result-set batch, ~15% of a cold full-tree walk between
+      # 1.9.1 and 1.9.24. The buffers grow to the largest request
+      # seen (bounded by the widest element or result set) and are
+      # reused. Safe: no Ruby reentrancy during the C call, and
+      # per-thread storage keeps concurrent fetches independent.
+      # Never freed — a few KB pinned per thread.
+      PTR_BYTES = ::FFI.type_size(:pointer)
+      private_constant :PTR_BYTES
+      INT_BYTES = ::FFI.type_size(:int)
+      private_constant :INT_BYTES
+
+      def self.scratch_pointers(count)
+        scratch = (Thread.current[:leptris_scratch] ||= {})
+        ptr = scratch[:pointers]
+        if ptr.nil? || ptr.size / PTR_BYTES < count
+          ptr&.free
+          ptr = scratch[:pointers] = ::FFI::MemoryPointer.new(:pointer, count)
+        end
+        ptr
+      end
+
+      def self.scratch_ints(count)
+        scratch = (Thread.current[:leptris_scratch] ||= {})
+        ptr = scratch[:ints]
+        if ptr.nil? || ptr.size / INT_BYTES < count
+          ptr&.free
+          ptr = scratch[:ints] = ::FFI::MemoryPointer.new(:int, count)
+        end
+        ptr
+      end
+
+      # Pull-event staging block for leptris_pull_next_batch (the
+      # #589 bulk transport): LeptrisPullEvent records, stride from
+      # the struct layout that mirrors the ABI.
+      def self.scratch_events(count)
+        need = count * PullEventStruct.size
+        scratch = (Thread.current[:leptris_scratch] ||= {})
+        ptr = scratch[:pull_events]
+        if ptr.nil? || ptr.size < need
+          ptr&.free
+          ptr = scratch[:pull_events] = ::FFI::MemoryPointer.new(need)
+        end
+        ptr
+      end
+    end
+  end
+end