leptris 1.9.311.2-aarch64-linux → 1.9.312.0-aarch64-linux

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5bdff2edc4dd2718b7e55edc7cb459597f5119a7275439648cb14118510c2b48
-  data.tar.gz: d2925ceeb71346cc106c8ed3985e490779a9ba23a8c61b576d8f7b4e9527b7ab
+  metadata.gz: 9de71b8c23036b66ec08f42ba8d76658c4e0b434d1310edd0f25b22c67685cfa
+  data.tar.gz: b6a93975b39dd5c601e021c4265ddc4ad50af9e4542c161d946d992110b02fbc
 SHA512:
-  metadata.gz: 013d7a590fbf1c5e03b2c5b3be4158519f976c30694dc35f45ed5a1e9cfa7e655d421f40751b80ead5a84dda2a8dd1e429991574d50ec29b0db404bd15302cc8
-  data.tar.gz: a1c8447bc14ea7636dd3ca945de6c0d64fd79512ff119c53bfd923fa2d4f188f49785c230c5713da8f07bb298c7d41633906134107cf216290a00b7f1d043e4c
+  metadata.gz: fbd674dc47c7220e0405a473dce2d261370d4ef45a8cca93475212250ddf4859206884638901974124e8f23aff5ea78b44e5f4a8e6e078647f5279efe0ab1544
+  data.tar.gz: 37082ea5af7b48056ea1d19cd2613d6f8d4696cce9dcb547ebc14c3ee30ef0af28d88a1d086d4857d07ef3431be03217b3ff0c9a0fa39511211890773525474c

data/CHANGELOG.md

@@ -1,3 +1,52 @@
+## [1.9.312.0] - 2026-10-07
+
+### Added — engine sync (libleptris 1.9.312)
+
+- **Descriptor#serialize — plan-guided serialization (#1551)**:
+  `leptris_plan_serialize` round-trips a walk result back to XML —
+  the plan supplies element wrappers (row wire_name + the new
+  `ns_prefix:` field on element/child/attr rows), the result the
+  content. Children emit in document order; rows with ns EXACT +
+  `ns_prefix:` emit prefixed names and every distinct (prefix,
+  uri) pair is declared exactly once, on the output root, in
+  first-encounter order; text/attr values escape; RAW members are
+  verbatim. The three plan structs take the additive trailing
+  `ns_prefix` field (attr row 40 → 48B; the row-size skew gate
+  holds). `PlanValue#result_ptr` exposes the whole-result handle
+  the face reads.
+- **Wildcard child rows (#1552)**: `kind: :wildcard` binds every
+  element child no named sibling row bound — named rows win
+  regardless of row order; the row emits exactly one COLLECTION
+  (echoing wire_name/type_tag, even when empty); members keep
+  document order; an explicit `ns:` filters the remainder
+  (`ns: :none` binds no-namespace children alone; unset stays the
+  catch-all ANY default). PLAN_KIND_WILDCARD = 7.
+
+### Fixed — engine sync (1.9.312)
+
+- **Root-level leaf splices adopt single-node (#1539)**: a leaf
+  directly on a scratch document's children chain (prolog
+  comment / PI) no longer reports LEPTRIS_ERROR_MEMORY on
+  cross-document append — spec-pinned in the adoption suite.
+
+## [1.9.311.3] - 2026-10-06
+
+### Performance
+
+- **Same-document splices stop paying the cross-document sweep
+  (#374, the fresh-doc 0.80x follow-up)**: every fast splice path
+  is reached only after `foreign_to?` said no — the child's
+  document IS this one — so the post-splice
+  `invalidate_cross_document!` (a method call plus two ivar reads
+  that always returned at the equal check) was dead weight on the
+  hottest construction loop. Removed from the add_child /
+  prepend_child / sibling-insert fast paths and their FFI tails
+  (the foreign and batch paths keep their sweeps); `add_child` no
+  longer runs the Ruby-side readonly/version gate twice when the
+  C face self-gates. Measured under load with interleaved
+  CPU-time medians (3 rounds, 15k appends): add_child 1.69 →
+  1.41 µs/call (~16%), programmatic build ~14%.
+
 ## [1.9.311.2] - 2026-10-06
 
 ### Fixed

data/Rakefile

@@ -8,7 +8,7 @@ RSpec::Core::RakeTask.new(:spec)
 # Pin for `rake compile` and the platform-gem builds. Keep in lockstep
 # with .github/workflows/build.yml (which calls `rake compile`) and the
 # CHANGELOG when libleptris releases.
-LIBLEPTRIS_VERSION = "1.9.311"
+LIBLEPTRIS_VERSION = "1.9.312"
 # Vendored alongside libleptris for fn:normalize-unicode (TODO
 # .restructure/20): built per platform with a RELOCATABLE @rpath
 # install name, loaded by ffi.rb before libleptris so the

data/lib/leptris/version.rb

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

data/lib/leptris/xml/descriptor.rb

@@ -74,6 +74,12 @@ class Leptris::XML::Descriptor
     raw: Leptris::XML::FFI::PLAN_KIND_RAW,
     content: Leptris::XML::FFI::PLAN_KIND_CONTENT,
     callback: Leptris::XML::FFI::PLAN_KIND_CALLBACK,
+    # libleptris 1.9.312 (#1552): the remainder bucket — binds
+    # every element child no named sibling row bound. Emits one
+    # COLLECTION (even when empty); named rows win regardless of
+    # row order. child_plan_index >= 0 walks members through that
+    # plan; -1 (the default) emits RAW serialized subtrees.
+    wildcard: Leptris::XML::FFI::PLAN_KIND_WILDCARD,
   }.freeze
   private_constant :KINDS
 
@@ -177,6 +183,10 @@ class Leptris::XML::Descriptor
         end
       ep[:ns_form] = ns_form
       ep[:ns_uri] = ns_uri
+      # libleptris 1.9.312 (#1551): the root plan's serialization
+      # prefix (ns_form EXACT rows emit "prefix:local" and the
+      # xmlns declaration lands once on the output root).
+      ep[:ns_prefix] = anchor_string(anchors, plan[:ns_prefix]) if plan[:ns_prefix]
       attrs = plan[:attributes] || []
       attr_memory = attrs.empty? ? nil :
         ::FFI::MemoryPointer.new(Leptris::XML::FFI::AttrPlan, attrs.size)
@@ -198,6 +208,9 @@ class Leptris::XML::Descriptor
         ap[:ns_uri] =
           row[:ns].is_a?(Hash) ?
             anchor_string(anchors, row[:ns].fetch(:exact)) : nil
+        # libleptris 1.9.312 (#1551): serialization prefix — with
+        # ns_form EXACT the attribute emits as "prefix:local".
+        ap[:ns_prefix] = anchor_string(anchors, row[:ns_prefix]) if row[:ns_prefix]
         pack_predicates(ap, row, anchors)
       end
       ep[:attribute_count] = attrs.size
@@ -214,16 +227,24 @@ class Leptris::XML::Descriptor
         cp[:child_plan_index] = row[:child_plan_index] || -1
         # Rule-level ns form (libleptris 1.9.178, #1115): siblings
         # under one parent can require different URIs when set;
-        # defaults to NONE for backward compatibility.
+        # defaults to NONE for backward compatibility. WILDCARD
+        # rows (#1552) read an explicit :ns through pad0 (an
+        # explicit :none filters no-namespace remainder alone;
+        # unset stays the catch-all ANY default).
         cp[:ns_form] =
           case row[:ns]
           when :any then Leptris::XML::FFI::PLAN_NS_ANY
           when Hash  then Leptris::XML::FFI::PLAN_NS_EXACT
           else         Leptris::XML::FFI::PLAN_NS_NONE
           end
+        cp[:pad0] = 1 if row[:kind] == :wildcard && row.key?(:ns)
         cp[:ns_uri] =
           row[:ns].is_a?(Hash) ?
             anchor_string(anchors, row[:ns].fetch(:exact)) : nil
+        # libleptris 1.9.312 (#1551): serialization prefix — with
+        # ns_form EXACT the element emits as "prefix:local" and
+        # its declaration lands once on the output root.
+        cp[:ns_prefix] = anchor_string(anchors, row[:ns_prefix]) if row[:ns_prefix]
         pack_predicates(cp, row, anchors)
       end
       ep[:child_count] = children.size
@@ -318,6 +339,26 @@ class Leptris::XML::Descriptor
                                 owner: true, plans: @plans, plan: @plans[0])
   end
 
+  # libleptris 1.9.312 (#1551): serialize a walk result back to
+  # XML guided by this plan — the plan supplies element wrappers
+  # (row wire_name + ns_prefix), the result the content; children
+  # emit in document order. Rows with ns_form EXACT + ns_prefix
+  # emit prefixed names and every distinct (prefix, uri) pair is
+  # declared exactly once, on the output root, first-encounter
+  # order. Text and attribute values are escaped; RAW members are
+  # verbatim.
+  def serialize(plan_value)
+    result_ptr = plan_value.result_ptr
+    status = ::FFI::MemoryPointer.new(:int)
+    raw = Leptris::XML::FFI.leptris_plan_serialize(
+      @handle, result_ptr, status)
+    if raw.null?
+      raise Leptris::XML::Error,
+        "plan serialize failed (status=#{status.read_int})"
+    end
+    Leptris::XML::FFI.read_owned_string(raw)
+  end
+
   # The fused loop (#1269b): source bytes → typed rows in ONE C
   # call — leptris_plan_materialize runs parse, walk, and free
   # natively; the returned PlanValue tree is standalone and the

data/lib/leptris/xml/element.rb

@@ -446,7 +446,6 @@ class Leptris::XML::Element < Leptris::XML::Node
     if native_fast_children?
       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
     end
@@ -456,7 +455,6 @@ class Leptris::XML::Element < Leptris::XML::Node
     end
     Leptris::XML::FFI.check_status(
       Leptris::XML::FFI.leptris_element_prepend_child(c_ptr, node.c_ptr))
-    Leptris::XML::Node.invalidate_cross_document!(node, @document)
     node
   end
 
@@ -481,7 +479,6 @@ class Leptris::XML::Element < Leptris::XML::Node
     if native_fast_children?
       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
     end
@@ -491,7 +488,6 @@ class Leptris::XML::Element < Leptris::XML::Node
     end
     Leptris::XML::FFI.check_status(
       Leptris::XML::FFI.leptris_element_insert_after(c_ptr, node.c_ptr))
-    Leptris::XML::Node.invalidate_cross_document!(node, @document)
     node
   end
 
@@ -516,7 +512,6 @@ class Leptris::XML::Element < Leptris::XML::Node
     if native_fast_children?
       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
     end
@@ -526,7 +521,6 @@ class Leptris::XML::Element < Leptris::XML::Node
     end
     Leptris::XML::FFI.check_status(
       Leptris::XML::FFI.leptris_element_insert_before(c_ptr, node.c_ptr))
-    Leptris::XML::Node.invalidate_cross_document!(node, @document)
     node
   end
 
@@ -672,7 +666,6 @@ class Leptris::XML::Element < Leptris::XML::Node
   end
 
   def add_child(node_or_markup)
-    ensure_writable!
     case node_or_markup
     when Leptris::XML::Node
       # Foreign-child adoption (1.9.304, #1528): the engine
@@ -686,22 +679,24 @@ class Leptris::XML::Element < Leptris::XML::Node
       # readonly/liveness gates, the provable no-op lift
       # predicate, the version bump, and the engine append. Qnil
       # means the child needs the namespace lift — fall through
-      # to the full path.
+      # to the full path. Same-document children cannot reach
+      # here from another document (foreign ones routed above),
+      # so there is no cross-document sweep to run (#374): the
+      # C-side version bump invalidates this document's memos.
       if native_fast_children?
         # 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
       end
+      ensure_writable!
       unless Leptris::XML::Element.skip_adoption_lift?(node_or_markup)
         Leptris::XML::Element.lift_namespaces_for_adoption(node_or_markup, namespaces)
       end
       Leptris::XML::FFI.check_status(
         Leptris::XML::FFI.leptris_element_append_child(c_ptr, node_or_markup.c_ptr))
-      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
@@ -721,6 +716,7 @@ class Leptris::XML::Element < Leptris::XML::Node
         # path (it re-fails fast)
         Leptris::XML::DocumentFragment.parse(node_or_markup, @document)
       end
+      ensure_writable!
       frag = Leptris::XML::DocumentFragment.parse(node_or_markup, @document)
       added = []
       frag.children.each do |n|
@@ -741,6 +737,7 @@ class Leptris::XML::Element < Leptris::XML::Node
   # original is removed after (the source loses the node, as
   # every pre-304 caller observed).
   def append_installed(node)
+    ensure_writable!
     unless Leptris::XML::Element.skip_adoption_lift?(node)
       Leptris::XML::Element.lift_namespaces_for_adoption(node, namespaces)
     end

data/lib/leptris/xml/ffi.rb

@@ -306,7 +306,12 @@ module Leptris
                # unset = the historical wire-name lookup.
                :ns_form, :uint8,
                :pad_ns, :uint8,
-               :ns_uri, :pointer
+               :ns_uri, :pointer,
+               # libleptris 1.9.312 (#1551): intended wire prefix
+               # for plan-path serialization (ns_form EXACT emits
+               # "ns_prefix:wire_name"). NULL keeps matching-only
+               # behavior.
+               :ns_prefix, :pointer
       end
       class ChildPlan < ::FFI::Struct
         layout :wire_name, :pointer,
@@ -321,7 +326,13 @@ module Leptris
                # #1272: element-side predicates (same semantics).
                :predicate_count, :uint16,
                :pad_pred, :uint16,
-               :predicates, :pointer
+               :predicates, :pointer,
+               # libleptris 1.9.312 (#1551): serialization prefix,
+               # same contract as AttrPlan's. For WILDCARD rows
+               # (libleptris 1.9.312, #1552) pad0 marks an EXPLICIT
+               # ns_form (0 then filters no-namespace remainder);
+               # unset keeps the catch-all ANY default.
+               :ns_prefix, :pointer
       end
       class ElementPlan < ::FFI::Struct
         layout :element_name, :pointer,
@@ -333,7 +344,10 @@ module Leptris
                :attribute_plans, :pointer,
                :child_plans, :pointer,
                :flags, :uint16,
-               :pad1, :uint16
+               :pad1, :uint16,
+               # libleptris 1.9.312 (#1551): the root plan's
+               # serialization prefix.
+               :ns_prefix, :pointer
       end
       class PlanSpec < ::FFI::Struct
         layout :abi_version, :uint32,
@@ -349,6 +363,11 @@ module Leptris
       PLAN_KIND_RAW = 4
       PLAN_KIND_CONTENT = 5
       PLAN_KIND_CALLBACK = 6
+      # libleptris 1.9.312 (#1552): catch-all row — binds every
+      # element child no named sibling row bound (named rows win
+      # regardless of order); emits one COLLECTION echoing the
+      # row's wire_name/type_tag, members in document order.
+      PLAN_KIND_WILDCARD = 7
 
       PLAN_FLAG_MIXED_CONTENT = 0x1
       PLAN_FLAG_ORDERED = 0x2
@@ -391,6 +410,12 @@ module Leptris
         :leptris_plan_result
       attach_function :leptris_plan_result_free,
         [:leptris_plan_result], :void
+      # libleptris 1.9.312 (#1551): serialize a walk result back
+      # to XML guided by its plan — the plan supplies element
+      # wrappers (row wire_name + ns_prefix), the result the
+      # content. Caller-freed string (leptris_free_string).
+      attach_function :leptris_plan_serialize,
+        [:leptris_plan, :leptris_plan_result, :pointer], :pointer
       attach_function :leptris_plan_value_kind,
         [:leptris_plan_result], :int
       attach_function :leptris_plan_value_name,

data/lib/leptris/xml/plan_value.rb

@@ -30,6 +30,13 @@ class Leptris::XML::PlanValue
     @counter = counter || [0]
   end
 
+  # The engine value handle — the ROOT value's is the whole-result
+  # handle whole-result faces (leptris_plan_serialize) read. Pass
+  # the value Descriptor#walk/#materialize returned.
+  def result_ptr
+    @ptr
+  end
+
   def kind
     @counter[0] += 1
     VALUE_KINDS.fetch(Leptris::XML::FFI.leptris_plan_value_kind(@ptr))

data/vendor-src/README.md

@@ -1,7 +1,7 @@
 Sources vendored in this gem (recompile rights; the ruby
 variant builds them at install via extconf.rb):
 
-- libleptris v1.9.311
+- libleptris v1.9.312
 - utf8proc v2.11.0
 
 Rebuild by hand:

data/vendor-src/libleptris/CHANGELOG.md

@@ -1,5 +1,50 @@
 ## [Unreleased]
 
+## [1.9.312] - 2026-10-06
+
+### Added
+
+- **Plan-path serialization emits namespace declarations (#1551,
+  PR #1558).** New `leptris_plan_serialize(plan, result)`: the plan
+  supplies element wrappers, the result the content — children emit
+  in document order, collections are transparent, RAW members
+  verbatim, text and attributes escaped. Rows carrying
+  `ns_form = EXACT` plus the new trailing `ns_prefix` field emit
+  prefixed wire names, and every distinct (prefix, uri) pair is
+  declared exactly once on the output root in first-encounter
+  order. `leptris_attr_plan` takes the same field, so #1486-matched
+  attributes emit the plan-chosen spelling. Byte-parity gates on a
+  `w:document` corpus; additive trailing fields keep
+  `PLAN_ABI_VERSION` at 1 (64-bit attr row 40 -> 48 bytes). Rust
+  mirror (`leptris-descriptor`) updated in lockstep.
+- **Wildcard (catch-all) child rows (#1552, PR #1555).**
+  `LEPTRIS_PLAN_KIND_WILDCARD` binds every element child no named
+  sibling row bound — named rows take precedence regardless of row
+  order (a two-pass walk over a completed `bound[]` map; a named
+  row that rejected a child does not reserve it). Namespace-form
+  aware (`pad0` marks the form explicit so `NS_NONE` is
+  expressible; unset keeps the catch-all ANY default), emits one
+  COLLECTION echoing the row wire_name/type_tag even when empty,
+  members in document order; `child_plan_index >= 0` walks members
+  through that plan. Rust mirror gains `PLAN_KIND_WILDCARD = 7`.
+
+### Fixed
+
+- **Root-level leaf splice arguments adopt single-node (#1539,
+  PR #1554).** A leaf directly on a scratch document's children
+  chain (prolog/epilog comment or PI) reported
+  `LEPTRIS_ERROR_MEMORY` on cross-document append: the chain
+  copier hit the root element and misread it as OOM. The seam now
+  copies exactly the argument for the doc-level shape; in-element
+  leaves keep the #540 chain shape.
+- **Emulated-i386 perf-gate stability (PR #1561).** The
+  indexed-child-access shape budget widens 6x -> 7.5x: the qemu
+  timer noise of the ILP32 leg flaked past 6x three times in one
+  day while every native leg measured ~3x. Linear ~3x, quadratic
+  ~9x, O(N^3) ~27x — the gate keeps its discrimination.
+
+
+
 ## [1.9.311] - 2026-10-06
 
 ### Added

data/vendor-src/libleptris/CMakeLists.txt

@@ -3,7 +3,7 @@
 cmake_minimum_required(VERSION 3.20)
 
 project(leptris
-    VERSION 1.9.311
+    VERSION 1.9.312
     DESCRIPTION "Fast XML parser and XPath evaluator in pure C"
     LANGUAGES C CXX
 )

data/vendor-src/libleptris/bindings/rust/descriptor/src/lib.rs

@@ -31,6 +31,11 @@ pub const PLAN_KIND_NESTED: PlanKind = 3;
 pub const PLAN_KIND_RAW: PlanKind = 4;
 pub const PLAN_KIND_CONTENT: PlanKind = 5;
 pub const PLAN_KIND_CALLBACK: PlanKind = 6;
+/// #1552: catch-all row — binds every element child no named
+/// sibling row bound; emits one COLLECTION echoing the row
+/// wire_name/type_tag; `child_plan_index >= 0` walks members
+/// through that plan, else members are RAW serialized subtrees.
+pub const PLAN_KIND_WILDCARD: PlanKind = 7;
 
 /// Element plan flags.
 pub const PLAN_FLAG_MIXED_CONTENT: u32 = 0x1;
@@ -83,6 +88,9 @@ pub struct AttrPlan {
     pub pad_ns: u8,
     /// `PLAN_NS_EXACT` only.
     pub ns_uri: *const c_char,
+    /// #1551: intended wire prefix for serialized output
+    /// (`leptris_plan_serialize`); meaningful with EXACT.
+    pub ns_prefix: *const c_char,
 }
 
 /// Child binding row.
@@ -107,6 +115,9 @@ pub struct ChildPlan {
     pub predicate_count: u16,
     pub pad_pred: u16,
     pub predicates: *const AttrPredicate,
+    /// #1551: intended wire prefix for serialized output
+    /// (`leptris_plan_serialize`); meaningful with EXACT.
+    pub ns_prefix: *const c_char,
 }
 
 /// One element plan: the attribute and child rows bound to a name.
@@ -127,6 +138,9 @@ pub struct ElementPlan {
     /// `PLAN_FLAG_*`.
     pub flags: u16,
     pub pad1: u16,
+    /// #1551: the root plan's intended wire prefix for serialized
+    /// output (`leptris_plan_serialize`); meaningful with EXACT.
+    pub ns_prefix: *const c_char,
 }
 
 /// Top-level plan specification handed to the engine.

data/vendor-src/libleptris/bindings/rust/tests/descriptor_abi.rs

@@ -86,6 +86,7 @@ fn plan_build_and_walk_round_trip() {
         ns_form: descriptor::PLAN_NS_NONE,
         pad_ns: 0,
         ns_uri: ptr::null(),
+        ns_prefix: ptr::null(),
     };
     let child_row = descriptor::ChildPlan {
         wire_name: title.as_ptr(),
@@ -98,6 +99,7 @@ fn plan_build_and_walk_round_trip() {
         predicate_count: 0,
         pad_pred: 0,
         predicates: ptr::null(),
+        ns_prefix: ptr::null(),
     };
     let book_plan = descriptor::ElementPlan {
         element_name: book.as_ptr(),
@@ -110,6 +112,7 @@ fn plan_build_and_walk_round_trip() {
         child_plans: &child_row,
         flags: 0,
         pad1: 0,
+        ns_prefix: ptr::null(),
     };
     let root_child = descriptor::ChildPlan {
         wire_name: book.as_ptr(),
@@ -124,6 +127,7 @@ fn plan_build_and_walk_round_trip() {
         predicate_count: 0,
         pad_pred: 0,
         predicates: ptr::null(),
+        ns_prefix: ptr::null(),
     };
     let root_plan = descriptor::ElementPlan {
         element_name: catalog.as_ptr(),
@@ -136,6 +140,7 @@ fn plan_build_and_walk_round_trip() {
         child_plans: &root_child,
         flags: 0,
         pad1: 0,
+        ns_prefix: ptr::null(),
     };
     let plans = [root_plan, book_plan];
     let spec = descriptor::PlanSpec {

data/vendor-src/libleptris/src/include/leptris/descriptor.h

@@ -65,7 +65,18 @@ typedef enum {
     LEPTRIS_PLAN_KIND_NESTED = 3,     /* recurse into plans[child_plan_index] */
     LEPTRIS_PLAN_KIND_RAW = 4,        /* verbatim serialized subtree */
     LEPTRIS_PLAN_KIND_CONTENT = 5,    /* mixed-content text runs, doc order */
-    LEPTRIS_PLAN_KIND_CALLBACK = 6    /* escape hatch: raw value + position */
+    LEPTRIS_PLAN_KIND_CALLBACK = 6,   /* escape hatch: raw value + position */
+    /* #1552: catch-all row. Binds every element child that no
+     * named sibling row bound — named rows take precedence
+     * regardless of row-list position. Emits exactly one
+     * COLLECTION echoing the row's wire_name/type_tag (even when
+     * the remainder is empty). Members keep document order and
+     * echo the row type_tag. The row's ns_form filters members;
+     * an unset form means ANY namespace (catch-all), unlike
+     * named rows' historical NONE. child_plan_index >= 0 walks
+     * each member through that plan (ELEMENT members); -1 emits
+     * RAW serialized subtrees. */
+    LEPTRIS_PLAN_KIND_WILDCARD = 7    /* remainder bucket, named rows win */
 } LeptrisPlanKind;
 
 /* Element plan flags. */
@@ -118,6 +129,12 @@ typedef struct {
     uint8_t ns_form;       /* LeptrisPlanNsForm */
     uint8_t pad_ns;
     const char* ns_uri;    /* LEPTRIS_PLAN_NS_EXACT only */
+    /* #1551 (additive trailing field, the #1115 pattern): the
+     * intended wire prefix for serialized output. With ns_form
+     * EXACT, plan-path serialization emits the attribute as
+     * "ns_prefix:wire_name" (wire_name is the LOCAL name). NULL
+     * keeps matching-only behavior. */
+    const char* ns_prefix;
 } leptris_attr_plan;
 
 typedef struct {
@@ -137,6 +154,10 @@ typedef struct {
      * zero value) keeps the historical no-namespace+NS_LENIENT
      * behavior — the fields are consulted only when set. */
     uint8_t ns_form;       /* LeptrisPlanNsForm */
+    /* #1552 WILDCARD rows only: nonzero marks ns_form as
+     * explicitly set — ns_form 0 then binds no-namespace
+     * remainder alone. Unset (0), the row is the catch-all ANY
+     * default. Ignored by named rows. */
     uint8_t pad0;
     const char* ns_uri;    /* LEPTRIS_PLAN_NS_EXACT only */
     /* #1272: element-side predicates. Same semantics as attr_predicate
@@ -144,6 +165,12 @@ typedef struct {
     uint16_t predicate_count;
     uint16_t pad_pred;
     const leptris_attr_predicate* predicates;
+    /* #1551 (additive trailing field): the intended wire prefix
+     * for serialized output. With ns_form EXACT, the walk stamps
+     * the binding on values and plan-path serialization emits
+     * "ns_prefix:local" and the xmlns declaration (once, on the
+     * output root). NULL keeps matching-only behavior. */
+    const char* ns_prefix;
 } leptris_child_plan;
 
 typedef struct {
@@ -159,6 +186,9 @@ typedef struct {
     const leptris_child_plan* child_plans;
     uint16_t flags; /* LEPTRIS_PLAN_FLAG_* */
     uint16_t pad1;
+    /* #1551 (additive trailing field): the root plan's intended
+     * wire prefix, same contract as the child-row field. */
+    const char* ns_prefix;
 } leptris_element_plan;
 
 typedef struct {
@@ -222,6 +252,20 @@ LEPTRIS_API LeptrisPlanResult leptris_plan_walk(LeptrisDocument doc,
                                                 LeptrisStatus* status);
 LEPTRIS_API void leptris_plan_result_free(LeptrisPlanResult result);
 
+/* #1551: serialize a walk result back to XML, guided by its plan.
+ * The plan supplies element wrappers (row wire_name + ns_prefix)
+ * and the result supplies content; children emit in document order
+ * (the walk's order_index). Rows carrying ns_form EXACT +
+ * ns_prefix emit prefixed names, and every distinct (prefix, uri)
+ * pair used anywhere in the tree is declared exactly once, on the
+ * output root element, in first-encounter order. Attribute rows
+ * with ns_prefix emit "prefix:local". Text and attribute values
+ * are escaped; RAW members are verbatim. Returns a caller-freed
+ * string (leptris_free_string); NULL + status on failure. */
+LEPTRIS_API char* leptris_plan_serialize(LeptrisPlan plan,
+                                         const LeptrisPlanResult result,
+                                         LeptrisStatus* status);
+
 /* ---- Result accessors (NULL-tolerant: NULL in, 0/NULL out) ------- */
 
 LEPTRIS_API LeptrisPlanValueKind leptris_plan_value_kind(const LeptrisPlanResult v);