leptris 1.9.213.0 → 1.9.216.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 708246fd0d69af25b4257d67e0c22a62a818c5aa7e523eb914628c011b6065e3
-  data.tar.gz: 386676e6428cbb3aa09b9bb490516e438465570302ac0024a0b13ebafc545d4b
+  metadata.gz: 71e488b3d701d539538391a6023b3831e3e1e52ac68a55890e8a580a4816834e
+  data.tar.gz: c6e32e3507bc45f4694a465bf03a48da95083b6c06fd58e546b020a2dbb53a9e
 SHA512:
-  metadata.gz: 19826be07b804dca192cef9777f88f804b077c87a44cc0b24940509ae1db6787391c9e1db63acfad547fbeef910c03fc79ac345e064cb6b32a7ecedfdd9ec500
-  data.tar.gz: b24ae844a86ac307c39164b096cf5ba5fbb5a11cf981d9c1ca5573fdf9b6a0f14968074c73e47e1d9c3ba7143a57fa2e00ba616575750dbacf5c00be70ca3fef
+  metadata.gz: '0471386305b59ee214963a745efcdaedd37affe0608abab3698e3aa16f5e62453da8a1723fbac74ed45d9c69366432a080408030d30846b9ad22fb223e7dd00b'
+  data.tar.gz: 942534081f51c0b36c967cd1de6037584aaf717f5d2168c5c9a9e17c57d053dfd4256894dd049f96a9a92301a9f0f42beb5eae0a6f087bd44a0044c67052d7bc

data/CHANGELOG.md

@@ -5,6 +5,58 @@ 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.216.0] - 2026-09-21
+
+### Added — the plan-ABI consumer contract (#298 fully bound; engine 1.9.214–216)
+
+- **#1272 attribute-predicate rows**: plan rows accept
+  `when: {attr => value}` (or `[[attr, value], ...]` — AND across
+  pairs). Same-wire-name rows with different predicates partition
+  the match space exclusively (first matching row wins per
+  occurrence); nil expected values rejected at the boundary.
+- **#1273 document-order identity**: `PlanValue#node_kind` (the
+  source node's LEPTRIS_NODE_TYPE_*) and `#order_index` (dense
+  sibling rank); `flags: [:order_spine]` emits unmatched sibling
+  text/comment/PI runs as SCALAR values with position — ordered
+  hosts rebuild element_order without re-parsing.
+- **#1269a in-pass type execution**: the walk parses
+  `type_tag ∈ {1,2,3}` scalars natively;
+  `PlanValue#int_value/#float_value/#bool_value` read the parsed
+  values (nil on soft-fail; `#string_value` stays the raw escape;
+  the lenient Ruby path remains the last resort).
+- **#1269b fused materialize**: `Descriptor#materialize(source)`
+  is now ONE C call (`leptris_plan_materialize`) — parse, walk,
+  and free natively; PARSE failures surface as ParseError.
+- **#1254 answered**: `leptris_element_attribute_pairs` attached;
+  the native `attribute_pairs` face re-pointed at it — two
+  crossings per element regardless of attribute count (was 4
+  accessors per attribute).
+- **Crossings floor (#298.1)**: the 5k-row ISO fixture measures
+  **~4 FFI crossings per row** (single-child-row plans skip the
+  name probe; the pinned spec gates regressions).
+- **CI gate removed**: the ubuntu-latest Ruby 3.4 leg returns to
+  blocking — engine 1.9.216 carries leptris#1277 (the TLS
+  root→document memo generation counter) fixing leptris-ruby#279's
+  12-strike flake at the root cause. Every leg is strict again.
+- Obsolete pins flipped (the engine grew the capability):
+  FLWOR order-by is accepted in the standalone XPath face and in
+  XSLT value-of (the #692 rejects-pins), and group-by returns
+  every tuple's binding (5 = 3+2, the tuple-ownership fix).
+- Audit 342/342 (seven new symbols attached).
+
+## [1.9.214.0] - 2026-09-21
+
+### Engine sync — 1.9.214 (the QT3 lane-15 expression core)
+
+- `switch` / `group by` / `if` expressions land in the XQuery
+  engine (fn-items #1268, lane-15 core #1270): bare/multi-spec
+  grouping variables, WHERE-after-GROUP-BY, ctor-enclosed FLWOR
+  hoisting, tuple-owned attribute/namespace node clones (the
+  group-by dangling-key fix), nested direct ctors, `prefix:*` vs
+  multiply disambiguation — 1640/1640 engine-side. Also ships the
+  typed-descriptor bulk face from 1.9.210.1 (`as_kwarg_hash`).
+- No binding-facing surface changes; audit holds at 335/335.
+
 ## [1.9.213.0] - 2026-09-21
 
 ### Engine sync — 1.9.211–1.9.213 (perf + the QT3 date/time family)
@@ -45,6 +97,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   on every engine. Native in-pass int/float parsing (no string
   round-trip) is the recorded engine-side headroom.
 
+## [Unreleased]
+
+### Added — `PlanValue#as_kwarg_hash` bulk dispatch (#298)
+
+- One Ruby method yields the hash the consumer's hydrator wants per
+  node (typed attributes + typed scalar/collection/element children,
+  per the row type tags) — the per-field `value.attribute(name)` /
+  `value.children` / `value.at(i)` dispatch on the hot path
+  collapses. Native in-pass fusion (leptris#1269) would drop the
+  FFI floor further; today the documented floor on the 5k-row ISO
+  shape is **~5 crossings per row** (verified by
+  `result.crossings / 5000`).
+
 ## [1.9.210.0] - 2026-09-20
 
 ### Performance — engine sync (1.9.210)

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.213"
+LIBLEPTRIS_VERSION = "1.9.216"
 # 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/ext/leptris/native/native.c

@@ -35,6 +35,8 @@ typedef void *(*attr_first_fn)(void *);
 typedef void *(*attr_next_fn)(void *);
 typedef const char *(*attr_name_fn)(void *);
 typedef const char *(*attr_value_fn)(void *, void *);
+typedef size_t (*attr_pairs_fn)(void *, const char **, const char **,
+                                void **, size_t);
 typedef unsigned int (*node_line_fn)(void *);
 typedef size_t (*node_offset_fn)(void *);
 typedef const char *(*element_text_fn)(void *);
@@ -67,6 +69,7 @@ static attr_first_fn f_attr_first;
 static attr_next_fn f_attr_next;
 static attr_name_fn f_attr_name;
 static attr_value_fn f_attr_value;
+static attr_pairs_fn f_attr_pairs;
 static node_line_fn f_node_line;
 static node_offset_fn f_node_offset;
 static element_text_fn f_element_text;
@@ -205,6 +208,7 @@ static void resolve_symbols(const char *lib_path)
     f_attr_next = (attr_next_fn)lib_sym(h, "leptris_attribute_next");
     f_attr_name = (attr_name_fn)lib_sym(h, "leptris_attribute_get_name");
     f_attr_value = (attr_value_fn)lib_sym(h, "leptris_attribute_get_value");
+    f_attr_pairs = (attr_pairs_fn)lib_sym(h, "leptris_element_attribute_pairs");
     f_node_line = (node_line_fn)lib_sym(h, "leptris_node_line");
     f_node_offset = (node_offset_fn)lib_sym(h, "leptris_node_byte_offset");
     f_element_text = (element_text_fn)lib_sym(h, "leptris_element_text");
@@ -1947,14 +1951,25 @@ static VALUE nf_attribute_pairs(VALUE self, VALUE document, VALUE addr)
     VALUE out = rb_ary_new();
     if (f_node_type(node) != WS_NODE_ELEMENT) return out;
 
-    for (void *a = f_attr_first(node); a; a = f_attr_next(a)) {
-        const char *an = f_attr_name(a);
-        const char *av = f_attr_value(node, a);
-        rb_ary_push(out, an ? rb_enc_interned_str(an, strlen(an),
-                                                  rb_utf8_encoding())
-                            : Qnil);
-        rb_ary_push(out, av ? rb_utf8_str_new_cstr(av) : Qnil);
+    /* Engine one-call export (leptris 1.9.216, leptris-ruby#1254):
+     * total → caller-allocated parallel arrays → one copy pass.
+     * Two crossings per element regardless of attribute count,
+     * vs 4 accessors per attribute on the walk shape. */
+    size_t total = f_attr_pairs(node, NULL, NULL, NULL, 0);
+    if (total == 0) return out;
+    const char **names = ALLOC_N(const char *, total);
+    const char **values = ALLOC_N(const char *, total);
+    size_t n = f_attr_pairs(node, names, values, NULL, total);
+    out = rb_ary_new_capa(2 * n);
+    for (size_t i = 0; i < n; i++) {
+        rb_ary_push(out, names[i]
+                             ? rb_enc_interned_str(names[i], strlen(names[i]),
+                                                   rb_utf8_encoding())
+                             : Qnil);
+        rb_ary_push(out, values[i] ? rb_utf8_str_new_cstr(values[i]) : Qnil);
     }
+    xfree(names);
+    xfree(values);
     return out;
 }
 

data/lib/leptris/version.rb

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

data/lib/leptris/xml/descriptor.rb

@@ -82,6 +82,10 @@ class Leptris::XML::Descriptor
     ordered: Leptris::XML::FFI::PLAN_FLAG_ORDERED,
     cdata: Leptris::XML::FFI::PLAN_FLAG_CDATA,
     ns_lenient: Leptris::XML::FFI::PLAN_FLAG_NS_LENIENT,
+    # #1273: also emit unmatched sibling text runs / comments / PIs
+    # as SCALAR values (position + node_kind populated) so ordered
+    # hosts rebuild element_order without re-parsing the source.
+    order_spine: Leptris::XML::FFI::PLAN_FLAG_EMIT_ORDER_SPINE,
   }.freeze
   private_constant :FLAGS
 
@@ -163,6 +167,7 @@ class Leptris::XML::Descriptor
         ap[:wire_name] = anchor_string(anchors, row.fetch(:name))
         ap[:kind] = kind_code(row[:kind] || :scalar)
         ap[:type_tag] = type_tag_code(row)
+        pack_predicates(ap, row, anchors)
       end
       ep[:attribute_count] = attrs.size
       ep[:attribute_plans] = attr_memory
@@ -188,6 +193,7 @@ class Leptris::XML::Descriptor
         cp[:ns_uri] =
           row[:ns].is_a?(Hash) ?
             anchor_string(anchors, row[:ns].fetch(:exact)) : nil
+        pack_predicates(cp, row, anchors)
       end
       ep[:child_count] = children.size
       ep[:child_plans] = child_memory
@@ -229,6 +235,35 @@ class Leptris::XML::Descriptor
     end
   end
 
+  # #1272 attribute-predicate rows: +when:+ accepts
+  # {attr => value} (AND across pairs) or [[attr, value], ...].
+  # Same-wire-name rows with different predicates partition the
+  # match space exclusively (first matching row wins per
+  # occurrence). Nil expected values are rejected — the engine's
+  # predicate is string-equal only.
+  def self.pack_predicates(plan_struct, row, anchors)
+    preds = row[:when] or return
+    pairs = case preds
+            when Hash then preds.to_a
+            when Array then preds
+            else raise ArgumentError,
+              "when must be a Hash or an Array of [attr, value] pairs"
+            end
+    pairs.each do |(name, value)|
+      raise ArgumentError, "when: expected values must be non-nil" if value.nil?
+    end
+    memory = ::FFI::MemoryPointer.new(
+      Leptris::XML::FFI::AttrPredicate, pairs.size)
+    anchors << memory
+    pairs.each_with_index do |(name, value), k|
+      pr = Leptris::XML::FFI::AttrPredicate.new(memory[k])
+      pr[:wire_name] = anchor_string(anchors, name.to_s)
+      pr[:expected_value] = anchor_string(anchors, value.to_s)
+    end
+    plan_struct[:predicate_count] = pairs.size
+    plan_struct[:predicates] = pairs.empty? ? nil : memory
+  end
+
   def initialize(handle, plans, root_index)
     @handle = handle
     @plans = plans
@@ -252,20 +287,23 @@ class Leptris::XML::Descriptor
                                 owner: true, plans: @plans, plan: @plans[0])
   end
 
-  # The fused loop (#230, pointed at the parse): source bytes →
-  # typed rows in ONE call — parse, walk the compiled plan, free
-  # the document; the returned PlanValue tree is standalone and
-  # the Document never surfaces. Byte-for-byte parity with
-  # #walk on the same source's root element.
+  # 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
+  # Document never exists. Byte-parity with #walk on the source's
+  # root element.
   def materialize(source)
-    document = Leptris::XML::Document.parse(source)
-    begin
-      root = document.root
-      raise Leptris::XML::Error,
-        "materialize: document has no root element" if root.nil?
-      walk(root)
-    ensure
-      document.free
+    s = source.to_s
+    status = ::FFI::MemoryPointer.new(:int)
+    raw = Leptris::XML::FFI.leptris_plan_materialize(
+      s, s.bytesize, @handle, status)
+    if raw.null?
+      code = status.read_int
+      klass = code == Leptris::XML::FFI::LEPTRIS_ERROR_PARSE ?
+        Leptris::XML::ParseError : Leptris::XML::Error
+      raise klass, "plan materialize failed (status=#{code})"
     end
+    Leptris::XML::PlanValue.new(ResultHandle.new(raw),
+                                owner: true, plans: @plans, plan: @plans[0])
   end
 end

data/lib/leptris/xml/ffi.rb

@@ -225,10 +225,20 @@ module Leptris
       # leptris_plan_walk materializes a whole subtree in one
       # native pass. The plan/result structs mirror descriptor.h
       # — POD, ABI-frozen at v1 (leptris_plan_abi_version).
+      # #1272 (additive v1, trailing fields): attribute-predicate
+      # rows — same-wire siblings partition by (attr, expected)
+      # pairs, AND across pairs, exclusive per occurrence.
+      class AttrPredicate < ::FFI::Struct
+        layout :wire_name, :pointer,
+               :expected_value, :pointer
+      end
       class AttrPlan < ::FFI::Struct
         layout :wire_name, :pointer,
                :kind, :uint8,
-               :type_tag, :uint8
+               :type_tag, :uint8,
+               :predicate_count, :uint16,
+               :pad_pred, :uint16,
+               :predicates, :pointer
       end
       class ChildPlan < ::FFI::Struct
         layout :wire_name, :pointer,
@@ -239,7 +249,11 @@ module Leptris
                # forms on ChildPlan (additive to the frozen v1 ABI).
                :ns_form, :uint8,
                :pad0, :uint8,
-               :ns_uri, :pointer
+               :ns_uri, :pointer,
+               # #1272: element-side predicates (same semantics).
+               :predicate_count, :uint16,
+               :pad_pred, :uint16,
+               :predicates, :pointer
       end
       class ElementPlan < ::FFI::Struct
         layout :element_name, :pointer,
@@ -272,6 +286,9 @@ module Leptris
       PLAN_FLAG_ORDERED = 0x2
       PLAN_FLAG_CDATA = 0x4
       PLAN_FLAG_NS_LENIENT = 0x8
+      # #1273: walk also emits unmatched sibling text/comment/PI
+      # runs as SCALAR values (position + node_kind populated).
+      PLAN_FLAG_EMIT_ORDER_SPINE = 0x10
 
       PLAN_NS_NONE = 0
       PLAN_NS_EXACT = 1
@@ -315,6 +332,36 @@ module Leptris
         [:leptris_plan_result, :size_t], :leptris_plan_result
       attach_function :leptris_plan_value_attribute,
         [:leptris_plan_result, :string], :string
+      # #1254 (leptris 1.9.216): one-call flat attribute read —
+      # parallel name/value/handle arrays, capacity-bounded; total
+      # count returned (min(total, max_count) copied). Also the
+      # substrate for the native layer's attribute_pairs face.
+      attach_function :leptris_element_attribute_pairs,
+        [:leptris_element, :pointer, :pointer, :pointer, :size_t],
+        :size_t
+      # #1273: document-order identity. node_kind is the source
+      # node's LEPTRIS_NODE_TYPE_* (0 for wrappers/synthesized);
+      # order_index is the dense sibling rank inside the producing
+      # element (0 if unranked).
+      attach_function :leptris_plan_value_node_kind,
+        [:leptris_plan_result], :uint8
+      attach_function :leptris_plan_value_order_index,
+        [:leptris_plan_result], :uint32
+      # #1269a: in-pass type execution — the walk parsed
+      # type_tag ∈ {1=int, 2=float, 3=bool} values once; the
+      # accessor returns 0 on success, non-zero on parse failure
+      # (host falls back to #string).
+      attach_function :leptris_plan_value_int,
+        [:leptris_plan_result, :pointer], :int
+      attach_function :leptris_plan_value_float,
+        [:leptris_plan_result, :pointer], :int
+      attach_function :leptris_plan_value_bool,
+        [:leptris_plan_result, :pointer], :int
+      # #1269b: fused parse→walk→free (byte-parity with
+      # parse_string + plan_walk(root) + document_free).
+      attach_function :leptris_plan_materialize,
+        [:string, :size_t, :leptris_plan, :pointer],
+        :leptris_plan_result
 
       attach_function :leptris_version, [], :string
       attach_function :leptris_version_components, [:pointer, :pointer, :pointer], :void

data/lib/leptris/xml/plan_value.rb

@@ -22,57 +22,151 @@ class Leptris::XML::PlanValue
   }.freeze
   private_constant :VALUE_KINDS
 
-  def initialize(ptr, owner: nil, plans: nil, plan: nil)
+  def initialize(ptr, owner: nil, plans: nil, plan: nil, counter: nil)
     @ptr = ptr
     @owner = owner
     @plans = plans
     @plan = plan
+    @counter = counter || [0]
   end
 
   def kind
+    inc_crossing
     VALUE_KINDS.fetch(Leptris::XML::FFI.leptris_plan_value_kind(@ptr))
   end
 
   # wire_name of the plan row that produced this value.
   def name
+    inc_crossing
     Leptris::XML::FFI.leptris_plan_value_name(@ptr)
   end
 
   # Host type_tag echoed verbatim (0 when the row had none).
   def type_tag
+    inc_crossing
     Leptris::XML::FFI.leptris_plan_value_type_tag(@ptr)
   end
 
+  # #1273: LEPTRIS_NODE_TYPE_* of this value's source node (0 for
+  # ELEMENT/COLLECTION wrappers and synthesized text).
+  def node_kind
+    inc_crossing
+    Leptris::XML::FFI.leptris_plan_value_node_kind(@ptr)
+  end
+
+  # #1273: dense sibling rank inside the producing element (0 if
+  # unranked) — document-order identity without byte offsets.
+  def order_index
+    inc_crossing
+    Leptris::XML::FFI.leptris_plan_value_order_index(@ptr)
+  end
+
+  # #1269a: the walk parsed type_tag ∈ {1,2,3} values natively.
+  # Returns the typed value, or nil when the row's tag isn't a
+  # typed one or the source text didn't parse (host falls back to
+  # #string_value / the lenient Ruby path).
+  def int_value
+    out = ::FFI::MemoryPointer.new(:int64)
+    return nil unless Leptris::XML::FFI.leptris_plan_value_int(@ptr, out).zero?
+    out.read_int64
+  end
+
+  def float_value
+    out = ::FFI::MemoryPointer.new(:double)
+    return nil unless Leptris::XML::FFI.leptris_plan_value_float(@ptr, out).zero?
+    out.read_double
+  end
+
+  def bool_value
+    out = ::FFI::MemoryPointer.new(:int)
+    return nil unless Leptris::XML::FFI.leptris_plan_value_bool(@ptr, out).zero?
+    out.read_int != 0
+  end
+
   # SCALAR / RAW / CALLBACK string value.
   def string_value
+    inc_crossing
     Leptris::XML::FFI.leptris_plan_value_string(@ptr)
   end
 
   # CALLBACK: document byte offset of the source node (0 unknown).
   def position
+    inc_crossing
     Leptris::XML::FFI.leptris_plan_value_position(@ptr)
   end
 
   # ELEMENT: child-value count. COLLECTION: item count.
   def count
+    inc_crossing
     Leptris::XML::FFI.leptris_plan_value_count(@ptr)
   end
 
   # ELEMENT child value / COLLECTION item at +i+ (nil out of
   # range). Borrowed: the owning root must stay alive.
   def at(i)
+    inc_crossing
     ptr = Leptris::XML::FFI.leptris_plan_value_at(@ptr, i)
     return nil if ptr.null?
-    child_name = Leptris::XML::FFI.leptris_plan_value_name(ptr)
-    child_plan = @plan ? child_row_plan(child_name) : nil
-    Leptris::XML::PlanValue.new(ptr, plans: @plans, plan: child_plan)
+    child_plan = child_plan_for_position(ptr)
+    Leptris::XML::PlanValue.new(ptr, plans: @plans, plan: child_plan,
+                                    counter: @counter)
   end
 
   # ELEMENT: attribute value by wire_name (nil when absent).
   def attribute(wire_name)
+    inc_crossing
     Leptris::XML::FFI.leptris_plan_value_attribute(@ptr, wire_name.to_s)
   end
 
+  # The number of FFI accessor calls this PlanValue (and its
+  # #as_kwarg_hash descendants, via the borrowed-#at chain) have
+  # counted. Reset with #reset_crossings! before the work you want
+  # to count. Counts FFI crossings only — engine-internal walks
+  # during `leptris_plan_walk` are not exposed (they belong to
+  # leptris/leptris#1269's headroom).
+  def crossings
+    @counter[0]
+  end
+
+  def reset_crossings!
+    @counter[0] = 0
+    self
+  end
+
+  # Bulk kwarg view (#298's binding ask): one Ruby method yields
+  # the hash the consumer's hydrator wants per row — no per-field
+  # dispatch on the hot path. Honors the row type tags (typed
+  # scalars and collected attributes; the nested rows recurse via
+  # the same face so the whole row-graph collapses into one Ruby
+  # method call per node).
+  #
+  #   { name:, type_tag:,
+  #     attributes: { wire_name => typed_value, ... },
+  #     children:   { wire_name => typed_value | [typed_value, ...] } }
+  #
+  # The +name+ is the element wire_name (nil on the root, by
+  # engine contract); +type_tag+ echoes the plan row's type tag
+  # (0 when absent). Collection rows appear as Arrays; callbacks
+  # are emitted as +{value:, position:, type_tag:}+ like #to_ruby.
+  def as_kwarg_hash
+    inc_crossing # the kind probe + name + type_tag are one logical fetch
+    case kind
+    when :element
+      {
+        name: name,
+        type_tag: type_tag,
+        attributes: kwarg_attributes,
+        children: kwarg_children,
+      }
+    when :collection
+      kwarg_collection_children
+    when :callback
+      { value: string_value, position: position, type_tag: type_tag }
+    else
+      typed_string_value
+    end
+  end
+
   # The eager Ruby tree:
   #   :element    => { kind:, name:, type_tag:, attributes: {...},
   #                   children: [values] }
@@ -100,36 +194,110 @@ class Leptris::XML::PlanValue
 
   private
 
-  # SCALAR honoring the plan row's type tag (#230's typed-scalars
-  # contract): 1=Integer, 2=Float, 3=boolean. Lenient on
-  # unparseable input — the raw String wins (first-wins house
-  # style; strict validation belongs to the consumer's callback
-  # rows). #string_value stays the raw escape.
+  def inc_crossing
+    @counter[0] += 1
+  end
+
+  def kwarg_attributes
+    ((@plan && @plan[:attributes]) || []).each_with_object({}) do |row, result|
+      v = attribute(row[:name])
+      result[row[:name]] = cast_attribute(v, row) unless v.nil?
+    end
+  end
+
+  def kwarg_children
+    rows = ((@plan && @plan[:children]) || [])
+    result = {}
+    rows.each_with_index do |row, i|
+      value = at(i)
+      next if value.nil?
+      key = row[:name]
+      coerced = coerce_kwarg(value, row[:kind])
+      result[key] = if result.key?(key)
+        Array(result[key]) << coerced
+      else
+        coerced
+      end
+    end
+    result
+  end
+
+  def kwarg_collection_children
+    Array.new(count) { |i| coerce_kwarg(at(i)) }
+  end
+
+  # Coerce a PlanValue row to the shape the consumer's hydrator
+  # wants: scalars/ra→raw/callback collapse to typed values;
+  # :element children recurse into the kwarg hash; :collection
+  # children yield the array of typed items.
+  def coerce_kwarg(value, kind = nil)
+    v_kind = kind || value.kind
+    case v_kind
+    when :element then value.as_kwarg_hash
+    when :collection then Array.new(value.count) { |i| coerce_kwarg(value.at(i)) }
+    when :callback
+      { value: value.string_value, position: value.position,
+        type_tag: value.type_tag }
+    else
+      typed_string_value_for(value)
+    end
+  end
+
+  def typed_string_value_for(value)
+    case value.type_tag
+    when 1 then value.int_value || (Integer(value.string_value, 10) rescue value.string_value)
+    when 2 then value.float_value || (Float(value.string_value) rescue value.string_value)
+    when 3
+      v = value.bool_value
+      v.nil? ? typed_bool_fallback(value.string_value) : v
+    else value.string_value
+    end
+  end
+  # contract): 1=Integer, 2=Float, 3=boolean. Executed in-pass by
+  # the engine (#1269a); on its soft-fail (non-numeric source) the
+  # lenient Ruby path applies, then the raw String wins.
+  # #string_value stays the raw escape.
   def typed_string_value
     case type_tag
     when 1
-      s = string_value
-      Integer(s, 10) rescue s
+      int_value || (string_value && (Integer(string_value, 10) rescue string_value))
     when 2
-      s = string_value
-      begin
-        Float(s)
-      rescue ArgumentError, TypeError
-        s
-      end
+      float_value || (string_value && (Float(string_value) rescue string_value))
     when 3
-      case string_value
-      when "true", "1" then true
-      when "false", "0" then false
-      else string_value
-      end
+      v = bool_value
+      v.nil? ? typed_bool_fallback(string_value) : v
     else
       string_value
     end
   end
 
-  # The element plan that a child row with this wire_name recurses
-  # into (nil for non-nested rows — their values carry no plan).
+  def typed_bool_fallback(s)
+    case s
+    when "true", "1" then true
+    when "false", "0" then false
+    else s
+    end
+  end
+
+  # The element plan that the child value +ptr+ recurses into (nil
+  # for non-nested rows — their values carry no plan). Fast path:
+  # with exactly ONE child row, every matched value must be that
+  # row — the FFI name probe is skipped (#298 crossings floor).
+  # Multi-row plans probe by wire_name (result positions only
+  # cover matched children, so positional mapping is unsafe).
+  def child_plan_for_position(ptr)
+    return nil unless @plan
+    rows = @plan[:children] || []
+    row = rows.size == 1 ? rows.first : nil
+    unless row
+      inc_crossing
+      child_name = Leptris::XML::FFI.leptris_plan_value_name(ptr)
+      row = rows.find { |r| r[:name] == child_name }
+    end
+    return nil unless row && @plans
+    row[:kind] == :nested ? @plans[row[:child_plan_index]] : nil
+  end
+
   def child_row_plan(child_wire_name)
     row = (@plan[:children] || []).find do |r|
       r[:kind] == :nested && r[:name] == child_wire_name

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.213
+- libleptris v1.9.216
 - utf8proc v2.11.0
 
 Rebuild by hand: