hyperuuid 0.6.0-aarch64-linux-musl

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: df842f35933b133dacb0fff7e972a74a6a6a7bc23268bcf9d59316e83e13b0c7
+  data.tar.gz: 4068551ff41f1f8f220703158c1347db49d27543cf086976af5a7302189019a1
+SHA512:
+  metadata.gz: 8f31b85bb00425be9a181ac9de8f5a2c68820d7b1b92457da7fe707a28d8e3c25ea9e6d6a3606c90965fbe0e6250d3b9e6e227f7544d2c080887b6de0a37dde2
+  data.tar.gz: a4b6958b623b7f81e8388243585900a40772f8922e282beac516920e3e5b6acf4a56b92571c0e3cb6205dfcde3920e5c140c5faee02a7d29448d1c3a6f4250fb

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Skunk Werkx
+
+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/README.md

@@ -0,0 +1,375 @@
+# hyperuuid
+
+[![CI](https://github.com/SkunkWerkx/HyperUuid/actions/workflows/ci.yml/badge.svg)](https://github.com/SkunkWerkx/HyperUuid/actions/workflows/ci.yml)
+[![RubyGems](https://img.shields.io/gem/v/hyperuuid.svg)](https://rubygems.org/gems/hyperuuid)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/SkunkWerkx/HyperUuid/blob/master/LICENSE)
+
+**Ruby's own stdlib stops at `SecureRandom.uuid` — random v4, full stop. No v5, no v6, no v7. This gem is the whole RFC, with zero gem dependency beyond `Fiddle` (which ships with every Ruby install) — and it's faster than `SecureRandom.uuid` too.**
+
+RFC 9562 UUID v4 (random), v5 (deterministic), v6 and v7 (time-sortable) generation, with
+two backends sharing one public surface. Ruby 3.3 is the floor. The fast path is a native
+extension built with [Magnus](https://github.com/matsadler/magnus) — the Rust core linked
+directly into the Ruby VM, auto-selected when loadable — which redefines the low-level
+`Runtime` methods in place on require; everything above them (`Uuid`, the module doors and
+their argument checks, batch slicing) is shared byte-for-byte between backends. The
+last-resort fallback, in the universal gem only, calls the native `libhyperuuid` shared
+library via [`Fiddle`](https://docs.ruby-lang.org/en/master/Fiddle.html) — dlopen/dlsym plus
+a raw C-ABI call, no runtime bridge. `HyperUuid::BACKEND` reports which one is live;
+`HYPERUUID_PURE=1` forces Fiddle for testing — see [Backends](#backends).
+
+```ruby
+require "hyperuuid"
+
+id = HyperUuid.new_v4
+id2 = HyperUuid.new_v5(HyperUuid::Namespaces::DNS, "example.com")
+id3 = HyperUuid.new_v6
+id4 = HyperUuid.new_v7
+
+id4.timestamp # recover the embedded UTC Time
+id4.timestamp(raise_on_mismatch: false) # nil instead of raising if id4 isn't v6/v7
+id4.to_sql_order # byte order SQL Server's uniqueidentifier needs to sort by creation order
+
+# One native call, one random-bytes fetch, one counter reservation for the whole batch:
+batch = HyperUuid.new_v7_batch(1000)
+```
+
+## The doors
+
+| Door | Returns | Takes |
+|---|---|---|
+| `new_v4` | `Uuid` | — |
+| `new_v5(namespace, name)` | `Uuid`, the same one for the same pair | a `Uuid` namespace (`Namespaces::DNS`/`URL`/`OID`/`X500`, or your own) and a `String` name — text is hashed as UTF-8, a binary String as its bytes, and it may be empty |
+| `new_v6(time = nil)` `new_v7(time = nil)` | `Uuid` | nothing (now), a `Time`, or an Integer of Unix-epoch milliseconds |
+| `new_v6_batch(count, time = nil)` `new_v7_batch(count, time = nil)` | `Array` of `Uuid` | a count, and the same time forms |
+| `new_v6_batch_bytes(count, time = nil)` `new_v7_batch_bytes(count, time = nil)` | one binary `String`, 16 bytes per UUID | as the batch doors — see [Bulk generation into bytes](#bulk-generation-into-bytes) |
+| `native_version` | the loaded core's `"major.minor.patch"` | — |
+| `available?` | `true`/`false`, never raising | — |
+
+Every generating door returns `HyperUuid::Uuid`, a minimal value object — this gem has no
+runtime dependency on the `uuid` gem:
+
+| On `Uuid` | |
+|---|---|
+| `Uuid.parse(text)` | the 8-4-4-4-12 hyphenated form `#to_s` produces, either case, and nothing else — an `ArgumentError` otherwise |
+| `Uuid.new(bytes)` | wraps 16 raw RFC 9562-ordered bytes |
+| `Uuid::NIL` `Uuid::MAX` | the RFC 9562 §5.9/§5.10 special values |
+| `#bytes` `#to_s` `#version` `#variant` | the frozen binary String, the hyphenated text, the version nibble, the variant bits |
+| `#timestamp(raise_on_mismatch: true)` | the UTC `Time` embedded in a version 6 or 7 UUID; `nil` instead of an `ArgumentError` for any other version when passed `false` |
+| `#to_sql_order` `#from_sql_order` | to and from the byte order SQL Server's `uniqueidentifier` sorts by |
+| `==` `eql?` `hash` `<=>` | value equality and byte-order comparison (`Comparable`) |
+
+`#to_sql_order`/`#from_sql_order` convert a version 6 or 7 UUID to and from the byte order SQL
+Server's `uniqueidentifier` needs on the wire to sort by creation order (`#to_sql_order`
+dispatches on the UUID's own version, matching `#timestamp`'s convention) — computed once in
+the native Rust core rather than reimplemented in Ruby, and verified there (and independently
+against the real `System.Data.SqlTypes.SqlGuid` comparator in the C# binding's test suite).
+Same-millisecond v6 UUIDs aren't guaranteed to sort correctly afterward — v6 has no counter,
+so `clock_seq`/`node` (not the timestamp) decide ties, the same pre-existing RFC 9562 v6
+limitation plain order already has. `#from_sql_order` figures out which version to invert by
+checking a byte position that's provably collision-free between the two (see the method's own
+doc comment).
+
+### Errors
+
+Two exceptions are this gem's own, and both carry the same message on every backend:
+
+- `HyperUuid::TimestampOutOfRangeError` — the time cannot be embedded: past version 7's
+  48-bit millisecond field, past version 6's 60-bit one, or negative (a `Time` before the Unix
+  epoch included).
+- `HyperUuid::RandomSourceError` — the operating system's random source failed.
+
+Through 0.3.0 these were reachable only as `HyperUuid::Runtime::TimestampOutOfRangeError` and
+`HyperUuid::Runtime::RandomSourceError`; those names remain, as aliases of the same classes.
+
+Everything else is a caller bug and raises Ruby's own error for it, checked once in the shared
+doors rather than left to whichever backend is live: a `TypeError` for a time that is not a
+`Time`, an Integer or `nil`, for a count that is not an Integer, for a namespace that is not a
+`Uuid` or a name that is not a `String`; an `ArgumentError` for a count outside
+0..2³² − 1.
+
+### Is the native core there?
+
+`HyperUuid.available?` answers whether a backend actually loaded — probed once, cached, never
+raising — for a consumer with a fallback of its own:
+
+```ruby
+id = HyperUuid.available? ? HyperUuid.new_v7.to_s : SecureRandom.uuid
+```
+
+`HyperUuid.native_version` reads the version out of the loaded core itself (its
+`hyperuuid_version` export), so a mismatch against `HyperUuid::VERSION` can be named before
+the first UUID is minted. `HyperUuid::BACKEND` says which backend was *selected*, which is not
+the same question: it reads `:fiddle` on a platform with no library at all, because that is
+the backend whose first call explains what is missing — a `LoadError` naming the path it
+looked for, or `HyperUuid::NativePlatform::UnsupportedPlatformError` naming the platform.
+
+## Why not `SecureRandom.uuid`?
+
+`SecureRandom.uuid` only ever gives you a random v4 UUID — Ruby's stdlib has no built-in v5, v6, or v7 at all. If you need more than that, the choice is really "which gem":
+
+1. **Full RFC 9562 coverage, one gem, zero extra dependency.** v4/v5/v6/v7 plus batch generation plus `Nil`/`Max`, and the only thing this gem adds to your `Gemfile.lock` beyond `Fiddle` — which is Ruby's own bundled FFI layer, not a third-party C extension to compile.
+2. **No native-extension compile step.** Third-party UUID gems that go beyond v4 are typically pure Ruby or wrap a C extension compiled at install time; this gem ships its fast path as a prebuilt platform-gem extension and its fallback as a `dlopen`ed prebuilt library — either way, the gem itself compiles nothing at install time ([Install](#install) has the one caveat, which is Fiddle's own).
+3. **Batch generation.** `new_v7_batch(1000)` shares one timestamp capture, one random-bytes fetch, and one counter reservation across the whole batch instead of paying per-item overhead a thousand times over.
+4. **Cross-language consistency.** The same Rust core mints v5 namespace UUIDs for Python, Go, C#, and every other binding in this repo — verified in CI to match Python's own `uuid.uuid5` byte-for-byte. If your system isn't Ruby-only, no Ruby-only gem can offer that.
+
+The honest trade-off: this gem is native code, not pure Ruby — a precompiled extension in each platform gem, and on the universal gem a platform-specific `libhyperuuid.so`/`.dylib`/`.dll` loaded through Fiddle — so it runs only where one of those was built. If plain v4 randomness is all you need, `SecureRandom.uuid` is simpler and already in stdlib — that's a completely reasonable choice.
+
+## Bulk generation into bytes
+
+`new_v6_batch_bytes` and `new_v7_batch_bytes` return the batch as one binary `String` of raw RFC 9562-ordered bytes — 16 per UUID — instead of an Array of `Uuid` objects:
+
+```ruby
+bytes = HyperUuid.new_v7_batch_bytes(1000)
+first = bytes[0, 16]        # ready for a BINARY(16) bind parameter
+```
+
+**About 20x faster than `new_v7_batch`** for a 1000-UUID batch (10.4 µs versus 210 µs). The native call is identical — the difference is that `new_v7_batch` then allocates a `Uuid` object and its byte Strings for every item on top of it. This hands back the bytes the native core already produced, untouched.
+
+The catch, and it inverts the advice: **if you need `Uuid` objects, keep using `new_v7_batch`.** Slicing these bytes into objects yourself just relocates the identical allocations into your own code, and measures no better — sometimes worse. Reach for the byte form only when bytes are the destination: a bind parameter, a wire format, a bulk load.
+
+Slice it with `bytes[i * 16, 16]` — which is exactly what `new_v7_batch` does internally.
+
+## Benchmarks
+
+`ruby benchmark/uuid_benchmark.rb` reproduces every table here and the bytes-versus-objects
+comparison above. Its first line names the backend, core version and Ruby it measured, so
+run it again under `HYPERUUID_PURE=1` for the other backend.
+
+Real numbers, `benchmark-ips` on Ruby 4.0.7, linux-x64 on an Intel Core i9-11900H (`ruby benchmark/uuid_benchmark.rb`) — not claimed, measured. With the Magnus backend (the default wherever the extension loads):
+
+| Call | i/s | vs `SecureRandom.uuid` |
+|---|---:|---:|
+| `SecureRandom.uuid` | 872,365 | baseline |
+| `HyperUuid.new_v4` | 4,278,000 | **4.9x faster** |
+| `HyperUuid.new_v7` (explicit ms) | 3,517,000 | **4.0x faster** |
+| `HyperUuid.new_v6` (explicit ms) | 3,487,000 | **4.0x faster** |
+| `HyperUuid.new_v6` (current time) | 3,324,000 | **3.8x faster** |
+| `HyperUuid.new_v7` (current time) | 3,320,000 | **3.8x faster** |
+| `HyperUuid.new_v5` | 1,838,000 | 2.1x faster |
+
+A `HyperUuid.new_v4` — real entropy, correct version/variant bits, minted by the shared Rust core — costs a fifth of what `SecureRandom.uuid` does, because the Magnus extension is an ordinary native method call with nothing marshalled around it.
+
+The "current time" rows deserve a footnote, because they will not look like this everywhere. Here they land beside the explicit-ms rows: the only difference between the two is one `Process.clock_gettime(CLOCK_REALTIME)` wall-clock read, and on this machine that read is too cheap to see. On a machine with a slow clock it is the whole story — where a virtualized clock defeats the vDSO fast path the same read costs ~1µs, which puts both current-time rows at parity with `SecureRandom.uuid` while the explicit-ms rows stay well ahead of it. `SecureRandom.uuid` never reads a clock — random v4 is the only thing it does. If your clock is slow and you are minting many, read it once and pass the timestamp, or use the batch doors.
+
+The Fiddle fallback (`HYPERUUID_PURE=1`, and any platform without a prebuilt extension) keeps its own diet — a reused thread-local scratch buffer instead of two GC-finalizer-registering mallocs per call, zero-copy `String` passes for read-only inputs, an unsynchronized fast path past the load mutex — landing at 1.25x slower than `SecureRandom.uuid` for v4 (1.26 µs against 1.01 µs in its own run) and 1.45x slower for v6/v7, with the same structural story as before: `Fiddle`'s interpreted marshalling is the floor, and the batch doors are how you amortize it.
+
+Batch generation still amortizes per-call cost on both backends — one native call for the whole batch:
+
+| Call | i/s (Magnus backend) |
+|---|---:|
+| `new_v6` × 1000 (individual) | 3,498 |
+| `new_v6_batch(1000)` | 4,633 (**1.3x**) |
+| `new_v7` × 1000 (individual) | 3,539 |
+| `new_v7_batch(1000)` | 4,677 (**1.3x**) |
+
+The multiplier is small on this backend for the best reason available: the individual calls are cheap, so there is little waste left to amortize, and what `new_v7_batch` spends its 214 µs on is building a thousand `Uuid` objects — the byte form above does the same native work in 10 µs. On the Fiddle backend, where each call costs 1.4 µs, the same batch is 6.7x the loop. If you need v5/v6/v7, need many at once, or need this Ruby service's IDs to agree byte-for-byte with a Go or Python service's, that's what this gem is for — and now it's the fast option too, not just the capable one.
+
+## Backends
+
+| `HyperUuid::BACKEND` | What runs | Chosen when |
+|---|---|---|
+| `:native` | the core linked into a Magnus extension | a precompiled platform gem is installed — every one carries an extension for each Ruby it installs on; see [Install](#install) |
+| `:fiddle` | `libhyperuuid` for this platform, `dlopen`ed through Fiddle | no extension loads: the universal gem, on a Ruby or platform no platform gem covers; also the answer when nothing loads at all |
+
+Selection happens once, at `require`, in that order.
+
+`HYPERUUID_PURE` forces `:fiddle`, even where an extension would load. It is a testing and
+diagnostic switch — CI runs the whole suite through it, and it is how to rule an extension
+problem in or out — not a setting a deployment needs. It is read for presence, not value: set
+to anything at all, `0` and the empty string included, it forces Fiddle. A forced backend that
+turns out to have nothing to load does not fall through to another one: the first call raises,
+and `HyperUuid.available?` answers `false`. That is what happens inside a platform gem, which
+carries no Fiddle library: the `LoadError` names the universal gem
+(`gem install hyperuuid --platform ruby`, or Bundler's `force_ruby_platform`), where the
+Fiddle backend lives.
+
+**Threads.** Every backend is safe to call from any number of threads. The extension runs
+under the GVL. Fiddle releases the GVL for the duration of each call, so that is the one
+backend where Ruby threads run the core truly in parallel — each through its own scratch
+buffer, with the core's v7 counter shared and atomic. `spec/hyperuuid_spec.rb`'s "concurrent
+callers" examples run under both.
+
+**Ractors.** Main Ractor only, on every backend: called from another Ractor the doors raise
+`Ractor::UnsafeError`.
+
+## Verifying provenance
+
+Every gem RubyGems.org serves — the universal fallback and each of the seven precompiled
+platform gems — carries its own GitHub build-provenance attestation, signed directly by
+this repo's own `release.yml` (the `rubygems-publish` job attests `ruby/pkg/*.gem` right
+before the push), so plain `--repo` verifies any of them:
+
+```sh
+gem fetch hyperuuid -v X.Y.Z --platform <platform>   # or omit --platform for the universal gem
+gh attestation verify hyperuuid-X.Y.Z-<platform>.gem --repo SkunkWerkx/HyperUuid
+```
+
+That's the release's second layer of checking, not the only one: before any gem gets built,
+the same job verifies every native binary it packs — the Fiddle libraries, the Magnus
+extensions (one per Ruby ABI per platform) — against *their own*
+attestations — those are signed from `SkunkWerkx/.github` by `hyper-build-native.yml`, so
+that check needs `--signer-repo SkunkWerkx/.github` added — and refuses to proceed on an
+unverified one. RubyGems.org has no unpublish and no
+duplicate-version overwrite, so this all happens while a bad artifact is still reversible.
+The release run's job summary then re-fetches every gem from the CDN and records
+attested-vs-served digests, turning "rubygems.org stores an upload verbatim" into a
+per-release measurement rather than an assumption — see
+[csharp/README.md's provenance section](../csharp/README.md#native-binary-provenance) for
+more on why `--signer-repo` is needed for some artifacts here and not others.
+
+## Install
+
+```sh
+gem install hyperuuid
+```
+
+Eight gems are published per release: seven precompiled Magnus platform gems that
+`gem install` and `bundle` auto-select when they match — `x86_64-linux-gnu`,
+`aarch64-linux-gnu`, `x86_64-linux-musl`, `aarch64-linux-musl`, `arm64-darwin`,
+`x64-mingw-ucrt` and `aarch64-mingw-ucrt` — and one universal `ruby`-platform gem. A platform gem carries its
+Magnus extensions and nothing else native: no Fiddle library at all. The universal gem is
+the last resort, Fiddle with every platform's native library bundled, and it is what
+RubyGems resolves for a Ruby the platform gems do not cover (3.3, or a Ruby newer than the
+release, such as 4.1 before a release ships for it) and on a platform no platform gem is
+built for — Intel macOS among them, which runs on Fiddle. No extra configuration needed either
+way.
+
+Selection has **two** axes here, unlike every other binding in this repo. A Magnus extension
+is bound to one Ruby minor ABI — there's no `abi3` equivalent to collapse the version axis the
+way [the Python binding's](../python/) wheels do — so each platform gem is a "fat" gem
+carrying one compiled extension per supported Ruby, under `lib/hyperuuid/<minor>/`, and picks
+one at `require` time:
+
+| Ruby | Linux (glibc and musl), Apple silicon macOS, Windows — x64 and arm64 | Gem installed |
+| --- | --- | --- |
+| a newer Ruby than the release covers (4.1+) | Fiddle | universal |
+| 4.0 (primary) | Magnus, `BACKEND == :native` | platform |
+| 3.4 (until its EOL 2028-03-31) | Magnus, `BACKEND == :native` | platform |
+| 3.3 (the floor, until its EOL 2027-03-31) | Fiddle | universal |
+
+What stands behind each cell: CI runs the whole suite through each Magnus extension on every
+push — Ruby 3.4 and 4.0 on all seven platform-gem platforms, the two musl ones inside each
+Ruby's own Alpine image — and the Fiddle suite on Ruby 4.0 on every one of them, plus on Ruby
+3.3 inside Alpine. Intel macOS has no CI leg: its library is cross-built and tested at the
+core, and Ruby there runs the universal gem's Fiddle backend over it. Anywhere else — a platform with no native build at
+all — the universal gem installs but `HyperUuid.available?` answers `false`, and the first
+call raises `HyperUuid::NativePlatform::UnsupportedPlatformError`.
+
+The platform gems declare `required_ruby_version >= 3.4, < 4.1` precisely so RubyGems
+*declines* them outside that range and resolves the universal gem instead — a wrong-ABI
+extension must never be installed in the first place. On Windows it would at least fail to
+load cleanly (the extension imports `<arch>-ucrt-ruby<minor>.dll` by name —
+`x64-ucrt-ruby400.dll` on x64, `aarch64-ucrt-ruby400.dll` on ARM), but Linux extensions
+don't link libruby at all, so one can load successfully against the wrong ABI and misbehave
+later. When 3.4 goes EOL it simply leaves the matrix and its users fall back to Fiddle, which
+is exactly what the fallback is for.
+
+**musl.** Alpine has platform gems of its own, `x86_64-linux-musl` and
+`aarch64-linux-musl`, whose extensions are built inside each Ruby's official `ruby:*-alpine`
+image and need nothing beyond musl's libc. The glibc gems name their libc too
+(`x86_64-linux-gnu`, `aarch64-linux-gnu`), which is what makes both `gem install` and
+Bundler pick the right one on every supported Ruby: next to a plain `x86_64-linux` gem,
+RubyGems before 4.0 resolves that one on Alpine instead, even under
+`--platform x86_64-linux-musl`.
+
+**Nothing in this gem is ever compiled, on any platform.** Its one dependency can be:
+`fiddle` is a bundled gem on Ruby 4.0 and a default gem on 3.3 and 3.4, and `gem install` is
+satisfied by the copy Ruby ships. Bundler resolves the newest `fiddle` on rubygems.org
+instead, and when that is newer than the one your Ruby ships — true today on 3.3 and 3.4, not
+on 4.0 — it builds Fiddle's own C extension, which takes a compiler and libffi's headers
+(`apk add build-base libffi-dev` on Alpine). Holding `fiddle` at your Ruby's version in the
+`Gemfile.lock` avoids that.
+
+Both Windows architectures get a Magnus gem. MinGW is the *only* Windows flavour `rb-sys`
+targets (`x64-mingw-ucrt` and `aarch64-mingw-ucrt`, both `supported: true` in its own
+`data/toolchains.json`); the one it has no support for is MSVC. Windows is also where the
+Fiddle fallback costs the most: measured on win-x64, Ruby 3.4, the Magnus backend does
+`new_v4` in 406ns against Fiddle's 2407ns (**5.9x**) and `new_v7` in 595ns against 2759ns
+(**4.6x**) — a far wider gap than any Linux or macOS leg shows — and on real Windows-on-ARM
+hardware, Ruby 4.0.6, `new_v4` in 416ns against Fiddle's 2299ns (**5.5x**) and `new_v7` in
+621ns against 2474ns (**4.0x**), the same shape. Both extensions are built for the `gnullvm`
+Rust targets rather than `gnu` — the same mingw-w64/UCRT ABI RubyInstaller's Ruby uses,
+linked with LLVM and compiler-rt instead of GCC and a statically-linked libgcc, which is what
+keeps the shipped extension small. The build script, and the two flags that are load-bearing
+on the ARM leg (a static libunwind, and a clang-spelled `--target` for bindgen), live in the
+forge's `ruby-magnus` action (`build-magnus.sh`), shared with every other Hyper* repo.
+
+## Development
+
+Everything below runs from a checkout, with `rust/` beside `ruby/`; none of it is needed to
+use the gem. The Fiddle backend finds the in-repo build on its own when nothing
+is staged under `lib/hyperuuid/native/`. The Magnus backend does not — an extension has to be
+built for the Ruby you are running and put where `require` looks — and that is what
+`rake native:dev` is for.
+
+```sh
+cd rust
+cargo cdylib                           # libhyperuuid, what the Fiddle backend loads
+
+cd ../ruby
+bundle install
+bundle exec rake native:dev          # build the Magnus extension for this Ruby and stage it
+bundle exec rspec                    # BACKEND == :native
+HYPERUUID_PURE=1 bundle exec rspec   # BACKEND == :fiddle
+bundle exec rake docs:check          # every public object carries a doc comment
+ruby benchmark/uuid_benchmark.rb     # prints the backend it measured
+```
+
+`rake native:dev` runs `cargo ruby-ext` (an alias in `rust/.cargo/config.toml` that builds the
+`ruby` feature into `rust/target/ruby/`, never over the plain library in
+`rust/target/release/`) and copies the result to
+`lib/hyperuuid/<minor>/hyperuuid_native.<so|bundle>` — the path `lib/hyperuuid.rb` tries
+first. The copy is also a rename, and it is the step `cargo ruby-ext` alone does not do: cargo
+names its output `libhyperuuid.so`, and Ruby derives the `Init_` function it calls from the
+file name it was asked to `require`. Three things worth knowing:
+
+- **Run it again after changing `rust/`.** The staged file is a copy; nothing rebuilds it.
+- **One staging per Ruby.** An extension is bound to one Ruby minor, so under a second Ruby
+  (`RBENV_VERSION=3.4.11 bundle exec rake native:dev`, say) the task rebuilds for that ABI
+  and stages beside the first, each Ruby loading its own.
+- **Without it, `bundle exec rspec` still passes — on Fiddle.** The examples under "native
+  backend" report themselves pending with `BACKEND=fiddle`; that line, or
+  `ruby -Ilib -rhyperuuid -e 'p HyperUuid::BACKEND'`, is how to tell which backend a run
+  exercised. Deleting `lib/hyperuuid/<minor>/` goes back to Fiddle.
+
+The task covers Linux and macOS. The Windows extensions need the `gnullvm` targets and linker
+flags in the forge's `build-magnus.sh`, which is also what CI uses on every platform.
+
+The musl build has no host to run on outside a container. With the core built for musl at
+`rust/target/musl/linux-musl-x64/libhyperuuid.so`, this runs the Fiddle suite against it on
+Alpine, with the checkout mounted read-only:
+
+```sh
+docker run --rm -v "$PWD/..":/src:ro ruby:4.0-alpine sh -euc '
+  mkdir /work && cp -r /src/ruby /work/ruby
+  mkdir -p /work/ruby/lib/hyperuuid/native/linux-musl-x64
+  cp /src/rust/target/musl/linux-musl-x64/libhyperuuid.so /work/ruby/lib/hyperuuid/native/linux-musl-x64/
+  cd /work/ruby && rm -f Gemfile.lock
+  bundle install --quiet --prefer-local
+  HYPERUUID_PURE=1 bundle exec rspec'
+```
+
+The floor's test is the same container on `ruby:3.3-alpine`. Bundler would compile a newer
+Fiddle there (see [Install](#install)), so this one goes around Bundler and runs against the
+Fiddle that Ruby 3.3 ships:
+
+```sh
+docker run --rm -v "$PWD/..":/src:ro ruby:3.3-alpine sh -euc '
+  mkdir /work && cp -r /src/ruby /work/ruby
+  mkdir -p /work/ruby/lib/hyperuuid/native/linux-musl-x64
+  cp /src/rust/target/musl/linux-musl-x64/libhyperuuid.so /work/ruby/lib/hyperuuid/native/linux-musl-x64/
+  cd /work/ruby && rm -f Gemfile Gemfile.lock
+  gem install rspec -v "~> 3.13" --no-document --silent
+  HYPERUUID_PURE=1 rspec'
+```
+
+The musl Magnus extension is built the way CI builds it by the forge's
+`ruby-magnus-musl/build-magnus-musl.sh`, which runs on any machine with Docker: from the repo
+root, `build-magnus-musl.sh hyperuuid linux-musl-x64 4.0 . <dir with the musl libhyperuuid.so> <out-dir>`
+compiles it in `ruby:4.0-alpine`, then runs this suite through it on a bare copy of that image.
+
+See [the repo root README](../README.md) for the full RFC 9562 coverage table and the state of every other language binding.
+
+## License
+
+[MIT](https://github.com/SkunkWerkx/HyperUuid/blob/master/LICENSE)

data/lib/hyperuuid/errors.rb

@@ -0,0 +1,12 @@
+module HyperUuid
+  # Raised when the operating system's random source fails while a UUID is being minted —
+  # the one way `new_v4`, `new_v6`, `new_v7` and their batch forms can fail once their
+  # arguments are valid. Carries the same message on every backend.
+  class RandomSourceError < StandardError; end
+
+  # Raised when a timestamp cannot be embedded in the UUID being minted: a version 7 value
+  # past RFC 9562's 48-bit millisecond field, a version 6 value past its 60-bit field, or
+  # any negative one (a `Time` before the Unix epoch included). Carries the same message on
+  # every backend.
+  class TimestampOutOfRangeError < StandardError; end
+end

data/lib/hyperuuid/namespaces.rb

@@ -0,0 +1,13 @@
+module HyperUuid
+  # Well-known namespace UUIDs defined in RFC 9562 Section 6.6.
+  module Namespaces
+    # The DNS namespace UUID.
+    DNS = Uuid.parse("6ba7b810-9dad-11d1-80b4-00c04fd430c8")
+    # The URL namespace UUID.
+    URL = Uuid.parse("6ba7b811-9dad-11d1-80b4-00c04fd430c8")
+    # The ISO OID namespace UUID.
+    OID = Uuid.parse("6ba7b812-9dad-11d1-80b4-00c04fd430c8")
+    # The X.500 DN namespace UUID.
+    X500 = Uuid.parse("6ba7b814-9dad-11d1-80b4-00c04fd430c8")
+  end
+end

data/lib/hyperuuid/native_platform.rb

@@ -0,0 +1,28 @@
+module HyperUuid
+  # Maps the running RUBY_PLATFORM to the RID-style directory (matching the other bindings'
+  # runtimes/{rid}/native/ / native/{rid}/ convention) and native library filename to load.
+  module NativePlatform
+    class UnsupportedPlatformError < StandardError; end
+
+    # +platform+ is a parameter only so the specs can walk the whole table from one host;
+    # every real caller takes the default.
+    def self.rid_and_library_name(platform = RUBY_PLATFORM)
+      arch = platform.match?(/arm64|aarch64/) ? "arm64" : "x64"
+
+      case platform
+      when /mingw|mswin|windows/
+        ["win-#{arch}", "hyperuuid.dll"]
+      when /darwin/
+        ["osx-#{arch}", "libhyperuuid.dylib"]
+      when /linux/
+        # Two C libraries, two builds: a glibc-linked library cannot be relied on to dlopen
+        # into a musl process (Alpine), so musl gets RIDs of its own. Ruby names the libc
+        # in its platform string there ("x86_64-linux-musl") and leaves it off on glibc.
+        os = platform.include?("musl") ? "linux-musl" : "linux"
+        ["#{os}-#{arch}", "libhyperuuid.so"]
+      else
+        raise UnsupportedPlatformError, "hyperuuid: unsupported platform RUBY_PLATFORM=#{platform}"
+      end
+    end
+  end
+end

data/lib/hyperuuid/runtime.rb

@@ -0,0 +1,266 @@
+require "fiddle"
+
+module HyperUuid
+  # Fiddle plumbing for the native libhyperuuid shared library — dlopen/dlsym plus a raw
+  # C-ABI call, no runtime bridge (the same "no shim" positioning as the Swift binding's
+  # dlopen approach). Fiddle ships with every Ruby install; it's a plain gem dependency here
+  # (see hyperuuid.gemspec) rather than a third-party one — mirroring Python's
+  # zero-dependency PyO3 wheels.
+  #
+  # A Ruby gem's files are plain files on disk once installed, so native/{rid}/{lib} can be
+  # dlopen'd directly, with no extraction step.
+  module Runtime
+    # The package's two exceptions live on HyperUuid itself (errors.rb). These are the names
+    # they had through 0.3.0, kept as aliases of the very same classes so a
+    # `rescue HyperUuid::Runtime::TimestampOutOfRangeError` written against an earlier
+    # release still catches.
+    RandomSourceError = HyperUuid::RandomSourceError
+    TimestampOutOfRangeError = HyperUuid::TimestampOutOfRangeError
+
+    # One copy of each out-of-range message for the Fiddle backend and for the
+    # doors' own range check in hyperuuid.rb; the Magnus extension (rust/src/ruby_ext.rs)
+    # carries the same text, and spec/native_backend_spec.rb pins that the two agree.
+    V6_TIMESTAMP_OUT_OF_RANGE = "unix_millis does not fit the 60-bit v6 timestamp field"
+    V7_TIMESTAMP_OUT_OF_RANGE = "unix_millis must fit within the RFC 9562 48-bit field"
+
+    NATIVE_DIR = File.join(__dir__, "native")
+
+    @mutex = Mutex.new
+    @functions = nil
+
+    class << self
+      def new_v4
+        out = scratch
+        rc = functions[:new_v4].call(out)
+        raise random_source_failure("uuid_new_v4") unless rc.zero?
+        out[0, 16]
+      end
+
+      def new_v5(namespace_bytes, name_bytes)
+        out = scratch
+        # Fiddle passes a String's own bytes for void* (read-only, no copy of them) — the
+        # same crossing every other input here uses. An empty name crosses as it is, a
+        # valid pointer with length 0, never as nil: NULL is not part of this export's
+        # contract.
+        rc = functions[:new_v5].call(namespace_bytes, name_bytes, name_bytes.bytesize, out)
+        raise random_source_failure("uuid_new_v5") unless rc.zero?
+        out[0, 16]
+      end
+
+      def new_v6(unix_millis)
+        out = scratch
+        rc = functions[:new_v6].call(unix_millis, out)
+        case rc
+        when 0 then out[0, 16]
+        when 2 then raise TimestampOutOfRangeError, V6_TIMESTAMP_OUT_OF_RANGE
+        else raise random_source_failure("uuid_new_v6")
+        end
+      end
+
+      def v6_unix_millis(bytes)
+        functions[:v6_unix_millis].call(bytes)
+      end
+
+      def new_v6_batch(count, unix_millis)
+        return "" if count.zero?
+        out = Fiddle::Pointer.malloc(count * 16, Fiddle::RUBY_FREE)
+        rc = functions[:new_v6_batch].call(unix_millis, count, out)
+        case rc
+        when 0 then out[0, count * 16]
+        when 2 then raise TimestampOutOfRangeError, V6_TIMESTAMP_OUT_OF_RANGE
+        else raise random_source_failure("uuid_new_v6_batch")
+        end
+      end
+
+      def new_v7(unix_millis)
+        out = scratch
+        rc = functions[:new_v7].call(unix_millis, out)
+        case rc
+        when 0 then out[0, 16]
+        when 2 then raise TimestampOutOfRangeError, V7_TIMESTAMP_OUT_OF_RANGE
+        else raise random_source_failure("uuid_new_v7")
+        end
+      end
+
+      def v7_unix_millis(bytes)
+        functions[:v7_unix_millis].call(bytes)
+      end
+
+      def new_v7_batch(count, unix_millis)
+        return "" if count.zero?
+        out = Fiddle::Pointer.malloc(count * 16, Fiddle::RUBY_FREE)
+        rc = functions[:new_v7_batch].call(unix_millis, count, out)
+        case rc
+        when 0 then out[0, count * 16]
+        when 2 then raise TimestampOutOfRangeError, V7_TIMESTAMP_OUT_OF_RANGE
+        else raise random_source_failure("uuid_new_v7_batch")
+        end
+      end
+
+      def v7_to_sql_order(bytes)
+        rewrite(:v7_to_sql_order, bytes)
+      end
+
+      def v7_to_rfc_order(bytes)
+        rewrite(:v7_to_rfc_order, bytes)
+      end
+
+      def v6_to_sql_order(bytes)
+        rewrite(:v6_to_sql_order, bytes)
+      end
+
+      def v6_to_rfc_order(bytes)
+        rewrite(:v6_to_rfc_order, bytes)
+      end
+
+      # The loaded core's version word, major << 16 | minor << 8 | patch, straight from the
+      # library's zero-argument hyperuuid_version export. HyperUuid.native_version unpacks
+      # it; like every method here, each backend replaces this one in place.
+      def packed_version
+        functions[:version].call
+      end
+
+      # The one failure every generating export shares, with the one message every backend
+      # raises for it: the export's name, and that the system's random source failed.
+      def random_source_failure(export)
+        RandomSourceError.new("#{export}: the system random source failed")
+      end
+
+      private
+
+      # The shared library to dlopen: this install's native/{rid}/{lib}, or — the
+      # development loop — the in-repo cargo build, exactly what the other bindings' local
+      # staging does (HyperCast's runtime has had this since its first release). Nil when
+      # neither exists.
+      def library_path
+        rid, lib_name = NativePlatform.rid_and_library_name
+        path = File.join(NATIVE_DIR, rid, lib_name)
+        return path if File.exist?(path)
+
+        repo_build = File.expand_path(File.join(__dir__, "../../../rust/target/release", lib_name))
+        File.exist?(repo_build) ? repo_build : nil
+      end
+
+      # Why Fiddle found nothing to load. A precompiled platform gem is the one install where
+      # that is by design rather than a gap: it carries only its Magnus extensions, and the
+      # Fiddle backend is reached there only by forcing it (HYPERUUID_PURE) or because none
+      # of its extensions loaded — a gem RubyGems matched to a Ruby it was not built for,
+      # such as the glibc Linux gem that `gem install` on RubyGems 3.x picks on Alpine. So
+      # that case names its fix, the universal gem, which carries every platform's library,
+      # instead of a missing path that reads like a packaging bug. Both arguments are
+      # parameters only so the specs can ask for every wording.
+      def missing_library_message(gem_platform = Gem.loaded_specs["hyperuuid"]&.platform,
+                                  forced = ENV.key?("HYPERUUID_PURE"))
+        rid, lib_name = NativePlatform.rid_and_library_name
+        missing = File.join(NATIVE_DIR, rid, lib_name)
+        if gem_platform && gem_platform.to_s != Gem::Platform::RUBY
+          reason =
+            if forced
+              "HYPERUUID_PURE forces the Fiddle backend (unset it to use the extension)"
+            else
+              "none of its extensions loads on this Ruby (#{RUBY_VERSION}, #{RUBY_PLATFORM})"
+            end
+          "hyperuuid: this #{gem_platform} platform gem carries only Magnus extensions, no " \
+            "Fiddle library, and #{reason}. The universal gem has the Fiddle backend for every " \
+            "platform: `gem install hyperuuid --platform ruby`, or Bundler's force_ruby_platform " \
+            "(#{missing} not found)"
+        else
+          "hyperuuid: #{missing} not found (unsupported platform, or this gem was built " \
+            "without a native library for it)"
+        end
+      end
+
+      # One 16-byte scratch allocation per thread, reused by every single-item call —
+      # Fiddle::Pointer.malloc(..., RUBY_FREE) registers a GC finalizer per call, measured
+      # (in HyperCast, same mechanism) as the dominant per-call cost by an order of
+      # magnitude. Batches keep a per-call buffer: one malloc amortized over `count` IDs.
+      def scratch
+        Thread.current[:hyperuuid_scratch] ||= Fiddle::Pointer.malloc(16, Fiddle::RUBY_FREE)
+      end
+
+      # The in-place byte-order rewrites are the one shape that must copy in: the native
+      # call genuinely mutates the buffer, and the input String is frozen.
+      def rewrite(symbol, bytes)
+        buf = scratch
+        buf[0, 16] = bytes
+        functions[symbol].call(buf)
+        buf[0, 16]
+      end
+
+      # Loaded lazily and exactly once, mirroring Java's class initializer / Swift's lazy
+      # static let — the native library and its function pointers live for the process's
+      # lifetime, same as every other binding (never dlclose'd). The unsynchronized read is
+      # the hot path; the mutex only guards the one-time load (a benign race — idempotent).
+      def functions
+        @functions || @mutex.synchronize { @functions ||= load_functions }
+      end
+
+      def load_functions
+        path = library_path
+        raise LoadError, missing_library_message if path.nil?
+
+        handle = Fiddle.dlopen(path)
+        {
+          new_v4: Fiddle::Function.new(handle["uuid_new_v4"], [Fiddle::TYPE_VOIDP], Fiddle::TYPE_INT),
+          new_v5: Fiddle::Function.new(
+            handle["uuid_new_v5"],
+            [Fiddle::TYPE_VOIDP, Fiddle::TYPE_VOIDP, Fiddle::TYPE_UINT32_T, Fiddle::TYPE_VOIDP],
+            Fiddle::TYPE_INT
+          ),
+          new_v6: Fiddle::Function.new(
+            handle["uuid_new_v6"],
+            [Fiddle::TYPE_UINT64_T, Fiddle::TYPE_VOIDP],
+            Fiddle::TYPE_INT
+          ),
+          v6_unix_millis: Fiddle::Function.new(
+            handle["uuid_v6_unix_millis"],
+            [Fiddle::TYPE_VOIDP],
+            Fiddle::TYPE_UINT64_T
+          ),
+          new_v6_batch: Fiddle::Function.new(
+            handle["uuid_new_v6_batch"],
+            [Fiddle::TYPE_UINT64_T, Fiddle::TYPE_UINT32_T, Fiddle::TYPE_VOIDP],
+            Fiddle::TYPE_INT
+          ),
+          new_v7: Fiddle::Function.new(
+            handle["uuid_new_v7"],
+            [Fiddle::TYPE_UINT64_T, Fiddle::TYPE_VOIDP],
+            Fiddle::TYPE_INT
+          ),
+          v7_unix_millis: Fiddle::Function.new(
+            handle["uuid_v7_unix_millis"],
+            [Fiddle::TYPE_VOIDP],
+            Fiddle::TYPE_UINT64_T
+          ),
+          new_v7_batch: Fiddle::Function.new(
+            handle["uuid_new_v7_batch"],
+            [Fiddle::TYPE_UINT64_T, Fiddle::TYPE_UINT32_T, Fiddle::TYPE_VOIDP],
+            Fiddle::TYPE_INT
+          ),
+          v7_to_sql_order: Fiddle::Function.new(
+            handle["uuid_v7_to_sql_order"],
+            [Fiddle::TYPE_VOIDP],
+            Fiddle::TYPE_VOID
+          ),
+          v7_to_rfc_order: Fiddle::Function.new(
+            handle["uuid_v7_to_rfc_order"],
+            [Fiddle::TYPE_VOIDP],
+            Fiddle::TYPE_VOID
+          ),
+          v6_to_sql_order: Fiddle::Function.new(
+            handle["uuid_v6_to_sql_order"],
+            [Fiddle::TYPE_VOIDP],
+            Fiddle::TYPE_VOID
+          ),
+          v6_to_rfc_order: Fiddle::Function.new(
+            handle["uuid_v6_to_rfc_order"],
+            [Fiddle::TYPE_VOIDP],
+            Fiddle::TYPE_VOID
+          ),
+          # The one export that mints nothing: the zero-argument version probe.
+          version: Fiddle::Function.new(handle["hyperuuid_version"], [], Fiddle::TYPE_UINT32_T),
+        }
+      end
+    end
+  end
+end

data/lib/hyperuuid/uuid.rb

@@ -0,0 +1,179 @@
+module HyperUuid
+  # A parsed 16-byte RFC 9562 UUID value. Minimal by design — this gem has no runtime
+  # dependency on the `uuid` gem, the same "no extra dependency" positioning as the Go
+  # binding's lone google/uuid requirement and the Python binding's dependency-free PyO3
+  # wheels.
+  class Uuid
+    include Comparable
+
+    # The UUID's 16 raw bytes in RFC 9562 (big-endian) order.
+    attr_reader :bytes
+
+    # Wraps a raw 16-byte RFC 9562 (big-endian) UUID value. The bytes are copied, so the
+    # String passed in stays the caller's.
+    #
+    # +owned+ is for this gem's own use: it says +bytes+ is a String the native core has
+    # just produced — sixteen bytes, already ASCII-8BIT, held by nothing else — so there is
+    # nothing to check, copy or re-tag, and that copy is most of what constructing one costs.
+    #
+    # @raise [ArgumentError] if +bytes+ isn't exactly 16 bytes.
+    def initialize(bytes, owned = false)
+      if owned
+        @bytes = bytes.freeze
+      else
+        raise ArgumentError, "bytes must be exactly 16 bytes" unless bytes.bytesize == 16
+
+        @bytes = bytes.dup.force_encoding(Encoding::BINARY).freeze
+      end
+    end
+
+    # The RFC 9562 §5.9 Nil UUID — all 128 bits zero.
+    NIL = new(("\x00" * 16).b).freeze
+
+    # The RFC 9562 §5.10 Max UUID — all 128 bits one.
+    MAX = new(("\xFF" * 16).b).freeze
+
+    # The one text shape .parse accepts: 8-4-4-4-12 hex digits, either case, the four hyphens
+    # exactly where #to_s puts them.
+    HYPHENATED = /\A\h{8}-\h{4}-\h{4}-\h{4}-\h{12}\z/
+    private_constant :HYPHENATED
+
+    # Parses an 8-4-4-4-12 hyphenated hex UUID string — exactly the shape #to_s produces, in
+    # either case. Nothing else parses: not the bare 32 hex digits, not hyphens anywhere but
+    # those four positions, not braces or a `urn:uuid:` prefix.
+    #
+    # @raise [ArgumentError] if +string+ isn't a String in that shape.
+    def self.parse(string)
+      unless string.is_a?(String) && string.match?(HYPHENATED)
+        raise ArgumentError, "invalid UUID string: #{string.inspect}"
+      end
+
+      new([string.delete("-")].pack("H*"))
+    end
+
+    # The RFC 9562 version nibble (bits 48-51, the high nibble of octet 6).
+    def version
+      (bytes.getbyte(6) >> 4) & 0x0F
+    end
+
+    # The RFC 9562 variant bits (top two bits of octet 8). +0b10+ means RFC 9562/4122.
+    def variant
+      (bytes.getbyte(8) >> 6) & 0b11
+    end
+
+    # The 8-4-4-4-12 hyphenated hex string representation.
+    def to_s
+      hex = bytes.unpack1("H*")
+      "#{hex[0, 8]}-#{hex[8, 4]}-#{hex[12, 4]}-#{hex[16, 4]}-#{hex[20, 12]}"
+    end
+    alias_method :to_str, :to_s
+
+    # The UTC timestamp embedded in a version 6 or 7 UUID's timestamp field. Only meaningful
+    # when `version` is 6 or 7 — the RFC 9562 bit layout doesn't distinguish "not a time-based
+    # UUID" from "time-based UUID with a very early timestamp", so the caller is responsible
+    # for checking `version` first if that matters.
+    #
+    # Raises by default for any other version; pass `raise_on_mismatch: false` to get `nil`
+    # back instead — for a caller that doesn't already know (or want to separately check)
+    # whether this UUID is time-based.
+    def timestamp(raise_on_mismatch: true)
+      millis =
+        case version
+        when 6 then Runtime.v6_unix_millis(bytes)
+        when 7 then Runtime.v7_unix_millis(bytes)
+        else
+          raise ArgumentError, "timestamp is only defined for version 6 or 7 UUIDs, got version #{version}" if raise_on_mismatch
+          return nil
+        end
+      Time.at(millis / 1000, millis % 1000, :millisecond).utc
+    end
+
+    # Converts an RFC 9562-ordered version 6 or 7 UUID to the byte order SQL Server's
+    # `uniqueidentifier` needs on the wire to sort by creation order. Dispatches on `version`
+    # the same way #timestamp does.
+    #
+    # `System.Data.SqlTypes.SqlGuid` comparison — and therefore T-SQL `ORDER BY` on a
+    # `uniqueidentifier` column — doesn't compare a GUID's 16 bytes left to right; it uses a
+    # fixed, non-sequential byte significance order (octets 10,11,12,13,14,15,8,9,6,7,4,5,
+    # 0,1,2,3, most significant first). Computed once in the native Rust core and verified
+    # there (and independently, against the real SqlGuid comparator, in this project's C#
+    # test suite); this binding calls the same native functions rather than reimplementing
+    # the byte math.
+    #
+    # For v7, this moves the timestamp and counter — the two fields that determine creation
+    # order — into that comparison's most-significant bytes, and moves the trailing entropy,
+    # which carries no ordering information, into the least-significant ones as one intact
+    # block. For v6, which has no monotonic counter the way v7 does, the only field that
+    # determines creation order is the 60-bit timestamp itself, so that moves into the most
+    # significant bytes instead, with `clock_seq`/`node` (independently random per call, not
+    # a counter, so no ordering value either way) relocated into the rest. v6's much simpler
+    # byte layout needs no bit-level repacking to do this — just whole-octet-group
+    # relocation — unlike v7's, and its version/variant land at different sql-order offsets
+    # as a result (octet 8's top nibble / octet 6's top two bits, not 7/8).
+    #
+    # **v6-specific caveat, unlike v7:** two version 6 UUIDs minted at the same millisecond
+    # have identical timestamp bits, so they aren't guaranteed to sort in creation order any
+    # more than plain RFC order already does — a pre-existing RFC 9562 v6 limitation, not one
+    # this transform introduces.
+    #
+    # Meaningful only for a genuine version 6 or 7 UUID.
+    def to_sql_order
+      case version
+      when 7 then self.class.new(Runtime.v7_to_sql_order(bytes), true)
+      when 6 then self.class.new(Runtime.v6_to_sql_order(bytes), true)
+      else raise ArgumentError, "to_sql_order is only defined for version 6 or 7 UUIDs, got version #{version}"
+      end
+    end
+
+    # Inverse of #to_sql_order — converts a SQL-Server-ordered version 6 or 7 UUID back to
+    # RFC 9562 order.
+    #
+    # A SQL-ordered value's version nibble sits at a different octet depending on which
+    # version produced it (octet 7's top nibble = 7 for v7-sql-order, octet 8's top nibble =
+    # 6 for v6-sql-order — #version itself assumes RFC order's octet 6 and can't tell these
+    # apart), so this checks both fixed positions directly rather than calling #version.
+    #
+    # Order matters here and isn't arbitrary: octet 8 must be checked *first*. For v6-sql-order
+    # it's deterministic (top nibble always 0x6, by construction), and for v7-sql-order it's
+    # also deterministic but structurally excluded from ever reading 0x6 (its top two bits are
+    # the fixed variant `10`, so the nibble only ever lands in 0x8-0xB) — no collision either
+    # way. Octet 7, by contrast, is *not* safe to check first: for v7-sql-order it's
+    # deterministically 0x7, but for v6-sql-order it holds `clock_seq`'s fully random low
+    # byte, which has a real (~1-in-16) chance of a top nibble that also happens to read 0x7 —
+    # confirmed by an actual test failure during development, not a hypothetical. Checking
+    # octet 8 first rules v6 in or out unambiguously before octet 7's reading can matter.
+    def from_sql_order
+      octet8_version = (bytes.getbyte(8) >> 4) & 0x0F
+      octet7_version = (bytes.getbyte(7) >> 4) & 0x0F
+      if octet8_version == 6
+        self.class.new(Runtime.v6_to_rfc_order(bytes), true)
+      elsif octet7_version == 7
+        self.class.new(Runtime.v7_to_rfc_order(bytes), true)
+      else
+        raise ArgumentError, "from_sql_order: not a recognized version 6 or 7 SQL-ordered UUID"
+      end
+    end
+
+    # Whether +other+ wraps the same 16 raw bytes.
+    def ==(other)
+      other.is_a?(Uuid) && bytes == other.bytes
+    end
+    alias_method :eql?, :==
+
+    # Hash code consistent with #==, based on the raw bytes.
+    def hash
+      bytes.hash
+    end
+
+    # Byte-order comparison against +other+, or +nil+ if +other+ isn't a Uuid.
+    def <=>(other)
+      return nil unless other.is_a?(Uuid)
+      bytes <=> other.bytes
+    end
+
+    # Debug representation, e.g. <tt>#<HyperUuid::Uuid ...></tt>.
+    def inspect
+      "#<HyperUuid::Uuid #{self}>"
+    end
+  end
+end

data/lib/hyperuuid.rb

@@ -0,0 +1,247 @@
+require_relative "hyperuuid/errors"
+require_relative "hyperuuid/uuid"
+require_relative "hyperuuid/namespaces"
+require_relative "hyperuuid/native_platform"
+require_relative "hyperuuid/runtime"
+
+# RFC 9562 UUID v4 (random), v5 (deterministic), v6 and v7 (time-sortable) generation from one
+# Rust core, reached through whichever of two backends this install can load: the core
+# linked straight into a Magnus native extension (shipped precompiled in the platform gems),
+# or the native libhyperuuid shared library called through Fiddle (the universal gem bundles
+# one per supported platform, picked by HyperUuid::NativePlatform). No runtime bridge in
+# either, and nothing compiled at install time. HyperUuid::BACKEND names the one that loaded; the selection logic
+# is at the bottom of this file.
+#
+# The doors below — with Uuid, Namespaces and the two exception classes — are the public
+# surface, and are shared by every backend, argument validation included: a caller bug raises
+# the same error whichever backend is live.
+module HyperUuid
+  # This gem's own version — distinct from the RFC 9562 UUID *versions* (v4/v5/v6/v7) the
+  # rest of this module generates.
+  VERSION = "0.6.0"
+
+  # The widest batch count, and the longest v5 name in bytes, the native ABI carries (a u32).
+  # (The millisecond count is a u64; unix_millis_from refuses anything wider.)
+  U32_MAX = 0xFFFF_FFFF
+  private_constant :U32_MAX
+
+  # Creates a random UUID version 4 (RFC 9562 §5.4).
+  def self.new_v4
+    Uuid.new(Runtime.new_v4, true)
+  end
+
+  # Creates a deterministic UUID version 5 (RFC 9562 §5.5) from a namespace and a name. The
+  # same (namespace, name) pair always produces the same UUID. `name` may be a text String
+  # (encoded as UTF-8) or already-raw ASCII-8BIT bytes, which are used as-is; it may be empty.
+  #
+  # @raise [TypeError] if +namespace+ isn't a HyperUuid::Uuid or +name+ isn't a String.
+  def self.new_v5(namespace, name)
+    raise TypeError, "namespace must be a HyperUuid::Uuid; got #{namespace.class}" unless namespace.is_a?(Uuid)
+    raise TypeError, "name must be a String; got #{name.class}" unless name.is_a?(String)
+
+    name_bytes =
+      if name.encoding == Encoding::ASCII_8BIT
+        name
+      else
+        name.encode(Encoding::UTF_8).dup.force_encoding(Encoding::BINARY)
+      end
+    raise ArgumentError, "name must be at most #{U32_MAX} bytes" if name_bytes.bytesize > U32_MAX
+
+    Uuid.new(Runtime.new_v5(namespace.bytes, name_bytes), true)
+  end
+
+  # Converts +value+ to a Unix-epoch millisecond integer: +nil+ becomes the current time, a
+  # +Time+ is converted exactly (via its own Rational seconds, avoiding float rounding), and
+  # an Integer millisecond count passes through unchanged. Shared by every
+  # `new_v6`/`new_v7`/batch door below so a caller can pass either a `Time` or a raw
+  # millisecond count interchangeably.
+  #
+  # This is also where a caller bug is caught once, for every backend: anything else is a
+  # TypeError, and a count that cannot cross the ABI as a u64 at all — negative (a `Time`
+  # before the epoch included) or past 64 bits — is the same TimestampOutOfRangeError, with
+  # the same +out_of_range+ message, the core raises for a value it can see but not embed.
+  # Left to the backends those cases diverged: a RangeError from the extension, a wrapped
+  # value from Fiddle.
+  #
+  # The two common arguments go first and cheapest: no argument is the clock, which needs no
+  # range check, and an Integer is checked by its bit length rather than against 2**64 - 1: a
+  # comparison with a number that size is a bignum comparison, and cost more than the mint.
+  private_class_method def self.unix_millis_from(value, out_of_range)
+    return Process.clock_gettime(Process::CLOCK_REALTIME, :millisecond) if value.nil?
+
+    millis =
+      if value.is_a?(Integer) then value
+      elsif value.is_a?(Time) then (value.to_r * 1000).floor
+      else raise TypeError, "unix_millis must be a Time, an Integer or nil; got #{value.class}"
+      end
+    raise TimestampOutOfRangeError, out_of_range unless millis >= 0 && millis.bit_length <= 64
+
+    millis
+  end
+
+  # Checks a batch +count+ once, for every backend: an Integer the ABI's u32 can carry.
+  private_class_method def self.batch_count(count)
+    raise TypeError, "count must be an Integer; got #{count.class}" unless count.is_a?(Integer)
+    raise ArgumentError, "count must be between 0 and #{U32_MAX}; got #{count}" unless count.between?(0, U32_MAX)
+
+    count
+  end
+
+  # Creates a time-sortable UUID version 6 (RFC 9562 §5.6), a field-compatible reordering of
+  # version 1 for better sort/index locality. Defaults to the current time; pass an explicit
+  # `Time` or Unix-epoch millisecond integer to embed a specific time instead. `clock_seq` and
+  # `node` are randomly generated on every call — unlike version 7, there is no monotonic
+  # counter, so calls within the same millisecond are not guaranteed to sort in creation order.
+  #
+  # @raise [TimestampOutOfRangeError] if the time is negative or past the 60-bit v6 field.
+  # @raise [TypeError] if +unix_millis+ isn't a Time, an Integer or nil.
+  def self.new_v6(unix_millis = nil)
+    Uuid.new(Runtime.new_v6(unix_millis_from(unix_millis, Runtime::V6_TIMESTAMP_OUT_OF_RANGE)), true)
+  end
+
+  # Creates `count` time-sortable version 6 UUIDs sharing one timestamp capture — one FFI call
+  # and one random-bytes fetch instead of `count` of each. Defaults to the current time; pass
+  # an explicit `Time` or Unix-epoch millisecond integer to embed a specific time instead.
+  #
+  # @raise [TypeError, ArgumentError] if +count+ isn't an Integer between 0 and 2**32 - 1.
+  # @raise [TimestampOutOfRangeError] if the time is negative or past the 60-bit v6 field.
+  def self.new_v6_batch(count, unix_millis = nil)
+    bytes = new_v6_batch_bytes(count, unix_millis)
+    Array.new(count) { |i| Uuid.new(bytes[i * 16, 16], true) }
+  end
+
+  # Creates a time-sortable UUID version 7 (RFC 9562 §6.2). Defaults to the current time; pass
+  # an explicit `Time` or Unix-epoch millisecond integer (non-negative, fitting in 48 bits) to
+  # embed a specific time instead.
+  #
+  # @raise [TimestampOutOfRangeError] if the time is negative or past the 48-bit v7 field.
+  # @raise [TypeError] if +unix_millis+ isn't a Time, an Integer or nil.
+  def self.new_v7(unix_millis = nil)
+    Uuid.new(Runtime.new_v7(unix_millis_from(unix_millis, Runtime::V7_TIMESTAMP_OUT_OF_RANGE)), true)
+  end
+
+  # Creates `count` time-sortable version 7 UUIDs sharing one timestamp capture and one
+  # contiguous block of the monotonic counter — one FFI call and one random-bytes fetch
+  # instead of `count` of each. Defaults to the current time; pass an explicit `Time` or
+  # Unix-epoch millisecond integer to embed a specific time instead.
+  #
+  # @raise [TypeError, ArgumentError] if +count+ isn't an Integer between 0 and 2**32 - 1.
+  # @raise [TimestampOutOfRangeError] if the time is negative or past the 48-bit v7 field.
+  def self.new_v7_batch(count, unix_millis = nil)
+    bytes = new_v7_batch_bytes(count, unix_millis)
+    Array.new(count) { |i| Uuid.new(bytes[i * 16, 16], true) }
+  end
+
+  # Returns `count` version 7 UUIDs as one binary String of raw RFC 9562-ordered bytes,
+  # 16 per UUID, instead of an Array of Uuid objects.
+  #
+  # Far faster than #new_v7_batch for a large batch — the README's "Bulk generation into
+  # bytes" section carries the measured figures. The difference is not the native call —
+  # that is identical — it is that #new_v7_batch then allocates `count` Uuid objects and
+  # their byte Strings on top of it. This hands back the bytes the native core already
+  # produced, untouched.
+  #
+  # Use it when bytes are the destination: a BYTEA/uniqueidentifier bind parameter, a wire
+  # format, a bulk COPY. If you need Uuid objects, keep using #new_v7_batch — slicing this
+  # String into them yourself just moves the same allocations into your own code.
+  #
+  # Slice it with `bytes[i * 16, 16]`, which is what #new_v7_batch does internally.
+  #
+  # @raise [TypeError, ArgumentError] if +count+ isn't an Integer between 0 and 2**32 - 1.
+  # @raise [TimestampOutOfRangeError] if the time is negative or past the 48-bit v7 field.
+  def self.new_v7_batch_bytes(count, unix_millis = nil)
+    count = batch_count(count)
+    Runtime.new_v7_batch(count, unix_millis_from(unix_millis, Runtime::V7_TIMESTAMP_OUT_OF_RANGE))
+  end
+
+  # Returns `count` version 6 UUIDs as one binary String of raw RFC 9562-ordered bytes,
+  # 16 per UUID. The version 6 counterpart to #new_v7_batch_bytes, with the same rationale and
+  # the same guidance about when it is the right call.
+  #
+  # clock_seq and node are independently random per item; unlike version 7 there is no
+  # monotonic counter, so items minted in the same millisecond are not guaranteed to sort in
+  # creation order.
+  #
+  # @raise [TypeError, ArgumentError] if +count+ isn't an Integer between 0 and 2**32 - 1.
+  # @raise [TimestampOutOfRangeError] if the time is negative or past the 60-bit v6 field.
+  def self.new_v6_batch_bytes(count, unix_millis = nil)
+    count = batch_count(count)
+    Runtime.new_v6_batch(count, unix_millis_from(unix_millis, Runtime::V6_TIMESTAMP_OUT_OF_RANGE))
+  end
+
+  # The version of the native core actually loaded, as "major.minor.patch" — read from the
+  # library itself (its `hyperuuid_version` export), not from this gem, so a consumer can
+  # prove the core behind the doors is the one this binding was built against (and name the
+  # mismatch against HyperUuid::VERSION when it is not). The cheapest possible probe that the
+  # backend resolved at all: takes nothing, mints nothing, cannot fail once the backend loads.
+  #
+  # @raise [LoadError] if no backend could be loaded for this platform.
+  def self.native_version
+    word = Runtime.packed_version
+    "#{word >> 16}.#{(word >> 8) & 0xFF}.#{word & 0xFF}"
+  end
+
+  # Whether a backend actually loaded and exports the ABI this binding was built against —
+  # what a consumer with a fallback of its own (SecureRandom.uuid, say) checks before
+  # committing to these doors. Probed once (a native_version round trip), cached, and never
+  # raises: a missing shared library, an unsupported platform, or an older core without the
+  # version export all answer false. The doors themselves keep their own behavior — the
+  # first call on an unavailable backend raises its precise error — this only answers the
+  # question quietly.
+  def self.available?
+    return @available unless @available.nil?
+
+    @available = begin
+      native_version.is_a?(String)
+    rescue LoadError, StandardError
+      false
+    end
+  end
+end
+
+# --- backend selection: the Magnus extension, when present, replaces the Runtime methods
+# above in place (no delegation layer) — Fiddle's measured per-call marshalling floor drops
+# to an ordinary extension call, while everything above Runtime (Uuid, the module doors,
+# batch slicing) stays shared byte-for-byte between backends. The pure-Fiddle definitions
+# remain the universal zero-compile fallback — the last resort, for a Ruby or a platform no
+# platform gem covers; precompiled platform gems are how the extension ships without ever
+# making a consumer compile anything, and they carry no Fiddle library at all.
+#
+# HYPERUUID_PURE forces Fiddle. It is a testing and diagnostic switch — CI runs the whole suite
+# through it, and it is how a suspected extension bug is ruled in or out — not a setting a
+# deployment needs. It is read for presence, not value, so "0" and the empty string force it
+# too. Inside a platform gem there is no library for it to load: BACKEND still reads :fiddle,
+# HyperUuid.available? answers false, and the first door call raises a LoadError naming the
+# universal gem, which is where the Fiddle backend lives.
+HyperUuid::BACKEND =
+  if ENV["HYPERUUID_PURE"]
+    :fiddle
+  else
+    # Two layouts, and both have to work. A released platform gem is a "fat" gem carrying one
+    # extension per supported Ruby ABI under lib/hyperuuid/<minor>/ (see the Rakefile's
+    # native:gem task for why an ABI-per-file is unavoidable — Magnus has no `abi3`
+    # equivalent), and `rake native:dev` — the local dev loop — stages its own build at that
+    # same versioned path. CI's in-job staging additionally drops a single extension flat at
+    # lib/, which is also where a hand copy of `cargo ruby-ext`'s output goes (the alias only
+    # builds into rust/target/ruby/release/; nothing but that rake task copies it here).
+    # Trying the versioned path first and the flat one second means neither has to know the
+    # other exists.
+    #
+    # A miss on both is not an error: it means this Ruby/platform combination has no
+    # precompiled extension, which is precisely what the Fiddle backend below is for. A
+    # platform with no shared library either still lands on Fiddle, so the first call raises
+    # its own precise error — a "not found" LoadError naming the path, or
+    # NativePlatform::UnsupportedPlatformError naming the platform. HyperUuid.available? is
+    # the quiet way to ask.
+    begin
+      require "hyperuuid/#{RUBY_VERSION[/\d+\.\d+/]}/hyperuuid_native"
+      :native
+    rescue LoadError
+      begin
+        require "hyperuuid_native"
+        :native
+      rescue LoadError
+        :fiddle
+      end
+    end
+  end

metadata

@@ -0,0 +1,103 @@
+--- !ruby/object:Gem::Specification
+name: hyperuuid
+version: !ruby/object:Gem::Version
+  version: 0.6.0
+platform: aarch64-linux-musl
+authors:
+- Brian Buvinghausen
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: fiddle
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+description: |
+  RFC 9562 UUID v4 (random), v5 (deterministic), v6 and v7 (time-sortable) generation, with
+  batch and raw-bytes forms, from one native Rust core. Two backends behind one surface,
+  selected automatically and both shipped prebuilt: a Magnus extension where a precompiled
+  platform gem matches, and stdlib Fiddle everywhere else. No runtime bridge, no
+  dependencies beyond Fiddle.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/hyperuuid.rb
+- lib/hyperuuid/3.4/hyperuuid_native.so
+- lib/hyperuuid/4.0/hyperuuid_native.so
+- lib/hyperuuid/errors.rb
+- lib/hyperuuid/namespaces.rb
+- lib/hyperuuid/native_platform.rb
+- lib/hyperuuid/runtime.rb
+- lib/hyperuuid/uuid.rb
+homepage: https://github.com/SkunkWerkx/HyperUuid
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/SkunkWerkx/HyperUuid
+  changelog_uri: https://github.com/SkunkWerkx/HyperUuid/blob/master/CHANGELOG.md
+  bug_tracker_uri: https://github.com/SkunkWerkx/HyperUuid/issues
+  documentation_uri: https://github.com/SkunkWerkx/HyperUuid/tree/master/ruby#readme
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.4'
+  - - "<"
+    - !ruby/object:Gem::Version
+      version: '4.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.20
+specification_version: 4
+summary: RFC 9562 UUID v4/v5/v6/v7 generation over a native Rust core, shipped prebuilt
+test_files: []