nosj 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 87c27bdaeada8a26a98f378d168befec0d1b50b497663bf09ea58b133358b98f
+  data.tar.gz: 0756f4a05107fabcffe58c889c7a40487c7f060d944d9b5bce161430d4e0c70f
+SHA512:
+  metadata.gz: ff14cc073152752000f9ad0102222c69e3a63ec561b8411886164c5e1c85fb30044d31e6286074169e1cc531a533b8d59d5b103473b4ae413c32c4e0d565b7f9
+  data.tar.gz: 673019e943af6446a6bb63dacaaaee002f11c07e450154abd5b0842deffc1f798e924ec3531366d2717a71391bf630d98b83b1e2320e90aa3790c83cb2cd93dd

data/CHANGELOG.md

@@ -0,0 +1,10 @@
+## [0.1.0] - 2026-07-15
+
+Initial release.
+
+- `NOSJ.parse`, `NOSJ.generate`, and `NOSJ.pretty_generate`: `json`-gem-compatible parsing and generation—same output bytes, same option names, same error classes and messages—built on the first-party SIMD [nosj](https://crates.io/crates/nosj) crate (NEON on Apple Silicon; SSE2/AVX2 on x86-64, selected at runtime). Faster than the `json` gem and the third-party parsers (Oj, RapidJSON, FastJsonparser, Yajl) across the benchmark corpus, in both directions.
+- Partial parsing: `NOSJ.dig` and `NOSJ.at_pointer` resolve a JSON Pointer and materialize only the matched subtree; `NOSJ.dig_many` and `NOSJ.at_pointers` resolve whole batches of paths in a single pass over the document.
+- `NOSJ.valid?`: full-strictness validation that allocates no Ruby objects.
+- Drop-in acceleration: `require "nosj/json"` reroutes `JSON.parse`, `JSON.generate`, `JSON.pretty_generate`, and `JSON.dump` through nosj, falling back to the original implementation for unsupported options; `require "nosj/multi_json"` adds a MultiJson adapter.
+- Precompiled platform gems, each built natively with profile-guided optimization: Linux x86-64 and arm64 (glibc and musl), macOS (Apple Silicon), Windows (x64), for Ruby 3.3 through 4.0. Other platforms compile the source gem.
+- RBS signatures and full YARD documentation.

data/Cargo.lock

@@ -0,0 +1,375 @@
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 4
+
+[[package]]
+name = "ahash"
+version = "0.8.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5a15f179cd60c4584b8a8c596927aadc462e27f2ca70c04e0071964a73ba7a75"
+dependencies = [
+ "cfg-if",
+ "getrandom",
+ "once_cell",
+ "version_check",
+ "zerocopy",
+]
+
+[[package]]
+name = "aho-corasick"
+version = "1.1.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ddd31a130427c27518df266943a5308ed92d4b226cc639f5a8f1002816174301"
+dependencies = [
+ "memchr",
+]
+
+[[package]]
+name = "bindgen"
+version = "0.72.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "993776b509cfb49c750f11b8f07a46fa23e0a1386ffc01fb1e7d343efc387895"
+dependencies = [
+ "bitflags",
+ "cexpr",
+ "clang-sys",
+ "itertools",
+ "proc-macro2",
+ "quote",
+ "regex",
+ "rustc-hash",
+ "shlex",
+ "syn",
+]
+
+[[package]]
+name = "bitflags"
+version = "2.13.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b4388bee8683e3d04af747c73422af53102d2bd24d9eadb6cbc100baef4b43f8"
+
+[[package]]
+name = "cexpr"
+version = "0.6.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6fac387a98bb7c37292057cffc56d62ecb629900026402633ae9160df93a8766"
+dependencies = [
+ "nom",
+]
+
+[[package]]
+name = "cfg-if"
+version = "1.0.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9330f8b2ff13f34540b44e946ef35111825727b38d33286ef986142615121801"
+
+[[package]]
+name = "clang-sys"
+version = "1.8.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0b023947811758c97c59bf9d1c188fd619ad4718dcaa767947df1cadb14f39f4"
+dependencies = [
+ "glob",
+ "libc",
+ "libloading",
+]
+
+[[package]]
+name = "either"
+version = "1.16.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "91622ff5e7162018101f2fea40d6ebf4a78bbe5a49736a2020649edf9693679e"
+
+[[package]]
+name = "fast-float2"
+version = "0.2.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f8eb564c5c7423d25c886fb561d1e4ee69f72354d16918afa32c08811f6b6a55"
+
+[[package]]
+name = "getrandom"
+version = "0.3.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "899def5c37c4fd7b2664648c28120ecec138e4d395b459e5ca34f9cce2dd77fd"
+dependencies = [
+ "cfg-if",
+ "libc",
+ "r-efi",
+ "wasip2",
+]
+
+[[package]]
+name = "glob"
+version = "0.3.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0cc23270f6e1808e30a928bdc84dea0b9b4136a8bc82338574f23baf47bbd280"
+
+[[package]]
+name = "itertools"
+version = "0.13.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "413ee7dfc52ee1a4949ceeb7dbc8a33f2d6c088194d9f922fb8318faf1f01186"
+dependencies = [
+ "either",
+]
+
+[[package]]
+name = "lazy_static"
+version = "1.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bbd2bcb4c963f2ddae06a2efc7e9f3591312473c50c6685e1f298068316e66fe"
+
+[[package]]
+name = "libc"
+version = "0.2.186"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "68ab91017fe16c622486840e4c83c9a37afeff978bd239b5293d61ece587de66"
+
+[[package]]
+name = "libloading"
+version = "0.8.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d7c4b02199fee7c5d21a5ae7d8cfa79a6ef5bb2fc834d6e9058e89c825efdc55"
+dependencies = [
+ "cfg-if",
+ "windows-link",
+]
+
+[[package]]
+name = "magnus"
+version = "0.9.0"
+source = "git+https://github.com/matsadler/magnus#4e46772050e47cd6cd988fa935263cc5c583e388"
+dependencies = [
+ "magnus-macros",
+ "rb-sys",
+ "rb-sys-env",
+ "seq-macro",
+]
+
+[[package]]
+name = "magnus-macros"
+version = "0.9.0"
+source = "git+https://github.com/matsadler/magnus#4e46772050e47cd6cd988fa935263cc5c583e388"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "memchr"
+version = "2.8.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cf8baf1c55e62ffcace7a9f06f4bd9cd3f0c4beb022d3b367256b91b87513d98"
+
+[[package]]
+name = "minimal-lexical"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "68354c5c6bd36d73ff3feceb05efa59b6acb7626617f4962be322a825e61f79a"
+
+[[package]]
+name = "nom"
+version = "7.1.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d273983c5a657a70a3e8f2a01329822f3b8c8172b73826411a55751e404a0a4a"
+dependencies = [
+ "memchr",
+ "minimal-lexical",
+]
+
+[[package]]
+name = "nosj"
+version = "0.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c6ecf0db23b7e9944ecee15ab3dd01b0bde0ab2a195442f363847739f667ac8d"
+dependencies = [
+ "fast-float2",
+]
+
+[[package]]
+name = "nosj_native"
+version = "0.1.0"
+dependencies = [
+ "ahash",
+ "magnus",
+ "nosj",
+ "rb-sys",
+]
+
+[[package]]
+name = "once_cell"
+version = "1.21.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50"
+
+[[package]]
+name = "proc-macro2"
+version = "1.0.106"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8fd00f0bb2e90d81d1044c2b32617f68fcb9fa3bb7640c23e9c748e53fb30934"
+dependencies = [
+ "unicode-ident",
+]
+
+[[package]]
+name = "quote"
+version = "1.0.46"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "dfbc457d0c7a0759a614551b11a6409e5951f6c7537be1f1b7682b9ae9230368"
+dependencies = [
+ "proc-macro2",
+]
+
+[[package]]
+name = "r-efi"
+version = "5.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "69cdb34c158ceb288df11e18b4bd39de994f6657d83847bdffdbd7f346754b0f"
+
+[[package]]
+name = "rb-sys"
+version = "0.9.128"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "45ca28513560e56cfb79a62b1fce363c73af170a182024ce880c77ee9429920a"
+dependencies = [
+ "rb-sys-build",
+]
+
+[[package]]
+name = "rb-sys-build"
+version = "0.9.128"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ce04b2c55eff3a21aaa623fcc655d94373238e72cac6b3e1a3641ff31649f99a"
+dependencies = [
+ "bindgen",
+ "lazy_static",
+ "proc-macro2",
+ "quote",
+ "regex",
+ "shell-words",
+ "syn",
+]
+
+[[package]]
+name = "rb-sys-env"
+version = "0.2.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cca7ad6a7e21e72151d56fe2495a259b5670e204c3adac41ee7ef676ea08117a"
+
+[[package]]
+name = "regex"
+version = "1.13.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2a0e75113e14dc5acb068cd0786884f214f1312650a3d36d269f5c4f3cdee8a2"
+dependencies = [
+ "aho-corasick",
+ "memchr",
+ "regex-automata",
+ "regex-syntax",
+]
+
+[[package]]
+name = "regex-automata"
+version = "0.4.15"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1f388202e4b80542a0921078cc23b6333bcf1409c1e3f86404cae4766a6131db"
+dependencies = [
+ "aho-corasick",
+ "memchr",
+ "regex-syntax",
+]
+
+[[package]]
+name = "regex-syntax"
+version = "0.8.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d6f6ff9a378485b298a5286656da665ba74413d36db0979633275d2e708145d4"
+
+[[package]]
+name = "rustc-hash"
+version = "2.1.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6b1e7f9a428571be2dc5bc0505c13fb6bf936822b894ec87abf8a08a4e51742d"
+
+[[package]]
+name = "seq-macro"
+version = "0.3.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1bc711410fbe7399f390ca1c3b60ad0f53f80e95c5eb935e52268a0e2cd49acc"
+
+[[package]]
+name = "shell-words"
+version = "1.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "dc6fe69c597f9c37bfeeeeeb33da3530379845f10be461a66d16d03eca2ded77"
+
+[[package]]
+name = "shlex"
+version = "1.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0fda2ff0d084019ba4d7c6f371c95d8fd75ce3524c3cb8fb653a3023f6323e64"
+
+[[package]]
+name = "syn"
+version = "2.0.119"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "872831b642d1a07999a962a351ed35b955ea2cfc8f3862091e2a240a84f17297"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
+[[package]]
+name = "unicode-ident"
+version = "1.0.24"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e6e4313cd5fcd3dad5cafa179702e2b244f760991f45397d14d4ebf38247da75"
+
+[[package]]
+name = "version_check"
+version = "0.9.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0b928f33d975fc6ad9f86c8f283853ad26bdd5b10b7f1542aa2fa15e2289105a"
+
+[[package]]
+name = "wasip2"
+version = "1.0.4+wasi-0.2.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b67efb37e106e55ce722a510d6b5f9c17f083e5fc79afc2badeb12cc313d9487"
+dependencies = [
+ "wit-bindgen",
+]
+
+[[package]]
+name = "windows-link"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f0805222e57f7521d6a62e36fa9163bc891acd422f971defe97d64e70d0a4fe5"
+
+[[package]]
+name = "wit-bindgen"
+version = "0.57.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1ebf944e87a7c253233ad6766e082e3cd714b5d03812acc24c318f549614536e"
+
+[[package]]
+name = "zerocopy"
+version = "0.8.54"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b7cbbc0a705a0fd05cc3676525980d2bf5a9bc4adac6d6475209a7887cf59d19"
+dependencies = [
+ "zerocopy-derive",
+]
+
+[[package]]
+name = "zerocopy-derive"
+version = "0.8.54"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e2e817b7b52d0c7358d3246da9d69935ebb18116b2b102b4230dac079b4862f5"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]

data/Cargo.toml

@@ -0,0 +1,27 @@
+# This Cargo.toml is here to let externals tools (IDEs, etc.) know that this is
+# a Rust project. Your extensions dependencies should be added to the Cargo.toml
+# in the ext/ directory.
+
+[workspace]
+members = ["./ext/nosj"]
+resolver = "2"
+
+[profile.release]
+opt-level = 3
+lto = "fat"
+codegen-units = 1
+# Ship lean artifacts: leftover debug sections (e.g. from the
+# precompiled std) are stripped. The symbol table stays, so crash
+# backtraces keep function names.
+strip = "debuginfo"
+# No landing pads: a Ruby extension must never unwind across the C
+# boundary anyway, and magnus's per-pair hash-iteration panic guard
+# (std::panic::catch_unwind) compiles to a plain call under abort.
+# Measured ~4ns per object pair on Zen 4 with unwinding enabled.
+panic = "abort"
+
+[profile.profiling]
+inherits = "release"
+debug = true
+opt-level = 3
+lto = "fat"

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Yaroslav Markin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/NOTICE

@@ -0,0 +1,13 @@
+nosj (Ruby gem)
+
+Copyright (c) 2026 Yaroslav Markin. Released under the MIT License
+(see LICENSE.txt).
+
+Every distribution of this gem embeds the nosj Rust crate
+(https://github.com/yaroslav/nosj), compiled into the native
+extension: precompiled platform gems ship the compiled binary, and the
+source gem compiles the crate at install time. The crate is licensed
+MIT AND BSL-1.0 AND Apache-2.0; its NOTICE file itemizes the derived
+components (the fpconv/Grisu2 float formatter under BSL-1.0; the
+fast_float decimal conversion and simdjson structural-indexing
+techniques under Apache-2.0) and reproduces each component license.

data/README.md

@@ -0,0 +1,214 @@
+# gem nosj
+
+**gem nosj** is an **very fast JSON parser and generator for Ruby**, written in Rust on the first-party [nosj](https://github.com/yaroslav/nosj) crate and **SIMD-accelerated** on every platform (NEON on Apple Silicon, SSE2/AVX2 on x86-64).
+
+> gem nosj is the powerful evil twin of the json gem.
+
+[![GitHub Release](https://img.shields.io/github/v/release/yaroslav/nosj-ruby)](https://github.com/yaroslav/nosj-ruby/releases)
+[![Docs](https://img.shields.io/badge/yard-docs-blue.svg)](https://rubydoc.info/gems/nosj)
+
+- It is **faster** than gem json and every
+third-party parser, including Oj, RapidJSON, FastJsonparser, Yajl. 1.0–1.8× faster than the bundled json gem, 1.3–11× faster than Oj, and up to 17×
+faster than Yajl—[see Benchmarks](#benchmarks).
+- It comes **precompiled** (platform gems built with per-platform optimizations,
+nothing to compile on install).
+- It has a **partial parsing mode**: JSON Pointer lookups that pull single values out of big documents in microseconds, skipping everything else.
+- Same API and option names as gem json.
+
+**And there's more**: validate documents without building a single Ruby object, resolve whole batches of paths in one pass, and accelerate an entire application with a one-line drop-in.
+
+- [Requirements](#requirements)
+- [Getting started](#getting-started)
+- [What's in the box](#whats-in-the-box)
+- [Benchmarks](#benchmarks)
+- [Switching from the json gem](#switching-from-the-json-gem)
+- [How it works](#how-it-works)
+- [Development](#development)
+- [License](#license)
+
+## Requirements
+
+- **Ruby 3.3 or newer** (CRuby; tested on 3.3, 3.4, and 4.0).
+- **Linux** (x86-64 and arm64, glibc and musl), **macOS** (Apple
+  Silicon), or **Windows** (x64): these platforms install precompiled,
+  per-platform-optimized gems with nothing to build.
+
+## Getting started
+
+```bash
+bundle add nosj
+```
+
+```ruby
+require "nosj"
+
+NOSJ.parse('{"a":[1,true]}')       #=> {"a" => [1, true]}
+NOSJ.generate({"a" => [1, true]})  #=> '{"a":[1,true]}'
+```
+
+That's it—if you know the `json` gem, you already know `nosj`.
+
+Want the speedup without touching your code? One line reroutes
+`JSON.parse`, `JSON.generate`, `JSON.pretty_generate`, and `JSON.dump`
+through nosj:
+
+```ruby
+require "nosj/json"
+```
+
+In a Bundler app (Rails included) that can live entirely in the
+Gemfile you can do this:
+
+```ruby
+gem "nosj", require: "nosj/json"
+```
+
+Options nosj supports take the fast path; anything exotic
+(`create_additions`, `object_class`, `JSON::State`, procs, IO
+arguments) falls back to the original implementation, so `JSON.load`,
+`JSON.parse!`, and `JSON.load_file` keep their exact behavior.
+Exceptions re-raise as the JSON classes, so your rescue clauses keep
+working. Measured through the patch: parse 1.11×, generate 1.05× over
+the original gem. (A MultiJson adapter ships too:
+`require "nosj/multi_json"`, then `MultiJson.use NOSJ::MultiJsonAdapter`.)
+
+## What's in the box
+
+**The `json` gem API**, on the `NOSJ` module:
+
+```ruby
+NOSJ.parse(src, symbolize_names: true)   # also: freeze, max_nesting,
+                                         # allow_nan, allow_trailing_comma
+NOSJ.generate(obj)                       # indent, space, object_nl, ...,
+NOSJ.pretty_generate(obj)                # ascii_only, script_safe, strict
+```
+
+**Validation without parsing.** `NOSJ.valid?` runs the full
+parser—tokenizers, string decode, number validation—into a null sink
+and allocates no Ruby objects at all. It is 2-4× faster than
+`NOSJ.parse`, which already leads every parser above:
+
+```ruby
+NOSJ.valid?('{"a":1}')                #=> true
+NOSJ.valid?('{"a":}')                 #=> false
+NOSJ.valid?(src, max_nesting: false)  # same options as parse
+```
+
+**Partial parsing.** Pull values out of a document without
+materializing the rest—skipped content is stepped over at SIMD block
+speed, so a lookup costs what it skips, not what the document weighs:
+
+```ruby
+NOSJ.dig(json, "users", 3, "name")        # Hash#dig-shaped
+NOSJ.at_pointer(json, "/users/3/name")    # JSON Pointer
+
+# Many lookups in one pass. A batch costs about as much as its
+# single deepest member:
+NOSJ.at_pointers(json, ["/users/3/name", "/meta/count"])
+NOSJ.dig_many(json, [["users", 3, "name"], ["meta", "count"]])
+```
+
+Example: an early field resolves in ~0.35µs where `JSON.parse(json).dig(...)`
+costs ~980µs on the same document—three orders of magnitude. A field
+at the far end of a 570 KB document costs ~71µs, still 13× faster
+than parse-then-dig. Misses return nil; matched subtrees materialize
+with the same options as `parse` (`symbolize_names:`, `freeze:`).
+
+## Benchmarks
+
+Every installed JSON gem, benchmark-ips: AWS EC2 c7a.2xlarge (AMD EPYC 9R14, Zen 4), Ruby 4.0.6 + YJIT, json 2.21.1, Oj 3.17.4, RapidJSON 0.4.0, FastJsonparser 0.6.0, Yajl 1.4.3, PGO build, 2026-07-16. `×N` = times slower than nosj. 
+
+Parse:
+
+| file | nosj (i/s) | json | Oj | FastJsonparser | RapidJSON | Yajl |
+|---|---:|---:|---:|---:|---:|---:|
+| activitypub | **12.4k** | ×1.18 | ×1.53 | ×1.89 | ×1.99 | ×4.57 |
+| canada | **248** | ×1.10 | ×8.28 | ×1.45 | ×1.51 | ×4.96 |
+| citm_catalog | **504** | ×1.03 | ×1.97 | ×2.07 | ×1.83 | ×4.93 |
+| gsoc-2018 | **397** | ×1.30 | ×1.47 | ×1.81 | ×1.80 | ×4.78 |
+| homebrew-formula | **15.2** | ×1.13 | ×1.54 | ×2.42 | ×2.02 | ×4.30 |
+| homebrew-llvm | **49.3k** | ×1.60 | ×1.48 | ×1.50 | ×1.85 | ×5.11 |
+| mesh | **1.1k** | ×1.30 | ×3.93 | ×1.82 | ×1.95 | ×6.96 |
+| numbers | **5.9k** | ×1.19 | ×4.64 | ×1.43 | ×1.75 | ×7.04 |
+| ohai | **14.4k** | ×1.47 | ×1.61 | ×2.11 | ×1.97 | ×4.71 |
+| simple | **977k** | ×1.31 | ×1.77 | ×2.08 | ×1.63 | ×5.15 |
+| small_mixed | **3.2M** | ×1.48 | ×2.85 | ×2.44 | ×1.82 | ×6.75 |
+| tolstoy | **8.9k** | ×1.79 | ×1.96 | ×2.29 | ×2.10 | ×17.31 |
+| twitter | **1.1k** | ×1.09 | ×1.83 | ×2.25 | ×2.61 | ×5.40 |
+
+Generate:
+
+| file | nosj (i/s) | json | Oj | RapidJSON | Yajl |
+|---|---:|---:|---:|---:|---:|
+| activitypub | **34.8k** | ×1.20 | ×1.78 | ×2.41 | ×5.84 |
+| canada | **150** | ×0.98\* | ×10.98 | ×11.20 | ×10.87 |
+| citm_catalog | **1.3k** | ×1.04 | ×1.44 | ×1.55 | ×2.85 |
+| gsoc-2018 | **1.1k** | ×1.28 | ×2.64 | ×3.64 | ×11.00 |
+| homebrew-formula | **20.9** | ×1.07 | ×1.25 | ×1.62 | ×3.03 |
+| homebrew-llvm | **71.5k** | ×1.23 | ×2.22 | ×3.04 | ×5.80 |
+| mesh | **613** | ×1.08 | ×9.24 | ×9.40 | ×9.26 |
+| numbers | **2.1k** | ×1.03 | ×10.63 | ×11.00 | ×10.69 |
+| ohai | **39.4k** | ×1.07 | ×1.29 | ×1.50 | ×3.37 |
+| simple | **2.2M** | ×1.03 | ×1.58 | ×1.62 | ×4.36 |
+| small_mixed | **5.6M** | ×1.09 | ×2.26 | ×1.83 | ×7.16 |
+| tolstoy | **8.3k** | ×1.30 | ×4.15 | ×6.50 | ×14.54 |
+| twitter | **2.9k** | ×1.09 | ×1.46 | ×2.01 | ×4.05 |
+
+\* canada-generate is a statistical tie with the json gem (within
+measurement error).
+
+Reproduce with `rake bench` (the parity-gated comparison, after a PGO retrain—the shipping configuration) or `rake bench:ips` (the multi-gem shoot-out).
+
+## Switching from the json gem
+
+You mostly don't have to do anything. Some differences:
+
+- The legacy object-deserialization options (`create_additions`,
+  `object_class`, `array_class`, `decimal_class`) raise ArgumentError;
+  the `nosj/json` drop-in falls back to the original gem for them.
+- Behaviors the `json` gem itself deprecates (JS comments, raw invalid
+  UTF-8) follow the strict semantics instead.
+- Unlike `Array#dig`, negative indices in `NOSJ.dig` return nil (JSON
+  Pointer has no equivalent).
+- Parse error *messages* use byte offsets rather than the gem's
+  phrasing (classes match).
+
+Everything else—including the gem's exact float formatting, which is
+not the shortest-round-trip form most libraries emit—matches
+byte-for-byte and is verified continuously against the full corpus.
+
+## How it works
+
+Most fast parsers build their own tree first and convert it into Ruby
+objects second, paying for every string and container twice. nosj is
+built on the [nosj](https://github.com/yaroslav/nosj) Rust crate, an
+event parser with no tree of its own:
+
+- **No intermediate tree.** The crate parses with NEON/SSE2/AVX2 SIMD
+  kernels and emits *events*; the extension builds interned hash keys,
+  strings, and containers directly on Ruby's heap during the parse,
+  with GC-safe value stacks and epoch-evicted key caches. Generation
+  walks Ruby objects once, streaming through fused scan-and-store
+  escape kernels.
+- **Byte-exact floats.** Output reproduces the json gem's fpconv
+  (Grisu2) float format digit for digit—round-tripping is verified,
+  not assumed.
+- **PGO everywhere.** Local builds, CI, and every precompiled platform
+  gem train on the benchmark corpus before the shipping compile; the
+  precompiled binaries use portable codegen with SIMD tiers detected at
+  runtime.
+
+## Development
+
+```bash
+bundle exec rake compile                # build the extension (applies a PGO profile if present)
+bundle exec rake spec                   # the gem-parity suite
+bundle exec rake bench                  # PGO retrain + the parity-gated sweep vs the json gem
+bundle exec rake bench:fast             # the sweep without retraining
+bundle exec rake "bench:ips[twitter]"   # multi-gem shoot-out (benchmark-ips); no args = full corpus
+```
+
+## License
+
+MIT. The underlying Rust crate is `MIT AND BSL-1.0 AND Apache-2.0`; its
+NOTICE file itemizes the derived components.