jmespath-ruby 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cf530e6a526f4e83cc7fd29f7f527fedf0b28add8d0e57b362db7ac96b379cb7
-  data.tar.gz: 29b4682722f6371663cd0c84f29119db2c1fd89943ad60db395aead75adc2456
+  metadata.gz: f9f2db0a8d51af9e3258964210daf3aa1391f97370fca0d0e5610045aad9e012
+  data.tar.gz: ec560bc1d5607e14175267d6b1bb82329a3d126686d99393c2cd6a8e7bc62585
 SHA512:
-  metadata.gz: 40f6a36ceb35cb72fe6dd62651f51ae41a8b79f204f71b6941c754f93ac5a2dd18e08ef9f2ee98791073bae4493b636ebd79ef8196541cccd3b92853310faa22
-  data.tar.gz: 8a4e7dfa8ea63e0e6c5e073f7e893a34d76de3267a6300ba5e60cd27d51cc9566be26985dd7e56b51bf31b7b5160bd2e41e634c9f8358483e358631a43357424
+  metadata.gz: b8b8a4b5d663ae5b6ac54d093867c94ea420d836d44f1de5de1b781c21a984277a8211f7a6343392b335d0e451b7f3f749802e0ad910fc0af45d573fb305d2b9
+  data.tar.gz: 985c5eddf2e47265eaa74f37afd4ea73094ae84f6a87ec90ec0c0501be1af03b3c46a4d95207be57d42ec47f4b94dc2b632a1e87b5eabfa712e3ba4232753794

data/CHANGELOG.md

@@ -1,9 +1,37 @@
 # Changelog
 
-## 0.1.0 - 2026-11-01
+All notable changes are recorded here using [Keep a Changelog 2.0.0](https://keepachangelog.com/en/2.0.0/).
+Versions follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html) for the public contract defined in [VERSIONING.md](VERSIONING.md).
+
+## [Unreleased]
+
+## [0.1.2] - 2026-11-02
+
+### Added
+
+- Add `JMESPath::Diagnostic.format` for syntax reasons, source coordinates, query excerpts, and carets.
+- Expose immutable function validation data, including argument positions, expected and actual types, arity, and query byte ranges.
+- Add `Functions#names`, `Functions#metadata`, and optional custom function descriptions for immutable registry inspection.
+- Suggest similar names from the active registry for unknown functions; expose the missing name and ranked suggestions on the error.
+
+### Changed
+
+- Show located CLI syntax, function type, and arity diagnostics; describe validation and suggestions in CLI help.
+- Report malformed CLI input as `Invalid JSON input` without exposing JSON parser messages or document fragments.
+
+## [0.1.1] - 2026-11-01
+
+### Changed
+
+- Expand installation, support, contribution, and performance comparison documentation.
+- Publish gems with build provenance, a dependency inventory, and attested release assets.
+
+## [0.1.0] - 2026-11-01
 
 Initial implementation for Ruby 3.3 and later.
 
+### Added
+
 - Implement the JMESPath language and all 26 standard functions.
 - Preserve the public `require "jmespath"` and `JMESPath.search` entry points under the `jmespath-ruby` package name.
 - Add immutable compiled expressions, bounded synchronized caching, and immutable custom function registries.
@@ -16,3 +44,8 @@ Initial implementation for Ruby 3.3 and later.
 
 The compatibility guide documents intentional corrections and limits.
 Applications that depend on the gem name `jmespath` must change that dependency explicitly.
+
+[unreleased]: https://github.com/svyatov/jmespath-ruby/compare/v0.1.2...HEAD
+[0.1.2]: https://github.com/svyatov/jmespath-ruby/compare/v0.1.1...v0.1.2
+[0.1.1]: https://github.com/svyatov/jmespath-ruby/compare/v0.1.0...v0.1.1
+[0.1.0]: https://github.com/svyatov/jmespath-ruby/releases/tag/v0.1.0

data/CONTRIBUTING.md

@@ -3,6 +3,25 @@
 Use Ruby 3.3 or later.
 Install the locked development bundle with `bundle install`.
 
+Outside contributions are welcome. This guide is the project's contribution standard.
+
+## Submit a change
+
+Fork the repository and create a branch from `main`.
+Use a branch name such as `fix/query-validation` and Conventional Commits for commit messages.
+Keep each pull request focused on one change.
+Open a pull request against `main` describing the problem, the change, and any public API consequences.
+
+New functionality must include tests. Bug fixes must include a regression test that fails before the fix.
+Follow the checks, fixture rules, and documentation requirements in this guide.
+Follow [VERSIONING.md](VERSIONING.md) when changing the public contract.
+Participants must follow the [code of conduct](CODE_OF_CONDUCT.md).
+
+## Decisions and continuity
+
+Leonid Svyatov is the sole maintainer and decides which changes to accept, merge, and release.
+No successor is arranged if he stops maintaining the project.
+
 ## Checks
 
 ```sh
@@ -16,6 +35,8 @@ Coverage requires 100% lines and branches.
 Every measurable library method must score at most 10 in coverage-aware CRAP analysis.
 A missing coverage report fails the check.
 Unmeasurable methods are reported for review.
+CI reports existing dependency advisories without blocking unrelated changes.
+Dependency review blocks pull requests that introduce known vulnerabilities.
 
 Run `bundle exec rspec spec/unit/parser_spec.rb` for a focused test cycle.
 Focused RSpec runs collect coverage without enforcing full-suite thresholds.
@@ -47,11 +68,13 @@ Publishing and remote repository operations require separate authorization.
 Update `lib/jmespath/version.rb` and `CHANGELOG.md` together.
 Run `bundle exec rake release:check` before creating a release tag.
 Push a `vVERSION` tag that exactly matches `JMESPath::VERSION`.
-The release workflow runs the full quality matrix, verifies the tag, archives the built gem, and publishes through RubyGems trusted publishing.
+The release workflow runs the quality matrix and builds the gem, dependency inventory, checksums, and changelog-derived release notes.
+It verifies the tag before publication and publishes the exact archived gem through RubyGems trusted publishing after manual approval.
+It uploads provenance to RubyGems and attaches the attested gem, inventory, and checksums to the GitHub release.
 
 The trusted publisher is restricted to `svyatov/jmespath-ruby`, workflow `release.yml`, and GitHub environment `release`.
 The environment accepts release tags matching `v*`.
 The token exchange declares the account's immutable RubyGems owner ID, `71752`, which is required for the first publication.
 No long-lived RubyGems API key is required.
-After publication, create the GitHub release from the archived gem and its matching changelog entry.
-If only GitHub release creation fails, reuse that artifact; do not republish the gem.
+Use manual workflow dispatch on a branch to verify and build without publishing.
+If only GitHub release creation fails, rerun the failed job to reuse the archived artifact; do not republish the gem.

data/README.md

@@ -1,43 +1,101 @@
 # jmespath-ruby
 
-A pure Ruby implementation of JMESPath for Ruby 3.3 and later.
+Search JSON and Ruby data with reusable queries and typed custom functions.
 
-Search JSON-compatible values, compile expressions for reuse, and register typed custom functions.
-The package keeps `require "jmespath"` and `JMESPath.search` while using the gem name `jmespath-ruby`.
+- Runs on Ruby 3.3 and later with a pure Ruby implementation.
+- Replaces [jmespath.rb](https://github.com/jmespath/jmespath.rb)'s documented `JMESPath.search` API; see the [migration limits](#replace-jmespathrb).
+- Reuses compiled queries and supports typed custom functions.
+- Measured 7.97x geometric-mean public-search speedup over jmespath 1.6.2 on MRI 4.0.9; see the [benchmark results](docs/guides/comparison.md).
 
 ## Install
 
-Add the gem to your Gemfile:
+In your Ruby project, add the gem with Bundler. Run `bundle init` first if the project has no Gemfile.
 
-```ruby
-gem "jmespath-ruby", "~> 0.1.0"
+```sh
+bundle add jmespath-ruby --version "~> 0.1.2"
 ```
 
-Or install it directly:
+Save this Ruby example as `example.rb`:
 
-```sh
-gem install jmespath-ruby
+```ruby
+require "jmespath"
+
+data = {user: {name: "Ada"}}
+JMESPath.search("user.name", data) #=> "Ada"
 ```
 
-### Install from this checkout
+Run it with `bundle exec ruby example.rb`. The final expression returns `"Ada"`.
 
-```sh
-bundle install
-bundle exec rake build
-gem install ./pkg/jmespath-ruby-0.1.0.gem
+## Performance
+
+**Fastest public search in every matching MRI benchmark case.**
+On MRI 4.0.9, jmespath-ruby beats each competing implementation on every workload that both return correctly.
+
+| Implementation | Version | Correct workloads | jmespath-ruby public-search speedup |
+| --- | --- | ---: | ---: |
+| **jmespath-ruby** | **0.1.0** | **18/18** | **Baseline** |
+| jmespath (jmespath.rb) | 1.6.2 | 18/18 | **7.97x** |
+| BurtPath | 1.1.2 | 15/18 | **9.99x** |
+| Jamespath | 0.5.1 | 13/18 | **8.07x** |
+
+Speedups use geometric means of median times across each competitor's correctly evaluated workloads.
+Measurements use five rounds of 20,000 searches on an Apple M1 Pro.
+The suite includes all 12 upstream benchmark cases and six supplemental cases.
+Results vary by workload: **1.35x to 78.48x faster than jmespath 1.6.2** in this run.
+
+Query reuse has different results: BurtPath's private cached runtime is faster in five workloads, and Jamespath has three lower medians.
+The [full comparison](docs/guides/comparison.md) includes those results, JRuby, failures, methodology, and raw samples.
+The JRuby-only `jmespath-jruby` 1.0.0.pre0 fails on the tested JRuby 10.1 runtime; its results are recorded separately.
+
+## Why choose jmespath-ruby?
+
+- **Reuse work across searches.** Compile once, save query options, and share immutable expressions across threads.
+- **Add functions without global patches.** Typed, immutable registries validate arguments before your callback runs.
+- **Type-check integrations.** The gem ships RBS signatures for its public API.
+- **Use Ruby data directly.** Search string-keyed or symbol-keyed hashes, Structs, arrays, JSON streams, and Pathname inputs.
+- **Control query growth.** The synchronized cache holds at most 32 queries and 1 MiB of source text; expression nesting has an explicit limit.
+
+Both Ruby and Python upstream compliance corpora run in the test suite, alongside Ruby-specific input and error checks.
+The [comparison with existing implementations](docs/guides/comparison.md) includes exact versions, rejected workloads, and reproducible measurements.
+
+| Feature | jmespath-ruby | jmespath | BurtPath | Jamespath | jmespath-jruby |
+| --- | --- | --- | --- | --- | --- |
+| Public query compilation | Yes | No | No | Yes | Yes |
+| Documented typed function registry | Yes | No | No | No | No |
+| Packaged RBS signatures | Yes | No | No | No | No |
+| Pure Ruby implementation | Yes | Yes | Yes | Yes | No |
+| Ordinary `JMESPath.search` calls | Yes | Yes | Yes | No | No |
+
+`jmespath` and BurtPath support reuse through private runtime classes.
+The [full comparison](docs/guides/comparison.md) distinguishes those classes from public compilation APIs.
+
+## Replace jmespath.rb
+
+The official jmespath.rb project publishes the gem named `jmespath`.
+Replace that Gemfile entry:
+
+```diff
+-gem "jmespath"
++gem "jmespath-ruby", "~> 0.1.2"
 ```
 
-For a local Bundler application:
+Run `bundle install`. Your Ruby code keeps the same entry points:
 
 ```ruby
-gem "jmespath-ruby", path: "/path/to/jmespath-ruby"
+require "jmespath"
+JMESPath.search("user.name", {user: {name: "Ada"}}) #=> "Ada"
 ```
 
 Use one provider per bundle.
-A dependency on the package named `jmespath` needs its own dependency change; this gem cannot satisfy that name automatically.
+A third-party dependency that requires the package named `jmespath` needs a dependency change; Bundler cannot substitute `jmespath-ruby` automatically.
+Private parser/runtime classes and exact error messages are outside the replacement contract.
+Validation is stricter for invalid function arguments, and empty `min_by`/`max_by` results return nil.
+See [compatibility and deliberate corrections](docs/guides/compatibility.md) before migrating.
 
 ## Search
 
+Use `JMESPath.search` in Ruby code to evaluate a query:
+
 ```ruby
 require "jmespath"
 
@@ -53,6 +111,8 @@ The library preserves selected input objects and does not mutate the input.
 
 ## Compile once
 
+Use `JMESPath.compile` in Ruby code to reuse a parsed expression:
+
 ```ruby
 expression = JMESPath.compile("user.name")
 expression.search({user: {name: "Ada"}}) #=> "Ada"
@@ -63,7 +123,7 @@ Compiled expressions are immutable and safe to share between threads.
 Each search uses separate evaluation state.
 Custom callbacks and input objects remain the caller's responsibility.
 
-Save evaluation options when compiling a query, then use `search` or its `call` alias:
+In Ruby code, save evaluation options when compiling a query, then use `search` or its `call` alias:
 
 ```ruby
 query = JMESPath.compile("length(name)", disable_visit_errors: true)
@@ -73,6 +133,8 @@ query.call({name: nil}) #=> nil
 
 ## Custom functions
 
+Create a function registry in Ruby code and pass it to `JMESPath.search`:
+
 ```ruby
 functions = JMESPath::Functions.default.with("double", signature: [[:number]]) { |number| number * 2 }
 JMESPath.search("double(price)", {price: 12}, functions: functions) #=> 24
@@ -82,6 +144,25 @@ Registration returns a separate immutable registry.
 An existing function requires `override: true` to replace it.
 Every argument, including variadic arguments, is validated before the callback runs.
 
+Inspect registered functions in Ruby without executing their callbacks:
+
+```ruby
+JMESPath::Functions.default.names.include?("length") #=> true
+metadata = JMESPath::Functions.default.metadata("length")
+metadata.signature #=> [[:string, :array, :object]]
+metadata.description #=> "Character or element count."
+```
+
+Use `description:` when registering a custom function to include its description in immutable metadata.
+See [registry inspection](docs/guides/functions.md#registry-inspection) for all fields and override behavior.
+
+## Errors and diagnostics
+
+Format syntax failures in Ruby with `JMESPath::Diagnostic.format(error)` to get source coordinates, a query excerpt, and a caret.
+Function type and arity errors expose immutable validation data, including the function name, signature, argument counts or types, and available source ranges.
+Unknown-function errors expose the missing name and up to three suggestions from the active registry.
+See [errors and diagnostics](docs/guides/errors.md) for examples, nullable fields, and source-location limits.
+
 ## Command line
 
 Both `jmespath` and `jmespath.rb` accept an expression and a JSON document on standard input.
@@ -91,7 +172,12 @@ printf '%s\n' '{"user":{"name":"Ada"}}' | jmespath 'user.name'
 ```
 
 The result goes to standard output as JSON.
-Errors go to standard error with a nonzero status.
+Syntax, function type, and arity failures include source coordinates, a query excerpt, and a caret when available.
+Unknown functions suggest similar registered names.
+Malformed JSON input reports `Invalid JSON input` without including document fragments.
+These failures go to standard error and exit with status 1.
+Usage failures exit with status 2; `--help` and `--version` exit with status 0 without reading input.
+See [CLI diagnostics](docs/guides/errors.md#cli-diagnostics) for examples and fallback behavior.
 
 ## Guides
 
@@ -101,7 +187,19 @@ Errors go to standard error with a nonzero status.
 - [Errors and limits](docs/guides/errors.md)
 - [Compatibility and migration](docs/guides/compatibility.md)
 - [Performance measurements](docs/guides/performance.md)
+- [Comparison with other implementations](docs/guides/comparison.md)
 - [Development](CONTRIBUTING.md)
+- [Changelog](CHANGELOG.md)
+
+## Help and maintenance
+
+This project is maintained by Leonid Svyatov.
+Use [GitHub issues](https://github.com/svyatov/jmespath-ruby/issues) for questions and defect reports.
+Report vulnerabilities through the private channel in [SECURITY.md](SECURITY.md).
+
+Release assets include the gem, `sbom.cdx.json`, and `SHA256SUMS`.
+Verify a downloaded asset with `gh attestation verify ASSET --repo svyatov/jmespath-ruby --signer-workflow svyatov/jmespath-ruby/.github/workflows/release.yml`.
+Check downloaded files against the manifest with `sha256sum -c SHA256SUMS`.
 
 ## Verify and document
 

data/SECURITY.md

@@ -11,6 +11,7 @@ Bound request sizes and runtime resources at the application boundary.
 Run `bundle exec rake audit` to refresh the dependency advisory database and check the lockfile.
 A failed database update fails the audit.
 
-Report security concerns through a private maintainer contact channel.
+Report vulnerabilities privately to [leonid@svyatov.com](mailto:leonid@svyatov.com).
+Leonid Svyatov will respond within 7 days.
+Include the affected version, a minimal reproduction, and the security impact.
 Do not post credentials or private application data in public reports.
-Private repository reporting must be configured before publication.

data/docs/guides/comparison.md

@@ -0,0 +1,189 @@
+# Ruby implementation comparison
+
+The comparison covers the latest published versions found on November 1, 2026.
+[RubyGems search](https://rubygems.org/api/v1/search.json?query=jmespath) and the upstream repositories identify these implementations:
+
+| Gem | Version | Upstream | API used |
+| --- | --- | --- | --- |
+| jmespath-ruby | 0.1.0 checkout | [svyatov/jmespath-ruby](https://github.com/svyatov/jmespath-ruby) | `JMESPath.search`, `JMESPath.compile` |
+| jmespath | 1.6.2 | [jmespath/jmespath.rb](https://github.com/jmespath/jmespath.rb) | `JMESPath.search`, persistent `JMESPath::Runtime` |
+| burtpath | 1.1.2 | [burtcorp/burtpath](https://github.com/burtcorp/burtpath) | `JMESPath.search`, persistent `JMESPath::Runtime` |
+| jamespath | 0.5.1 | [lsegal/jamespath](https://github.com/lsegal/jamespath) | `Jamespath.search`, `Jamespath.compile` |
+| jmespath-jruby | 1.0.0.pre0 | [burtcorp/jmespath-jruby](https://github.com/burtcorp/jmespath-jruby) | `JmesPath#compile`, compiled query reuse |
+
+The gem named `jmespath.rb` is an empty name-protection package, not the official implementation.
+The official implementation uses the gem name `jmespath`.
+`stack_master_json_parameter_store` consumes JMESPath rather than implementing it.
+The mruby project has no RubyGems release in this search and targets a different Ruby runtime.
+
+Package checksums and exclusions are recorded in the [source manifest](../../benchmark/results/comparison-sources.json).
+This project's library source is revision `609c178dfe3be49e13c64ae1b49790570c9fec37`; each report also fingerprints the measured library files.
+
+## MRI results
+
+The following results use MRI 4.0.9 without YJIT.
+Each speedup is the geometric mean of competitor time divided by this library's time, using only workloads both implementations evaluate correctly.
+Each workload's time is the median of its five samples before ratios are calculated.
+Each workload contributes equally to the mean.
+A value above 1 favors this library; a value below 1 favors the competitor.
+
+| Implementation | Correct search workloads | Public-search speedup | Search speedup range | Reuse speedup |
+| --- | ---: | ---: | ---: | ---: |
+| **jmespath-ruby 0.1.0** | **✅ 18/18** | **1.00x** | **Baseline** | **1.00x** |
+| jmespath 1.6.2 | ✅ 18/18 | 7.97x | 1.35x to 78.48x | 4.35x |
+| BurtPath 1.1.2 | ❌ 15/18 | 9.99x | 1.74x to 80.59x | 1.04x |
+| Jamespath 0.5.1 | ❌ 13/18 | 8.07x | 2.74x to 26.91x | 1.38x |
+
+Public search is faster in every mutually passing workload.
+Reuse is not uniformly faster: BurtPath has lower medians in five of 15 shared workloads; Jamespath has lower medians in three of 13.
+The 1.04x aggregate against BurtPath represents near parity, not a decisive reuse advantage.
+No statistical significance claim is made for close medians.
+
+BurtPath's faster reuse cases are `single_expression`, `deep_nesting_50_index`, `multi_wildcard_field`, `wildcard_with_field_match`, and `wildcard_with_field_match2`.
+Jamespath's lower reuse medians occur in `single_dot_expression`, `double_dot_expression`, and `dot_no_match`.
+
+Raw results: [all MRI providers](../../benchmark/results/comparison-mri-4.0.9.json) and [Jamespath follow-up](../../benchmark/results/comparison-jamespath-mri-4.0.9.json).
+The follow-up removes a per-call adapter conditional; its Jamespath measurements supply the tables above.
+The original full run remains available, including every failed case and sample.
+
+## JRuby results
+
+These measurements use JRuby 10.1.0.0 and Temurin Java 21.0.11.
+They use the same median and geometric-mean calculation as the MRI table, with separate timing samples.
+
+| Implementation | Correct public-search workloads | Correct reuse workloads | Public-search speedup | Reuse speedup |
+| --- | ---: | ---: | ---: | ---: |
+| **jmespath-ruby 0.1.0** | **✅ 18/18** | **✅ 18/18** | **1.00x** | **1.00x** |
+| jmespath 1.6.2 | ✅ 18/18 | ✅ 18/18 | 7.80x | 5.24x |
+| BurtPath 1.1.2 | ❌ 15/18 | ❌ 16/18 | 10.45x | 0.88x |
+| Jamespath 0.5.1 | ❌ 13/18 | ❌ 13/18 | 10.23x | 0.97x |
+| jmespath-jruby 1.0.0.pre0 | ❌ 0/18 | ❌ 0/18 | Unavailable | Unavailable |
+
+Public search has lower median times in every mutually passing workload.
+The range against `jmespath` is 1.42x to 87.88x.
+Reuse favors BurtPath in 12 of 16 shared workloads, Jamespath in six of 13, and `jmespath` in three of 18.
+This library therefore does not have a universal query-reuse advantage on JRuby.
+
+BurtPath's filter fails during public search but passes during reuse in this execution sequence.
+Its other rejected workloads are the stepped slice and Unicode function.
+The Java-backed implementation fails before timing because its JAR calls a removed JRuby runtime method.
+See the [complete JRuby samples](../../benchmark/results/comparison-jruby-10.1.0.0.json), including all errors.
+
+## Beyond speed
+
+| Capability | jmespath-ruby | jmespath | BurtPath | Jamespath | jmespath-jruby |
+| --- | --- | --- | --- | --- | --- |
+| Public query compilation | ✅ `compile` | ❌ Private `Runtime` | ❌ Private `Runtime` | ✅ `compile` | ✅ `compile` |
+| Documented typed function registry | ✅ `Functions#with` | ❌ | ❌ | ❌ | ❌ |
+| Packaged RBS signatures | ✅ | ❌ | ❌ | ❌ | ❌ |
+| Pure Ruby implementation | ✅ | ✅ | ✅ | ✅ | ❌ Java extension |
+| Ordinary `JMESPath.search` calls | ✅ | ✅ Original API | ✅ | ❌ Different module | ❌ Instance API |
+
+This library's compiled expressions and function registries are immutable.
+Save options at compilation, reuse queries across threads, and extend one registry without changing other callers.
+Callback arguments are validated, including variadic arguments; callback errors retain their original exception and backtrace.
+These guarantees are described in the [compilation](compilation.md) and [function](functions.md) guides.
+
+Ruby input compatibility, named errors, and the positional options hash make migration from jmespath.rb practical.
+The [compatibility guide](compatibility.md) lists the limits: package dependencies need updating, private internals differ, and several invalid-input behaviors are corrected.
+
+## Method
+
+All providers receive the same JSON-compatible input and independently recorded expected output.
+The suite contains all 12 upstream benchmark cases and six supplemental cases: field lookup, projection, filter, sorting, slicing, and Unicode.
+Each operation must return the expected result before warmup, after warmup, and after timing.
+Rejected syntax, exceptions, and incorrect results appear as failures with no timing.
+
+Two modes measure distinct application patterns:
+
+- **Public search:** call the documented search API for each document. The Java-backed provider compiles on each call because it exposes no equivalent module method.
+- **Reuse:** compile once or retain the provider's runtime, then query repeatedly. Parsing and setup are outside the measured loop.
+
+The retained `JMESPath::Runtime` classes in `jmespath` and BurtPath are marked `@api private`.
+They provide a stronger cached baseline but are not public compilation APIs.
+This library, Jamespath, and the Java-backed implementation expose compilation APIs directly.
+
+Measurements run on an Apple M1 Pro with arm64 macOS.
+Each round starts a separate process for each provider.
+Provider order and workload order rotate between rounds.
+Providers run sequentially, using the same interpreter within each report, default garbage collection, and pre-parsed input.
+JSON parsing, process startup, and query construction for reuse are excluded.
+Results describe these workloads and runtime configurations; they do not measure application throughput or cold startup.
+
+MRI uses 2,000 warmup calls and 20,000 measured calls in each of five rounds, with YJIT disabled.
+JRuby uses 10,000 warmup calls and 10,000 measured calls in each of five rounds, with Temurin Java 21.0.11.
+Its results are separate because its JVM and JIT differ from MRI.
+JRuby does not provide MRI's allocated-object counter; allocation fields are null there.
+These runs do not measure peak RAM.
+
+Published gem contents are loaded directly with `-I`, without Bundler dependency activation.
+This allows a source comparison on the same interpreter and JSON library.
+It does not verify that each published package can be installed in a current application bundle.
+In particular, BurtPath declares `json ~> 1.8`; the MRI source comparison uses JSON 3.1.0.
+
+## Compatibility findings
+
+Both this library and `jmespath` produce the expected results for all 18 workloads on the tested interpreters.
+BurtPath fails the filter, stepped slice, and Unicode workloads on MRI.
+Its filter raises a missing-constant error, the slice returns nil, and `reverse` is unknown.
+Jamespath rejects the filter, sorting, stepped slice, Unicode function, and pipe workloads.
+Its 13 remaining workloads return the expected results.
+
+The Java-backed gem cannot evaluate these workloads on JRuby 10.1.0.0.
+Its bundled JAR calls the removed `org.jruby.RubyObject.getNativeTypeIndex()` method.
+The runner loads `jruby` before the extension to initialize its bridge; the binary incompatibility remains.
+This is a failure on the tested current runtime, not a claim about historical JRuby releases.
+
+## Reproduce
+
+Fetch the release artifacts in a scratch directory, then unpack their sources:
+
+```sh
+gem fetch jmespath --version 1.6.2
+gem unpack jmespath-1.6.2.gem
+gem fetch burtpath --version 1.1.2
+gem unpack burtpath-1.1.2.gem
+gem fetch jamespath --version 0.5.1
+gem unpack jamespath-0.5.1.gem
+gem fetch jmespath-jruby --version 1.0.0.pre0 --platform java
+gem unpack jmespath-jruby-1.0.0.pre0-java.gem
+```
+
+This does not install their declared dependencies.
+Compare the downloaded files' SHA-256 digests with the source manifest.
+Keep source directories separate because several packages provide the same require path and constants.
+Create a JSON configuration with a root, provider adapter, and version for each implementation:
+
+```json
+{
+  "jmespath-ruby": {"root": "/path/to/this/checkout", "provider": "jmespath", "version": "0.1.0"},
+  "jmespath": {"root": "/path/to/jmespath-1.6.2", "provider": "jmespath", "version": "1.6.2"},
+  "burtpath": {"root": "/path/to/burtpath-1.1.2", "provider": "jmespath", "version": "1.1.2"},
+  "jamespath": {"root": "/path/to/jamespath-0.5.1", "provider": "jamespath", "version": "0.5.1"}
+}
+```
+
+Run the MRI comparison:
+
+```sh
+ruby script/compare.rb --config /path/to/providers.json --iterations 20000 --warmup 2000 --rounds 5 --output /tmp/comparison.json
+```
+
+For JRuby, add the Java-backed provider to the configuration:
+
+```json
+"jmespath-jruby": {"root": "/path/to/jmespath-jruby-1.0.0.pre0-java", "provider": "jmespath-jruby", "version": "1.0.0.pre0"}
+```
+
+Run the script with the JRuby executable and a compatible `JAVA_HOME`:
+
+```sh
+jruby script/compare.rb --config /path/to/providers.json --iterations 10000 --warmup 10000 --rounds 5 --output /tmp/comparison-jruby.json
+```
+
+Keep JRuby results in a separate output file.
+The runner rejects changes to library sources or workload files during measurement.
+The saved MRI and JRuby reports hash files in their runtime's glob traversal order, producing different fingerprints for identical sources.
+Review verified the file bytes match; the current runner explicitly sorts paths to make future fingerprints portable across runtimes.
+The source manifest records the harness revision needed to reproduce each historical fingerprint.
+For the earlier private-node, cache-churn, startup, and memory experiments, see [performance measurements](performance.md).