nosj 0.1.0 → 0.3.0

data/ext/nosj/src/gen/walker.rs

@@ -3,7 +3,7 @@
 //! Compact and pretty modes are one const-generic body, so the compact
 //! hot path carries no formatting branches.
 
-use nosj::emit::{self, EscapeMode};
+use nosj::emit::{self, copy_short_raw, EscapeMode};
 use rb_sys::macros::{
     FIX2LONG, FIXNUM_P, FLONUM_P, RARRAY_CONST_PTR, RARRAY_LEN, RB_BUILTIN_TYPE, RHASH_SIZE,
     STATIC_SYM_P,
@@ -14,52 +14,16 @@ use super::errors::GenFail;
 use super::keys::GenKeyCache;
 use super::opts::GenConfig;
 use super::ruby::{
-    is_special_const, protected_encode_utf8, protected_to_json, protected_to_s, rstring_bytes,
-    str_coderange, str_enc_index, to_json_id, utf8_encindexes, CR_7BIT, CR_VALID, QFALSE, QNIL,
-    QTRUE,
+    is_json_fragment, is_special_const, protected_as_json, protected_encode_utf8,
+    protected_to_json, protected_to_s, rstring_bytes, str_coderange, str_enc_index, to_json_id,
+    utf8_encindexes, CR_7BIT, CR_VALID, QFALSE, QNIL, QTRUE,
 };
 
-/// Overlapping-word copy for short runs through a raw pointer (the
-/// crate's `copy_small` shape, local because that helper is
-/// crate-internal): a size-laddered pair of unaligned loads/stores
-/// instead of a libc memmove call, whose per-call overhead measured
-/// 42% on tiny-copy-heavy generation. Cached keys over 32 bytes are
-/// rare enough for the memcpy fallback.
-///
-/// # Safety
-///
-/// `n` readable bytes at `src`, `n` writable bytes at `dst`, and the
-/// ranges must not overlap.
-#[inline(always)]
-unsafe fn copy_short_raw(src: *const u8, dst: *mut u8, n: usize) {
-    /// One overlapping pair: word-size chunks at offset 0 and at
-    /// `n - size` cover `size..=2*size` bytes; the overlapped middle
-    /// is written twice with identical data.
-    macro_rules! word_pair {
-        ($t:ty) => {{
-            const SIZE: usize = size_of::<$t>();
-            dst.cast::<$t>()
-                .write_unaligned(src.cast::<$t>().read_unaligned());
-            dst.add(n - SIZE)
-                .cast::<$t>()
-                .write_unaligned(src.add(n - SIZE).cast::<$t>().read_unaligned());
-        }};
-    }
-    if n >= 16 {
-        if n <= 32 {
-            word_pair!(u128);
-        } else {
-            std::ptr::copy_nonoverlapping(src, dst, n);
-        }
-    } else if n >= 8 {
-        word_pair!(u64);
-    } else if n >= 4 {
-        word_pair!(u32);
-    } else if n >= 2 {
-        word_pair!(u16);
-    } else if n == 1 {
-        *dst = *src;
-    }
+/// Whether keys escaped under `mode` may be cached: the cached bytes
+/// bake in the escape mode, so the scratch keeps one cache per
+/// cacheable mode and hands `Gen` the matching one.
+pub(super) fn mode_cacheable(mode: EscapeMode) -> bool {
+    matches!(mode, EscapeMode::Standard | EscapeMode::HtmlSafe)
 }
 
 pub(super) struct Gen<'a> {
@@ -69,6 +33,7 @@ pub(super) struct Gen<'a> {
     pub(super) fail: Option<GenFail>,
     /// Pre-escaped key cache, borrowed for the whole document (one
     /// thread-local borrow per generate call instead of one per key).
+    /// Always the cache matching `cfg.mode` (see [`mode_cacheable`]).
     pub(super) keys: &'a mut GenKeyCache,
 }
 
@@ -149,6 +114,11 @@ impl Gen<'_> {
             emit::write_f64(&mut *self.out, f);
             return Ok(());
         }
+        if self.cfg.rails {
+            // ActiveSupport's Float#as_json: non-finite floats are null.
+            self.out.extend_from_slice(b"null");
+            return Ok(());
+        }
         let name = if f.is_nan() {
             "NaN"
         } else if f > 0.0 {
@@ -166,13 +136,14 @@ impl Gen<'_> {
     }
 
     /// Emit an object key from the pre-escaped cache. Only frozen string
-    /// keys in Standard escape mode are cacheable: frozen guarantees the
-    /// content behind the VALUE can't change, and the cached bytes bake in
-    /// the escape mode.
+    /// keys in a cacheable escape mode qualify: frozen guarantees the
+    /// content behind the VALUE can't change, and the cached bytes bake
+    /// in the escape mode, so each cacheable mode gets its own cache
+    /// instance from the scratch (see [`mode_cacheable`]).
     fn emit_key_cached(&mut self, k: VALUE) -> Result<(), ()> {
         const FL_FREEZE: u64 = rb_sys::ruby_fl_type::RUBY_FL_FREEZE as u64;
         let frozen = unsafe { (*(k as *const rb_sys::RBasic)).flags } & FL_FREEZE != 0;
-        if !frozen || self.cfg.mode != EscapeMode::Standard {
+        if !frozen || !mode_cacheable(self.cfg.mode) {
             return self.emit_rstring_quoted(k);
         }
         if let Some(bytes) = self.keys.get(k) {
@@ -190,13 +161,13 @@ impl Gen<'_> {
     }
 
     /// The pre-escaped bytes for `k` when the cache may serve it:
-    /// frozen string key, Standard escape mode (see [`Gen::emit_key_cached`]
-    /// for why only that combination is cacheable). An associated fn
-    /// over the split-out fields so callers keep `self.out` free.
+    /// frozen string key, cacheable escape mode (see
+    /// [`Gen::emit_key_cached`]). An associated fn over the split-out
+    /// fields so callers keep `self.out` free.
     #[inline(always)]
     fn cached_key_bytes<'k>(cfg: &GenConfig, keys: &'k GenKeyCache, k: VALUE) -> Option<&'k [u8]> {
         const FL_FREEZE: u64 = rb_sys::ruby_fl_type::RUBY_FL_FREEZE as u64;
-        if cfg.mode == EscapeMode::Standard
+        if mode_cacheable(cfg.mode)
             && !is_special_const(k)
             && unsafe { RB_BUILTIN_TYPE(k) } == ruby_value_type::RUBY_T_STRING
             && unsafe { (*(k as *const rb_sys::RBasic)).flags } & FL_FREEZE != 0
@@ -303,11 +274,20 @@ impl Gen<'_> {
         }
     }
 
-    /// Non-native type: strict raises; otherwise `to_json` if the object
-    /// responds (result appended verbatim), else `to_s` as a JSON string,
-    /// which is exactly what the gem's `Object#to_json` does.
-    fn emit_fallback(&mut self, raw: VALUE) -> Result<(), ()> {
+    /// Non-native type: strict raises (except `JSON::Fragment`, which
+    /// the gem splices even under strict); otherwise `to_json` if the
+    /// object responds (result appended verbatim), else `to_s` as a
+    /// JSON string, which is exactly what the gem's `Object#to_json`
+    /// does. Rails mode recurses through `as_json` instead
+    /// (JSONGemEncoder#jsonify).
+    fn emit_fallback<const PRETTY: bool>(&mut self, raw: VALUE, depth: usize) -> Result<(), ()> {
+        if self.cfg.rails {
+            return self.emit_rails_fallback::<PRETTY>(raw, depth);
+        }
         if self.cfg.strict {
+            if is_json_fragment(raw) {
+                return self.splice_to_json(raw);
+            }
             let name = unsafe {
                 std::ffi::CStr::from_ptr(rb_sys::rb_obj_classname(raw))
                     .to_string_lossy()
@@ -341,6 +321,64 @@ impl Gen<'_> {
         }
     }
 
+    /// Splice `raw`'s `to_json` result verbatim: the JSON::Fragment
+    /// path (pre-rendered JSON, trusted like the gem trusts it).
+    fn splice_to_json(&mut self, raw: VALUE) -> Result<(), ()> {
+        match protected_to_json(raw) {
+            Ok(json)
+                if !is_special_const(json)
+                    && unsafe { RB_BUILTIN_TYPE(json) } == ruby_value_type::RUBY_T_STRING =>
+            {
+                self.append_rstring_raw(json);
+                Ok(())
+            }
+            Ok(_) => {
+                self.fail = Some(GenFail::Generator(
+                    "JSON::Fragment#to_json did not return a String".to_string(),
+                ));
+                Err(())
+            }
+            Err(exc) => {
+                self.fail = Some(GenFail::Reraise(exc));
+                Err(())
+            }
+        }
+    }
+
+    /// Rails-mode fallback, mirroring JSONGemEncoder#jsonify:
+    /// fragments splice through (like ActiveSupport passes them to the
+    /// gem); everything else is asked for its as_json representation
+    /// (no arguments; only the top-level value receives the encoder
+    /// options), which is emitted in its place. An as_json returning
+    /// the receiver would recurse forever, so it raises instead.
+    fn emit_rails_fallback<const PRETTY: bool>(
+        &mut self,
+        raw: VALUE,
+        depth: usize,
+    ) -> Result<(), ()> {
+        if is_json_fragment(raw) {
+            return self.splice_to_json(raw);
+        }
+        match protected_as_json(raw) {
+            Ok(json) if json == raw => {
+                let name = unsafe {
+                    std::ffi::CStr::from_ptr(rb_sys::rb_obj_classname(raw))
+                        .to_string_lossy()
+                        .into_owned()
+                };
+                self.fail = Some(GenFail::Generator(format!(
+                    "{name}#as_json returned the receiver"
+                )));
+                Err(())
+            }
+            Ok(json) => self.emit_value::<PRETTY>(json, depth),
+            Err(exc) => {
+                self.fail = Some(GenFail::Reraise(exc));
+                Err(())
+            }
+        }
+    }
+
     fn nesting_check(&mut self, inner: usize) -> Result<(), ()> {
         if self.cfg.max_nesting > 0 && inner > self.cfg.max_nesting {
             self.fail = Some(GenFail::Nesting(self.cfg.max_nesting));
@@ -601,7 +639,7 @@ impl Gen<'_> {
                     let s = unsafe { rb_sys::rb_sym2str(raw) };
                     self.emit_rstring_quoted(s)
                 }
-                _ => self.emit_fallback(raw),
+                _ => self.emit_fallback::<PRETTY>(raw, depth),
             };
         }
         if FIXNUM_P(raw) {
@@ -633,6 +671,6 @@ impl Gen<'_> {
             let s = unsafe { rb_sys::rb_sym2str(raw) };
             return self.emit_rstring_quoted(s);
         }
-        self.emit_fallback(raw)
+        self.emit_fallback::<PRETTY>(raw, depth)
     }
 }

data/ext/nosj/src/lazy.rs

@@ -0,0 +1,422 @@
+//! Lazy documents: `NOSJ.lazy` wraps a JSON document and resolves
+//! access on demand through the crate's pointer skipper. Every node is
+//! a byte span into a shared, immutable copy of the document; container
+//! children come back as further lazy nodes, scalars materialize
+//! immediately through the same sink machinery as a full parse. Nothing
+//! outside the touched path is ever parsed, so pulling a few fields out
+//! of a large document costs microseconds, not a full parse.
+//!
+//! Validation is as-you-go (the crate's skipper checks bracket balance
+//! over skipped content and fully validates resolved targets), so a
+//! malformed region raises when an access first walks it, not at
+//! `NOSJ.lazy` time.
+
+use std::sync::Arc;
+
+use magnus::typed_data::Obj;
+use magnus::value::ReprValue;
+use magnus::{DataTypeFunctions, Error, RArray, RString, Ruby, TypedData, Value};
+
+use crate::errors::parser_error_at;
+use crate::parse::{materialize_at, parse_native_opts, span_of, utf8_input, ParseNativeOpts};
+use crate::pointer::{path_to_pointer, push_escaped_token};
+use crate::state::PULL_STATE;
+
+/// The document bytes behind a node tree. A frozen Ruby source is
+/// borrowed zero-copy: freezing rules out mutation, and every node
+/// GC-marks the string with `rb_gc_mark` semantics, which both keeps it
+/// alive and pins it against compaction, so the captured pointer stays
+/// valid for as long as any node exists. Anything else is copied once.
+pub(crate) enum DocBytes {
+    Owned(Vec<u8>),
+    Frozen {
+        source: rb_sys::VALUE,
+        ptr: *const u8,
+        len: usize,
+    },
+    /// A read-only file mapping (`NOSJ.load_lazy_file`): pages never
+    /// touched are never read off disk. Concurrent modification of the
+    /// mapped file by another process is documented as unsupported
+    /// (the standard mmap caveat).
+    Mmap(memmap2::Mmap),
+}
+
+/// The shared document: stable bytes plus the parse options every
+/// materialization from this document uses.
+struct DocInner {
+    bytes: DocBytes,
+    opts: ParseNativeOpts,
+}
+
+// SAFETY: the bytes are immutable for the document's whole life (an
+// owned Vec, or a frozen Ruby string pinned and kept alive by every
+// node's GC mark), so cross-thread reads are plain shared reads; the
+// raw VALUE is only dereferenced by the GC mark, which runs at
+// safepoints (the ShadowHandle contract in state.rs). There is no
+// interior mutability anywhere in the type.
+unsafe impl Send for DocInner {}
+unsafe impl Sync for DocInner {}
+
+impl DocInner {
+    fn bytes(&self) -> &[u8] {
+        match &self.bytes {
+            DocBytes::Owned(v) => v,
+            // SAFETY: the source string is frozen (no mutation, no
+            // buffer reallocation) and pinned+kept alive by every
+            // node's GC mark; see DocBytes.
+            DocBytes::Frozen { ptr, len, .. } => unsafe { std::slice::from_raw_parts(*ptr, *len) },
+            DocBytes::Mmap(m) => m,
+        }
+    }
+}
+
+const KIND_OBJECT: u8 = b'{';
+const KIND_ARRAY: u8 = b'[';
+
+/// One lazy container node: a byte span into its document. Spans always
+/// come from the crate's resolver (token edges within the doc bytes),
+/// and never cross the Ruby boundary, so they cannot be forged from
+/// Ruby.
+#[derive(TypedData)]
+#[magnus(class = "NOSJ::Lazy", mark)]
+pub struct LazyNode {
+    doc: Arc<DocInner>,
+    start: usize,
+    end: usize,
+    kind: u8,
+}
+
+impl DataTypeFunctions for LazyNode {
+    fn mark(&self, marker: &magnus::gc::Marker) {
+        if let DocBytes::Frozen { source, .. } = self.doc.bytes {
+            use magnus::rb_sys::FromRawValue;
+            // SAFETY: the VALUE was a live, frozen string at node
+            // creation and this mark is what keeps it that way.
+            marker.mark(unsafe { Value::from_raw(source) });
+        }
+    }
+}
+
+impl LazyNode {
+    fn span(&self) -> &[u8] {
+        &self.doc.bytes()[self.start..self.end]
+    }
+}
+
+/// Wrap a resolved raw-value slice: containers become new lazy nodes,
+/// scalars materialize now. `sub` must be a subslice of `doc.bytes`.
+fn resolved_to_value(ruby: &Ruby, doc: &Arc<DocInner>, sub: &[u8]) -> Result<Value, Error> {
+    let (start, end) = span_of(doc.bytes(), sub);
+    match sub.first().copied() {
+        Some(k) if k == KIND_OBJECT || k == KIND_ARRAY => {
+            let node = LazyNode {
+                doc: Arc::clone(doc),
+                start,
+                end,
+                kind: k,
+            };
+            let obj: Obj<LazyNode> = ruby.obj_wrap(node);
+            Ok(obj.as_value())
+        }
+        _ => materialize_at(ruby, doc.bytes(), start, end, &doc.opts),
+    }
+}
+
+/// Resolve `pointer` within `node`'s span. Shared by `__get` and
+/// `__at_pointer`; both misses and negative-index paths return nil.
+fn resolve_in_span(ruby: &Ruby, node: &LazyNode, pointer: &str) -> Result<Value, Error> {
+    // Resolve first (one PULL_STATE borrow, slice borrows the doc, not
+    // the buffers), then materialize (which re-borrows internally).
+    let resolved = PULL_STATE.with(|cell| {
+        let mut state = cell.borrow_mut();
+        // SAFETY: doc bytes were coderange-gated at NOSJ.lazy creation,
+        // and spans lie on token edges, so the span is valid UTF-8.
+        unsafe { nosj::pointer_utf8_unchecked(node.span(), pointer, &mut state.bufs) }
+    });
+    match resolved {
+        Ok(None) => Ok(ruby.qnil().as_value()),
+        Ok(Some(sub)) => resolved_to_value(ruby, &node.doc, sub.as_bytes()),
+        Err(e) if matches!(e.kind, nosj::ErrorKind::InvalidPointer) => {
+            Err(Error::new(ruby.exception_arg_error(), e.to_string()))
+        }
+        Err(e) => Err(reader_err(ruby, node, e)),
+    }
+}
+
+/// `NOSJ.lazy(source, opts)`: gate the encoding, copy the bytes, locate
+/// the root value. Container roots wrap as lazy nodes; a scalar root has
+/// nothing to defer and materializes immediately.
+///
+/// The root span is the input trimmed of surrounding whitespace; no
+/// byte of content is walked here (resolving via the "" pointer would
+/// bracket-skip the whole document just to find the same end), so
+/// malformation anywhere, including root-level trailing garbage,
+/// surfaces on first access, per the module's lazy-validation contract.
+pub fn lazy_native(
+    ruby: &Ruby,
+    _rb_self: Value,
+    data: RString,
+    opts: Value,
+) -> Result<Value, Error> {
+    let o = parse_native_opts(ruby, opts)?;
+    let input = utf8_input(ruby, &data)?;
+
+    // Frozen sources are borrowed zero-copy (see DocBytes); `data` is
+    // on the caller's machine stack, so it stays pinned through this
+    // call, and the node's mark takes over from the first GC on.
+    let bytes = if data.as_value().is_frozen() {
+        use magnus::rb_sys::AsRawValue;
+        DocBytes::Frozen {
+            source: data.as_raw(),
+            ptr: input.as_ptr(),
+            len: input.len(),
+        }
+    } else {
+        DocBytes::Owned(input.to_vec())
+    };
+    wrap_root(ruby, bytes, o)
+}
+
+/// Wrap document bytes as the root lazy value. Shared by `NOSJ.lazy`
+/// and `NOSJ.load_lazy_file`; the bytes must already be known UTF-8.
+pub(crate) fn wrap_root(
+    ruby: &Ruby,
+    bytes: DocBytes,
+    opts: ParseNativeOpts,
+) -> Result<Value, Error> {
+    const WS: [u8; 4] = *b" \t\n\r";
+    let doc = Arc::new(DocInner { bytes, opts });
+    let input = doc.bytes();
+    let Some(start) = input.iter().position(|b| !WS.contains(b)) else {
+        return Err(parser_error_at(
+            ruby,
+            input,
+            input.len(),
+            "unexpected end of input".into(),
+        ));
+    };
+    let end = input.iter().rposition(|b| !WS.contains(b)).unwrap() + 1;
+    let sub = &doc.bytes()[start..end];
+    resolved_to_value(ruby, &doc, sub)
+}
+
+/// `__get(token)`: one path step. Integer tokens are JSON Pointer
+/// indices (negative ones resolve to nil, as in NOSJ.dig); String and
+/// Symbol tokens are keys, `~`/`/`-escaped.
+pub fn lazy_get(ruby: &Ruby, rb_self: Obj<LazyNode>, token: Value) -> Result<Value, Error> {
+    let mut ptr = String::new();
+    if let Some(int) = magnus::Integer::from_value(token) {
+        let idx = int.to_i64()?;
+        if idx < 0 {
+            return Ok(ruby.qnil().as_value());
+        }
+        ptr.push('/');
+        ptr.push_str(&idx.to_string());
+    } else if let Some(s) = RString::from_value(token) {
+        push_escaped_token(&mut ptr, &s.to_string()?);
+    } else if let Some(sym) = magnus::Symbol::from_value(token) {
+        push_escaped_token(&mut ptr, &sym.name()?);
+    } else {
+        return Err(Error::new(
+            ruby.exception_arg_error(),
+            "keys must be Strings, Symbols, or Integers",
+        ));
+    }
+    resolve_in_span(ruby, &rb_self, &ptr)
+}
+
+/// `__dig(path)`: the whole dig path fused into ONE pointer resolution
+/// within this node's span, instead of one resolve (and one cached
+/// node) per step. Semantics match `NOSJ.dig`: negative indices and
+/// steps into scalars resolve to nil.
+pub fn lazy_dig(ruby: &Ruby, rb_self: Obj<LazyNode>, path: RArray) -> Result<Value, Error> {
+    match path_to_pointer(ruby, path)? {
+        Some(ptr) => resolve_in_span(ruby, &rb_self, &ptr),
+        None => Ok(ruby.qnil().as_value()),
+    }
+}
+
+/// `__at_pointer(pointer)`: a full RFC 6901 pointer, resolved within
+/// this node's subtree.
+pub fn lazy_at_pointer(
+    ruby: &Ruby,
+    rb_self: Obj<LazyNode>,
+    pointer: RString,
+) -> Result<Value, Error> {
+    let ptr = pointer.to_string()?;
+    resolve_in_span(ruby, &rb_self, &ptr)
+}
+
+/// `__materialize`: the whole span as plain Ruby values, under the
+/// document's parse options.
+pub fn lazy_materialize(ruby: &Ruby, rb_self: Obj<LazyNode>) -> Result<Value, Error> {
+    materialize_at(
+        ruby,
+        rb_self.doc.bytes(),
+        rb_self.start,
+        rb_self.end,
+        &rb_self.doc.opts,
+    )
+}
+
+/// `__kind`: `:object` or `:array`.
+pub fn lazy_kind(ruby: &Ruby, rb_self: Obj<LazyNode>) -> magnus::Symbol {
+    match rb_self.kind {
+        KIND_OBJECT => ruby.to_symbol("object"),
+        _ => ruby.to_symbol("array"),
+    }
+}
+
+/// `__byte_size`: span length in bytes (cheap; used by #inspect).
+pub fn lazy_byte_size(_ruby: &Ruby, rb_self: Obj<LazyNode>) -> usize {
+    rb_self.end - rb_self.start
+}
+
+/// A walk failure inside `node`'s span: the reader's offset is
+/// span-relative, so shift by the node's start to report an absolute
+/// document position.
+fn reader_err(ruby: &Ruby, node: &LazyNode, e: nosj::ParseError) -> Error {
+    parser_error_at(ruby, node.doc.bytes(), node.start + e.offset, e.to_string())
+}
+
+/// `__keys`: the object's decoded keys, one Reader walk, values skipped.
+pub fn lazy_keys(ruby: &Ruby, rb_self: Obj<LazyNode>) -> Result<RArray, Error> {
+    if rb_self.kind != KIND_OBJECT {
+        return Err(Error::new(
+            ruby.exception_type_error(),
+            "keys on a JSON array",
+        ));
+    }
+    let out = ruby.ary_new();
+    PULL_STATE.with(|cell| -> Result<(), Error> {
+        let mut state = cell.borrow_mut();
+        // SAFETY: spans are valid UTF-8 (see resolve_in_span).
+        let mut r = unsafe { nosj::Reader::from_utf8_unchecked(rb_self.span(), &mut state.bufs) };
+        r.next_node().map_err(|e| reader_err(ruby, &rb_self, e))?;
+        let mut has = match r
+            .object_first_key()
+            .map_err(|e| reader_err(ruby, &rb_self, e))?
+        {
+            Some(k) => {
+                out.push(ruby.str_new(k))?;
+                true
+            }
+            None => false,
+        };
+        while has {
+            r.skip_value().map_err(|e| reader_err(ruby, &rb_self, e))?;
+            has = match r
+                .object_next_key()
+                .map_err(|e| reader_err(ruby, &rb_self, e))?
+            {
+                Some(k) => {
+                    out.push(ruby.str_new(k))?;
+                    true
+                }
+                None => false,
+            };
+        }
+        Ok(())
+    })?;
+    Ok(out)
+}
+
+/// `__size`: entry count (object pairs or array elements), one walk,
+/// nothing materialized.
+pub fn lazy_size(ruby: &Ruby, rb_self: Obj<LazyNode>) -> Result<usize, Error> {
+    PULL_STATE.with(|cell| {
+        let mut state = cell.borrow_mut();
+        // SAFETY: spans are valid UTF-8 (see resolve_in_span).
+        let mut r = unsafe { nosj::Reader::from_utf8_unchecked(rb_self.span(), &mut state.bufs) };
+        r.next_node().map_err(|e| reader_err(ruby, &rb_self, e))?;
+        let mut n = 0usize;
+        if rb_self.kind == KIND_OBJECT {
+            let mut has = r
+                .object_first_key()
+                .map_err(|e| reader_err(ruby, &rb_self, e))?
+                .is_some();
+            while has {
+                n += 1;
+                r.skip_value().map_err(|e| reader_err(ruby, &rb_self, e))?;
+                has = r
+                    .object_next_key()
+                    .map_err(|e| reader_err(ruby, &rb_self, e))?
+                    .is_some();
+            }
+        } else {
+            let mut has = r.array_first().map_err(|e| reader_err(ruby, &rb_self, e))?;
+            while has {
+                n += 1;
+                r.skip_value().map_err(|e| reader_err(ruby, &rb_self, e))?;
+                has = r.array_next().map_err(|e| reader_err(ruby, &rb_self, e))?;
+            }
+        }
+        Ok(n)
+    })
+}
+
+/// A child discovered during a container walk: a doc-relative span,
+/// plus the owned key for object entries (decoded keys borrow the
+/// reader's scratch, so they are copied out before phase two).
+struct ChildDesc {
+    key: Option<String>,
+    start: usize,
+    end: usize,
+}
+
+/// `__children`: every direct child in ONE walk. Objects yield
+/// `[key, child]` pairs, arrays yield children; containers wrap lazily,
+/// scalars materialize. Two phases so the Reader's buffer borrow ends
+/// before materialization re-borrows the thread state.
+pub fn lazy_children(ruby: &Ruby, rb_self: Obj<LazyNode>) -> Result<RArray, Error> {
+    let base = rb_self.doc.bytes().as_ptr() as usize;
+    let descs: Result<Vec<ChildDesc>, nosj::ParseError> = PULL_STATE.with(|cell| {
+        let mut state = cell.borrow_mut();
+        // SAFETY: spans are valid UTF-8 (see resolve_in_span).
+        let mut r = unsafe { nosj::Reader::from_utf8_unchecked(rb_self.span(), &mut state.bufs) };
+        r.next_node()?;
+        let mut out = Vec::new();
+        if rb_self.kind == KIND_OBJECT {
+            let mut key = r.object_first_key()?.map(String::from);
+            while let Some(k) = key {
+                let sub = r.skip_value()?;
+                let start = sub.as_ptr() as usize - base;
+                out.push(ChildDesc {
+                    key: Some(k),
+                    start,
+                    end: start + sub.len(),
+                });
+                key = r.object_next_key()?.map(String::from);
+            }
+        } else {
+            let mut has = r.array_first()?;
+            while has {
+                let sub = r.skip_value()?;
+                let start = sub.as_ptr() as usize - base;
+                out.push(ChildDesc {
+                    key: None,
+                    start,
+                    end: start + sub.len(),
+                });
+                has = r.array_next()?;
+            }
+        }
+        Ok(out)
+    });
+    let descs = descs.map_err(|e| reader_err(ruby, &rb_self, e))?;
+
+    let out = ruby.ary_new_capa(descs.len());
+    for d in descs {
+        let child = resolved_to_value(ruby, &rb_self.doc, &rb_self.doc.bytes()[d.start..d.end])?;
+        match d.key {
+            Some(k) => {
+                let pair = ruby.ary_new_capa(2);
+                pair.push(ruby.str_new(&k))?;
+                pair.push(child)?;
+                out.push(pair)?;
+            }
+            None => out.push(child)?,
+        }
+    }
+    Ok(out)
+}