leptris 1.9.93.0-aarch64-linux → 1.9.100.0-aarch64-linux

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0ebdc082d76b283134bda0418f21d6b65358f2391a585f831b3d7798883f07b5
-  data.tar.gz: ccfb4ffc72881b4333fc529b772554b0d9fec1698ec7072ead485726e8718762
+  metadata.gz: 44ed8b08a6de1caebd58bc36a7851af7910e715c741a3ba9df613559d1fd3962
+  data.tar.gz: 725b2f7a0efdfa263178c7761d98f1458ed8ee028c8750e0ef475c304450c2c8
 SHA512:
-  metadata.gz: e14942acf892ed7be8e4e699556fd2f2576c275102f1c0cc6ddae2b481dc47567a3744b07446670d07965b147a216e970824f74fafe506e2dad0cc12988446ac
-  data.tar.gz: d37b4f9268de085bd276dc58d64530d2be975509298627bbe09dfad766c412352ff441ece4573a6068970aafb6a5a6df987dbd4039e162b3389f3e86a0c09faa
+  metadata.gz: 5ffd33f5dbc8ca062921ae57cc1b3114cad81a7c811a5c6a49d34cf6fc035d877c496354b4e0a0c29e75aaf24539a04c51b2ee33b49b9f52916a692076170250
+  data.tar.gz: f98c4c66fe9b83ae722bdc18bf61093ff2e25fa96b861d5f0bd6df027e4a16285cb15061b70ab387fd77cc0123459f09058d683b66510abd8ec4a112da215cb6

data/CHANGELOG.md

@@ -5,56 +5,161 @@ All notable changes to Leptris will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [1.9.93.0] - 2026-09-06
+## [1.9.100.0] - 2026-09-07
 
 ### Changed
 
-- **Lockstep with libleptris 1.9.93** (1.9.91 → 1.9.93; no new C
-  surface — the audit holds at 261/261):
-  - 1.9.93 — **predicate-pattern dispatch indexes** (leptris/
-    leptris#866, filed from this binding last round): name keys
-    (a `foo` element never evaluates `item[...]` candidates) and a
-    literal `(name, attr, value)` bucket. Our exact fixture —
-    120 `item[@k='N']` templates over 2400 elements — went
-    **102.4 ms / 0.6x Nokogiri → 2.65 ms / 20.3x faster**.
-  - 1.9.92 — **append-tail cache fix** (leptris#848 follow-up):
-    the 8-slot direct-mapped cache thrashed on the HTML shape
-    (persistent <body> alternating with fresh parents — O(n²)
-    over 40k nodes); 64 slots. Entity-laden HTML at scale
-    (1.4 MB, 120k entity refs): **12.2 ms vs Nokogiri's 44.5 ms —
-    3.6x faster** (was 6x BEHIND libxml2 before the fix).
-  - 1.9.91 — the #659 Nokogiri-parity reference corpus (372/1555
-    exact tree matches, both conformance and parity floors
-    pinned) — test infra upstream; direction recorded: WHATWG
-    conformance with HTML4/HTML5 as distinct modes.
+- **Lockstep with libleptris 1.9.100** (1.9.94 → 1.9.100 — seven
+  releases: TLS last-root memo, element-level ext entries,
+  namespace-fixup walk gating, **#875 dispatch index fix**,
+  namebp backpointer fix, **#869 `leptris_node_digest` Merkle
+  subtree digest**, streaming emission Phase 1). Three new public
+  symbols attached (audit 264/264):
+  - `leptris_element_serialize_ext[_sized]` (1.9.95, #882):
+    element-level `expand_empty` serialization — wired through
+    `Element#to_xml(expand_empty: true)` for libxml2's
+    `NO_EMPTY_TAGS` parity.
+  - `leptris_node_digest` (1.9.99, #869): content-defined 64-bit
+    Merkle digest of a subtree — wired through `Node#digest(drop_ws:)`
+    with structural-equality semantics.
+
+- **#875 sentinel gate extended**: verified 97/97, 120/120, **500/500**
+  on this build — the 1.9.93 dispatch overflow is gone (the
+  upstream fix used dynamic resize instead of the bare-continue
+  cap; the predicate-pattern index is back to ~25 ms on the
+  120-template fixture — fast and correct).
+- **Vendored `SerializeExtStruct` layout refreshed** to mirror the
+  new C layout (`expand_empty: :int`).
+- **#153 binding fix-forward**: leptris-ruby PR #154 (open,
+  ResultAttr wrap) — the engine needed nothing. The fix will
+  ride a follow-up binding release once it merges.
+
+### Fixed
+
+- **Namebp backpointer validity after QName split** (engine, 1.9.98)
+  — the round-21 mutation backpointer is only valid while `name`
+  points at the carve slot; prefixed names now drop the flag when
+  `#846`'s QName split advances past the colon.
+- **Namespace-fixup walk gating** (engine, 1.9.96): the
+  result-document walks are now gated on `has_namespaces` — the
+  common dispatch shape (no namespaces in the result) is a single
+  flag check.
+- **TLS last-root memo** (engine, 1.9.94): the
+  `leptris_element_get_document` hot path answers consecutive
+  same-tree queries with a single pointer compare.
+
+### Performance
+
+- **Streaming emission Phase 1** (engine, 1.9.100, gated): a
+  compile-time gate admits v1.x namespace-free literal elements,
+  text/value-of, comment/PI, select-only variables, and control
+  flow into direct byte emission — the result DOM is not
+  materialized for those safe shapes. Everything else keeps the
+  result-tree path byte-identically. Run-based emitters, 1306/1306
+  ctest.
+
+## [1.9.92.2] - 2026-09-07
+
+### Changed — restructure round (TODO.restructure/01-06, all DONE)
+
+- **Constraint compliance**: the last `respond_to?` duck checks in
+  lib are gone — `Document.parse`/`Iterparse.parse` dispatch on
+  `is_a?(String)` (readable objects read; garbage fails honestly),
+  `SAX::Parser#parse` dispatches on explicit `IO, StringIO,
+  Pathname` types. Audit clean: no `send`, no
+  `instance_variable_set/_get`, no `require_relative`; the two
+  in-file-documented require exceptions (gem-root version, eager
+  FFI bootstrap) recorded in the audit.
+- **Deep-copy seam**: `Document.copy_of` is the single authority
+  for "C-copy an element as a new document's root" —
+  `Node#dup`/`Element#dup`/the indent-unit path delegate (three
+  inline duplicates retired; the drift that twice flipped dup
+  across #696/#721/#812 can no longer happen).
+- **Evaluation-context seam**: new `EvaluationContext` value object
+  (autoloaded) resolves Document-or-Element receivers for
+  `XPath#eval` and `XQuery#eval` — one typed seam, one
+  ArgumentError shape.
+- **Spec MECE**: HTML specs live in `spec/xml/html_spec.rb`;
+  pure-`#xpath` blocks (value-level surface, 2.0 ledger, type
+  operators, xs: constructors, ResultText) live in
+  `xpath_spec.rb`; `xquery_spec.rb` carries only the XQuery face.
+  Count-neutral: 535 examples before and after.
+- **Docs**: README gains a Memory section (finalizer-drain
+  semantics, held-workload profile — #147 option A); CLAUDE.md's
+  architecture map and conventions refreshed.
+
+No behavior change (same FFI sequences, delegation only); suite
+green throughout. The perf battery window was unavailable (shared
+machine at load 184) — neutrality is structural: identical call
+sequences plus one cold-path allocation per expression evaluation.
+
+## [1.9.92.1] - 2026-09-06
+
+### Changed — hotfix: replaces libleptris 1.9.93
+
+- **Re-pinned to libleptris 1.9.92** (from 1.9.93): the 1.9.93
+  predicate-pattern dispatch index silently drops templates past
+  96 distinct literal patterns (leptris/leptris#875 — wrong
+  transform output with no error). 1.9.92 predates the index and
+  dispatches correctly for any pattern count; the #875 sentinel
+  spec un-pends (97/97, 120/120 verified on this build) and stays
+  as the guard. **1.9.93.0 and 1.9.93.1 are yanked.**
+- The honest cost: predicate-pattern dispatch returns to the
+  1.9.92 ladder (~102 ms on the 120-template fixture vs 1.9.93's
+  2.65 ms — but with correct output). Everything else from the
+  1.9.88-1.9.92 perf wave (bare-name dispatch indexes, the
+  append-tail cache — 3.6x Nokogiri on entity-laden HTML) is
+  retained.
+- When the #875 fix releases upstream, the next `{C}.0` re-adopts
+  the index and re-runs this exact fixture as the gate.
+
+## [1.9.93.1] - 2026-09-06
+
+### Changed
+
+- **Lockstep with libleptris 1.9.93** — #866: predicate-pattern
+  dispatch indexes (name keys + literal @attr='value' index). The
+  reported fixture drops 82 → 2ms per transform (40x; ~28x ahead
+  of libxslt); the 2000-book scorecard is 3.93ms.
+
+## [1.9.92.0] - 2026-09-05
+
+### Changed
+
+- **Lockstep with libleptris 1.9.91–1.9.92** — #659 Nokogiri
+  parity reference (372/1555 exact-match floor; WHATWG-conformance
+  direction recorded) and the append-tail cache fix: entity-laden
+  HTML 291ms → 42ms per 1.3MB page (6.8x), now at par to 1.15x
+  AHEAD of libxml2 — no sub-1x HTML parse shape remains.
 
 ## [1.9.90.0] - 2026-09-05
 
 ### Changed
 
-- **Lockstep with libleptris 1.9.90** (1.9.88 → 1.9.90; no new C
-  surface — the audit holds at 261/261):
-  - 1.9.88: template dispatch indexes (#682) — named-template
-    hash, per-mode candidate buckets, bare-Name fast path.
-  - 1.9.89: `fn:analyze-string` group spans fixed (leptris/leptris
-    #857): pmatch offsets are subject-relative but were applied
-    from the match start, and excess regexec slots read stale
-    stack data — single-group matches leaked the following
-    non-match into group values. Two specs pin the corrected
-    shapes (`12`, not `12cd`) and the call-order independence.
-  - 1.9.90: html5lib tree-construction corpus harness upstream
-    (193/1753 passing with a red-list snapshot; the implied-head /
-    foster-parenting bucket shapes the next HTML slices).
+- **Lockstep with libleptris 1.9.90** — #659: the html5lib
+  tree-construction corpus harness (vendored snapshot, falsifiable
+  pass-count floor, red-list) and the empty-shape-inputs fix
+  (stray-end-only / doctype-only / empty input parse to the empty
+  document instead of failing).
 
-### Fixed
+## [1.9.89.0] - 2026-09-05
+
+### Changed
+
+- **Lockstep with libleptris 1.9.89** — #857: fn:analyze-string
+  group spans (subject-relative pmatch offsets + exact nmatch —
+  single-group regexes leaked the following non-match, and results
+  were call-order dependent).
+
+## [1.9.88.0] - 2026-09-05
+
+### Changed
 
-- **Dispatch perf observation filed upstream (leptris/leptris
-  #866)**: predicate patterns (`match="item[@k='N']"` — the common
-  real-world shape) still pay the candidate ladder after 1.9.88;
-  measured 102.4 ms vs Nokogiri's 58.2 ms on a 120-template /
-  2400-element fixture (bare names ride the fast path). Suggested
-  per-Name sub-bucketing; offered to re-measure any experimental
-  build.
+- **Lockstep with libleptris 1.9.88** — #682 template dispatch
+  indexes: named-template hash, per-mode candidate buckets, and a
+  bare-Name pattern fast path. Template-heavy dispatch 10.21 →
+  5.56 ms per transform (1.83x); gap to in-process lxml/libxslt
+  narrows 3.27x → 1.78x.
 
 ## [1.9.87.0] - 2026-09-05
 

data/CLAUDE.md

@@ -39,24 +39,32 @@ The C DOM is the single source of truth; Ruby objects are thin FFI
 handles. One Ruby method = one FFI call wherever possible.
 
 ```
-lib/leptris.rb                — Leptris::VERSION
+lib/leptris.rb                — Leptris::VERSION + eager FFI bootstrap
 lib/leptris/xml.rb            — autoload registry, error classes,
-                                Leptris::XML.parse / parse_file
+                                Leptris::XML.parse / parse_html
 lib/leptris/xml/ffi.rb        — every public C declaration + seam
                                 helpers (check_status, read_owned_string,
-                                status_message)
+                                serialize_into_string, scratch buffers)
 lib/leptris/xml/document.rb   — the only C-memory owner (finalizer);
-                                factories, PI accessors, exslt, last_error
+                                factories; Document.copy_of: the single
+                                deep-copy seam behind Node#dup/Element#dup
 lib/leptris/xml/node.rb       — Node.wrap: the ONLY wrapper constructor
-                                (identity cache + type dispatch)
+                                (identity cache + type dispatch,
+                                ResultText for sequence items)
 lib/leptris/xml/element.rb    — attributes via the v1.1.0 iteration
-                                face; namespace/mutation surface
-lib/leptris/xml/node_set.rb   — lazy XPath results; batch fetch via
-                                get_nodes_ex
-lib/leptris/xml/searchable.rb — xpath/css/at_*; namespace-bound path
+                                face; namespace= (nil-detach/rebind)
+lib/leptris/xml/result_text.rb — sequence/map/array result items
+                                (values captured at materialization)
+lib/leptris/xml/node_set.rb   — lazy XPath/XQuery results; batch fetch
+                                via get_nodes_ex; ResultText capture
+lib/leptris/xml/searchable.rb — xpath/css/at_*; result materialization
+lib/leptris/xml/evaluation_context.rb — receiver -> (document,
+                                context-node ptr) for the expression faces
 lib/leptris/xml/xpath.rb      — compiled expressions (parse once,
                                 eval many)
-lib/leptris/xml/sax/          — callback SAX
+lib/leptris/xml/xquery.rb     — compiled XQuery 1.0 core face
+lib/leptris/xml/xslt.rb       — compiled XSLT 1.0-3.0 face
+lib/leptris/xml/sax/          — callback SAX (streaming + DOM dispatch)
 lib/leptris/xml/pull.rb       — StAX-style pull parsing
 lib/leptris/xml/iterparse.rb  — bounded-memory element iteration
 lib/leptris/xml/serialization.rb — serialize/c14n (Document + Element
@@ -81,9 +89,12 @@ lib/leptris/xml/css_to_xpath.rb   — minimal CSS translation
 
 ## Conventions
 
-- Autoload only — no `require_relative` inside `lib/`.
-- No `instance_variable_set`/`_get` across objects; no `respond_to?`
-  type checks; specs use real documents, never doubles.
+- Autoload only — no `require_relative` or intra-library `require`
+  inside `lib/` (sanctioned exceptions, with reasons in-file:
+  `leptris/version` at the gem root and the eager FFI bootstrap).
+- No `instance_variable_set`/`_get` across objects; no `send` to
+  private methods; no `respond_to?` type checks (dispatch on types
+  with `is_a?`/`case`); specs use real documents, never doubles.
 - New C surface: attach in `ffi.rb`, sugar where it earns its keep,
   specs against a locally built library, CHANGELOG, lockstep release.
 - All changes via PRs; no AI attribution; `git add` explicit paths.

data/README.adoc

@@ -548,6 +548,37 @@ is valid only while its Document is alive.
 * Don't hold a `Node` reference past the lifetime of its `Document`.
   The C memory is gone; using the wrapper is undefined behaviour.
 
+== Memory behavior
+
+Two facts worth knowing for memory-sensitive workloads:
+
+**Finalizers drain asynchronously.** When a Document becomes
+unreachable, its C tree frees when Ruby runs the registered
+finalizer — and MRI executes finalizers on its own scheduling, not
+synchronously inside `GC.start`. A tight `GC.start` loop can leave
+the last document's wrappers (flagged `uncollectible`) alive
+indefinitely; a short wall-clock yield drains the queue:
+
+[source,ruby]
+----
+doc = Leptris::XML::Document.parse(xml)
+doc.root.children   # ...
+doc = nil
+GC.start
+sleep 0.05          # yield to the finalizer queue
+GC.start            # now fully collected, C tree freed
+----
+
+**Held documents carry the Ruby wrapper layer.** A fully walked,
+held document costs roughly +552 kB of wrapper objects on top of
+the C tree's +456 kB (about 1.57x Nokogiri for the same held
+shape) — the measured cost of the FFI-only, no-compile-at-install
+architecture: every wrapped node is a small Ruby object holding an
+`FFI::Pointer`. Parse-and-discard workloads are unaffected (the
+tree is the dominant cost and the wrappers die young). See
+https://github.com/leptris/leptris-ruby/issues/147[#147] for the
+analysis and the open TypedData options.
+
 == Errors
 
 All Leptris errors descend from `Leptris::XML::Error`:

data/Rakefile

@@ -8,7 +8,7 @@ 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.93"
+LIBLEPTRIS_VERSION = "1.9.100"
 
 CMAKE_FLAGS = %w[
   -DCMAKE_BUILD_TYPE=Release

data/TODO.restructure/01-constraint-compliance-audit.md

@@ -0,0 +1,40 @@
+# 01 — Constraint compliance audit (autoload / send / ivar / respond_to?)
+
+Status: DONE
+
+## Findings (2026-09-07 scan)
+
+- `.send(` in lib: none.
+- `instance_variable_set`/`_get` across objects: none.
+  (`instance_variable_defined?(:@readonly_document)` in node.rb is
+  a read-only memo predicate on self — not a set/get; reviewed and
+  kept.)
+- `require_relative` in lib/spec: none.
+- `respond_to?` type checks — three real violations in lib + one
+  in spec (fixed below).
+
+## Sanctioned exceptions (documented, load-bearing)
+
+- `leptris.rb` requires `leptris/version`: autoload cannot serve a
+  bare constant (`Leptris::VERSION`), and the release workflow's
+  bump step seds exactly this file.
+- `leptris.rb` requires `leptris/xml/ffi` AFTER registering
+  `autoload :XML`: eager native-library resolution (issue #49)
+  with an ordering subtlety documented in the file (issue #53 —
+  requiring earlier shadows the manifest module and hides the API).
+- `require "ffi"` at the top of FFI-using files: external gem (the
+  ban is on intra-library requires), needed because class bodies
+  reference `::FFI::AutoPointer` at definition time.
+
+## Fixes
+
+- [x] `Document.parse`: `respond_to?(:read)` duck check → `is_a?(String)`
+      branch (String passes through; readable objects read; anything
+      else fails honestly with NoMethodError instead of silently
+      parsing a garbage `to_s`).
+- [x] `Iterparse.parse`: same replacement.
+- [x] `SAX::Parser#parse`: lambda-guard `respond_to?(:read)` → explicit
+      `when IO, StringIO, Pathname` branch (typed, MECE; previously
+      anything readable dispatched, narrowing to the read-capable
+      types the API documents).
+- [x] `features_namespace_spec.rb`: dropped the `respond_to?` null-guard.

data/TODO.restructure/02-deep-copy-seam.md

@@ -0,0 +1,21 @@
+# 02 — Deep-copy seam: one authority for "copy as a new document's root"
+
+Status: DONE
+
+The create-document → element_copy → wrap → attach-as-root sequence
+was duplicated in three places (`Node#dup`, `Element#dup`,
+`Serialization.to_xml_element_unit`) — a DRY/MECE violation with
+drift risk (it already drifted twice across the #696/#721/#812
+rounds).
+
+## Change
+
+- [x] `Leptris::XML::Document.copy_of(element)` — the single
+      authority: creates the target document, C-copies the element,
+      wraps, attaches as root, returns the copy (model-driven: the
+      Document owns its construction semantics).
+- [x] `Node#dup` / `Element#dup` / `to_xml_element_unit` delegate
+      to it; the three inline copies removed.
+- [x] Existing dup/copy specs (byte-parity, namespaces, comment/PI,
+      detached-from-original, #130 flatness) all pass unchanged —
+      behavior-neutral by construction.

data/TODO.restructure/03-evaluation-context-seam.md

@@ -0,0 +1,18 @@
+# 03 — Evaluation-context seam for the expression faces
+
+Status: DONE
+
+`XPath#eval` and `XQuery#eval` each hand-rolled "resolve a Document
+or Element receiver into (owning document, context-node pointer)"
+with their own argument errors — duplicated logic, drift-prone as
+faces multiply (XPath / XQuery / future).
+
+## Change
+
+- [x] New `Leptris::XML::EvaluationContext` (autoloaded from
+      `lib/leptris/xml.rb`, per the autoload rule): a value object
+      with `.of(receiver)` and `#document` / `#context_node_ptr`
+      readers; raises ArgumentError for anything but a Document or
+      Element — one typed seam.
+- [x] `XPath#eval` and `XQuery#eval` resolve through it; their
+      private duplicated resolvers removed.

data/TODO.restructure/04-spec-mece-restructure.md

@@ -0,0 +1,20 @@
+# 04 — Spec MECE: one domain per file
+
+Status: DONE
+
+The lockstep rounds accreted specs into whichever file was open:
+`xquery_spec.rb` carried HTML-parsing and pure-XPath blocks;
+`document_spec.rb` carried the HTML suite. Reorganized by domain —
+count-neutral moves only, no example text changed.
+
+## Moves
+
+- [x] All HTML specs (`parse_html` behaviors, characterization
+      gates, head-content lift, PI constructs) → new
+      `spec/xml/html_spec.rb`.
+- [x] Pure-`#xpath` blocks (XPath 3.1 value-level surface, 2.0
+      ledger, type operators, format-number, analyze-string,
+      catalog slices) → `spec/xml/xpath_spec.rb`.
+- [x] `xquery_spec.rb` now contains only the XQuery face;
+      `document_spec.rb` only Document behaviors.
+- [x] Total example count unchanged before/after (audit gate).

data/TODO.restructure/05-memory-documentation.md

@@ -0,0 +1,13 @@
+# 05 — README: Memory section (#147 resolution, option A)
+
+Status: DONE
+
+- [x] Document the two findings from leptris-ruby#147:
+      finalizer semantics (objects stay `uncollectible` until the
+      async finalizer queue drains — retention tests must yield
+      wall-clock time, not just `GC.start`) and the held-workload
+      profile (wrappers ~+552 kB/doc vs the C tree's +456 kB;
+      ~1.57x Nokogiri held) as the documented cost of the
+      FFI-only architecture.
+- [x] Note the TypedData trade-off and the open option (A/B/C) on
+      the issue for the maintainer.

data/TODO.restructure/06-architecture-map-refresh.md

@@ -0,0 +1,12 @@
+# 06 — CLAUDE.md architecture map refresh
+
+Status: DONE
+
+The map predated XQuery, ResultText, HTML parsing, the XSLT/XPath
+compiled faces, and the copy/evaluation-context seams.
+
+- [x] File map updated (xquery.rb, result_text.rb, xslt.rb,
+      xpath.rb, evaluation_context.rb, Document.copy_of seam).
+- [x] Conventions now name the constraint set explicitly (no
+      respond_to? type checks in lib; send/ivar rules were already
+      there).

data/TODO.restructure/07-external-gates.md

@@ -0,0 +1,18 @@
+# 07 — External gates (blocked outside this repo; tracked, not completable here)
+
+Status: TRACKED
+
+- [ ] **leptris/leptris#875 re-adoption**: when the fix releases,
+      re-pin to `{C}`, un-pend the sentinel spec, re-run the
+      96/97/120 boundary + the 120-template perf fixture as the
+      release gate, ship `{C}.0`. (1.9.93.0/1.9.93.1 yanked;
+      1.9.92.1 is the standing replacement.)
+- [ ] **utf8proc build decision** (owner): `fn:normalize-unicode`
+      requires utf8proc, compiled out of the vendored platform
+      builds — enabling it changes the vendored binary surface.
+      Pending spec documents it.
+- [ ] **#147 option A/B/C** (owner): A (document — DONE via 05),
+      B (FFI+native `leptris-typed` variant gem — roadmap), C
+      (revisit if ruby-ffi grows TypedData).
+- [ ] **#683 remainder** (upstream): 3.1 string templates, XQuery
+      3.1 territory.

data/lib/leptris/version.rb

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

data/lib/leptris/xml/document.rb

@@ -58,7 +58,7 @@ class Leptris::XML::Document
   end
 
   def self.parse(xml_or_io, options: nil, readonly: false, recover: false)
-    xml = xml_or_io.respond_to?(:read) ? xml_or_io.read : xml_or_io.to_s
+    xml = xml_or_io.is_a?(String) ? xml_or_io : xml_or_io.read
     if xml.empty?
       raise Leptris::XML::ParseError, "empty input"
     end
@@ -119,6 +119,18 @@ class Leptris::XML::Document
     wrap(raw)
   end
 
+  # Deep copy of +element+ as the root of a NEW document — the one
+  # authority behind Node#dup / Element#dup and the indent-unit
+  # path (the C copy keeps every child kind and namespace since
+  # libleptris 1.9.76 — #696/#721/#812). The returned tree is
+  # detached from the original and fully navigable.
+  def self.copy_of(element)
+    new_doc = create
+    copy = Leptris::XML::FFI.leptris_element_copy(element.c_ptr, new_doc.c_ptr)
+    raise Leptris::XML::Error, "leptris_element_copy failed" if copy.null?
+    new_doc.root = Leptris::XML::Node.wrap(copy, new_doc)
+  end
+
   # Convert a raw LeptrisDocument pointer into a Ruby Document with safe
   # GC lifetime management. The finalizer captures the raw address
   # integer (not the Document or Pointer object — those would prevent

data/lib/leptris/xml/element.rb

@@ -251,15 +251,12 @@ class Leptris::XML::Element < Leptris::XML::Node
     self
   end
 
-  # Deep copy in a NEW document via the C copy, attached as the
-  # fresh document's root (#696 1.9.39, #721 1.9.47, #812 1.9.76 —
-  # every child kind and namespace survives, pool-threaded).
+  # Deep copy in a NEW document via Document.copy_of (the single
+  # copy seam — every child kind and namespace survives,
+  # #696/#721/#812).
   def dup
     ensure_alive!
-    new_doc = Leptris::XML::Document.create
-    copy = Leptris::XML::FFI.leptris_element_copy(@c_ptr, new_doc.c_ptr)
-    raise Leptris::XML::Error, "leptris_element_copy failed" if copy.null?
-    new_doc.root = Leptris::XML::Node.wrap(copy, new_doc)
+    Leptris::XML::Document.copy_of(self)
   end
   alias_method :clone, :dup
 
@@ -382,7 +379,8 @@ class Leptris::XML::Element < Leptris::XML::Node
   # semantics (leptris-ruby#109; via a C-side copy into a fresh
   # document — no element-level ext entry exists yet). true is NOT
   # supported here: the display form is document-level.
-  def to_xml(indent: 0, no_decl: false, encoding: nil, indent_text: false)
+  def to_xml(indent: 0, no_decl: false, encoding: nil, indent_text: false,
+              expand_empty: false)
     if indent_text == true
       raise ArgumentError,
         "indent_text: true (display form) is document-level — " \
@@ -390,6 +388,7 @@ class Leptris::XML::Element < Leptris::XML::Node
     end
     return Leptris::XML::Serialization.to_xml_element_unit(
       self, indent_text, indent: indent) if indent_text.is_a?(String)
+    return Leptris::XML::Serialization.element_xml_expand_empty(@c_ptr) if expand_empty
     Leptris::XML::Serialization.to_xml(
       Leptris::XML::Serialization::ELEMENT_SERIALIZE_INTO, @c_ptr,
       indent: indent, no_decl: no_decl, encoding: encoding)

data/lib/leptris/xml/evaluation_context.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "ffi"
+
+# Resolves an expression-face receiver into its evaluation context:
+# the OWNING document (lifetime + memoization scope) and the
+# context-node pointer (nil at document level). The single typed
+# seam behind XPath#eval and XQuery#eval — one authority, one
+# ArgumentError shape, as the expression faces multiply.
+#
+#     context = Leptris::XML::EvaluationContext.of(node)
+#     context.document        # => Leptris::XML::Document
+#     context.context_node_ptr # => FFI::Pointer or nil
+#
+class Leptris::XML::EvaluationContext
+  def self.of(receiver)
+    case receiver
+    when Leptris::XML::Document then new(receiver, nil)
+    when Leptris::XML::Element then new(receiver.document, receiver.c_ptr)
+    else
+      raise ArgumentError,
+        "expected a Leptris::XML::Document or Element, got #{receiver.class}"
+    end
+  end
+
+  def initialize(document, context_node_ptr)
+    @document = document
+    @context_node_ptr = context_node_ptr
+  end
+
+  attr_reader :document, :context_node_ptr
+end

data/lib/leptris/xml/ffi.rb

@@ -79,7 +79,8 @@ module Leptris
       # entry.
       class SerializeExtStruct < ::FFI::Struct
         layout :indent_text, :int,
-               :indent_unit, :pointer
+               :indent_unit, :pointer,
+               :expand_empty, :int
       end
 
       # Mirrors LeptrisParseOptions (libleptris >= 1.9.0 carries the
@@ -681,6 +682,22 @@ attach_function :leptris_parse_string,
         [: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,

data/lib/leptris/xml/iterparse.rb

@@ -41,7 +41,7 @@ class Leptris::XML::Iterparse
   # iterator starts — the bounded-memory path is parse_file (C-side
   # file streaming). The C API takes one (xml, len) buffer.
   def self.parse(xml_or_io, mode: :top_level, &block)
-    xml = xml_or_io.respond_to?(:read) ? xml_or_io.read : xml_or_io.to_s
+    xml = xml_or_io.is_a?(String) ? xml_or_io : xml_or_io.read
     iterator = new(Leptris::XML::FFI.leptris_iterparse_new_ex(
       xml, xml.bytesize, mode_code(mode)))
     return iterator unless block

data/lib/leptris/xml/node.rb

@@ -83,6 +83,19 @@ class Leptris::XML::Node
   alias_method :node_type, :type
 
   def element?;  type == Leptris::XML::FFI::NODE_ELEMENT;  end
+
+  # Content-defined 64-bit Merkle digest of this subtree
+  # (libleptris 1.9.99, #869): element name/prefix/resolved
+  # namespace URI, attributes sorted and first-wins-deduplicated,
+  # children hashed in document order — no addresses participate,
+  # so equal trees hash equal across processes. Equality implies
+  # subtree equivalence; inequality implies nothing (descend).
+  # +drop_ws+ skips whitespace-only text nodes.
+  def digest(drop_ws: false)
+    ensure_alive!
+    Leptris::XML::FFI.leptris_node_digest(
+      @c_ptr, drop_ws ? 1 : 0)
+  end
   def text?;     type == Leptris::XML::FFI::NODE_TEXT;     end
   def comment?;  type == Leptris::XML::FFI::NODE_COMMENT;  end
   def cdata?;    type == Leptris::XML::FFI::NODE_CDATA;    end
@@ -374,20 +387,14 @@ class Leptris::XML::Node
     result
   end
 
-  # Deep copy in a NEW document via the C copy, attached as the
-  # fresh document's root. Both copy gaps are closed for good:
-  # comment/PI children in 1.9.39 (#696), namespaces in 1.9.47
-  # (#721) with the 1.9.74 descendant-declaration regression fixed
-  # in 1.9.76 (#812). Perf: the detached copier is pool-threaded —
-  # upstream measures ~2.3x Nokogiri per subtree.
+  # Deep copy in a NEW document via Document.copy_of (the single
+  # copy seam — comment/PI children and namespaces both survive,
+  # #696/#721/#812; the copier is pool-threaded, ~2.3x Nokogiri).
   def dup
     ensure_alive!
     elem_ptr = Leptris::XML::FFI.leptris_node_as_element(@c_ptr)
     raise Leptris::XML::Error, "dup is only supported for element nodes" if elem_ptr.null?
-    new_doc = Leptris::XML::Document.create
-    copy = Leptris::XML::FFI.leptris_element_copy(elem_ptr, new_doc.c_ptr)
-    raise Leptris::XML::Error, "leptris_element_copy failed" if copy.null?
-    new_doc.root = Leptris::XML::Node.wrap(copy, new_doc)
+    Leptris::XML::Document.copy_of(self)
   end
   alias_method :clone, :dup
 

data/lib/leptris/xml/sax/parser.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 require "ffi"
+require "pathname"
+require "stringio"
 
 class Leptris::XML::SAX::Parser
   CHUNK_SIZE = 4096
@@ -42,7 +44,7 @@ class Leptris::XML::SAX::Parser
   def parse(input)
     case input
     when String                then parse_memory(input)
-    when ->(x) { x.respond_to?(:read) } then parse_io(input)
+    when IO, StringIO, Pathname then parse_io(input)
     else
       raise ArgumentError, "SAX parser expects a String or IO, got #{input.class}"
     end

data/lib/leptris/xml/serialization.rb

@@ -51,6 +51,20 @@ module Leptris::XML::Serialization
       ELEMENT_SERIALIZE_INTO, c_ptr, DEFAULT_OPTIONS.pointer)
   end
 
+  # Element serialization with expand_empty (libleptris 1.9.95,
+  # #882): empty elements emit <a></a> instead of <a/> — the
+  # inverse of libxml2's XML_SAVE_NO_EMPTY, through the element
+  # ext entry (the sized form keeps older ext allocations safe).
+  def self.element_xml_expand_empty(c_ptr)
+    ext = Leptris::XML::FFI::SerializeExtStruct.new
+    ext[:indent_text] = 0
+    ext[:indent_unit] = nil
+    ext[:expand_empty] = 1
+    str_ptr = Leptris::XML::FFI.leptris_element_serialize_ext_sized(
+      c_ptr, DEFAULT_OPTIONS.pointer, ext.pointer, ext.size)
+    Leptris::XML::FFI.read_owned_string(str_ptr)
+  end
+
   # Display-form document serialization (libleptris 1.9.9, #129):
   # the ext struct's indent_text hands ALL whitespace to the
   # formatter — text and mixed content indent too. Display-oriented:
@@ -115,17 +129,13 @@ module Leptris::XML::Serialization
 
   # Element-face indent unit (leptris-ruby#109 residual 2): no
   # element-level ext-serialize entry exists yet, so the unit path
-  # C-copies the subtree into a fresh document (every child kind
-  # and namespace survive since 1.9.76 — #696/#721/#812) and
-  # serializes that document without a declaration — identical
-  # output to the element serializer for the standard layout, with
-  # the unit and every child kind intact.
+  # copies the subtree into a fresh document via Document.copy_of
+  # (the single copy seam) and serializes that document without a
+  # declaration — identical output to the element serializer for
+  # the standard layout, with the unit and every child kind intact.
   def self.to_xml_element_unit(element, unit, indent: 0)
-    document = Leptris::XML::Document.create
+    document = Leptris::XML::Document.copy_of(element).document
     begin
-      copy = Leptris::XML::FFI.leptris_element_copy(element.c_ptr, document.c_ptr)
-      raise Leptris::XML::Error, "leptris_element_copy failed" if copy.null?
-      document.root = Leptris::XML::Node.wrap(copy, document)
       to_xml_indent_unit(document.c_ptr, unit,
                          indent: indent, no_decl: true)
     ensure

data/lib/leptris/xml/xpath.rb

@@ -36,17 +36,17 @@ class Leptris::XML::XPath
   # namespace bindings ("prefix" => uri) routes the evaluation through
   # the namespace-bound path, matching Searchable#xpath semantics.
   def eval(doc_or_element, ns = nil)
-    context = resolve_context(doc_or_element)
+    context = Leptris::XML::EvaluationContext.of(doc_or_element)
     document = context.document
     result_ptr =
       if ns && !ns.empty?
         Leptris::XML::FFI.with_ns_set(ns) do |set|
           Leptris::XML::FFI.leptris_xpath_compiled_eval_ns(
-            @handle, document.c_ptr, context_ptr(context), set)
+            @handle, document.c_ptr, context.context_node_ptr, set)
         end
       else
         Leptris::XML::FFI.leptris_xpath_compiled_eval(
-          @handle, document.c_ptr, context_ptr(context))
+          @handle, document.c_ptr, context.context_node_ptr)
       end
     if result_ptr.null?
       raise Leptris::XML::XPathError,
@@ -54,20 +54,4 @@ class Leptris::XML::XPath
     end
     Leptris::XML::Searchable.wrap_xpath_result(document, result_ptr)
   end
-
-  private
-
-  def resolve_context(doc_or_element)
-    case doc_or_element
-    when Leptris::XML::Document then doc_or_element
-    when Leptris::XML::Element then doc_or_element
-    else
-      raise ArgumentError,
-        "expected a Leptris::XML::Document or Element, got #{doc_or_element.class}"
-    end
-  end
-
-  def context_ptr(context)
-    context.is_a?(Leptris::XML::Document) ? nil : context.c_ptr
-  end
 end

data/lib/leptris/xml/xquery.rb

@@ -47,23 +47,13 @@ class Leptris::XML::XQuery
   # an aggregate until the engine materializes readable sequence
   # items (same caveat as the XPath for-return subset).
   def eval(doc_or_element)
-    case doc_or_element
-    when Leptris::XML::Document
-      document = doc_or_element
-      context = nil
-    when Leptris::XML::Element
-      document = doc_or_element.document
-      context = doc_or_element.c_ptr
-    else
-      raise ArgumentError,
-        "expected a Leptris::XML::Document or Element, got #{doc_or_element.class}"
-    end
+    context = Leptris::XML::EvaluationContext.of(doc_or_element)
     result_ptr = Leptris::XML::FFI.leptris_xquery_eval(
-      @handle, document.c_ptr, context)
+      @handle, context.document.c_ptr, context.context_node_ptr)
     if result_ptr.null?
       raise Leptris::XML::XPathError,
         Leptris::XML::FFI.leptris_last_error.to_s
     end
-    Leptris::XML::Searchable.wrap_xpath_result(document, result_ptr)
+    Leptris::XML::Searchable.wrap_xpath_result(context.document, result_ptr)
   end
 end

data/lib/leptris/xml.rb

@@ -22,6 +22,7 @@ module Leptris
     autoload :Serialization, "leptris/xml/serialization"
     autoload :SAX, "leptris/xml/sax"
     autoload :XPath, "leptris/xml/xpath"
+    autoload :EvaluationContext, "leptris/xml/evaluation_context"
     autoload :ResultText, "leptris/xml/result_text"
     autoload :XSLT, "leptris/xml/xslt"
     autoload :XQuery, "leptris/xml/xquery"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: leptris
 version: !ruby/object:Gem::Version
-  version: 1.9.93.0
+  version: 1.9.100.0
 platform: aarch64-linux
 authors:
 - Ribose Inc.
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-06 00:00:00.000000000 Z
+date: 2026-09-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ffi
@@ -69,6 +69,13 @@ files:
 - LICENSE.md
 - README.adoc
 - Rakefile
+- TODO.restructure/01-constraint-compliance-audit.md
+- TODO.restructure/02-deep-copy-seam.md
+- TODO.restructure/03-evaluation-context-seam.md
+- TODO.restructure/04-spec-mece-restructure.md
+- TODO.restructure/05-memory-documentation.md
+- TODO.restructure/06-architecture-map-refresh.md
+- TODO.restructure/07-external-gates.md
 - docs/adr/0001-lockstep-mirror.md
 - docs/adr/0002-utf8-at-the-seam.md
 - docs/adr/0003-readonly-memoization-pattern.md
@@ -88,6 +95,7 @@ files:
 - lib/leptris/xml/document.rb
 - lib/leptris/xml/document_fragment.rb
 - lib/leptris/xml/element.rb
+- lib/leptris/xml/evaluation_context.rb
 - lib/leptris/xml/ffi.rb
 - lib/leptris/xml/iterparse.rb
 - lib/leptris/xml/namespace.rb