makiri 0.5.1 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ee7e950514b33a2fa483cb6f4f4f48d5b80b8b6cc2205dbf720c2f47f790821d
-  data.tar.gz: 5c6739b1eabec71dbc34b8ce410c4ada7053112dd88d04d278840070178b4aa4
+  metadata.gz: c178d50564ea8152e886817e6df19628c491eb7bb1213e06ab70f6ffe8665015
+  data.tar.gz: 55a69b4d93c40b130581cb078ffee01dc6355cec4843fdc0f86269d7d22a4390
 SHA512:
-  metadata.gz: 51af947ded032f4e09d3c622374cf09bbbc36f92f3f2006c98bd2f6d4884b51de83ded0a6faf8174be27cece0986d317ea2cd553e6837286d7c1d0a743c3261d
-  data.tar.gz: da5184494302a3c43cd8014972cf43e6c684460af1a53ef219a42bdfac9238e98a792ec2976b442462661ea63328330195408dd31d9b180f8dd421122676de13
+  metadata.gz: c87c6c98a58fe500d60f7775c088c655d3938e22cf614ed57b84d395d15229bd4dfbf5e61909c86804132d90dfdb31d62278e36ed7399c66102590c13867ca36
+  data.tar.gz: 2da0687466e5c2faab9d0c95d8181e529acf68b30165c9357375edb10e5dff5cd45557e7186c133fdfaf40043f7d2c2f3ee1a49d945cacea4f46c1b56b195c2c

data/.github/workflows/ci.yml

@@ -12,7 +12,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        os: [ubuntu-latest, macos-latest]
+        os: [ubuntu-latest, macos-latest, windows-latest]
         ruby: ["3.2", "3.3", "3.4", "4.0"]
 
     steps:
@@ -42,6 +42,7 @@ jobs:
           THREADING: ${{ (matrix.os == 'ubuntu-latest' && matrix.ruby == '3.4') && '1' || '' }}
 
       - name: Smoke-load the gem
+        shell: bash
         run: bundle exec ruby -Ilib -r makiri -e 'p Makiri::VERSION'
 
   sanitize:

data/.github/workflows/libfuzzer.yml

@@ -21,7 +21,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        target: [xml, xpath]
+        target: [xml, xpath, xml_xpath]
 
     steps:
       - name: Checkout (with vendored Lexbor submodule)

data/.github/workflows/release.yml

@@ -62,10 +62,12 @@ jobs:
         - x86_64-linux
         - aarch64-linux
         - arm64-darwin
+        - x64-mingw-ucrt
         include:
-          - { platform: x86_64-linux,  os: ubuntu-latest }
-          - { platform: aarch64-linux, os: ubuntu-24.04-arm }
-          - { platform: arm64-darwin,  os: macos-14 }
+          - { platform: x86_64-linux,   os: ubuntu-latest }
+          - { platform: aarch64-linux,  os: ubuntu-24.04-arm }
+          - { platform: arm64-darwin,   os: macos-14 }
+          - { platform: x64-mingw-ucrt, os: windows-latest }
     steps:
       - uses: actions/checkout@v6
         with:
@@ -79,6 +81,7 @@ jobs:
       - name: Compile (builds vendored Lexbor, then the ext)
         run: bundle exec rake compile
       - name: Smoke-load
+        shell: bash
         run: bundle exec ruby -Ilib -r makiri -e 'p Makiri::VERSION'
       - name: Stage the compiled binary under its ABI subdir
         shell: bash
@@ -97,16 +100,25 @@ jobs:
         run: |
           dlext="$(ruby -e 'print RbConfig::CONFIG["DLEXT"]')"
           bin="lib/makiri/makiri.${dlext}"
-          if [ "$(uname)" = "Darwin" ]; then
-            if otool -L "$bin" | grep -i 'libruby'; then
-              echo "::error::$bin hard-links libruby; precompiled gem would not load on other Ruby installs"; exit 1
-            fi
-          else
-            if readelf -d "$bin" 2>/dev/null | grep -iE 'NEEDED.*libruby'; then
-              echo "::error::$bin has a libruby NEEDED entry; precompiled gem may not load on a static Ruby"; exit 1
-            fi
-          fi
-          echo "OK: $bin has no libruby dependency"
+          case "$(uname -s)" in
+            Darwin)
+              if otool -L "$bin" | grep -i 'libruby'; then
+                echo "::error::$bin hard-links libruby; precompiled gem would not load on other Ruby installs"; exit 1
+              fi
+              ;;
+            MINGW*|MSYS*|CYGWIN*)
+              # Windows PE DLLs MUST import the Ruby DLL via the import library
+              # (no dynamic_lookup on PE/COFF). A libruby import here is by design,
+              # not a portability bug, so this assertion does not apply.
+              echo "Windows (x64-mingw-ucrt): Ruby import-library link is by design; skipping libruby assertion"
+              ;;
+            *)
+              if readelf -d "$bin" 2>/dev/null | grep -iE 'NEEDED.*libruby'; then
+                echo "::error::$bin has a libruby NEEDED entry; precompiled gem may not load on a static Ruby"; exit 1
+              fi
+              ;;
+          esac
+          echo "OK: portability check complete for $bin"
       - uses: actions/upload-artifact@v7
         with:
           name: bin-${{ matrix.platform }}-${{ matrix.ruby }}
@@ -128,6 +140,8 @@ jobs:
           os: ubuntu-24.04-arm
         - platform: arm64-darwin
           os: macos-14
+        - platform: x64-mingw-ucrt
+          os: windows-latest
     steps:
       - uses: actions/checkout@v6
         with:
@@ -157,6 +171,7 @@ jobs:
       - name: Build the native gem
         run: ruby script/build_native_gem.rb "${{ matrix.platform }}"
       - name: Verify it installs without recompiling
+        shell: bash
         run: |
           gem install "makiri-"*"-${{ matrix.platform }}.gem" --local
           ruby -e 'require "makiri"; puts Makiri::VERSION'

data/.github/workflows/verify.yml

@@ -0,0 +1,37 @@
+name: Verify
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  cbmc:
+    name: CBMC proofs
+    runs-on: ubuntu-24.04
+    timeout-minutes: 20
+
+    steps:
+      - name: Checkout (with vendored Lexbor submodule)
+        uses: actions/checkout@v6
+        with:
+          submodules: recursive
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.4"
+          bundler-cache: true
+
+      - name: Install CBMC
+        env:
+          CBMC_VERSION: "6.9.0"
+        run: |
+          curl -fsSLO "https://github.com/diffblue/cbmc/releases/download/cbmc-${CBMC_VERSION}/ubuntu-24.04-cbmc-${CBMC_VERSION}-Linux.deb"
+          sudo apt-get update
+          sudo apt-get install -y "./ubuntu-24.04-cbmc-${CBMC_VERSION}-Linux.deb"
+          cbmc --version
+
+      - name: Run verification suite
+        run: bundle exec rake verify

data/CHANGELOG.md

@@ -1,5 +1,57 @@
 # Changelog
 
+## [0.7.0] - 2026-07-11
+
+### Added
+
+* `Document#create_document_type(name, public_id = "", system_id = "")` on both
+  `Makiri::HTML::Document` and `Makiri::XML::Document` (DOM
+  `DOMImplementation.createDocumentType`): creates a detached `DocumentType`
+  node, to be placed before the document element (e.g. with
+  `root.add_previous_sibling(doctype)`). The name is case-preserving; an omitted
+  or empty public/system id is treated as absent; an invalid name (or a `"` in an
+  id) raises. Inserting a doctype is validated against the WHATWG rules — it may
+  only be a child of the document, must precede the document element, and a
+  document holds at most one — so a misplaced or duplicate doctype raises rather
+  than producing a malformed tree.
+
+* The XML `DocumentType` is now part of the tree: it appears in
+  `Document#children` (before the root, like a browser DOM) and carries
+  `parent`/sibling links, for both a parsed `<!DOCTYPE>` and the factory above.
+  `Document#internal_subset` still returns it. XPath is unaffected — its 1.0 data
+  model excludes the doctype (`//node()` / `/node()` never surface it), as in
+  Nokogiri/libxml2. This supports building a document with
+  `DOMImplementation.createDocument(namespace, qualifiedName, doctype)`.
+
+* `Makiri::XML::Document#create_loose_dom_element(qualified_name, prefix,
+  local_name, namespace_uri)`, an escape hatch for browser-DOM interop that
+  creates an element whose name follows WHATWG DOM element-name rules rather
+  than the stricter XML QName rules (e.g. `"f:o:o"`, `":foo"`, `"0:a"`). The
+  regular factories stay XML-strict. Such an element is intentionally not
+  XML-serializable: `#to_xml` and `#canonicalize` raise `Makiri::Error` if the
+  tree contains one. Renaming it to a valid XML name (`#name=`) returns it to
+  strict mode.
+
+### Fixed
+
+* Replacing an XML node with a `DocumentFragment` (`node.replace(fragment)`) is
+  now all-or-nothing: if the replacement is rejected (e.g. it would leave the
+  document with two root elements), the target node and the fragment are left
+  untouched, instead of dropping the target and splicing in only part of the
+  fragment. Replacing the root element with a single-element fragment now works.
+
+## [0.6.0] - 2026-07-05
+
+### Changed
+
+* Text and comment node content (`create_text_node`, `create_comment`,
+  `content=`) and attribute values (`[]=`, `set_attribute_ns`) now accept an
+  embedded NUL (U+0000) and store it verbatim, matching the WHATWG DOM and
+  browsers, instead of raising. Names, tag names, namespaces, CSS selectors, and
+  XPath expressions stay NUL-strict, and invalid UTF-8 is still rejected. XML
+  documents (`Makiri::XML`) are unchanged and still reject NUL everywhere, since
+  XML 1.0 has no legal U+0000 character.
+
 ## [0.5.1] - 2026-06-22
 
 ### Changed

data/README.md

@@ -267,6 +267,22 @@ Detailed, test-backed notes live in `spec/conformance/README.md`.
 * Type selectors are ASCII case-insensitive (CSS-correct for HTML; `LI` matches `<li>`)
   * `Nokogiri::HTML5` is case-sensitive there.
 
+### Text input (mutation APIs)
+
+* Programmatic string arguments must be **valid UTF-8** (invalid bytes raise
+  `Makiri::Error`, never silently repaired - unlike HTML *parsing*, which decodes
+  leniently to U+FFFD).
+* An embedded **NUL (U+0000)** is **accepted in HTML data-family content** -
+  text/comment node content (`create_text_node`, `create_comment`, `content=`)
+  and attribute values (`[]=`, `set_attribute_ns`) - and stored/read back
+  verbatim, matching the WHATWG DOM / browsers (`document.createTextNode("\0")`).
+  It is still **rejected** in names, tag names, namespaces, PI target/data, CSS
+  selectors, and XPath expressions/variable names (a NUL there raises).
+  * On re-parse, the HTML tokenizer replaces a U+0000 in text/attributes with
+    U+FFFD (WHATWG), so a serialized-then-reparsed round-trip is not byte-identical.
+  * `Makiri::XML` rejects NUL everywhere: XML 1.0 has no legal U+0000 character,
+    so admitting it would produce non-well-formed XML.
+
 ## Conformance
 
 The XPath engine and XML parser are original code, so their correctness is held by

data/Rakefile

@@ -287,6 +287,20 @@ task :oom do
   puts "(injection build left in place; run `rake clean compile` to restore a normal build)"
 end
 
+desc "CBMC proofs over the Ruby/Lexbor-free carve-out (core + XML + XPath front; " \
+     "needs cbmc; see docs/formal_verification.ja.md and verify/Makefile)"
+task :verify do
+  # The 10 CBMC proofs are independent processes with a lopsided cost
+  # distribution (a few ~1-2min solves dominate, the rest are trivial), so run
+  # them in parallel: wall-clock drops toward the single slowest harness with no
+  # loss of coverage. Cap -j at the CPU count (Etc.nprocessors; the runner has
+  # RAM for that many concurrent core-set solves). smoke/selftest are quick and
+  # come first as ordered goals.
+  require "etc"
+  jobs = Integer(ENV.fetch("VERIFY_JOBS", Etc.nprocessors))
+  sh "make", "-C", "verify", "-j#{jobs}", "smoke", "selftest", "cbmc"
+end
+
 desc "Run the performance benchmark (Makiri vs Nokogiri reference)"
 task bench: :compile do
   # Run outside the bundle so the bench-only gems (nokogiri, benchmark-ips)
@@ -303,13 +317,6 @@ task "bench:xml" => :compile do
   end
 end
 
-desc "Run the CSS selector-query benchmark on a note.com-style SPA page (set BENCH_CARDS)"
-task "bench:css" => :compile do
-  Bundler.with_unbundled_env do
-    sh "#{FileUtils::RUBY} -Ilib bench/bench_css_query.rb"
-  end
-end
-
 namespace :conformance do
   desc "WHATWG HTML5 parsing conformance: run html5lib-tests through Makiri"
   task html5: :compile do

data/ext/makiri/bridge/bridge.h

@@ -24,6 +24,22 @@ typedef struct {
     size_t      len;
 } mkr_ruby_borrowed_text_t;
 
+/* A validated, borrowed view of a Ruby String argument for a DATA-FAMILY
+ * mutation (text/comment/CDATA node content, attribute value). Contract: valid
+ * UTF-8, interior NUL ALLOWED, NUL-terminated at ptr[len] but - unlike
+ * mkr_ruby_borrowed_text_t - NOT usable as a C string, because an interior NUL
+ * may truncate it. Every consumer MUST pass (ptr, len) explicitly. `value`
+ * keeps `ptr` alive while the view stays on the C stack. This type is
+ * deliberately distinct from mkr_ruby_borrowed_text_t so the compiler forbids a
+ * NUL-bearing value from reaching a name or engine API that requires the
+ * NUL-free contract (DOM createTextNode/setAttribute must accept U+0000; names
+ * and engine strings still must not). */
+typedef struct {
+    VALUE       value;
+    const char *ptr;
+    size_t      len;
+} mkr_ruby_borrowed_data_t;
+
 /* A borrowed raw byte view of a Ruby String. This deliberately does NOT enforce
  * Makiri's strict text contract; HTML parsing consumes raw bytes and decodes
  * invalid UTF-8 leniently. */
@@ -37,6 +53,12 @@ typedef struct {
  * Makiri::Error (naming +what+) on a NUL byte or invalid UTF-8. */
 mkr_ruby_borrowed_text_t mkr_ruby_verified_text(VALUE in, const char *what);
 
+/* Constructor for mkr_ruby_borrowed_data_t (see its contract above): coerce +in+
+ * to a String, requiring valid UTF-8 but permitting an interior NUL. Raises
+ * Makiri::Error (naming +what+) on invalid UTF-8 only. For data-family values;
+ * names and engine strings use mkr_ruby_verified_text. */
+mkr_ruby_borrowed_data_t mkr_ruby_verified_data(VALUE in, const char *what);
+
 /* Coerce +in+ to a String and return its raw bytes. No UTF-8 / NUL validation.
  * The returned `ptr` borrows the bytes of `value`; use mkr_ruby_copy_bytes when
  * the buffer must outlive the source String. */
@@ -84,10 +106,12 @@ const char *mkr_ruby_try_verified_text(VALUE sv, size_t max_bytes,
  * escape. Embedded NULs are intentionally truncated by %s formatting. */
 void mkr_ruby_exception_message(VALUE exc, char *buf, size_t len);
 
-/* The sole constructor of mkr_verified_text_t. Turns an already-validated view
- * (from mkr_ruby_verified_text or mkr_ruby_try_verified_text) into the token the
- * XPath engine accepts. The returned token borrows v.ptr; the caller must keep
- * v.value alive for the duration of the engine call. */
+/* The Ruby-bound constructor of mkr_verified_text_t. Turns an already-validated
+ * view (from mkr_ruby_verified_text or mkr_ruby_try_verified_text) into the token
+ * the XPath engine accepts. The returned token borrows v.ptr; the caller must
+ * keep v.value alive for the duration of the engine call. The sole Ruby-free
+ * constructor is mkr_verified_text_lit (core/mkr_text.h), for compile-time
+ * literals. */
 mkr_verified_text_t mkr_verified_text_from_view(mkr_ruby_borrowed_text_t v);
 
 /* Assemble a UTF-8 Ruby String of exactly +total+ bytes by concatenating +n+

data/ext/makiri/bridge/bridge_internal.h

@@ -0,0 +1,28 @@
+#ifndef MAKIRI_BRIDGE_INTERNAL_H
+#define MAKIRI_BRIDGE_INTERNAL_H
+
+/* Bridge-private surface shared between the string-bridge TUs (ruby_string.c and
+ * xml_decode.c). Deliberately NOT part of the public glue API in bridge.h: this
+ * is the allocation-free core of Makiri's strict text contract, consumed both by
+ * the programmatic-API validators (ruby_string.c) and by the XML input decoder
+ * (xml_decode.c). */
+#include <ruby.h>
+#include <stddef.h>
+
+/* Verdict of the strict text contract (no NUL byte, valid UTF-8). Each caller
+ * maps a verdict to its own error surface (Makiri::Error, XML::SyntaxError, or a
+ * reason string). */
+typedef enum {
+    MKR_TEXT_OK = 0,
+    MKR_TEXT_HAS_NUL,
+    MKR_TEXT_INVALID_UTF8,
+} mkr_text_verdict_t;
+
+/* Check [ptr,len) against the strict text contract, consulting +coderange_str+'s
+ * CACHED coderange (no scan, no alloc) for the fast path; +ptr+/+len+ may be a
+ * suffix of +coderange_str+ (see the XML BOM-strip case). ALLOCATION-FREE BY
+ * DESIGN - it runs between a caller taking a borrowed RSTRING pointer and using
+ * it, so it must not be a GC point. Defined in ruby_string.c. */
+mkr_text_verdict_t mkr_text_check(VALUE coderange_str, const char *ptr, size_t len);
+
+#endif /* MAKIRI_BRIDGE_INTERNAL_H */

data/ext/makiri/bridge/ruby_string.c

@@ -1,5 +1,6 @@
 #include "bridge.h"
 #include "../makiri.h"
+#include "bridge_internal.h"
 
 #include <limits.h>
 #include <stdio.h>
@@ -48,6 +49,8 @@ mkr_ruby_str_from_borrowed(mkr_borrowed_text_t text)
 /* The shared core of Makiri's strict text contract: no NUL byte, valid UTF-8.
  * Returns the specific violation (or MKR_TEXT_OK); each caller maps the verdict
  * to its own error surface (Makiri::Error, XML::SyntaxError, or a reason string).
+ * The verdict enum + this signature are declared in bridge_internal.h so the XML
+ * input decoder (xml_decode.c) shares this one implementation.
  *
  * ALLOCATION-FREE BY DESIGN, which every caller relies on: it runs between a
  * caller taking a borrowed RSTRING pointer and using it, so it must not be a GC
@@ -62,13 +65,7 @@ mkr_ruby_str_from_borrowed(mkr_borrowed_text_t text)
  * the bytes (the BOM is one complete UTF-8 char, so a whole-string VALID
  * coderange still proves the suffix valid). Bytes are validated as UTF-8
  * regardless of the String's declared encoding. */
-typedef enum {
-    MKR_TEXT_OK = 0,
-    MKR_TEXT_HAS_NUL,
-    MKR_TEXT_INVALID_UTF8,
-} mkr_text_verdict_t;
-
-static mkr_text_verdict_t
+mkr_text_verdict_t
 mkr_text_check(VALUE coderange_str, const char *ptr, size_t len)
 {
     mkr_span_t sv = mkr_span(ptr, len);
@@ -115,6 +112,31 @@ mkr_ruby_verified_text(VALUE in, const char *what)
     return v;
 }
 
+mkr_ruby_borrowed_data_t
+mkr_ruby_verified_data(VALUE in, const char *what)
+{
+    VALUE       s   = rb_String(in);
+    const char *ptr = RSTRING_PTR(s);
+    size_t      len = (size_t)RSTRING_LEN(s);
+
+    /* Data-family (text/comment/CDATA content, attribute value): only invalid
+     * UTF-8 is fatal; an interior NUL is permitted so DOM data can hold U+0000.
+     * mkr_verify_text is not reused because it raises on NUL. mkr_text_check is
+     * allocation-free, so the borrow above is not held across a GC point. */
+    switch (mkr_text_check(s, ptr, len)) {
+        case MKR_TEXT_INVALID_UTF8:
+            rb_raise(mkr_eError, "%s must be valid UTF-8", what);
+        case MKR_TEXT_HAS_NUL: /* permitted for data-family */
+        case MKR_TEXT_OK:
+            break;
+    }
+    mkr_ruby_borrowed_data_t v;
+    v.value = s;
+    v.ptr   = ptr;
+    v.len   = len;
+    return v;
+}
+
 mkr_ruby_borrowed_bytes_t
 mkr_ruby_bytes_view(VALUE in)
 {
@@ -171,220 +193,6 @@ mkr_ruby_to_utf8(VALUE str)
                          ECONV_INVALID_REPLACE | ECONV_UNDEF_REPLACE, Qnil);
 }
 
-/* rb_str_encode with no replacement flags: an undefined conversion or invalid
- * byte sequence RAISES (Encoding::UndefinedConversionError /
- * Encoding::InvalidByteSequenceError) instead of substituting U+FFFD. Run under
- * rb_protect so we can remap the Ruby Encoding error to Makiri::XML::SyntaxError. */
-static VALUE
-mkr_xml_strict_transcode_thunk(VALUE str)
-{
-    return rb_str_encode(str, rb_enc_from_encoding(rb_utf8_encoding()), 0, Qnil);
-}
-
-/* --- XML 1.0 Appendix F: byte-encoding autodetection (BOM, then declaration) ---
- *
- * The leading byte-order mark, or NULL; *bom_len gets its length. UTF-32 BOMs are
- * checked before the UTF-16 LE BOM they share a prefix with.
- *
- * *stride / *ascii_off get the interleave geometry of the ASCII column the decl
- * scanner later extracts (default 1/0 for a single-byte stream). It is resolved
- * HERE, at the match, rather than re-derived downstream, because that derivation
- * needs rb_enc_find (it can autoload an encoding = a GC point) and the decl
- * scanner reads a borrowed RSTRING view that must not be held across one - so
- * the scanner is kept allocation-free until its reads are done. Each span read
- * of p still finishes before the rb_enc_find in the return. */
-static rb_encoding *
-mkr_xml_bom_encoding(const unsigned char *p, long len, long *bom_len, long *stride, long *ascii_off)
-{
-    mkr_span_t s = mkr_span((const char *)p, (size_t)len);
-    *bom_len = 0;
-    *stride = 1;
-    *ascii_off = 0;
-    if (mkr_span_starts(&s, "\x00\x00\xFE\xFF", 4)) { *bom_len = 4; *stride = 4; *ascii_off = 3; return rb_enc_find("UTF-32BE"); }
-    if (mkr_span_starts(&s, "\xFF\xFE\x00\x00", 4)) { *bom_len = 4; *stride = 4; *ascii_off = 0; return rb_enc_find("UTF-32LE"); }
-    if (mkr_span_starts(&s, "\xFE\xFF", 2)) { *bom_len = 2; *stride = 2; *ascii_off = 1; return rb_enc_find("UTF-16BE"); }
-    if (mkr_span_starts(&s, "\xFF\xFE", 2)) { *bom_len = 2; *stride = 2; *ascii_off = 0; return rb_enc_find("UTF-16LE"); }
-    if (mkr_span_starts(&s, "\xEF\xBB\xBF", 3)) { *bom_len = 3; return rb_utf8_encoding(); }
-    return NULL;
-}
-
-static int
-mkr_decl_ws(int c)
-{
-    return c == ' ' || c == '\t' || c == '\r' || c == '\n';
-}
-
-/* The encoding named in the '<?xml ... encoding="NAME" ?>' declaration, or NULL.
- * The declaration is ASCII; for a UTF-16/32-detected document its bytes are
- * stride-interleaved, so the ASCII column is extracted (stride/off resolved by
- * the BOM matcher) before the scan, letting a BOM-vs-declaration conflict be
- * caught even in UTF-16.
- *
- * p is a borrowed RSTRING view, so this stays allocation-free until every read
- * of p is done: the stride/off geometry is passed in (rather than derived here
- * via rb_enc_find, which can autoload = a GC point), and the only rb_enc_find -
- * the final name lookup - runs after the bytes have been copied into head[]. */
-static rb_encoding *
-mkr_xml_decl_encoding(const unsigned char *p, long len, long stride, long off)
-{
-    /* Extract the ASCII column (per the BOM stride) through bounded reads into
-     * a bounded writer - neither side trusts the loop arithmetic. */
-    mkr_span_t in = mkr_span((const char *)p, len < 0 ? 0 : (size_t)len);
-    char head[256];
-    mkr_spanbuf_t hw = mkr_spanbuf(head, sizeof(head));
-    for (size_t i = (size_t)off; hw.pos < sizeof(head); i += (size_t)stride) {
-        int c = mkr_span_at(&in, i);
-        if (c < 0) break;
-        mkr_spanbuf_putc(&hw, (char)c);
-    }
-    mkr_span_t h = mkr_span(head, hw.pos);
-    size_t hn = hw.pos;
-
-    size_t i = 0;
-    while (mkr_decl_ws(mkr_span_at(&h, i))) i++;
-    {
-        mkr_span_t t = mkr_span_tail(&h, i);
-        if (!mkr_span_starts(&t, "<?xml", 5)) return NULL;
-    }
-    i += 5;
-    /* find a whitespace-introduced "encoding" before the '?>' */
-    for (; i + 8 <= hn; i++) {
-        if (mkr_span_at(&h, i) == '?' && mkr_span_at(&h, i + 1) == '>') return NULL; /* end of decl */
-        mkr_span_t t = mkr_span_tail(&h, i);
-        if (!mkr_decl_ws(mkr_span_at(&h, i - 1)) || !mkr_span_starts(&t, "encoding", 8)) continue;
-        size_t j = i + 8;
-        while (mkr_decl_ws(mkr_span_at(&h, j))) j++;
-        if (mkr_span_at(&h, j) != '=') return NULL;
-        j++;
-        while (mkr_decl_ws(mkr_span_at(&h, j))) j++;
-        int q = mkr_span_at(&h, j);
-        if (q != '"' && q != '\'') return NULL;
-        j++;
-        size_t ns = j;
-        while (mkr_span_at(&h, j) >= 0 && mkr_span_at(&h, j) != q) j++;
-        if (j >= hn) return NULL;
-        char name[64];
-        size_t nl = j - ns;
-        if (nl == 0 || nl >= sizeof(name)) return NULL;
-        memcpy(name, head + ns, nl);
-        name[nl] = '\0';
-        return rb_enc_find(name);   /* NULL for an unknown encoding name */
-    }
-    return NULL;
-}
-
-/* Two encodings agree for conflict purposes when identical, or when either is
- * US-ASCII (a subset of UTF-8 and the single-byte encodings). */
-static int
-mkr_xml_enc_compatible(rb_encoding *a, rb_encoding *b)
-{
-    return a == b || a == rb_usascii_encoding() || b == rb_usascii_encoding();
-}
-
-VALUE
-mkr_xml_decode_input(VALUE str, size_t max_bytes)
-{
-    rb_encoding   *tag    = rb_enc_get(str);
-    const unsigned char *raw = (const unsigned char *)RSTRING_PTR(str);
-    long           rawlen = RSTRING_LEN(str);
-
-    /* Detect the byte encoding (XML 1.0 Appendix F): a BOM wins, else the
-     * declaration. The Ruby String's encoding is authoritative when it is a
-     * concrete text encoding; a BOM/declaration that disagrees is a fatal
-     * conflict. ASCII-8BIT means "raw bytes, no claimed encoding", so there the
-     * detected encoding decodes the input (a UTF-16/Shift_JIS/BOM'd file read
-     * with File.binread now parses). */
-    long bom_len = 0, bom_stride = 1, bom_off = 0;
-    rb_encoding *bom  = mkr_xml_bom_encoding(raw, rawlen, &bom_len, &bom_stride, &bom_off);
-    /* rb_enc_find inside the BOM lookup can autoload an encoding (a Ruby
-     * allocation = a GC point), so re-borrow the bytes before reading them
-     * again - a borrowed RSTRING pointer must not be held across one. The
-     * interleave geometry (stride/off) is resolved by the BOM matcher and
-     * passed through, keeping the decl scanner itself allocation-free. */
-    raw = (const unsigned char *)RSTRING_PTR(str);
-    rb_encoding *decl = mkr_xml_decl_encoding(raw + bom_len, rawlen - bom_len, bom_stride, bom_off);
-    int is_binary = (tag == rb_ascii8bit_encoding());
-
-    if (bom && decl && !mkr_xml_enc_compatible(bom, decl)) {
-        rb_raise(mkr_eXmlSyntaxError,
-                 "XML encoding conflict: the byte-order mark and the encoding declaration disagree");
-    }
-    if (!is_binary && bom && !mkr_xml_enc_compatible(bom, tag)) {
-        rb_raise(mkr_eXmlSyntaxError,
-                 "XML encoding conflict: the byte-order mark disagrees with the string's encoding");
-    }
-    if (!is_binary && decl && !mkr_xml_enc_compatible(decl, tag)) {
-        /* A concrete String encoding is authoritative for decoding, so the
-         * declaration is not used to transcode - but a declaration that names a
-         * different encoding than the String is tagged with (e.g. a Shift_JIS
-         * String declaring encoding="UTF-8") is a self-inconsistent document and
-         * a fatal error, not a silently-ignored mismatch. */
-        rb_raise(mkr_eXmlSyntaxError,
-                 "XML encoding conflict: the encoding declaration disagrees with the string's encoding");
-    }
-
-    rb_encoding *eff = is_binary ? (bom ? bom : (decl ? decl : rb_utf8_encoding())) : tag;
-
-    /* Decode to UTF-8 (strict). UTF-8 / US-ASCII / ASCII-8BIT are already UTF-8
-     * bytes (validated below); anything else is strict-transcoded, raising rather
-     * than substituting U+FFFD. */
-    VALUE s;
-    if (eff == rb_utf8_encoding() || eff == rb_usascii_encoding() || eff == rb_ascii8bit_encoding()) {
-        s = str;
-    } else {
-        VALUE in = str;
-        if (rb_enc_get(str) != eff) { in = rb_str_dup(str); rb_enc_associate(in, eff); }
-        int state = 0;
-        s = rb_protect(mkr_xml_strict_transcode_thunk, in, &state);
-        if (state != 0) {
-            VALUE exc = rb_errinfo();
-            rb_set_errinfo(Qnil);
-            char msg[256];
-            mkr_ruby_exception_message(exc, msg, sizeof msg);
-            rb_raise(mkr_eXmlSyntaxError,
-                     "XML input could not be decoded to UTF-8: %s", msg);
-        }
-    }
-
-    const char *ptr = RSTRING_PTR(s);
-    long        len = RSTRING_LEN(s);
-    long        off = 0;
-    /* §4.3.3: a leading BOM is the encoding signature, not document content -
-     * strip a U+FEFF (the transcode above turns any UTF-16/32 BOM into one). */
-    mkr_span_t sv = mkr_span(ptr, (size_t)len);
-    if (mkr_span_starts(&sv, "\xEF\xBB\xBF", 3)) {
-        off = 3; len -= 3;
-        mkr_span_skip(&sv, 3);
-    }
-
-    /* Fail closed on an over-budget input BEFORE the validation scan and the
-     * caller's GVL-release copy (an input whose UTF-8 length exceeds the arena
-     * budget can never parse). max_bytes == 0 disables the check (__decode). */
-    if (max_bytes != 0 && (size_t)len > max_bytes) {
-        rb_raise(mkr_eXmlLimitExceeded, "XML input exceeds the byte budget");
-    }
-
-    /* Strict UTF-8 validation via the shared, allocation-free core - no GC point
-     * while `ptr` is borrowed: an embedded NUL or any invalid UTF-8 is fatal (no
-     * U+FFFD repair - unlike the HTML mkr_utf8_sanitize path). The whole-string
-     * `s` is consulted for the cached coderange (it covers the BOM-stripped
-     * suffix too - the BOM is one complete UTF-8 character), while the validated
-     * bytes are the stripped suffix `ptr + off`. */
-    switch (mkr_text_check(s, ptr + off, (size_t)len)) {
-        case MKR_TEXT_HAS_NUL:
-            rb_raise(mkr_eXmlSyntaxError, "XML input must not contain a NUL byte");
-        case MKR_TEXT_INVALID_UTF8:
-            rb_raise(mkr_eXmlSyntaxError, "XML input must be valid UTF-8");
-        case MKR_TEXT_OK:
-            break;
-    }
-    /* Build the result through the VALUE, not the borrowed ptr (rb_str_subseq
-     * allocates, so the ptr must not be what it copies from). */
-    VALUE u = rb_str_subseq(s, off, len);
-    rb_enc_associate(u, rb_utf8_encoding());
-    return u; /* validated, UTF-8-tagged, BOM-stripped */
-}
-
 bool
 mkr_ruby_str_known_valid_utf8(VALUE str)
 {