makiri 0.5.1-aarch64-linux → 0.7.0-aarch64-linux

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dc9698d035a5e648a62aacda44694b0df5918e88cea61c52a061af4418976c7b
-  data.tar.gz: aae9379b5390003c757e98e77154c8d36e7620eaf9f0ad5b05a91af8816ba6a9
+  metadata.gz: 1117686dde2fd5e8a6e863971b3220a7bfffd621e3dea8097d0b0b0b14f75275
+  data.tar.gz: ee2fbfb3b456a86f9444bf9faa9ccdf051b224e44ffc951e2b84ef49333e6907
 SHA512:
-  metadata.gz: ef81933c52378d6368a71250397c4dd459a1fe106acf7e5974d96a82f7bee8bf74d0d1e74868d800a1efebfd0dfd8c6e99e82e689e92ce3e8b022f84a1b5bd16
-  data.tar.gz: 43d7cd497019cc3ed4f119e84d0f1a8608535187ae62f35caaa9cb2034f2021e425f8511e80e642fe861300db5c5041dc16f750767182a103aa0a44c51c0e920
+  metadata.gz: 5fa4fce173089263057caf5f8f13ab305d60c6d07f7df4a2d5b921d7025a25be5ace35c7797e9664938f7537a7ff3c6870cfacd75b6689f3e692f3e9c9d003a8
+  data.tar.gz: 97694793f4875a0378582e504b2df12baa4902d18c2b28ea9d3fc9ed78de0da9310af78f67a7a7a5e5298a321477175343fcc34320ea49787450e0951b56a371

data/.github/workflows/ci.yml

@@ -12,7 +12,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        os: [ubuntu-latest, macos-latest]
+        os: [ubuntu-latest, macos-latest, windows-latest]
         ruby: ["3.2", "3.3", "3.4", "4.0"]
 
     steps:
@@ -42,6 +42,7 @@ jobs:
           THREADING: ${{ (matrix.os == 'ubuntu-latest' && matrix.ruby == '3.4') && '1' || '' }}
 
       - name: Smoke-load the gem
+        shell: bash
         run: bundle exec ruby -Ilib -r makiri -e 'p Makiri::VERSION'
 
   sanitize:

data/.github/workflows/libfuzzer.yml

@@ -21,7 +21,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        target: [xml, xpath]
+        target: [xml, xpath, xml_xpath]
 
     steps:
       - name: Checkout (with vendored Lexbor submodule)

data/.github/workflows/release.yml

@@ -62,10 +62,12 @@ jobs:
         - x86_64-linux
         - aarch64-linux
         - arm64-darwin
+        - x64-mingw-ucrt
         include:
-          - { platform: x86_64-linux,  os: ubuntu-latest }
-          - { platform: aarch64-linux, os: ubuntu-24.04-arm }
-          - { platform: arm64-darwin,  os: macos-14 }
+          - { platform: x86_64-linux,   os: ubuntu-latest }
+          - { platform: aarch64-linux,  os: ubuntu-24.04-arm }
+          - { platform: arm64-darwin,   os: macos-14 }
+          - { platform: x64-mingw-ucrt, os: windows-latest }
     steps:
       - uses: actions/checkout@v6
         with:
@@ -79,6 +81,7 @@ jobs:
       - name: Compile (builds vendored Lexbor, then the ext)
         run: bundle exec rake compile
       - name: Smoke-load
+        shell: bash
         run: bundle exec ruby -Ilib -r makiri -e 'p Makiri::VERSION'
       - name: Stage the compiled binary under its ABI subdir
         shell: bash
@@ -97,16 +100,25 @@ jobs:
         run: |
           dlext="$(ruby -e 'print RbConfig::CONFIG["DLEXT"]')"
           bin="lib/makiri/makiri.${dlext}"
-          if [ "$(uname)" = "Darwin" ]; then
-            if otool -L "$bin" | grep -i 'libruby'; then
-              echo "::error::$bin hard-links libruby; precompiled gem would not load on other Ruby installs"; exit 1
-            fi
-          else
-            if readelf -d "$bin" 2>/dev/null | grep -iE 'NEEDED.*libruby'; then
-              echo "::error::$bin has a libruby NEEDED entry; precompiled gem may not load on a static Ruby"; exit 1
-            fi
-          fi
-          echo "OK: $bin has no libruby dependency"
+          case "$(uname -s)" in
+            Darwin)
+              if otool -L "$bin" | grep -i 'libruby'; then
+                echo "::error::$bin hard-links libruby; precompiled gem would not load on other Ruby installs"; exit 1
+              fi
+              ;;
+            MINGW*|MSYS*|CYGWIN*)
+              # Windows PE DLLs MUST import the Ruby DLL via the import library
+              # (no dynamic_lookup on PE/COFF). A libruby import here is by design,
+              # not a portability bug, so this assertion does not apply.
+              echo "Windows (x64-mingw-ucrt): Ruby import-library link is by design; skipping libruby assertion"
+              ;;
+            *)
+              if readelf -d "$bin" 2>/dev/null | grep -iE 'NEEDED.*libruby'; then
+                echo "::error::$bin has a libruby NEEDED entry; precompiled gem may not load on a static Ruby"; exit 1
+              fi
+              ;;
+          esac
+          echo "OK: portability check complete for $bin"
       - uses: actions/upload-artifact@v7
         with:
           name: bin-${{ matrix.platform }}-${{ matrix.ruby }}
@@ -128,6 +140,8 @@ jobs:
           os: ubuntu-24.04-arm
         - platform: arm64-darwin
           os: macos-14
+        - platform: x64-mingw-ucrt
+          os: windows-latest
     steps:
       - uses: actions/checkout@v6
         with:
@@ -157,6 +171,7 @@ jobs:
       - name: Build the native gem
         run: ruby script/build_native_gem.rb "${{ matrix.platform }}"
       - name: Verify it installs without recompiling
+        shell: bash
         run: |
           gem install "makiri-"*"-${{ matrix.platform }}.gem" --local
           ruby -e 'require "makiri"; puts Makiri::VERSION'

data/.github/workflows/verify.yml

@@ -0,0 +1,37 @@
+name: Verify
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  cbmc:
+    name: CBMC proofs
+    runs-on: ubuntu-24.04
+    timeout-minutes: 20
+
+    steps:
+      - name: Checkout (with vendored Lexbor submodule)
+        uses: actions/checkout@v6
+        with:
+          submodules: recursive
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.4"
+          bundler-cache: true
+
+      - name: Install CBMC
+        env:
+          CBMC_VERSION: "6.9.0"
+        run: |
+          curl -fsSLO "https://github.com/diffblue/cbmc/releases/download/cbmc-${CBMC_VERSION}/ubuntu-24.04-cbmc-${CBMC_VERSION}-Linux.deb"
+          sudo apt-get update
+          sudo apt-get install -y "./ubuntu-24.04-cbmc-${CBMC_VERSION}-Linux.deb"
+          cbmc --version
+
+      - name: Run verification suite
+        run: bundle exec rake verify

data/CHANGELOG.md

@@ -1,5 +1,57 @@
 # Changelog
 
+## [0.7.0] - 2026-07-11
+
+### Added
+
+* `Document#create_document_type(name, public_id = "", system_id = "")` on both
+  `Makiri::HTML::Document` and `Makiri::XML::Document` (DOM
+  `DOMImplementation.createDocumentType`): creates a detached `DocumentType`
+  node, to be placed before the document element (e.g. with
+  `root.add_previous_sibling(doctype)`). The name is case-preserving; an omitted
+  or empty public/system id is treated as absent; an invalid name (or a `"` in an
+  id) raises. Inserting a doctype is validated against the WHATWG rules — it may
+  only be a child of the document, must precede the document element, and a
+  document holds at most one — so a misplaced or duplicate doctype raises rather
+  than producing a malformed tree.
+
+* The XML `DocumentType` is now part of the tree: it appears in
+  `Document#children` (before the root, like a browser DOM) and carries
+  `parent`/sibling links, for both a parsed `<!DOCTYPE>` and the factory above.
+  `Document#internal_subset` still returns it. XPath is unaffected — its 1.0 data
+  model excludes the doctype (`//node()` / `/node()` never surface it), as in
+  Nokogiri/libxml2. This supports building a document with
+  `DOMImplementation.createDocument(namespace, qualifiedName, doctype)`.
+
+* `Makiri::XML::Document#create_loose_dom_element(qualified_name, prefix,
+  local_name, namespace_uri)`, an escape hatch for browser-DOM interop that
+  creates an element whose name follows WHATWG DOM element-name rules rather
+  than the stricter XML QName rules (e.g. `"f:o:o"`, `":foo"`, `"0:a"`). The
+  regular factories stay XML-strict. Such an element is intentionally not
+  XML-serializable: `#to_xml` and `#canonicalize` raise `Makiri::Error` if the
+  tree contains one. Renaming it to a valid XML name (`#name=`) returns it to
+  strict mode.
+
+### Fixed
+
+* Replacing an XML node with a `DocumentFragment` (`node.replace(fragment)`) is
+  now all-or-nothing: if the replacement is rejected (e.g. it would leave the
+  document with two root elements), the target node and the fragment are left
+  untouched, instead of dropping the target and splicing in only part of the
+  fragment. Replacing the root element with a single-element fragment now works.
+
+## [0.6.0] - 2026-07-05
+
+### Changed
+
+* Text and comment node content (`create_text_node`, `create_comment`,
+  `content=`) and attribute values (`[]=`, `set_attribute_ns`) now accept an
+  embedded NUL (U+0000) and store it verbatim, matching the WHATWG DOM and
+  browsers, instead of raising. Names, tag names, namespaces, CSS selectors, and
+  XPath expressions stay NUL-strict, and invalid UTF-8 is still rejected. XML
+  documents (`Makiri::XML`) are unchanged and still reject NUL everywhere, since
+  XML 1.0 has no legal U+0000 character.
+
 ## [0.5.1] - 2026-06-22
 
 ### Changed

data/README.md

@@ -267,6 +267,22 @@ Detailed, test-backed notes live in `spec/conformance/README.md`.
 * Type selectors are ASCII case-insensitive (CSS-correct for HTML; `LI` matches `<li>`)
   * `Nokogiri::HTML5` is case-sensitive there.
 
+### Text input (mutation APIs)
+
+* Programmatic string arguments must be **valid UTF-8** (invalid bytes raise
+  `Makiri::Error`, never silently repaired - unlike HTML *parsing*, which decodes
+  leniently to U+FFFD).
+* An embedded **NUL (U+0000)** is **accepted in HTML data-family content** -
+  text/comment node content (`create_text_node`, `create_comment`, `content=`)
+  and attribute values (`[]=`, `set_attribute_ns`) - and stored/read back
+  verbatim, matching the WHATWG DOM / browsers (`document.createTextNode("\0")`).
+  It is still **rejected** in names, tag names, namespaces, PI target/data, CSS
+  selectors, and XPath expressions/variable names (a NUL there raises).
+  * On re-parse, the HTML tokenizer replaces a U+0000 in text/attributes with
+    U+FFFD (WHATWG), so a serialized-then-reparsed round-trip is not byte-identical.
+  * `Makiri::XML` rejects NUL everywhere: XML 1.0 has no legal U+0000 character,
+    so admitting it would produce non-well-formed XML.
+
 ## Conformance
 
 The XPath engine and XML parser are original code, so their correctness is held by

data/Rakefile

@@ -287,6 +287,20 @@ task :oom do
   puts "(injection build left in place; run `rake clean compile` to restore a normal build)"
 end
 
+desc "CBMC proofs over the Ruby/Lexbor-free carve-out (core + XML + XPath front; " \
+     "needs cbmc; see docs/formal_verification.ja.md and verify/Makefile)"
+task :verify do
+  # The 10 CBMC proofs are independent processes with a lopsided cost
+  # distribution (a few ~1-2min solves dominate, the rest are trivial), so run
+  # them in parallel: wall-clock drops toward the single slowest harness with no
+  # loss of coverage. Cap -j at the CPU count (Etc.nprocessors; the runner has
+  # RAM for that many concurrent core-set solves). smoke/selftest are quick and
+  # come first as ordered goals.
+  require "etc"
+  jobs = Integer(ENV.fetch("VERIFY_JOBS", Etc.nprocessors))
+  sh "make", "-C", "verify", "-j#{jobs}", "smoke", "selftest", "cbmc"
+end
+
 desc "Run the performance benchmark (Makiri vs Nokogiri reference)"
 task bench: :compile do
   # Run outside the bundle so the bench-only gems (nokogiri, benchmark-ips)
@@ -303,13 +317,6 @@ task "bench:xml" => :compile do
   end
 end
 
-desc "Run the CSS selector-query benchmark on a note.com-style SPA page (set BENCH_CARDS)"
-task "bench:css" => :compile do
-  Bundler.with_unbundled_env do
-    sh "#{FileUtils::RUBY} -Ilib bench/bench_css_query.rb"
-  end
-end
-
 namespace :conformance do
   desc "WHATWG HTML5 parsing conformance: run html5lib-tests through Makiri"
   task html5: :compile do

data/lib/makiri/attr.rb

@@ -2,9 +2,6 @@
 
 module Makiri
   # An attribute node. Most of the API lives in C (#name, #value).
-  #
-  # An attribute knows its owning element through the document's lazily-built
-  # attr->owner index, exposed as both #parent and #element.
   class Attr < Node
     # The element this attribute belongs to, or nil if detached. Defined as a
     # method (not an alias) so it resolves #parent dynamically on the per-kind

data/lib/makiri/comment.rb

@@ -2,9 +2,7 @@
 
 module Makiri
   class Comment < Node
-    # Create a detached comment owned by +document+ (Nokogiri-style constructor;
-    # the document comes FIRST for Comment / CDATASection / ProcessingInstruction, unlike
-    # Element / Text). Delegates to {Document#create_comment}.
+    # Create a detached comment owned by +document+ (Nokogiri-style constructor)
     #
     # @param document [Makiri::Document]
     # @param content [String]

data/lib/makiri/compat_aliases.rb

@@ -3,18 +3,7 @@
 module Makiri
   # Nokogiri-compatible class-name aliases.
   #
-  # Makiri's canonical node-class names are the WHATWG DOM interface names
-  # (Element, Attr, Text, Comment, CDATASection, ProcessingInstruction,
-  # DocumentType, Document, DocumentFragment). Two of those differ from the
-  # libxml2/Nokogiri spelling; we expose the Nokogiri names as aliases so a
-  # snippet ported from Nokogiri (or an is_a?/case check) resolves unchanged:
-  #
-  #   CDATASection  <- CDATA   (Nokogiri::XML::CDATA)
-  #   DocumentType  <- DTD     (Nokogiri::XML::DTD)
-  #
-  # An alias is the same class object, so #is_a? works under either name; only
-  # #class.name (and inspect) report the canonical DOM name. Defined at all three
-  # levels (the abstract base and the HTML::/XML:: leaves).
+  # Makiri's canonical node-class names are the WHATWG DOM interface names.
   CDATA = CDATASection
   DTD = DocumentType
 

data/lib/makiri/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Makiri
-  VERSION = "0.5.1"
+  VERSION = "0.7.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

@@ -96,22 +96,13 @@ ignore_paths:
   - path: ext/makiri/glue/ruby_node_set.c
     rule: node_raw_boundary
     reason: NodeSet.new stores representation-opaque pointers; mkr_node_raw takes a seed node's pointer only after same-document validation guarantees its kind matches the set.
-
-# --- 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 in fuzz/*.c
   - 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
+    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."
+
+# --- parser-TU reader discipline (raw_scan_call / raw_cursor_member) ---
+allowlist: []

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_selftest.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