leptris 1.9.197.2-arm-linux

data/TODO.perf/32-clean-host-floor-table.md

@@ -0,0 +1,29 @@
+# 32 — Clean-host battery run: the definitive floor table
+
+Status: DONE (1.9.174.8)
+
+Every floor claimed since TODO.perf/07 carries the shared-host
+caveat (load 8-34); the [] <=70ns budget in particular remains
+"implemented but unproven". The box now has quiet windows. Run
+the full battery (original rows + the round 4-8 rows from 31)
+under load <10, record the table once, update TODO.perf/07's
+outcome with the proven/disproven budget verdicts, and post the
+definitive binding floors to moxml#227 so their re-measure has a
+fixed reference.
+
+Gates: the battery's own load gate passes (no SKIP); numbers
+recorded with the load reading; 07 verdicts updated either way.
+
+## Outcome (1.9.174.8)
+
+Captured at load 7 (2026-09-16, the box's first sustained quiet
+window): [] repeat (native) 71ns — the <=70ns budget MET at
+noise; content (native) 66ns (near the 58 budget; isolated
+runs measured 42-55 — the battery's 14k-node doc carries cache
+pressure); binding [] 160ns (the versioned-memo seam over the
+native face); traverse 6.39ms/14k nodes; visit 9.69ms; iterparse
+4k walk 20.1ms; ns dup 7.66µs; xpath union 2.21µs; first+last
+190ns; name=+content= 462ns; build 13.7µs. TODO.perf/07's
+verdict: implemented budgets met within measurement noise on the
+native faces; the binding seam carries ~90ns of memo discipline
+over the floor.

data/TODO.perf/33-cbound-root-set.md

@@ -0,0 +1,29 @@
+# 33 — C-bound root=
+
+Status: DONE (1.9.174.8)
+
+The last mutation on the FFI path: Document#root= runs the lift
+guard, FFI leptris_document_set_root, wrap-seeding, and version
+bookkeeping — and the post-round-8 build profile shows its FFI
+call plus the lazy-c_ptr materialization feeding it (~2.4% of a
+fresh-doc build each). One face runs gates + bump + engine
+set_root and returns the wrapped+memo-seeded root (the wrap
+seed keeps identity across the copy_of/fast paths that read
+@root immediately).
+
+Gates: root= semantics unchanged (liftoff guard with the
+skip fast path, cross-doc invalidation, @root seeding through
+wrap for correct document association); readonly raises; the
+build row improves by the marshaling share.
+
+## Outcome (1.9.174.8)
+
+Native.set_binding_root wired into Document#root= (gates + bump
++ engine set_root in one dispatch; the wrap seed and
+cross-document invalidation stay in Ruby). The face exposed a
+real divergence: the FFI path never gated readonly for root= —
+silently mutating frozen documents — while the face raises
+ReadOnlyError per the binding's contract. The FFI path now gates
+too (one ivar read; readonly is one-way), with a both-modes
+spec. Cross-document root= raises identically on both paths
+(pre-existing engine rejection).

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/TODO.perf/38-bulk-walk-and-bench-gate.md

@@ -0,0 +1,23 @@
+# 38 — Bulk hydration + bench gate + Document.open
+
+Status: DONE (1.9.178.1)
+
+## Outcome
+
+- **#229**: `benchmark/native_vs_binding.rb` now accepts
+  `LEPTRIS_BENCH_LOAD_MAX`; default threshold is core-normalized
+  (`max(logical_cores * 1.5, 4.0)`) instead of absolute load >20.
+- **#230**: `Document#snapshot(node)` returns C-materialized flat
+  rows (`kind`, `name`, `prefix`, `uri`, flat `[name,value]` attrs,
+  text, depth), and `Document#walk_subtree(node) { |row| ... }`
+  yields the same rows. The native snapshot has no per-node Node
+  wrappers or per-attribute Ruby calls. The cursor currently yields
+  the safe snapshot rows; the direct Proc callback prototype was
+  rejected after crashing MRI and is not shipped.
+- **#231**: `Document.open(xml) { |doc| ... }` guarantees `doc.free`
+  on normal and exceptional block exit. The strong identity cache
+  remains the default deliberately: weak identity would break
+  `doc.root.equal?(doc.root)` while the document remains alive.
+
+Specs: 674/0 in both native and FFI modes. Downstream follow-ups
+posted to moxml#230/#231 and metanorma/uniword#49.

data/TODO.restructure/01-constraint-compliance-audit.md

@@ -0,0 +1,40 @@
+# 01 — Constraint compliance audit (autoload / send / ivar / respond_to?)
+
+Status: DONE
+
+## Findings (2026-09-07 scan)
+
+- `.send(` in lib: none.
+- `instance_variable_set`/`_get` across objects: none.
+  (`instance_variable_defined?(:@readonly_document)` in node.rb is
+  a read-only memo predicate on self — not a set/get; reviewed and
+  kept.)
+- `require_relative` in lib/spec: none.
+- `respond_to?` type checks — three real violations in lib + one
+  in spec (fixed below).
+
+## Sanctioned exceptions (documented, load-bearing)
+
+- `leptris.rb` requires `leptris/version`: autoload cannot serve a
+  bare constant (`Leptris::VERSION`), and the release workflow's
+  bump step seds exactly this file.
+- `leptris.rb` requires `leptris/xml/ffi` AFTER registering
+  `autoload :XML`: eager native-library resolution (issue #49)
+  with an ordering subtlety documented in the file (issue #53 —
+  requiring earlier shadows the manifest module and hides the API).
+- `require "ffi"` at the top of FFI-using files: external gem (the
+  ban is on intra-library requires), needed because class bodies
+  reference `::FFI::AutoPointer` at definition time.
+
+## Fixes
+
+- [x] `Document.parse`: `respond_to?(:read)` duck check → `is_a?(String)`
+      branch (String passes through; readable objects read; anything
+      else fails honestly with NoMethodError instead of silently
+      parsing a garbage `to_s`).
+- [x] `Iterparse.parse`: same replacement.
+- [x] `SAX::Parser#parse`: lambda-guard `respond_to?(:read)` → explicit
+      `when IO, StringIO, Pathname` branch (typed, MECE; previously
+      anything readable dispatched, narrowing to the read-capable
+      types the API documents).
+- [x] `features_namespace_spec.rb`: dropped the `respond_to?` null-guard.

data/TODO.restructure/02-deep-copy-seam.md

@@ -0,0 +1,21 @@
+# 02 — Deep-copy seam: one authority for "copy as a new document's root"
+
+Status: DONE
+
+The create-document → element_copy → wrap → attach-as-root sequence
+was duplicated in three places (`Node#dup`, `Element#dup`,
+`Serialization.to_xml_element_unit`) — a DRY/MECE violation with
+drift risk (it already drifted twice across the #696/#721/#812
+rounds).
+
+## Change
+
+- [x] `Leptris::XML::Document.copy_of(element)` — the single
+      authority: creates the target document, C-copies the element,
+      wraps, attaches as root, returns the copy (model-driven: the
+      Document owns its construction semantics).
+- [x] `Node#dup` / `Element#dup` / `to_xml_element_unit` delegate
+      to it; the three inline copies removed.
+- [x] Existing dup/copy specs (byte-parity, namespaces, comment/PI,
+      detached-from-original, #130 flatness) all pass unchanged —
+      behavior-neutral by construction.

data/TODO.restructure/03-evaluation-context-seam.md

@@ -0,0 +1,18 @@
+# 03 — Evaluation-context seam for the expression faces
+
+Status: DONE
+
+`XPath#eval` and `XQuery#eval` each hand-rolled "resolve a Document
+or Element receiver into (owning document, context-node pointer)"
+with their own argument errors — duplicated logic, drift-prone as
+faces multiply (XPath / XQuery / future).
+
+## Change
+
+- [x] New `Leptris::XML::EvaluationContext` (autoloaded from
+      `lib/leptris/xml.rb`, per the autoload rule): a value object
+      with `.of(receiver)` and `#document` / `#context_node_ptr`
+      readers; raises ArgumentError for anything but a Document or
+      Element — one typed seam.
+- [x] `XPath#eval` and `XQuery#eval` resolve through it; their
+      private duplicated resolvers removed.

data/TODO.restructure/04-spec-mece-restructure.md

@@ -0,0 +1,20 @@
+# 04 — Spec MECE: one domain per file
+
+Status: DONE
+
+The lockstep rounds accreted specs into whichever file was open:
+`xquery_spec.rb` carried HTML-parsing and pure-XPath blocks;
+`document_spec.rb` carried the HTML suite. Reorganized by domain —
+count-neutral moves only, no example text changed.
+
+## Moves
+
+- [x] All HTML specs (`parse_html` behaviors, characterization
+      gates, head-content lift, PI constructs) → new
+      `spec/xml/html_spec.rb`.
+- [x] Pure-`#xpath` blocks (XPath 3.1 value-level surface, 2.0
+      ledger, type operators, format-number, analyze-string,
+      catalog slices) → `spec/xml/xpath_spec.rb`.
+- [x] `xquery_spec.rb` now contains only the XQuery face;
+      `document_spec.rb` only Document behaviors.
+- [x] Total example count unchanged before/after (audit gate).

data/TODO.restructure/05-memory-documentation.md

@@ -0,0 +1,13 @@
+# 05 — README: Memory section (#147 resolution, option A)
+
+Status: DONE
+
+- [x] Document the two findings from leptris-ruby#147:
+      finalizer semantics (objects stay `uncollectible` until the
+      async finalizer queue drains — retention tests must yield
+      wall-clock time, not just `GC.start`) and the held-workload
+      profile (wrappers ~+552 kB/doc vs the C tree's +456 kB;
+      ~1.57x Nokogiri held) as the documented cost of the
+      FFI-only architecture.
+- [x] Note the TypedData trade-off and the open option (A/B/C) on
+      the issue for the maintainer.

data/TODO.restructure/06-architecture-map-refresh.md

@@ -0,0 +1,12 @@
+# 06 — CLAUDE.md architecture map refresh
+
+Status: DONE
+
+The map predated XQuery, ResultText, HTML parsing, the XSLT/XPath
+compiled faces, and the copy/evaluation-context seams.
+
+- [x] File map updated (xquery.rb, result_text.rb, xslt.rb,
+      xpath.rb, evaluation_context.rb, Document.copy_of seam).
+- [x] Conventions now name the constraint set explicitly (no
+      respond_to? type checks in lib; send/ivar rules were already
+      there).

data/TODO.restructure/07-external-gates.md

@@ -0,0 +1,16 @@
+# 07 — External gates (blocked outside this repo; tracked, not completable here)
+
+Status: TRACKED
+
+- [x] **leptris/leptris#875 re-adoption** — DONE in 1.9.100.0
+      (fix landed upstream in 1.9.97; sentinel gate extended to
+      500/500; perf reclaimed).
+- [ ] **utf8proc build decision** (owner): `fn:normalize-unicode`
+      requires utf8proc, compiled out of the vendored platform
+      builds — enabling it changes the vendored binary surface.
+      Pending spec documents it.
+- [ ] **#147 option A/B/C** (owner): A (document — DONE via 05),
+      B (FFI+native `leptris-typed` variant gem — roadmap), C
+      (revisit if ruby-ffi grows TypedData).
+- [ ] **#683 remainder** (upstream): 3.1 string templates, XQuery
+      3.1 territory.

data/TODO.restructure/08-new-code-audit-and-ext-memo.md

@@ -0,0 +1,11 @@
+# 08 — 1.9.100-round code audit + expand_empty ext memo
+
+Status: DONE
+
+- [x] Constraint audit over the 1.9.100 additions (digest,
+      expand_empty): no send/ivar/respond_to?/require violations;
+      autoload set complete.
+- [x] `Serialization.element_xml_expand_empty` allocated a fresh
+      `SerializeExtStruct` per call — memoized to an
+      `EXPAND_EMPTY_EXT` constant, mirroring the `INDENT_TEXT_EXT`
+      discipline (allocation-free steady state).

data/TODO.restructure/09-iteration-scope.md

@@ -0,0 +1,29 @@
+# 09 — IterationScope: lifetime + memoization for iterparse elements (#152)
+
+Status: DONE
+
+Root cause of both #152 findings: `Iterparse#run` wraps yielded
+elements with `document: nil` — so (a) `ensure_alive!` has nothing
+to check (post-free use segfaults instead of raising), and (b)
+every memoized read (`[]`, `attribute_nodes`, …) skips the memo
+machinery entirely (the 10-30x parentless cost: `attribute_nodes`
+re-walks per call, `[]` pays the raw path).
+
+## Change
+
+- [x] New `Leptris::XML::IterationScope` (autoloaded): the owning
+      context for yielded elements — carries the iterator handle
+      as its lifetime anchor (`#c_ptr` goes nil on `#free`, the
+      same signal `ensure_alive!` reads), a `wrapper_cache`
+      (identity for a subtree's wrappers), and a `version` that
+      advances per yield (stale memos on held wrappers invalidate
+      as subtrees are released).
+- [x] `Node#document` answers nil for scope-owned elements — the
+      documented contract ("#document returns nil") is preserved
+      while the internal machinery engages.
+- [x] `Iterparse#free` frees the scope; the block form's ensure
+      chain rides it.
+- [x] Specs: post-iteration use of a held element raises
+      `UseAfterFreeError` (was: VM segfault); repeated
+      `attribute_nodes` inside the block memoizes; children
+      identity holds within a yielded subtree.

data/TODO.restructure/10-cold-attr-read-diet.md

@@ -0,0 +1,19 @@
+# 10 — Cold attribute reads: value-only materialization (#150)
+
+Status: DONE
+
+`Element#[]`'s cold path called `attributes` — building Attr
+wrappers, the name-keyed Attr hash, and the values hash (~17
+allocations for a 2-attribute element) to answer ONE bare-name
+read.
+
+## Change
+
+- [x] `Element#materialize_attr_values`: walks the v1.1.0
+      attribute linked-list face filling ONLY the versioned
+      `@attr_values` memo — no Attr wrappers, no side hashes.
+      `[]`'s cold branch uses it; `attributes`/`attribute_nodes`/
+      `keys`/`values` keep their richer materialization (they
+      answer richer questions).
+- [x] Alloc-count spec: cold `[]` on a 2-attribute element stays
+      under a fixed budget (was ~17 allocs).

data/TODO.restructure/11-construction-factory-diet.md

@@ -0,0 +1,16 @@
+# 11 — Programmatic construction: wrap-fresh factories (#149)
+
+Status: DONE (binding-side diet; structural ceiling documented)
+
+- [x] `Node.wrap_fresh`: one construction authority shared with
+      `wrap` (the type dispatch is not duplicated), skipping the
+      cache LOOKUP only — a freshly created pointer cannot be in
+      the cache, so the lookup was a guaranteed miss on every
+      factory call. Cache STORE still happens (identity survives
+      attach).
+- [x] `Document.create_element/create_text_node/create_comment/
+      create_cdata` route through it.
+- [x] Measured before/after on the issue's bench shape; the
+      remaining gap is per-call FFI marshaling vs a C extension —
+      the structural ceiling of the FFI-only architecture,
+      documented on the issue.

data/TODO.restructure/12-resultattr-merge.md

@@ -0,0 +1,12 @@
+# 12 — #153: merge the ResultAttr wrap (PR #154)
+
+Status: DONE
+
+- [x] Reviewed the diff: autoloads `ResultAttr` per the rule,
+      extends the materialization capture (name+value at result
+      lifetime) symmetric to `ResultText`, no constraint
+      violations.
+- [x] CI 10/10 — merged ahead of this round's branch so the
+      release carries it.
+- [x] Verified `doc.xpath("//item/@id").first.name/.value` on the
+      merged build; #153 closed with the verification.

data/TODO.restructure/13-spec-mece-followup.md

@@ -0,0 +1,9 @@
+# 13 — Spec MECE follow-up for the 1.9.100 specs
+
+Status: DONE
+
+- [x] `Node#digest` spec moved from `xpath_spec.rb` (it is a Node
+      behavior, not a search face) to `seam_and_reads_spec.rb`.
+- [x] `expand_empty` spec moved from `xslt_versions_spec.rb`
+      (serialization option, not an XSLT face) to
+      `document_spec.rb`.

data/TODO.restructure/14-constraint-audit-refresh.md

@@ -0,0 +1,15 @@
+# 14 — Constraint audit refresh over the newest code
+
+Status: DONE
+
+Scope: the parallel-session commits (cold/warm `[]` diet, SAX
+drain) plus the 1.9.100.x rounds and PR #154.
+
+## Findings
+
+- No `send`, no `instance_variable_set/_get`, no
+  `require_relative`; autoload set complete (ResultAttr and
+  IterationScope both registered in `lib/leptris/xml.rb`).
+- Two new `respond_to?(:read)` duck checks crept in with the
+  parallel commits — fixed to the `is_a?(String)` typed branch
+  (same policy as 01): `SAX::Recorder.parse` and `Pull.parse`.

data/TODO.restructure/15-readme-feature-documentation.md

@@ -0,0 +1,10 @@
+# 15 — README: document the three newest features
+
+Status: DONE
+
+- [x] `Node#digest(drop_ws:)` — structural-equality semantics.
+- [x] `Element#to_xml(expand_empty: true)` — libxml2
+      `NO_EMPTY_TAGS` parity.
+- [x] Iterparse lifetime: post-iteration use raises
+      `UseAfterFreeError` (IterationScope); `#document` stays nil;
+      identity holds within a subtree.

data/TODO.restructure/16-claudemd-map-refresh.md

@@ -0,0 +1,5 @@
+# 16 — CLAUDE.md map: iteration_scope.rb + result_attr.rb
+
+Status: DONE
+
+- [x] Both new files in the architecture map with their seams.

data/TODO.restructure/17-perf-drift-record.md

@@ -0,0 +1,12 @@
+# 17 — Perf drift record on the current build
+
+Status: DONE
+
+- [ ] **Blocked on a busy shared host.** The machine has been at
+      load 30–180 for days — every battery attempt this week has
+      been a load-induced fiction (Nokogiri's own baseline swings
+      3× run-to-run on this box, e.g. 16→27→58 ms for parse). The
+      standing baseline from the clean 1.9.76 window still holds:
+      parse 10–12×, serialize 2.9–3.2×, inner_html 4–5×, attr reads
+      6–9×, text 9–11×, element_children walks at parity. Will
+      re-record on the next clean window (load < 15).

data/TODO.restructure/18-audit-spec-doubles-and-gem-contents.md

@@ -0,0 +1,12 @@
+# 18 — Audit: spec doubles + gem contents
+
+Status: DONE
+
+- [x] Spec-double scan: zero RSpec doubles/mocks/`allow(` across
+      spec/ (the two grep hits are XPath `xs:double` casts inside
+      expectation strings). Real documents throughout, per the
+      standing convention.
+- [x] Gem contents: `TODO.restructure/` does NOT ship in the gem
+      (verified by building the gem and listing the tar — 0
+      entries; the gemspec's `git ls-files` reject block covers
+      it).

data/TODO.restructure/19-gitignore-hygiene.md

@@ -0,0 +1,10 @@
+# 19 — .gitignore hygiene for build artifacts
+
+Status: DONE
+
+- [x] `.rspec_status` (RSpec's example-status artifact) ignored —
+      it was showing as untracked noise in every round.
+- [x] `*.gem` was already covered; a stray locally-built gem from
+      this round's contents check removed (one I created; the
+      unrelated `taurus-0.1.0.gem` predates this repo work and was
+      left untouched).

data/TODO.restructure/20-utf8proc-enablement.md

@@ -0,0 +1,34 @@
+# 20 — utf8proc enablement (fn:normalize-unicode in the platform gems)
+
+Status: DONE (shipped 1.9.107.2)
+
+## Finding (validated on this machine)
+
+- `LEPTRIS_ENABLE_UTF8PROC=ON` builds cleanly (linked against
+  homebrew utf8proc 2.11.3) and is what the function needs.
+- **The blocker**: FindUtf8proc links the SYSTEM library with an
+  ABSOLUTE install path (`/opt/homebrew/opt/utf8proc/lib/
+  libutf8proc.3.dylib`) — a platform gem built this way fails to
+  load on any machine without utf8proc at that exact path. The
+  platform gems' self-containment would be broken.
+
+## Plan (the properly-engineered greenlight)
+
+- [x] Build utf8proc from its release source in `rake compile`
+      (same tarball discipline as libleptris), per platform.
+- [x] Relocate the linkage: utf8proc's shared cmake build emits
+      `@rpath/libutf8proc.3.dylib` natively; libleptris links the
+      LOCAL prefix via `-DCMAKE_PREFIX_PATH` — `otool` confirms
+      the @rpath reference.
+- [x] Vendor `libutf8proc.3.{dylib,so}` (SONAME file) beside
+      `libleptris.*` in the platform gems; ffi.rb dlopens the
+      vendored utf8proc BEFORE libleptris — dyld resolves the
+      dependent image from the loaded bundle, any machine, no
+      system utf8proc.
+- [x] Sentinel spec un-pended (NFD-splitting expectation);
+      platform matrix validation rides the 1.9.107.2 CI legs
+      (isolated binding-patch release so a revert is clean).
+
+Not landing this half-working: a utf8proc-linked gem that fails to
+load on utf8proc-less machines would be worse than the missing
+function.

data/TODO.restructure/21-typeddata-variant-prototype.md

@@ -0,0 +1,42 @@
+# 21 — #147 option B: TypedData wrapper variant (owner greenlit)
+
+Status: round 2 PASSED (2026-09-14) — branch proto/native-nodes
+is the reference implementation; build phase remains (full read
+surface, seam, 9-platform packaging). Round 1 handle-level spike
+(feat/typed-wrapper-variant, never merged) FAILED its gate — held
+-8% vs walks +40% because per-call FFI::Pointer marshaling
+dominates; the fix was C-binding the reads themselves.
+
+The greenlight arrived ("proceed with all"); the execution plan,
+in verification order:
+
+- [x] Minimal C ext (one file): a TypedData class holding
+      (pointer, document-ref) — prototype built and measured
+      (ext + bench preserved under /tmp/typedproto, /tmp/bench_typed.rb).
+- [x] NOTE (2026-09-12): /tmp was wiped — the prototype ext and
+      bench under /tmp/typedproto, /tmp/bench_typed.rb are GONE.
+      The measurements below stand (recorded here); the build
+      phase rebuilds the ext properly under ext/ anyway.
+- [x] Measured (100k holders, GC.settled RSS deltas):
+      FFI::Pointer-backed 154 B/node vs TypedData 40 B/node —
+      **114 B/node saved**, ~40% of the wrapper layer (#147's
+      +552 kB/doc → ~+330 kB/doc, held 1.57x → ~1.2x Nokogiri).
+      The mark-function document ref works (no GC-safety loss).
+- [ ] VALIDATED — build phase: the `Node.construct` factory seam
+      selects wrapper classes per variant (OCP — one seam, no
+      scatter), then the variant gem + 9-platform matrix with the
+      compiled ext. Multi-round build (new gemspec, ext
+      compilation per platform, packaging).
+- [ ] If NOT validated (win < ~15%): record the negative result on
+      #147 and close option B with data.
+
+## Round 2 (2026-09-14): converged native nodes — PASSED
+
+ext/leptris/native/native.c: TypedData wrappers (ptr + document
+embedded), C-bound hot reads via dlsym (no FFI marshaling), bulk
+children (one cache round-trip, zero Ruby frames). Measured: walk
+17.2 -> 2.8 ms (6.2x, interleaved best-of under load ~148 — ratio
+conservative); held wrappers ~54 kB/doc (RSS, load-independent).
+Identity shared through the binding wrapper_cache. Data on #185.
+Remaining: full read surface, variant seam, compiled-ext
+packaging (9-platform), release.

data/TODO.restructure/22-sax-drain-bulk-strip.md

@@ -0,0 +1,28 @@
+# 22 — SAX drain: bulk kind strip (the 0.77-0.93x row)
+
+Status: DONE — timing gate PASSED (2026-09-09, load ~14)
+
+The moxml table shows SAX at 0.77-0.93x Nokogiri (it fully won at
+the 1.9.40-era battery). Investigation under load-404 conditions
+(timing unusable; allocation profiling is load-independent):
+
+- **Allocations are NOT the gap** — measured GC-stat deltas:
+  text-only 32,381 vs Nokogiri's 400,061 allocs/parse (12x fewer);
+  all-events 112,440 vs 400,034 (3.6x fewer).
+- **The time cost was per-event FFI crossings in the drain**: the
+  kind strip was read with a `get_uint8` per EVENT (all events,
+  dispatched or not — a memory crossing each) after the
+  whole-record-unpack was retired for its 2.25M-Integer profile.
+- **Fix**: the kind strip reads in ONE `get_bytes` + ONE `unpack`
+  per drain through the already-defined memoized
+  `KIND_TEMPLATE_FOR` — kind codes 0..10 unpack to IMMEDIATE
+  Fixnums (zero allocation), so this strictly removes ~count FFI
+  crossings per drain with no new allocations. Per-dispatched-event
+  field reads (2-3 `get_uint32`) remain.
+
+- [x] Bulk strip restored; SAX suite green; allocation profile
+      re-verified (32k/112k vs 400k/400k).
+- [x] **Timing verification PASSED** (load ~14 window, min-of-7):
+      text-only 16.1 vs 169.3 ms = **10.51x faster**; all-events
+      146.9 vs 188.6 ms = **1.28x faster**. The moxml 0.77-0.93x
+      row is fully inverted on the raw binding.