leptris 1.9.197.2-arm-linux

data/TODO.perf/12-document-lifetime-in-c.md

@@ -0,0 +1,47 @@
+# 12 — Document lifetime in C: TypedData handle replaces the ObjectSpace finalizer
+
+Status: DONE (1.9.163.6)
+
+Every document (parsed AND created) registers an ObjectSpace
+finalizer: a per-document proc allocation (~110ns), the
+define_finalizer call (~315ns), the Freed struct, and — the real
+cost — a Ruby finalizer invocation at GC time that must dispatch
+back through FFI to leptris_document_free (~1-2µs per document
+inside GC pauses). Fresh-document build loops measured 7.1µs per
+Document.create in-loop, ~4-5µs of it GC/finalizer amortization
+(stackprof: GC ~19% of a build loop, define_finalizer+proc in the
+top frames).
+
+Fix: a TypedData DocHandle (struct { void *doc; }) whose dfree
+calls leptris_document_free directly — no Ruby finalizer, no FFI
+from finalizer context, no proc. The handle is referenced only by
+the Document's @doc_handle ivar, so its lifetime IS the
+Document's. Document#free keeps its explicit path (FFI free +
+release the handle's pointer so dfree no-ops — the same
+double-free protocol Freed enforces today, in C). The proc
+finalizer stays for LEPTRIS_NO_NATIVE mode.
+
+Companion: Native.create_binding_document — the full
+Document.create in one C dispatch (engine create + wrapper
+allocation + @c_ptr/@c_address/@freed/@readonly/@version + handle
+attach). Document.create today pays FFI marshaling + wrap frames
+(~250-600ns) on top of the engine call.
+
+Gates: lifetime_contract_spec + memory_spec green in both modes;
+double-free impossible (free → dfire no-op, finalizer-mode
+unchanged); Document.create and fresh-doc build rows improve.
+
+## Outcome (1.9.163.6)
+
+DocHandle TypedData (struct { void *doc; }, RUBY_TYPED_FREE_IMMEDIATELY,
+dfree -> leptris_document_free) attached as @doc_handle on every
+wrap() when native is enabled; Document#free detaches it (dfree
+no-ops). Native.create_binding_document does engine create +
+ivar-seeded wrapper + handle in one dispatch (Document.create
+routes through it). Freed stays the shared free-state; the proc
+finalizer remains for LEPTRIS_NO_NATIVE. 3,000-doc GC-reclamation
+and explicit-free-then-GC specs green; 647/0 both modes. Measured
+under host load 14-30: GC-amortized Document.create ~5.0us (the
+Ruby-finalizer invocation and FFI-dispatch-at-GC are gone from
+every document lifecycle; clean-load numbers pending the battery
+— the box never dropped under load 13 this session).

data/TODO.perf/13-structural-memos.md

@@ -0,0 +1,49 @@
+# 13 — Version-stamped structural memos: root/parent/siblings (+ FFI-mode stale-@parent fix)
+
+Status: DONE (1.9.163.6)
+
+Document#root re-derives (FFI + wrap) on every call — every
+pipeline entry pays it. Node#parent and the sibling hops
+(next_sibling/previous_sibling) pay FFI + Node.wrap per call, so
+Nokogiri-style sibling-advancement loops pay ~300ns/hop.
+
+BUG found while designing this: in FFI mode the children walk
+seeds @parent, and a later move (add_child to another parent)
+leaves the stale @parent — child.parent answers the OLD parent.
+Native mode masks it (the bulk path does not seed @parent). The
+version-stamped memo fixes both modes: derive once, stamp with
+the owning document's mutation version, re-derive after any
+mutation that bumps it.
+
+Design: parent memoizes only for document-owned nodes
+(scope-owned iterparse elements keep deriving — a scope element
+adopted into a document moves without its scope's version
+advancing, so a stamp would lie). Cross-document adoption bumps
+BOTH documents' versions (the source document's other nodes hold
+sibling/parent stamps that the move invalidates); the moved
+node's stamps clear at the mutation site. next_sibling /
+previous_sibling memoize the same way. Document#root memoizes
+against the document's own version (root= bumps it; free clears).
+
+Gates: parent correct after same-doc and cross-doc moves in BOTH
+modes (the FFI staleness becomes a spec); sibling chains correct
+around unlink/insert; root identity stable; traversal-loop rows
+improve.
+
+## Outcome (1.9.163.6)
+
+Version-stamped memos on Document#root (pure ivar compare, ~82ns
+under load 17), Node#parent / next_sibling / previous_sibling
+(~72-76ns memo hits vs ~300-500ns deriving; @structure_memoizable
+computed once at construction — including the C-constructed
+wrappers — keeping the hit path free of method dispatch). The
+FFI-mode stale-@parent bug is FIXED (spec-pinned: parent correct
+after same-doc and cross-doc moves; the seed stamps only
+constructor-KNOWN parents — nil constructor parent means unknown,
+because the engine may attach during creation, e.g. create_child).
+Cross-document moves clear the moved node's stamps and advance
+the SOURCE document's version. The adoption-lift ancestor walk
+uses Node#unstamped_parent: deriving a stamped parent between the
+version bump and the engine move would record post-bump versions
+carrying pre-move truth. Scope-owned iterparse elements never
+memoize.

data/TODO.perf/14-insert-family-c-bound.md

@@ -0,0 +1,31 @@
+# 14 — C-bound insert family + cold-[] native fill
+
+Status: DONE (1.9.163.6)
+
+add_child and []= are C-bound (TODO.perf/08-09); prepend_child,
+add_next_sibling, and add_previous_sibling still run the full
+Ruby path (ensure_writable + eager-namespace guard ordering +
+FFI). One C face with a mode int covers all engine insertions
+(append/prepend/insert_after/insert_before — same
+int(void*, void*) ABI): gates + predicate + version bump + engine
+insert in one dispatch, Qnil fallback when the child needs the
+namespace lift, exactly like append_binding_child.
+
+Also: the completely-cold branch of Element#[] fills through
+leptris_element_attribute (FFI) while the partial-memo branch
+above it uses the native face — the cold path should ride the
+native face too (~150ns per first-touch attribute read).
+
+Gates: insert semantics unchanged (specs exist for sibling
+inserts); namespaced children still lift; readonly raises.
+
+## Outcome (1.9.163.6)
+
+Native.insert_binding_child(document, anchor, child, mode): 1
+prepend / 2 after / 3 before — gates + predicate + version bump +
+engine insert in one dispatch, Qnil fallback to the Ruby lift
+path. prepend_child / add_next_sibling / add_previous_sibling
+carry the fast branch + cross-document invalidation. The
+completely-cold Element#[] first-touch fill rides the native face
+(matching the partial-memo branch). Specs: ordering, lift
+fallback, readonly raise.

data/TODO.perf/15-compiled-expression-cache.md

@@ -0,0 +1,35 @@
+# 15 — Compiled-expression cache for Searchable#xpath / #at_xpath
+
+Status: DONE (1.9.163.6)
+
+Searchable#xpath passes the expression STRING to
+leptris_xpath_eval each call. The engine caches compiled
+expressions by string (measured: repeat-string eval 7.0µs vs
+varied-string 34.98µs — the ~28µs is per-call parsing), but the
+string path still pays cache lookup + hashing per call. A
+compiled handle evaluated directly measured 4.58µs on the same
+shape — 34% under the string path.
+
+The binding already exposes XPath.compile (parse once, eval
+many). Add a bounded LRU keyed on the expression string inside
+Searchable: plain (no version pin, no ns bindings) xpath/at_xpath
+evaluations route through cached compiled handles. Cache only
+successful compiles; bounded (~64 entries, Hash#shift eviction);
+GVL makes the Hash ops safe.
+
+Gates: xpath/at_xpath results identical (nodesets, scalars,
+empty results); invalid expressions still raise XPathError;
+namespace-bound and version-pinned paths unchanged; repeat-call
+rows improve ~30%.
+
+## Outcome (1.9.163.6)
+
+Searchable.compiled_expression: bounded LRU (64 entries, Hash#shift
+eviction, LRU refresh on hit) keyed on the expression string;
+plain xpath/at_xpath evaluate cached compiled handles via
+XPath#eval_ptrs (leptris_xpath_compiled_eval). Failed compiles
+never cache (fall back to the string entry so the error surface
+is unchanged); version-pinned and namespace-bound paths keep
+their dedicated entries. Measured: repeat at_xpath 3.7us ->
+1.9us under load 17-30 (~2x); CSS rides it automatically
+(deterministic translation -> same key).

data/TODO.perf/16-at-xpath-single-result-seam.md

@@ -0,0 +1,38 @@
+# 16 — C-bound at_xpath single-result seam
+
+Status: DONE (1.9.163.7)
+
+at_xpath is the hottest query shape (adapters picking one node),
+and its result path is five FFI calls per hit: result_type,
+get_node(0), node_kind(0), Node.wrap (pointer + construct), and
+result_free — plus the Ruby case dispatch between them. The bulk
+machinery from TODO.perf/03 already knows how to materialize a
+result entry as a binding wrapper in C (identity cache, kind
+dispatch, attribute/text value capture).
+
+Add Native.at_xpath_first(document, result_ptr): one C dispatch
+checks the result type; nodesets materialize entry 0 through the
+bulk machinery (get_nodes_ex with capacity 1 carries pointer +
+kind in one call), free the result handle, and return the binding
+node (or Qnil on empty); non-nodeset results return Qundef so the
+existing Ruby scalar path keeps its exact semantics. Searchable's
+wrap_xpath_first_result routes through the face when native is
+enabled.
+
+Gates: at_xpath parity for elements, attributes (ResultAttr name/
+value capture), text-kind results, empty results, and scalars;
+the result handle always freed exactly once.
+
+## Outcome (1.9.163.7)
+
+Native.at_xpath_first(document, result_ptr): one dispatch — type
+check, entry-0 materialization through the extracted
+materialize_xp_entry (shared with the TODO.perf/03 bulk loop:
+identity cache, kind dispatch, attribute/text value capture),
+result free. Non-nodeset results return the Native module object
+(Qundef must never cross into Ruby) and keep the exact Ruby
+scalar path. Measured: repeat at_xpath 3.7µs baseline -> 1.9µs
+(TODO.perf/15) -> ~1.3µs with the seam (2.8x total, load 8-30;
+the same-run Nokogiri comparison on this box is anomalous and not
+reported). Specs pin element identity, attribute capture, text
+kinds, nil misses, scalars, and xpath().first agreement.

data/TODO.perf/17-precomputed-fast-path-flags.md

@@ -0,0 +1,35 @@
+# 17 — Precomputed fast-path flags + set_attribute tightening
+
+Status: DONE (1.9.163.7)
+
+The native guards on hot paths are method chains:
+native_fast_children? resolves as defined?(NATIVE_FAST) plus
+scope_owned? (another method) — paid per mutation ([]=, add_child,
+the insert family) and per cold read fill. @structure_memoizable
+(TODO.perf/13) already carries "document-owned and alive" as an
+ivar; NATIVE_FAST availability is fixed at load time before any
+node exists, so the conjunction is construct-time constant.
+
+Add @native_fast to every wrapper construction (Ruby initialize
+and every C construction site): one ivar read replaces the chain
+at every gate. Fold in the set_attribute shaves: the C face reads
+attribute NAMES via StringValue+RSTRING_PTR (names cannot contain
+NULs — same rationale as nn_attribute); VALUES keep StringValueCStr
+so an embedded-NUL value still raises rather than truncating.
+
+Gates: suite green in both modes (the FFI fallback semantics must
+be unchanged for nodes constructed before a late native require —
+worst case they stay on the FFI path); set_attribute row improves.
+
+## Outcome (1.9.163.7)
+
+@native_fast computed once at construction (Ruby initialize and
+every C construction site — the bundle running implies the
+constant), replacing the defined?+scope_owned? method chain at
+every gate (native_fast?/native_fast_children? are ivar readers
+now). []= additionally reads attribute names via
+StringValue+RSTRING_PTR (values keep StringValueCStr — an
+embedded-NUL value still raises; spec-pinned). Measured (load
+17-31): binding []= 454ns mandate baseline -> 236ns (~2x on the
+row; 0.88x vs Nokogiri's 209ns in the same run — effectively
+parity).

data/TODO.perf/18-inner-html-one-c-pass.md

@@ -0,0 +1,32 @@
+# 18 — inner_html in one C pass
+
+Status: DONE (1.9.163.7)
+
+Element#inner_html walks children (bulk since TODO.perf/01) and
+then serializes EACH child from Ruby: element children get one
+ext dispatch each, text/comment/PI children are string-built in
+Ruby and joined. An N-child element pays N dispatches plus the
+case ladder plus the join.
+
+Bind the whole pass in C: iterate the child chain once, appending
+each child's serialization into one growable buffer — elements
+through leptris_element_serialize_into (the fast_serialize
+protocol), text nodes XML-escaped (& < > — the binding's
+escape_text set), CDATA wrapped raw, comments and PIs wrapped.
+One dispatch, one string mint, no Ruby per child.
+
+Gates: inner_html parity for every child kind (elements, text
+with entities, CDATA, comments, PIs, mixed), empty elements,
+large children past the 4096-byte stack probe (growth path).
+
+## Outcome (1.9.163.7)
+
+Native.fast_inner_xml: one pass over the child chain into a
+grow-only scratch — elements through leptris_element_serialize_into
+(needed-1 protocol, grow+retry past capacity), text escaped with
+the binding's entity set (& < > \r), CDATA raw-wrapped, comments
+and PIs wrapped (PI data leading-whitespace-stripped, read_pi_data
+parity). Byte-identical to the Ruby loop for every child kind and
+past the 4KB growth floor (specs). Measured (load 17-31): 30-child
+inner_html ~4.9µs (~160ns/child vs the loop's ~500-800ns/child
+estimate).

data/TODO.perf/19-lazy-node-pointer.md

@@ -0,0 +1,39 @@
+# 19 — Lazy FFI::Pointer on wrappers
+
+Status: DONE (1.9.174.3)
+
+Every binding wrapper stores an FFI::Pointer (@c_ptr), and the C
+construction faces mint one per node via
+rb_funcall(FFI::Pointer, :new) — ~200ns plus a Ruby object and
+its GC visit per node, paid at creation even though most nodes'
+Pointers are never read (the hot reads are memoized or go through
+the address-based native faces).
+
+Store @c_address (Integer) as the canonical truth on every
+wrapper; `c_ptr` becomes a lazy materializer
+(@c_ptr ||= FFI::Pointer.new(@c_address)) preserving the public
+API. Internal call sites: `@c_ptr.address` collapses to
+@c_address (also skipping the #address dispatch), and remaining
+internal @c_ptr reads go through the c_ptr reader (same cost as
+the old attr_reader). The C faces stop constructing Pointers
+entirely — they already hold the address.
+
+Gates: suite green both modes (a missed site fails loudly — nil
+to FFI raises TypeError); wrapper identity and c_ptr stability
+unchanged; creation faces drop ~200ns and one allocation per
+node; fresh-doc build row improves accordingly.
+
+## Outcome (1.9.174.3)
+
+@c_address is the canonical truth on every Node wrapper; c_ptr
+materializes lazily (@c_ptr ||= FFI::Pointer.new(@c_address)),
+preserving the public API and identity. All internal @c_ptr
+reads became c_ptr reader calls; the 15 @c_ptr.address sites
+collapsed to @c_address (also skipping the #address dispatch).
+The C construction faces (create element/text, bulk children,
+every xpath materialization) stopped minting Pointers entirely —
+one allocation and ~200ns saved per node, and proportionally less
+GC. Document keeps its eager reader (documents are few).
+Measured under host load 22-25: GC-amortized Document.create
+~5-6µs -> ~4.0µs; NativeNode#[] 78ns (budget 70 — clear at
+load <10), content 45ns (budget 58 met).

data/TODO.perf/20-css-translation-cache.md

@@ -0,0 +1,24 @@
+# 20 — CSS translation cache
+
+Status: DONE (1.9.174.3)
+
+Searchable#css/#at_css run CssToXPath.convert on every call —
+pure Ruby regex/string work (~300ns+) — before the compiled-
+expression cache (TODO.perf/15) can hit on the result. The
+translation is a pure function of (selector, prefix); cache it
+with the same bounded-LRU shape (64 entries, Hash#shift
+eviction, GVL-safe), so repeat selectors skip straight to the
+compiled handle.
+
+Gates: css/at_css results identical; repeat-call rows improve by
+the translation cost; the join in xpath()'s expression build is
+also skipped for the single-String-path shape (join minted a
+fresh String per call even for one path).
+
+## Outcome (1.9.174.3)
+
+Searchable.css_expression: bounded LRU (64, shared limit) keyed
+on prefix+selector; css/at_css translate through it so repeat
+selectors skip the regex machinery straight to the compiled-
+expression cache. The single-String-path shape of xpath/at_xpath
+no longer joins (join minted a fresh String per call).

data/TODO.perf/21-key-memo-consult.md

@@ -0,0 +1,20 @@
+# 21 — key? consults the attribute memo
+
+Status: DONE (1.9.174.3)
+
+Element#key?/has_attribute? pays an engine FFI round-trip per
+call even when the versioned @attr_values memo already proves
+presence. Consult the memo first (hit = true; only a miss falls
+through to the engine + written-name fallback — the memo cannot
+prove ABSENCE for a partial fill).
+
+Gates: key? true for memoized names, unchanged miss semantics
+(undeclared-prefix fallback intact), readonly/namespace specs
+green.
+
+## Outcome (1.9.174.3)
+
+Element#key? consults the versioned @attr_values memo first —
+presence-proven hits skip the engine round-trip; partial-fill
+misses still fall through to the engine + written-name fallback
+(the memo cannot prove absence).

data/TODO.perf/22-eager-nodeset-materialization.md

@@ -0,0 +1,30 @@
+# 22 — Eager-in-C nodeset materialization (drop the per-call AutoPointer)
+
+Status: DONE (1.9.174.4)
+
+Every xpath() nodeset result pays an FFI::AutoPointer + a Method
+object + finalizer registration (~400-600ns plus their GC) just
+to keep the C result handle alive until the lazy NodeSet
+materializes — and virtually every consumer materializes anyway
+(each/size/to_a). Materialize eagerly in C instead: one face runs
+the bulk pass AND frees the result handle, returning the Ruby
+Array; Searchable wraps it in the eager NodeSet constructor (an
+Array-backed set has no handle at all). Exotic node kinds (the
+module-object sentinel) fall back to the existing lazy path with
+the handle intact.
+
+Gates: xpath results identical for every kind (including
+sentinel-graded kinds); laziness is internal — the public NodeSet
+behaviors (indexing, iteration, size) unchanged; the xpath row
+drops the AutoPointer cost per call.
+
+## Outcome (1.9.174.4)
+
+Native.materialize_xpath: the bulk pass AND the result free in C;
+Searchable's nodeset branch wraps the returned Array in the eager
+NodeSet (no AutoPointer, no Method object, no finalizer per
+xpath call). Sentinel scans happen in C (a Ruby include? would
+cost microseconds on large sets) — any exotic kind returns Qnil
+with the handle alive for the lazy fallback. Measured (load
+~11): full materialization of a 2000-node xpath set 55.9µs vs
+Nokogiri 57.3µs — parity on the heavy shape.

data/TODO.perf/23-cbound-value-mutations.md

@@ -0,0 +1,27 @@
+# 23 — C-bound name= / content= / unlink
+
+Status: DONE (1.9.174.4)
+
+The value mutations still run ensure_writable! + FFI marshaling
+per call (~450ns): Element#name=, Element#content=,
+Text#content=, and Node#unlink (transforms rename, rewrite, and
+remove nodes constantly). Same face shape as set_binding_attribute:
+gates + version bump + engine write in one dispatch —
+set_binding_name (element names), set_binding_text (element text
+or text-node content, kind-dispatched in C), and
+unlink_binding_node (plus the Ruby-side @parent clear and memo
+invalidations that ride the version bump).
+
+Gates: rename/content/unlink semantics unchanged (memos, sibling
+stamps, path memo all invalidate through the version bump);
+readonly raises through every face.
+
+## Outcome (1.9.174.4)
+
+Native.set_binding_name / set_binding_text (kind-dispatched
+element-vs-text) / unlink_binding_node — gates + bump + engine
+write in one dispatch, wired into Element#name=, #content=,
+Text#content=, and Node#unlink (@parent clear and memo
+invalidation ride the version bump). Measured (load ~11):
+name= 237ns, content= 298ns, unlink+re-add 1.74µs; readonly
+raises verified through every face.

data/TODO.perf/24-immutable-read-lanes.md

@@ -0,0 +1,22 @@
+# 24 — Immutable read lanes: line/byte_offset memo + precomputed public #document
+
+Status: DONE (1.9.174.4)
+
+Node#line and #byte_offset pay an FFI round-trip per call, but a
+node's source position never changes — memoize unconditionally
+(first read wins). The public Node#document walks scope_owned? (a
+method chain) on every call though scope ownership is fixed at
+construction — precompute @pub_document once (nil for
+scope-owned) including at every C construction site.
+
+Gates: line/byte_offset stable across mutations (they must be —
+the engine reports source positions); document nil for
+scope-owned yields exactly as before; suite both modes.
+
+## Outcome (1.9.174.4)
+
+line/byte_offset memoize unconditionally (a node's source
+position never changes; 40ns hits). Node#document answers the
+constructor-precomputed @pub_document (nil for scope-owned
+yields) — the scope_owned? method chain disappears from one of
+the most-called readers; every C construction site sets it.

data/TODO.perf/25-scope-owned-bulk-path.md

@@ -0,0 +1,39 @@
+# 25 — Scope-owned (iterparse) elements on the bulk/native read path
+
+Status: DONE (1.9.174.5)
+
+iterparse is moxml's streaming core, yet scope-owned elements
+ride the FFI read path (two-call fetch + per-child Ruby wrap
+frames; #4ca5b3c kept them off deliberately). The IterationScope
+exposes exactly the seams the C faces read — @wrapper_cache
+(reset per yield by new_subtree!, killing recycled-address
+entries) and @version (advances per yield and on mutation) — so
+the bulk children faces can take the SCOPE as their "document"
+argument safely, provided the constructed wrappers are stamped
+scope-aware: @structure_memoizable/@native_fast false,
+@pub_document nil.
+
+Pure address-based reads (fast_attribute / element text / name)
+touch no cache — scope elements can use them via a construction
+-time @addr_reads_fast that ignores scope ownership.
+
+Gates: iterparse children/element_children identical via the C
+path; identity holds within a yielded subtree and resets across
+yields (the new_subtree! discipline); document stays nil for
+scope yields; mutations on scope elements keep the Ruby path;
+suite both modes.
+
+## Outcome (1.9.174.5)
+
+The bulk children faces take the IterationScope itself as their
+"document" (its @wrapper_cache resets per yield via new_subtree!
+— recycled pool addresses cannot collide — and its @version
+advances per yield and on mutation); the C face stamps
+scope-aware (@structure_memoizable/@native_fast false,
+@pub_document nil) while document-owned stamps stay Qtrue.
+Pure address-based reads (fast_attribute / element text / name)
+switch to @addr_reads_fast — true for scope elements too (they
+touch no cache). Mutations on scope elements keep the Ruby path.
+Measured (load ~6): the 20k-record iterparse walk (attr + child
+name + content per record) 124.8ms (FFI) -> 100.5ms (native
+bulk) — ~20%.

data/TODO.perf/26-post-mutation-memo-seeding.md

@@ -0,0 +1,26 @@
+# 26 — Post-mutation memo seeding
+
+Status: DONE (1.9.174.5)
+
+Every mutation invalidates the read memos through the version
+bump, so a write-then-read cycle pays a full re-derivation even
+when the new value is known at write time. Seed it: Element#[]=
+re-stamps @attr_values at the new version and writes the value
+into it (a partial fill stays partial — same rules); content=
+stores the new text as the @content memo at the new version;
+name= already seeds @name.
+
+Gates: []=/content=/name= followed by reads answers from the
+seeded memo (spec-observable via identity for strings? — no,
+values only); mixed attribute sets then attributes() still
+rebuild the full face on demand; invalidation semantics
+unchanged for other mutators.
+
+## Outcome (1.9.174.5)
+
+Element#[]= seeds the version-stamped @attr_values at the new
+version (a just-invalidated valid partial memo extends in place;
+a full face or anything older restarts partial, mirroring the
+cold-[] rules); content= seeds @content; name= seeds @name
+(already). Measured: the []= + [] read-back cycle runs ~545ns
+(write + read combined).

data/TODO.perf/27-c-yield-traversal.md

@@ -0,0 +1,38 @@
+# 27 — C-yield traversal (traverse/visit without the FFI::Function closure)
+
+Status: DONE (1.9.174.6)
+
+Node#traverse and #visit allocate an FFI::Function closure per
+call (~1µs) and dispatch every visited node back through the
+Ruby closure — the dominant per-node cost of whole-subtree
+iteration, paid even on small subtrees where the walk itself is
+microseconds.
+
+Bind both to C callbacks that rb_yield directly: the ext's
+traverse face keeps the abort-at-self post-order contract and
+the exception discipline (rb_protect in the callback stashes,
+aborts the walk, re-raises after — exactly the Ruby version's
+contract); visit keeps its (node, entering, depth) callback
+shape with the same stash-and-raise treatment. Node wrapping per
+visit rides the shared binding construction (identity cache +
+kind dispatch), and the walk state lives on the C stack — no
+globals, nested traversals safe.
+
+Gates: post-order sequence identical (receiver last); the
+subtree boundary holds (abort-at-self); block exceptions
+re-raise after the walk stops; enum_for forms unchanged; suite
+both modes.
+
+## Outcome (1.9.174.6)
+
+Native.traverse_binding / visit_binding: C callbacks that
+rb_yield directly (block forwarded explicitly — rb_yield needs
+it on the C entry's frame). traverse keeps post-order +
+abort-at-self + stash-abort-raise (rb_protect in the callback,
+walk state on the C stack — nested traversals independent);
+visit keeps (node, entering, depth) with the engine's
+(user, node, ...) callback order. Two bugs found by the suite:
+the visit callback's argument order (user first — the segfault
+spec caught it) and the block forwarding. Measured (load 34):
+traverse over 8k nodes 1663.5µs (FFI closure) -> 379.9µs
+(4.4x; 6.81x Nokogiri); visit 2288.6µs -> 545.4µs (4.2x).

data/TODO.perf/28-address-fills.md

@@ -0,0 +1,25 @@
+# 28 — Address-based first-touch fills for the remaining reads
+
+Status: DONE (1.9.174.6)
+
+The memoized content readers still fill through FFI marshaling on
+first touch — Text/Comment/CDATA/PI content, and Node#path
+(owned-string read + free) — and the bulk attribute faces exclude
+scope-owned elements though they touch no document state. Add the
+trivial address faces (fast_text/comment/cdata content, pi
+target/data, node path with the free protocol) and switch the
+fills to @addr_reads_fast (scope-eligible); the attributes bulk
+path follows.
+
+Gates: identical values for every kind (UTF-8, escapes, nils);
+scope-owned fills answer the same; path memo unchanged; suite
+both modes.
+
+## Outcome (1.9.174.6)
+
+fast_text/comment/cdata content, fast_pi_target/data (the
+read_pi_data strip preserved), and fast_path (owned-string copy
++ engine free) — every first-touch content fill now rides the
+address faces via @addr_reads_fast (scope-eligible), and the
+bulk attribute faces accept scope-owned elements (they touch no
+document state; the scope's version stamps the memo).

data/TODO.perf/29-ns-xpath-compiled.md

@@ -0,0 +1,23 @@
+# 29 — Namespace-bound xpath on the compiled + eager path
+
+Status: DONE (1.9.174.7)
+
+TODO.perf/15 excluded namespace-bound evaluations from the
+compiled-expression cache — they still pay the engine's string
+parse per call (~2-3µs) on top of an already-cached ns set. The
+engine has leptris_xpath_compiled_eval_ns; route the ns branch
+of xpath/at_xpath through the compiled cache (the handle is
+ns-independent — compile once) and the cached ns set, then let
+the eager materializer (TODO.perf/22) take the result.
+
+Gates: ns-bound results identical (prefix resolution, missing
+prefixes raising as today); the version-pinned path untouched;
+suite both modes.
+
+## Outcome (1.9.174.7)
+
+The ns branch of xpath/at_xpath rides the compiled-expression
+cache (the handle is ns-independent) + the cached ns set via
+XPath#eval_ns_ptrs (leptris_xpath_compiled_eval_ns); results
+flow into the eager materializer. Measured (load ~16): repeat
+ns-xpath 7.9µs -> 3.1µs (2.5x).

data/TODO.perf/30-copy-and-element-child-faces.md

@@ -0,0 +1,31 @@
+# 30 — dup one-dispatch + first/last element child faces
+
+Status: DONE (1.9.174.7)
+
+Node#dup runs create + FFI element_copy + root= (three dispatches
+plus the lift-guard walk) for an engine-copier op that is already
+2.3x — bind the whole copy: engine create + handle + element_copy
++ root wrap in one face. And the element-child readers pay O(N):
+first_element_child scans siblings with two FFI calls per
+non-element (text-heavy parents), last_element_children batches
+ALL children to keep one — one C walk each answers in a single
+dispatch.
+
+Gates: dup semantics (comment/PI children, namespaces — the
+copy_of seam contract #696/#721/#812); first/last on mixed
+content, empty elements, document receivers; suite both modes.
+
+## Outcome (1.9.174.7)
+
+Native.copy_binding_element: engine create + lifetime handle +
+document wrapper + element_copy + rooted+memo-seeded wrap in one
+dispatch; the namespace-lift decision stays in Ruby (skip_
+adoption_lift? + lift — the copy_of seam's #696/#721/#812
+semantics), and the return shape matches copy_of's contract (the
+copied root ELEMENT — my first version returned the document and
+the probe caught it). Native.first/last_element_child: one C
+walk each (the FFI scan paid two calls per skipped sibling; the
+batch fetch materialized every child to keep one). Measured
+(load ~16): ns-bearing element dup 37.0µs -> 9.6µs (3.9x);
+first_element_child over 1000 mixed children 98ns (memo-hit
+shape), last 3.2µs cold-walk.

data/TODO.perf/31-battery-rounds-4-8.md

@@ -0,0 +1,23 @@
+# 31 — Battery rows for the round 4-8 surfaces
+
+Status: DONE (1.9.174.8)
+
+The drift battery (benchmark/native_vs_binding.rb) predates
+TODO.perf/22-30: eager materialization, C-yield traversal,
+streaming bulk, one-dispatch dup, ns-xpath on the compiled path,
+first/last element-child walks, and the value mutations have no
+rows — nothing regression-gates them. Add interleaved best-of
+rows behind the file's load gate for each, mirroring the shapes
+measured in their TODO docs.
+
+Gates: every row runs under load <20 (the file's own gate) and
+prints both surfaces where two exist (FFI vs native via
+LEPTRIS_NO_NATIVE).
+
+## Outcome (1.9.174.8)
+
+Seven new rows behind the file's load gate: iterparse walk 4k,
+traverse/visit over the 14k-node doc, ns-bearing element dup,
+xpath union materialization, first+last element child, and the
+name=+content= pair. The round-4-8 surfaces are now
+regression-gated.