makiri 0.1.0 → 0.3.0

data/ext/makiri/bridge/bridge.h

@@ -46,6 +46,34 @@ mkr_ruby_borrowed_bytes_t mkr_ruby_bytes_view(VALUE in);
  * for an empty input), suitable for use while the GVL is released. */
 int mkr_ruby_copy_bytes(VALUE in, mkr_owned_bytes_t *out);
 
+/* Return a UTF-8 Ruby String for `str`, honouring its declared encoding: UTF-8 /
+ * US-ASCII / ASCII-8BIT are returned unchanged (the parser handles their bytes
+ * directly); any other encoding is transcoded to UTF-8 (invalid/undef -> U+FFFD)
+ * so its content is preserved rather than read as raw UTF-8. The UTF-8 common
+ * case is a single encoding comparison. */
+VALUE mkr_ruby_to_utf8(VALUE str);
+
+/* STRICT decode for XML (§2.1): like mkr_ruby_to_utf8 it honours the String's
+ * declared encoding (UTF-8 / US-ASCII / ASCII-8BIT pass through; any other
+ * encoding is transcoded to UTF-8) - but FAIL-CLOSED, never lenient: a non-UTF-8
+ * byte that can't be converted, invalid UTF-8, or an embedded NUL all raise
+ * Makiri::XML::SyntaxError (no U+FFFD replacement). Returns a validated,
+ * UTF-8-tagged Ruby String. (The HTML replace path mkr_ruby_to_utf8 itself is
+ * NOT reused for the conversion - only its encoding-judgment rule is shared.)
+ *
+ * +max_bytes+ bounds the decoded UTF-8 length: an input that already exceeds the
+ * parser's arena byte budget is rejected here with Makiri::XML::LimitExceeded,
+ * before the validation copy and the caller's GVL-release copy (so a hostile
+ * oversized document is not copied twice for a doomed parse). 0 disables the
+ * check (decode-only callers that build no arena). */
+VALUE mkr_xml_decode_input(VALUE str, size_t max_bytes);
+
+/* True if `str` is *already known* to be valid UTF-8 - pure ASCII, or valid in
+ * the UTF-8 encoding - from its cached coderange, WITHOUT forcing a scan. Lets
+ * the parse skip mkr_utf8_sanitize's validation pass for input Ruby has already
+ * classified (an unknown/broken coderange returns false: sanitize handles it). */
+bool mkr_ruby_str_known_valid_utf8(VALUE str);
+
 /* Validate a Ruby String for use as an XPath engine string: valid UTF-8,
  * no interior NUL, and at most +max_bytes+. Returns NULL on success and fills
  * +out+; otherwise returns a static reason string. +sv+ must be a String. */

data/ext/makiri/bridge/ruby_string.c

@@ -108,6 +108,223 @@ mkr_ruby_copy_bytes(VALUE in, mkr_owned_bytes_t *out)
     return 0;
 }
 
+VALUE
+mkr_ruby_to_utf8(VALUE str)
+{
+    /* Honour the Ruby String's declared encoding so its content survives:
+     *
+     *  - UTF-8 / US-ASCII / ASCII-8BIT (binary): returned unchanged. These are
+     *    already UTF-8 bytes (or deliberately raw bytes), and the native parser
+     *    does the WHATWG invalid-byte replacement for them. The UTF-8 common
+     *    case costs only this encoding comparison - no transcode, no copy.
+     *
+     *  - any other encoding (Shift_JIS, EUC-JP, ISO-8859-1, Windows-1252, ...):
+     *    transcoded to UTF-8 with invalid/undef -> U+FFFD, so e.g. Shift_JIS
+     *    text becomes the right UTF-8 characters instead of being read as raw
+     *    UTF-8 bytes and mangled. Only non-UTF-8 input pays this. */
+    rb_encoding *enc = rb_enc_get(str);
+    if (enc == rb_utf8_encoding()
+        || enc == rb_usascii_encoding()
+        || enc == rb_ascii8bit_encoding()) {
+        return str;
+    }
+    return rb_str_encode(str, rb_enc_from_encoding(rb_utf8_encoding()),
+                         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. */
+static rb_encoding *
+mkr_xml_bom_encoding(const unsigned char *p, long len, long *bom_len)
+{
+    *bom_len = 0;
+    if (len >= 4 && p[0] == 0x00 && p[1] == 0x00 && p[2] == 0xFE && p[3] == 0xFF) {
+        *bom_len = 4; return rb_enc_find("UTF-32BE");
+    }
+    if (len >= 4 && p[0] == 0xFF && p[1] == 0xFE && p[2] == 0x00 && p[3] == 0x00) {
+        *bom_len = 4; return rb_enc_find("UTF-32LE");
+    }
+    if (len >= 2 && p[0] == 0xFE && p[1] == 0xFF) { *bom_len = 2; return rb_enc_find("UTF-16BE"); }
+    if (len >= 2 && p[0] == 0xFF && p[1] == 0xFE) { *bom_len = 2; return rb_enc_find("UTF-16LE"); }
+    if (len >= 3 && p[0] == 0xEF && p[1] == 0xBB && p[2] == 0xBF) { *bom_len = 3; return rb_utf8_encoding(); }
+    return NULL;
+}
+
+/* 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 (per the BOM) before the
+ * scan, letting a BOM-vs-declaration conflict be caught even in UTF-16. */
+static rb_encoding *
+mkr_xml_decl_encoding(const unsigned char *p, long len, rb_encoding *bom)
+{
+    long stride = 1, off = 0;
+    if (bom == rb_enc_find("UTF-16LE"))      { stride = 2; off = 0; }
+    else if (bom == rb_enc_find("UTF-16BE")) { stride = 2; off = 1; }
+    else if (bom == rb_enc_find("UTF-32LE")) { stride = 4; off = 0; }
+    else if (bom == rb_enc_find("UTF-32BE")) { stride = 4; off = 3; }
+
+    char head[256];
+    long hn = 0;
+    for (long i = off; i < len && hn < (long)sizeof(head); i += stride) head[hn++] = (char)p[i];
+
+    long i = 0;
+    while (i < hn && (head[i] == ' ' || head[i] == '\t' || head[i] == '\r' || head[i] == '\n')) i++;
+    if (i + 5 > hn || memcmp(head + i, "<?xml", 5) != 0) return NULL;
+    i += 5;
+    /* find a whitespace-introduced "encoding" before the '?>' */
+    for (; i + 8 <= hn; i++) {
+        if (head[i] == '?' && i + 1 < hn && head[i + 1] == '>') return NULL; /* end of decl */
+        int ws_before = (head[i - 1] == ' ' || head[i - 1] == '\t' || head[i - 1] == '\r' || head[i - 1] == '\n');
+        if (!ws_before || memcmp(head + i, "encoding", 8) != 0) continue;
+        long j = i + 8;
+        while (j < hn && (head[j] == ' ' || head[j] == '\t' || head[j] == '\r' || head[j] == '\n')) j++;
+        if (j >= hn || head[j] != '=') return NULL;
+        j++;
+        while (j < hn && (head[j] == ' ' || head[j] == '\t' || head[j] == '\r' || head[j] == '\n')) j++;
+        if (j >= hn || (head[j] != '"' && head[j] != '\'')) return NULL;
+        char q = head[j++];
+        long ns = j;
+        while (j < hn && head[j] != q) j++;
+        if (j >= hn) return NULL;
+        char name[64];
+        long nl = j - ns;
+        if (nl <= 0 || nl >= (long)sizeof(name)) return NULL;
+        memcpy(name, head + ns, (size_t)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;
+    rb_encoding *bom  = mkr_xml_bom_encoding(raw, rawlen, &bom_len);
+    rb_encoding *decl = mkr_xml_decl_encoding(raw + bom_len, rawlen - bom_len, bom);
+    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);
+        }
+        RB_GC_GUARD(in);
+    }
+
+    const char *ptr = RSTRING_PTR(s);
+    long        len = RSTRING_LEN(s);
+    /* §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). */
+    if (len >= 3 && (unsigned char)ptr[0] == 0xEF && (unsigned char)ptr[1] == 0xBB
+        && (unsigned char)ptr[2] == 0xBF) {
+        ptr += 3; len -= 3;
+    }
+
+    /* Fail closed on an over-budget input BEFORE the validation copy 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_GC_GUARD(s);
+        rb_raise(mkr_eXmlLimitExceeded, "XML input exceeds the byte budget");
+    }
+
+    /* Strict UTF-8 validation: an embedded NUL or any invalid UTF-8 is fatal
+     * (no U+FFFD repair - unlike the HTML mkr_utf8_sanitize path). */
+    if (len > 0 && memchr(ptr, '\0', (size_t)len) != NULL) {
+        rb_raise(mkr_eXmlSyntaxError, "XML input must not contain a NUL byte");
+    }
+    VALUE u = rb_enc_str_new(ptr, len, rb_utf8_encoding());
+    if (rb_enc_str_coderange(u) == ENC_CODERANGE_BROKEN) {
+        rb_raise(mkr_eXmlSyntaxError, "XML input must be valid UTF-8");
+    }
+    RB_GC_GUARD(s);
+    return u; /* validated, UTF-8-tagged, BOM-stripped */
+}
+
+bool
+mkr_ruby_str_known_valid_utf8(VALUE str)
+{
+    if (!RB_TYPE_P(str, T_STRING)) {
+        return false;
+    }
+    /* ENC_CODERANGE reads the *cached* classification from the object's flags;
+     * it does NOT scan (rb_enc_str_coderange would, costing as much as our own
+     * validator). So this only wins when Ruby already knows the answer. */
+    int cr = ENC_CODERANGE(str);
+    if (cr == ENC_CODERANGE_7BIT) {
+        return true; /* all bytes < 0x80 in an ASCII-compatible encoding */
+    }
+    if (cr == ENC_CODERANGE_VALID) {
+        return rb_enc_get(str) == rb_utf8_encoding(); /* valid AND UTF-8 */
+    }
+    return false; /* UNKNOWN or BROKEN: let mkr_utf8_sanitize handle it */
+}
+
 const char *
 mkr_ruby_try_verified_text(VALUE sv, size_t max_bytes, mkr_ruby_borrowed_text_t *out)
 {

data/ext/makiri/core/mkr_alloc.h

@@ -6,7 +6,7 @@
  * allocators, the foundation every other C layer (glue, xpath engine,
  * lexbor_compat) builds on, so the ad-hoc `cap *= 2` / `n + 1` /
  * `malloc(n * sizeof(T))` patterns are written once, here, and fail closed.
- * NOTHING in this header touches Ruby — exception mapping happens at the glue
+ * NOTHING in this header touches Ruby - exception mapping happens at the glue
  * boundary. (mkr_core.h is a thin umbrella over this + the other core headers.)
  */
 

data/ext/makiri/core/mkr_buf.c

@@ -13,7 +13,12 @@ mkr_buf_append(mkr_buf_t *b, const void *bytes, size_t n)
     if (!mkr_size_add(b->len, n, &need)) {
         return MKR_ERR_OOM;
     }
-    if (b->max != 0 && need > b->max) {
+    /* max == 0 is NOT unbounded: it falls back to the conservative default
+     * ceiling, so a caller that never set a cap still fails closed. Either way the
+     * absolute hard ceiling clamps it, so no buffer can exhaust memory. */
+    size_t soft  = (b->max != 0) ? b->max : MKR_BUF_DEFAULT_LIMIT;
+    size_t limit = (soft < MKR_BUF_HARD_MAX) ? soft : MKR_BUF_HARD_MAX;
+    if (need > limit) {
         return MKR_ERR_LIMIT;
     }
     size_t need_term; /* room for the NUL terminator too */
@@ -38,6 +43,35 @@ mkr_buf_append(mkr_buf_t *b, const void *bytes, size_t n)
     return MKR_OK;
 }
 
+mkr_status_t
+mkr_buf_reserve(mkr_buf_t *b, size_t n)
+{
+    /* Pre-allocate capacity for n bytes so a known-size fill does not realloc on
+     * every geometric step (the serializer reserves ~the output size up front).
+     * Best-effort: never grow past the buffer's own cap, and a later append still
+     * fails closed if the real output exceeds it. */
+    size_t soft  = (b->max != 0) ? b->max : MKR_BUF_DEFAULT_LIMIT;
+    size_t limit = (soft < MKR_BUF_HARD_MAX) ? soft : MKR_BUF_HARD_MAX;
+    if (n > limit) {
+        n = limit;
+    }
+    size_t need_term; /* room for the NUL terminator too */
+    if (!mkr_size_add(n, 1, &need_term)) {
+        return MKR_ERR_OOM;
+    }
+    if (need_term <= b->cap) {
+        return MKR_OK; /* already have room */
+    }
+    char *p = realloc(b->data, need_term);
+    if (p == NULL) {
+        return MKR_ERR_OOM;
+    }
+    b->data = p;
+    b->cap  = need_term;
+    b->data[b->len] = '\0'; /* keep NUL-terminated */
+    return MKR_OK;
+}
+
 char *
 mkr_buf_steal(mkr_buf_t *b, size_t *out_len)
 {

data/ext/makiri/core/mkr_buf.h

@@ -2,7 +2,7 @@
 #define MAKIRI_CORE_MKR_BUF_H
 
 /*
- * mkr_buf_t — an owned, growable, optionally capped byte buffer, kept
+ * mkr_buf_t - an owned, growable, optionally capped byte buffer, kept
  * NUL-terminated. Built on the fail-closed allocators in mkr_alloc.h.
  * (mkr_core.h is a thin umbrella over mkr_alloc.h + mkr_text.h + this.)
  */
@@ -13,14 +13,42 @@
 extern "C" {
 #endif
 
+/* Memory safety for buffers lives HERE, at the one buffer primitive, not at each
+ * call site: "max == 0" can no longer mean "unbounded". Two ceilings bound every
+ * mkr_buf so a runaway - a cycle, an unbounded loop, or a caller that forgot to
+ * pass a cap - fails closed with MKR_ERR_LIMIT instead of exhausting memory and
+ * freezing the machine:
+ *
+ *   MKR_BUF_DEFAULT_LIMIT  the cap applied when the caller passes max == 0. A
+ *                          conservative default (100 MiB): code that did not
+ *                          think about a bound gets a tight one for free, and a
+ *                          buffer that genuinely needs to be large must opt in
+ *                          EXPLICITLY by passing a larger max.
+ *   MKR_BUF_HARD_MAX       an absolute ceiling no buffer may exceed, even one
+ *                          with an explicit max - the last-resort backstop.
+ *                          Tight, content-scaled bounds still belong to the
+ *                          caller (e.g. the XML serializer caps itself at a
+ *                          multiple of arena_bytes); this stops total runaway.
+ *
+ * Override either at build time: -DMKR_BUF_DEFAULT_LIMIT=<bytes> / -DMKR_BUF_HARD_MAX=<bytes>. */
+#ifndef MKR_BUF_DEFAULT_LIMIT
+#define MKR_BUF_DEFAULT_LIMIT ((size_t)100 << 20)   /* 100 MiB */
+#endif
+#ifndef MKR_BUF_HARD_MAX
+#define MKR_BUF_HARD_MAX ((size_t)4 << 30)        /* 4 GiB */
+#endif
+
 typedef struct {
     char  *data; /* owned; kept NUL-terminated after any append */
     size_t len;  /* bytes used (excluding the terminator) */
     size_t cap;  /* bytes allocated */
-    size_t max;  /* 0 = unbounded; else append past max returns MKR_ERR_LIMIT */
+    size_t max;  /* 0 = the conservative MKR_BUF_DEFAULT_LIMIT; else this value -
+                  * either way clamped by MKR_BUF_HARD_MAX (past it -> ERR_LIMIT) */
 } mkr_buf_t;
 
-/* Initialise an empty buffer. max == 0 means unbounded. */
+/* Initialise an empty buffer. max == 0 applies the conservative default ceiling
+ * (MKR_BUF_DEFAULT_LIMIT) - it is NOT unbounded; pass an explicit (larger or
+ * smaller) value to opt into a different bound, always under MKR_BUF_HARD_MAX. */
 static inline void
 mkr_buf_init(mkr_buf_t *b, size_t max)
 {
@@ -35,6 +63,12 @@ mkr_buf_init(mkr_buf_t *b, size_t max)
  * failure (the buffer is left intact in every failure case). n == 0 is a no-op. */
 mkr_status_t mkr_buf_append(mkr_buf_t *b, const void *bytes, size_t n);
 
+/* Pre-allocate capacity for at least n bytes (best-effort, clamped to the
+ * buffer's cap), so a fill of known approximate size avoids per-append reallocs.
+ * A no-op if the buffer already has room. Returns MKR_ERR_OOM on overflow /
+ * allocation failure (the buffer is left intact). */
+mkr_status_t mkr_buf_reserve(mkr_buf_t *b, size_t n);
+
 /* Take ownership of the (NUL-terminated) bytes; the buffer is reset to empty.
  * Returns a freshly owned "" for an empty buffer, or NULL on OOM. */
 char *mkr_buf_steal(mkr_buf_t *b, size_t *out_len);

data/ext/makiri/core/mkr_core.h

@@ -10,7 +10,7 @@
  *   mkr_text.h   string-type lattice (owned/borrowed/verified text + bytes)
  *   mkr_buf.h    mkr_buf_t (growable, capped byte buffer)
  *
- * NOTHING here touches Ruby — exception mapping happens at the glue boundary.
+ * NOTHING here touches Ruby - exception mapping happens at the glue boundary.
  */
 
 #include "mkr_alloc.h"

data/ext/makiri/core/mkr_hash.h

@@ -35,7 +35,7 @@ mkr_ptr_hash(const void *p)
 
 /* Smallest power of two >= n, into *out. Returns false on overflow (no power of
  * two >= n fits in size_t) so the caller fails closed rather than sizing a
- * power-of-two hash table below the element count it must hold — which would
+ * power-of-two hash table below the element count it must hold - which would
  * never find a free slot under linear probing. Shared by the pointer-keyed
  * indexes (attr->owner, text-index). */
 static inline bool

data/ext/makiri/core/mkr_text.h

@@ -16,7 +16,7 @@ extern "C" {
 #endif
 
 /* ---------------------------------------------------------------- */
-/* mkr_verified_text_t — a string proven to meet the engine text contract */
+/* mkr_verified_text_t - a string proven to meet the engine text contract */
 /* ---------------------------------------------------------------- */
 
 /* A borrowed byte slice whose contents are guaranteed to satisfy Makiri's
@@ -39,7 +39,7 @@ typedef struct {
 /*
  * Makiri's string types form a small lattice over two axes plus a shape marker.
  * They look alike ({ptr,len}) but C has no subtyping, so each contract is its
- * own type — that distinctness IS the guarantee, and is why there is no single
+ * own type - that distinctness IS the guarantee, and is why there is no single
  * "string" type.
  *
  *   axis 1  ownership : borrowed (we never free) | owned (free via *_clear)
@@ -51,7 +51,7 @@ typedef struct {
  *   shape \ contract        raw (bytes)               valid (text)
  *   ----------------------  ------------------------  -------------------------
  *   ruby-anchored borrowed  mkr_ruby_borrowed_bytes_t mkr_ruby_borrowed_text_t  (bridge.h)
- *   borrowed slice          (none yet — would be      mkr_borrowed_text_t /
+ *   borrowed slice          (none yet - would be      mkr_borrowed_text_t /
  *                            mkr_borrowed_bytes_t)     mkr_verified_text_t (*)
  *   owned                   mkr_owned_bytes_t         mkr_owned_text_t
  *
@@ -65,22 +65,22 @@ typedef struct {
  *   cannot reach the engine's public API. Internally the engine carries the
  *   freely-constructible mkr_borrowed_text_t instead.
  *
- * Conversions — the only sanctioned edges. The points that actually VALIDATE
+ * Conversions - the only sanctioned edges. The points that actually VALIDATE
  * raw bytes are the bridge's checked entry points; everything else only moves
  * already-valid text between shapes (no edge re-validates, and none turns raw
  * bytes into text without one of those checks):
- *   validate raw -> valid : the bridge's checked entry points only —
+ *   validate raw -> valid : the bridge's checked entry points only -
  *                           mkr_ruby_verified_text / mkr_ruby_try_verified_text
  *                           (both validate UTF-8 + no NUL); never a cast.
  *   drop the GC anchor    : mkr_verified_text_from_view (ruby_borrowed_text -> verified_text)
  *   assert valid (no copy) : mkr_borrowed_text (const char*,len -> borrowed_text)
- *                            — caller asserts the bytes already meet the contract
+ *                            - caller asserts the bytes already meet the contract
  *   downgrade to borrow   : mkr_borrowed_text_from_owned (owned_text -> borrowed_text)
  *                           mkr_borrowed_text_from_verified (verified_text -> borrowed_text)
  *   copy into owned       : mkr_owned_text_from_borrowed_copy /
- *                           mkr_owned_text_from_buf_steal — accept only
+ *                           mkr_owned_text_from_buf_steal - accept only
  *                           already-asserted-valid text; they copy, not validate.
- *   take ownership        : mkr_owned_text (char*,len -> owned_text) — caller
+ *   take ownership        : mkr_owned_text (char*,len -> owned_text) - caller
  *                           transfers an already-valid heap buffer it produced
  *                           (substring/concat/format output); asserts validity.
  */

data/ext/makiri/extconf.rb

@@ -12,7 +12,7 @@ require "etc"
 #   1. Build vendored Lexbor (unpatched) via cmake into vendor/lexbor/build,
 #      install headers + a static archive into vendor/lexbor/dist.
 #   2. Compile ext/makiri/**/*.c with rake-compiler, linking against the
-#      static Lexbor archive only — no system libxml2/libxslt.
+#      static Lexbor archive only - no system libxml2/libxslt.
 #
 # Security note: the C extension is built with -D_FORTIFY_SOURCE=2,
 # -fstack-protector-strong, and -Wformat -Wformat-security. -O2 is kept
@@ -60,7 +60,7 @@ $LDFLAGS << " #{lexbor_archive.shellescape}"
 # Sanitizer build (opt-in): MAKIRI_SANITIZE=address,undefined rake clean compile
 # Then run the suite under the runtime via `rake sanitize` (which preloads the
 # ASan runtime). Sanitizers replace the heap allocator, so even the vendored
-# (uninstrumented) Lexbor's allocations get red-zoned — heap overflows on
+# (uninstrumented) Lexbor's allocations get red-zoned - heap overflows on
 # Lexbor-owned buffers are still caught. _FORTIFY_SOURCE is dropped here because
 # it conflicts with the sanitizer interceptors.
 sanitize = ENV["MAKIRI_SANITIZE"].to_s.strip
@@ -115,6 +115,24 @@ elsif RbConfig::CONFIG["target_os"] =~ /linux/
   $LIBRUBYARG_STATIC = ""
 end
 
+# Export ONLY Init_makiri from the compiled extension. `-fvisibility=hidden`
+# above hides our own sources' symbols, but the vendored Lexbor static library
+# is built (by Lexbor's own CMake) with default visibility, so without this the
+# linker re-exports ~1700 `lxb_*` / `lexbor_*` symbols into the bundle's dynamic
+# table. Another Lexbor-based extension loaded in the same process (e.g.
+# nokolexbor) would then resolve its own `lxb_*` calls to OUR copy - a different
+# Lexbor version with an incompatible ABI - and segfault. Restricting the export
+# list to Init_makiri keeps Makiri's Lexbor entirely private (Ruby only needs
+# Init_makiri, found via dlsym at require time).
+if RbConfig::CONFIG["target_os"] =~ /darwin/
+  $DLDFLAGS << " -Wl,-exported_symbol,_Init_makiri"
+elsif RbConfig::CONFIG["target_os"] =~ /linux/
+  # Hide every symbol pulled in from static archives (the Lexbor .a); our own
+  # are already hidden by -fvisibility=hidden, leaving just RUBY_FUNC_EXPORTED
+  # Init_makiri in the dynamic symbol table.
+  $DLDFLAGS << " -Wl,--exclude-libs,ALL"
+end
+
 # Recursively pick up C sources under ext/makiri/.
 $srcs = Dir.glob(File.join(EXT_DIR, "**", "*.c")).map { |f| f.sub("#{EXT_DIR}/", "") }
 $VPATH ||= []

data/ext/makiri/glue/glue.h

@@ -8,11 +8,24 @@
 extern "C" {
 #endif
 
+/* A DOM node pointer of UNKNOWN representation - an HTML lxb_dom_node_t or an XML
+ * mkr_xml_node_t - as stored in a node wrapper or a NodeSet. It is an INCOMPLETE
+ * type on purpose: it cannot be dereferenced, and (unlike void*) it does not
+ * implicitly convert to a typed pointer, so reading a stored node AS a specific
+ * representation requires an explicit cast that the kind-checked accessors
+ * (mkr_html_node_unwrap / mkr_xml_node_unwrap) justify by the wrapper's TypedData type
+ * (or, for a NodeSet, by doc_is_xml). The stored pointer is only ever
+ * pointer-compared or cast through one of those accessors. */
+typedef struct mkr_raw_node mkr_raw_node_t;
+
 /* Wrapper for any DOM node except Document. The node memory is owned by the
- * document's Lexbor arena; we keep only the pointer plus a keepalive VALUE
- * reference to the Ruby Document so the arena outlives the wrapper. */
+ * document's arena (an HTML Lexbor arena or the XML node arena); we keep only the
+ * pointer plus a keepalive VALUE reference to the Ruby Document so the arena
+ * outlives the wrapper. The pointer is representation-opaque (mkr_raw_node_t):
+ * read it only through mkr_html_node_unwrap / mkr_xml_node_unwrap, which check the
+ * wrapper's representation (distinct TypedData types) before casting. */
 typedef struct {
-    lxb_dom_node_t *node;
+    mkr_raw_node_t *node;
     VALUE           document;
 } mkr_node_data_t;
 
@@ -31,14 +44,35 @@ extern const rb_data_type_t mkr_node_type;
 extern const rb_data_type_t mkr_doc_type;
 extern const rb_data_type_t mkr_node_set_type;
 
-/* Node bridge (glue/ruby_node.c). mkr_wrap_node returns the Document VALUE
+/* Node bridge (glue/ruby_node.c). mkr_wrap_html_node returns the Document VALUE
  * for the document node, Qnil for NULL, otherwise a freshly-wrapped Node. */
-VALUE           mkr_wrap_node(lxb_dom_node_t *node, VALUE document);
-lxb_dom_node_t *mkr_node_unwrap(VALUE rb_node);
+VALUE           mkr_wrap_html_node(lxb_dom_node_t *node, VALUE document);
 VALUE           mkr_node_document(VALUE rb_node);
 
+/* HTML and XML nodes are wrapped under DISTINCT TypedData types (both deriving
+ * from the shared base mkr_node_type), so a representation-specific accessor
+ * rejects the wrong kind via Ruby's type machinery. See ruby_node.c.
+ *   mkr_html_node_unwrap      -> lxb_dom_node_t* ; raises on an XML node/Document.
+ *   mkr_xml_node_unwrap-> mkr_xml_node_t* ; raises on an HTML node/Document (ruby_xml_node.c).
+ *   mkr_node_raw       -> void* ; kind-agnostic raw pointer for identity, or for a
+ *                         site where the kind is already guaranteed. Deref needs an
+ *                         explicit cast - never treat it as a typed pointer blindly.
+ *   mkr_node_id        -> uintptr_t ; node identity for ==/eql?/hash/pointer_id. */
+extern const rb_data_type_t mkr_html_node_type;
+extern const rb_data_type_t mkr_xml_node_type;
+lxb_dom_node_t *mkr_html_node_unwrap(VALUE rb_node);
+void           *mkr_node_raw(VALUE rb_node);
+uintptr_t       mkr_node_id(VALUE rb_node);
+
+/* XML node bridge (glue/ruby_xml_node.c): wrap a custom XML node into the right
+ * Makiri::XML::* leaf (Qnil for NULL, the Document VALUE for the document node). */
+struct mkr_xml_node;
+VALUE mkr_wrap_xml_node(struct mkr_xml_node *node, VALUE document);
+/* XML node-pointer accessor; raises TypeError on an HTML node/Document. */
+struct mkr_xml_node *mkr_xml_node_unwrap(VALUE rb_node);
+
 /* Document bridge (glue/ruby_doc.c). */
-lxb_dom_document_t *mkr_doc_unwrap(VALUE rb_doc);
+lxb_dom_document_t *mkr_html_doc_unwrap(VALUE rb_doc);
 mkr_parsed_t       *mkr_doc_parsed(VALUE rb_doc);
 VALUE               mkr_wrap_document(mkr_parsed_t *parsed); /* GC takes ownership */
 
@@ -46,7 +80,7 @@ VALUE               mkr_wrap_document(mkr_parsed_t *parsed); /* GC takes ownersh
  * inner_html=/outer_html= so the UTF-8 sanitisation and import+template-fixup
  * are not duplicated.
  *
- * mkr_sanitize_html_input: decode rb_html for the fragment parser — *out / *out_len
+ * mkr_sanitize_html_input: decode rb_html for the fragment parser - *out / *out_len
  * are the bytes to parse, *owned a malloc'd buffer to free afterwards (NULL when
  * the input is used in place). Returns 0, or -1 on OOM (nothing allocated), so
  * the caller can release its parser before raising. See mkr_utf8_sanitize.
@@ -54,7 +88,7 @@ VALUE               mkr_wrap_document(mkr_parsed_t *parsed); /* GC takes ownersh
  * mkr_import_fragment_children: deep-import each child of `root` into `doc`, hand
  * it to `emit`, and fix up any <template> contents (which import_node omits).
  *
- * mkr_emit_append / mkr_emit_before: emit callbacks — append as last child of
+ * mkr_emit_append / mkr_emit_before: emit callbacks - append as last child of
  * `u`, or insert before the reference node `u`. */
 int  mkr_sanitize_html_input(VALUE html, const lxb_char_t **out, size_t *out_len,
                              lxb_char_t **owned);
@@ -63,9 +97,17 @@ void mkr_import_fragment_children(lxb_dom_document_t *doc, lxb_dom_node_t *root,
 void mkr_emit_append(lxb_dom_node_t *imported, void *u);
 void mkr_emit_before(lxb_dom_node_t *imported, void *u);
 
-/* NodeSet bridge (glue/ruby_node_set.c). */
+/* Node#clone_node(deep=false): shallow/deep DOM clone owned by this node's
+ * document (import_node + <template>-content fixup), detached from any parent.
+ * Implemented in ruby_doc.c (next to the import machinery), bound in
+ * mkr_init_node. */
+VALUE mkr_node_clone_node(int argc, VALUE *argv, VALUE self);
+
+/* NodeSet bridge (glue/ruby_node_set.c). mkr_raw_node_t (above): callers cast
+ * their typed node to it when pushing (forgetting the type is the safe, store
+ * direction); the single typed read-back lives in mkr_node_set_wrap. */
 VALUE mkr_node_set_new(VALUE document);
-void  mkr_node_set_push(VALUE rb_set, lxb_dom_node_t *node);
+void  mkr_node_set_push(VALUE rb_set, mkr_raw_node_t *node);
 
 #ifdef __cplusplus
 }