leptris 1.9.174.8 → 1.9.174.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e3bbbd00177ef272738c9d0d9562beb33cc2ed100145bc843785fd56ae0c5f22
-  data.tar.gz: c47af3b6769fb4e9cb233128df91b36bf9cecae4d23e06b9f94ad60caf9d498a
+  metadata.gz: f0e347192431e6ed3ff15bed0fca55fb103ba7307a33d889014e72c3ece0dba8
+  data.tar.gz: f7edb28afa62063bbc1f0ab2cfcc349619a8944249f69f41b40e054e016b5b45
 SHA512:
-  metadata.gz: e951276162615da4fdecfd7d500bdd9ddd2a378188190d9edf14341713243f1ce802fa2a129f5afb07d676ce2977e7d0e59e44b474dce656432cdb57d99b5fac
-  data.tar.gz: 812ae80ffb569ae41fa0734858a8f487f31f3a22689fc221686b801cf1922e69d4331615a678e1dd5a5589c2c464b6fe6ae51c4504b365448ea63a6ad6215628
+  metadata.gz: 660309e07c7ce84a4a68bdca9c46a1970f0af6a1bd2e316acca600de60cf54cbd445cd0814232593dd1752f59965d7df8ede74c14da977005b48cbec4ec276fd
+  data.tar.gz: ffe8c0e4f6fc98f4bda50187b3c740e278aae6c82ec384f1ac6843673276b916910a1ab72a4c740a69e0006992418c83eb92280a619b18fac69c8568f5b7639e

data/CHANGELOG.md

@@ -5,6 +5,43 @@ All notable changes to Leptris will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.9.174.10] - 2026-09-16
+
+### Changed
+
+- **Status raises in C (TODO.perf/36)**: every C mutation face
+  raises `Leptris::XML::Error` with the exact `status_message`
+  format — the Ruby `check_status` dispatch leaves the fast
+  mutation paths (and the success/lift-marker collision it
+  briefly introduced — Qtrue on success now — was caught by the
+  bottom-up construction spec). `to_xml(encoding:)` rides the ext
+  serializer face (encoding VALUE, nil → NULL).
+- **Document lazy Pointer (TODO.perf/37)**: `#c_ptr` materializes
+  once over `@c_address` (freed docs answer nil); the parse/create
+  faces skip the Pointer mint entirely. The ffi gem rejects
+  Integers for typedef'd pointer params — the search paths keep
+  the lazy Pointer.
+- **Atomic bundle vendoring**: replacing a mapped `native.bundle`
+  in place gets the next loader SIGKILLed (CODESIGNING Invalid
+  Page) — the Rakefile now cp+mv's atomically.
+
+## [1.9.174.9] - 2026-09-16
+
+### Changed
+
+- **Fragment fast lane (TODO.perf/34)**: `add_child(String)` runs
+  one C dispatch for the whole markup add — fragment parse +
+  every child append + a single readonly gate and version bump
+  (the move-during-iteration hazard handled: appending detaches,
+  so the walk captures next before each move). The fragment parse
+  face returns an address (no status MemoryPointer, no Pointer);
+  `DocumentFragment#children` rides the bulk face; parse failures
+  fall back to the legacy path for the exact error.
+- **Document.parse default path as one C dispatch (TODO.perf/35)**:
+  engine parse + ivar-seeded wrapper + lifetime handle in one
+  call — small parses measured 15.6µs → 6.8µs (~2.3x, under host
+  load ~100; the shape is self-contained).
+
 ## [1.9.174.8] - 2026-09-16
 
 ### Fixed

data/Rakefile

@@ -172,7 +172,12 @@ task :compile do
       # Build-log proof of the linkage contract: libSystem only.
       puts `otool -L #{bundle}`
     end
-    cp(bundle, "lib/leptris/xml/#{File.basename(bundle)}")
+    # Atomic replace: overwriting a bundle another process still
+    # has mapped gets that loader SIGKILLed (CODESIGNING Invalid
+    # Page) — cp to a temp name, then mv.
+    dest = "lib/leptris/xml/#{File.basename(bundle)}"
+    cp(bundle, "#{dest}.new")
+    mv("#{dest}.new", dest)
     puts "Vendored native layer (#{File.basename(bundle)}) into lib/leptris/xml/"
   end
 end

data/TODO.perf/34-fragment-fast-lane.md

@@ -0,0 +1,41 @@
+# 34 — Fragment fast lane: C parse, bulk children, one-shot markup append
+
+Status: DONE (1.9.174.9)
+
+The add_child(String) path — moxml's markup-builder shape — pays
+three layers per call: parse_fragment_with_status allocates a
+MemoryPointer for the status out-param, DocumentFragment#children
+runs the FFI fetch+wrap loop (never moved to the bulk faces), and
+each child appends through its own dispatch.
+
+Bind the lane: a C parse face returns the fragment's address
+(Integer — no Pointer, no MemoryPointer); the fragment stores
+@c_address with a lazy c_ptr; children rides the bulk face
+(fragment nodes live in the document pool — the document's cache
+and version discipline apply); and a one-shot append face parses
+the markup, walks the fragment's children, and appends every one
+with a single readonly gate + version bump. Parse failures return
+a marker; the Ruby fallback re-runs the old path for the exact
+error message (the rare path, cheap to re-fail).
+
+Gates: add_child(String) semantics identical (multiple top-level
+nodes, text, PIs, namespaces lifted per the Node path); fragment
+children identical through the bulk face; suite both modes.
+
+## Outcome (1.9.174.9)
+
+Three layers landed: the fragment parse face answers the
+fragment ADDRESS (no status MemoryPointer, no Pointer mint —
+failures fall back to the FFI pair for the exact error);
+DocumentFragment stores @c_address with a lazy c_ptr and
+children() rides the bulk face (fragment nodes live in the
+document pool — the document's cache and version discipline
+apply); and Element#add_child(String) runs ONE dispatch for the
+whole markup add (parse + per-child append + single gate/bump —
+with the move-during-iteration hazard caught by the suite:
+appending detaches the child, so the walk captures next BEFORE
+each move). -1 re-runs the legacy path for parse errors;
+-1000-st routes through check_status. The markup row needs a
+quiet-host battery number (this box sat at load 100+ today);
+small-parse measured 6.8µs native vs 15.6µs FFI (~2.3x) under
+load 100.

data/TODO.perf/35-parse-default-c-face.md

@@ -0,0 +1,24 @@
+# 35 — Document.parse default path as one C dispatch
+
+Status: DONE (1.9.174.9)
+
+The default parse path (no options, no recover — the adapter
+default) is already allocation-free at the Ruby level (#187),
+but still pays FFI marshaling, the wrap frames, the Freed and
+Pointer constructions, and the handle attach across three Ruby
+layers. One C face runs leptris_parse_string + the full document
+wrapper (ivar-seeded) + lifetime handle and returns it; failure
+raises the same ParseError shape via last_error read in C.
+
+Gates: parse defaults identical (errors, readonly flag, root
+access); the options/recover paths untouched; suite both modes.
+
+## Outcome (1.9.174.9)
+
+Native.parse_binding_document: leptris_parse_string + the full
+ivar-seeded wrapper + lifetime handle in one dispatch (shared
+build_binding_document helper); Document.parse's default path
+(no options, no recover) routes through it, raising the same
+ParseError shape via last_error on failure. Options/recover
+paths untouched. Measured (load ~100, self-contained shape):
+small parse 15.6µs -> 6.8µs (~2.3x).

data/TODO.perf/36-raise-in-c-serializer-encoding.md

@@ -0,0 +1,34 @@
+# 36 — Status raises in C + encoding on the serializer faces
+
+Status: DONE (1.9.174.10)
+
+Every C mutation face returns INT2FIX(st) for a Ruby check_status
+dispatch (~30ns per mutation, plus a whole class of
+"forgot-to-check" bug the compiler cannot catch). With
+leptris_status_string and leptris_last_error both dlsym'd, the
+faces raise Leptris::XML::Error in C with the exact
+status_message format ("base" or "base (detail)") — call sites
+shrink to the bare face call.
+
+The ext serializer faces skip the encoding-tagged shape entirely
+(to_xml(encoding: ...) still builds the options struct through
+FFI): the faces gain an encoding VALUE (nil -> NULL, the Ruby
+string's bytes stay valid across the synchronous engine call).
+
+Gates: every mutation's failure message byte-identical to
+check_status; encoding-tagged to_xml output identical to the FFI
+path (declaration, no anchor lifetime issues); suite both modes.
+
+## Outcome (1.9.174.10)
+
+All seven mutation faces raise Leptris::XML::Error in C with the
+exact status_message format (status_string + optional
+" (last_error)") — the Ruby check_status dispatch disappears from
+every fast mutation. TRAP FOUND: the faces' success return became
+Qnil, colliding with the lift-needed marker — every fast mutation
+fell through to the slow path and re-applied (order-corrupting
+for inserts; the v180 bottom-up spec caught it). Success now
+returns Qtrue. The serializer faces take an encoding VALUE (nil
+-> NULL; the Ruby string's bytes live across the synchronous
+call), and to_xml(encoding:) rides the ext face instead of the
+options-struct FFI path.

data/TODO.perf/37-document-lazy-pointer.md

@@ -0,0 +1,28 @@
+# 37 — Document lazy Pointer + address-based xpath contexts
+
+Status: DONE (1.9.174.10)
+
+Documents still mint an FFI::Pointer eagerly (the parse/create
+faces pay the funcall + one allocation + its GC visit per
+document). Make #c_ptr lazy like Node's (attr_reader becomes a
+materializer over @c_address), skip the Pointer in
+build_binding_document, and feed the search paths Integer
+addresses (the ffi gem converts Integers for :pointer params) so
+per-xpath document Pointers never materialize at all.
+
+Gates: c_ptr stability and public API unchanged; every FFI
+document consumer still works (options paths, c14n, fragment
+fallback); suite both modes.
+
+## Outcome (1.9.174.10)
+
+Document#c_ptr materializes lazily over @c_address (freed docs
+answer nil — never re-materialize); build_binding_document skips
+the Pointer funcall (one alloc + ~200ns per document). TRAP
+FOUND: this ffi version does NOT convert Integers for typedef'd
+pointer params — passing c_address into the compiled-eval calls
+failed with ":pointer argument is not a valid pointer"; the
+search paths keep passing the (now lazy, once-per-document)
+Pointer. Also: replacing a mapped native.bundle in place gets
+the next loader SIGKILLed (CODESIGNING Invalid Page) — the
+vendoring cp is now an atomic cp+mv.

data/ext/leptris/native/native.c

@@ -94,6 +94,10 @@ typedef void (*visit_fn)(void *, visit_cb_fn, void *);
 typedef void (*free_str_fn)(void *);
 typedef const char *(*node_xpath_fn)(void *);
 typedef void *(*elem_copy_fn)(void *, void *);
+typedef void *(*parse_str_fn)(const char *, size_t, void *);
+typedef void *(*parse_frag_fn)(const char *, size_t, void *, int *);
+typedef const char *(*last_err_fn)(void);
+typedef const char *(*status_str_fn)(int);
 static set_str_fn f_elem_set_name, f_elem_set_text, f_text_set_content;
 static node_unlink_fn f_node_unlink;
 static traverse_fn f_node_traverse;
@@ -101,6 +105,10 @@ static visit_fn f_node_visit;
 static free_str_fn f_free_str;
 static node_xpath_fn f_node_xpath;
 static elem_copy_fn f_elem_copy;
+static parse_str_fn f_parse_str;
+static parse_frag_fn f_parse_frag;
+static last_err_fn f_last_err;
+static status_str_fn f_status_str;
 static set_root_fn f_set_root;
 static doc_free_fn f_doc_free;
 
@@ -119,8 +127,10 @@ static void resolve_binding_classes(void);
 static VALUE binding_cache_of(VALUE document);
 static VALUE binding_klass_for(int kind);
 static VALUE c_iteration_scope;
+static VALUE c_leptris_error;
 static VALUE c_b_document, c_b_freed, c_ffi_pointer;
 static ID id_ptr_new, id_freed_new, id_alive;
+static void check_status_c(int st);
 
 #define NT_ELEMENT 0
 
@@ -221,6 +231,10 @@ static void resolve_symbols(const char *lib_path)
     f_free_str = (free_str_fn)lib_sym(h, "leptris_free_string");
     f_node_xpath = (node_xpath_fn)lib_sym(h, "leptris_node_get_xpath");
     f_elem_copy = (elem_copy_fn)lib_sym(h, "leptris_element_copy");
+    f_parse_str = (parse_str_fn)lib_sym(h, "leptris_parse_string");
+    f_parse_frag = (parse_frag_fn)lib_sym(h, "leptris_parse_fragment");
+    f_last_err = (last_err_fn)lib_sym(h, "leptris_last_error");
+    f_status_str = (status_str_fn)lib_sym(h, "leptris_status_string");
     f_set_root = (set_root_fn)lib_sym(h, "leptris_document_set_root");
     f_doc_free = (doc_free_fn)lib_sym(h, "leptris_document_free");
     if (!f_elem_name || !f_text_content || !f_attr ||
@@ -233,7 +247,8 @@ static void resolve_symbols(const char *lib_path)
         !f_pi_data || !f_elem_set_name || !f_elem_set_text ||
         !f_text_set_content || !f_node_unlink ||
         !f_node_traverse || !f_node_visit || !f_free_str ||
-        !f_node_xpath || !f_elem_copy ||
+        !f_node_xpath || !f_elem_copy || !f_parse_str ||
+        !f_parse_frag || !f_last_err || !f_status_str ||
         !f_doc_free ||
         !f_elem_prefix || !f_xp_count || !f_xp_nodes_ex ||
         !f_xp_node_kind || !f_xp_node_name || !f_xp_node_value ||
@@ -630,7 +645,8 @@ static VALUE nf_append_binding_child(VALUE self, VALUE document,
     rb_ivar_set(document, id_iv_version,
                 LONG2FIX(FIX2LONG(rb_ivar_get(document, id_iv_version)) + 1));
     st = f_append_child(parent, child);
-    return INT2FIX(st);
+    check_status_c(st);
+    return Qtrue;
 }
 
 /* C-bound set_attribute (TODO.perf/11, #204 gap row 0.25x): the
@@ -659,7 +675,8 @@ static VALUE nf_set_binding_attribute(VALUE self, VALUE document,
      * embedded-NUL value raises rather than truncates. */
     st = f_set_attr(node, RSTRING_PTR(StringValue(name)),
                     StringValueCStr(value));
-    return INT2FIX(st);
+    check_status_c(st);
+    return Qtrue;
 }
 
 /* C-bound value mutations (TODO.perf/23): the same gates + bump
@@ -682,7 +699,8 @@ static VALUE nf_set_binding_name(VALUE self, VALUE document,
     rb_ivar_set(document, id_iv_version,
                 LONG2FIX(FIX2LONG(rb_ivar_get(document, id_iv_version)) + 1));
     st = f_elem_set_name(node, StringValueCStr(name));
-    return INT2FIX(st);
+    check_status_c(st);
+    return Qtrue;
 }
 
 /* Element text or text-node content — kind-dispatched in C. */
@@ -706,7 +724,8 @@ static VALUE nf_set_binding_text(VALUE self, VALUE document,
     st = f_node_type(node) == NT_ELEMENT
              ? f_elem_set_text(node, StringValueCStr(content))
              : f_text_set_content(node, StringValueCStr(content));
-    return INT2FIX(st);
+    check_status_c(st);
+    return Qtrue;
 }
 
 static VALUE nf_unlink_binding_node(VALUE self, VALUE document,
@@ -727,7 +746,8 @@ static VALUE nf_unlink_binding_node(VALUE self, VALUE document,
     rb_ivar_set(document, id_iv_version,
                 LONG2FIX(FIX2LONG(rb_ivar_get(document, id_iv_version)) + 1));
     st = f_node_unlink(node);
-    return INT2FIX(st);
+    check_status_c(st);
+    return Qtrue;
 }
 
 /* C-bound root= (TODO.perf/33): gates + bump + engine set_root
@@ -751,7 +771,8 @@ static VALUE nf_set_binding_root(VALUE self, VALUE document,
     rb_ivar_set(document, id_iv_version,
                 LONG2FIX(FIX2LONG(rb_ivar_get(document, id_iv_version)) + 1));
     st = f_set_root(doc_ptr_of(document), node);
-    return INT2FIX(st);
+    check_status_c(st);
+    return Qtrue;
 }
 
 /* ---- C-yield traversal (TODO.perf/27) ----------------------------
@@ -1064,7 +1085,8 @@ static VALUE nf_insert_binding_child(VALUE self, VALUE document,
         rb_raise(rb_eArgError, "invalid insert mode %d", m);
         return Qnil;
     }
-    return INT2FIX(st);
+    check_status_c(st);
+    return Qtrue;
 }
 
 /* Builder factories (#149): create in C, wrap as NativeNode — no
@@ -1215,6 +1237,7 @@ static void resolve_binding_classes(void)
     c_b_document = rb_path2class("Leptris::XML::Document");
     c_b_freed = rb_path2class("Leptris::XML::Document::Freed");
     c_iteration_scope = rb_path2class("Leptris::XML::IterationScope");
+    c_leptris_error = rb_path2class("Leptris::XML::Error");
     id_ptr_new = rb_intern("new");
     rb_gc_register_mark_object(c_b_element);
     rb_gc_register_mark_object(c_b_text);
@@ -1229,6 +1252,7 @@ static void resolve_binding_classes(void)
     rb_gc_register_mark_object(c_b_document);
     rb_gc_register_mark_object(c_b_freed);
     rb_gc_register_mark_object(c_iteration_scope);
+    rb_gc_register_mark_object(c_leptris_error);
 }
 
 static VALUE binding_klass_for(int kind)
@@ -1625,7 +1649,8 @@ static char *ser_buf;
 static size_t ser_cap;
 
 static VALUE fast_serialize(serialize_into_fn fn, void *node,
-                            int indent, int xml_declaration)
+                            int indent, int xml_declaration,
+                            VALUE encoding)
 {
     struct serialize_opts opts;
     char stack_buf[4096];
@@ -1636,7 +1661,11 @@ static VALUE fast_serialize(serialize_into_fn fn, void *node,
 
     opts.indent = indent;
     opts.xml_declaration = xml_declaration;
-    opts.encoding = NULL;
+    /* The Ruby string's bytes stay valid across the synchronous
+     * engine call (TODO.perf/36). */
+    opts.encoding = NIL_P(encoding)
+                        ? NULL
+                        : StringValueCStr(encoding);
     /* Probe the largest buffer we own: a big scratch from a prior
      * call usually fits (single serialization); cold calls start
      * on the stack buffer. */
@@ -1662,21 +1691,25 @@ static VALUE fast_serialize(serialize_into_fn fn, void *node,
 }
 
 static VALUE nf_fast_document_xml(VALUE self, VALUE addr,
-                                  VALUE indent, VALUE decl)
+                                  VALUE indent, VALUE decl,
+                                  VALUE encoding)
 {
     (void)self;
     return fast_serialize(f_doc_serialize,
                           (void *)(uintptr_t)NUM2ULL(addr),
-                          NUM2INT(indent), RTEST(decl) ? 1 : 0);
+                          NUM2INT(indent), RTEST(decl) ? 1 : 0,
+                          encoding);
 }
 
 static VALUE nf_fast_element_xml(VALUE self, VALUE addr,
-                                 VALUE indent, VALUE decl)
+                                 VALUE indent, VALUE decl,
+                                 VALUE encoding)
 {
     (void)self;
     return fast_serialize(f_elem_serialize,
                           (void *)(uintptr_t)NUM2ULL(addr),
-                          NUM2INT(indent), RTEST(decl) ? 1 : 0);
+                          NUM2INT(indent), RTEST(decl) ? 1 : 0,
+                          encoding);
 }
 
 /* ---- inner_html in one C pass (TODO.perf/18) --------------------
@@ -1851,8 +1884,6 @@ static VALUE nf_copy_binding_element(VALUE self, VALUE document,
         return Qnil;
     doc_addr = ULL2NUM((uint64_t)(uintptr_t)doc);
     new_doc = rb_obj_alloc(c_b_document);
-    rb_iv_set(new_doc, "@c_ptr",
-              rb_funcall(c_ffi_pointer, id_ptr_new, 1, doc_addr));
     rb_iv_set(new_doc, "@c_address", doc_addr);
     freed = rb_funcall(c_b_freed, id_freed_new, 1, ID2SYM(id_alive));
     rb_iv_set(new_doc, "@freed", freed);
@@ -1874,6 +1905,119 @@ static VALUE nf_copy_binding_element(VALUE self, VALUE document,
     return new_doc;
 }
 
+/* Shared document-wrapper construction from a C document
+ * pointer: ivar-seeded wrapper + lifetime handle. Returns the
+ * wrapper. (TODO.perf/35 — the create face inlines the same
+ * steps.) */
+static VALUE build_binding_document(void *doc)
+{
+    VALUE new_doc, doc_addr, handle, freed;
+    struct doc_handle *h;
+
+    doc_addr = ULL2NUM((uint64_t)(uintptr_t)doc);
+    new_doc = rb_obj_alloc(c_b_document);
+    rb_iv_set(new_doc, "@c_ptr",
+              rb_funcall(c_ffi_pointer, id_ptr_new, 1, doc_addr));
+    rb_iv_set(new_doc, "@c_address", doc_addr);
+    freed = rb_funcall(c_b_freed, id_freed_new, 1, ID2SYM(id_alive));
+    rb_iv_set(new_doc, "@freed", freed);
+    rb_iv_set(new_doc, "@readonly", Qfalse);
+    rb_iv_set(new_doc, "@version", INT2FIX(0));
+    handle = TypedData_Make_Struct(c_doc_handle, struct doc_handle,
+                                   &dh_type, h);
+    h->doc = doc;
+    rb_ivar_set(new_doc, id_iv_doc_handle, handle);
+    return new_doc;
+}
+
+/* check_status in C (TODO.perf/36): the exact status_message
+ * format — "base" or "base (detail)" — so the mutation faces
+ * raise instead of returning codes for a Ruby dispatch. */
+static void check_status_c(int st)
+{
+    const char *base, *detail;
+
+    if (st == 0)
+        return;
+    base = f_status_str(st);
+    detail = f_last_err();
+    if (detail && *detail)
+        rb_raise(c_leptris_error, "%s (%s)",
+                 base ? base : "?", detail);
+    rb_raise(c_leptris_error, "%s", base ? base : "?");
+}
+
+/* Document.parse default path in one dispatch (TODO.perf/35):
+ * leptris_parse_string + wrapper + handle. Qnil = parse failure
+ * (the caller raises with the same message shape). */
+static VALUE nf_parse_binding_document(VALUE self, VALUE xml)
+{
+    void *doc;
+
+    (void)self;
+    resolve_binding_classes();
+    doc = f_parse_str(RSTRING_PTR(StringValue(xml)),
+                      (size_t)RSTRING_LEN(StringValue(xml)), NULL);
+    return doc ? build_binding_document(doc) : Qnil;
+}
+
+/* Fragment lane (TODO.perf/34): parse the markup against the
+ * document; returns the fragment's ADDRESS, or Qfalse when the
+ * parse fails (status is not surfaced — the caller re-runs the
+ * FFI path for the exact error). */
+static VALUE nf_parse_fragment_addr(VALUE self, VALUE document,
+                                    VALUE xml)
+{
+    void *frag;
+    int status;
+
+    (void)self;
+    resolve_binding_classes();
+    frag = f_parse_frag(RSTRING_PTR(StringValue(xml)),
+                        (size_t)RSTRING_LEN(StringValue(xml)),
+                        doc_ptr_of(document), &status);
+    return frag ? ULL2NUM((uint64_t)(uintptr_t)frag) : Qfalse;
+}
+
+/* One-shot markup append (TODO.perf/34): parse the markup, walk
+ * the fragment's children, append each to the parent — one
+ * readonly gate + version bump for the whole batch. Returns the
+ * appended count; -1 = parse failure; status codes surface as
+ * negatives (-1000 - st) for the caller's check_status path. */
+static VALUE nf_append_markup(VALUE self, VALUE document,
+                              VALUE parent_addr, VALUE xml)
+{
+    void *frag, *parent, *child, *next_child;
+    int status, count = 0;
+
+    (void)self;
+    resolve_binding_classes();
+    if (NIL_P(rb_ivar_get(document, id_iv_c_address)))
+        rb_raise(c_use_after_free_error,
+                 "owning document has been freed");
+    if (rb_ivar_get(document, id_iv_readonly) == Qtrue)
+        rb_raise(c_readonly_error,
+                 "document is readonly — mutation attempted");
+    frag = f_parse_frag(RSTRING_PTR(StringValue(xml)),
+                        (size_t)RSTRING_LEN(StringValue(xml)),
+                        doc_ptr_of(document), &status);
+    if (!frag)
+        return INT2FIX(-1);
+    parent = (void *)(uintptr_t)NUM2ULL(parent_addr);
+    rb_ivar_set(document, id_iv_version,
+                LONG2FIX(FIX2LONG(rb_ivar_get(document, id_iv_version)) + 1));
+    /* Appending DETACHES the child from the fragment — capture
+     * the next sibling before each move or the walk corrupts. */
+    for (child = f_first_child(frag); child != NULL; child = next_child) {
+        next_child = f_next_sibling(child);
+        status = f_append_child(parent, child);
+        if (status != 0)
+            check_status_c(status);
+        count++;
+    }
+    return INT2FIX(count);
+}
+
 static VALUE nf_doc_handle_attach(VALUE self, VALUE document)
 {
     struct doc_handle *h;
@@ -2097,6 +2241,12 @@ void Init_native(void)
                               nf_copy_binding_element, 2);
     rb_define_module_function(m_native, "set_binding_root",
                               nf_set_binding_root, 2);
+    rb_define_module_function(m_native, "parse_binding_document",
+                              nf_parse_binding_document, 1);
+    rb_define_module_function(m_native, "parse_fragment_addr",
+                              nf_parse_fragment_addr, 2);
+    rb_define_module_function(m_native, "append_markup",
+                              nf_append_markup, 3);
     rb_define_module_function(m_native, "fast_inner_xml",
                               nf_fast_inner_xml, 1);
     rb_define_module_function(m_native, "doc_handle_attach",
@@ -2119,7 +2269,7 @@ void Init_native(void)
                               nf_bulk_element_children, 2);
     rb_define_module_function(m_native, "bulk_xpath", nf_bulk_xpath, 2);
     rb_define_module_function(m_native, "fast_document_xml",
-                              nf_fast_document_xml, 3);
+                              nf_fast_document_xml, 4);
     rb_define_module_function(m_native, "fast_element_xml",
-                              nf_fast_element_xml, 3);
+                              nf_fast_element_xml, 4);
 }

data/lib/leptris/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Leptris
-  VERSION = "1.9.174.8"
+  VERSION = "1.9.174.10"
 end

data/lib/leptris/xml/document.rb

@@ -3,7 +3,6 @@
 require "ffi"
 
 class Leptris::XML::Document
-  attr_reader :c_ptr
 
   # @api private
   # Internal flag container shared between the Document instance and its
@@ -57,6 +56,19 @@ class Leptris::XML::Document
     # document for trees that are freed before any wrap.
   end
 
+  # TODO.perf/37: the Integer address is canonical; the Pointer
+  # materializes only when read (parse/create faces skip it).
+  # A freed document answers nil — never re-materialize a stale
+  # or absent address.
+  def c_ptr
+    @c_ptr ||= (@c_address && ::FFI::Pointer.new(@c_address))
+  end
+
+  # The Integer twin of #c_ptr.
+  def c_address
+    @c_address
+  end
+
   def wrapper_cache
     @wrapper_cache ||= {}
   end
@@ -70,6 +82,15 @@ class Leptris::XML::Document
     # ParseOptions.new here would only discover flags==0 (#187 —
     # per-call overhead is most of a small-document parse).
     if options.nil? && !recover
+      # TODO.perf/35: parse + wrapper + lifetime handle in one C
+      # dispatch; failure raises through the shared path below.
+      if defined?(Leptris::XML::NATIVE_FAST)
+        doc = Leptris::XML::Native.parse_binding_document(xml)
+        raise Leptris::XML::ParseError,
+              "leptris_parse_string failed: " +
+              Leptris::XML::FFI.leptris_last_error.to_s if doc.nil?
+        return doc.tap { |d| d.readonly! if readonly }
+      end
       raw = Leptris::XML::FFI.leptris_parse_string(xml, xml.bytesize, nil)
       if raw.null?
         raise Leptris::XML::ParseError,
@@ -299,8 +320,7 @@ class Leptris::XML::Document
     # dispatch (the FFI call plus the c_ptr materialization fed
     # ~5% of a fresh-doc build).
     if defined?(Leptris::XML::NATIVE_FAST)
-      Leptris::XML::FFI.check_status(
-        Leptris::XML::Native.set_binding_root(self, element.c_address))
+      Leptris::XML::Native.set_binding_root(self, element.c_address)
     else
       Leptris::XML::FFI.check_status(
         Leptris::XML::FFI.leptris_document_set_root(c_ptr, element.c_ptr))

data/lib/leptris/xml/document_fragment.rb

@@ -9,12 +9,32 @@ class Leptris::XML::DocumentFragment
 
   attr_reader :document, :c_ptr
 
-  def initialize(document, c_ptr)
+  def initialize(document, c_ptr, c_address: nil)
     @document = document
     @c_ptr = c_ptr
+    # TODO.perf/34: the address may arrive before any Pointer
+    # exists (the C parse face returns an Integer).
+    @c_address = c_address || c_ptr&.address
+  end
+
+  # Integer twin — reading it never materializes a Pointer.
+  def c_address
+    @c_address
+  end
+
+  def c_ptr
+    @c_ptr ||= ::FFI::Pointer.new(@c_address)
   end
 
   def self.parse(xml, document)
+    # TODO.perf/34: the C face answers the fragment address with
+    # no status MemoryPointer and no Pointer mint; failures fall
+    # back to the FFI pair for the exact error.
+    if defined?(Leptris::XML::NATIVE_FAST)
+      addr = Leptris::XML::Native.parse_fragment_addr(
+        document, xml.to_s)
+      return new(document, nil, c_address: addr) if addr != false
+    end
     raw, status = Leptris::XML::FFI.parse_fragment_with_status(
       xml.to_s, document.c_ptr)
     if raw.null?
@@ -25,6 +45,11 @@ class Leptris::XML::DocumentFragment
   end
 
   def children
+    # TODO.perf/34: one C pass (fragment nodes live in the
+    # document pool — the document's cache and version apply).
+    if defined?(Leptris::XML::NATIVE_FAST)
+      return Leptris::XML::Native.bulk_children(@document, @c_address)
+    end
     pointers, kinds = Leptris::XML::FFI.fetch_children(c_ptr)
     nodes = Array.new(pointers.size) do |i|
       Leptris::XML::Node.wrap(pointers[i], @document, node_type: kinds[i])

data/lib/leptris/xml/element.rb

@@ -25,9 +25,8 @@ class Leptris::XML::Element < Leptris::XML::Node
 
   def name=(new_name)
     if @native_fast
-      Leptris::XML::FFI.check_status(
-        Leptris::XML::Native.set_binding_name(
-          @document, @c_address, new_name))
+      Leptris::XML::Native.set_binding_name(
+        @document, @c_address, new_name)
       return @name = new_name
     end
     ensure_writable!
@@ -54,9 +53,8 @@ class Leptris::XML::Element < Leptris::XML::Node
 
   def content=(new_content)
     if @native_fast
-      Leptris::XML::FFI.check_status(
-        Leptris::XML::Native.set_binding_text(
-          @document, @c_address, new_content.to_s))
+      Leptris::XML::Native.set_binding_text(
+        @document, @c_address, new_content.to_s)
       @content = new_content.to_s
       @content_version = @document.version if @document
       return new_content
@@ -138,9 +136,8 @@ class Leptris::XML::Element < Leptris::XML::Node
     # set in one dispatch; the bump drops the version-stamped
     # attribute memos on both surfaces.
     if native_fast_children?
-      Leptris::XML::FFI.check_status(
-        Leptris::XML::Native.set_binding_attribute(
-          @document, @c_address, key.to_s, value.to_s))
+      Leptris::XML::Native.set_binding_attribute(
+        @document, @c_address, key.to_s, value.to_s)
       seed_attribute_memo(key.to_s, value.to_s)
       return value
     end
@@ -374,10 +371,8 @@ class Leptris::XML::Element < Leptris::XML::Node
     # bump + engine insert in one dispatch; Qnil = the child needs
     # the namespace lift — the full path below handles it.
     if native_fast_children?
-      st = Leptris::XML::Native.insert_binding_child(
-        @document, @c_address, node.c_ptr.address, 1)
-      unless st.nil?
-        Leptris::XML::FFI.check_status(st)
+      unless Leptris::XML::Native.insert_binding_child(
+        @document, @c_address, node.c_ptr.address, 1).nil?
         Leptris::XML::Node.invalidate_cross_document!(node, @document)
         return node
       end
@@ -397,10 +392,8 @@ class Leptris::XML::Element < Leptris::XML::Node
     # bump + engine insert in one dispatch; Qnil = the child needs
     # the namespace lift — the full path below handles it.
     if native_fast_children?
-      st = Leptris::XML::Native.insert_binding_child(
-        @document, @c_address, node.c_ptr.address, 2)
-      unless st.nil?
-        Leptris::XML::FFI.check_status(st)
+      unless Leptris::XML::Native.insert_binding_child(
+        @document, @c_address, node.c_ptr.address, 2).nil?
         Leptris::XML::Node.invalidate_cross_document!(node, @document)
         return node
       end
@@ -420,10 +413,8 @@ class Leptris::XML::Element < Leptris::XML::Node
     # bump + engine insert in one dispatch; Qnil = the child needs
     # the namespace lift — the full path below handles it.
     if native_fast_children?
-      st = Leptris::XML::Native.insert_binding_child(
-        @document, @c_address, node.c_ptr.address, 3)
-      unless st.nil?
-        Leptris::XML::FFI.check_status(st)
+      unless Leptris::XML::Native.insert_binding_child(
+        @document, @c_address, node.c_ptr.address, 3).nil?
         Leptris::XML::Node.invalidate_cross_document!(node, @document)
         return node
       end
@@ -539,10 +530,10 @@ class Leptris::XML::Element < Leptris::XML::Node
       # means the child needs the namespace lift — fall through
       # to the full path.
       if native_fast_children?
-        st = Leptris::XML::Native.append_binding_child(
-          @document, @c_address, node_or_markup.c_ptr.address)
-        unless st.nil?
-          Leptris::XML::FFI.check_status(st)
+        # The face raises on failure (TODO.perf/36); Qnil = the
+        # child needs the lift — the full path handles it.
+        unless Leptris::XML::Native.append_binding_child(
+          @document, @c_address, node_or_markup.c_ptr.address).nil?
           Leptris::XML::Node.invalidate_cross_document!(node_or_markup, @document)
           return node_or_markup
         end
@@ -555,6 +546,23 @@ class Leptris::XML::Element < Leptris::XML::Node
       Leptris::XML::Node.invalidate_cross_document!(node_or_markup, @document)
       node_or_markup
     when String
+      # TODO.perf/34: one dispatch parses the markup and appends
+      # every fragment child (single gate + bump). Negative
+      # returns: -1 re-runs the FFI path for the exact parse
+      # error; -1000-st routes through check_status.
+      if native_fast_children?
+        r = Leptris::XML::Native.append_markup(
+          @document, @c_address, node_or_markup)
+        if r != -1
+          # Appends raise in C on status failures (TODO.perf/36);
+          # -1 alone means the parse failed.
+          return Leptris::XML::NodeSet.new(@document, []) if r.zero?
+          return Leptris::XML::NodeSet.new(@document, last_added(r))
+        end
+        # parse failure: reproduce the exact error via the legacy
+        # path (it re-fails fast)
+        Leptris::XML::DocumentFragment.parse(node_or_markup, @document)
+      end
       frag = Leptris::XML::DocumentFragment.parse(node_or_markup, @document)
       added = []
       frag.children.each do |n|
@@ -567,6 +575,14 @@ class Leptris::XML::Element < Leptris::XML::Node
       raise ArgumentError, "add_child expects a Node or String, got #{node_or_markup.class}"
     end
   end
+  # The markup-append face appends in fragment order; the added
+  # nodes are this element's last +count+ children.
+  def last_added(count)
+    kids = children.to_a
+    kids.last(count)
+  end
+  private :last_added
+
   alias_method :<<, :add_child
 
   def namespace

data/lib/leptris/xml/node.rb

@@ -486,8 +486,7 @@ class Leptris::XML::Node
 
   def unlink
     if @native_fast
-      Leptris::XML::FFI.check_status(
-        Leptris::XML::Native.unlink_binding_node(@document, @c_address))
+      Leptris::XML::Native.unlink_binding_node(@document, @c_address)
       @parent = nil
       return self
     end

data/lib/leptris/xml/searchable.rb

@@ -55,6 +55,10 @@ module Leptris::XML::Searchable
     expr = paths.one? && paths.first.is_a?(String) ? paths.first
                                                     : paths.join(" | ")
 
+    # TODO.perf/37: the document's Pointer is lazy (materializes
+    # once per document lifetime, not per parse); the ffi gem
+    # does NOT convert Integers for typedef'd pointer params, so
+    # the Pointer object is still what crosses here.
     doc_ptr = is_a?(Leptris::XML::Document) ? c_ptr : document.c_ptr
     context_ptr = is_a?(Leptris::XML::Document) ? nil : c_ptr
 
@@ -100,6 +104,10 @@ module Leptris::XML::Searchable
     expr = paths.one? && paths.first.is_a?(String) ? paths.first
                                                     : paths.join(" | ")
 
+    # TODO.perf/37: the document's Pointer is lazy (materializes
+    # once per document lifetime, not per parse); the ffi gem
+    # does NOT convert Integers for typedef'd pointer params, so
+    # the Pointer object is still what crosses here.
     doc_ptr = is_a?(Leptris::XML::Document) ? c_ptr : document.c_ptr
     context_ptr = is_a?(Leptris::XML::Document) ? nil : c_ptr
 

data/lib/leptris/xml/serialization.rb

@@ -32,16 +32,16 @@ module Leptris::XML::Serialization
   # cycle lives at the FFI seam (FFI.serialize_into_string); this
   # module owns only options selection and construction.
   def self.to_xml(ffi_function, c_ptr, indent: 0, no_decl: false, encoding: nil)
-    # TODO.perf/04: the common shape (no encoding) runs the whole
-    # sized-buffer cycle in the ext — one C dispatch, no options
-    # marshaling, no Ruby buffer management.
-    if defined?(Leptris::XML::NATIVE_FAST) && encoding.nil?
+    # TODO.perf/04+36: the whole sized-buffer cycle in the ext —
+    # one C dispatch, no options marshaling, no Ruby buffer
+    # management; encoding rides the face (nil -> no override).
+    if defined?(Leptris::XML::NATIVE_FAST)
       decl = !no_decl
       return Leptris::XML::Native.fast_element_xml(
-        c_ptr.address, indent.to_i, decl) if
+        c_ptr.address, indent.to_i, decl, encoding) if
         ffi_function == ELEMENT_SERIALIZE_INTO
       return Leptris::XML::Native.fast_document_xml(
-        c_ptr.address, indent.to_i, decl) if
+        c_ptr.address, indent.to_i, decl, encoding) if
         ffi_function == DOCUMENT_SERIALIZE_INTO
     end
     opts =
@@ -59,7 +59,8 @@ module Leptris::XML::Serialization
   # loop: no kwargs, no options rebuild, no method allocation —
   # one FFI fast-path dispatch per child.
   def self.element_xml_default(c_ptr)
-    return Leptris::XML::Native.fast_element_xml(c_ptr.address, 0, true) if
+    return Leptris::XML::Native.fast_element_xml(c_ptr.address, 0, true,
+                                                  nil) if
       defined?(Leptris::XML::NATIVE_FAST)
     Leptris::XML::FFI.serialize_into_string(
       ELEMENT_SERIALIZE_INTO, c_ptr, DEFAULT_OPTIONS.pointer)

data/lib/leptris/xml/text.rb

@@ -20,9 +20,8 @@ class Leptris::XML::Text < Leptris::XML::Node
 
   def content=(new_content)
     if @native_fast
-      Leptris::XML::FFI.check_status(
-        Leptris::XML::Native.set_binding_text(
-          @document, @c_address, new_content.to_s))
+      Leptris::XML::Native.set_binding_text(
+        @document, @c_address, new_content.to_s)
       return new_content
     end
     ensure_writable!

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: leptris
 version: !ruby/object:Gem::Version
-  version: 1.9.174.8
+  version: 1.9.174.10
 platform: ruby
 authors:
 - Ribose Inc.
@@ -102,6 +102,10 @@ files:
 - TODO.perf/31-battery-rounds-4-8.md
 - TODO.perf/32-clean-host-floor-table.md
 - TODO.perf/33-cbound-root-set.md
+- TODO.perf/34-fragment-fast-lane.md
+- TODO.perf/35-parse-default-c-face.md
+- TODO.perf/36-raise-in-c-serializer-encoding.md
+- TODO.perf/37-document-lazy-pointer.md
 - TODO.restructure/01-constraint-compliance-audit.md
 - TODO.restructure/02-deep-copy-seam.md
 - TODO.restructure/03-evaluation-context-seam.md