hyperuuid 0.2.0-x64-mingw-ucrt

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8601b6074d2d6bbde0afeba53e5719d525522d43aab82291b9944c786f46d588
+  data.tar.gz: a8a66899d0566baf69e3a7fa7c889b532eebecb9a7d065f122495d53e2e1860b
+SHA512:
+  metadata.gz: 7d0d4f031d24a3d9e972d034c58de8a4334353b46c64b811854cf49af3d85cb3d0e1af1e476f3d914dc5844050cc40a4c6b616092cda7563b566d53ab8137620
+  data.tar.gz: 3a092005c188968cae23093c1e03346e3f5297678363e0c9cccfebfad8a56aae31a0739c0eaf288016c45715502d5211c4c7348cf76f329fcfbe72a8aad36041

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,185 @@
+# 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)
+
+**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. 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, batch slicing) is shared
+byte-for-byte between backends. The universal fallback 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, nothing to compile on
+`bundle install`. Set `HYPERUUID_PURE=1` to force the Fiddle backend;
+`HyperUuid::BACKEND` reports which one is live. Bundles a native build for every supported
+platform (linux/darwin/windows × x64/arm64) and picks the right one at runtime.
+
+```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)
+```
+
+Returns `HyperUuid::Uuid`, a minimal value object (`#bytes`, `#to_s`, `#version`, `#variant`,
+comparable/hashable) — this gem has no runtime dependency on the `uuid` gem.
+`HyperUuid::Namespaces::DNS`/`URL`/`OID`/`X500` are RFC 9562 Section 6.6's well-known
+namespaces. `#timestamp` recovers the embedded UTC `Time` from a version 6 or 7 UUID; pass
+`raise_on_mismatch: false` to get `nil` back for any other version instead of raising.
+`.new_v6`/`.new_v7` also accept a `Time` directly in place of a raw millisecond count.
+`#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).
+`HyperUuid::Uuid::NIL`/`MAX` are the RFC 9562 §5.9/§5.10 special-value UUIDs.
+`HyperUuid.new_v6_batch(count)`/`new_v7_batch(count)` generate `count` UUIDs sharing one
+timestamp capture and one native call, instead of `count` of each.
+
+## 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, nothing to compile on `bundle install`.
+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 `dlopen`s a native library instead of being pure Ruby, so it needs a platform-specific `libhyperuuid.so`/`.dylib`/`.dll` bundled alongside it. 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 15x faster than `new_v7_batch`** for a 1000-UUID batch (24 µs versus 370 µs). The native call is identical — the difference is that `new_v7_batch` then allocates 1000 `Uuid` objects and 1000 String slices 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
+
+Real numbers, `benchmark-ips` on Ruby 4.0.6, linux-arm64 (`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` | 775,868 | baseline |
+| `HyperUuid.new_v7` (explicit ms) | 2,275,763 | **2.9x faster** |
+| `HyperUuid.new_v6` (explicit ms) | 2,197,698 | **2.8x faster** |
+| `HyperUuid.new_v4` | 2,176,244 | **2.8x faster** |
+| `HyperUuid.new_v5` | 1,458,385 | 1.9x faster |
+| `HyperUuid.new_v7` (current time) | 701,373 | parity (1.1x slower) |
+| `HyperUuid.new_v6` (current time) | 703,748 | parity (1.1x slower) |
+
+An earlier edition of this section said single-item calls "lose to `SecureRandom.uuid`, full stop" and called the gap "structural, not a bug to fix — no amount of tuning closes that gap." That was wrong, and the receipts above are the correction: the gap was `Fiddle`'s per-call marshalling, and replacing the mechanism (the same play as this repo's Python PyO3 backend) closed it with room to spare. A `HyperUuid.new_v4` — real entropy, correct version/variant bits, minted by the shared Rust core — now costs a third of what `SecureRandom.uuid` does.
+
+The two "current time" rows deserve their honest footnote: the explicit-ms rows isolate the binding's own cost (~440-460ns), and the difference is one `Process.clock_gettime(CLOCK_REALTIME)` wall-clock read — which this WSL2 measurement box prices at ~1µs because its Hyper-V clock defeats the vDSO fast path (verified: `CLOCK_REALTIME_COARSE` costs 102ns on the same box). On bare-metal Linux that read is tens of nanoseconds, and the default-time rows land next to the explicit-ms ones. `SecureRandom.uuid` never reads a clock — random v4 is the only thing it does.
+
+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.27x slower than `SecureRandom.uuid` for v4 (was 1.30x before the diet, from a worse baseline run) 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) | 731.3 |
+| `new_v6_batch(1000)` | 2,655.6 (**3.6x**) |
+| `new_v7` × 1000 (individual) | 710.0 |
+| `new_v7_batch(1000)` | 2,744.3 (**3.9x**) |
+
+The batch multiplier shrank from 11x to ~3.8x for the best reason available: the individual calls got 3x faster, so there's less waste left to amortize. 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.
+
+## Install
+
+```sh
+gem install hyperuuid
+```
+
+Published to [RubyGems.org](https://rubygems.org/gems/hyperuuid) as real precompiled
+"platform gems" — `bundle`/`gem install` auto-selects the matching one for
+linux-x64/arm64, osx-x64/arm64, x64-mingw-ucrt or aarch64-mingw-ucrt (the compiled Magnus
+native extension, `backend: :native`), falling back automatically to the universal
+`ruby`-platform gem (pure Fiddle, zero compile, bundles all 6 platforms' native libs)
+everywhere else. 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-x64/arm64, osx-x64/arm64, x64-mingw-ucrt, aarch64-mingw-ucrt | anywhere else (musl/Alpine, …) |
+| --- | --- | --- |
+| 4.0 (primary) | Magnus, `backend: :native` | Fiddle |
+| 3.4 (floor, until its EOL 2028-03-31) | Magnus, `backend: :native` | Fiddle |
+| 3.2 / 3.3 | Fiddle | Fiddle |
+
+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.
+
+An earlier edition of this section said the fallback covered "Windows included, since Magnus
+doesn't target it." That was wrong in both halves. MinGW is the *only* Windows flavour
+`rb-sys` targets — its own `data/toolchains.json` maps `x64-mingw-ucrt` to the
+`x86_64-pc-windows-gnu` Rust target, `supported: true`; the target it has no support for is
+`x86_64-pc-windows-msvc`. And Windows is where the Fiddle fallback cost 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.
+
+Windows-on-ARM is no longer the exception it was. `rb-sys` maps `aarch64-mingw-ucrt` to the
+`aarch64-pc-windows-gnullvm` Rust target (`supported: true`), and RubyInstaller ships an
+`aarch64-mingw-ucrt` build of both ABIs in the table above, so win-arm64 now gets the same fat
+platform gem as every other leg. Measured on real Windows-on-ARM hardware, Ruby 4.0.6, the
+Magnus backend does `new_v4` in 416ns against Fiddle's 2299ns (**5.5x**) and `new_v7` in 621ns
+against 2474ns (**4.0x**) — the same shape the x64 leg shows.
+
+What differs from the x64 build follows from `gnullvm` being LLVM-based where
+`x86_64-pc-windows-gnu` is GCC-based. The linker driver is `aarch64-w64-mingw32-clang` from
+MSYS2's CLANGARM64 environment — RubyInstaller's own ARM devkit installs it locally, and
+`ruby/setup-ruby` installs it on `windows-11-arm` — so there is no `link-self-contained=no`
+dance. Two flags are load-bearing:
+
+- **`-l static=unwind`.** rustc emits its `-lunwind` in the linker's *dynamic* section, where
+  CLANGARM64 offers both `libunwind.a` and `libunwind.dll.a` and lld prefers the latter. Left
+  alone, the extension acquires a runtime dependency on `libunwind.dll` — a file no consumer
+  of the gem would have.
+- **`BINDGEN_EXTRA_CLANG_ARGS=--target=aarch64-w64-mingw32`.** bindgen hands clang the *Rust*
+  target triple when cargo cross-compiles, and clang rejects `aarch64-pc-windows-gnullvm`
+  outright (`version 'llvm' in target triple ... is invalid`), then fails behind that on a
+  missing `stdalign.h` it never reached its own resource dir to find. `aarch64-w64-mingw32`
+  is the same ABI spelled the way clang accepts, exactly as x64 spells its gnu target
+  `x86_64-w64-mingw32`.
+
+That second one was briefly documented here as *unnecessary*, on the strength of a local
+build where it genuinely was: that build used a `gnullvm` **host** toolchain, so host equals
+target, cargo was not cross-compiling, and bindgen injected no `--target` at all. CI's host is
+MSVC, so it does. A local build says nothing about that step unless its host triple matches
+the runner's.
+
+See [the repo root README](../README.md) for the full RFC 9562 coverage table and the state of every other language binding.

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/README.md

@@ -0,0 +1,6 @@
+# native/
+
+Populated per-RID with the platform's native `libhyperuuid` build (`native/{rid}/{lib}`) by CI
+and by `cargo build --release` for local dev — see `../../../.gitignore`. This file exists so
+the directory has at least one tracked file on a fresh checkout, matching the Go/Swift
+bindings' `native/`/`NativeLibs/` placeholder convention.

data/lib/hyperuuid/native_platform.rb

@@ -0,0 +1,22 @@
+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
+
+    def self.rid_and_library_name
+      is_arm = RUBY_PLATFORM.match?(/arm64|aarch64/)
+
+      case RUBY_PLATFORM
+      when /mingw|mswin|windows/
+        is_arm ? ["win-arm64", "hyperuuid.dll"] : ["win-x64", "hyperuuid.dll"]
+      when /darwin/
+        is_arm ? ["osx-arm64", "libhyperuuid.dylib"] : ["osx-x64", "libhyperuuid.dylib"]
+      when /linux/
+        is_arm ? ["linux-arm64", "libhyperuuid.so"] : ["linux-x64", "libhyperuuid.so"]
+      else
+        raise UnsupportedPlatformError, "hyperuuid: unsupported platform RUBY_PLATFORM=#{RUBY_PLATFORM}"
+      end
+    end
+  end
+end

data/lib/hyperuuid/runtime.rb

@@ -0,0 +1,204 @@
+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 Go/Swift bindings'
+  # purego/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 Go's
+  # "no cgo" and Python's zero-dependency PyO3 wheels.
+  #
+  # Unlike the Go/Swift bindings, which embed their native builds inside a single compiled
+  # archive and must extract to a temp file before dlopen can see a real path, a Ruby gem's
+  # files are already plain files on disk once installed — native/{rid}/{lib} can be
+  # dlopen'd directly, no extraction step needed.
+  module Runtime
+    class RandomSourceError < StandardError; end
+    class TimestampOutOfRangeError < StandardError; end
+
+    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 RandomSourceError, "uuid_new_v4 failed with code #{rc}" unless rc.zero?
+        out[0, 16]
+      end
+
+      def new_v5(namespace_bytes, name_bytes)
+        out = scratch
+        # Fiddle passes a String's bytes for void* directly (read-only) — no Pointer
+        # wrapper, no copy — the same zero-copy crossing every other input here uses.
+        name = name_bytes.empty? ? nil : name_bytes
+        rc = functions[:new_v5].call(namespace_bytes, name, name_bytes.bytesize, out)
+        raise RandomSourceError, "uuid_new_v5 failed with code #{rc}" 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, "unix_millis does not fit the 60-bit v6 timestamp field"
+        else raise RandomSourceError, "uuid_new_v6 failed with code #{rc}"
+        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, "unix_millis does not fit the 60-bit v6 timestamp field"
+        else raise RandomSourceError, "uuid_new_v6_batch failed with code #{rc}"
+        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, "unix_millis must fit within the RFC 9562 48-bit field"
+        else raise RandomSourceError, "uuid_new_v7 failed with code #{rc}"
+        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, "unix_millis must fit within the RFC 9562 48-bit field"
+        else raise RandomSourceError, "uuid_new_v7_batch failed with code #{rc}"
+        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
+
+      private
+
+      # 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 the Go binding's sync.Once / 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
+        rid, lib_name = NativePlatform.rid_and_library_name
+        path = File.join(NATIVE_DIR, rid, lib_name)
+        unless File.exist?(path)
+          raise LoadError,
+                "hyperuuid: #{path} not found (unsupported platform, or this gem was built without a native library for it)"
+        end
+
+        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
+          ),
+        }
+      end
+    end
+  end
+end

data/lib/hyperuuid/uuid.rb

@@ -0,0 +1,160 @@
+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 purego-only/no-cgo approach 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.
+    #
+    # @raise [ArgumentError] if +bytes+ isn't exactly 16 bytes.
+    def initialize(bytes)
+      raise ArgumentError, "bytes must be exactly 16 bytes" unless bytes.bytesize == 16
+      @bytes = bytes.dup.force_encoding(Encoding::BINARY).freeze
+    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
+
+    # Parses an 8-4-4-4-12 hyphenated hex UUID string.
+    #
+    # @raise [ArgumentError] if +string+ isn't a valid UUID string.
+    def self.parse(string)
+      hex = string.delete("-")
+      raise ArgumentError, "invalid UUID string: #{string.inspect}" unless hex.match?(/\A[0-9a-fA-F]{32}\z/)
+      new([hex].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))
+      when 6 then self.class.new(Runtime.v6_to_sql_order(bytes))
+      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))
+      elsif octet7_version == 7
+        self.class.new(Runtime.v7_to_rfc_order(bytes))
+      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,142 @@
+require "time"
+
+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, calling
+# directly into the native libhyperuuid shared library via Fiddle — no runtime bridge, no
+# extra gem dependency. Bundles a native build for every supported platform (see
+# HyperUuid::NativePlatform) and picks the right one at runtime, the same trick the Go/
+# Java bindings use since RubyGems has no per-platform native selection wired up here.
+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.2.0"
+
+  # Creates a random UUID version 4 (RFC 9562 §5.4).
+  def self.new_v4
+    Uuid.new(Runtime.new_v4)
+  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.
+  def self.new_v5(namespace, name)
+    name_bytes =
+      if name.encoding == Encoding::ASCII_8BIT
+        name
+      else
+        name.encode(Encoding::UTF_8).dup.force_encoding(Encoding::BINARY)
+      end
+    Uuid.new(Runtime.new_v5(namespace.bytes, name_bytes))
+  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
+  # anything else (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.
+  private_class_method def self.unix_millis_from(value)
+    case value
+    when nil then Process.clock_gettime(Process::CLOCK_REALTIME, :millisecond)
+    when Time then (value.to_r * 1000).to_i
+    else value
+    end
+  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.
+  def self.new_v6(unix_millis = nil)
+    Uuid.new(Runtime.new_v6(unix_millis_from(unix_millis)))
+  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.
+  def self.new_v6_batch(count, unix_millis = nil)
+    bytes = Runtime.new_v6_batch(count, unix_millis_from(unix_millis))
+    Array.new(count) { |i| Uuid.new(bytes[i * 16, 16]) }
+  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.
+  def self.new_v7(unix_millis = nil)
+    Uuid.new(Runtime.new_v7(unix_millis_from(unix_millis)))
+  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.
+  def self.new_v7_batch(count, unix_millis = nil)
+    bytes = Runtime.new_v7_batch(count, unix_millis_from(unix_millis))
+    Array.new(count) { |i| Uuid.new(bytes[i * 16, 16]) }
+  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.
+  #
+  # Roughly 11x faster than #new_v7_batch for a 1000-UUID batch (about 35 us versus 400 us).
+  # The difference is not the native call — that is identical — it is that #new_v7_batch then
+  # allocates `count` Uuid objects and `count` String slices 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.
+  def self.new_v7_batch_bytes(count, unix_millis = nil)
+    Runtime.new_v7_batch(count, unix_millis_from(unix_millis))
+  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.
+  def self.new_v6_batch_bytes(count, unix_millis = nil)
+    Runtime.new_v6_batch(count, unix_millis_from(unix_millis))
+  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; precompiled platform gems are how the
+# extension ships without ever making a consumer compile anything. Set HYPERUUID_PURE=1 to
+# force Fiddle.
+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). CI's in-job staging and a local `cargo build --release --features ruby`
+    # instead drop a single extension flat at lib/. 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.
+    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,118 @@
+--- !ruby/object:Gem::Specification
+name: hyperuuid
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: x64-mingw-ucrt
+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: benchmark-ips
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.15'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.15'
+- !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: |
+  High-performance, allocation-free RFC 9562 UUID v4 (random), v5 (deterministic), v6 and v7
+  (time-sortable) generation, calling directly into the native libhyperuuid shared library
+  via Fiddle (Ruby's standard-library FFI) — no runtime bridge, no extra gem dependency.
+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/namespaces.rb
+- lib/hyperuuid/native/README.md
+- lib/hyperuuid/native/linux-arm64/libhyperuuid.so
+- lib/hyperuuid/native/linux-x64/libhyperuuid.so
+- lib/hyperuuid/native/osx-arm64/libhyperuuid.dylib
+- lib/hyperuuid/native/osx-x64/libhyperuuid.dylib
+- lib/hyperuuid/native/win-arm64/hyperuuid.dll
+- lib/hyperuuid/native/win-x64/hyperuuid.dll
+- 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
+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.16
+specification_version: 4
+summary: RFC 9562 UUID v4/v5/v6/v7 generation — direct native FFI into a Rust core,
+  no runtime bridge.
+test_files: []