hyperuuid 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d2b7cb6d510ac9faccd193dde27916dc8bd7384b6b9c1d387dfc47682eeb9274
+  data.tar.gz: f4d3082562a32328b0519b6f2c0b461d8fb3303d731fca8b1b96422266f97e4c
+SHA512:
+  metadata.gz: 1d80438fc78ff61048568c3ff70fff7bc6493ba639ac60299c21495b863419fc49f5e61f38bdfaf1b9be9910930da9124deaf98254bc119d9ec0d8f11b6cf1fc
+  data.tar.gz: beed906a491217aef07a6d3ce2ac36f77410710c7379ae1cffa0733cdb3c33c2eb1deeecd24fac7d32f96160068b512b6d5984fbd5aa7508e6fa23590e950169

data/README.md

@@ -0,0 +1,99 @@
+# 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.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.
+`#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.
+
+## 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
+
+Not yet published to RubyGems.org under a registered `SkunkWerkx`/`buvinghausen` presence —
+for now this is proven by CI building and testing the native core plus this gem on real
+hardware for every platform leg. Consume via a direct
+`gem "hyperuuid", git: "https://github.com/SkunkWerkx/HyperUuid", glob: "ruby/*.gemspec"` in
+the meantime.
+
+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 ctypes-only stance.
+  #
+  # 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,153 @@
+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 stdlib-ctypes-only one.
+  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.
+    def timestamp
+      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}"
+        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,89 @@
+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.1.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
+
+  # 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
+  # Unix-epoch millisecond timestamp 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)
+    unix_millis ||= Process.clock_gettime(Process::CLOCK_REALTIME, :millisecond)
+    Uuid.new(Runtime.new_v6(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.
+  def self.new_v6_batch(count, unix_millis = nil)
+    unix_millis ||= Process.clock_gettime(Process::CLOCK_REALTIME, :millisecond)
+    bytes = Runtime.new_v6_batch(count, 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 Unix-epoch millisecond timestamp (non-negative, fitting in 48 bits) to embed a
+  # specific time instead.
+  def self.new_v7(unix_millis = nil)
+    unix_millis ||= Process.clock_gettime(Process::CLOCK_REALTIME, :millisecond)
+    Uuid.new(Runtime.new_v7(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.
+  def self.new_v7_batch(count, unix_millis = nil)
+    unix_millis ||= Process.clock_gettime(Process::CLOCK_REALTIME, :millisecond)
+    bytes = Runtime.new_v7_batch(count, unix_millis)
+    Array.new(count) { |i| Uuid.new(bytes[i * 16, 16]) }
+  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
+    begin
+      require "hyperuuid_native"
+      :native
+    rescue LoadError
+      :fiddle
+    end
+  end

metadata

@@ -0,0 +1,112 @@
+--- !ruby/object:Gem::Specification
+name: hyperuuid
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+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:
+- README.md
+- lib/hyperuuid.rb
+- 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.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: RFC 9562 UUID v4/v5/v6/v7 generation — direct native FFI into a Rust core,
+  no runtime bridge.
+test_files: []