leptris 1.9.201.4 → 1.9.207.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 230f192458c26ad52475b9ef659644858d264777896cc197482205ac32972a01
-  data.tar.gz: 2013be07ce60da7b35b5564b6d18b3905dd7809d08acabb2780211323a6f6781
+  metadata.gz: b10f689b2142684316157264cfd935433d6d0d22db8cf90b4a27e9c4ba79bd88
+  data.tar.gz: f3e625c375d995087bec8cd6c058a7a9c900791125f1422f6da8b2436e90047b
 SHA512:
-  metadata.gz: 979d1f1a2e9d5815a6502c1990e171ff6e0e1df90751121bf96eacab517f7510b0eb30efca09e848fb3ab4c27e33fba4f2fbcf3f977811a786b766a23fa58545
-  data.tar.gz: 3df36dfd59e33291acad1ad240541d12d2f1fb0cd7a4e4590ff1bf7569e30ce6b639fbbc6aaffc469bf49716dc914c9d5ef42dafada61da49c0f408711ed2949
+  metadata.gz: ddf28875bb34e2eb14074c51834614f5cb5acddf0a33c58f55a50d9e6970a065eb70cb6f3da51c1114cad3a8c062a6dec98d6ce271ff27a81a77033f92e774ea
+  data.tar.gz: b1c7bc0629b2840a7a23d71bd27b08303426ab7b013d8a272d9a1fedc82b8f40ba8fdd6805724f878fbf4374752912658ea5922e79548f16a53a859cf4de3164

data/CHANGELOG.md

@@ -5,6 +5,75 @@ 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.204.0] - 2026-09-19
+
+### Added — document-level mutation completed: #1229 (the 1.9.204 surface)
+
+- **`Document#clear_declaration`** — un-sets the XML declaration
+  (clears version/encoding and the standalone marker); the
+  document serializes exactly as if the input had none.
+  Idempotent; returns self.
+- **`Document#remove_doctype`** — un-sets the DOCTYPE; it leaves
+  the child chain and the serializer's view while the DocType
+  stays pool-owned and readable (`doc.doctype.name` et al.) until
+  `#free`. Returns true when removed, false when the document had
+  none. Rounds out the write-half next to `#set_doctype` /
+  `doc.doctype` (the read/create faces wired earlier).
+- Completes upstream leptris/leptris#1229 and, with it, the
+  leptris-ruby#275 umbrella (PI removal 1.9.9, declaration clear +
+  DOCTYPE unset 1.9.204). Spec battery in
+  `document_construction_spec.rb`.
+- Engine adoption: 1.9.203 (`leptris_dtd_parse` honors the
+  NULL-on-error contract, upstream #1211) and 1.9.204 (html.h
+  subsystem header, one-shot name fast paths, one-call buffer-mode
+  pull feeds). #1229's two exports are wired as the
+  `Document#clear_declaration` / `#remove_doctype` faces; the
+  other two 1.9.204 exports attach for lockstep parity
+  (`leptris_sax_parser_set_one_shot` — the binding's one-shot SAX
+  entry is one-shot by construction and pull's memory source sets
+  it engine-side; `leptris_alloc_buffer` — engine-heap allocation
+  for callback-owned buffers like the DTD PE loader, released via
+  the already-bound `leptris_free_string`). Audit 333/333.
+
+### Fixed — portability (audit:symbols + POWER vendor mapping)
+
+- `nm -gU` → `nm -g`: GNU binutils nm (Debian bookworm 2.40)
+  accepts `-U` but then ignores the file operand entirely
+  (`nm: 'a.out': No such file`, empty export list, guaranteed
+  false drift). Undefined externals print two columns, so the
+  existing `split[2]` + `compact` already skips them on every nm
+  flavor. The engine build itself succeeded on ppc64le this round
+  — #1196's LTO crash did not reproduce.
+- `vendor_platforms_for` normalizes RbConfig's `powerpc64le` to
+  the gem-tier spelling `ppc64le`: the JVM-host rebuild ("java" →
+  host cpu-os) matched no tier on POWER hosts, so JRuby/
+  TruffleRuby there missed their vendored binary. Surfaced by the
+  ppc64le qemu leg (ffi_spec:223) once the audit fix let the suite
+  run; the spec now asserts JVM ≡ host tier.
+
+### Not fixed despite upstream closes
+
+- **Iterparse attribute reads: all-nil runs on ubuntu-latest Ruby
+## [1.9.207.0] - 2026-09-19
+
+### Fixed — engine sync: big-endian close-tag parse (#1197 upstream)
+
+- Vendored libleptris 1.9.207: the close-tag fast-path compare
+  masked the wrong end of its 8-byte name load on big-endian hosts,
+  rejecting ordinary paired-tag documents with "malformed input"
+  (434/727 binding-suite failures under qemu s390x). The mask now
+  follows memory order per byte dialect; the s390x-linux-musl
+  platform gem becomes viable with this release.
+
+### Added — FFI mirror adopts the 1.9.202–1.9.207 engine surface
+
+- audit:symbols lockstep attachments: recover diagnostics
+  (leptris_document_parse_diag[_count]), the standalone DTD family
+  (leptris_dtd_*), declaration/doctype removal, engine-heap buffer
+  allocation, and one-shot SAX. leptris_set_error stays internal —
+  the engine now hides it on ELF too (leptris#1243), so the export
+  surface agrees across Linux/macOS/Windows.
+
 ## [1.9.201.3] - 2026-09-19
 
 ### Added — the HTML facade (Nokogiri-shaped entry points)

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.201"
+LIBLEPTRIS_VERSION = "1.9.207"
 # 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
@@ -326,7 +326,13 @@ namespace :audit do
     unless lib
       abort "audit:symbols: vendored library not found — run rake compile"
     end
-    exported = `nm -gU #{lib}`
+    # Plain -g, not -U: GNU binutils nm (Debian bookworm 2.40)
+    # accepts -U but then ignores the file operand entirely
+    # ("nm: 'a.out': No such file", empty export list, guaranteed
+    # false drift — the ppc64le leg). Undefined externals print two
+    # columns (type, name), so split[2] is nil for them and the
+    # compact below already drops them on every nm flavor.
+    exported = `nm -g #{lib}`
       .lines.map { |l| l.split[2] }.compact
       .map { |n| n.sub(/\A_/, "") }
       .select { |n| n.start_with?("leptris_") }

data/lib/leptris/version.rb

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

data/lib/leptris/xml/document.rb

@@ -635,6 +635,31 @@ class Leptris::XML::Document
     Leptris::XML::DocType.new(dt, self)
   end
 
+  # Un-set the XML declaration (libleptris 1.9.204, upstream
+  # #1229): the document stops being declaration-bearing and
+  # serialization emits none — exactly as if the input had none.
+  # Clears version/encoding and the standalone marker. Idempotent.
+  # Returns self.
+  def clear_declaration
+    Leptris::XML::FFI.check_status(
+      Leptris::XML::FFI.leptris_document_clear_declaration(c_ptr))
+    @version += 1
+    self
+  end
+
+  # Un-set the document's DOCTYPE (libleptris 1.9.204, upstream
+  # #1229). The DocType stays pool-owned and readable via #doctype
+  # until #free; it leaves the child chain and the serializer's
+  # view. Returns true when removed, false when the document had
+  # none.
+  def remove_doctype
+    rc = Leptris::XML::FFI.leptris_document_remove_doctype(c_ptr)
+    return false if rc == Leptris::XML::FFI::LEPTRIS_ERROR_NOT_FOUND
+    Leptris::XML::FFI.check_status(rc)
+    @version += 1
+    true
+  end
+
   # Append a document-level comment (epilog position, after the
   # root element) — the add_pi twin (libleptris 1.9.160, #1032;
   # parsed document-level comments round-tripped since 1.9.3/#578,

data/lib/leptris/xml/dtd.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require "ffi"
+
+module Leptris::XML
+  # DTD validation (the libleptris 1.9.202-exported surface, the
+  # leptris validate --dtd CLI's library face): parse an internal
+  # subset, optionally merge an external subset (the application
+  # owns I/O — read the resource named by the DOCTYPE system id
+  # and hand the bytes over), then validate any number of documents.
+  # The RelaxNG shape: parse once, validate many; errors carry
+  # message/element/line/column.
+  #
+  #     dtd = Leptris::XML::DTD.parse(<<~DTD)
+  #       <!ELEMENT book (title, author+)>
+  #       <!ATTLIST book id ID #REQUIRED>
+  #     DTD
+  #     dtd.valid?(doc)
+  #     dtd.validate(doc)  # => [{message:, element:, line:, column:}]
+  #
+  module DTD
+    module_function
+
+    def parse(dtd_content)
+      DTDHandle.parse(dtd_content)
+    end
+
+    # The document's own internal subset (from its DOCTYPE), as a
+    # validatable handle: document-owned, never freed by the caller.
+    # Extend it with an external subset via #merge_external_subset.
+    def from_document(document)
+      DTDHandle.wrap_owned(
+        Leptris::XML::FFI.leptris_document_get_dtd(document.c_ptr))
+    end
+
+    # One struct-free convenience: validate +first_error. Returns
+    # nil when valid.
+    def first_error(document, dtd_content)
+      DTDHandle.parse(dtd_content).first_error(document)
+    end
+
+    class DTDHandle
+      def self.parse(dtd_content)
+        content = dtd_content.to_s
+        raw = Leptris::XML::FFI.leptris_dtd_parse(
+          content, content.bytesize)
+        if raw.null?
+          raise Leptris::XML::Error,
+            "DTD parse failed: #{Leptris::XML::FFI.leptris_last_error}"
+        end
+        new(OwnedHandle.new(raw))
+      end
+
+      def self.wrap_owned(ptr)
+        new(nil, ptr)
+      end
+
+      class OwnedHandle < ::FFI::AutoPointer
+        def self.release(ptr)
+          Leptris::XML::FFI.leptris_dtd_free(ptr)
+        end
+      end
+
+      def initialize(owned, doc_owned_ptr = nil)
+        @owned = owned
+        @ptr = doc_owned_ptr || owned
+      end
+
+      def c_ptr
+        @ptr
+      end
+
+      # Merge an external subset (the application reads the resource;
+      # the library never does I/O). First declaration of a name wins,
+      # so the internal subset is never overridden.
+      def merge_external_subset(content)
+        c = content.to_s
+        rc = Leptris::XML::FFI.leptris_dtd_parse_external_subset(
+          c_ptr, c, c.bytesize)
+        raise Leptris::XML::Error, "external subset merge failed" if rc.negative?
+        self
+      end
+
+      def valid?(document)
+        validate(document).empty?
+      end
+
+      # [{ message:, element:, line:, column: }] — empty when valid.
+      def validate(document)
+        err = Leptris::XML::FFI::DTDErrorStruct.new
+        rc = Leptris::XML::FFI.leptris_dtd_validate(
+          document.c_ptr, c_ptr, err)
+        return [] if rc == 1
+        return [{ message: "internal validation error" }] if rc.negative?
+        message = err[:message]
+        return [{ message: "validation failed" }] if message.nil?
+        [{
+          message: message,
+          element: err[:element_name],
+          line: err[:line],
+          column: err[:column],
+        }]
+      ensure
+        Leptris::XML::FFI.leptris_dtd_error_free(err) unless rc == 1
+      end
+
+      # nil when valid — the single-error convenience.
+      def first_error(document)
+        validate(document).first
+      end
+    end
+  end
+end

data/lib/leptris/xml/ffi.rb

@@ -26,6 +26,9 @@ module Leptris
           end
           cpu = RbConfig::CONFIG["host_cpu"].to_s
           cpu = "aarch64" if cpu.empty?
+          # RbConfig says "powerpc64le"; the gem/vendor tier is
+          # "ppc64le-linux" (the gem platform spelling).
+          cpu = "ppc64le" if cpu == "powerpc64le"
           os = host_os =~ /darwin/ ? "darwin" : "linux"
           ruby_platform = "#{cpu}-#{os}"
         end
@@ -118,6 +121,7 @@ module Leptris
       typedef :pointer, :leptris_node_ref
       typedef :pointer, :leptris_attribute
       typedef :pointer, :leptris_doctype
+      typedef :pointer, :leptris_dtd
       typedef :pointer, :leptris_xpath_result
       typedef :pointer, :leptris_xpath_ns_set
       typedef :pointer, :leptris_xpath_compiled
@@ -133,6 +137,7 @@ module Leptris
       typedef :pointer, :leptris_iterparse
       typedef :pointer, :leptris_xpath_var_set
       typedef :pointer, :leptris_sax_parser
+      typedef :pointer, :leptris_dtd
       typedef :int, :leptris_status
 
       class SAXHandler < ::FFI::Struct
@@ -381,6 +386,12 @@ attach_function :leptris_parse_string,
         [:leptris_document, :int], :leptris_status
       attach_function :leptris_document_set_doctype,
         [:leptris_document, :string, :string, :string], :leptris_doctype
+      # The #1229 remove-half (libleptris 1.9.204): un-set the
+      # declaration; un-set the DOCTYPE (NOT_FOUND when none set).
+      attach_function :leptris_document_clear_declaration,
+        [:leptris_document], :leptris_status
+      attach_function :leptris_document_remove_doctype,
+        [:leptris_document], :leptris_status
       attach_function :leptris_document_append_pi,
         [:leptris_document, :string, :string], :leptris_node_ref
       attach_function :leptris_document_remove_child,
@@ -849,6 +860,14 @@ attach_function :leptris_parse_string,
         [:leptris_sax_parser], :void
       attach_function :leptris_sax_parser_set_streaming,
         [:leptris_sax_parser, :int], :int
+      # One-shot input hint (libleptris 1.9.204): whole document in
+      # a single feed(), alive for the parser's lifetime — enables
+      # in-place scans. The binding's one-shot entry
+      # (leptris_sax_parse) is one-shot by construction; the engine
+      # sets this itself for pull's memory source. Attach-only
+      # until a chunked-feed face wants to opt in.
+      attach_function :leptris_sax_parser_set_one_shot,
+        [:leptris_sax_parser, :int], :void
 
       # Pull parsing (v1.6.0): StAX-style cursor over a document.
       attach_function :leptris_pull_new,
@@ -1024,6 +1043,30 @@ attach_function :leptris_parse_string,
       attach_function :leptris_str_has_nonstandard_entity,
         [:string, :size_t], :int
 
+      # DTD validation (exported 1.9.202; the surface existed
+      # since the CLI work): parse an internal subset, merge an
+      # external subset (application-owned I/O), validate a
+      # document. Errors carry message/element/line/column.
+      class DTDErrorStruct < ::FFI::Struct
+        layout :message, :string,
+               :element_name, :string,
+               :line, :int,
+               :column, :int
+      end
+      attach_function :leptris_dtd_parse,
+        [:string, :size_t], :pointer
+      # leptris_document_get_dtd attached above with the readers
+      attach_function :leptris_dtd_parse_external_subset,
+        [:pointer, :string, :size_t], :int
+      attach_function :leptris_dtd_set_pe_loader,
+        [:pointer, :pointer, :pointer], :void
+      attach_function :leptris_dtd_validate,
+        [:leptris_document, :pointer, :pointer], :int
+      attach_function :leptris_dtd_free,
+        [:pointer], :void
+      attach_function :leptris_dtd_error_free,
+        [:pointer], :void
+
       attach_function :leptris_rng_parse,
         [:string, :size_t, :pointer], :leptris_relaxng
       attach_function :leptris_rng_parse_file,
@@ -1100,6 +1143,11 @@ attach_function :leptris_parse_string,
         [:leptris_doctype], :string
 
       attach_function :leptris_free_string, [:pointer], :void
+      # Engine-heap allocation (libleptris 1.9.204): buffers handed
+      # to engine callbacks (the DTD PE loader) so the engine frees
+      # through its matching deallocation path. Release with
+      # leptris_free_string when NOT consumed by the engine.
+      attach_function :leptris_alloc_buffer, [:size_t], :pointer
       attach_function :leptris_explicit_cleanup, [], :void
       attach_function :leptris_set_memory_management_functions,
         [:pointer, :pointer], :void
@@ -1109,6 +1157,33 @@ attach_function :leptris_parse_string,
         [:leptris_document, :pointer, :pointer], :leptris_status
       attach_function :leptris_status_string, [:leptris_status], :string
       attach_function :leptris_error_message, [:leptris_status], :string
+      # Engine surface adopted with libleptris 1.9.206 (the FFI
+      # mirror audit keeps attachments and exports in lockstep):
+      # recover diagnostics (#1200), the standalone DTD family
+      # (leptris_dtd_*), declaration/doctype removal (#1094), the
+      # engine-heap buffer (#1219), one-shot SAX (#1178), and the
+      # exported error-recorder entry point.
+      attach_function :leptris_alloc_buffer, [:size_t], :pointer
+      attach_function :leptris_document_clear_declaration,
+        [:leptris_document], :leptris_status
+      attach_function :leptris_document_remove_doctype,
+        [:leptris_document], :leptris_status
+      attach_function :leptris_document_parse_diag_count,
+        [:leptris_document], :size_t
+      attach_function :leptris_document_parse_diag,
+        [:leptris_document, :size_t, :pointer, :pointer, :size_t], :int
+      attach_function :leptris_dtd_parse,
+        [:string, :size_t], :leptris_dtd
+      attach_function :leptris_dtd_free, [:leptris_dtd], :void
+      attach_function :leptris_dtd_parse_external_subset,
+        [:leptris_dtd, :string, :size_t], :int
+      attach_function :leptris_dtd_set_pe_loader,
+        [:leptris_dtd, :pointer, :pointer], :void
+      attach_function :leptris_dtd_validate,
+        [:leptris_document, :leptris_dtd, :pointer], :int
+      attach_function :leptris_dtd_error_free, [:pointer], :void
+      attach_function :leptris_sax_parser_set_one_shot,
+        [:leptris_sax_parser, :int], :void
       # Thread-global last-failure position (error.h): companion to
       # leptris_last_error; populated by recover parses (#547).
       attach_function :leptris_last_error_position,

data/lib/leptris/xml.rb

@@ -34,6 +34,7 @@ module Leptris
     autoload :XSLT, "leptris/xml/xslt"
     autoload :XQuery, "leptris/xml/xquery"
     autoload :RelaxNG, "leptris/xml/relaxng"
+    autoload :DTD, "leptris/xml/dtd"
     autoload :Pull, "leptris/xml/pull"
     autoload :Iterparse, "leptris/xml/iterparse"
 

data/vendor-src/libleptris/CHANGELOG.md

@@ -1,5 +1,84 @@
 ## [Unreleased]
 
+## [1.9.207] - 2026-09-19
+
+### Fixed
+
+- stop leptris_set_error leaking into the ELF dynamic table (build)
+
+
+
+## [1.9.206] - 2026-09-19
+
+### Fixed
+
+- endian-neutral close-tag name compare (#1197) (parse)
+
+### Performance
+
+- memchr finds the text span end (TODO.max-perf/2-3 slice 3) (sax)
+- zero-copy slice emission for one-shot pulls (#1178 tail) (sax)
+
+
+
+## [1.9.205] - 2026-09-19
+
+### Added
+
+- Parse recover diagnostics (#1200): the DOM parse now records
+  duplicate-attribute events on the document — `LeptrisDiagKind`
+  (with the new `LEPTRIS_DIAG_RECOVER` kind) is public in
+  types.h, and the diag list reads through
+  `leptris_document_parse_diag_count` /
+  `leptris_document_parse_diag` (error.h). First definition wins,
+  matching the SAX lane's libxml2-recover surface; the digest
+  gate no longer needs a SAX probe pass.
+- `LEPTRIS_DIGEST_ATTR_ORDER` (#1200 part 1): opt-in digest flag
+  that makes attribute order identity-bearing instead of sorted
+  away.
+
+### Fixed
+
+- MSVC C2027 in `leptris_internal.h`: the `LeptrisDiag` forward
+  declaration moved to file scope (broke the windows-dll-exports
+  leg).
+
+### Performance
+
+- First-char-bucketed tag classifier for the WHATWG HTML path:
+  the tokenizer's name-list strcmp scans become one-load bucket
+  lookups — parse +31-37% on the #1218 bench shapes.
+
+
+
+## [1.9.204] - 2026-09-19
+
+### Added
+
+- leptris/html.h subsystem header; one-shot name fast paths (slice 1); document HTML parsing (api+perf)
+
+### Performance
+
+- buffer-mode pull feeds in ONE call (slice-1 prerequisite) (sax)
+
+
+
+## [1.9.203] - 2026-09-19
+
+### Fixed
+
+- leptris_dtd_parse honors the NULL-on-error contract (#1211) (dtd)
+
+
+
+## [1.9.202] - 2026-09-18
+
+### Fixed
+
+- export the DTD validation surface; gate unmarked public declarations (api)
+
+
+
 ## [1.9.201] - 2026-09-18
 
 <!-- Edit this section with the actual release notes. -->

data/vendor-src/libleptris/CLAUDE.md

@@ -69,7 +69,7 @@ Core (src/leptris/)    →  DOM, parser, XPath engine, SAX, DTD, encoding, memor
 - `xinclude/` — built and shipping. `parse="text"` with `xi:fallback` works end-to-end. `parse="xml"` and xpointer are TODO 92.
 
 ### Public API surface (`src/include/leptris/`)
-The public contract. Don't break ABI without a major bump. Headers split by subsystem: `dom/{document,element,serialize}.h`, `xpath/xpath.h`, `sax/sax.h`, plus `types.h`, `error.h`, `dtd.h` at the top level. All handles are opaque typedefs (`LeptrisDocument`, `LeptrisElement`, `LeptrisNodeRef`, …); callers never see struct definitions.
+The public contract. Don't break ABI without a major bump. Headers split by subsystem: `dom/{document,element,serialize}.h`, `xpath/xpath.h`, `sax/sax.h`, `html.h`, plus `types.h`, `error.h`, `dtd.h` at the top level. All handles are opaque typedefs (`LeptrisDocument`, `LeptrisElement`, `LeptrisNodeRef`, …); callers never see struct definitions.
 
 ### Memory model
 - Pool allocator is the dominant allocation path — node creation should go through `leptris_node_create_pooled`.

data/vendor-src/libleptris/CMakeLists.txt

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

data/vendor-src/libleptris/README.adoc

@@ -320,6 +320,32 @@ if (r) {
 Supported: all 13 axes, all 27 functions, all 15 operators, full
 predicate syntax.  See <<api,xpath-coverage>> for details.
 
+==== HTML parsing (WHATWG + libxml2-compat)
+
+HTML is a first-class input — two tolerant parsers, both declared in
+`leptris/html.h`:
+
+[source,c]
+----
+LeptrisStatus st;
+/* WHATWG-conformant tree construction (html5lib corpus green). */
+LeptrisDocument doc =
+    leptris_parse_html_string("<p>Hello <b>world", 18, &st);
+
+/* Nokogiri byte-for-byte shape: no synthesized <html>/<head>/<body>,
+ * no implied <tbody>, leading script/style content stays in <body>. */
+LeptrisDocument frag =
+    leptris_parse_html4_string("<p>Hello <b>world", 18, &st);
+----
+
+Both handle implied end tags (`p`/`li`/`td`/`tr`/`th`/`dt`/`dd`/
+`option`/...), void elements, raw-text `script`/`style`, minimized
+and unquoted attribute values, case-insensitive tag/attribute names,
+and the HTML named-entity table.  Malformed input never fails the
+parse — it degrades to text; the result serializes and queries
+(XPath/XSLT) like any XML document.  Memory contract identical to
+`leptris_parse_string`.
+
 ==== Parsing models: DOM, SAX, StAX, iterparse
 
 One engine, four consumption models. Pick by how you want to pay:

data/vendor-src/libleptris/TODO.max-perf/2-3-oneshot-tokenizer-design.md

@@ -0,0 +1,98 @@
+# Levers 2+3 — compiled-dispatch + zero-copy one-shot emission (design)
+
+Status: DESIGNED (2026-09-19). Implementation slices below.
+Owners: engine repo. Bench: `benchmarks/sax/bench_iterparse.c` (#1195).
+
+## Problem
+
+The pull/iterparse path costs 4.4x the compact DOM parse over the
+same bytes (10KB medium: pull 54.7us vs DOM one-shot 12.3us).
+Root cause (measured, #1178): every event string is copied twice —
+
+1. streaming.c copies names/text/attrs into per-frame storage
+   (scratch arena + inline name bufs), because a streaming feed()
+   chunk may be freed once the call returns;
+2. pull.c's cb_* strdups them again into queue events, freed at the
+   next _next.
+
+A falsified attempt (per-call arena staging in _next) ADDED a third
+copy layer and measured slower (54.7 -> 67.6us) — churn-shaving the
+wrong layer cannot win; the copies must not happen at all.
+
+## Insight
+
+One-shot parses (leptris_sax_parse / leptris_pull_new over an
+in-memory buffer) have no interruption: the input buffer is
+immutable (#1125), caller-owned, and alive for the whole iteration
+(the pull API already documents input-lifetime for buffer mode).
+Names and attribute names cannot contain entity references (XML
+names are name-chars only), so in one-shot mode they are always
+contiguous slices of the input — borrowable with zero copies.
+
+Only entity-expanded payloads (attribute values, text with &...;)
+must materialize; the common case has none.
+
+## Design
+
+### Slice events (one-shot only)
+
+```
+typedef struct {
+    const char* ptr;   /* points INTO the input buffer */
+    size_t      len;
+} LeptrisSlice;
+
+typedef struct {
+    LeptrisPullEventType type;
+    LeptrisSlice name;         /* element / PI target          */
+    LeptrisSlice text;         /* ONLY if no entities: borrowed */
+    char*        text_owned;   /* materialized when entities    */
+    LeptrisSlice attr_flat[];  /* name,value pairs, names always
+                                  borrowed; values borrowed when
+                                  entity-free, else owned       */
+} OneShotEvent;
+```
+
+Rule: a payload is borrowed iff the engine can prove (single scan,
+memchr '&') that its span contains no '&'. One memchr per payload
+replaces one malloc+memcpy+free — and '&' is absent from the vast
+majority of real payloads.
+
+### Compiled dispatch (lever 2)
+
+The streaming machine's per-state if-chains (peek '<', '/', '!',
+name-start, ws...) become a 256-entry class table + a state-indexed
+goto/switch jump table:
+
+- class LUT: 4 bits (WS, NAME_START, NAME_CHAR, SPECIAL masks) —
+  one load classifies each byte (the #1177 LUT result generalized);
+- state dispatch: `switch (state)` compiled to a jump table by the
+  compiler once states are a dense enum — keep cases small and
+  branchless-friendly (the hot tokenizer states are ~20).
+
+The SAME token loop serves both modes: streaming keeps frames/carry
+(one_shot=0); one-shot mode (one_shot=1) skips carry and frame
+copies, emits slices, and materializes only entity spans.
+
+### Consumer adaptation
+
+pull.c gains a one-shot queue variant: cb_* check parser->one_shot
+and enqueue slice events (no strdup); queue_reset_event frees only
+owned pointers. Batch staging (#589) copies out of slices on
+demand — the existing stage chain unchanged.
+
+## Slices
+
+1. **Slice events + one-shot flag** in streaming.c; pull one-shot
+   queue. Acceptance: bench_iterparse full-doc 0.47us/event ->
+   <=0.15us/event; no test changes (contracts identical).
+2. **Class LUT + dense-state dispatch** in the tokenizer loop.
+   Acceptance: bench_sax +5% minimum; no behavioral delta.
+3. **memchr fast paths** for text/attr-value spans feeding the
+   borrow check. Acceptance: entity-free docs near-memcpy speed.
+
+## Non-goals
+
+- No API changes; event lifetime contracts unchanged.
+- Streaming feed() semantics untouched (frames/carry stay).
+- No new allocation strategies in pull.c (the falsified lesson).