leptris 1.9.199.0-arm-linux

data/docs/adr/0001-lockstep-mirror.md

@@ -0,0 +1,17 @@
+# ADR 0001: ffi.rb mirrors the public header
+
+## Context
+ffi.rb attaches ~30 functions the binding never calls (typed
+attribute accessors, copy-inserts, allocator hooks, xinclude
+getters). Reviews keep proposing to strip them.
+
+## Decision
+Keep attaching every public-header symbol. The mirror makes the
+attached-vs-exported audit (`nm -gU` on a fresh build) a drift
+detector: when libleptris changes its surface, the audit fails
+loudly instead of the binding silently missing ABI.
+
+## Consequences
+Attachment is declarative and cheap; unused functions cost nothing.
+When a call site starts using a string-returning mirror function,
+add it to the UTF8_RETURNS wrap-list (ADR 0002).

data/docs/adr/0002-utf8-at-the-seam.md

@@ -0,0 +1,19 @@
+# ADR 0002: UTF-8 at the seam, both faces
+
+## Context
+The headers contract every C string as UTF-8, but FFI's implicit
+string conversion returns ASCII-8BIT — on returns (2026-08-25,
+release 1.9.3) and on FFI::Function callback params (2026-08-25,
+1.9.4; only `characters` was corrected before).
+
+## Decision
+The encoding policy lives entirely in ffi.rb: the UTF8_RETURNS
+wrap-list for called string-returning attaches, plus
+read_owned_string, CStringArray.to_ruby, and the SAX adapter's
+nil-safe utf8 for callback params. Mirror-only attachments stay
+raw; they join the list when a call site appears.
+
+## Consequences
+Memoized readonly results can safely cache strings (they freeze as
+UTF-8, the correct encoding, not BINARY). Non-ASCII content can no
+longer leak BINARY into consumer code.

data/docs/adr/0003-readonly-memoization-pattern.md

@@ -0,0 +1,34 @@
+# ADR 0003: memoization stays hand-rolled; writable docs memoize via version stamps
+
+## 2026-08-27 extension (leptris-ruby 1.9.14)
+
+Writable documents now memoize too: Document carries a mutation
+version advanced at every mutation gate (Node#ensure_writable!,
+root=, add_pi), and each memoized field stores its OWN version
+stamp (`return @x if memo_hit?(@x_version)`). A shared node-level
+stamp was tried and rejected — one field's recompute resurrects
+another field's stale memo. Readonly semantics are unchanged
+(their version never advances). Round X's "version-stamp rejected:
+the compare costs the read" was corrected: the compare is cheap
+against multi-FFI reads.
+
+The hand-rolled per-site pattern (below) still stands; only the
+guard gained a version argument.
+
+
+## Context
+Every readonly-mode read repeats the same three lines:
+`return @x if readonly_cached?(:@x); v = compute; @x = v if
+@document&.readonly?`. ~25 sites. Reviews keep proposing a
+`readonly_memo(ivar) { }` concentrator.
+
+## Decision
+Keep the pattern hand-rolled. Concentrating it requires
+instance_variable_get/set — banned project-wide (encapsulation:
+no reaching into another object's ivars, and metaprogrammed ivar
+access hides the memo identity from readers).
+
+## Consequences
+The repetition IS the invariant — greppable, one file at a time.
+New readonly reads copy the three lines verbatim; a site that
+deviates is visible in review.

data/docs/adr/0004-lifetime-guard.md

@@ -0,0 +1,21 @@
+# ADR 0004: borrowed handles validate their lender
+
+## Context
+Before 1.9.5, only Document's own methods checked freed state:
+`doc.free; node.name` read freed memory silently (verified
+returning ""), stale mutations risked segfaults.
+
+## Decision
+`Node#ensure_alive!` guards every c_ptr-derefercing entry point —
+after memo checks (memoized readonly results stay check-free) and
+folded into `ensure_writable!` for mutations. The check is the
+cheapest sufficient one: `Document#c_ptr.nil?` (#free nils it; the
+GC finalizer cannot fire while any handle exists). `Document#freed?`
+is the accurate public predicate.
+
+## Consequences
+Measured cost (harness, 1.9.4→1.9.6): visible only on the
+single-cheapest call shape (Element#[] hot loops, ~13-28%); every
+other loop at parity. Accepted as the price of the contract;
+readonly hot loops have the memoized attributes/keys alternatives.
+Do not re-litigate without a C-side lifetime mechanism.

data/docs/adr/0005-autoload-manifest-ordering.md

@@ -0,0 +1,19 @@
+# ADR 0005: the eager FFI require runs after autoload registration
+
+## Context
+Issue #53: eager-loading ffi.rb from inside `module Leptris`
+BEFORE `autoload :XML` was registered let ffi.rb's module opening
+create Leptris::XML first; the registration was shadowed, xml.rb
+never loaded, and the whole API was unreachable
+(constants == [:FFI]).
+
+## Decision
+leptris.rb: register `autoload :XML` first, then the eager
+`require "leptris/xml/ffi"` at top level — ffi.rb's module opening
+triggers the autoload, landing FFI inside the real manifest module;
+a downstream `require "leptris/xml"` is then a no-op. A subprocess
+spec guards the cold path (the in-process suite cannot see it).
+
+## Consequences
+Any new eager require in leptris.rb must come after the autoload
+block. Eager resolution at require time (issue #49) is unchanged.

data/docs/adr/0006-ruby-variant-policy.md

@@ -0,0 +1,25 @@
+# ADR 0006: the ruby-platform variant ships as the fallback, unvendored
+
+## Context
+The 1.9.0-era CHANGELOG said "never publishes ruby-platform releases
+without the vendored library — platform variants only", and an early
+fix removed the `gem:native:any` task. The 1.9.0 lockstep restored
+the `ruby` matrix entry deliberately, and every release since has
+published the variant — practice contradicting the recorded policy.
+
+## Decision
+The `ruby`-platform gem ships as the fallback/source variant WITHOUT
+a vendored library, by design. It is safe because library resolution
+is eager (issue #49): on a machine without a usable libleptris the
+gem fails at `require` with the actionable remedy (install the
+platform-specific variant or set LEPTRIS_LIB_PATH) instead of deep
+inside Document.parse. Bundler prefers platform-specific gems
+wherever they exist (9 of 10 published variants are precompiled);
+the ruby variant serves source installs and exotic platforms that
+accept providing their own library.
+
+## Consequences
+Do not re-propose removing the `platform: any` release leg without
+new evidence that bundler misresolves it in practice. A future
+change to the eager-load behavior (ADR 0005 ordering aside) must
+keep the ruby variant failing loudly at require time.

data/ext/build_windows_native.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+# Builds the native read layer DLL for the CURRENT Ruby and
+# installs it under its minor-versioned name
+# (lib/leptris/xml/native_<major>_<minor>.so).
+#
+# #207/#227: a PE DLL cannot resolve Ruby imports lazily — it
+# must bind the build Ruby's x64-ucrt-rubyNNN.dll. One DLL per
+# supported minor therefore ships in the Windows platform gems,
+# and native_layer picks by RUBY_VERSION at require.
+#
+# The name is DOT-FREE: MRI derives a C extension's init symbol
+# from the require feature's basename cut at the first dot, so
+# native_3_3.so resolves Init_native_3_3 (a valid C symbol,
+# exported by native.c) — a dotted native-3.3.so would make Ruby
+# look for "Init_native-3", which cannot exist.
+
+require "rbconfig"
+require "fileutils"
+
+root = File.expand_path("..", __dir__)
+ext_dir = File.join(root, "ext", "leptris", "native")
+minor = RUBY_VERSION[/\A\d+\.\d+/]
+minor_us = minor.tr(".", "_")
+
+Dir.chdir(ext_dir) do
+  system(RbConfig.ruby, "extconf.rb") or abort "extconf failed under #{RUBY_VERSION}"
+  # mkmf's link binds the CURRENT Ruby's runtime DLL — exactly
+  # what the versioned naming is for.
+  success = system("make")
+  abort "make failed under #{RUBY_VERSION}" unless success
+  so = Dir.glob("native.{so,dll}").first
+  abort "native bundle not produced under #{RUBY_VERSION}" unless so
+  dest = File.join(root, "lib", "leptris", "xml", "native_#{minor_us}.so")
+  # The artifact must reference only this minor's Ruby DLL.
+  imported = `strings #{so} 2>/dev/null`[/[a-z0-9-]*ruby\d{3,}\.dll/i]
+  if imported && !imported.include?("ruby#{minor.delete('.')}")
+    abort "#{so} imports #{imported} but was built under #{RUBY_VERSION} — refuse to mis-name it"
+  end
+  FileUtils.cp(so, dest)
+  puts "Installed native layer for Ruby #{minor} -> #{dest} (#{imported || 'no ruby dll string found'})"
+end

data/ext/leptris/native/extconf.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+# The bundle must load into ANY Ruby (not the building runner's):
+# macOS links with -undefined dynamic_lookup (Ruby symbols resolve
+# from the loading interpreter — the standard C-ext convention)
+# and a conservative deployment target; libruby is never linked.
+ENV["MACOSX_DEPLOYMENT_TARGET"] ||= "11.0"
+require "mkmf"
+if RUBY_PLATFORM =~ /darwin/
+  # Robust across mkmf versions: older rubies drop $(ldflags)
+  # from the bundle link line, so pin BOTH the compile and link
+  # variables. -undefined dynamic_lookup is the standard C-ext
+  # convention (Ruby symbols resolve from the loading
+  # interpreter); -mmacosx-version-min keeps the bundle loadable
+  # on older user OSes than the building runner.
+  min = " -mmacosx-version-min=#{ENV['MACOSX_DEPLOYMENT_TARGET']}"
+  lookup = " -undefined dynamic_lookup"
+  [$LDFLAGS, $DLDFLAGS, $CFLAGS, $CXXFLAGS].each do |var|
+    var << min unless var.include?(min.strip)
+  end
+  [$LDFLAGS, $DLDFLAGS].each do |var|
+    var << lookup unless var.include?("dynamic_lookup")
+  end
+  # setup-ruby builds carry the RUNNER's absolute libruby path in
+  # LIBRUBYARG_SHARED — recorded as an LC_LOAD_DYLIB in the
+  # bundle, unresolvable on user machines. A Ruby extension
+  # resolves Ruby symbols from the loading interpreter; never
+  # link libruby.
+  # BOTH maps: mkmf's Makefile interpolates from MAKEFILE_CONFIG,
+  # not CONFIG — clearing only CONFIG is a silent no-op (caught via
+  # the build-log otool on the runner).
+  RbConfig::CONFIG["LIBRUBYARG_SHARED"] = ""
+  RbConfig::CONFIG["LIBRUBYARG_STATIC"] = ""
+  RbConfig::MAKEFILE_CONFIG["LIBRUBYARG_SHARED"] = ""
+  RbConfig::MAKEFILE_CONFIG["LIBRUBYARG_STATIC"] = ""
+end
+if Gem.win_platform?
+  # Windows names the artifact per Ruby minor, DOT-FREE (#227
+  # fix): MRI derives the init symbol from the basename cut at
+  # the first dot, so native_3_4.so needs Init_native_3_4
+  # exported. GNU ld auto-exports only when no explicit export
+  # is present — pin the export table with a .def file so the
+  # wrapper init names are certain to be exported.
+  def_path = File.expand_path("native_exports.def", __dir__)
+  File.write(def_path, <<~DEF)
+    EXPORTS
+    Init_native
+    Init_native_3_3
+    Init_native_3_4
+    Init_native_4_0
+  DEF
+  win_def = " #{def_path.tr('/', '\\\\')}"
+  $DLDFLAGS << win_def unless $DLDFLAGS.include?("native_exports.def")
+end
+create_makefile("leptris/xml/native")