nosj 0.1.0

data/ext/nosj/Cargo.toml

@@ -0,0 +1,25 @@
+[package]
+# The PACKAGE cannot share the parser crate's name (`nosj` is a
+# dependency below); nosj_native resolves that clash and nothing else.
+# The LIB TARGET is named nosj so the artifact is libnosj → nosj.bundle,
+# required by lib/nosj.rb as "nosj/nosj" (Init_nosj set explicitly in
+# lib.rs). Gem name, module, and API are plain nosj.
+name = "nosj_native"
+version = "0.1.0"
+edition = "2021"
+authors = ["Yaroslav Markin <yaroslav@markin.net>"]
+license = "MIT"
+publish = false
+
+[lib]
+name = "nosj"
+crate-type = ["cdylib", "rlib"]
+
+[dependencies]
+magnus = { git = "https://github.com/matsadler/magnus", features = ["embed", "rb-sys"] }
+rb-sys = { version = "0.9.124", default-features = false }
+ahash = "0.8.11"
+# First-party SIMD JSON parse/generate library (github.com/yaroslav/nosj).
+# For coordinated crate+gem work, temporarily flip to
+# { path = "../../../nosj" } and restore before any commit or release.
+nosj = "0.1.1"

data/ext/nosj/extconf.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require "mkmf"
+require "rb_sys/mkmf"
+
+create_rust_makefile("nosj/nosj")

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

@@ -0,0 +1,61 @@
+//! Generation failure carriers and their mapping onto the gem's
+//! exception classes (NOSJ::GeneratorError, NOSJ::NestingError, or a
+//! re-raise of the user's own exception).
+
+use magnus::error::ErrorType;
+use magnus::rb_sys::AsRawValue;
+use magnus::value::ReprValue;
+use magnus::{Error, ExceptionClass, Module, RModule, Ruby};
+
+use super::ruby::rstring_bytes;
+
+pub(super) enum GenFail {
+    /// Re-raise a Ruby exception captured by a protected call (user
+    /// `to_json` or `to_s`).
+    Reraise(Error),
+    /// NOSJ::GeneratorError with this message.
+    Generator(String),
+    /// NOSJ::GeneratorError carrying the caught exception's message
+    /// (encoding conversion failures; the gem wraps these the same way).
+    GeneratorFrom(Error),
+    /// NOSJ::NestingError naming the configured limit.
+    Nesting(usize),
+}
+
+fn nosj_exception(ruby: &Ruby, name: &str) -> ExceptionClass {
+    let lookup = || -> Result<ExceptionClass, Error> {
+        let m: RModule = ruby.define_module("NOSJ")?;
+        m.const_get(name)
+    };
+    lookup().unwrap_or_else(|_| ruby.exception_runtime_error())
+}
+
+/// The exception's `to_s` (its message), matching what the gem embeds
+/// when it wraps a secondary exception.
+fn error_message(err: &Error) -> String {
+    if let ErrorType::Exception(exc) = err.error_type() {
+        let s = unsafe { rb_sys::rb_obj_as_string(exc.as_value().as_raw()) };
+        // Safety: rb_obj_as_string returns a T_STRING; the bytes are
+        // copied into an owned String before any further Ruby call.
+        let bytes = unsafe { rstring_bytes(s) };
+        return String::from_utf8_lossy(bytes).into_owned();
+    }
+    err.to_string()
+}
+
+pub(super) fn raise_fail(ruby: &Ruby, fail: GenFail) -> Error {
+    match fail {
+        GenFail::Reraise(err) => err,
+        GenFail::Generator(msg) => Error::new(nosj_exception(ruby, "GeneratorError"), msg),
+        GenFail::GeneratorFrom(err) => {
+            let msg = error_message(&err);
+            Error::new(nosj_exception(ruby, "GeneratorError"), msg)
+        }
+        GenFail::Nesting(limit) => Error::new(
+            nosj_exception(ruby, "NestingError"),
+            format!(
+                "nesting of {limit} is too deep. Did you try to serialize objects with circular references?"
+            ),
+        ),
+    }
+}

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

@@ -0,0 +1,53 @@
+//! The one hand-written C-ABI callback in this extension.
+//!
+//! Ruby's only allocation-free hash iteration is `rb_hash_foreach`,
+//! which takes a C function pointer. magnus's closure wrapper for it
+//! (`RHash::foreach`) costs a measured 3-8% on object-heavy
+//! generation (per-pair `Value` wrapping, Ruby-handle construction,
+//! and result plumbing), so this module packs the same closure shape
+//! over the raw API: the closure is monomorphized straight into the
+//! trampoline and a pair costs exactly the callback dispatch.
+//! Everything else in the extension stays on magnus.
+
+use rb_sys::VALUE;
+use std::os::raw::c_int;
+
+/// Continue/stop signal from the per-pair closure, mirroring
+/// `st_retval`'s two values the callback may return here.
+pub(super) enum Step {
+    Continue,
+    Stop,
+}
+
+/// Iterate `hash`'s pairs, passing raw VALUEs to `f`.
+///
+/// The closure must not let a Ruby exception cross this frame (route
+/// raising calls through magnus's protect and report via [`Step`]);
+/// panics abort the process (the extension builds with panic=abort),
+/// never unwind into C.
+///
+/// # Safety
+///
+/// `hash` must be a live `T_HASH` VALUE.
+pub(super) unsafe fn foreach_raw<F>(hash: VALUE, mut f: F)
+where
+    F: FnMut(VALUE, VALUE) -> Step,
+{
+    unsafe extern "C" fn trampoline<F>(k: VALUE, v: VALUE, arg: VALUE) -> c_int
+    where
+        F: FnMut(VALUE, VALUE) -> Step,
+    {
+        let f = unsafe { &mut *(arg as *mut F) };
+        match f(k, v) {
+            Step::Continue => 0,
+            Step::Stop => 1,
+        }
+    }
+    unsafe {
+        rb_sys::rb_hash_foreach(
+            hash,
+            Some(trampoline::<F>),
+            std::ptr::from_mut(&mut f) as VALUE,
+        );
+    }
+}

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

@@ -0,0 +1,58 @@
+//! Pre-escaped object-key cache for generation.
+
+use rb_sys::VALUE;
+
+use crate::state::{ensure_marked_shadow, VStackShadow};
+
+/// Epoch eviction, like the parse-side key cache: at capacity the whole map
+/// is cleared and hot keys repopulate; one unique-key-heavy document must
+/// not degrade every later document.
+const GEN_KEY_CACHE_CAP: usize = 2048;
+
+/// Cache of quoted-and-escaped key bytes, keyed on the key string's VALUE
+/// identity. Sound because Ruby freezes all string hash keys (immutable
+/// content) and the GC-marked shadow keeps every cached key alive (an
+/// address can never be reused for a different string while cached).
+/// Documents emit few unique keys many times over (twitter: 94 unique keys,
+/// 13,345 emissions), so key emission collapses to one short copy.
+///
+/// Taken out of the thread-local for the duration of a generate call (like
+/// the output buffer): recursive generation via a user `to_json` sees a
+/// fresh default and cannot double-borrow.
+#[derive(Default)]
+pub(super) struct GenKeyCache {
+    map: ahash::AHashMap<VALUE, Box<[u8]>>,
+    shadow: Option<&'static mut VStackShadow>,
+}
+
+impl GenKeyCache {
+    pub(super) fn with_capacity(n: usize) -> Self {
+        GenKeyCache {
+            map: ahash::AHashMap::with_capacity(n),
+            shadow: None,
+        }
+    }
+
+    #[inline]
+    pub(super) fn get(&self, k: VALUE) -> Option<&[u8]> {
+        self.map.get(&k).map(Box::as_ref)
+    }
+
+    /// Cache `bytes` for `k`, evicting the whole epoch at capacity and
+    /// registering `k` with the GC-marked shadow that keeps it alive.
+    pub(super) fn store(&mut self, k: VALUE, bytes: Box<[u8]>) {
+        if self.map.len() >= GEN_KEY_CACHE_CAP {
+            self.map.clear();
+            if let Some(shadow) = self.shadow.as_mut() {
+                shadow.values.clear();
+            }
+        }
+        ensure_marked_shadow(&mut self.shadow);
+        self.shadow
+            .as_mut()
+            .expect("shadow just ensured")
+            .values
+            .push(k);
+        self.map.insert(k, bytes);
+    }
+}

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

@@ -0,0 +1,171 @@
+//! JSON generation: walks a Ruby object graph and emits JSON bytes through
+//! nosj's SIMD emission kernels (escape scanning, Ruby-format floats).
+//! Matches the JSON gem's `generate` semantics: same output bytes, same
+//! error classes and messages, same options.
+//!
+//! - `opts.rs`: option-hash decoding into [`opts::GenConfig`].
+//! - `walker.rs`: the recursive emitter (compact/pretty const-generic).
+//! - `keys.rs`: the pre-escaped, VALUE-identity key cache.
+//! - `ruby.rs`: `rb_protect` shims and inline RBasic flag readers.
+//! - `errors.rs`: failure carriers mapped onto the gem's exceptions.
+//!
+//! Tried and rejected (2026-07-15, measured on Zen 4 AND Apple
+//! Silicon): emitting through the crate's `EmitBuf` trait straight
+//! into the returned Ruby String (both a pure heap-String buffer and a
+//! stack-prefix hybrid with last-output-size spill hints). It removes
+//! the final `rb_utf8_str_new` copy, and twitter generation won one
+//! roll on Zen 4 (0.96), but the per-call multi-MB String allocation
+//! loses to this warm pooled Vec everywhere else: ARM gsoc generation
+//! regressed a deterministic 1.42x (13/13 wins fell to 10/13), x86
+//! tiny documents up to 1.29x. The final copy was never the expensive
+//! part; the warm buffer is.
+
+mod errors;
+mod hash_iter;
+mod keys;
+mod opts;
+mod ruby;
+mod walker;
+
+use magnus::rb_sys::{AsRawValue, FromRawValue};
+use magnus::{Error, RString, Ruby, Value};
+use std::cell::RefCell;
+
+use errors::raise_fail;
+use keys::GenKeyCache;
+use walker::Gen;
+
+/// Per-thread generate scratch: the pooled output buffer (capacity
+/// survives across calls) and the pre-escaped key cache. One
+/// thread_local, borrowed ONCE for the whole call: in a shared library
+/// every thread_local access is a `__tls_get_addr` call, and the old
+/// take/put-back shape paid two of them plus struct moves per call
+/// (measurable on 45-byte documents). A recursive generate via a user
+/// `to_json` hits the failed `try_borrow_mut` arm and runs on a fresh
+/// scratch instead of panicking the RefCell.
+struct GenScratch {
+    buf: Vec<u8>,
+    keys: GenKeyCache,
+}
+
+thread_local! {
+    static GEN_SCRATCH: RefCell<GenScratch> = RefCell::new(GenScratch {
+        buf: Vec::new(),
+        keys: GenKeyCache::with_capacity(256),
+    });
+}
+
+/// `NOSJ.generate(obj, opts = nil)`, registered as a variadic native
+/// method: no Ruby forwarder frame, and the nil-options path borrows
+/// the shared [`opts::DEFAULT_CONFIG`] instead of building a config.
+pub fn generate_entry(ruby: &Ruby, _rb_self: Value, args: &[Value]) -> Result<RString, Error> {
+    use magnus::value::ReprValue;
+    let (obj, opts) = match *args {
+        [obj] => (obj, None),
+        [obj, opts] if opts.is_nil() => (obj, None),
+        [obj, opts] => (obj, Some(opts)),
+        _ => {
+            return Err(Error::new(
+                ruby.exception_arg_error(),
+                format!(
+                    "wrong number of arguments (given {}, expected 1..2)",
+                    args.len()
+                ),
+            ));
+        }
+    };
+    let built;
+    let (cfg, cap_hint): (&opts::GenConfig, usize) = match opts {
+        None => (&opts::DEFAULT_CONFIG, 0),
+        Some(o) => {
+            let (c, hint) = opts::parse_gen_opts(ruby, o)?;
+            built = c;
+            (&built, hint)
+        }
+    };
+    generate_scratched(ruby, obj, cfg, cap_hint)
+}
+
+/// `NOSJ.generate_native(obj, opts)`: the fixed-arity entry kept for
+/// the Ruby-level wrappers (pretty_generate merges options first).
+pub fn generate_native(
+    ruby: &Ruby,
+    _rb_self: Value,
+    obj: Value,
+    opts: Value,
+) -> Result<RString, Error> {
+    use magnus::value::ReprValue;
+    if opts.is_nil() {
+        return generate_scratched(ruby, obj, &opts::DEFAULT_CONFIG, 0);
+    }
+    let (cfg, cap_hint) = opts::parse_gen_opts(ruby, opts)?;
+    generate_scratched(ruby, obj, &cfg, cap_hint)
+}
+
+fn generate_scratched(
+    ruby: &Ruby,
+    obj: Value,
+    cfg: &opts::GenConfig,
+    cap_hint: usize,
+) -> Result<RString, Error> {
+    GEN_SCRATCH.with(|cell| match cell.try_borrow_mut() {
+        Ok(mut scratch) => {
+            let scratch = &mut *scratch;
+            generate_with(
+                ruby,
+                obj,
+                cfg,
+                cap_hint,
+                &mut scratch.buf,
+                &mut scratch.keys,
+            )
+        }
+        Err(_) => {
+            let mut buf = Vec::new();
+            let mut keys = GenKeyCache::default();
+            generate_with(ruby, obj, cfg, cap_hint, &mut buf, &mut keys)
+        }
+    })
+}
+
+fn generate_with(
+    ruby: &Ruby,
+    obj: Value,
+    cfg: &opts::GenConfig,
+    cap_hint: usize,
+    out: &mut Vec<u8>,
+    keys: &mut GenKeyCache,
+) -> Result<RString, Error> {
+    out.clear();
+    if out.capacity() < cap_hint {
+        out.reserve(cap_hint);
+    }
+
+    let mut g = Gen {
+        out,
+        cfg,
+        fail: None,
+        keys,
+    };
+    let result = if cfg.pretty {
+        g.emit_value::<true>(obj.as_raw(), cfg.start_depth)
+    } else {
+        g.emit_value::<false>(obj.as_raw(), cfg.start_depth)
+    };
+
+    let Gen { out, fail, .. } = g;
+    match (result, fail) {
+        (Ok(()), None) => Ok(unsafe {
+            RString::from_value(Value::from_raw(rb_sys::rb_utf8_str_new(
+                out.as_ptr().cast(),
+                out.len() as std::os::raw::c_long,
+            )))
+            .expect("rb_utf8_str_new returns a String")
+        }),
+        (_, Some(fail)) => Err(raise_fail(ruby, fail)),
+        (Err(()), None) => Err(Error::new(
+            ruby.exception_runtime_error(),
+            "generation failed without error detail",
+        )),
+    }
+}

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

@@ -0,0 +1,162 @@
+//! JSON.generate-compatible option decoding: formatting strings, escape
+//! mode, nesting limits, and the buffer size hint.
+
+use magnus::value::ReprValue;
+use magnus::{Error, RHash, RString, Ruby, Value};
+use nosj::emit::EscapeMode;
+
+pub(super) struct GenConfig {
+    pub(super) indent: Vec<u8>,
+    pub(super) space: Vec<u8>,
+    pub(super) space_before: Vec<u8>,
+    pub(super) object_nl: Vec<u8>,
+    pub(super) array_nl: Vec<u8>,
+    /// 0 = unlimited.
+    pub(super) max_nesting: usize,
+    pub(super) start_depth: usize,
+    pub(super) allow_nan: bool,
+    pub(super) strict: bool,
+    pub(super) mode: EscapeMode,
+    /// Precomputed "any formatting string set": scanning the five
+    /// vectors per call was measurable on tiny documents.
+    pub(super) pretty: bool,
+}
+
+/// The nil-options configuration, shared instead of rebuilt: stamping
+/// a fresh ~140-byte GenConfig onto the stack per call was measurable
+/// on tiny documents (the json gem likewise reuses a cached State for
+/// the default options). Safe as a static: `Vec::new` is const and
+/// allocation-free, and generation only ever borrows the config.
+pub(super) static DEFAULT_CONFIG: GenConfig = GenConfig {
+    indent: Vec::new(),
+    space: Vec::new(),
+    space_before: Vec::new(),
+    object_nl: Vec::new(),
+    array_nl: Vec::new(),
+    max_nesting: 100,
+    start_depth: 0,
+    allow_nan: false,
+    strict: false,
+    mode: EscapeMode::Standard,
+    pretty: false,
+};
+
+impl Default for GenConfig {
+    fn default() -> Self {
+        GenConfig {
+            indent: Vec::new(),
+            space: Vec::new(),
+            space_before: Vec::new(),
+            object_nl: Vec::new(),
+            array_nl: Vec::new(),
+            max_nesting: 100,
+            start_depth: 0,
+            allow_nan: false,
+            strict: false,
+            mode: EscapeMode::Standard,
+            pretty: false,
+        }
+    }
+}
+
+fn opt_bytes(ruby: &Ruby, opts: RHash, name: &str) -> Result<Option<Vec<u8>>, Error> {
+    let v: Value = opts
+        .get(ruby.to_symbol(name))
+        .unwrap_or_else(|| ruby.qnil().as_value());
+    if v.is_nil() {
+        return Ok(None);
+    }
+    let s = RString::from_value(v).ok_or_else(|| {
+        Error::new(
+            ruby.exception_type_error(),
+            format!("{name} must be a String"),
+        )
+    })?;
+    Ok(Some(unsafe { s.as_slice() }.to_vec()))
+}
+
+fn opt_bool(ruby: &Ruby, opts: RHash, name: &str) -> Option<bool> {
+    let v: Value = opts.get(ruby.to_symbol(name))?;
+    if v.is_nil() {
+        None
+    } else {
+        Some(v.to_bool())
+    }
+}
+
+/// Decode a non-nil options hash (nil takes [`DEFAULT_CONFIG`] at the
+/// call site without constructing anything).
+pub(super) fn parse_gen_opts(ruby: &Ruby, opts: Value) -> Result<(GenConfig, usize), Error> {
+    let mut cfg = GenConfig::default();
+    let mut cap_hint = 0usize;
+    if opts.is_nil() {
+        return Ok((cfg, cap_hint));
+    }
+    let opts = RHash::from_value(opts)
+        .ok_or_else(|| Error::new(ruby.exception_type_error(), "options must be a Hash or nil"))?;
+
+    if let Some(v) = opt_bytes(ruby, opts, "indent")? {
+        cfg.indent = v;
+    }
+    if let Some(v) = opt_bytes(ruby, opts, "space")? {
+        cfg.space = v;
+    }
+    if let Some(v) = opt_bytes(ruby, opts, "space_before")? {
+        cfg.space_before = v;
+    }
+    if let Some(v) = opt_bytes(ruby, opts, "object_nl")? {
+        cfg.object_nl = v;
+    }
+    if let Some(v) = opt_bytes(ruby, opts, "array_nl")? {
+        cfg.array_nl = v;
+    }
+    if let Some(v) = opt_bool(ruby, opts, "allow_nan") {
+        cfg.allow_nan = v;
+    }
+    if let Some(v) = opt_bool(ruby, opts, "strict") {
+        cfg.strict = v;
+    }
+    let ascii = opt_bool(ruby, opts, "ascii_only").unwrap_or(false);
+    let script = opt_bool(ruby, opts, "script_safe").unwrap_or(false)
+        || opt_bool(ruby, opts, "escape_slash").unwrap_or(false);
+    if ascii {
+        cfg.mode = EscapeMode::AsciiOnly;
+        if script {
+            return Err(Error::new(
+                ruby.exception_arg_error(),
+                "NOSJ.generate: ascii_only and script_safe cannot be combined",
+            ));
+        }
+    } else if script {
+        cfg.mode = EscapeMode::ScriptSafe;
+    }
+    if let Some(v) = opts.get(ruby.to_symbol("max_nesting")) {
+        let v: Value = v;
+        // nil/false → unlimited; true → keep the default 100; Integer → limit.
+        if !v.to_bool() {
+            cfg.max_nesting = 0;
+        } else if let Ok(n) = <i64 as magnus::TryConvert>::try_convert(v) {
+            cfg.max_nesting = if n <= 0 { 0 } else { n as usize };
+        }
+    }
+    if let Some(v) = opts.get(ruby.to_symbol("depth")) {
+        let v: Value = v;
+        if let Ok(n) = <i64 as magnus::TryConvert>::try_convert(v) {
+            cfg.start_depth = if n <= 0 { 0 } else { n as usize };
+        }
+    }
+    if let Some(v) = opts.get(ruby.to_symbol("buffer_initial_length")) {
+        let v: Value = v;
+        if let Ok(n) = <i64 as magnus::TryConvert>::try_convert(v) {
+            if n > 0 {
+                cap_hint = n as usize;
+            }
+        }
+    }
+    cfg.pretty = !(cfg.indent.is_empty()
+        && cfg.space.is_empty()
+        && cfg.space_before.is_empty()
+        && cfg.object_nl.is_empty()
+        && cfg.array_nl.is_empty());
+    Ok((cfg, cap_hint))
+}

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

@@ -0,0 +1,100 @@
+//! Low-level Ruby helpers for generation: protected wrappers over the
+//! user-reachable raising calls (a Ruby raise longjmping through Rust
+//! frames is UB, so each goes through magnus's closure-based
+//! `rb_sys::protect`; magnus owns the FFI trampoline) and inline
+//! RBasic flag readers.
+
+use magnus::Error;
+use rb_sys::{ruby_special_consts, VALUE};
+use std::os::raw::c_int;
+use std::sync::OnceLock;
+
+pub(super) const QNIL: VALUE = ruby_special_consts::RUBY_Qnil as VALUE;
+pub(super) const QTRUE: VALUE = ruby_special_consts::RUBY_Qtrue as VALUE;
+pub(super) const QFALSE: VALUE = ruby_special_consts::RUBY_Qfalse as VALUE;
+
+/// `v.to_s`, protected.
+pub(super) fn protected_to_s(v: VALUE) -> Result<VALUE, Error> {
+    magnus::rb_sys::protect(|| unsafe { rb_sys::rb_obj_as_string(v) })
+}
+
+/// `v.to_json`, protected.
+pub(super) fn protected_to_json(v: VALUE) -> Result<VALUE, Error> {
+    magnus::rb_sys::protect(|| unsafe { rb_sys::rb_funcall(v, to_json_id(), 0) })
+}
+
+/// Encode `v` to UTF-8, protected. `rb_str_encode` raises on
+/// undefined/invalid conversions, matching the gem, which wraps that
+/// exception as GeneratorError (`rb_str_export_to_enc` is lenient and
+/// silently passes bad bytes through).
+pub(super) fn protected_encode_utf8(v: VALUE) -> Result<VALUE, Error> {
+    magnus::rb_sys::protect(|| unsafe {
+        let utf8 = rb_sys::rb_enc_from_encoding(rb_sys::rb_utf8_encoding());
+        rb_sys::rb_str_encode(v, utf8, 0, QNIL)
+    })
+}
+
+/// Interned `to_json` method ID, resolved once per process.
+pub(super) fn to_json_id() -> rb_sys::ID {
+    static TO_JSON: OnceLock<usize> = OnceLock::new();
+    *TO_JSON.get_or_init(|| unsafe { rb_sys::rb_intern(c"to_json".as_ptr()) } as usize)
+        as rb_sys::ID
+}
+
+pub(super) fn utf8_encindexes() -> (c_int, c_int) {
+    static IDX: OnceLock<(c_int, c_int)> = OnceLock::new();
+    *IDX.get_or_init(|| unsafe { (rb_sys::rb_utf8_encindex(), rb_sys::rb_usascii_encindex()) })
+}
+
+// Coderange and encoding index live in RBasic flags (public ABI); reading
+// them inline instead of calling rb_enc_str_coderange / rb_enc_get_index is
+// how the gem avoids two C calls per string (RB_ENC_CODERANGE,
+// RB_ENCODING_GET_INLINED).
+const CR_MASK: u64 = 3 << 20;
+pub(super) const CR_7BIT: u64 = 1 << 20;
+pub(super) const CR_VALID: u64 = 2 << 20;
+const ENC_SHIFT: u64 = 22;
+const ENC_MASK: u64 = 127 << 22;
+
+#[inline(always)]
+pub(super) fn str_coderange(s: VALUE) -> u64 {
+    let flags = unsafe { (*(s as *const rb_sys::RBasic)).flags };
+    let cr = flags & CR_MASK;
+    if cr != 0 {
+        cr
+    } else {
+        (unsafe { rb_sys::rb_enc_str_coderange(s) } as u64) & CR_MASK
+    }
+}
+
+#[inline(always)]
+pub(super) fn str_enc_index(s: VALUE) -> c_int {
+    let flags = unsafe { (*(s as *const rb_sys::RBasic)).flags };
+    let idx = ((flags & ENC_MASK) >> ENC_SHIFT) as c_int;
+    if idx == 127 {
+        // RUBY_ENCODING_INLINE_MAX sentinel: index stored out of line.
+        unsafe { rb_sys::rb_enc_get_index(s) }
+    } else {
+        idx
+    }
+}
+
+#[inline(always)]
+pub(super) fn is_special_const(v: VALUE) -> bool {
+    // RB_SPECIAL_CONST_P: immediates plus Qnil/Qfalse.
+    (v & (ruby_special_consts::RUBY_IMMEDIATE_MASK as VALUE)) != 0 || v == QNIL || v == QFALSE
+}
+
+/// Borrow a Ruby String's bytes.
+///
+/// # Safety
+/// `s` must be a `T_STRING` VALUE. The slice borrows the Ruby heap: it is
+/// valid only until the next call that could mutate, reallocate, or free
+/// the string, so callers must copy the bytes out before any Ruby call.
+#[inline(always)]
+pub(super) unsafe fn rstring_bytes<'a>(s: VALUE) -> &'a [u8] {
+    std::slice::from_raw_parts(
+        rb_sys::macros::RSTRING_PTR(s).cast::<u8>(),
+        rb_sys::macros::RSTRING_LEN(s) as usize,
+    )
+}