makiri 0.3.0 → 0.4.0

data/ext/makiri/bridge/ruby_string.c

@@ -48,19 +48,31 @@ mkr_ruby_str_from_borrowed(mkr_borrowed_text_t text)
 void
 mkr_verify_text(VALUE str, const char *what)
 {
+    /* ALLOCATION-FREE by design: this gate runs between a caller taking a
+     * borrowed RSTRING pointer and using it, so it must not be a GC point. The
+     * former implementation built a throwaway Ruby String (rb_enc_str_new) to
+     * ask for its coderange - a Ruby allocation inside every borrow, which both
+     * passed the borrowed ptr into an allocating call and opened a GC window
+     * under every OTHER borrow already held at multi-borrow call sites. Bytes
+     * are validated as UTF-8 regardless of the String's declared encoding,
+     * exactly as before. */
     long        len = RSTRING_LEN(str);
     const char *ptr = RSTRING_PTR(str);
 
-    if (len > 0 && memchr(ptr, '\0', (size_t)len) != NULL) {
+    mkr_span_t sv = mkr_span(ptr, (size_t)len);
+    size_t nul_at;
+    if (mkr_span_find(&sv, '\0', &nul_at)) {
         rb_raise(mkr_eError, "%s must not contain a NUL byte", what);
     }
 
-    /* Validate the bytes as UTF-8 regardless of the String's declared encoding. */
-    VALUE u = rb_enc_str_new(ptr, len, rb_utf8_encoding());
-    if (rb_enc_str_coderange(u) == ENC_CODERANGE_BROKEN) {
+    /* Cached-coderange fast path (reads flags, never scans, never allocates);
+     * NUL is valid UTF-8, so the memchr above stays either way. */
+    if (mkr_ruby_str_known_valid_utf8(str)) {
+        return;
+    }
+    if (!mkr_utf8_valid((const unsigned char *)ptr, (size_t)len)) {
         rb_raise(mkr_eError, "%s must be valid UTF-8", what);
     }
-    RB_GC_GUARD(str);
 }
 
 mkr_ruby_borrowed_text_t
@@ -96,7 +108,6 @@ mkr_ruby_copy_bytes(VALUE in, mkr_owned_bytes_t *out)
     size_t alloc_len = (v.len > 0) ? v.len : 1;
     char *buf = mkr_reallocarray(NULL, alloc_len, 1);
     if (buf == NULL) {
-        RB_GC_GUARD(v.value);
         return -1;
     }
     if (v.len > 0) {
@@ -145,63 +156,89 @@ mkr_xml_strict_transcode_thunk(VALUE str)
 /* --- 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. */
+ * 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)
+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;
-    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(); }
+    *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;
 }
 
 /* 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)
+ * 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 int
+mkr_decl_ws(int c)
 {
-    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; }
+    return c == ' ' || c == '\t' || c == '\r' || c == '\n';
+}
 
+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];
-    long hn = 0;
-    for (long i = off; i < len && hn < (long)sizeof(head); i += stride) head[hn++] = (char)p[i];
+    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;
 
-    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;
+    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 (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;
+        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++;
-        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++;
+        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];
-        long nl = j - ns;
-        if (nl <= 0 || nl >= (long)sizeof(name)) return NULL;
-        memcpy(name, head + ns, (size_t)nl);
+        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 */
     }
@@ -229,9 +266,15 @@ mkr_xml_decode_input(VALUE str, size_t max_bytes)
      * 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);
+    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)) {
@@ -273,36 +316,44 @@ mkr_xml_decode_input(VALUE str, size_t max_bytes)
             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);
+    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). */
-    if (len >= 3 && (unsigned char)ptr[0] == 0xEF && (unsigned char)ptr[1] == 0xBB
-        && (unsigned char)ptr[2] == 0xBF) {
-        ptr += 3; len -= 3;
+    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 copy and the
+    /* 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_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) {
+    /* Strict UTF-8 validation, allocation-free - no GC point while `ptr` is
+     * borrowed (the former rb_enc_str_new copy handed the borrow straight into
+     * an allocating call): an embedded NUL or any invalid UTF-8 is fatal (no
+     * U+FFFD repair - unlike the HTML mkr_utf8_sanitize path). A whole-string
+     * cached coderange covers the BOM-stripped suffix too (the BOM is one
+     * complete UTF-8 character). */
+    size_t nul_at;
+    if (mkr_span_find(&sv, '\0', &nul_at)) {
         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) {
+    if (!mkr_ruby_str_known_valid_utf8(s)
+        && !mkr_utf8_valid((const unsigned char *)ptr + off, (size_t)len)) {
         rb_raise(mkr_eXmlSyntaxError, "XML input must be valid UTF-8");
     }
-    RB_GC_GUARD(s);
+    /* 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 */
 }
 
@@ -328,22 +379,26 @@ mkr_ruby_str_known_valid_utf8(VALUE str)
 const char *
 mkr_ruby_try_verified_text(VALUE sv, size_t max_bytes, mkr_ruby_borrowed_text_t *out)
 {
+    /* ALLOCATION-FREE, like mkr_verify_text: the returned borrow must not have
+     * crossed a Ruby allocation (the former rb_utf8_str_new + valid_encoding?
+     * funcall allocated twice with `ptr` already taken). */
     long len = RSTRING_LEN(sv);
     if ((size_t)len > max_bytes) {
         return "string exceeds the maximum length";
     }
     const char *ptr = RSTRING_PTR(sv);
-    if (memchr(ptr, '\0', (size_t)len) != NULL) {
+    mkr_span_t view = mkr_span(ptr, (size_t)len);
+    size_t nul_at;
+    if (mkr_span_find(&view, '\0', &nul_at)) {
         return "string contains a NUL byte";
     }
-    VALUE u = rb_utf8_str_new(ptr, len);
-    if (!RTEST(rb_funcall(u, rb_intern("valid_encoding?"), 0))) {
+    if (!mkr_ruby_str_known_valid_utf8(sv)
+        && !mkr_utf8_valid((const unsigned char *)ptr, (size_t)len)) {
         return "string is not valid UTF-8";
     }
     out->value = sv;
     out->ptr   = ptr;
     out->len   = (size_t)len;
-    RB_GC_GUARD(u);
     return NULL;
 }
 
@@ -368,9 +423,7 @@ mkr_ruby_exception_message(VALUE exc, char *buf, size_t len)
     }
     if (!RB_TYPE_P(msg, T_STRING)) {
         snprintf(buf, len, "%s", "error");
-        RB_GC_GUARD(msg);
         return;
     }
     snprintf(buf, len, "%s", RSTRING_PTR(msg));
-    RB_GC_GUARD(msg);
 }

data/ext/makiri/core/mkr_alloc.c

@@ -1,5 +1,37 @@
 #include "mkr_alloc.h"
 
+#ifdef MKR_ALLOC_INJECT
+/* See mkr_alloc.h: the OOM sweep's failure injection. The counter counts
+ * ATTEMPTS (every consult), armed or not, so the harness can size its sweep
+ * from a disarmed baseline run; the countdown fails exactly one allocation
+ * and then disarms itself, modelling a single transient OOM per run. */
+static long long          mkr_inject_countdown = 0;  /* 0 = disarmed */
+static unsigned long long mkr_inject_attempts  = 0;
+
+void
+mkr_alloc_inject_arm(long long nth)
+{
+    mkr_inject_countdown = (nth > 0) ? nth : 0;
+    mkr_inject_attempts  = 0;
+}
+
+unsigned long long
+mkr_alloc_inject_calls(void)
+{
+    return mkr_inject_attempts;
+}
+
+int
+mkr_alloc_inject_should_fail(void)
+{
+    mkr_inject_attempts++;
+    if (mkr_inject_countdown > 0 && --mkr_inject_countdown == 0) {
+        return 1; /* fail this one allocation; now disarmed */
+    }
+    return 0;
+}
+#endif
+
 void *
 mkr_reallocarray(void *ptr, size_t count, size_t elem)
 {
@@ -11,6 +43,7 @@ mkr_reallocarray(void *ptr, size_t count, size_t elem)
     if (!mkr_size_mul(count, elem, &bytes)) {
         return NULL; /* overflow: leave ptr unchanged */
     }
+    if (MKR_ALLOC_INJECT_FAIL()) return NULL;
     return realloc(ptr, bytes);
 }
 
@@ -20,11 +53,14 @@ mkr_callocarray(size_t count, size_t elem)
     if (count == 0 || elem == 0) {
         return NULL;
     }
-    size_t bytes;
-    if (!mkr_size_mul(count, elem, &bytes)) {
+    /* 2-arg calloc is itself overflow-safe, but check explicitly so every core
+     * allocator fails the SAME way (deterministic NULL) rather than leaving the
+     * overflow case to calloc's implementation-defined behaviour. */
+    if (count > SIZE_MAX / elem) {
         return NULL; /* overflow */
     }
-    return calloc(count, elem); /* 2-arg calloc is itself overflow-safe */
+    if (MKR_ALLOC_INJECT_FAIL()) return NULL;
+    return calloc(count, elem);
 }
 
 char *
@@ -34,6 +70,7 @@ mkr_str_alloc(size_t n)
     if (!mkr_size_add(n, 1, &total)) {
         return NULL; /* n + 1 overflow */
     }
+    if (MKR_ALLOC_INJECT_FAIL()) return NULL;
     char *p = malloc(total);
     if (p == NULL) {
         return NULL;

data/ext/makiri/core/mkr_alloc.h

@@ -97,10 +97,33 @@ char *mkr_strdup(const char *s);
  * `cap *= 2; realloc(p, cap * sizeof(T))` pattern in one call. */
 mkr_status_t mkr_grow_reserve(void **ptr, size_t *cap, size_t need, size_t elem);
 
-/* Self-test of the overflow / allocation / buffer edge cases (incl. paths real
- * inputs cannot reach). Returns 0 on success, nonzero on the first failure.
- * Wired to a private Ruby method for the spec suite. */
-int mkr_core_selftest(void);
+/* --- allocation-failure injection (debug builds only) ------------------- */
+/*
+ * The OOM sweep harness (script/check_alloc_failures.rb, `rake oom`) verifies
+ * that every fail-closed OOM branch actually fails closed: it arms "the nth
+ * core allocation fails", runs a workload, and asserts the result is either a
+ * clean exception or byte-identical to the baseline - never truncated.
+ *
+ * Compiled in ONLY under -DMKR_ALLOC_INJECT (extconf: MAKIRI_ALLOC_INJECT=1);
+ * a release build carries no counter and no branch. Covers every core libc
+ * allocation site (mkr_alloc.c + mkr_buf.c - the funnel the direct_alloc lint
+ * forces all engine allocations through). Ruby's xmalloc family and Lexbor's
+ * internal allocations are out of scope (Ruby raises NoMemoryError itself;
+ * Lexbor is vendor code). Not thread-safe by design (the harness is
+ * single-threaded).
+ */
+#ifdef MKR_ALLOC_INJECT
+/* Arm: the nth subsequent core allocation (1-based) fails once, then the
+ * injection disarms itself. nth <= 0 disarms. Resets the call counter. */
+void mkr_alloc_inject_arm(long long nth);
+/* Core allocation attempts since the last arm (sizes the sweep). */
+unsigned long long mkr_alloc_inject_calls(void);
+/* Internal: consulted by each core libc allocation site. */
+int mkr_alloc_inject_should_fail(void);
+#define MKR_ALLOC_INJECT_FAIL() (mkr_alloc_inject_should_fail())
+#else
+#define MKR_ALLOC_INJECT_FAIL() 0
+#endif
 
 #ifdef __cplusplus
 }

data/ext/makiri/core/mkr_buf.c

@@ -30,7 +30,17 @@ mkr_buf_append(mkr_buf_t *b, const void *bytes, size_t n)
         if (!mkr_grow_capacity(b->cap, need_term, 1, &new_cap)) {
             return MKR_ERR_OOM;
         }
-        char *p = realloc(b->data, new_cap);
+        /* Geometric growth can overshoot to ~2x need_term; clamp the ALLOCATION
+         * to the same ceiling as the content (limit, plus one byte for the NUL),
+         * so cap never runs to ~2x MKR_BUF_HARD_MAX near the limit. Safe: this
+         * append already passed need <= limit, so need_term <= limit + 1 and the
+         * clamp never drops new_cap below what this append needs. (If limit + 1
+         * overflows - only a pathological -DMKR_BUF_HARD_MAX=SIZE_MAX - skip it.) */
+        size_t cap_ceiling;
+        if (mkr_size_add(limit, 1, &cap_ceiling) && new_cap > cap_ceiling) {
+            new_cap = cap_ceiling;
+        }
+        char *p = MKR_ALLOC_INJECT_FAIL() ? NULL : realloc(b->data, new_cap);
         if (p == NULL) {
             return MKR_ERR_OOM;
         }
@@ -62,7 +72,7 @@ mkr_buf_reserve(mkr_buf_t *b, size_t n)
     if (need_term <= b->cap) {
         return MKR_OK; /* already have room */
     }
-    char *p = realloc(b->data, need_term);
+    char *p = MKR_ALLOC_INJECT_FAIL() ? NULL : realloc(b->data, need_term);
     if (p == NULL) {
         return MKR_ERR_OOM;
     }
@@ -76,7 +86,7 @@ char *
 mkr_buf_steal(mkr_buf_t *b, size_t *out_len)
 {
     if (b->data == NULL) {
-        char *empty = malloc(1);
+        char *empty = MKR_ALLOC_INJECT_FAIL() ? NULL : malloc(1);
         if (empty == NULL) {
             return NULL;
         }

data/ext/makiri/core/mkr_buf.h

@@ -24,11 +24,15 @@ extern "C" {
  *                          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.
+ *   MKR_BUF_HARD_MAX       an absolute ceiling on a buffer's CONTENT length, even
+ *                          with an explicit max - the last-resort backstop. The
+ *                          ALLOCATION is bounded by it too: geometric growth is
+ *                          clamped so cap never exceeds HARD_MAX + 1 (the one NUL
+ *                          terminator byte), i.e. it does NOT overshoot to ~2x
+ *                          near the limit. 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
@@ -82,6 +86,77 @@ mkr_buf_free(mkr_buf_t *b)
     b->len = b->cap = 0;
 }
 
+/* ------------------------------------------------------------------------- */
+/* mkr_spanbuf_t - a bounded writer over a borrowed, fixed-capacity buffer    */
+/* ------------------------------------------------------------------------- */
+/*
+ * "span" = a non-owning view of a fixed-extent contiguous region; a spanbuf is
+ * the bounded *writer* over such a span. The complement to mkr_buf_t: where
+ * mkr_buf_t GROWS and OWNS its malloc storage, a spanbuf BORROWS a fixed buffer
+ * owned elsewhere (e.g. an arena cut) and never grows it.
+ *
+ * The name leads with "borrowed/fixed" deliberately, for safety: the
+ * fixed/bounded property is SELF-ENFORCED (a write past `cap` is refused, so
+ * misunderstanding it costs at most a truncation, caught by _finish), but the
+ * BORROWED property is the caller's responsibility - the type cannot stop you
+ * from free()ing `buf` or holding `finish()`'s pointer past the owner's
+ * lifetime, and getting that wrong is a use-after-free / double-free. So:
+ *   - never free() buf (the owner does, e.g. the arena is freed wholesale);
+ *   - finish()'s pointer is valid only while the backing storage lives.
+ *
+ * Bounds safety is BY CONSTRUCTION (the writer owns the cursor + check, not the
+ * caller's per-write guard): an over-long write is refused and latches `ok` to
+ * false (sticky). The caller's only duty is one check at the end (via _finish or
+ * the public `ok` field), failing closed rather than using a truncated buffer.
+ * This is the sanctioned way to hand-fill a raw region; see mkr_xml_arena_spanbuf
+ * for the arena adapter.
+ */
+typedef struct {
+    char  *buf;   /* borrowed; the owner keeps it alive - do NOT free. NULL => never ok. */
+    size_t cap;   /* capacity in bytes (fixed) */
+    size_t pos;   /* bytes written so far (always <= cap) */
+    bool   ok;    /* false once a write would overflow, or buf was NULL */
+} mkr_spanbuf_t;
+
+/* Wrap [buf, buf+cap) for bounded writing. buf == NULL yields a permanently
+ * not-ok writer (every write a no-op), so an upstream allocation failure flows
+ * straight through without a separate guard at each call site. */
+static inline mkr_spanbuf_t
+mkr_spanbuf(char *buf, size_t cap)
+{
+    return (mkr_spanbuf_t){ .buf = buf, .cap = cap, .pos = 0, .ok = (buf != NULL) };
+}
+
+/* Append one byte; refuse (latch ok=false) if it would exceed cap. */
+static inline void
+mkr_spanbuf_putc(mkr_spanbuf_t *b, char c)
+{
+    if (!b->ok) return;
+    if (b->pos >= b->cap) { b->ok = false; return; }
+    b->buf[b->pos++] = c;
+}
+
+/* Append n bytes; refuse (latch ok=false) if they would exceed cap. n == 0 is a
+ * no-op. pos <= cap is the invariant (a refused write never advances pos), so
+ * cap - pos cannot underflow; the pos > cap arm is belt-and-suspenders. */
+static inline void
+mkr_spanbuf_write(mkr_spanbuf_t *b, const void *src, size_t n)
+{
+    if (!b->ok || n == 0) return;
+    if (b->pos > b->cap || n > b->cap - b->pos) { b->ok = false; return; }
+    memcpy(b->buf + b->pos, src, n);
+    b->pos += n;
+}
+
+/* The filled prefix [buf, buf+pos), or NULL if any write was refused (or buf was
+ * NULL); on a non-NULL return the length is `b->pos`. Forces the caller through a
+ * single fail-closed check instead of trusting the writes individually. */
+static inline const char *
+mkr_spanbuf_finish(const mkr_spanbuf_t *b)
+{
+    return b->ok ? b->buf : NULL;
+}
+
 #ifdef __cplusplus
 }
 #endif