makiri 0.5.0 → 0.6.0

data/ext/makiri/glue/ruby_html_mutate.c

@@ -219,7 +219,7 @@ mkr_node_aset(VALUE self, VALUE rb_name, VALUE rb_value)
         rb_raise(mkr_eError, "cannot set an attribute on a non-element node");
     }
     mkr_ruby_borrowed_text_t nv = mkr_ruby_verified_text(rb_name, "attribute name");
-    mkr_ruby_borrowed_text_t vv = mkr_ruby_verified_text(rb_value, "attribute value");
+    mkr_ruby_borrowed_data_t vv = mkr_ruby_verified_data(rb_value, "attribute value");
     lxb_dom_attr_t *attr = lxb_dom_element_set_attribute(
         lxb_dom_interface_element(node),
         (const lxb_char_t *)nv.ptr, nv.len,
@@ -289,7 +289,7 @@ mkr_node_set_attribute_ns(VALUE self, VALUE rb_ns, VALUE rb_qname, VALUE rb_valu
     lxb_dom_element_t *el = lxb_dom_interface_element(node);
 
     mkr_ruby_borrowed_text_t qv = mkr_ruby_verified_text(rb_qname, "attribute qualified name");
-    mkr_ruby_borrowed_text_t vv = mkr_ruby_verified_text(rb_value, "attribute value");
+    mkr_ruby_borrowed_data_t vv = mkr_ruby_verified_data(rb_value, "attribute value");
 
     mkr_ruby_borrowed_text_t nv = {0};
     bool have_ns = false;
@@ -442,7 +442,7 @@ static VALUE
 mkr_node_set_content(VALUE self, VALUE rb_text)
 {
     lxb_dom_node_t *node = mkr_node_unwrap_mutable(self);
-    mkr_ruby_borrowed_text_t tv = mkr_ruby_verified_text(rb_text, "node content");
+    mkr_ruby_borrowed_data_t tv = mkr_ruby_verified_data(rb_text, "node content");
     lxb_status_t st = lxb_dom_node_text_content_set(
         node, (const lxb_char_t *)tv.ptr, tv.len);
     RB_GC_GUARD(tv.value);
@@ -584,7 +584,7 @@ static VALUE
 mkr_doc_create_text_node(VALUE self, VALUE rb_text)
 {
     lxb_dom_document_t *doc = mkr_html_doc_unwrap(self);
-    mkr_ruby_borrowed_text_t tv = mkr_ruby_verified_text(rb_text, "text content");
+    mkr_ruby_borrowed_data_t tv = mkr_ruby_verified_data(rb_text, "text content");
     lxb_dom_text_t *t = lxb_dom_document_create_text_node(
         doc, (const lxb_char_t *)tv.ptr, tv.len);
     RB_GC_GUARD(tv.value);
@@ -598,7 +598,7 @@ static VALUE
 mkr_doc_create_comment(VALUE self, VALUE rb_text)
 {
     lxb_dom_document_t *doc = mkr_html_doc_unwrap(self);
-    mkr_ruby_borrowed_text_t tv = mkr_ruby_verified_text(rb_text, "comment content");
+    mkr_ruby_borrowed_data_t tv = mkr_ruby_verified_data(rb_text, "comment content");
     lxb_dom_comment_t *c = lxb_dom_document_create_comment(
         doc, (const lxb_char_t *)tv.ptr, tv.len);
     RB_GC_GUARD(tv.value);

data/ext/makiri/xpath/mkr_xpath.c

@@ -258,6 +258,18 @@ mkr_limit_ast_node(mkr_xpath_limits_t *L, mkr_xpath_error_t *err)
   return 0;
 }
 
+/*
+ * THE evaluator progress gate. This is the single primitive that bounds runtime
+ * work: every loop in the engine whose trip count is input-derived charges ONE
+ * tick per iteration through here (the axis walk per visited node, the M*N
+ * compare per pair, the index-bucket scan per element, eval_node per AST node).
+ * One uniform rule - "input-bounded loop => one eval_op per step" - so checking
+ * the DoS bound is local: confirm each such loop calls this. Kept deliberately
+ * uniform (no bulk/up-front variant): a bulk charge would only suit
+ * run-to-completion loops and would wrongly reject an early-exiting query if
+ * misapplied, trading one foot-gun-free rule for a conditional one. Overrun is
+ * fail-closed (MKR_XPATH_ERR_LIMIT), never a truncated result.
+ */
 int
 mkr_limit_eval_op(mkr_xpath_limits_t *L, mkr_xpath_error_t *err)
 {

data/ext/makiri/xpath/mkr_xpath_eval_body.h

@@ -1509,14 +1509,15 @@ eval_fncall(mkr_xpath_context_t *ctx, const mkr_node_t *n,
             mkr_val_t *out, mkr_xpath_error_t *err)
 {
   const char *ns_uri = NULL;
+  size_t ns_uri_len = 0;
   if (n->u.fncall.prefix.ptr) {
-    ns_uri = mkr_ctx_lookup_ns(ctx, n->u.fncall.prefix.ptr, n->u.fncall.prefix.len, NULL);
+    ns_uri = mkr_ctx_lookup_ns(ctx, n->u.fncall.prefix.ptr, n->u.fncall.prefix.len, &ns_uri_len);
     if (ns_uri == NULL) {
       mkr_err_setf(err, MKR_XPATH_ERR_RUNTIME, "unknown namespace prefix '%s'", n->u.fncall.prefix.ptr);
       return -1;
     }
   }
-  mkr_func_impl_t fn = mkr_lookup_function(ns_uri, n->u.fncall.name.ptr);
+  mkr_func_impl_t fn = mkr_lookup_function(ns_uri, ns_uri_len, n->u.fncall.name.ptr, n->u.fncall.name.len);
 
   /* Evaluate arguments once and reuse for either path. */
   mkr_val_t *args = NULL;
@@ -1666,22 +1667,30 @@ eval_node(mkr_xpath_context_t *ctx, const mkr_node_t *n,
           mkr_val_t *out, mkr_xpath_error_t *err)
 {
   /* Budget + recursion bookkeeping. Every AST node visit counts as one
-   * eval op; recursion depth tracks how deep we are in expression
-   * nodes so we abort cleanly on pathological inputs. */
+   * eval op; recursion depth tracks how deep we are in expression nodes
+   * so we abort cleanly on pathological inputs.
+   *
+   * eval_node is the engine's ONLY recursive function, so "AST-driven
+   * recursion is bounded" reduces entirely to this one enter/leave pair:
+   * charge one op + one recursion level on entry, release the level at the
+   * SINGLE exit below. Keeping eval_node single-exit is what makes that
+   * balance locally verifiable - there is no path from the enter here to a
+   * return that skips the mkr_limit_recurse_leave. Do not add an early
+   * `return` between here and the leave; set `rc` and fall through. */
   mkr_xpath_limits_t *L = mkr_ctx_limits(ctx);
   if (mkr_limit_eval_op(L, err) != 0) return -1;
   if (mkr_limit_recurse_enter(L, err) != 0) return -1;
 
+  int rc;
+
   /* Hoisting fast path: a CI subtree that's already been computed in
    * this evaluate is returned as a clone. The clone keeps ownership
    * semantics clean - mkr_val_clear on either copy is safe. */
   if (n->is_context_independent && n->memoized) {
-    int rc = mkr_val_clone(&n->memo_value, out, err);
-    mkr_limit_recurse_leave(L);
-    return rc;
+    rc = mkr_val_clone(&n->memo_value, out, err);
+    goto done; /* single exit: the recurse_leave below still runs */
   }
 
-  int rc;
   switch (n->kind) {
   case MKR_NK_LITERAL_STR: {
     mkr_owned_text_t text;
@@ -1772,6 +1781,7 @@ eval_node(mkr_xpath_context_t *ctx, const mkr_node_t *n,
     }
   }
 
+done:
   mkr_limit_recurse_leave(L);
   return rc;
 }

data/ext/makiri/xpath/mkr_xpath_funcs_body.h

@@ -329,13 +329,17 @@ fn_nokogiri_local_name_is(mkr_xpath_context_t *ctx, const mkr_focus_t *focus,
 
 typedef struct {
   const char     *name;
-  mkr_func_impl_t  fn;
+  size_t          name_len;
+  mkr_func_impl_t fn;
 } fn_entry_t;
 
+#define FN_ENTRY(name, fn) { (name), sizeof(name) - 1, (fn) }
+#define FN_ENTRY_END       { NULL, 0, NULL }
+
 static const fn_entry_t fn_table_nokogiri_builtin[] = {
-  { "css-class",     fn_nokogiri_css_class     },
-  { "local-name-is", fn_nokogiri_local_name_is },
-  { NULL,            NULL                      },
+  FN_ENTRY("css-class",     fn_nokogiri_css_class),
+  FN_ENTRY("local-name-is", fn_nokogiri_local_name_is),
+  FN_ENTRY_END,
 };
 
 #ifdef MKR_HOST_XML
@@ -1047,58 +1051,61 @@ fn_lang(mkr_xpath_context_t *ctx, const mkr_focus_t *focus,
 
 static const fn_entry_t fn_table[] = {
   /* node-set */
-  { "last",             fn_last             },
-  { "position",         fn_position         },
-  { "count",            fn_count            },
-  { "id",               fn_id               },
-  { "local-name",       fn_local_name       },
-  { "namespace-uri",    fn_namespace_uri    },
-  { "name",             fn_name             },
+  FN_ENTRY("last",             fn_last),
+  FN_ENTRY("position",         fn_position),
+  FN_ENTRY("count",            fn_count),
+  FN_ENTRY("id",               fn_id),
+  FN_ENTRY("local-name",       fn_local_name),
+  FN_ENTRY("namespace-uri",    fn_namespace_uri),
+  FN_ENTRY("name",             fn_name),
   /* string */
-  { "string",           fn_string           },
-  { "concat",           fn_concat           },
-  { "starts-with",      fn_starts_with      },
-  { "contains",         fn_contains         },
-  { "substring-before", fn_substring_before },
-  { "substring-after",  fn_substring_after  },
-  { "substring",        fn_substring        },
-  { "string-length",    fn_string_length    },
-  { "normalize-space",  fn_normalize_space  },
-  { "translate",        fn_translate        },
+  FN_ENTRY("string",           fn_string),
+  FN_ENTRY("concat",           fn_concat),
+  FN_ENTRY("starts-with",      fn_starts_with),
+  FN_ENTRY("contains",         fn_contains),
+  FN_ENTRY("substring-before", fn_substring_before),
+  FN_ENTRY("substring-after",  fn_substring_after),
+  FN_ENTRY("substring",        fn_substring),
+  FN_ENTRY("string-length",    fn_string_length),
+  FN_ENTRY("normalize-space",  fn_normalize_space),
+  FN_ENTRY("translate",        fn_translate),
   /* boolean */
-  { "not",              fn_not              },
-  { "true",             fn_true             },
-  { "false",            fn_false            },
-  { "boolean",          fn_boolean          },
-  { "lang",             fn_lang             },
+  FN_ENTRY("not",              fn_not),
+  FN_ENTRY("true",             fn_true),
+  FN_ENTRY("false",            fn_false),
+  FN_ENTRY("boolean",          fn_boolean),
+  FN_ENTRY("lang",             fn_lang),
   /* number */
-  { "number",           fn_number           },
-  { "sum",              fn_sum              },
-  { "floor",            fn_floor            },
-  { "ceiling",          fn_ceiling          },
-  { "round",            fn_round            },
+  FN_ENTRY("number",           fn_number),
+  FN_ENTRY("sum",              fn_sum),
+  FN_ENTRY("floor",            fn_floor),
+  FN_ENTRY("ceiling",          fn_ceiling),
+  FN_ENTRY("round",            fn_round),
 #ifdef MKR_HOST_XML
   /* CSS-only internal hooks for untyped :*-of-type; the \x01-prefixed names are
    * unreachable from a user XPath expression (the lexer cannot produce them). */
-  { MKR_FN_OF_TYPE_POS,      fn_xml_of_type_pos      },
-  { MKR_FN_OF_TYPE_POS_LAST, fn_xml_of_type_pos_last },
+  FN_ENTRY(MKR_FN_OF_TYPE_POS,      fn_xml_of_type_pos),
+  FN_ENTRY(MKR_FN_OF_TYPE_POS_LAST, fn_xml_of_type_pos_last),
 #endif
-  { NULL,               NULL                },
+  FN_ENTRY_END,
 };
 
 /* File-static: the function table is engine-internal. eval_fncall (later in the
  * merged engine TU) resolves through it; nothing outside the engine does. */
 static mkr_func_impl_t
-mkr_lookup_function(const char *ns_uri, const char *local_name)
+mkr_lookup_function(const char *ns_uri, size_t ns_uri_len,
+                    const char *local_name, size_t local_name_len)
 {
   if (local_name == NULL) return NULL;
   if (ns_uri != NULL) {
     /* Nokogiri-compatible builtins live in MKR_NS_NOKOGIRI_BUILTIN_URI.
      * Other registered namespaces resolve to user-defined functions -
      * not yet implemented (Phase 3 TODO: custom function registry). */
-    if (strcmp(ns_uri, MKR_NS_NOKOGIRI_BUILTIN_URI) == 0) {
+    if (mkr_bytes_eq(ns_uri, ns_uri_len, MKR_NS_NOKOGIRI_BUILTIN_URI,
+                     sizeof(MKR_NS_NOKOGIRI_BUILTIN_URI) - 1)) {
       for (size_t i = 0; fn_table_nokogiri_builtin[i].name; ++i) {
-        if (strcmp(fn_table_nokogiri_builtin[i].name, local_name) == 0) {
+        if (mkr_bytes_eq(fn_table_nokogiri_builtin[i].name, fn_table_nokogiri_builtin[i].name_len,
+                         local_name, local_name_len)) {
           return fn_table_nokogiri_builtin[i].fn;
         }
       }
@@ -1107,7 +1114,9 @@ mkr_lookup_function(const char *ns_uri, const char *local_name)
   }
   /* Default namespace - XPath 1.0 standard library. */
   for (size_t i = 0; fn_table[i].name; ++i) {
-    if (strcmp(fn_table[i].name, local_name) == 0) return fn_table[i].fn;
+    if (mkr_bytes_eq(fn_table[i].name, fn_table[i].name_len, local_name, local_name_len)) {
+      return fn_table[i].fn;
+    }
   }
   return NULL;
 }

data/ext/makiri/xpath/mkr_xpath_xml_selftest.c

@@ -9,12 +9,11 @@
 #include "mkr_xpath_internal.h"
 #include "../xml/mkr_xml.h"
 
-/* Evaluate +expr+ (length +elen+) against the XML +doc+ and return the resulting
- * node-set count, or SIZE_MAX on any error / non-node-set. Registers prefix
- * "d" -> "urn:d". Lengths come from sizeof on the compile-time literals (no
- * strlen - this file is outside the clint core+bridge allowlist). */
+/* Evaluate +expr+ (a verified-text token over a compile-time literal) against
+ * the XML +doc+ and return the resulting node-set count, or SIZE_MAX on any
+ * error / non-node-set. Registers prefix "d" -> "urn:d". */
 static size_t
-xml_count(mkr_xml_doc_t *doc, const char *expr, size_t elen)
+xml_count(mkr_xml_doc_t *doc, mkr_verified_text_t expr)
 {
     /* The context's "document" and root context node are both the DOCUMENT node
      * (the XPath "/" root); for XML the engine's namespace services ignore the
@@ -24,13 +23,11 @@ xml_count(mkr_xml_doc_t *doc, const char *expr, size_t elen)
     if (ctx == NULL) return (size_t)-1;
     mkr_xpath_set_engine_kind(ctx, 1);
 
-    mkr_verified_text_t dp = { "d", 1 }, du = { "urn:d", 5 };
-    mkr_xpath_register_ns(ctx, dp, du);
+    mkr_xpath_register_ns(ctx, mkr_verified_text_lit("d"), mkr_verified_text_lit("urn:d"));
 
     mkr_xpath_limits_t *L = mkr_ctx_limits(ctx);
     mkr_xpath_error_t err = {0};
-    mkr_verified_text_t e = { expr, elen };
-    mkr_node_t *ast = mkr_parse(e, L, &err);
+    mkr_node_t *ast = mkr_parse(expr, L, &err);
     size_t out = (size_t)-1;
     if (ast != NULL) {
         mkr_xpath_value_t v = {0};
@@ -57,7 +54,7 @@ mkr_xml_xpath_selftest(void)
     if (doc == NULL) return ++idx;                                  /* 1 */
 
 #define CHECK(expr, want)                                                     \
-    do { idx++; if (xml_count(doc, (expr), sizeof(expr) - 1) != (size_t)(want)) { \
+    do { idx++; if (xml_count(doc, mkr_verified_text_lit(expr)) != (size_t)(want)) { \
              mkr_xml_doc_destroy(doc); return idx; } } while (0)
 
     CHECK("//b", 2);          /* 1: unprefixed -> no-namespace only (excludes d:b) */

data/lib/makiri/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Makiri
-  VERSION = "0.5.0"
+  VERSION = "0.6.0"
 end

data/script/check_c_safety.rb

@@ -83,6 +83,17 @@ RULES = [
     # buffer unnoticed.
     regex: /\(\s*mkr_verified_text_t\s*\)\s*\{|\bmkr_verified_text_t\s+\w+\s*=\s*\{/
   ),
+  Rule.new(
+    id: "borrowed_text_forge",
+    message: "mkr_borrowed_text_t must be built via mkr_borrowed_text()/mkr_borrowed_text_lit()/mkr_borrowed_text_from_*, not a raw struct literal",
+    # Same two forge shapes as verified_text_forge. Not a capability guard (a raw
+    # literal is semantically identical to the constructor); it funnels the
+    # "asserted-valid borrowed slice" through the single named constructor so the
+    # assertion stays auditable, matching mkr_text.h's stated intent ("replacing
+    # scattered casts"). core/** - where the constructors live - is globally
+    # ignore-pathed, so the definitions in mkr_text.h are exempt automatically.
+    regex: /\(\s*mkr_borrowed_text_t\s*\)\s*\{|\bmkr_borrowed_text_t\s+\w+\s*=\s*\{/
+  ),
   # --- HTML/XML representation boundary (see docs/html_xml_boundary_hardening) ---
   # These symbols assume one DOM representation; using them outside their
   # representation-correct / kind-checked home is how shared glue (XPath, NodeSet,

data/script/check_c_safety_allowlist.yml

@@ -99,19 +99,16 @@ ignore_paths:
 
 # --- parser-TU reader discipline (raw_scan_call / raw_cursor_member) ---
 allowlist:
-  - path: ext/makiri/xpath/mkr_xpath_funcs_body.h
-    rule: raw_scan_call
-    max: 3
-    reason: "mkr_lookup_function's three strcmp over compile-time function-name tables: both sides are NUL-terminated (table literals / owned AST text), and the lookup signature takes bare const char* from the evaluator."
-
-  # --- verified_text_forge: the two Ruby-free test entry points. Neither can use
-  #     mkr_verified_text_from_view (bridge = Ruby boundary), so each mints the
-  #     token itself and must supply the contract by construction. ---
-  - path: ext/makiri/xpath/mkr_xpath_xml_selftest.c
-    rule: verified_text_forge
-    max: 2
-    reason: "Selftest expressions are compile-time string literals: NUL-terminated, NUL-free, valid UTF-8 by construction."
+  # --- verified_text_forge: the Ruby-free test entry points that mint over a
+  #     runtime buffer (not a compile-time literal, which uses
+  #     mkr_verified_text_lit). Neither can use mkr_verified_text_from_view
+  #     (bridge = Ruby boundary), so each mints itself and must supply the
+  #     contract by construction. ---
   - path: ext/makiri/fuzz/xpath_fuzz.c
     rule: verified_text_forge
     max: 1
     reason: "The libFuzzer harness mints over an owned mkr_strndup copy, which supplies NUL-termination and no-interior-NUL; UTF-8 validity is deliberately left to the lexer's strict decoder (its rejection path is fuzz-target behavior)."
+  - path: ext/makiri/fuzz/xml_xpath_fuzz.c
+    rule: verified_text_forge
+    max: 1
+    reason: "The expression mint is over an owned mkr_strndup copy, which supplies NUL-termination and no-interior-NUL; UTF-8 validity is pre-checked (the harness filters invalid UTF-8 before parsing). Mirrors xpath_fuzz.c."

data/suppressions/ruby.supp

@@ -125,6 +125,28 @@
   fun:mark_roots
 }
 
+# ---- incremental GC write barrier: uninitialised-value reads ----
+# An allocating Ruby C-API call from one of our cfuncs (e.g. rb_str_subseq in
+# mkr_xml_decode_input) fires the incremental-GC write barrier synchronously;
+# `gc_writebarrier_incremental` then reads an object's not-yet-written RVALUE
+# flag word via `RVALUE_BLACK_P` - the same uninit-flag false positive as the GC
+# drivers above, but reached through the barrier rather than a mark/sweep cycle,
+# so the driver-anchored entries miss it. Our code never touches RVALUE flags;
+# it only calls the allocating API, so anchoring on the barrier cannot mask a
+# real uninit read of ours.
+{
+  ruby-gc-cond-writebarrier_incremental
+  Memcheck:Cond
+  ...
+  fun:gc_writebarrier_incremental
+}
+{
+  ruby-gc-value8-writebarrier_incremental
+  Memcheck:Value8
+  ...
+  fun:gc_writebarrier_incremental
+}
+
 # ---- Ruby VM internal caches that are never freed before exit ----
 # The global constant-cache / inline method-cache id_table is allocated lazily
 # on method lookup and lives for the life of the VM, so RUBY_FREE_AT_EXIT still

data/verify/Makefile

@@ -0,0 +1,237 @@
+# Verification build for the XML + XPath carve-out.
+#
+# Fully separate from the gem's extconf build: nothing here touches ext/'s
+# Makefile or object files, and no Ruby VM or Lexbor library is linked (the
+# only Lexbor pieces are UNMODIFIED vendor encoding sources - the vanilla
+# constraint is about not patching, not about not compiling).
+#
+# Targets:
+#   make smoke      - build every CBMC harness as a plain executable and run it
+#                     (the link check: CBMC treats a missing function body as a
+#                     nondet return, so only the linker catches a wrong source list)
+#   make selftest   - build + run the carve-out selftest (XML parse + XPath eval,
+#                     no Ruby, no Lexbor lib)
+#   make cbmc       - the proven set (alloc/utf8/utf8-chain/utf8-words/span/
+#                     spanbuf/buf/hash/xml-chars/xpath-number; ~8 min total)
+#   make cbmc-deep  - the experimental set (xpath-lex/xpath-parse/xml-parse/
+#                     xml-expand).
+#                     These do NOT converge in practical time on current
+#                     bit-level solvers (measured: >10 min each even at 3-4
+#                     byte inputs, with MiniSat, kissat and Bitwuzla alike);
+#                     kept as tuning knobs for future solver/harness work,
+#                     e.g. make cbmc-xpath-parse XPATH_EXPR_MAX=4 XPATH_UNWIND=12
+#
+# Native libFuzzer targets live in ext/makiri/fuzz/ (their own Makefile + the
+# nightly libfuzzer.yml workflow), not here - this directory is proofs only.
+
+ROOT := ..
+EXT  := $(ROOT)/ext/makiri
+LXB  := $(ROOT)/vendor/lexbor/source
+
+CC     ?= cc
+CBMC   ?= cbmc
+CFLAGS ?= -O1 -g -Wall -Wextra
+# fmod & co. need an explicit -lm on Linux (folded into libc on macOS).
+LDLIBS ?= -lm
+INC    := -I $(EXT) -I $(LXB) -I .
+
+CORE_SRC  := $(EXT)/core/mkr_alloc.c $(EXT)/core/mkr_buf.c \
+             $(EXT)/core/mkr_core.c $(EXT)/core/mkr_utf8.c
+XML_SRC   := $(EXT)/xml/mkr_xml_chars.c $(EXT)/xml/mkr_xml_index.c \
+             $(EXT)/xml/mkr_xml_mutate.c $(EXT)/xml/mkr_xml_node.c \
+             $(EXT)/xml/mkr_xml_tree.c
+# Lexer/parser/number + shared support: what mkr_parse reaches.
+XPATH_FRONT_SRC := $(EXT)/xpath/mkr_xpath_lex.c $(EXT)/xpath/mkr_xpath_parse.c \
+                   $(EXT)/xpath/mkr_xpath_shared.c $(EXT)/xpath/mkr_xpath_number.c
+# The full engine: dispatcher + the XML monomorphization (HTML side is stub.c).
+XPATH_FULL_SRC  := $(XPATH_FRONT_SRC) $(EXT)/xpath/mkr_xpath.c \
+                   $(EXT)/xpath/mkr_xpath_engine_xml.c
+# Unmodified vendor sources for lxb_encoding_decode_valid_utf_8_single.
+LXB_ENC_SRC := $(LXB)/lexbor/encoding/decode.c $(LXB)/lexbor/encoding/multi_res.c \
+               $(LXB)/lexbor/encoding/range_res.c $(LXB)/lexbor/encoding/single_res.c
+
+ENGINE_SRC := $(CORE_SRC) $(XML_SRC) $(XPATH_FULL_SRC) $(LXB_ENC_SRC) stub.c
+
+BUILD := build
+
+# ---------------------------------------------------------------- smoke + selftest
+
+HARNESSES := alloc utf8 utf8-chain utf8-words span spanbuf buf hash xml-chars xml-expand xpath-number xpath-lex xpath-parse xml-parse
+
+smoke: $(HARNESSES:%=$(BUILD)/harness-%)
+	@for h in $^; do echo "== $$h"; $$h || exit 1; done
+	@echo "smoke: all harnesses link and run"
+
+$(BUILD)/harness-alloc: harness_alloc.c $(EXT)/core/mkr_alloc.c | $(BUILD)
+	$(CC) $(CFLAGS) $(INC) $^ -o $@ $(LDLIBS)
+$(BUILD)/harness-utf8: harness_utf8.c $(EXT)/core/mkr_utf8.c | $(BUILD)
+	$(CC) $(CFLAGS) $(INC) $^ -o $@ $(LDLIBS)
+$(BUILD)/harness-utf8-chain: harness_utf8_chain.c $(EXT)/core/mkr_utf8.c | $(BUILD)
+	$(CC) $(CFLAGS) $(INC) $^ -o $@ $(LDLIBS)
+$(BUILD)/harness-utf8-words: harness_utf8_words.c $(EXT)/core/mkr_utf8.c | $(BUILD)
+	$(CC) $(CFLAGS) $(INC) $^ -o $@ $(LDLIBS)
+$(BUILD)/harness-span: harness_span.c | $(BUILD)
+	$(CC) $(CFLAGS) $(INC) $^ -o $@ $(LDLIBS)
+$(BUILD)/harness-spanbuf: harness_spanbuf.c | $(BUILD)
+	$(CC) $(CFLAGS) $(INC) $^ -o $@ $(LDLIBS)
+$(BUILD)/harness-buf: harness_buf.c $(EXT)/core/mkr_buf.c $(EXT)/core/mkr_alloc.c | $(BUILD)
+	$(CC) $(CFLAGS) $(INC) $^ -o $@ $(LDLIBS)
+$(BUILD)/harness-hash: harness_hash.c | $(BUILD)
+	$(CC) $(CFLAGS) $(INC) $^ -o $@ $(LDLIBS)
+$(BUILD)/harness-xpath-number: harness_xpath_number.c $(EXT)/xpath/mkr_xpath_number.c $(EXT)/core/mkr_alloc.c | $(BUILD)
+	$(CC) $(CFLAGS) $(INC) $^ -o $@ $(LDLIBS)
+# mkr_parse's limit checks + limits_init_defaults live in mkr_xpath.c (the
+# dispatcher), which references both engine instances - so the smoke link
+# takes the full engine (stub.c supplies the HTML side).
+$(BUILD)/harness-xpath-parse: harness_xpath_parse.c $(ENGINE_SRC) | $(BUILD)
+	$(CC) $(CFLAGS) $(INC) $^ -o $@ $(LDLIBS)
+$(BUILD)/harness-xpath-lex: harness_xpath_lex.c $(ENGINE_SRC) | $(BUILD)
+	$(CC) $(CFLAGS) $(INC) $^ -o $@ $(LDLIBS)
+$(BUILD)/harness-xml-parse: harness_xml_parse.c $(XML_SRC) $(CORE_SRC) | $(BUILD)
+	$(CC) $(CFLAGS) $(INC) $^ -o $@ $(LDLIBS)
+$(BUILD)/harness-xml-chars: harness_xml_chars.c $(XML_SRC) $(CORE_SRC) | $(BUILD)
+	$(CC) $(CFLAGS) $(INC) $^ -o $@ $(LDLIBS)
+$(BUILD)/harness-xml-expand: harness_xml_expand.c $(XML_SRC) $(CORE_SRC) | $(BUILD)
+	$(CC) $(CFLAGS) $(INC) $^ -o $@ $(LDLIBS)
+
+selftest: $(BUILD)/selftest
+	$(BUILD)/selftest
+
+$(BUILD)/selftest: selftest_main.c $(ENGINE_SRC) $(EXT)/xpath/mkr_xpath_xml_selftest.c | $(BUILD)
+	$(CC) $(CFLAGS) $(INC) $^ -o $@ $(LDLIBS)
+
+$(BUILD):
+	mkdir -p $(BUILD)
+
+# ---------------------------------------------------------------- CBMC proofs
+#
+# Every proof gets --bounds-check --pointer-check (memory safety) and
+# --signed-overflow-check (UB); --unsigned-overflow-check is added ONLY where
+# wrapping would be a bug (the size arithmetic) - the UTF-8 validator's
+# word-at-a-time scan and hash-style code wrap on purpose, and unsigned wrap
+# is defined C. --malloc-may-fail --malloc-fail-null verifies the fail-closed
+# OOM branches. Unwind bounds are per-harness knobs; --unwinding-assertions
+# turns "too small a bound" into a failure instead of a silent partial proof.
+
+CBMC_MEM := --bounds-check --pointer-check --signed-overflow-check \
+            --div-by-zero-check --unwinding-assertions --object-bits 12
+CBMC_OOM := --malloc-may-fail --malloc-fail-null
+# libc bodies CBMC lacks on this platform (see the file's comment).
+CBMC_MODELS := cbmc_models.c
+
+# mkr_grow_capacity doubles from 8, so <= ~60 iterations before the cap check.
+ALLOC_UNWIND ?= 64
+cbmc-alloc:
+	$(CBMC) harness_alloc.c $(CBMC_MODELS) $(EXT)/core/mkr_alloc.c $(INC) \
+	  $(CBMC_MEM) $(CBMC_OOM) --unsigned-overflow-check --conversion-check \
+	  --unwind $(ALLOC_UNWIND)
+
+UTF8_UNWIND ?= 12
+cbmc-utf8:
+	$(CBMC) harness_utf8.c $(CBMC_MODELS) $(EXT)/core/mkr_utf8.c $(INC) \
+	  $(CBMC_MEM) --unwind $(UTF8_UNWIND)
+
+# Chain length and unwind grow together (unwind must exceed the byte count;
+# see the harness header for the measured length/time trade-off).
+UTF8_CHAIN_MAX    ?= 12
+UTF8_CHAIN_UNWIND ?= 16
+cbmc-utf8-chain:
+	$(CBMC) harness_utf8_chain.c $(CBMC_MODELS) $(EXT)/core/mkr_utf8.c $(INC) \
+	  -DVERIFY_UTF8_CHAIN_MAX=$(UTF8_CHAIN_MAX) \
+	  $(CBMC_MEM) --unwind $(UTF8_CHAIN_UNWIND)
+
+cbmc-utf8-words:
+	$(CBMC) harness_utf8_words.c $(CBMC_MODELS) $(EXT)/core/mkr_utf8.c $(INC) \
+	  $(CBMC_MEM) --unwind 20
+
+SPAN_UNWIND ?= 12
+cbmc-span:
+	$(CBMC) harness_span.c $(CBMC_MODELS) $(INC) \
+	  $(CBMC_MEM) --unwind $(SPAN_UNWIND)
+
+cbmc-spanbuf:
+	$(CBMC) harness_spanbuf.c $(CBMC_MODELS) $(INC) \
+	  $(CBMC_MEM) --unwind $(SPAN_UNWIND)
+
+cbmc-buf:
+	$(CBMC) harness_buf.c $(CBMC_MODELS) $(EXT)/core/mkr_buf.c $(EXT)/core/mkr_alloc.c $(INC) \
+	  $(CBMC_MEM) $(CBMC_OOM) --unwind 16
+
+# The sizer only shifts, so unlike the mul/div guards this closes at full
+# width; the loop runs at most one step per size_t bit.
+HASH_UNWIND ?= 66
+cbmc-hash:
+	$(CBMC) harness_hash.c $(CBMC_MODELS) $(INC) \
+	  $(CBMC_MEM) --unwind $(HASH_UNWIND)
+
+# XML character classes: predicate inclusions over all code points + the
+# validators cross-checked against the independent UTF-8 validator. CBMC only
+# needs mkr_xml_chars.c + mkr_utf8.c (the other xml/ entries the header
+# declares stay bodyless - unreachable from this harness).
+XML_CHARS_UNWIND ?= 12
+cbmc-xml-chars:
+	$(CBMC) harness_xml_chars.c $(CBMC_MODELS) $(EXT)/xml/mkr_xml_chars.c $(EXT)/core/mkr_utf8.c $(INC) \
+	  $(CBMC_MEM) --unwind $(XML_CHARS_UNWIND)
+
+# The XPath Number scanner/converter. The cbmc_models.c strtod ("conversion
+# unavailable") steers from_extent down its own fallback chain - the isolating
+# reparse and the hand assembly, i.e. exactly our code - on every input; the
+# libc-success path is trusted, not verified (like memcpy).
+cbmc-xpath-number:
+	$(CBMC) harness_xpath_number.c $(CBMC_MODELS) $(EXT)/xpath/mkr_xpath_number.c $(EXT)/core/mkr_alloc.c $(INC) \
+	  $(CBMC_MEM) $(CBMC_OOM) --unwind 12
+
+cbmc: cbmc-alloc cbmc-utf8 cbmc-utf8-chain cbmc-utf8-words cbmc-span cbmc-spanbuf cbmc-buf cbmc-hash cbmc-xml-chars cbmc-xpath-number
+	@echo "cbmc: all proofs passed"
+
+# ------------------------------------------------- experimental (cbmc-deep)
+#
+# The whole-entry parser/lexer proofs below are formulated and smoke-checked,
+# but no current solver closes them in practical time (see the header). CBMC
+# gets mkr_xpath.c for the limit checks but NOT the engine instances or the
+# vendor encoding tables (nothing there is reachable from mkr_parse; the eval
+# entries mkr_xpath.c references stay bodyless - unreachable from these
+# harnesses). Expression/input length and unwind grow together.
+
+XPATH_EXPR_MAX ?= 6
+XPATH_UNWIND   ?= 16
+cbmc-xpath-lex:
+	$(CBMC) harness_xpath_lex.c $(CBMC_MODELS) $(XPATH_FRONT_SRC) $(EXT)/xpath/mkr_xpath.c $(CORE_SRC) $(INC) \
+	  -DVERIFY_XPATH_EXPR_MAX=$(XPATH_EXPR_MAX) \
+	  $(CBMC_MEM) --unwind $(XPATH_UNWIND)
+
+cbmc-xpath-parse:
+	$(CBMC) harness_xpath_parse.c $(CBMC_MODELS) $(XPATH_FRONT_SRC) $(EXT)/xpath/mkr_xpath.c $(CORE_SRC) $(INC) \
+	  -DVERIFY_XPATH_EXPR_MAX=$(XPATH_EXPR_MAX) \
+	  $(CBMC_MEM) $(CBMC_OOM) --unwind $(XPATH_UNWIND)
+
+XML_INPUT_MAX ?= 6
+XML_UNWIND    ?= 16
+cbmc-xml-parse:
+	$(CBMC) harness_xml_parse.c $(CBMC_MODELS) $(XML_SRC) $(CORE_SRC) $(INC) \
+	  -DVERIFY_XML_INPUT_MAX=$(XML_INPUT_MAX) \
+	  $(CBMC_MEM) $(CBMC_OOM) --unwind $(XML_UNWIND)
+
+# Entity/char-ref expansion over nondet valid-UTF-8 input (the document it
+# writes into is parsed from a concrete 4-byte input, so only the expansion
+# input is nondet). Does not converge: 7-byte input, --unwind 12, still in
+# BMC when the 420 s alarm killed it (measured; higher unwinds are strictly
+# larger). No $(CBMC_OOM): a NULL doc is treated as early-exit, OOM injection
+# is not what this harness is about.
+# Also measured: 5-byte input still did not converge in 6 min - the cost is
+# the whole-parser+arena state behind the doc handle, not the input length.
+XML_EXPAND_MAX    ?= 7
+XML_EXPAND_UNWIND ?= 12
+cbmc-xml-expand:
+	$(CBMC) harness_xml_expand.c $(CBMC_MODELS) $(XML_SRC) $(CORE_SRC) $(INC) \
+	  -DVERIFY_XML_EXPAND_MAX=$(XML_EXPAND_MAX) \
+	  $(CBMC_MEM) --unwind $(XML_EXPAND_UNWIND)
+
+cbmc-deep: cbmc-xpath-lex cbmc-xpath-parse cbmc-xml-parse cbmc-xml-expand
+
+clean:
+	rm -rf $(BUILD)
+
+.PHONY: smoke selftest cbmc cbmc-alloc cbmc-utf8 cbmc-utf8-chain cbmc-utf8-words cbmc-span \
+        cbmc-spanbuf cbmc-buf cbmc-hash cbmc-xml-chars cbmc-xpath-number \
+        cbmc-deep cbmc-xpath-lex cbmc-xpath-parse cbmc-xml-parse cbmc-xml-expand clean