makiri 0.3.0 → 0.4.0

data/ext/makiri/lexbor_compat/utf8_input.c

@@ -16,85 +16,12 @@
  * via mkr_utf8_sanitize (declared in compat.h).
  */
 
-/* Is `src` (len bytes) well-formed UTF-8? A dedicated validator (the Unicode
- * "well-formed UTF-8 byte sequences" table, RFC 3629 / WHATWG): it rejects bad
- * continuation bytes, overlong forms, surrogates (U+D800..U+DFFF) and code
- * points above U+10FFFF, and an incomplete trailing sequence. This is the same
- * accept set as Lexbor's decoder but validate-only - it never materialises code
- * points, and rips through ASCII (the common case) a machine word at a time, so
- * it is much cheaper than decode-and-discard. NUL bytes are valid here and are
- * left for the HTML tokenizer to handle per the spec.
- *
- * The contract that matters: this returns true *only* for input that
+/* UTF-8 validation: the shared, allocation-free validator lives in core
+ * (core/mkr_utf8.c, via mkr_core.h) so this fast path and the Ruby bridge's
+ * strict input gate (mkr_verify_text) run ONE implementation. Its contract
+ * here is unchanged: it returns true *only* for input that
  * mkr_utf8_replace_invalid would leave byte-identical, so "valid" can safely
- * skip the transcode. */
-static bool
-mkr_utf8_valid(const lxb_char_t *src, size_t len)
-{
-    const unsigned char *p   = (const unsigned char *)src;
-    const unsigned char *const end = p + len;
-
-    while (p < end) {
-        unsigned char b = *p;
-
-        if (b < 0x80) {
-            /* ASCII fast path: skip a run of ASCII bytes a word at a time
-             * (any high bit set ends the run), then byte-wise for the tail. */
-            while ((size_t)(end - p) >= sizeof(size_t)) {
-                size_t w;
-                memcpy(&w, p, sizeof(w));
-                if (w & (size_t)0x8080808080808080ULL) {
-                    break;
-                }
-                p += sizeof(size_t);
-            }
-            while (p < end && *p < 0x80) {
-                p++;
-            }
-            continue;
-        }
-
-        /* Multi-byte: decide length and validate the (length-dependent) ranges
-         * that exclude overlong forms, surrogates and > U+10FFFF. */
-        size_t n;
-        if (b >= 0xC2 && b <= 0xDF) {                 /* U+0080..U+07FF   */
-            n = 2;
-            if (end - p < 2 || (p[1] & 0xC0) != 0x80) return false;
-        } else if (b == 0xE0) {                       /* U+0800..U+0FFF   */
-            n = 3;
-            if (end - p < 3 || p[1] < 0xA0 || p[1] > 0xBF
-                || (p[2] & 0xC0) != 0x80) return false;
-        } else if (b >= 0xE1 && b <= 0xEC) {          /* U+1000..U+CFFF   */
-            n = 3;
-            if (end - p < 3 || (p[1] & 0xC0) != 0x80
-                || (p[2] & 0xC0) != 0x80) return false;
-        } else if (b == 0xED) {                       /* U+D000..U+D7FF   */
-            n = 3;                                    /* (excludes surrogates) */
-            if (end - p < 3 || p[1] < 0x80 || p[1] > 0x9F
-                || (p[2] & 0xC0) != 0x80) return false;
-        } else if (b == 0xEE || b == 0xEF) {          /* U+E000..U+FFFF   */
-            n = 3;
-            if (end - p < 3 || (p[1] & 0xC0) != 0x80
-                || (p[2] & 0xC0) != 0x80) return false;
-        } else if (b == 0xF0) {                       /* U+10000..U+3FFFF */
-            n = 4;
-            if (end - p < 4 || p[1] < 0x90 || p[1] > 0xBF
-                || (p[2] & 0xC0) != 0x80 || (p[3] & 0xC0) != 0x80) return false;
-        } else if (b >= 0xF1 && b <= 0xF3) {          /* U+40000..U+FFFFF */
-            n = 4;
-            if (end - p < 4 || (p[1] & 0xC0) != 0x80 || (p[2] & 0xC0) != 0x80
-                || (p[3] & 0xC0) != 0x80) return false;
-        } else if (b == 0xF4) {                       /* U+100000..U+10FFFF */
-            n = 4;
-            if (end - p < 4 || p[1] < 0x80 || p[1] > 0x8F
-                || (p[2] & 0xC0) != 0x80 || (p[3] & 0xC0) != 0x80) return false;
-        } else {                                      /* C0,C1,F5..FF,stray 80..BF */
-            return false;
-        }
-        p += n;
-    }
-    return true;
-}
+ * skip the transcode. (lxb_char_t is unsigned char, so the call is direct.) */
 
 /* Transcode UTF-8 -> UTF-8 replacing every invalid sequence with U+FFFD
  * (WHATWG byte-stream decoding), into a freshly malloc'd, NUL-terminated

data/ext/makiri/makiri.c

@@ -79,6 +79,48 @@ mkr_c_selftest(VALUE self)
     return Qtrue;
 }
 
+/* Makiri.__alloc_inject(n) / __alloc_inject_calls / __alloc_inject? - the OOM
+ * sweep harness's controls (script/check_alloc_failures.rb, `rake oom`): arm
+ * "the nth core allocation fails once", and read how many core allocations a
+ * workload attempted. Compiled to a real hook only under MKR_ALLOC_INJECT
+ * (extconf: MAKIRI_ALLOC_INJECT=1); in a normal build __alloc_inject? is
+ * false and the others raise, so the harness fails loudly on the wrong build
+ * instead of sweeping nothing. Test hooks only. */
+static VALUE
+mkr_s_alloc_inject_p(VALUE self)
+{
+    (void)self;
+#ifdef MKR_ALLOC_INJECT
+    return Qtrue;
+#else
+    return Qfalse;
+#endif
+}
+
+static VALUE
+mkr_s_alloc_inject(VALUE self, VALUE nth)
+{
+    (void)self;
+#ifdef MKR_ALLOC_INJECT
+    mkr_alloc_inject_arm((long long)NUM2LL(nth));
+    return Qnil;
+#else
+    (void)nth;
+    rb_raise(rb_eNotImpError, "rebuild with MAKIRI_ALLOC_INJECT=1 (rake oom does this)");
+#endif
+}
+
+static VALUE
+mkr_s_alloc_inject_calls(VALUE self)
+{
+    (void)self;
+#ifdef MKR_ALLOC_INJECT
+    return ULL2NUM(mkr_alloc_inject_calls());
+#else
+    rb_raise(rb_eNotImpError, "rebuild with MAKIRI_ALLOC_INJECT=1 (rake oom does this)");
+#endif
+}
+
 /* Makiri::XML.__decode(str) -> validated, UTF-8-tagged String, or raises
  * Makiri::XML::SyntaxError. Internal test hook exercising the strict input
  * decode (§2.1) on its own, until the full Makiri::XML(...) parse pipeline
@@ -223,5 +265,8 @@ Init_makiri(void)
     mkr_init_xml_node();
 
     rb_define_singleton_method(mkr_mMakiri, "__c_selftest", mkr_c_selftest, 0);
+    rb_define_singleton_method(mkr_mMakiri, "__alloc_inject?", mkr_s_alloc_inject_p, 0);
+    rb_define_singleton_method(mkr_mMakiri, "__alloc_inject", mkr_s_alloc_inject, 1);
+    rb_define_singleton_method(mkr_mMakiri, "__alloc_inject_calls", mkr_s_alloc_inject_calls, 0);
     rb_define_singleton_method(mkr_mXML, "__decode", mkr_xml_s_decode, 1);
 }

data/ext/makiri/xml/mkr_xml.h

@@ -99,9 +99,8 @@ int mkr_xml_is_char(uint32_t c);
  * recognition (comment/CDATA/PI content, where '&'/'<' are literal). 0 / -1. */
 int mkr_xml_validate_chars(const char *src, uint32_t len);
 
-/* Bounds-checked one-codepoint UTF-8 decode (byte length 1-4, or 0 at end /
- * on malformed input) + XML 1.0 §2.3 NameStartChar / NameChar (§9.2b). */
-int mkr_xml_utf8_decode(const char *p, const char *end, uint32_t *cp);
+/* XML 1.0 §2.3 NameStartChar / NameChar (§9.2b). One-codepoint decoding is the
+ * core mkr_utf8_decode1 / mkr_utf8_decode1_span (strict, bounds-checked). */
 int mkr_xml_is_name_start(uint32_t c);
 int mkr_xml_is_name_char(uint32_t c);
 

data/ext/makiri/xml/mkr_xml_chars.c

@@ -7,9 +7,16 @@
  * resulting codepoint (literal or from a numeric reference) must be an XML 1.0
  * Char; control characters / surrogates / out-of-range are rejected. The input
  * is already valid UTF-8 (§2.1).
+ *
+ * All input reads go through the bounded reader (core mkr_span_t) and the
+ * strict core decoder (mkr_utf8_decode1) - an out-of-bounds read is
+ * structurally impossible, not a per-site convention; all output goes through
+ * the bounded writer (mkr_spanbuf_t). The lint (raw_scan_call /
+ * raw_cursor_member) keeps it that way.
  */
 #include "mkr_xml.h"
 #include "mkr_xml_node.h"
+#include "../core/mkr_core.h"   /* mkr_span_t + mkr_utf8_decode1 */
 
 #include <string.h>
 
@@ -24,73 +31,25 @@ mkr_xml_is_char(uint32_t c)
         || (c >= 0x10000u && c <= 0x10FFFFu);
 }
 
-/* Decode one codepoint from UTF-8. STRICT (self-contained, not trusting the
- * caller): rejects truncation, bad continuation bytes, overlong encodings,
- * surrogates and out-of-range values. Returns the byte length (1-4) or 0 on any
- * violation - fail closed, even if some future caller feeds unvalidated bytes. */
-static int
-is_cont(const char *p, const char *end)
-{
-    return p < end && ((unsigned char)*p & 0xC0u) == 0x80u;
-}
-
-/* forward decl: utf8_decode is defined below but mkr_xml_validate_chars uses it. */
-static int utf8_decode(const char *p, const char *end, uint32_t *cp);
-
 /* Validate that [src, src+len) is entirely XML 1.0 Char, with NO entity/reference
  * recognition (for comment/CDATA/PI content, where '&' and '<' are literal). 0 if
- * all valid, -1 on the first malformed UTF-8 or non-Char (caller raises SYNTAX). */
+ * all valid, -1 on the first malformed UTF-8 or non-Char (caller raises SYNTAX).
+ * The strict decode (truncation / bad continuation / overlong / surrogate /
+ * out-of-range -> 0) is the core mkr_utf8_decode1 - self-contained, not trusting
+ * the caller, even if some future caller feeds unvalidated bytes. */
 int
 mkr_xml_validate_chars(const char *src, uint32_t len)
 {
-    const char *p = src, *end = src + len;
-    while (p < end) {
+    mkr_span_t s = mkr_span(src, len);
+    while (mkr_span_left(&s) > 0) {
         uint32_t cp;
-        int bl = utf8_decode(p, end, &cp);
+        int bl = mkr_utf8_decode1_span(&s, &cp);
         if (bl == 0 || !mkr_xml_is_char(cp)) return -1;
-        p += bl;
+        mkr_span_skip(&s, (size_t)bl);
     }
     return 0;
 }
 
-static int
-utf8_decode(const char *p, const char *end, uint32_t *cp)
-{
-    unsigned char c = (unsigned char)p[0];
-    if (c < 0x80u) { *cp = c; return 1; }
-    if ((c & 0xE0u) == 0xC0u) {
-        if (!is_cont(p + 1, end)) return 0;
-        uint32_t v = ((uint32_t)(c & 0x1Fu) << 6) | ((unsigned char)p[1] & 0x3Fu);
-        if (v < 0x80u) return 0;                                /* overlong */
-        *cp = v; return 2;
-    }
-    if ((c & 0xF0u) == 0xE0u) {
-        if (!is_cont(p + 1, end) || !is_cont(p + 2, end)) return 0;
-        uint32_t v = ((uint32_t)(c & 0x0Fu) << 12) | (((unsigned char)p[1] & 0x3Fu) << 6)
-            | ((unsigned char)p[2] & 0x3Fu);
-        if (v < 0x800u) return 0;                               /* overlong */
-        if (v >= 0xD800u && v <= 0xDFFFu) return 0;             /* surrogate */
-        *cp = v; return 3;
-    }
-    if ((c & 0xF8u) == 0xF0u) {
-        if (!is_cont(p + 1, end) || !is_cont(p + 2, end) || !is_cont(p + 3, end)) return 0;
-        uint32_t v = ((uint32_t)(c & 0x07u) << 18) | (((unsigned char)p[1] & 0x3Fu) << 12)
-            | (((unsigned char)p[2] & 0x3Fu) << 6) | ((unsigned char)p[3] & 0x3Fu);
-        if (v < 0x10000u || v > 0x10FFFFu) return 0;            /* overlong / out of range */
-        *cp = v; return 4;
-    }
-    return 0;
-}
-
-/* Public, bounds-checked one-codepoint decode for the tokenizer's name scanning
- * (returns 0 at end-of-input as well as on any malformed byte). */
-int
-mkr_xml_utf8_decode(const char *p, const char *end, uint32_t *cp)
-{
-    if (p >= end) return 0;
-    return utf8_decode(p, end, cp);
-}
-
 /* XML 1.0 §2.3 NameStartChar / NameChar (the full Unicode sets, not just ASCII).
  * Element/attribute QNames and PI targets are validated against these so an
  * ill-formed name never reaches the DOM (§9.2b). */
@@ -131,9 +90,12 @@ utf8_encode(uint32_t cp, char *out)
 
 /* Expand references in [src, src+len) and validate XML Char. Output is never
  * longer than the input (every &...; reference is >= 4 chars and yields <= 4
- * bytes), so a single arena buffer of `len` bytes suffices. Returns the arena
- * slice and sets *out_len; returns NULL on an undefined entity / bad reference /
- * non-XML-Char (sets *status = MKR_XML_ERR_SYNTAX) or arena OOM/LIMIT. */
+ * bytes), so a buffer of `len` bytes suffices - and the bounded arena writer
+ * (mkr_xml_arena_spanbuf + core mkr_spanbuf) enforces that bound rather than
+ * trusting it (a write past it fails closed instead of overrunning the arena).
+ * Returns the arena slice and sets *out_len;
+ * returns NULL on an undefined entity / bad reference / non-XML-Char (sets
+ * *status = MKR_XML_ERR_SYNTAX) or arena OOM/LIMIT. */
 const char *
 mkr_xml_expand(mkr_xml_doc_t *doc, const char *src, uint32_t len,
                mkr_xml_expand_mode_t mode, uint32_t *out_len, mkr_xml_status_t *status)
@@ -148,46 +110,45 @@ mkr_xml_expand(mkr_xml_doc_t *doc, const char *src, uint32_t len,
     if (len == 0) { *out_len = 0; return ""; }
     if (doc == NULL || src == NULL) { *status = MKR_XML_ERR_INTERNAL; return NULL; }
 
-    char *buf = mkr_xml_arena_scratch_bytes(doc, len);
-    if (buf == NULL) { *status = doc->oom; return NULL; } /* doc non-NULL here (guarded above) */
-
-    size_t      o   = 0;
-    const char *p   = src;
-    const char *end = src + len;
+    /* All output goes through the bounded writer, so no code below can overrun
+     * the buffer - a write that would exceed `len` is refused and latches ok=0. */
+    mkr_spanbuf_t b = mkr_xml_arena_spanbuf(doc, len);
+    if (!b.ok) { *status = doc->oom; return NULL; } /* backing alloc failed */
+    mkr_span_t s = mkr_span(src, len);
 
-    while (p < end) {
-        if (*p != '&') {
+    while (mkr_span_left(&s) > 0) {
+        if (mkr_span_peek(&s) != '&') {
             uint32_t cp;
-            int bl = utf8_decode(p, end, &cp);
+            int bl = mkr_utf8_decode1_span(&s, &cp);
             if (bl == 0 || !mkr_xml_is_char(cp)) { *status = MKR_XML_ERR_SYNTAX; return NULL; }
             /* §3.3.3: in an attribute value a *literal* TAB/LF/CR normalizes to a
              * space (reference-derived whitespace is preserved - see below). */
             if (mode == MKR_XML_EXPAND_ATTR
                 && (cp == 0x9u || cp == 0xAu || cp == 0xDu)) {
-                buf[o++] = ' ';
-                p += bl;
+                mkr_spanbuf_putc(&b, ' ');
+                mkr_span_skip(&s, (size_t)bl);
                 continue;
             }
-            memcpy(buf + o, p, (size_t)bl);
-            o += (size_t)bl;
-            p += bl;
+            mkr_spanbuf_write(&b, mkr_span_mark(&s), (size_t)bl);
+            mkr_span_skip(&s, (size_t)bl);
             continue;
         }
 
         /* a reference: '&' ... ';' */
-        p++; /* past '&' */
-        if (p < end && *p == '#') {                 /* numeric character reference */
-            p++;
+        mkr_span_skip(&s, 1); /* past '&' */
+        if (mkr_span_peek(&s) == '#') {             /* numeric character reference */
+            mkr_span_skip(&s, 1);
             int hex = 0;
             /* §4.1: the hex marker is a lowercase 'x' only - "&#X58;" is not-wf
              * (an uppercase 'X' is not a decimal digit either, so it is rejected
              * as "no digits" below). */
-            if (p < end && *p == 'x') { hex = 1; p++; }
-            const char *digits = p;
+            if (mkr_span_peek(&s) == 'x') { hex = 1; mkr_span_skip(&s, 1); }
             uint32_t base = hex ? 16u : 10u;
             uint32_t cp = 0;
-            while (p < end && *p != ';') {
-                unsigned char d = (unsigned char)*p;
+            int ndigits = 0;
+            for (;;) {
+                int d = mkr_span_peek(&s);
+                if (d < 0 || d == ';') break;
                 uint32_t dig;
                 if (d >= '0' && d <= '9')              dig = (uint32_t)(d - '0');
                 else if (hex && d >= 'a' && d <= 'f')  dig = (uint32_t)(d - 'a' + 10);
@@ -197,29 +158,38 @@ mkr_xml_expand(mkr_xml_doc_t *doc, const char *src, uint32_t len,
                  * uint32_t into the valid range and be falsely accepted. */
                 if (cp > (0x10FFFFu - dig) / base) { *status = MKR_XML_ERR_SYNTAX; return NULL; }
                 cp = cp * base + dig;
-                p++;
+                ndigits++;
+                mkr_span_skip(&s, 1);
             }
-            if (p >= end || p == digits) { *status = MKR_XML_ERR_SYNTAX; return NULL; } /* no ';' / no digits */
-            p++; /* past ';' */
+            if (mkr_span_peek(&s) != ';' || ndigits == 0) { *status = MKR_XML_ERR_SYNTAX; return NULL; } /* no ';' / no digits */
+            mkr_span_skip(&s, 1); /* past ';' */
             if (!mkr_xml_is_char(cp)) { *status = MKR_XML_ERR_SYNTAX; return NULL; }
-            o += (size_t)utf8_encode(cp, buf + o);
+            /* encode into a safe 4-byte local, then hand the exact length to the
+             * bounded writer (the encode itself can never overrun `enc`). */
+            char enc[4];
+            mkr_spanbuf_write(&b, enc, (size_t)utf8_encode(cp, enc));
         } else {                                    /* named entity */
-            const char *ns = p;
-            while (p < end && *p != ';') p++;
-            if (p >= end) { *status = MKR_XML_ERR_SYNTAX; return NULL; } /* unterminated */
-            size_t nlen = (size_t)(p - ns);
-            p++; /* past ';' */
+            size_t nlen;
+            if (!mkr_span_find(&s, ';', &nlen)) { *status = MKR_XML_ERR_SYNTAX; return NULL; } /* unterminated */
+            const char *ns = mkr_span_mark(&s);
+            mkr_span_skip(&s, nlen + 1); /* name + ';' */
             char ch;
-            if      (nlen == 2 && memcmp(ns, "lt",   2) == 0) ch = '<';
-            else if (nlen == 2 && memcmp(ns, "gt",   2) == 0) ch = '>';
-            else if (nlen == 3 && memcmp(ns, "amp",  3) == 0) ch = '&';
-            else if (nlen == 4 && memcmp(ns, "apos", 4) == 0) ch = '\'';
-            else if (nlen == 4 && memcmp(ns, "quot", 4) == 0) ch = '"';
+            if      (mkr_bytes_eq(ns, nlen, "lt",   2)) ch = '<';
+            else if (mkr_bytes_eq(ns, nlen, "gt",   2)) ch = '>';
+            else if (mkr_bytes_eq(ns, nlen, "amp",  3)) ch = '&';
+            else if (mkr_bytes_eq(ns, nlen, "apos", 4)) ch = '\'';
+            else if (mkr_bytes_eq(ns, nlen, "quot", 4)) ch = '"';
             else { *status = MKR_XML_ERR_SYNTAX; return NULL; } /* undefined entity */
-            buf[o++] = ch;
+            mkr_spanbuf_putc(&b, ch);
         }
     }
 
-    *out_len = (uint32_t)o;
-    return buf;
+    /* By construction the buffer was never overrun; finish returns NULL if a
+     * write was refused (the "output <= input" invariant broke - our bug). The
+     * backing alloc was already checked at init, so a NULL here means a refused
+     * write: fail closed rather than return a truncated expansion. */
+    const char *out = mkr_spanbuf_finish(&b);
+    if (out == NULL) { *status = MKR_XML_ERR_INTERNAL; return NULL; }
+    *out_len = (uint32_t)b.pos;
+    return out;
 }

data/ext/makiri/xml/mkr_xml_index.c

@@ -0,0 +1,169 @@
+/* Element-name index for the XML arena (see mkr_xml_index.h). Open-addressing
+ * hash keyed by (local name + namespace URI); each entry holds the
+ * document-ordered elements with that name. Two tree passes: count elements to
+ * size the table, then fill in document order. Heap-allocated (not the arena),
+ * freed on invalidate. OOM fails closed (NULL -> caller walks the tree). */
+
+#include "mkr_xml_index.h"
+#include "../core/mkr_core.h"
+
+#include <stdlib.h>
+#include <string.h>
+
+typedef struct {
+  const char     *local;      /* borrowed from the first element (arena-stable) */
+  const char     *ns_uri;     /* may be NULL (no namespace) */
+  uint32_t        local_len;
+  uint32_t        ns_uri_len;
+  mkr_xml_node_t **nodes;      /* document order */
+  size_t          count, cap;
+} mkr_xml_index_entry_t;
+
+struct mkr_xml_name_index {
+  mkr_xml_index_entry_t *buckets;
+  size_t                 cap;   /* power of two; 0 only for an empty document */
+};
+
+/* FNV-1a over the local name then the namespace URI. */
+static uint64_t
+key_hash(const char *local, size_t local_len, const char *ns_uri, size_t ns_uri_len)
+{
+  uint64_t h = 1469598103934665603ULL;
+  for (size_t i = 0; i < local_len; i++)  { h ^= (unsigned char)local[i];  h *= 1099511628211ULL; }
+  h ^= 0xff; h *= 1099511628211ULL;  /* separator so "ab"+"" != "a"+"b" */
+  for (size_t i = 0; i < ns_uri_len; i++) { h ^= (unsigned char)ns_uri[i]; h *= 1099511628211ULL; }
+  return h;
+}
+
+static int
+key_eq(const mkr_xml_index_entry_t *e, const char *local, size_t local_len,
+       const char *ns_uri, size_t ns_uri_len)
+{
+  if (e->local_len != local_len || e->ns_uri_len != ns_uri_len) return 0;
+  if (local_len && memcmp(e->local, local, local_len) != 0) return 0;
+  if (ns_uri_len && memcmp(e->ns_uri, ns_uri, ns_uri_len) != 0) return 0;
+  return 1;
+}
+
+
+/* Find the entry for the key, or the empty slot to create it (open addressing,
+ * power-of-two mask). The table is sized so it never fills (load < 0.5). */
+static mkr_xml_index_entry_t *
+slot_for(mkr_xml_name_index_t *idx, const char *local, size_t local_len,
+         const char *ns_uri, size_t ns_uri_len)
+{
+  size_t mask = idx->cap - 1;
+  size_t i = (size_t)key_hash(local, local_len, ns_uri, ns_uri_len) & mask;
+  for (;;) {
+    mkr_xml_index_entry_t *e = &idx->buckets[i];
+    if (e->local == NULL && e->count == 0) return e;            /* empty */
+    if (key_eq(e, local, local_len, ns_uri, ns_uri_len)) return e;
+    i = (i + 1) & mask;
+  }
+}
+
+/* Append +node+ to its key's bucket, creating the entry if new. 0 / -1 (OOM). */
+static int
+index_push(mkr_xml_name_index_t *idx, mkr_xml_node_t *node)
+{
+  mkr_xml_index_entry_t *e =
+      slot_for(idx, node->local, node->local_len, node->ns_uri, node->ns_uri_len);
+  if (e->local == NULL && e->count == 0) {       /* fresh entry: borrow the key */
+    e->local = node->local;          e->local_len = node->local_len;
+    e->ns_uri = node->ns_uri;        e->ns_uri_len = node->ns_uri_len;
+  }
+  if (mkr_grow_reserve((void **)&e->nodes, &e->cap, e->count + 1, sizeof(*e->nodes)) != MKR_OK) {
+    return -1;  /* grows geometrically + overflow-safely internally */
+  }
+  e->nodes[e->count++] = node;
+  return 0;
+}
+
+/* Count elements (document order is irrelevant here) to size the table. */
+static size_t
+count_elements(mkr_xml_node_t *root)
+{
+  size_t n = 0;
+  for (mkr_xml_node_t *cur = root; cur != NULL; cur = mkr_xml_preorder_next(root, cur)) {
+    if (cur->type == MKR_XML_NODE_TYPE_ELEMENT) n++;
+  }
+  return n;
+}
+
+static mkr_xml_name_index_t *
+build(mkr_xml_doc_t *doc)
+{
+  mkr_xml_node_t *root = doc->doc_node;
+  if (root == NULL) return NULL;
+
+  mkr_xml_name_index_t *idx = (mkr_xml_name_index_t *)mkr_callocarray(1, sizeof(*idx));
+  if (idx == NULL) return NULL;
+
+  size_t n = count_elements(root);
+  /* Size for load factor < 0.5 (2n+1 slots). The overflow-checked sizer fails
+   * closed - unlike the old next_pow2, which saturated to a too-small table on
+   * overflow, where open addressing could never find a free slot. */
+  size_t want;
+  if (!mkr_size_mul(n, 2, &want) || !mkr_size_add(want, 1, &want)
+      || !mkr_pow2_ceil(want, &idx->cap)) { free(idx); return NULL; }
+  if (idx->cap < 8) idx->cap = 8;              /* small floor */
+  idx->buckets = (mkr_xml_index_entry_t *)mkr_callocarray(idx->cap, sizeof(*idx->buckets));
+  if (idx->buckets == NULL) { free(idx); return NULL; }
+
+  /* Fill pass: pre-order (document order), elements only. */
+  for (mkr_xml_node_t *cur = root; cur != NULL; cur = mkr_xml_preorder_next(root, cur)) {
+    if (cur->type == MKR_XML_NODE_TYPE_ELEMENT) {
+      if (index_push(idx, cur) != 0) { mkr_xml_name_index_free(idx); return NULL; }
+    }
+  }
+  return idx;
+}
+
+mkr_xml_name_index_t *
+mkr_xml_name_index_get(mkr_xml_doc_t *doc)
+{
+  if (doc == NULL) return NULL;
+  if (doc->name_index != NULL) return (mkr_xml_name_index_t *)doc->name_index;
+  mkr_xml_name_index_t *idx = build(doc);
+  doc->name_index = idx;          /* NULL on OOM: caller walks, retries next time */
+  return idx;
+}
+
+void
+mkr_xml_name_index_free(mkr_xml_name_index_t *idx)
+{
+  if (idx == NULL) return;
+  if (idx->buckets != NULL) {
+    for (size_t i = 0; i < idx->cap; i++) free(idx->buckets[i].nodes);
+    free(idx->buckets);
+  }
+  free(idx);
+}
+
+void
+mkr_xml_name_index_invalidate(mkr_xml_doc_t *doc)
+{
+  if (doc == NULL || doc->name_index == NULL) return;
+  mkr_xml_name_index_free((mkr_xml_name_index_t *)doc->name_index);
+  doc->name_index = NULL;
+}
+
+mkr_xml_node_t *const *
+mkr_xml_name_index_lookup(const mkr_xml_name_index_t *idx,
+                          const char *local, size_t local_len,
+                          const char *ns_uri, size_t ns_uri_len, size_t *out_count)
+{
+  if (out_count != NULL) *out_count = 0;
+  if (idx == NULL || idx->cap == 0 || local == NULL) return NULL;
+  size_t mask = idx->cap - 1;
+  size_t i = (size_t)key_hash(local, local_len, ns_uri, ns_uri_len) & mask;
+  for (;;) {
+    const mkr_xml_index_entry_t *e = &idx->buckets[i];
+    if (e->local == NULL && e->count == 0) return NULL;          /* miss */
+    if (key_eq(e, local, local_len, ns_uri, ns_uri_len)) {
+      if (out_count != NULL) *out_count = e->count;
+      return e->nodes;
+    }
+    i = (i + 1) & mask;
+  }
+}

data/ext/makiri/xml/mkr_xml_index.h

@@ -0,0 +1,48 @@
+#ifndef MKR_XML_INDEX_H
+#define MKR_XML_INDEX_H
+
+#include "mkr_xml_node.h"
+#include <stddef.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/*
+ * Element-name index for the XML arena: maps each (local name + namespace URI)
+ * to the document-ordered list of elements bearing it, so a document-rooted
+ * descendant name test (//entry, css("entry")) is answered from the bucket
+ * instead of walking the whole tree. The HTML side has the analogous tag-id
+ * index; XML element names are arbitrary strings, so this is keyed by the name
+ * bytes (borrowed from the arena, stable until the next mutation).
+ *
+ * Lazily built and cached on the document; dropped by
+ * mkr_xml_name_index_invalidate from the single XML mutation hook (the same
+ * discipline as the HTML attr/text indices). Build OOM fails closed: the getter
+ * returns NULL and the caller walks the tree.
+ */
+typedef struct mkr_xml_name_index mkr_xml_name_index_t;
+
+/* The document's element-name index, built and cached on first call. Returns
+ * NULL on OOM (caller falls back to a tree walk). */
+mkr_xml_name_index_t *mkr_xml_name_index_get(mkr_xml_doc_t *doc);
+
+/* Drop the cached index after a structural mutation (no-op when unbuilt). */
+void mkr_xml_name_index_invalidate(mkr_xml_doc_t *doc);
+
+/* Free an index directly (used by mkr_xml_doc_destroy via the invalidate hook). */
+void mkr_xml_name_index_free(mkr_xml_name_index_t *idx);
+
+/* The document-ordered elements with local name +local+ and namespace URI
+ * +ns_uri+ (ns_uri == NULL / ns_uri_len == 0 means the no-namespace bucket).
+ * Returns the borrowed bucket and sets *out_count, or NULL with *out_count 0. */
+mkr_xml_node_t *const *mkr_xml_name_index_lookup(const mkr_xml_name_index_t *idx,
+                                                 const char *local, size_t local_len,
+                                                 const char *ns_uri, size_t ns_uri_len,
+                                                 size_t *out_count);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* MKR_XML_INDEX_H */