leptris 1.9.379.3-arm-linux → 1.9.380.1-arm-linux

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3770bdb85662c6961aedd258ccf0fd05acfe6b9973a118a405020dc3446c28ab
-  data.tar.gz: 8cc82d14ef2abb6d4b5ed108863d6858009ec5ba8ac53a2926c5d15e32443a8e
+  metadata.gz: c9d57ba010010d0eafdafc080938bc02ebf7d508799cdd01fbde67176d5f1e5f
+  data.tar.gz: 8d560c49128668a65a82a098e0918b7378957f5a07aa9e1f76b939709acd5283
 SHA512:
-  metadata.gz: 9beeff955522554c2a9dd0d59d73c44f1fa8c7b7116fa2cc26851afbfa0cc7be35a2196e14a022281d60934c75eb86ce0f992ccec00ecfcaa13cbab82fdb63ea
-  data.tar.gz: bf39d054e9f806e0e6a57a57460d92848bfe1eba4d0da4a4ccb94788dce8f077778db20211653e4f49fced598b6efabcf9123c05676a6884e8cc51c67a99bfd6
+  metadata.gz: c7c175ea55f978f206ca9b8505350478c0693c6caa3381d29e3355ee995d25faf69d908a41f4af379e58ec603157c35fb03e91a308b610f887e63095927818bd
+  data.tar.gz: 57b50326e6a4979410884d2610468e2e52d0de4e99eaf084be3f84a9a026864456105529b9c9cccd1e0d63406919d68f71f62eff894ca4208c5c8278d3c49a77

data/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [Unreleased]
+
+### Fixed — engine ride
+
+- **Ride libleptris 1.9.380**: the xsi:type conformance fix
+  (leptris/leptris#1832, lutaml/moxml#433) — an element carrying
+  `xsi:type` is assessed against the NAMED type (XSD 1.0
+  §2.6.2/§3.3.4), so valid xsi:type-derived instances validate
+  instead of being rejected against the declared type's content
+  model. Released 1.9.380.0 with the pin still at 1.9.379 (the
+  vendored dylib missed the fix); this pin bump is the real ride.
+
 ## [1.9.379.3] - 2026-10-22
 
 ### Fixed

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.379"
+LIBLEPTRIS_VERSION = "1.9.380"
 # 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

data/lib/leptris/version.rb

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

data/vendor-src/README.md

@@ -1,7 +1,7 @@
 Sources vendored in this gem (recompile rights; the ruby
 variant builds them at install via extconf.rb):
 
-- libleptris v1.9.379
+- libleptris v1.9.380
 - utf8proc v2.11.0
 
 Rebuild by hand:

data/vendor-src/libleptris/CHANGELOG.md

@@ -1,5 +1,15 @@
 ## [Unreleased]
 
+## [1.9.380] - 2026-10-22
+
+### Fixed
+
+- assess elements against the instance's xsi:type (moxml#433) (xsd)
+- choice alternatives after a failed parenthesized branch were unreachable (dtd)
+- iterative nested-include processing - no C-stack nesting (xinclude)
+
+
+
 ## [1.9.379] - 2026-10-21
 
 ### Fixed

data/vendor-src/libleptris/CMakeLists.txt

@@ -3,7 +3,7 @@
 cmake_minimum_required(VERSION 3.20)
 
 project(leptris
-    VERSION 1.9.379
+    VERSION 1.9.380
     DESCRIPTION "Fast XML parser and XPath evaluator in pure C"
     LANGUAGES C CXX
 )

data/vendor-src/libleptris/TODO.SOTA.md

@@ -27,54 +27,62 @@ docs/MISSION-PLAN.md and is updated at every release.
 
 ## Gate A — Conformance: zero reds everywhere
 
-### A1 WHATWG verdict parity: 1394/1555 → 1555/1555
-**Measured 2026-10-21 (main after #1800): 1535/1555 verdict,
-1555/1555 tree, zero false positives; floor pinned at 1535.** The
-remaining 20 verdict misses: adoption-agency (tests2:10, tests19:98,
-tests19:99, tests26:1, tests26:9), menuitem strays (menuitem:10/12),
-table/caption singletons (tests9:16, tests10:15, tests16:197,
-pending-spec-changes:2, tests20:48), tokenizer singletons (tests10:2,
-tests2:18, tests2:58, tests19:41, tests19:82) and two-heads
-(tests3:13). The remaining ~270 code-set divergences are prose-dialect
-labels from older corpus datasets; the verdict gate is presence-only.
-The slices already shipped: initial mode, raw-text EOF, unterminated
-close, frameset, fenced walk, InBody EOF allowed-set, in-select,
-foster-by-kind, unknown-doctype (#1778-#1791), raw-text strays,
-non-html-root, end-tag-too-early, after-body/frameset phases,
-start-tag phases, select/table/foreign, need-space-after-doctype
-(#1794), misplaced/stray-p, after-html codes, image (#1797, #1800).
-Ground every further slice in html5lib's actual source
-(~/src/external/html5lib):
-- [ ] escaped-state EOF codes (`unexpected-eof-in-text-mode`,
-      `eof-in-script-in-script`) — the script-data state machine's
-      EOF classification
-- [ ] the after-body EOF phase rule (tests1:34 class; the exact
-      phaseAtBody.eof semantics)
-- [ ] in-body `unexpected-start-tag` family (body/frameset/form
-      starts; the startTagBody/Forms/Frameset error sites)
-- [ ] `unexpected-end-tag` family (p-in-button-scope synthesis,
-      form pointer, li/dd/dt scope, endTagOther walk)
-- [ ] foster-parenting sites (start-tag/character/character-in-table)
-- [ ] adoption-agency codes (`adoption-agency-1.3` et al.)
-- [ ] in-table voodoo (`*-implies-table-voodoo`, cells, eof-in-table)
-- [ ] unknown-doctype / unexpected-char-in-doctype (doctype
-      tokenization §13.2.5.28+)
-- [ ] non-html-root, select-mode codes, heading/edge shapes
+### A1 WHATWG verdict parity: DONE — 1555/1555
+**Measured 2026-10-21 (PR #1803, tagged v1.9.378): verdict
+1555/1555, ZERO misses; tree 1555/1555; floor pinned at the full
+corpus count.** The gate is presence-only — every corpus document
+now reports a parse error exactly when html5lib does. The final
+tail closed at the html5lib source sites: adoption-agency-1.3
+(7 cases), menuitem endTagOther pair, tokenizer
+expected-dashes-or-doctype / solidus-in-tag / attributes-in-end-tag,
+AfterAfterFrameset trailing chars, BeforeHead
+end-tag-after-implied-root, BeforeHtml unexpected-end-tag-before-html,
+foreign end-tag mismatch, form-in-table both flavors, </form> table
+voodoo, template foster-parenting-character, two-heads. Earlier
+slices: initial mode, raw-text EOF, unterminated close, frameset,
+fenced walk, InBody EOF allowed-set, in-select, foster-by-kind,
+unknown-doctype (#1778-#1791), raw-text strays, non-html-root,
+end-tag-too-early, after-body/frameset phases, start-tag phases,
+select/table/foreign, need-space-after-doctype (#1794),
+misplaced/stray-p, after-html codes, image (#1797, #1800). The
+~270 remaining code-set divergences are prose-dialect labels from
+older corpus datasets — reported, not gated.
 
 ### A2 QT3 / XQuery 3.1: zero unexplained pins
-- [ ] re-pin fresh (the ~41–99 slice figures are dated)
-- [ ] every remaining pin gets a disposition file or a fix
+- [x] re-pin fresh (2026-10-22: 1723 pins, 62/62 green, zero reds; 106 sets, 72 pins moved)
+- [x] every remaining pin gets a disposition file or a fix
+  (test/xquery/qt3-dispositions/ — 10 files, 1723/1723 dispositioned;
+  fixes: fn:codepoint-equal empty-operand propagation, driver
+  assert-count/assert-empty, role="." context sources, QT3_REPORT
+  inventory channel)
 - [ ] ctor node-yield family: owned_docs transfer completion
 
 ### A3 XSD conformance lane: suite-complete
-- [ ] the lane's own queue (769→795 → its ceiling) to zero
+- [x] the lane's own queue to its dispositioned ceiling — **2026-10-22:
+  903 → 989**/1056 (PR #1825; the board's 795 was stale — five slices
+  had landed). 9 root-caused classes retired:
+  (2026-10-22: 903 → **989**/1056 — 9 root-caused classes retired:
+  xsi-attr exemption, empty content models, unprefixed builtins,
+  no-tns `##other`, xs:attribute 3.2.3 clauses (+55), g-regional
+  timezone, token whitespace, unknown-xs-builtin refs. 67 left,
+  every row dispositioned in test/xsd/xsd-dispositions/README.md:
+  substitution groups in content models, xsi:type, attribute form
+  defaults, identity-constraint checks, derivation-ok attribute
+  clauses; 1 oracle bug (bug322411) not chased)
 
 ### A4 DTD phase 8 (TODO 91)
-- [ ] ENTITY/ENTITIES attribute resolution
-- [ ] parameter entities, choice-model backtracking
+- [x] ENTITY/ENTITIES attribute resolution (undeclared entity, parsed
+      entity without NDATA, undeclared notation, bad ENTITIES token —
+      all falsifiably spec'd; shipped bd21acc6/9d3b3a0e)
+- [x] parameter entities (internal, chained, ATTLIST/ELEMENT bodies,
+      SYSTEM PEs via loader, recursion cap, conditional sections) and
+      choice-model backtracking — group-alternative failure walker
+      fixed so a failed parenthesized alternative still reaches later
+      `|` branches (DtdPhase8.GroupAlternativeFailureStillTriesLaterAlternatives)
 
 ### A5 XInclude completeness (TODO 92)
-- [ ] `parse="xml"` (ownership-transfer splice exists — wire it)
+- [x] `parse="xml"` (ownership-transfer splice + canonical insert face,
+      depth-guard resource-error fallback; verified by specs)
 - [ ] xpointer
 
 ### A6 The universality proof (differential corpus)
@@ -90,15 +98,15 @@ Ground every further slice in html5lib's actual source
 ## Gate B — Performance: every published row ≥1.00x
 
 ### B1 build row: ~2.9x → ≤1.0x (the #242 campaign)
-**Measured 2026-10-21: 1.86-1.92x** (moxml `sota/04-performance`
-branch + leptris 1.9.376.0; harness `wt/460-harness/build_bench.rb`,
-31 interleaved reps: 4.08ms vs Nokogiri 2.20ms for 250 records).
-Was 2.95x at the 1.9.363 era; the add_child alias and same-doc fast
-path landed since. StackProf attribution: `NativeNode.create_element`
-14.6%, GC mark+sweep 19%, `prime_contract` 7.7%, attach path 45% of
-tree; the `invalidate_namespace_cache!` line attribution is a
-sampling artifact (deleting both attach invalidations gains ~5%).
-Harness: wt/460-harness/build_bench.rb. Decomposition on record.
+**Measured 2026-10-22: ~1.47-1.54x median after NINE merged levers**
+(honest baseline 2.72x; guard retirement −22%, namespace gate,
+nil-ivar priming, children-cache guard, mint direct-dispatch +
+native set_attribute −19% (PR #431), prepare_node inline (PR #432)).
+Harness `wt/460-harness/build_bench.rb`; A/B pairs alternate within
+ONE window (drift ±20%). Rejected within noise: fast_attach,
+native-cache deletion, doc_klass memo, identity-probe deletion,
+add_child alias. Residual: wrapper allocation (owner-level node
+layout).
 - [ ] per-element object budget: one Ruby object per created node
       (drop the shell entirely post-create-priming; the mint cache
       insert policy; the context registration)
@@ -113,8 +121,16 @@ scaffolding. Memo law holds (dropping @children memo = 2x GC).
 - [ ] publish the per-face table (the honest much-faster story)
 
 ### B3 whole-pipeline rows (new, published)
-- [ ] parse→query→serialize pipeline row vs nokogiri/libxml2
-- [ ] build→transform (XSLT) pipeline row
+**Measured 2026-10-21: parse→query→serialize is GREEN — leptris
+finishes in 0.533-0.573x of Nokogiri's CPU time (~1.8x faster),
+three interleaved-median runs (`wt/460-harness/pipeline_bench.rb`,
+250 records, 31 reps; same document and query both sides).**
+- [x] parse→query→serialize pipeline row vs nokogiri (green, dated)
+- [x] build→transform (XSLT) pipeline row — **GREEN 2026-10-21:
+      build 250 records, XSLT 1.0 transform, serialize — leptris
+      finishes in 0.492-0.515x of Nokogiri's CPU time (~2x faster),
+      three interleaved-median runs
+      (`wt/460-harness/xslt_pipeline_bench.rb`)**
 - [ ] both to serialbench as the public scoreboard
 
 ### B4 durability
@@ -136,19 +152,29 @@ scaffolding. Memo law holds (dropping @children memo = 2x GC).
 - [ ] C3 reproducible builds everywhere: darwin toolchain pin done
       (ruby#512) — extend to linux/windows legs; publish a per-
       release build manifest (engine + binding hashes per platform)
-- [ ] C4 security.md: advisory channel, CVE-response process,
-      dependency-free attestation
+- [x] C4 security.md: advisory channel, CVE-response process,
+      dependency-free attestation — **shipped 2026-10-21 (PR #1804,
+      v1.9.378)**: GitHub Security Advisories channel, 5-business-day
+      acknowledgment target, coordinated disclosure, CVE assignment,
+      scope table, hardening inventory tied to the lanes that actually
+      run
 - [ ] C5 the memory story documented: pool arena model, leak gates,
       the borrowed-slice lifetime contract
 
 ## Gate D — Universality: same semantics everywhere
 
-- [ ] D1 leptris-descriptor published (crates.io; feat/294 branch
-      lands), rides lockstep
+- [x] D1 leptris-descriptor published — **2026-10-22: live on
+      crates.io as leptris-descriptor v1.9.379** (lockstep with the
+      engine; #1827 fixed the workspace publish to target the
+      descriptor package; issue #1829 records the one-time manual
+      establishment — crates.io trusted publishing cannot create new
+      crates — after which versions publish via the OIDC workflow)
 - [ ] D2 system packaging: homebrew, conan, deb (apt repo)
 - [ ] D3 cross-runtime differential CI (= A6, wired)
-- [ ] D4 libxml2→libleptris migration guide (docs/guide/) + the
-      nokogiri-compat surface documented
+- [x] D4 libxml2→libleptris migration guide — **shipped 2026-10-21
+      (PR #1810): docs/guide/migrating-from-libxml2.md** (ownership
+      model, parse/tree/XPath/serialize/SAX/DTD mappings, deliberate
+      differences); nokogiri-compat surface documented in the guide
 
 ## Gate E — 1.0 (the seal)
 

data/vendor-src/libleptris/benchmarks/baseline.json

@@ -0,0 +1 @@
+{}

data/vendor-src/libleptris/bindings/rust/Cargo.lock

@@ -11,4 +11,4 @@ dependencies = [
 
 [[package]]
 name = "leptris-descriptor"
-version = "0.1.0"
+version = "1.9.379"

data/vendor-src/libleptris/bindings/rust/descriptor/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "leptris-descriptor"
-version = "0.1.0"
+version = "1.9.379"
 edition = "2021"
 description = "Shared descriptor-plan ABI for the leptris engine family (leptris, yeptris, teptris) — repr(C) mirrors of the tree-shaped descriptor plan records"
 license = "MIT"

data/vendor-src/libleptris/cli/output.c

@@ -3,6 +3,17 @@
  * @brief Output formatting implementation for Leptris CLI
  */
 
+/* fileno is POSIX, not ISO C: under -std=c11 (C_EXTENSIONS OFF,
+ * __STRICT_ANSI__) glibc hides its declaration from <stdio.h> and
+ * both gcc-14 and clang-18 reject the implicit call, so declare the
+ * POSIX surface before ANY include pulls a system header in. macOS
+ * never hides fileno, which is why only the Linux lanes caught it
+ * (found by the ci/tsan lane's ubuntu build). Windows reaches
+ * fileno/isatty via <io.h> below. */
+#if !defined(_WIN32) && !defined(_POSIX_C_SOURCE)
+#  define _POSIX_C_SOURCE 200809L
+#endif
+
 #include "output.h"
 #include "error.h"
 #include <stdlib.h>

data/vendor-src/libleptris/docs/MISSION-PLAN.md

@@ -23,11 +23,11 @@ nothing to libxml2.
 | A1 | W3C XPath 1.0 | 438/438 pinned in CI | **done** — 438/438 |
 | A2 | libxslt (XSLT 1.0) | 205/205 pinned (Linux-authoritative; macOS skips bug-169 iconv-encoding) | **done** — 205/205 (v1.9.19) |
 | A3 | XsltFull | 27/27 + full suite green; XSLT gate (v1.10.0) stays met | **done** — gate MET (#1761) |
-| A4 | QT3 / XQuery 3.1 | 0 unexplained pins; every pin has a recorded disposition | pins ~41–99 by slice (2026-09/10) — **re-pin fresh** |
-| A5 | WHATWG/html5lib (#659) | 0 reds on the tree gate; verdict parity climbing on the #1771 error-verdict gate | **tree lane CLOSED** — 1555/1555, redlist retired (found during Phase 0); verdict gate flipped 2026-10-19: 1312/1555, floor pinned |
+| A4 | QT3 / XQuery 3.1 | 0 unexplained pins; every pin has a recorded disposition | **done** 2026-10-22 — 1723 pins, all dispositioned (test/xquery/qt3-dispositions/); 62/62 DUCET + 59/59 no-utf8proc green |
+| A5 | WHATWG/html5lib (#659) | 0 reds on BOTH gates — tree and error-verdict | **BOTH LANES CLOSED 2026-10-21** — tree 1555/1555; verdict 1555/1555, zero misses (PR #1803), floor pinned at the full corpus count |
 | A6 | XSD conformance lane | suite-complete per the lane's own queue | 769→795 (2026-10-14, queue #1691) |
 | A7 | DTD phase 8 (TODO 91) | ENTITY/ENTITIES attribute resolution, parameter entities, choice-model backtracking | open |
-| A8 | XInclude parse="xml" + xpointer (TODO 92) | spec-complete | open (parse="text" + fallback ship) |
+| A8 | XInclude parse="xml" + xpointer (TODO 92) | spec-complete | **closed 2026-10-22** — parse="xml" splice via canonical insert face + depth-guard fallback (PR #1815); xpointer schemes REC-conformant with pointer-miss=resource-error (PR #1820); windows iterative nesting fix (PR #1822) |
 | A9 | RelaxNG / C14N / SAX | parity maintained, no reds | green |
 
 **Working rule (proven across A1–A3):** suite-driven fixes only —
@@ -87,7 +87,7 @@ lands (TAG-RACE).
 | C2 | leptris-rs descriptor crate | `leptris-descriptor` published; safe-wrapper crate rides lockstep | feat/294 in flight, not published |
 | C3 | moxml gem | cut (owner-dispatched) carries the walk+read adoption | merged on main, release pending owner |
 | C4 | Prebuilt binaries everywhere consumers lack compilers | rubygems platform matrix ✓, PyPI wheels ✓, npm WASM ✓ | **done**, keep green |
-| C5 | System packaging | vcpkg ✓; add homebrew / conan / deb formulas so "install libleptris" is one command per platform | open |
+| C5 | System packaging | vcpkg ✓; add homebrew / conan / deb formulas so "install libleptris" is one command per platform | **formulas shipped in-repo; channel submission pending owner (2026-10-22)** |
 | C6 | Cargo publish lane | OIDC-free trusted publishing (crates-io-auth-action@v1) wired into the rust-release workflow; CARGO_REGISTRY_TOKEN secret set once | workflow shipped; secret/token state to verify in Phase 0 |
 
 **Exit:** a consumer on any of the four runtimes installs a prebuilt
@@ -165,11 +165,14 @@ tag that says so.
 | Gate | Command | Last run | Verdict |
 |------|---------|----------|---------|
 | A1 WHATWG tree parity | `test_html5lib --gtest_filter=Html5LibCorpus.*` | 2026-10-21 | green, 1555/1555 |
-| A1 WHATWG verdict parity | `Html5LibCorpus.ErrorVerdictParity` | 2026-10-21 | 1535/1555 (floor 1535; **red**) |
+| A1 WHATWG verdict parity | `Html5LibCorpus.ErrorVerdictParity` | 2026-10-21 | **green, 1555/1555 — zero misses** (PR #1803; floor pinned at the full corpus) |
 | A7 libxslt | `LibxsltSuite` | 2026-10-20 | 205/205 (204 + 1 macOS skip) |
-| B1 build row | `wt/460-harness/build_bench.rb` | 2026-10-21 | 1.86-1.92x (**red**, sota/04 branch) |
+| B1 build row | `wt/460-harness/build_bench.rb` | 2026-10-21 | **~1.9x red** (sota/04 after five levers; honest baseline re-measured 2.72x this day — the old 1.86x record is not reproducible) |
+| B3 pipeline row (parse→query→serialize) | `wt/460-harness/pipeline_bench.rb` | 2026-10-21 | **green** — 0.533-0.573x of Nokogiri's time (~1.8x faster), three runs |
+| B3 pipeline row (build→transform, XSLT) | `wt/460-harness/xslt_pipeline_bench.rb` | 2026-10-21 | **green** — 0.492-0.515x of Nokogiri's time (~2x faster), three runs |
 | B2 walk row | `wt/460-harness/walk_read_bench.rb` | 2026-10-20 | 0.88x (green) |
-| Test-suite runtime (fidelity) | `ctest`, 2074 cases | 2026-10-21 | 66.0 s serial → 31.0 s `-j4` (same 2074/2074; PR #1799) |
-| Rides 1.9.377 | registries | 2026-10-21 | rubygems/PyPI 1.9.377.0, npm 0.1.21 |
-| Issues | all repos | 2026-10-21 | 0 open (ruby#514/#515 closed with gem verification) |
+| Test-suite runtime (fidelity) | `ctest`, 2074 cases | 2026-10-21 | 66.0 s serial → 31.0 s `-j4` (same 2074/2074; **shipped in v1.9.378**) |
+| XPath index vs mutations | `XPathIndexInvalidation.*` | 2026-10-21 | green — splice paths invalidate (PR #1802; ruby#519 closed on the 1.9.378.0 gem) |
+| Rides 1.9.379 | registries | 2026-10-21 | rubygems/PyPI 1.9.379.0, npm 0.1.22 (engine v1.9.379; v1.9.378 rides blocked by the GCC-14 cast, fixed in #1806) |
+| Issues | all repos | 2026-10-21 | 0 open (ruby#519 closed with gem verification) |
 

data/vendor-src/libleptris/docs/guide/memory-model.md

@@ -0,0 +1,229 @@
+# The libleptris Memory Model
+
+This guide documents how libleptris allocates, who owns what, and which
+calls hand back memory you must free. Every public function that returns
+a string or handle carries a `Memory:` comment in `src/include/leptris.h`;
+this page is the map of the underlying rules.
+
+## The pool arena model
+
+Every byte a parsed document references lives in one memory arena owned
+by the document. There is no per-node allocation and no per-node free.
+
+- **One allocation per document.** The parser sizes a contiguous arena
+  from the input (`src/leptris/flat/direct_parse.c`), then creates an
+  arena-backed pool over it (`leptris_pool_create_arena_backed` in
+  `src/leptris/memory/pool.c`). Elements, attributes, text nodes, and
+  strings are all bump-allocated inside that span, so any two allocations
+  are within the arena size of each other by construction — the property
+  the compact-pointer tree edges require.
+- **O(1) allocation.** `leptris_pool_alloc` is a bump-pointer advance on
+  the current page; the slow path (span exhausted) allocates a new page,
+  still O(1). Requests larger than a page go to the allocator directly and
+  are tracked on an oversized list so `leptris_pool_destroy` can free them.
+- **No per-node free.** There is no `leptris_element_free` and no
+  reference counting. Individual nodes are never released; removing a
+  node from the tree returns its bytes to no one. This is deliberate —
+  the allocator never needs to reason about partial teardown.
+- **Batch release.** `leptris_document_free` destroys the pool and every
+  byte reachable from the document in one pass: pages, oversized blocks,
+  the input copy, and the document struct itself (which is also
+  pool-allocated). Callers never free anything else.
+
+Empty documents behave the same: `leptris_document_create` gives the
+document its own arena-backed pool, and programmatic nodes created via
+`leptris_element_create` land in it.
+
+Ownership transfers exist for two composition cases:
+
+- `leptris_document_adopt_child(parent, child)` keeps a freshly parsed
+  child document alive until the parent is freed (used by XInclude).
+- `leptris_document_absorb(dst, src)` moves `src`'s pool into `dst` so
+  cross-document splices can move nodes by reference; after the call the
+  `src` handle is handle-only and the memory dies with `dst`.
+
+A foreign element passed across documents (for example to
+`leptris_document_set_root`) is **adopted by copy**: nodes are pool-owned
+by their document, so a move would dangle after the source document's
+free. Always wrap the installed handle the API returns, never the
+borrowed source pointer.
+
+## String ownership
+
+Every string-returning accessor falls into one of two classes. The
+`Memory:` comment in the header says which, per function.
+
+### Document-owned: do not free
+
+Accessors returning `const char*` against a document-taking handle
+return pointers into the document's arena. Examples:
+`leptris_element_name`, `leptris_element_expanded_name`,
+`leptris_comment_node_get_content`, the diff op accessors. They are
+valid until `leptris_document_free` and must not be freed or modified:
+
+```c
+const char* name = leptris_element_name(root);  /* document-owned */
+/* no free */
+leptris_document_free(doc);                     /* releases name too */
+```
+
+Node handles are document-owned the same way
+(`leptris_document_root`, `leptris_xpath_result_get`,
+`leptris_node_children`): never free a node separately.
+
+### Caller-owned: free with `leptris_free_string`
+
+Functions that build a fresh string return `char*` and must be released
+with `leptris_free_string` (which routes through the installed
+allocator, so it matches how the string was made):
+
+- `leptris_document_serialize` and the other serializers
+- `leptris_xpath_result_string` (the string value of any result type)
+- `leptris_node_get_xpath`
+- `leptris_load_file` (the file buffer)
+- `leptris_alloc_buffer` (when the caller keeps the buffer)
+
+```c
+char* xml = leptris_document_serialize(doc, NULL);
+/* ... */
+leptris_free_string(xml);
+```
+
+XPath results are their own class: `leptris_xpath_eval` returns a
+caller-owned `LeptrisXPathResult` released with
+`leptris_xpath_result_free` — but the node handles inside a nodeset
+remain document-owned, so the result may be freed before the document,
+never after.
+
+### The borrowed-slice lifetime contract
+
+During parse, text is handled as `LeptrisStringView` — a
+`(data, length)` pair that borrows, not owns
+(`src/leptris/common/string_view.h`). The mechanics:
+
+1. The parser copies the input into the document's arena span (the
+   parse scratch) and NUL-terminates tokens **in that copy** as it
+   scans. Element names, attribute values, and text content are slices
+   of this document-owned buffer — no per-string allocation happens.
+2. What borrows what: node strings borrow from the document's private
+   input copy; the document's copy borrows from nothing. A second
+   pristine copy of the input is kept for line/column diagnostics,
+   because the scratch gets NUL substitutions.
+3. When a copy is made: entity-expanded content, interned strings (the
+   intern table copies both key and value into the pool so nothing
+   points into a reused buffer), and any string the public API returns
+   as caller-owned.
+
+Consequences:
+
+- After `leptris_parse_string` returns, the document is self-contained;
+  the header nevertheless documents `parse_string`'s input as valid for
+  the call. `leptris_parse_string_inplace` is the zero-copy variant with
+  a stricter contract: the document retains a reference to the caller's
+  writable buffer, which the caller must keep alive for the document's
+  lifetime (the parser writes NUL terminators into it).
+- Nothing a `const char*` accessor returns survives
+  `leptris_document_free`. Store copies, not pointers, if the data must
+  outlive the document.
+
+## Leak gates
+
+Three layers catch leaks before they merge.
+
+### CI
+
+`.github/workflows/asan.yml` runs two jobs:
+
+- **AddressSanitizer (Linux)** — full `ctest` under ASAN with
+  `ASAN_OPTIONS=detect_leaks=1:halt_on_error=1:abort_on_error=1`.
+- **leaks (macOS)** — builds and tests, then runs the CLI over fixtures
+  under `leaks --atExit` and fails unless it reports
+  `0 leaks for 0 total`.
+
+The macOS job matters because LeakSanitizer's leak mode is not supported
+on macOS ASAN; leaks there are only caught by this job (or Linux CI).
+
+### Locally
+
+```bash
+# macOS
+leaks --atExit -- ./build/test/c/test_dom
+
+# Linux
+valgrind --leak-check=full --error-exitcode=1 ./build/test/c/test_dom
+```
+
+Or configure an ASAN build and run any suite:
+
+```bash
+cmake -B build -S . -DLEPTRIS_ENABLE_ASAN=ON -DCMAKE_BUILD_TYPE=Debug
+cmake --build build
+ctest --test-dir build --output-on-failure
+```
+
+A finishing thread must not hold libleptris memory: call
+`leptris_thread_cleanup` after the last `leptris_document_free` on that
+thread to drain the per-thread caches and the pool-block recycler.
+
+## The FFI / binding contract
+
+`docs/FFI.md` states the boundary rules; the memory-relevant ones:
+
+- **One release function.** A binding needs only `leptris_document_free`
+  to release a parsed document. Everything reachable from the document
+  dies with it.
+- **Strings are read, then released per class.** Document-owned strings
+  are copied out (or read in place) and never freed; caller-owned
+  strings are freed with `leptris_free_string` before the binding object
+  is collected.
+- **Binding wrapper pointers are borrowed both ways.**
+  `leptris_node_set_binding_wrapper` stores a pointer the binding owns;
+  libleptris never dereferences or frees it. The binding must clear it
+  or guarantee the wrapper outlives the document.
+- **Finalizer-driven release must be exact.** The shipped Ruby binding
+  does not use a GC finalizer for the document, precisely because a
+  finalizer cannot tell an already-freed pointer from a valid one. If a
+  binding uses finalizers, it must track freed state itself and release
+  exactly once.
+
+### The free-before-pool-recycle hazard
+
+This is the #506-class failure for embedders. Destroyed arena blocks are
+recycled: `leptris_pool_destroy` parks default-shape blocks on capped
+thread-local lists and the next `leptris_parse_*` on the same thread
+pops an exact-size match. This makes document churn cheap — and it
+means **use-after-free does not crash at the bug site**. A stale handle
+written after `leptris_document_free` lands inside the *next*
+document's live tree and corrupts it silently; a double free hands the
+allocator a block the next parse now owns.
+
+Corollary hazards already guarded in the engine (do not reproduce them
+in embedder code): a binding finalizer releasing a document after a
+replacement document was created, and a caller freeing an absorbed
+document's handle a second time.
+
+## Rules for embedders
+
+1. Free the document **last**. `leptris_document_free` after every
+   borrowed pointer (nodes, document-owned strings, XPath results
+   holding nodes into it) is dead.
+2. Never free a `const char*` the API handed you. Only `char*` returns
+   documented as caller-owned are yours — release those with
+   `leptris_free_string`, once, on the same side of the boundary that
+   received them.
+3. Never write through a handle after its document is freed, and never
+   free a document twice. With the block recycler, both corrupt the next
+   parse instead of crashing.
+4. Keep `leptris_parse_string_inplace`'s buffer alive and unmodified for
+   the document's lifetime; prefer plain `leptris_parse_string` unless
+   the zero-copy path is measured to matter.
+5. Wrap installed handles, not borrowed sources — cross-document
+   element adoption copies, so the handle you passed in may not be the
+   node that got installed.
+6. Call `leptris_thread_cleanup` before a worker thread that used
+   libleptris exits.
+7. Install custom allocators (`leptris_set_memory_management_functions`,
+   or per-document `leptris_document_set_allocators`) before the first
+   allocation they should govern, and route host-language allocations
+   the engine will free through `leptris_alloc_buffer` so allocator and
+   CRT always match.