leptris 1.9.197.2-arm-linux

data/Rakefile

@@ -0,0 +1,407 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+# Pin for `rake compile` and the platform-gem builds. Keep in lockstep
+# with .github/workflows/build.yml (which calls `rake compile`) and the
+# CHANGELOG when libleptris releases.
+LIBLEPTRIS_VERSION = "1.9.199"
+# Vendored alongside libleptris for fn:normalize-unicode (TODO
+# .restructure/20): built per platform with a RELOCATABLE @rpath
+# install name, loaded by ffi.rb before libleptris so the
+# dependent image resolves inside the gem.
+UTF8PROC_VERSION = "2.11.0"
+
+
+CMAKE_FLAGS = %w[
+  -DCMAKE_BUILD_TYPE=Release
+  -DLEPTRIS_BUILD_SHARED=ON
+  -DLEPTRIS_BUILD_STATIC=OFF
+  -DBUILD_TESTING=OFF
+  -DLEPTRIS_BUILD_CLI=OFF
+  -DLEPTRIS_BUILD_BENCHMARKS=OFF
+  -DLEPTRIS_BUILD_MAN_PAGES=OFF
+  -DLEPTRIS_ENABLE_UTF8PROC=OFF
+  -DLEPTRIS_ENABLE_ICONV=OFF
+].freeze
+
+require "tmpdir"
+
+desc "Build libleptris #{LIBLEPTRIS_VERSION} (+ utf8proc) from release tarballs into lib/"
+task :compile do
+  # GitHub tarball downloads intermittently return a non-gzip body
+  # (rate-limit/redirect HTML) — the piped curl|tar form then fails
+  # with "not in gzip format" and takes the leg down. Download to a
+  # file with retries, validate the gzip magic, extract from the
+  # file.
+  # Whole-cycle retry: a truncated body can still start with the
+  # gzip magic (Windows runners) and only fail at tar EOF — refetch
+  # on any failure in the chain rather than trusting curl's exit
+  # code alone.
+  fetch_tarball = lambda do |url, dest_dir|
+    attempts = 0
+    begin
+      attempts += 1
+      tgz = File.join(Dir.tmpdir, "leptris-#{Time.now.to_i}-#{rand(1e9)}.tgz")
+      begin
+        sh "curl -sfL --retry 4 --retry-delay 2 --retry-all-errors -o #{tgz} #{url}"
+        magic = File.binread(tgz, 2)
+        unless magic.bytes == [0x1f, 0x8b]
+          raise "downloaded #{url} is not gzip (got #{magic.bytes.inspect})"
+        end
+        # GNU tar (Git-bundled, Windows) parses D:/... as a
+        # REMOTE host spec ("Cannot connect to D:") — the piped
+        # form never had a file argument, so this only surfaces
+        # with -o. --force-local is GNU tar; bsdtar (macOS) and
+        # plain GNU tar (linux) don't need it but tolerate being
+        # skipped.
+        local_flag = Gem.win_platform? ? " --force-local" : ""
+        sh "tar#{local_flag} -xzf #{tgz} -C #{dest_dir} --strip-components=1"
+      ensure
+        File.delete(tgz) if File.exist?(tgz)
+      end
+    rescue StandardError => e
+      raise if attempts >= 3
+      warn "tarball fetch attempt #{attempts} failed (#{e.message}); retrying"
+      retry
+    end
+  end
+
+  version = ENV.fetch("LIBLEPTRIS_VERSION", LIBLEPTRIS_VERSION)
+  build = File.expand_path("tmp/libleptris-#{version}", __dir__)
+  rm_rf(build)
+  mkdir_p(build)
+  fetch_tarball.call(
+    "https://api.github.com/repos/leptris/leptris/tarball/v#{version}", build)
+
+  # NOTE: 32-bit ARM (armv7) is an ENGINE port task — the round-19
+  # ABI asserts pin layouts to 8-byte-pointer sizes and correctly
+  # abort the build on 32-bit. Filed upstream as leptris/leptris
+  # #1174; the release legs stay experimental (continue-on-error)
+  # and flip green automatically when the port ships. We patch
+  # nothing here — the emulated-leg smoke validates whatever the
+  # engine provides.
+
+  # utf8proc: shared build only, @rpath install name, local prefix.
+  u8_dir = File.expand_path("tmp/utf8proc-#{UTF8PROC_VERSION}", __dir__)
+  u8_prefix = File.join(u8_dir, "prefix")
+  rm_rf(u8_dir)
+  mkdir_p(u8_dir)
+  fetch_tarball.call(
+    "https://github.com/JuliaStrings/utf8proc/releases/download/v#{UTF8PROC_VERSION}/utf8proc-#{UTF8PROC_VERSION}.tar.gz",
+    u8_dir)
+  sh "cmake -B #{u8_dir}/build -S #{u8_dir} -DCMAKE_BUILD_TYPE=Release -DBUILD_SHARED_LIBS=ON -DUTF8PROC_ENABLE_TESTING=OFF"
+  sh "cmake --build #{u8_dir}/build --config Release -j 4"
+  sh "cmake --install #{u8_dir}/build --prefix #{u8_prefix}"
+
+  # libleptris 1.9.18's xslt_functions.c:270 assigns LeptrisElement
+  # to LeptrisNodeRef — GCC 14 (Alpine/musl) makes incompatible
+  # pointer types an error by default and the musl platform gems
+  # fail to build; clang toolchains only warn. Downgrade to warning
+  # until the upstream fix (leptris/leptris#640).
+  # No quoting: the flag carries no spaces, and single quotes are
+  # literal on Windows shells (they broke the MSVC build).
+  # GCC-family only — MSVC's cl rejects the flag outright (D8021).
+  cflags = Gem.win_platform? ? "" : "-Wno-error=incompatible-pointer-types"
+  # macOS floor for the VENDORED dylibs: without this, cmake uses
+  # the building machine's SDK default (a macos-latest runner
+  # shipped minos 26.0) and the dylib refuses to load on user
+  # machines older than the runner — the extconf.rb 11.0 pin only
+  # ever covered the native bundle. CMake initializes
+  # CMAKE_OSX_DEPLOYMENT_TARGET from this env var at first
+  # configure (a plain -D lands UNINITIALIZED and is ignored).
+  # 11.0 = the oldest macOS GitHub still hosts runners for;
+  # matches extconf.rb.
+  ENV["MACOSX_DEPLOYMENT_TARGET"] ||= "11.0" if RUBY_PLATFORM =~ /darwin/
+  cmake_base =
+    "#{CMAKE_FLAGS.join(' ').sub('-DLEPTRIS_ENABLE_UTF8PROC=OFF', '-DLEPTRIS_ENABLE_UTF8PROC=ON')} " \
+    "-DCMAKE_PREFIX_PATH=#{u8_prefix} #{cflags.empty? ? '' : "-DCMAKE_C_FLAGS=#{cflags}"}"
+
+  # Two-stage PGO (engine CMake: LEPTRIS_ENABLE_PGO GENERATE/USE;
+  # measured ~20% CPU on the DOM parse path, v1.9.188 worktree A/B,
+  # every PGO round beating every baseline round). Train via the CLI
+  # over the tarball's XML corpus. Windows keeps the plain build —
+  # MSVC PGO is inherently LTCG and these gems link the DLL as-is.
+  # LEPTRIS_PGO=0 escapes to the single-stage build.
+  pgo = ENV["LEPTRIS_PGO"] != "0" && !Gem.win_platform?
+  if pgo
+    # The trainer is disposable infrastructure — an engine-side
+    # trainer break (e.g. leptris/leptris#1204: GCC LTO internalizes
+    # CLI-only API symbols and the CLI link dies) must degrade the
+    # gem to the plain build (loudly, with the issue pointer), not
+    # block every platform's release.
+    begin
+    # _GNU_SOURCE for the TRAIN build only: the CLI (the trainer, not
+    # built in normal gems) uses fileno, which musl hides without a
+    # POSIX feature macro (glibc is lenient). Upstream fix pending in
+    # the C repo; this stays on the throwaway instrumented build.
+    # _GNU_SOURCE is MUSL-ONLY: the CLI trainer's fileno needs a POSIX
+    # feature macro under musl. On glibc the macro reshuffles the
+    # header graph and breaks arena.c's accidental (missing-stdint.h)
+    # uintptr_t. -include stdint.h: under _GNU_SOURCE musl's header
+    # graph ALSO stops feeding stdint.h to arena.c (leptris/leptris
+    # #1166) — force the include on the throwaway trainer build;
+    # the shipped library keeps the plain flags. Single-quote: the
+    # value carries a space (an unquoted split hands cmake a bare
+    # -D_GNU_SOURCE); non-Windows branch, so sh quoting is safe.
+    gnu = RUBY_PLATFORM =~ /musl/ ? " -D_GNU_SOURCE -include stdint.h" : ""
+    pgo_cflags = "#{cflags}#{gnu}".strip
+    pgo_base =
+      if pgo_cflags == cflags
+        cmake_base
+      else
+        cmake_base.sub("-DCMAKE_C_FLAGS=#{cflags}",
+                       "-DCMAKE_C_FLAGS='#{pgo_cflags}'")
+      end
+    sh "cmake -B #{build}/build -S #{build} #{pgo_base} " \
+       "-DLEPTRIS_BUILD_CLI=ON -DLEPTRIS_ENABLE_PGO=GENERATE"
+    sh "cmake --build #{build}/build --config Release -j 4"
+    cli = File.join(build, "build", "cli", "leptris")
+    pgo_dir = File.join(build, "build", "pgo-data")
+    corpus = Dir[File.join(build, "benchmarks", "data", "*.xml")]
+    corpus.each do |xml|
+      # a corpus file can be deliberately malformed; training tolerates it
+      system({ "LLVM_PROFILE_FILE" => File.join(pgo_dir, "%p.profraw") },
+             cli, "parse", xml, out: File::NULL, err: File::NULL)
+    end
+    if RUBY_PLATFORM =~ /darwin/
+      sh "xcrun llvm-profdata merge -output=#{File.join(pgo_dir, 'default.profdata')} " \
+         "#{File.join(pgo_dir, '*.profraw')}"
+    end
+    sh "cmake -B #{build}/build -S #{build} #{cmake_base} " \
+       "-DLEPTRIS_BUILD_CLI=OFF -DLEPTRIS_ENABLE_PGO=USE"
+    sh "cmake --build #{build}/build --config Release -j 4"
+    rescue => e
+      warn "leptris: PGO trainer failed (#{e.message.to_s[0, 160]}); " \
+           "shipping the single-stage build — the parse path loses the " \
+           "~20% PGO gain this release (leptris/leptris#1204 tracks the " \
+           "engine-side trainer break)"
+      rm_rf(File.join(build, "build"))
+      sh "cmake -B #{build}/build -S #{build} #{cmake_base}"
+      sh "cmake --build #{build}/build --config Release -j 4"
+    end
+  else
+    sh "cmake -B #{build}/build -S #{build} #{cmake_base}"
+    sh "cmake --build #{build}/build --config Release -j 4"
+  end
+  # Windows names the shared library leptris.dll (no "lib" prefix);
+  # vendoring under the uniform libleptris.* name keeps the FFI
+  # search order simple. libleptris >= 1.3.0 renames the DLL to
+  # libleptris.dll on Windows too (leptris/leptris#507, issue
+  # TODO.concurrency/05) — accept both names.
+  lib = Dir.glob("#{build}/build/**/libleptris.{dylib,so,dll}").first ||
+        Dir.glob("#{build}/build/**/leptris.dll").first
+  raise "libleptris shared library not found after build" unless lib
+  ext = File.extname(lib)
+  cp(lib, "lib/libleptris#{ext}")
+  # The SONAME file is what @rpath references — .3.dylib on
+  # macOS, .so.3 on Linux (cmake installs the symlink chain;
+  # copying the symlink copies the target), plain .dll on
+  # Windows.
+  u8_lib = Dir.glob("#{u8_prefix}/lib/libutf8proc.3.dylib").first ||
+           Dir.glob("#{u8_prefix}/lib/libutf8proc.so.3").first ||
+           Dir.glob("#{u8_prefix}/lib/libutf8proc.so").first ||
+           Dir.glob("#{u8_prefix}/{lib,bin}/utf8proc.dll").first
+  raise "utf8proc shared library not found after build" unless u8_lib
+  cp(u8_lib, "lib/#{File.basename(u8_lib)}")
+  puts "Vendored #{File.basename(lib)} + #{File.basename(u8_lib)} into lib/"
+
+  # Opt-in native read layer ext (#185): built and vendored beside
+  # the library — no compile at install; resolves libleptris at
+  # require time via dlsym.
+  if Gem.win_platform?
+    # #207: a PE DLL cannot leave Ruby imports unresolved — it
+    # binds the build Ruby's x64-ucrt-rubyNNN.dll. The Windows
+    # gems therefore ship one DLL per supported Ruby minor
+    # (native-<minor>.so), and native_layer picks by RUBY_VERSION
+    # (#227). Local compile builds just the current minor's DLL;
+    # the release workflow runs the build script under 3.3/3.4/
+    # 4.0 to produce the full set.
+    sh "#{RbConfig.ruby} ext/build_windows_native.rb"
+  else
+    ext_dir = "ext/leptris/native"
+    Dir.chdir(ext_dir) do
+      sh "ruby extconf.rb"
+      if RUBY_PLATFORM =~ /darwin/
+        # Link the bundle ourselves: setup-ruby's custom rubies
+        # make mkmf link libruby by absolute runner path no matter
+        # which RbConfig entries are cleared, and any libruby
+        # LC_LOAD_DYLIB is unresolvable on user machines. Compile
+        # via the Makefile, link with pure -undefined
+        # dynamic_lookup (Ruby symbols resolve from the loading
+        # interpreter) and a conservative deployment target.
+        sh "make native.o"
+        sh "cc -dynamic -bundle -undefined dynamic_lookup " \
+           "-mmacosx-version-min=#{ENV['MACOSX_DEPLOYMENT_TARGET'] || '11.0'} " \
+           "-o native.bundle native.o"
+      else
+        # #207: the darwin contract on Linux too — mkmf's `make`
+        # linked libruby.so.3.3 (plus a runner runpath), which
+        # failed to load on 3.4/4.0. Link WITHOUT libruby: one
+        # .so serves every Ruby minor; rb_* resolve from the
+        # loading interpreter at dlopen (static rubies export
+        # their symbols via -rdynamic, like any extension .so).
+        sh "make native.o"
+        sh "#{RbConfig::CONFIG['CC']} -shared -fPIC -o native.so native.o"
+        # Guard the contract in the build log.
+        sh "if strings native.so | grep -q libruby; then " \
+           "echo 'ERROR: native.so links libruby (#207)'; exit 1; fi"
+      end
+    end
+    bundle = Dir.glob("#{ext_dir}/native.{bundle,so,dll}").first
+    raise "native layer bundle not found after build" unless bundle
+    if RUBY_PLATFORM =~ /darwin/
+      # Build-log proof of the linkage contract: libSystem only.
+      puts `otool -L #{bundle}`
+    end
+    # Atomic replace: overwriting a bundle another process still
+    # has mapped gets that loader SIGKILLed (CODESIGNING Invalid
+    # Page) — cp to a temp name, then mv.
+    dest = "lib/leptris/xml/#{File.basename(bundle)}"
+    cp(bundle, "#{dest}.new")
+    mv("#{dest}.new", dest)
+    puts "Vendored native layer (#{File.basename(bundle)}) into lib/leptris/xml/"
+  end
+end
+
+task spec: :compile unless ENV.key?("LEPTRIS_LIB_PATH")
+
+task default: :spec
+
+# Lockstep drift detector (ADR 0001): ffi.rb mirrors the public
+# header, so attached == exported must hold on the vendored library.
+# Run after `rake compile` and before any lockstep release.
+namespace :audit do
+  desc "Fail when ffi.rb attachments and library exports drift"
+  task :symbols do
+    # nm cannot read MSVC PE export tables (every symbol reports as
+    # unexported -> guaranteed false drift), so Windows skips: the
+    # darwin/linux CI legs enforce the mirror — any one platform's
+    # build of the same C surface suffices.
+    if Gem.win_platform?
+      puts "audit:symbols: skipped on Windows (PE export tables); " \
+           "darwin/linux legs enforce the mirror"
+      next
+    end
+    # Probe nm without a shell: the multi-arg system() execs
+    # directly, so there is no which/redirect syntax to be
+    # platform-hostile. File::NULL is NUL where it must be; a
+    # missing binary is falsy either way (ENOENT rescue belts the
+    # older spawn behavior).
+    unless nm_available?
+      puts "audit:symbols: skipped (nm unavailable on this platform)"
+      next
+    end
+    lib = Dir.glob("lib/libleptris.{dylib,so,dll}").first
+    unless lib
+      abort "audit:symbols: vendored library not found — run rake compile"
+    end
+    exported = `nm -gU #{lib}`
+      .lines.map { |l| l.split[2] }.compact
+      .map { |n| n.sub(/\A_/, "") }
+      .select { |n| n.start_with?("leptris_") }
+      .map { |n| n.sub(/\Aleptris_/, "") }.sort
+    attached = File.read("lib/leptris/xml/ffi.rb")
+      .scan(/attach_function :leptris_([a-z_0-9]+)/).flatten.sort
+    unattached = exported - attached
+    unexported = attached - exported
+    unless unattached.empty?
+      puts "exported but NOT attached (upstream surface drift):"
+      unattached.each { |s| puts "  leptris_#{s}" }
+    end
+    unless unexported.empty?
+      puts "attached but NOT exported (stale attachment):"
+      unexported.each { |s| puts "  leptris_#{s}" }
+    end
+    if unattached.empty? && unexported.empty?
+      puts "audit:symbols: #{attached.length}/#{exported.length} symbols in lockstep"
+    else
+      abort "audit:symbols: drift detected"
+    end
+  end
+
+  # @api private
+  def nm_available?
+    system("nm", "--version", out: File::NULL, err: File::NULL)
+  rescue Errno::ENOENT
+    false
+  end
+end
+
+require "rubygems/package_task"
+
+desc "Build the pure-Ruby gem"
+task "gem:native:any" do
+  sh "rake platform:any gem"
+end
+
+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
+
+platforms = [
+  "x64-mingw32",
+  "x64-mingw-ucrt",
+  "aarch64-mingw-ucrt",
+  "x86_64-linux",
+  "x86_64-linux-musl",
+  "aarch64-linux",
+  "aarch64-linux-musl",
+  "x86_64-darwin",
+  "arm64-darwin",
+  "arm-linux",
+  "arm-linux-musl",
+  "ppc64le-linux",
+  "s390x-linux-musl",
+]
+
+platforms.each do |platform|
+  desc "Build pre-compiled gem for the #{platform} platform"
+  task "gem:native:#{platform}" do
+    sh "rake compile platform:#{platform} gem"
+  end
+
+  desc "Define the gem task to build on the #{platform} platform (binary gem)"
+  task "platform:#{platform}" do
+    spec = Gem::Specification::load("leptris.gemspec").dup
+    spec.platform = Gem::Platform.new(platform)
+    spec.files += Dir.glob("lib/libleptris.{dll,so,dylib}")
+    spec.files += Dir.glob("lib/{libutf8proc.3.dylib,libutf8proc.so.3,libutf8proc.so,utf8proc.dll}")
+    if platform.include?("mingw")
+      # #207/#227: per-Ruby-minor DLLs (PE must bind its Ruby).
+      # DOT-FREE names — MRI derives the init symbol from the
+      # basename cut at the first dot (native_3_3.so ->
+      # Init_native_3_3; the dotted form made Ruby look for
+      # "Init_native-3", which cannot exist).
+      spec.files += Dir.glob("lib/leptris/xml/native_*.so")
+    else
+      spec.files += Dir.glob("lib/leptris/xml/native.{bundle,so,dll}")
+    end
+    task = Gem::PackageTask.new(spec)
+    task.define
+  end
+end
+
+require "rake/clean"
+
+CLOBBER.include("pkg")
+CLEAN.include("tmp",
+              "lib/libleptris.dll",
+              "lib/libleptris.dylib",
+              "lib/libleptris.so",
+              "lib/libutf8proc.3.dylib",
+              "lib/libutf8proc.so.3",
+              "lib/libutf8proc.so",
+              "lib/utf8proc.dll")

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

@@ -0,0 +1,28 @@
+# 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). COMPLETE (1.9.163.0): bulk children + bulk element_children for
+binding wrappers (one C pass: class dispatch + ivars + identity
+cache) — cold one-shot walk 9.2->1.2ms (7.8x, element_children +
+name/[]/content). Both TODO items done.
+
+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,18 @@
+# 03 — Bulk XPath result materialization
+
+Status: SHIPPED (1.9.163.0) — one C pass (kind dispatch incl.
+synthetic text/attr value capture, node-type consult for real
+Text/CDATA under XPATH text, identity cache). HONEST FINDING: the
+xpath one-shot is parse-dominated; the materialization slice gains
+~1.4x. >512-entry results and rare kinds fall back to the per-index
+path. No warm-path change.
+
+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,15 @@
+# 04 — Serialization buffer cycle in C
+
+Status: SHIPPED (1.9.163.1) — the sized-buffer cycle runs in C
+(probe largest owned buffer first: single serialization for
+big docs; grow-only scratch under the GVL). inner_html 84->50ms
+(1.7x per-call batch); doc serialize at parity with the FFI seam
+(both single-call); encoding: paths keep the FFI options path.
+
+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,19 @@
+# 05 — Complete the NativeNode read surface
+
+Status: SHIPPED (1.9.163.2) — #attributes (one C walk, string
+values — deliberately the flat [] shape, not the binding's
+Attr-valued hash), #line, #byte_offset with binding parity. Also:
+binding classes in the ext resolve LAZILY (Init may run before
+autoload loads Element — the standalone native_layer require
+crashed before; fixed) and native_layer requires ffi first.
+Remaining cold: writes stay FFI by design; attribute_nodes/
+namespaces deferred until a consumer asks.
+
+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,16 @@
+# 06 — Native-layer legs in the perf battery + drift record
+
+Status: SHIPPED (1.9.163.2) — benchmark/native_vs_binding.rb runs
+the walk/read/serialize rows through both surfaces under the
+TODO.restructure/17 load gate. Honest findings recorded: warm rows
+favor the binding's memoization (attr 0.08 vs 0.30 ms; the native
+API pays per-call dispatch with no memo layer); cold one-shot
+favors the native API (1.81 vs 2.39 ms — on TOP of the binding's
+own bulk/fast acceleration); serialize at parity.
+
+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/TODO.perf/07-native-read-floor.md

@@ -0,0 +1,31 @@
+# 07 — Native read floor: shave the TypedData []/content dispatch (#204 ask 1)
+
+Status: DONE (1.9.163.5)
+
+moxml's 2x mandate: `NativeNode#[]` at 110ns needs <= ~70ns (their
+wrapper keeps ~24ns); `#content` 85ns needs <= 58ns. The budget
+dies in the C entry itself: TypedData fetch + StringValueCStr's
+embedded-NUL scan (memchr over the name) + rb_utf8_str_new_cstr
+(strlen + string mint). The string mint (~50ns) is irreducible
+(the C string must be copied into a Ruby String) — the shaves:
+
+- StringValueCStr -> StringValue + RSTRING_PTR for wire names we
+  control the mint of (attribute names cannot contain NULs);
+- single type-check fetch (RTYPEDDATA_DATA + one pointer compare
+  against nn_type instead of the generic check);
+- measure honestly: report how close to 70/58 each landed.
+
+## Outcome (1.9.163.5)
+
+Repeat reads no longer re-enter the C reader at all: NativeNode
+keeps a version-stamped single-slot memo (struct fields, pointer
+compare against the document's Fixnum version) plus a hash-memo
+second layer for other repeat names; content memoizes in one
+slot. `StringValueCStr` -> `StringValue`+`RSTRING_PTR` landed for
+attribute names. Measured (shared host, load 12-19, so treat as
+upper bounds; #204's table was load <6): `#content` 85 -> 42-55ns
+(budget 58 met), `#[]` 110 -> ~140ns under load — the remaining
+residue is the argument mint + TypedData fetch; a clean-load run
+of benchmark/native_vs_binding.rb's gap rows is the honest gate.
+`#name` 78 -> ~63-73ns. One-shot reads still pay the string mint
+(irreducible: the C string must be copied).

data/TODO.perf/08-version-coherent-native-mutations.md

@@ -0,0 +1,24 @@
+# 08 — Version-coherent native mutations (#204 ask 2)
+
+Status: DONE (1.9.163.5)
+
+The native builder factories (create_element/text/child, add_child,
+set_root) do not advance the binding Document's mutation version —
+a binding children read after a native attach serves the STALE
+memo. Fix in the ext: every mutating entry calls the document's
+advance_version (cached ID) after the C mutation, and the readonly
+gate before it. Mutations are cold relative to reads, so the two
+rb_funcall hops are fine. Gate: build via native factories, read
+via binding children/element_children — lists must agree.
+
+## Outcome (1.9.163.5)
+
+document_advance_version moved from two rb_funcall hops to direct
+ivar reads/writes (@readonly Qtrue check, @version Fixnum bump) —
+no method dispatch on the mutation path. Every NativeNode
+mutating entry (create_child, append_child/add_child, set_root)
+and the new C-bound binding faces (append_binding_child,
+set_binding_attribute) run the same gate: UseAfterFreeError via
+the nil @c_address twin, ReadOnlyError via @readonly, then the
+bump. Gate verified: native append -> binding children/content
+serve fresh values; readonly raises through every native entry.

data/TODO.perf/09-adoption-lift-fast-path.md

@@ -0,0 +1,38 @@
+# 09 — Adoption-lift fast path + binding create via C (#204 ask 3, #149 continuation)
+
+Status: DONE (1.9.163.5)
+
+Binding create x2 + attach measured 4.1us vs Nokogiri 1.5us. The
+#178/#208 namespace lift + pruning runs on EVERY attach and costs
+several FFI round-trips (own definitions, prefix read, in-scope
+walk) even when it is a provable no-op. Add a one-dispatch C
+predicate `Native.ns_lift_needed?(addr)`: false when the node
+carries no namespace declarations AND its name has no prefix —
+the overwhelmingly common programmatic-build shape. add_child and
+friends skip the lift entirely on false. Also route binding
+create_element/create_text_node through the ext (one C call +
+binding-wrapper construction in C — no FFI marshaling) when
+auto-enabled.
+
+## Outcome (1.9.163.5)
+
+Three layers landed:
+1. `Element.skip_adoption_lift?` — non-elements skip outright
+   (lift no-ops them anyway); elements consult
+   `Native.ns_lift_needed?` (two C calls: own-declaration count +
+   resolved URI). Hoisted ABOVE the target's `namespaces`
+   materialization at all five mutation sites (add_child,
+   prepend_child, both sibling inserts, root=) — a fresh parent
+   no longer pays the in-scope collection FFI round-trips per
+   attach. Measured effect: add_child on a fresh parent
+   1678 -> 506ns.
+2. `Native.create_binding_element/text` build the binding wrapper
+   in C (one C call + wrapper + identity-cache store; no FFI
+   marshaling). Document.create/create_element/create_text_node
+   route through them when auto-enabled.
+3. `Native.append_binding_child` — gates + predicate + version
+   bump + engine append in ONE dispatch (Qnil = child needs the
+   lift, Ruby falls back). Element#add_child's node branch uses
+   it; namespaced children still lift (spec-pinned). The #204
+   ask-3 shape (create x2 + attach) went 4.1us -> ~1.2us measured
+   under host load 12-19 — at or past the Nokogiri row (1.5us).

data/TODO.perf/10-bulk-attribute-materialization.md

@@ -0,0 +1,20 @@
+# 10 — Bulk attribute materialization for the binding
+
+Status: DONE (1.9.163.5)
+
+Element#attributes / #each_attribute / #keys / #values walk the
+attribute list with one FFI call per attribute (name + value per
+row). One C pass materializes the {name => value} hash and the
+key/value arrays in a single walk. Gate: attribute-heavy cold
+reads improve; #attributes semantics unchanged (memoized, version
+invalidated).
+
+## Outcome (1.9.163.5)
+
+`Native.bulk_attr_faces` builds {name => Attr} + the values hash
+in one C walk (Attr value objects: name/value/element ivars,
+c_handle left nil); Element#attributes rides it when
+auto-enabled and memo-stamps both hashes. Measured (load 12-19):
+Element#attributes on a 5-attr element ~134-151ns vs Nokogiri
+~1107-1165ns (~8x). The values-only shape
+(`Native.bulk_attributes`) backs the legacy path.

data/TODO.perf/11-moxml-gap-battery.md

@@ -0,0 +1,18 @@
+# 11 — The #204 gap table as a battery leg
+
+Status: DONE (1.9.163.5)
+
+Reproduce moxml's gap table rows locally (parse 30KB, to_xml,
+[] / content / name reads, set_attribute, create x2 + attach,
+typed walk) in benchmark/native_vs_binding.rb so every perf round
+tracks the exact rows the 2x mandate measures — both surfaces,
+interleaved, load-gated.
+
+## Outcome (1.9.163.5)
+
+benchmark/native_vs_binding.rb gained the gap rows: []/content/
+name repeat reads (binding + native), set_attribute, and the
+build (create x2 + attach) row, all interleaved best-of behind
+the file's load gate (skips > 20). `set_attribute` itself became
+a C-bound face this round (Native.set_binding_attribute: gates +
+version bump + engine write in one dispatch).