makiri 0.2.0 → 0.4.0

data/ext/makiri/lexbor_compat/utf8_input.c

@@ -3,6 +3,8 @@
 
 #include <lexbor/encoding/encoding.h>
 
+#include <string.h>   /* memcpy for the word-at-a-time ASCII scan */
+
 /* ------------------------------------------------------------------ */
 /* UTF-8 input sanitisation (browser-compatible HTML decoding)        */
 /* ------------------------------------------------------------------ */
@@ -14,36 +16,12 @@
  * via mkr_utf8_sanitize (declared in compat.h).
  */
 
-/* Is `src` (len bytes) well-formed UTF-8? Uses Lexbor's spec UTF-8 decoder
- * (which rejects bad continuation bytes, overlong forms, surrogates and
- * out-of-range code points) with NO replacement, so the first error makes it
- * return false. An incomplete trailing sequence (caught by decode_finish) is
- * also invalid. NUL bytes are valid UTF-8 here and are left for the HTML
- * tokenizer to handle per the spec (drop in text, U+FFFD in foreign content). */
-static bool
-mkr_utf8_valid(const lxb_char_t *src, size_t len)
-{
-    const lxb_encoding_data_t *u8 = lxb_encoding_data(LXB_ENCODING_UTF_8);
-    lxb_encoding_decode_t dec;
-    lxb_codepoint_t cp[1024];
-    const lxb_char_t *data = src, *end = src + len;
-    lxb_status_t st;
-
-    if (lxb_encoding_decode_init(&dec, u8, cp,
-                                 sizeof(cp) / sizeof(cp[0])) != LXB_STATUS_OK) {
-        return false; /* treat as invalid -> caller transcodes (fail safe) */
-    }
-    /* No replace_set: an invalid sequence aborts with LXB_STATUS_ERROR. */
-    do {
-        st = u8->decode(&dec, &data, end);
-        lxb_encoding_decode_buf_used_set(&dec, 0); /* discard code points */
-    } while (st == LXB_STATUS_SMALL_BUFFER);
-
-    if (st != LXB_STATUS_OK) {
-        return false;
-    }
-    return lxb_encoding_decode_finish(&dec) == LXB_STATUS_OK;
-}
+/* 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. (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
@@ -73,9 +51,17 @@ mkr_utf8_replace_invalid(const lxb_char_t *src, size_t len, size_t *out_len)
     (void) lxb_encoding_encode_replace_set(&enc, LXB_ENCODING_REPLACEMENT_BYTES,
                                            LXB_ENCODING_REPLACEMENT_SIZE);
 
-    /* HTML parse input is not byte-capped; mkr_buf grows overflow-safe and fails
-     * closed (NULL) on OOM. */
-    mkr_buf_init(&buf, 0);
+    /* The output is at most 3x the input: WHATWG byte-stream decoding replaces
+     * each invalid byte with U+FFFD (3 bytes) and passes valid bytes through 1:1.
+     * Cap the buffer at exactly that bound - tight and tied to the actual input,
+     * so a large document still parses but nothing runs away - rather than a
+     * blanket ceiling. (len > 0 here: mkr_utf8_sanitize returns early on len == 0.)
+     * It grows overflow-safe and fails closed (NULL) on OOM or the cap. */
+    size_t cap;
+    if (!mkr_size_mul(len, 3, &cap)) {
+        cap = MKR_BUF_HARD_MAX;   /* unreachable for any real in-memory string */
+    }
+    mkr_buf_init(&buf, cap);
 
 #define MKR_FLUSH()                                                            \
     do {                                                                       \

data/ext/makiri/makiri.c

@@ -1,25 +1,54 @@
 #include "makiri.h"
 #include "core/mkr_core.h"
+#include "bridge/bridge.h"
+#include "xml/mkr_xml.h"
+#include "xml/mkr_xml_mutate.h"
 
 VALUE mkr_mMakiri;
 VALUE mkr_cNode;
 VALUE mkr_cDocument;
 VALUE mkr_cElement;
-VALUE mkr_cAttribute;
+VALUE mkr_cAttr;
 VALUE mkr_cText;
 VALUE mkr_cComment;
-VALUE mkr_cCData;
+VALUE mkr_cCDATASection;
 VALUE mkr_cProcessingInstruction;
 VALUE mkr_cDocumentType;
 VALUE mkr_cDocumentFragment;
+VALUE mkr_mHTML;
+VALUE mkr_mHtmlNodeMethods;
+VALUE mkr_cHtmlNode;
+VALUE mkr_cHtmlDocument;
+VALUE mkr_cHtmlElement;
+VALUE mkr_cHtmlAttr;
+VALUE mkr_cHtmlText;
+VALUE mkr_cHtmlComment;
+VALUE mkr_cHtmlCDATASection;
+VALUE mkr_cHtmlProcessingInstruction;
+VALUE mkr_cHtmlDocumentType;
+VALUE mkr_cHtmlDocumentFragment;
+VALUE mkr_mXmlNodeMethods;
+VALUE mkr_cXmlNode;
+VALUE mkr_cXmlDocument;
+VALUE mkr_cXmlElement;
+VALUE mkr_cXmlAttr;
+VALUE mkr_cXmlText;
+VALUE mkr_cXmlComment;
+VALUE mkr_cXmlCDATASection;
+VALUE mkr_cXmlProcessingInstruction;
+VALUE mkr_cXmlDocumentType;
+VALUE mkr_cXmlDocumentFragment;
 VALUE mkr_cNodeSet;
 VALUE mkr_cXPathContext;
 VALUE mkr_mXPath;
 VALUE mkr_mCSS;
+VALUE mkr_mXML;
 VALUE mkr_eError;
 VALUE mkr_eXPathSyntaxError;
 VALUE mkr_eXPathLimitExceeded;
 VALUE mkr_eCSSSyntaxError;
+VALUE mkr_eXmlSyntaxError;
+VALUE mkr_eXmlLimitExceeded;
 
 /* Makiri.__c_selftest -> true, or raises if the safe-core primitives
  * (mkr_core.c) fail their internal edge-case checks. Test hook only. */
@@ -31,9 +60,78 @@ mkr_c_selftest(VALUE self)
     if (rc != 0) {
         rb_raise(mkr_eError, "mkr_core_selftest failed at check %d", rc);
     }
+    int xc = mkr_xml_node_selftest();
+    if (xc != 0) {
+        rb_raise(mkr_eError, "mkr_xml_node_selftest failed at check %d", xc);
+    }
+    int pc = mkr_xml_parse_selftest();
+    if (pc != 0) {
+        rb_raise(mkr_eError, "mkr_xml_parse_selftest failed at check %d", pc);
+    }
+    int qc = mkr_xml_xpath_selftest();
+    if (qc != 0) {
+        rb_raise(mkr_eError, "mkr_xml_xpath_selftest failed at check %d", qc);
+    }
+    int mc = mkr_xml_mutate_selftest();
+    if (mc != 0) {
+        rb_raise(mkr_eError, "mkr_xml_mutate_selftest failed at check %d", mc);
+    }
     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
+ * (tokenizer + tree builder) lands and subsumes it. */
+static VALUE
+mkr_xml_s_decode(VALUE self, VALUE str)
+{
+    (void)self;
+    return mkr_xml_decode_input(rb_String(str), 0);  /* decode-only: no arena, no budget */
+}
+
 RUBY_FUNC_EXPORTED void
 Init_makiri(void)
 {
@@ -41,10 +139,10 @@ Init_makiri(void)
     mkr_cNode          = rb_define_class_under(mkr_mMakiri, "Node",         rb_cObject);
     mkr_cDocument      = rb_define_class_under(mkr_mMakiri, "Document",     mkr_cNode);
     mkr_cElement       = rb_define_class_under(mkr_mMakiri, "Element",      mkr_cNode);
-    mkr_cAttribute     = rb_define_class_under(mkr_mMakiri, "Attribute",    mkr_cNode);
+    mkr_cAttr     = rb_define_class_under(mkr_mMakiri, "Attr",    mkr_cNode);
     mkr_cText          = rb_define_class_under(mkr_mMakiri, "Text",         mkr_cNode);
     mkr_cComment       = rb_define_class_under(mkr_mMakiri, "Comment",      mkr_cNode);
-    mkr_cCData         = rb_define_class_under(mkr_mMakiri, "CData",        mkr_cNode);
+    mkr_cCDATASection         = rb_define_class_under(mkr_mMakiri, "CDATASection",        mkr_cNode);
     mkr_cProcessingInstruction =
         rb_define_class_under(mkr_mMakiri, "ProcessingInstruction", mkr_cNode);
     mkr_cDocumentType =
@@ -56,11 +154,85 @@ Init_makiri(void)
 
     mkr_mXPath         = rb_define_module_under(mkr_mMakiri, "XPath");
     mkr_mCSS           = rb_define_module_under(mkr_mMakiri, "CSS");
+    mkr_mXML           = rb_define_module_under(mkr_mMakiri, "XML");
+
+    /* Per-kind hierarchy (§12): the classes above are abstract bases; concrete
+     * HTML nodes are Makiri::HTML::* leaves. The reader/query methods (which read
+     * lxb_dom) live on the mkr_mHtmlNodeMethods behavior module and are included into
+     * every leaf, so XML nodes (added in step 2) never inherit an HTML reader. */
+    mkr_mHTML          = rb_define_module_under(mkr_mMakiri, "HTML");
+    mkr_mHtmlNodeMethods = rb_define_module_under(mkr_mHTML, "NodeMethods");
+    /* The concrete generic HTML node - the wrap fallback for an uncommon DOM node
+     * type with no more specific leaf. Carries the readers but is not an Element. */
+    mkr_cHtmlNode      = rb_define_class_under(mkr_mHTML, "Node",         mkr_cNode);
+    mkr_cHtmlDocument  = rb_define_class_under(mkr_mHTML, "Document",     mkr_cDocument);
+    mkr_cHtmlElement   = rb_define_class_under(mkr_mHTML, "Element",      mkr_cElement);
+    mkr_cHtmlAttr = rb_define_class_under(mkr_mHTML, "Attr",    mkr_cAttr);
+    mkr_cHtmlText      = rb_define_class_under(mkr_mHTML, "Text",         mkr_cText);
+    mkr_cHtmlComment   = rb_define_class_under(mkr_mHTML, "Comment",      mkr_cComment);
+    mkr_cHtmlCDATASection     = rb_define_class_under(mkr_mHTML, "CDATASection",        mkr_cCDATASection);
+    mkr_cHtmlProcessingInstruction =
+        rb_define_class_under(mkr_mHTML, "ProcessingInstruction", mkr_cProcessingInstruction);
+    mkr_cHtmlDocumentType =
+        rb_define_class_under(mkr_mHTML, "DocumentType", mkr_cDocumentType);
+    mkr_cHtmlDocumentFragment =
+        rb_define_class_under(mkr_mHTML, "DocumentFragment", mkr_cDocumentFragment);
+
+    /* Every HTML leaf - the generic node and the typed leaves - gets the shared
+     * lxb_dom reader/query methods. */
+    VALUE html_leaves[] = {
+        mkr_cHtmlNode, mkr_cHtmlDocument, mkr_cHtmlElement, mkr_cHtmlAttr,
+        mkr_cHtmlText, mkr_cHtmlComment, mkr_cHtmlCDATASection,
+        mkr_cHtmlProcessingInstruction, mkr_cHtmlDocumentType,
+        mkr_cHtmlDocumentFragment,
+    };
+    for (size_t i = 0; i < sizeof(html_leaves) / sizeof(html_leaves[0]); i++) {
+        rb_include_module(html_leaves[i], mkr_mHtmlNodeMethods);
+        rb_undef_alloc_func(html_leaves[i]); /* created only from C, never .new */
+    }
+
+    /* Makiri::XML leaves (the custom-node counterparts). XML::Document itself is
+     * defined in mkr_init_xml (it backs a mkr_parsed_t, not a node). */
+    mkr_mXmlNodeMethods = rb_define_module_under(mkr_mXML, "NodeMethods");
+    mkr_cXmlNode      = rb_define_class_under(mkr_mXML, "Node",      mkr_cNode);
+    mkr_cXmlElement   = rb_define_class_under(mkr_mXML, "Element",   mkr_cElement);
+    mkr_cXmlAttr = rb_define_class_under(mkr_mXML, "Attr", mkr_cAttr);
+    mkr_cXmlText      = rb_define_class_under(mkr_mXML, "Text",      mkr_cText);
+    mkr_cXmlComment   = rb_define_class_under(mkr_mXML, "Comment",   mkr_cComment);
+    mkr_cXmlCDATASection     = rb_define_class_under(mkr_mXML, "CDATASection",     mkr_cCDATASection);
+    mkr_cXmlProcessingInstruction =
+        rb_define_class_under(mkr_mXML, "ProcessingInstruction", mkr_cProcessingInstruction);
+    /* Makiri::XML::DocumentType - the off-tree DOCTYPE metadata node
+     * (doc->doctype), reachable only via Document#internal_subset (XPath has no
+     * doctype node, as in Nokogiri/libxml2). The canonical name is the WHATWG DOM
+     * interface name DocumentType (with a Makiri::XML::DTD alias for Nokogiri
+     * compatibility, defined in Ruby); it descends from the shared
+     * Makiri::DocumentType base (like HTML::DocumentType) - not Makiri::XML::Node -
+     * so is_a?(Makiri::DocumentType) holds for both HTML and XML doctypes. It is
+     * still an XML node leaf (the reader/identity methods come from the included
+     * mkr_mXmlNodeMethods below), with its own name/external_id/system_id readers. */
+    mkr_cXmlDocumentType       = rb_define_class_under(mkr_mXML, "DocumentType", mkr_cDocumentType);
+    /* Makiri::XML::DocumentFragment - a detached group of sibling nodes built by
+     * XML::DocumentFragment.parse / XML::Document#fragment (an XML node leaf, like
+     * its HTML counterpart). */
+    mkr_cXmlDocumentFragment =
+        rb_define_class_under(mkr_mXML, "DocumentFragment", mkr_cDocumentFragment);
+    VALUE xml_leaves[] = {
+        mkr_cXmlNode, mkr_cXmlElement, mkr_cXmlAttr, mkr_cXmlText,
+        mkr_cXmlComment, mkr_cXmlCDATASection, mkr_cXmlProcessingInstruction, mkr_cXmlDocumentType,
+        mkr_cXmlDocumentFragment,
+    };
+    for (size_t i = 0; i < sizeof(xml_leaves) / sizeof(xml_leaves[0]); i++) {
+        rb_include_module(xml_leaves[i], mkr_mXmlNodeMethods);
+        rb_undef_alloc_func(xml_leaves[i]);
+    }
 
     mkr_eError              = rb_define_class_under(mkr_mMakiri, "Error", rb_eStandardError);
     mkr_eXPathSyntaxError   = rb_define_class_under(mkr_mXPath, "SyntaxError",   mkr_eError);
     mkr_eXPathLimitExceeded = rb_define_class_under(mkr_mXPath, "LimitExceeded", mkr_eXPathSyntaxError);
     mkr_eCSSSyntaxError     = rb_define_class_under(mkr_mCSS,   "SyntaxError",   mkr_eError);
+    mkr_eXmlSyntaxError     = rb_define_class_under(mkr_mXML,   "SyntaxError",   mkr_eError);
+    mkr_eXmlLimitExceeded   = rb_define_class_under(mkr_mXML,   "LimitExceeded", mkr_eError);
 
     /* Instances of these classes are created only from C via
      * TypedData_Make_Struct (document parse / tree traversal / query
@@ -70,10 +242,10 @@ Init_makiri(void)
     rb_undef_alloc_func(mkr_cNode);
     rb_undef_alloc_func(mkr_cDocument);
     rb_undef_alloc_func(mkr_cElement);
-    rb_undef_alloc_func(mkr_cAttribute);
+    rb_undef_alloc_func(mkr_cAttr);
     rb_undef_alloc_func(mkr_cText);
     rb_undef_alloc_func(mkr_cComment);
-    rb_undef_alloc_func(mkr_cCData);
+    rb_undef_alloc_func(mkr_cCDATASection);
     rb_undef_alloc_func(mkr_cProcessingInstruction);
     rb_undef_alloc_func(mkr_cDocumentType);
     rb_undef_alloc_func(mkr_cDocumentFragment);
@@ -89,6 +261,12 @@ Init_makiri(void)
     mkr_init_css();
     mkr_init_serialize();
     mkr_init_mutate();
+    mkr_init_xml();
+    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/makiri.h

@@ -15,24 +15,64 @@ extern "C" {
 
 /* Ruby module + class refs, populated by Init_makiri. */
 extern VALUE mkr_mMakiri;
+/* Abstract bases (§12): Node and the per-type bases. Concrete nodes are the
+ * per-kind leaves below; `is_a?(Makiri::Element)` etc. stays true for both. */
 extern VALUE mkr_cNode;
 extern VALUE mkr_cDocument;
 extern VALUE mkr_cElement;
-extern VALUE mkr_cAttribute;
+extern VALUE mkr_cAttr;
 extern VALUE mkr_cText;
 extern VALUE mkr_cComment;
-extern VALUE mkr_cCData;
+extern VALUE mkr_cCDATASection;
 extern VALUE mkr_cProcessingInstruction;
 extern VALUE mkr_cDocumentType;
 extern VALUE mkr_cDocumentFragment;
+
+/* Makiri::HTML module + leaves. mkr_mHtmlNodeMethods (Makiri::HTML::NodeMethods)
+ * is a behavior module holding the lxb_dom-backed reader/query methods, included
+ * into every HTML leaf (so an XML node never inherits an HTML reader).
+ * mkr_cHtmlNode (Makiri::HTML::Node) is the concrete generic HTML node - the
+ * wrap fallback for an uncommon DOM node type that has no more specific leaf
+ * (it carries the readers but is NOT classified as an Element). */
+extern VALUE mkr_mHTML;
+extern VALUE mkr_mHtmlNodeMethods;
+extern VALUE mkr_cHtmlNode;
+extern VALUE mkr_cHtmlDocument;
+extern VALUE mkr_cHtmlElement;
+extern VALUE mkr_cHtmlAttr;
+extern VALUE mkr_cHtmlText;
+extern VALUE mkr_cHtmlComment;
+extern VALUE mkr_cHtmlCDATASection;
+extern VALUE mkr_cHtmlProcessingInstruction;
+extern VALUE mkr_cHtmlDocumentType;
+extern VALUE mkr_cHtmlDocumentFragment;
+
+/* Makiri::XML leaves + the XML reader behavior module (the custom-node
+ * counterpart of mkr_mHtmlNodeMethods). */
+extern VALUE mkr_mXmlNodeMethods;
+extern VALUE mkr_cXmlNode;
+extern VALUE mkr_cXmlDocument;
+extern VALUE mkr_cXmlElement;
+extern VALUE mkr_cXmlAttr;
+extern VALUE mkr_cXmlText;
+extern VALUE mkr_cXmlComment;
+extern VALUE mkr_cXmlCDATASection;
+extern VALUE mkr_cXmlProcessingInstruction;
+extern VALUE mkr_cXmlDocumentType;
+extern VALUE mkr_cXmlDocumentFragment;
+
+void mkr_init_xml_node(void);
 extern VALUE mkr_cNodeSet;
 extern VALUE mkr_cXPathContext;
 extern VALUE mkr_mXPath;
 extern VALUE mkr_mCSS;
+extern VALUE mkr_mXML;
 extern VALUE mkr_eError;
 extern VALUE mkr_eXPathSyntaxError;
 extern VALUE mkr_eXPathLimitExceeded;
 extern VALUE mkr_eCSSSyntaxError;
+extern VALUE mkr_eXmlSyntaxError;
+extern VALUE mkr_eXmlLimitExceeded;
 
 /* Forward-declared sub-init entry points. Each sub-component owns its
  * own Init_* and registers methods on the class refs above. */
@@ -43,6 +83,7 @@ void mkr_init_xpath(void);
 void mkr_init_css(void);
 void mkr_init_serialize(void);
 void mkr_init_mutate(void);
+void mkr_init_xml(void);
 
 #ifdef __cplusplus
 }

data/ext/makiri/xml/mkr_xml.h

@@ -0,0 +1,125 @@
+/* mkr_xml.h - public boundary of the native XML reader (Phase 1, read-only).
+ *
+ * Ruby-free. The Ruby surface (Makiri::XML::Document.parse / Makiri::XML(...)) lives in
+ * glue/ruby_xml.c, which decodes input (bridge/mkr_xml_decode_input), releases
+ * the GVL, and calls mkr_xml_parse here. See docs/xml_parser_plan.ja.md.
+ */
+#ifndef MKR_XML_H
+#define MKR_XML_H
+
+#include <stddef.h>
+#include "mkr_xml_node.h"
+
+/* Fail-closed status codes (mapped to Ruby exceptions at the glue boundary). */
+typedef enum {
+    MKR_XML_OK = 0,
+    MKR_XML_ERR_SYNTAX,   /* well-formedness violation -> Makiri::XML::SyntaxError */
+    MKR_XML_ERR_LIMIT,    /* budget exceeded            -> Makiri::XML::LimitExceeded */
+    MKR_XML_ERR_OOM,      /* allocation failure         -> Makiri::Error */
+    MKR_XML_ERR_INTERNAL, /* impossible-state guard tripped (programming error) -> Makiri::Error */
+    MKR_XML_ERR_VERSION   /* well-formed but a version != 1.0 (XML 1.1) -> Makiri::XML::SyntaxError */
+} mkr_xml_status_t;
+
+/* Per-document budgets (§4). Enforced in the arena / tree builder; exceeding any
+ * of them is fail-closed (no partial/truncated document - raise instead). */
+#define MKR_XML_MAX_DEPTH   1024u                 /* element nesting (no stack DoS) */
+#define MKR_XML_MAX_NODES   (10u * 1000u * 1000u) /* total DOM nodes - a SECONDARY guard; the
+                                                   * byte budget below is the primary memory
+                                                   * ceiling (at ~128 B/node it caps node count
+                                                   * well under 10M, so it trips first). */
+#define MKR_XML_MAX_ATTRS   4096u                 /* attributes per element */
+#define MKR_XML_MAX_NS      4096u                 /* namespace bindings IN SCOPE at once - the
+                                                   * scope-stack depth, popped on element close.
+                                                   * Bounds concurrent bindings + the binds array,
+                                                   * NOT document-wide distinct declarations (those
+                                                   * are each an attribute, bounded by the byte /
+                                                   * attr budgets). */
+#ifndef MKR_XML_MAX_BYTES
+/* Arena payload cap: the single arena choke (arena_alloc) counts BOTH node
+ * structs and copied name/value bytes against this, so it is the master memory
+ * ceiling - it subsumes the node-count limit and bounds tiny-element
+ * amplification (a `<a/>` flood is ~23x input→arena, measured) to ~11 MB of
+ * hostile input. Enforced before each allocation, and the parse entry rejects
+ * any input longer than this up front (so the line-ending scratch is bounded
+ * too). 256 MiB comfortably fits every standard document (a 50 MB sitemap is
+ * ~82 MB of arena; RSS/Atom/SOAP far less) and only rejects documents past
+ * ~2M elements. A caller that needs more passes max_bytes to mkr_xml_parse_ex
+ * (per-document override); -DMKR_XML_MAX_BYTES changes the default. */
+#define MKR_XML_MAX_BYTES   ((size_t)256u * 1024u * 1024u)  /* 256 MiB */
+#endif
+
+/* Per-parse budget overrides (the runtime counterpart of the MKR_XML_MAX_*
+ * compile-time defaults). A 0 field means "use the compile-time default", so a
+ * zeroed struct (or a NULL pointer to mkr_xml_parse_ex) reproduces mkr_xml_parse
+ * exactly. Only max_bytes is honoured today; the other budgets (max_nodes,
+ * max_depth, max_attrs, max_ns) are intended to join this struct as they become
+ * runtime-configurable, without changing the entry-point signature. */
+typedef struct {
+    size_t max_bytes;   /* arena payload cap; 0 = MKR_XML_MAX_BYTES */
+} mkr_xml_limits_t;
+
+/* Parse +len+ bytes of already-decoded, validated UTF-8 (§2.1 guarantees the
+ * input is valid UTF-8, XML-Char-only, NUL-free) into a document. Ruby-free, so
+ * the caller runs it with the GVL released. Returns NULL and sets *status on
+ * failure; otherwise an owned mkr_xml_doc_t the caller must hand to GC
+ * (mkr_xml_doc_destroy on free).
+ *
+ * mkr_xml_parse uses the compile-time default budgets; mkr_xml_parse_ex applies
+ * the non-zero fields of +limits+ over them first (a NULL +limits+ is identical
+ * to mkr_xml_parse). */
+mkr_xml_doc_t *mkr_xml_parse(const char *src, size_t len, mkr_xml_status_t *status);
+mkr_xml_doc_t *mkr_xml_parse_ex(const char *src, size_t len,
+                                const mkr_xml_limits_t *limits, mkr_xml_status_t *status);
+
+/* Parse +src+ as a FRAGMENT (0+ top-level nodes: char data, multiple elements,
+ * comments, PIs, CDATA - no XML declaration, DOCTYPE, or single-root rule) into a
+ * fresh DOCUMENT_FRAGMENT node in +doc+'s arena, returned on success. When
+ * +inherit_doc_ns+ is set, +doc+'s root in-scope namespace declarations seed the
+ * scope so a prefixed/default-namespaced name resolves against the document
+ * (Document#fragment); otherwise the fragment is self-contained
+ * (DocumentFragment.parse, typically into a fresh doc). Bytes count against
+ * +doc+'s budget. NULL + *status on error; the partial fragment is left detached
+ * in the arena (never freed). The input must already be validated UTF-8. */
+mkr_xml_node_t *mkr_xml_parse_fragment(mkr_xml_doc_t *doc, const char *src, size_t len,
+                                       int inherit_doc_ns, mkr_xml_status_t *status);
+
+/* Structural self-test of the tokenizer + tree builder (run from
+ * Makiri.__c_selftest). Returns 0 on success or the 1-based failing check. */
+int mkr_xml_parse_selftest(void);
+
+/* Self-test of the monomorphized XML XPath engine instance (xpath/
+ * mkr_xpath_xml_selftest.c): runs queries through the _xml engine over a small
+ * document. Returns 0 or the 1-based failing check. */
+int mkr_xml_xpath_selftest(void);
+
+/* --- character data: XML Char + entity/char-reference expansion (§9.1/§9.2) --- */
+int mkr_xml_is_char(uint32_t c);
+
+/* Validate that [src, src+len) is entirely XML 1.0 Char with NO reference
+ * recognition (comment/CDATA/PI content, where '&'/'<' are literal). 0 / -1. */
+int mkr_xml_validate_chars(const char *src, uint32_t len);
+
+/* 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);
+
+/* Expansion context. ATTR adds XML 1.0 §3.3.3 attribute-value normalization:
+ * a *literal* white-space byte (TAB/LF/CR) becomes a space, while a white-space
+ * character produced by a numeric reference (&#9;/&#10;/&#13;) is preserved. TEXT
+ * copies content verbatim (no whitespace folding). */
+typedef enum {
+    MKR_XML_EXPAND_TEXT = 0,
+    MKR_XML_EXPAND_ATTR = 1
+} mkr_xml_expand_mode_t;
+
+/* Expand the 5 predefined entities + numeric char refs in [src, src+len),
+ * validating XML Char (and, in ATTR mode, normalizing literal whitespace); writes
+ * the (never-longer) result into the arena. Returns the arena slice and sets
+ * *out_len, or NULL on undefined entity / bad reference / non-XML-Char (sets
+ * *status) 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);
+
+#endif /* MKR_XML_H */