makiri 0.10.0.rc2 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c7dc5843dd369edd0bcae884c8b4f23dbdb854de335b51c99e1474858c9c49f6
-  data.tar.gz: ba1aeb6c3363450fc0212f5ce814c971b0e2eaf8dfd3f927703cfa2a667fdc35
+  metadata.gz: b6163794fb07f39d4476e91a5d9db367d82b02888e167bc41435bb12de32de49
+  data.tar.gz: 4c075f42cbdf69b39b9783e3ad66bd09acb48f380447e8e80a47402dcdd427e5
 SHA512:
-  metadata.gz: f1699b0cdd955116e52a2b575abfa5dbfbbdaecd43d3217844020828d18af341505e2df25539a8c5086ad619c85fe099f679054a1cf562067d6ec159977aee73
-  data.tar.gz: 666692b6b9597640c6092a8407594a380fa6dfd6682844c1fecc4ce85ea5381e5dc49877210e3684ac3a10ab09f9b30a49cef4939b7f113fdc8d6e359b608156
+  metadata.gz: d6f1d154116c49d5b42e57e08d584781af42c2d0a02a6d3a1d6073659437cd7b0920a30a42451fedc70b173de242c9738a34ea4fd8d582dd3d199094bbfe10ab
+  data.tar.gz: 7278778cf2e98166e03ef79364ef9a4b0feec3b410949c2e4889f82f899594da8ba492ac00a6d75de2ee7a553430e5dc69a9af52a41292ab86249af830dea7fe

data/CHANGELOG.md

@@ -1,5 +1,42 @@
 # Changelog
 
+## [0.10.0] - 2026-09-22
+
+### Fixed
+
+* A frozen node now raises `FrozenError` when it is the ARGUMENT of a tree
+  mutation, not only the receiver: `b.add_child(a)` relinks `a` exactly as
+  `a.remove` does. Both `Makiri::XML` and `Makiri::HTML`. A fragment argument
+  splices its children, which have no wrapper of their own to check.
+* A `Makiri::XML` mutation that exceeds the document's own `max_bytes` /
+  `max_nodes` now raises `Makiri::XML::LimitExceeded` instead of reporting the
+  refusal as out of memory.
+* Inserting a `DocumentFragment` is all or nothing on `add_child`, `before` and
+  `after`, as it already was on `replace`: a child the rules refuse no longer
+  leaves the earlier ones linked in a document the caller was told had not
+  changed.
+* A rejected `Makiri::XML::Document#fragment` no longer charges the document for
+  the nodes it discarded. 100k rejected fragments grew a `<r/>` document to
+  77 MB; it is now 516 bytes.
+* A failed `Makiri::XML` parse reports the FIRST failure for all four kinds
+  (`syntax` was sticky while `limit` and `unsupported` overwrote each other).
+* `Makiri::XML#to_xml`'s serializer allocates fallibly again, so running out of
+  memory raises instead of aborting the process.
+* `:lexbor-contains()` now rejects an argument the bundled CSS parser does not
+  take, the way any unknown pseudo-class is rejected: `Makiri::CSS::SyntaxError`
+  from `#css` / `#at_css` / `#matches?`, and a `:bad_style` rule from
+  `Makiri::Lexbor::CSS.parse_stylesheet`. Well-formed uses are unchanged.
+
+### Performance
+
+* `Makiri::XML#to_xml` plans namespaces from a binding stack instead of
+  re-walking each ancestor's attribute list, which cost O(depth^2 x attributes).
+  403 KB of nested prefixed attributes took 4.88s and now takes 0.001s. A
+  crafted document fails closed with `Makiri::Error` ("namespace planning
+  exceeded its step budget") rather than running on.
+* Setting an attribute on a `Makiri::XML` element walks the attribute list once
+  instead of twice (4096 attributes: 47ms -> 27ms).
+
 ## [0.10.0.rc2] - 2026-09-20
 
 ### Added

data/NOKOGIRI_DIFFERENCES.md

@@ -61,6 +61,13 @@ what browsers do - rather than libxml2. Detailed, test-backed notes live in
   * `create_processing_instruction("a:b", ...)` succeeds, as DOM
     `createProcessingInstruction` does, but `#to_xml` / `#canonicalize` then raise,
     as DOM Parsing's well-formed serializer does. Nokogiri writes `<?a:b ...?>`.
+* `#freeze` on a node is ENFORCED: a frozen node's mutators raise `FrozenError`,
+  and so does passing a frozen node as the argument of an insertion, which
+  relinks it. Nokogiri reports `frozen?` but every mutator still mutates. The
+  check reaches the nodes the caller named; a fragment argument splices its
+  children, and those cannot be checked, because frozen-ness is a property of a
+  Ruby object and the arena keeps no map from a node back to its wrapper.
+
 * A node's namespace URI is its identity, not something re-derived from the
   declarations around it - the WHATWG DOM model, measured against Chrome 152
   (`DOMParser` + `XMLSerializer`).

data/Rakefile

@@ -74,6 +74,20 @@ namespace :unsafe do
   end
 end
 
+# The lint gate, with CI's OWN arguments. It exists because a narrower spelling
+# looks like it passes and is not: `cargo clippy --no-default-features --features
+# lexbor` never compiles `bridge/` or `glue/` at all, so five `clippy.toml`
+# violations there went unseen locally and turned CI red. `--all-features` is
+# every configuration the crate has, which is why CI uses it - and why this task
+# does, rather than leaving the arguments to be remembered.
+desc "Clippy and rustfmt exactly as CI runs them (--all-features, warnings are errors)"
+task :lint do
+  Dir.chdir("ext/makiri/rust") do
+    sh "cargo", "clippy", "--all-features", "--", "-D", "warnings"
+    sh "cargo", "fmt", "--all", "--", "--check"
+  end
+end
+
 # `rake spec:valgrind` - run the spec suite under Valgrind memcheck via
 # ruby_memcheck (Linux CI; see .github/workflows/valgrind.yml). The gem ships
 # Ruby's own Valgrind suppression files (matched by Ruby version) and filters

data/ext/makiri/rust/clippy.toml

@@ -19,17 +19,25 @@
 # call, and review is what catches a site that skipped them.
 disallowed-methods = [
   { path = "std::boxed::Box::new", reason = "aborts on OOM; use falloc::try_box" },
+  # `to_vec` is the same allocation as `Vec::from` under a friendlier name, and
+  # it was one of the holes this list had. Its sibling `ToOwned::to_owned` is NOT
+  # banned here, because it cannot be: on a `&str` it builds the String of a Ruby
+  # exception message, which the glue is right to allocate infallibly on a path
+  # that is already raising. The rule is per-LAYER and clippy.toml is crate-wide,
+  # so the layer half lives in `script/check_unsafe_boundaries.rb` ("infallible
+  # allocation inside an engine layer"), beside the other per-layer gates.
+  { path = "slice::to_vec", reason = "aborts on OOM; use falloc::try_to_vec" },
   { path = "alloc::vec::Vec::with_capacity", reason = "aborts on OOM; use falloc::try_vec_with_capacity" },
-  { path = "alloc::vec::Vec::reserve", reason = "aborts on OOM; use Reserve::mkr_reserve" },
-  { path = "alloc::vec::Vec::reserve_exact", reason = "aborts on OOM; use Reserve::mkr_reserve_exact" },
-  { path = "alloc::vec::Vec::try_reserve", reason = "not injectable; use Reserve::mkr_reserve" },
-  { path = "alloc::vec::Vec::try_reserve_exact", reason = "not injectable; use Reserve::mkr_reserve_exact" },
-  { path = "std::collections::HashMap::reserve", reason = "aborts on OOM; use Reserve::mkr_reserve" },
-  { path = "std::collections::HashMap::try_reserve", reason = "not injectable; use Reserve::mkr_reserve" },
-  { path = "std::collections::HashMap::with_capacity", reason = "aborts on OOM; use Reserve::mkr_reserve" },
-  { path = "std::collections::HashSet::reserve", reason = "aborts on OOM; use Reserve::mkr_reserve" },
-  { path = "std::collections::HashSet::try_reserve", reason = "not injectable; use Reserve::mkr_reserve" },
-  { path = "std::collections::HashSet::with_capacity", reason = "aborts on OOM; use Reserve::mkr_reserve" },
+  { path = "alloc::vec::Vec::reserve", reason = "aborts on OOM; use Reserve::falloc_reserve" },
+  { path = "alloc::vec::Vec::reserve_exact", reason = "aborts on OOM; use Reserve::falloc_reserve_exact" },
+  { path = "alloc::vec::Vec::try_reserve", reason = "not injectable; use Reserve::falloc_reserve" },
+  { path = "alloc::vec::Vec::try_reserve_exact", reason = "not injectable; use Reserve::falloc_reserve_exact" },
+  { path = "std::collections::HashMap::reserve", reason = "aborts on OOM; use Reserve::falloc_reserve" },
+  { path = "std::collections::HashMap::try_reserve", reason = "not injectable; use Reserve::falloc_reserve" },
+  { path = "std::collections::HashMap::with_capacity", reason = "aborts on OOM; use Reserve::falloc_reserve" },
+  { path = "std::collections::HashSet::reserve", reason = "aborts on OOM; use Reserve::falloc_reserve" },
+  { path = "std::collections::HashSet::try_reserve", reason = "not injectable; use Reserve::falloc_reserve" },
+  { path = "std::collections::HashSet::with_capacity", reason = "aborts on OOM; use Reserve::falloc_reserve" },
   # std's STABLE sorts take a scratch buffer from the global allocator and abort
   # the process when it cannot be had - outside falloc, so `rake oom` never
   # fails them. The unstable sorts sort in place and allocate nothing.

data/ext/makiri/rust/fuzz/fuzz_targets/common.rs

@@ -12,7 +12,7 @@ use core::ffi::c_void;
 
 pub use makiri::text::VerifiedText;
 pub use makiri::token::Token;
-pub use makiri::xml::parse::xml_parse;
+pub use makiri::xml::tree::parse as xml_parse;
 pub use makiri::xml::Document;
 pub use makiri::xpath::ast::Ast;
 pub use makiri::xpath::ctx::{Context, XPathValue};

data/ext/makiri/rust/src/bridge/html.rs

@@ -118,15 +118,28 @@ pub fn wrap_html_node(node: RawNode, document: Value) -> Value {
         _ => CLASS_HTML_NODE.raw(),
     };
 
+    /* One wrapper per node: navigating here twice must give the SAME object, or
+     * everything that lives on a Ruby object is silently lost - `equal?`, an
+     * instance variable, a singleton method, `freeze`. The Document above is
+     * already its own wrapper, which is why it needs no entry. */
+    let token = node.as_ptr() as usize;
+    if let Some(cached) = crate::bridge::wrapper::cached_node(document, token) {
+        return cached;
+    }
+
     /* The Document is stored after the wrap: see `TypedType::wrap`. */
     // SAFETY: a fresh wrapper; the store closure only moves a live VALUE in.
-    unsafe {
+    let fresh = unsafe {
         value(HTML_NODE_TYPE.wrap(
             klass,
             |nd| nd.node = node.as_ptr(),
             |nd| nd.document = document.as_raw(),
         ))
-    }
+    };
+    /* After the wrap, so the VALUE exists; `fresh` is on the stack, where the
+     * conservative scan pins it across the cache's own allocation. */
+    crate::bridge::wrapper::cache_node(document, token, fresh);
+    fresh
 }
 
 /// The HTML node handle behind an HTML node or HTML Document.
@@ -297,6 +310,14 @@ fn release_from_tree(node: HtmlNodeMut<'_>) {
 pub fn insert(this: &HtmlSelf, rb_incoming: Value, place: Place) -> Result<Value, Error> {
     let target = edit(this)?;
     let incoming = arg_node(&rb_incoming)?;
+    /* The argument is relinked too - `place` changes its parent and siblings, and
+     * an adoption removes it from its own document - so a frozen argument is a
+     * frozen node being modified. The receiver check alone let it through, which
+     * made `a.remove` raise and `span.add_child(a)` not, for the same effect on
+     * `a`. Reaches the nodes the caller NAMED; a fragment's children cannot be
+     * checked, because frozenness lives on the Ruby object and there is no map
+     * from a node back to its wrapper. */
+    crate::bridge::ruby::check_frozen(rb_incoming)?;
     Insertion::new(target.node(), place, incoming)
         .and_then(|i| i.check())
         .map_err(|e| refused(e, place))?;

data/ext/makiri/rust/src/bridge/node_set.rs

@@ -613,7 +613,7 @@ impl Index {
             return Index::Linear;
         }
         let mut set = PtrSet::default();
-        if set.mkr_reserve(nodes.len()).is_err() {
+        if set.falloc_reserve(nodes.len()).is_err() {
             return Index::Linear;
         }
         set.extend(nodes.iter().copied());
@@ -626,7 +626,7 @@ impl Index {
             return Index::Linear;
         }
         let mut set = PtrSet::default();
-        if set.mkr_reserve(expected).is_err() {
+        if set.falloc_reserve(expected).is_err() {
             return Index::Linear;
         }
         Index::Hashed(set)

data/ext/makiri/rust/src/bridge/typed.rs

@@ -26,12 +26,40 @@ use super::ruby::protect;
 pub struct Marker(());
 
 impl Marker {
-    /// Mark a stored `VALUE` as reachable.
+    /// Mark a stored `VALUE` as reachable, PINNING it where it is.
+    ///
+    /// For a field the object holds once. A table of many - a node cache - uses
+    /// [`Marker::mark_movable`] instead, so 50,000 pinned objects do not stop
+    /// compaction from doing its job.
     #[inline]
     pub fn mark(&self, v: VALUE) {
         // SAFETY: called from Ruby's mark phase, with the GVL held.
         unsafe { rb_sys::rb_gc_mark(v) };
     }
+
+    /// Mark a stored `VALUE` that compaction MAY move.
+    ///
+    /// Paired with [`Relocator::location`] in [`Hooks::compact`]: whatever is
+    /// marked movable must be re-read there, or the stored copy is left pointing
+    /// at where the object used to be.
+    #[inline]
+    pub fn mark_movable(&self, v: VALUE) {
+        // SAFETY: as `mark`; `Hooks::compact` updates every VALUE marked here.
+        unsafe { rb_sys::rb_gc_mark_movable(v) };
+    }
+}
+
+/// The compaction phase's handle, for [`Hooks::compact`].
+pub struct Relocator(());
+
+impl Relocator {
+    /// Where `v` is now, after compaction may have moved it.
+    #[inline]
+    pub fn location(&self, v: VALUE) -> VALUE {
+        // SAFETY: called from Ruby's compaction phase, with the GVL held, on a
+        // VALUE this object marked movable.
+        unsafe { rb_sys::rb_gc_location(v) }
+    }
 }
 
 /// A Rust value owned by a Ruby object.
@@ -44,6 +72,15 @@ pub trait Hooks: Sized {
     /// Mark every `VALUE` this object holds.
     fn mark(&self, marker: &Marker);
 
+    /// Re-read every `VALUE` marked with [`Marker::mark_movable`].
+    ///
+    /// Empty by default, which is correct for an object that only ever marks
+    /// with [`Marker::mark`] - those are pinned and cannot move. An object that
+    /// marks movable MUST implement this; Ruby's `GC.auto_compact` (which
+    /// `GC_COMPACT_STRESS=1` turns on for the whole suite) is what catches one
+    /// that does not.
+    fn compact(&mut self, _relocator: &Relocator) {}
+
     /// The bytes this object owns, reported to Ruby's GC.
     fn memsize(&self) -> usize {
         core::mem::size_of::<Self>()
@@ -82,6 +119,12 @@ unsafe extern "C" fn memsize_cb<T: Hooks>(ptr: *const c_void) -> rb_sys::size_t
     unsafe { (*(ptr as *const T)).memsize() as rb_sys::size_t }
 }
 
+unsafe extern "C" fn compact_cb<T: Hooks>(ptr: *mut c_void) {
+    // SAFETY: as `mark_cb`; compaction has finished moving and is now fixing up
+    // the references to what it moved.
+    unsafe { (*(ptr as *mut T)).compact(&Relocator(())) };
+}
+
 /// A `rb_data_type_t` for `T`: its GC callbacks drive [`Hooks`] for `T`, and
 /// every way to make or read an object of this type goes through it.
 ///
@@ -105,6 +148,7 @@ impl<T: Hooks> TypedType<T> {
                 Some(mark_cb::<T>),
                 Some(free_cb::<T>),
                 Some(memsize_cb::<T>),
+                Some(compact_cb::<T>),
             ),
             _t: PhantomData,
         }
@@ -190,6 +234,7 @@ impl DataType {
         dmark: rb_sys::RUBY_DATA_FUNC,
         dfree: rb_sys::RUBY_DATA_FUNC,
         dsize: Option<unsafe extern "C" fn(*const core::ffi::c_void) -> rb_sys::size_t>,
+        dcompact: rb_sys::RUBY_DATA_FUNC,
     ) -> DataType {
         DataType(rb_sys::rb_data_type_t {
             wrap_struct_name: name,
@@ -197,7 +242,7 @@ impl DataType {
                 dmark,
                 dfree,
                 dsize,
-                dcompact: None,
+                dcompact,
                 reserved: [core::ptr::null_mut(); 1],
             },
             parent,

data/ext/makiri/rust/src/bridge/wrapper.rs

@@ -18,11 +18,14 @@ use crate::bridge::ruby::makiri_error;
 use magnus::{prelude::*, Error, Value};
 
 use crate::bridge::ruby::{value, VALUE};
-use crate::bridge::typed::{Hooks, Marker, TypedType};
+use crate::bridge::typed::{Hooks, Marker, Relocator, TypedType};
+use crate::falloc::MapInsert;
 use crate::init::CLASS_DOCUMENT;
 use crate::lexbor::adapter::html::{HtmlDoc, RawDoc};
 use crate::lexbor::adapter::post_parse::HtmlParsed;
-use crate::xml::model::Doc as XmlDoc;
+use crate::xml::model::Document as XmlDoc;
+use core::hash::BuildHasherDefault;
+use std::collections::HashMap;
 
 /* ------------------------------------------------------------------ *
  * the node wrapper                                                   *
@@ -97,6 +100,86 @@ impl Content {
     }
 }
 
+/// One Ruby wrapper per node, so navigating to the same node twice gives the
+/// SAME object.
+///
+/// Without it every navigation allocated a fresh wrapper, and everything that
+/// lives on a Ruby object was silently lost: `equal?` was false for one node,
+/// an instance variable set through one wrapper was gone through the next, a
+/// singleton method vanished, and `freeze` protected only the object you
+/// happened to be holding. `==`/`eql?`/`hash` were unaffected, because those
+/// are node identity, which is why it went unnoticed.
+///
+/// The cost is Nokogiri's, and it is the same cost for the same reason: a
+/// wrapper stays alive while its document does. Measured on a 50,000-node
+/// document, minor GC after wrapping N nodes and dropping every reference:
+/// N=1,000 costs nothing (0.30 ms, the same as N=0), N=50,000 costs +2.2 ms.
+/// Nokogiri's figures for the same experiment are 0.31 ms and +2.24 ms.
+///
+/// Keyed by the node TOKEN - a `NodeId` for XML, a node pointer for HTML - which
+/// is stable for the document's life in both: XML never recycles an arena slot,
+/// and HTML detaches without destroying, so a node is never freed.
+struct NodeCache {
+    /// Empty until the first navigation, so a document nobody walks pays
+    /// nothing.
+    map: HashMap<usize, VALUE, BuildHasherDefault<TokenHasher>>,
+}
+
+/// The token is already a well-distributed integer - a slot index or an aligned
+/// pointer - so it only needs mixing, not hashing. `ptr_table::mix64` is the
+/// crate's one place for that.
+#[derive(Default)]
+struct TokenHasher(u64);
+
+impl core::hash::Hasher for TokenHasher {
+    fn finish(&self) -> u64 {
+        self.0
+    }
+    fn write(&mut self, bytes: &[u8]) {
+        for &b in bytes {
+            self.0 = crate::ptr_table::mix64(self.0 ^ b as u64);
+        }
+    }
+    fn write_usize(&mut self, n: usize) {
+        self.0 = crate::ptr_table::mix64(n as u64);
+    }
+}
+
+impl NodeCache {
+    fn get(&self, token: usize) -> Option<VALUE> {
+        self.map.get(&token).copied()
+    }
+
+    /// Remember `wrapper` as the one wrapper for `token`.
+    ///
+    /// A failed insert leaves the node uncached, so the next navigation builds
+    /// another wrapper and identity is lost for it. That only happens when the
+    /// allocator is refusing, where the process is already failing; the
+    /// alternative is raising out of a wrap that has no error path.
+    fn insert(&mut self, token: usize, wrapper: VALUE) {
+        let _ = self.map.falloc_insert(token, wrapper);
+    }
+
+    /// MOVABLE, not pinned: a document walked end to end holds one entry per
+    /// node, and pinning them all would stop compaction doing its job. Paired
+    /// with [`NodeCache::compact`].
+    fn mark(&self, marker: &Marker) {
+        for v in self.map.values() {
+            marker.mark_movable(*v);
+        }
+    }
+
+    fn compact(&mut self, relocator: &Relocator) {
+        for v in self.map.values_mut() {
+            *v = relocator.location(*v);
+        }
+    }
+
+    fn memsize(&self) -> usize {
+        self.map.capacity() * (core::mem::size_of::<usize>() + core::mem::size_of::<VALUE>())
+    }
+}
+
 /// A Document wrapper's data: the parsed content (owned - GC frees it), the
 /// mutation gate's count, and the reserved errors Array.
 pub struct DocData {
@@ -110,9 +193,38 @@ pub struct DocData {
     /// The external bytes this wrapper has told the GC about, so `release`
     /// takes back exactly what [`account_document`] reported.
     reported: usize,
+    /// One wrapper per node; see [`NodeCache`].
+    ///
+    /// Boxed and optional because a `DocData` is born from `ruby_xcalloc` - all
+    /// zero bytes - and a zeroed `HashMap` is not an empty one: hashbrown's empty
+    /// table points at a static, not at null. `None` IS all-zero (Box is
+    /// non-null, so the niche is the null pointer), which makes the zeroed state
+    /// both valid and the right one: a document nobody navigates never allocates
+    /// a cache.
+    nodes: Option<Box<NodeCache>>,
 }
 
 impl DocData {
+    /// The one wrapper for `token`, or None until something navigates to it.
+    fn cached(&self, token: usize) -> Option<VALUE> {
+        self.nodes.as_ref()?.get(token)
+    }
+
+    /// Remember `wrapper` for `token`, allocating the cache on first use.
+    fn cache(&mut self, token: usize, wrapper: VALUE) {
+        if self.nodes.is_none() {
+            let Ok(fresh) = crate::falloc::try_box(NodeCache {
+                map: HashMap::with_hasher(BuildHasherDefault::default()),
+            }) else {
+                return; /* see NodeCache::insert on a refusing allocator */
+            };
+            self.nodes = Some(fresh);
+        }
+        if let Some(cache) = self.nodes.as_mut() {
+            cache.insert(token, wrapper);
+        }
+    }
+
     /// The Document's parse-warning Array.
     pub fn errors(&self) -> Value {
         // SAFETY: the live Array this wrapper marks.
@@ -126,7 +238,7 @@ impl DocData {
             match self.content {
                 Content::Empty => 0,
                 Content::Html(p) => p.as_ref().external_bytes(),
-                Content::Xml(d) => crate::xml::api::xml_doc_memsize(d.as_ref()),
+                Content::Xml(d) => d.as_ref().memsize(),
             }
         }
     }
@@ -135,10 +247,21 @@ impl DocData {
 impl Hooks for DocData {
     fn mark(&self, marker: &Marker) {
         marker.mark(self.errors);
+        if let Some(cache) = self.nodes.as_ref() {
+            cache.mark(marker);
+        }
+    }
+
+    fn compact(&mut self, relocator: &Relocator) {
+        if let Some(cache) = self.nodes.as_mut() {
+            cache.compact(relocator);
+        }
     }
 
     fn memsize(&self) -> usize {
-        core::mem::size_of::<DocData>().saturating_add(self.external_bytes())
+        core::mem::size_of::<DocData>()
+            .saturating_add(self.external_bytes())
+            .saturating_add(self.nodes.as_ref().map_or(0, |c| c.memsize()))
     }
 
     fn release(&mut self) {
@@ -151,6 +274,10 @@ impl Hooks for DocData {
             }
         }
         self.content = Content::Empty;
+        /* The cache is Rust-owned heap in a struct Ruby frees with `xfree`, which
+         * does NOT run Drop - so it has to be dropped here, like the content
+         * above. `rake leaks` is what caught this one when it was missing. */
+        drop(self.nodes.take());
         /* Balance the report, or the GC keeps counting freed arenas as live
          * and collects ever more eagerly. A plain C call, as this hook has to
          * be: it only subtracts, and Ruby's own `xfree` does the same from
@@ -356,6 +483,22 @@ pub(in crate::bridge) fn with_html_parsed_known<R>(
     unsafe { f(p.as_mut()) }
 }
 
+/// The one wrapper for `token` under `rb_doc`, or None the first time.
+///
+/// `rb_doc` must be a live Document; the two `wrap_*_node` functions are the
+/// only callers and both already hold one.
+pub fn cached_node(rb_doc: Value, token: usize) -> Option<Value> {
+    // SAFETY: as `with_doc_data_known`.
+    let v = with_doc_data_known(rb_doc, |d| d.cached(token));
+    // SAFETY: a VALUE this document marks, so it is live.
+    v.map(|v| unsafe { value(v) })
+}
+
+/// Remember `wrapper` as the one wrapper for `token` under `rb_doc`.
+pub fn cache_node(rb_doc: Value, token: usize, wrapper: Value) {
+    with_doc_data_known(rb_doc, |d| d.cache(token, wrapper.as_raw()));
+}
+
 /// Run `f` over a Document's wrapper data, for the fields that are the
 /// wrapper's own rather than the content's (the evaluation count).
 fn with_doc_data_known<R>(rb_doc: Value, f: impl FnOnce(&mut DocData) -> R) -> R {