hyperuuid-wasm 0.7.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a4acc2b5b222f7604e7b21efe1c5f958e7279a470f546bed3ad00089f033f13f
-  data.tar.gz: 0c9349c620020edf44cf37afbfff39480d49497ade4e63c94e9549e028ce2abb
+  metadata.gz: 8b35d26b737a64df74f7a10783112899a0386bbd7dd7b7aa6387b4cbd5fb3c09
+  data.tar.gz: c37cd5f4d1bc6ad5eef8d181aa263ac61212c73f4f73640724f63e53a9797f61
 SHA512:
-  metadata.gz: c9f72f6b99806013e5c6557189c15f542ab1a4328528b07a2992770c01d4008111e1591b36cc00f567cdd6a919d89e6e81e7fd4bad8886bcfdcef10f7b1328c9
-  data.tar.gz: 6d6d7e0f7eecd6d4e62d6af9803090be5b76f90f3ee1d59534d409c92f5ee95b14d4c829af820485d3668108fbe2b500f0dc7385865de00f3a1315e225e22417
+  metadata.gz: 1580f8edd7863896d8b646db61e5918aa7efcaa22db88995e2c6aa2d4456f8dd2698e1200e214191830b984aee8fcdd56f22f5da51985a48305401bf10b84201
+  data.tar.gz: e5a86147bafa4f1e9bfb266656e073f135286f07750dbb930cf6a8b10e9a3b45060e5a8daf73cd6c7162ee060a75f3e4f02c3a609c63fc8b94bbb26a0a46c653

data/README.md

@@ -4,10 +4,10 @@
 [![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.**
+**Ruby's own stdlib stops at `SecureRandom.uuid` and `SecureRandom.uuid_v7` — random v4 and v7, one at a time. No v5, no batches, no timestamp read-back, no SQL Server order. This gem fills that in, 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
+RFC 9562 UUID v4 (random), v5 (deterministic) and v7 (time-sortable) generation, with a
+version 8 SQL Server order for v7 and 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
@@ -22,12 +22,13 @@ require "hyperuuid"
 
 id = HyperUuid.new_v4
 id2 = HyperUuid.new_v5(HyperUuid::Namespaces::DNS, "example.com")
-id3 = HyperUuid.new_v6
-id4 = HyperUuid.new_v7
+id3 = 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
+id3.timestamp # recover the embedded UTC Time
+id3.timestamp(raise_on_mismatch: false) # nil instead of raising if id3 isn't an RFC 9562 v7
+id3.rfc?(7) # the RFC 9562 variant and version 7, the guard before trusting its fields
+sql = id3.to_sql_order # a version 8 laid out so SQL Server's uniqueidentifier sorts by creation order
+sql.timestamp(layout: :sql_server) # read straight from SQL order, no round trip
 
 # One native call, one random-bytes fetch, one counter reservation for the whole batch:
 batch = HyperUuid.new_v7_batch(1000)
@@ -39,9 +40,9 @@ batch = HyperUuid.new_v7_batch(1000)
 |---|---|---|
 | `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) |
+| `new_v7(time = nil)` | `Uuid` | nothing (now), a `Time`, or an Integer of Unix-epoch milliseconds |
+| `new_v7_batch(count, time = nil)` | `Array` of `Uuid` | a count (at most `MAX_V7_BATCH`), and the same time forms |
+| `new_v7_batch_bytes(count, time = nil)` | one binary `String`, 16 bytes per UUID | as `new_v7_batch` — see [Bulk generation into bytes](#bulk-generation-into-bytes) |
 | `native_version` | the loaded core's `"major.minor.patch"` | — |
 | `available?` | `true`/`false`, never raising | — |
 
@@ -53,29 +54,94 @@ runtime dependency on the `uuid` gem:
 | `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 |
+| `#bytes` `#to_s` | the frozen binary String, the hyphenated text |
+| `#version(layout: :rfc9562)` | the version in that layout: the nibble, 0-15, in RFC order; in `:sql_server`, 7, the version a SQL-ordered value was converted from, and 0 when the bytes aren't one |
+| `#variant` | the RFC 9562 §4.1 variant, as a Symbol: `:rfc9562` (every UUID this gem mints, and the only variant with versions), `:ncs` (Nil among them), `:microsoft`, `:future` (Max among them) |
+| `#rfc?(version, layout: :rfc9562)` | whether it is an RFC 9562 UUID of that version: the variant and the version together. A version outside 0-15 is `false` |
+| `#timestamp(raise_on_mismatch: true, layout: :rfc9562)` | the UTC `Time` embedded in an RFC 9562 version 7 UUID held in that layout, in one native call that checks the variant as well as the version (a 7 nibble under another variant has no timestamp, and nor does a v1 or v6 minted elsewhere); `nil` instead of an `ArgumentError` for anything that isn't one when passed `false` |
+| `#to_sql_order` `#from_sql_order` | to and from the layout SQL Server's `uniqueidentifier` sorts by, refusing what doesn't fit it |
 | `==` `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).
+`#to_sql_order`/`#from_sql_order` convert a version 7 UUID to and from the layout SQL Server's
+`uniqueidentifier` needs on the wire to sort by creation order — 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). The converted
+value is an RFC 9562 version 8: the 8 and the RFC variant sit where SQL Server's text form and
+a .NET `Guid` show them, and the v7's 122 other bits (timestamp, counter, random) fill the rest
+in the order SQL Server compares them. Every v7 converts, and the conversion back is exact.
+Either direction refuses a value of the wrong kind with an `ArgumentError`: anything that isn't
+an RFC 9562 v7 for `#to_sql_order`, anything without the layout's 8 and variant for
+`#from_sql_order`.
+
+### Layouts
+
+`#version`, `#rfc?` and `#timestamp` take the byte order the value is held in as `layout:`, a
+Symbol: `:rfc9562` (the default, what every other method takes and returns) or `:sql_server`
+(what `#to_sql_order` returns, a version 8 holding a converted v7). `Uuid::LAYOUTS` lists them.
+Anything else is an `ArgumentError`, never a guess. With the default, `#version` and `#rfc?`
+read the value as RFC 9562 order, which looks at the wrong bytes of a SQL-ordered value (one
+from `#to_sql_order`, or a `uniqueidentifier` read back from SQL Server), so pass
+`layout: :sql_server` at every call site that can see one. There is deliberately no
+layout-agnostic check: whoever holds the value knows its order.
+
+`#variant` reads RFC 9562 order only and has no layout form. The SQL Server layout keeps the
+variant in the same place, so a SQL-ordered value reads `:rfc9562` there, but that says nothing
+about whether it holds a converted v7; to validate one, or a `uniqueidentifier` read-back,
+`#rfc?(7, layout: :sql_server)` checks the layout's 8 and variant.
+
+```ruby
+sql = HyperUuid.new_v7.to_sql_order
+sql.version(layout: :sql_server)   # => 7
+sql.rfc?(7, layout: :sql_server)   # => true
+sql.timestamp(layout: :sql_server) # the same Time as sql.from_sql_order.timestamp
+```
+
+The bytes alone cannot say which order they are in, so the layout is yours to know: an
+RFC-ordered value can happen to carry the layout's 8 and variant (a random v4 does one time in
+16), and `#from_sql_order` then converts it rather than refusing it. The same goes the other
+way: a value already in SQL order carries a 7 where `#to_sql_order` looks for the version about
+one time in 16, and is then converted a second time rather than refused.
+
+### Binding to SQL Server
+
+Send `#to_sql_order`'s result as its raw `#bytes`, not as UUID text. SQL Server stores a UUID
+string's first three groups byte-reversed, which loses the creation order
+([details](https://github.com/SkunkWerkx/HyperUuid#sql-server-ordering)); tiny_tds 3.4 and an ActiveRecord `:uuid` attribute both send text. A binary
+literal lands byte for byte:
+
+```ruby
+sql = HyperUuid.new_v7.to_sql_order
+client.execute("INSERT INTO orders (id) VALUES (0x#{sql.bytes.unpack1('H*')})").do
+
+row = client.execute("SELECT CAST(id AS binary(16)) AS id FROM orders").first
+sql = HyperUuid::Uuid.new(row["id"])  # read with layout: :sql_server
+```
+
+In ActiveRecord, map the column as `:binary`, which quotes as `0x…`. Reading needs the `CAST`
+too: tiny_tds returns a `uniqueidentifier` as text with those groups reversed.
+
+### The version 7 batch limit
+
+`HyperUuid::MAX_V7_BATCH` is 67,108,864 (2²⁶), the size of the counter that orders version 7
+UUIDs within a millisecond, and the most one `new_v7_batch` or `new_v7_batch_bytes` call
+mints. A larger count is an `ArgumentError` naming the limit, raised before anything is
+allocated. Every batch is in strictly increasing order: the counter is one process-wide
+sequence, so a batch can straddle the point where it wraps back to 0, and the UUIDs from there
+on carry a timestamp one millisecond later than the one supplied rather than sorting before the
+ones ahead of them.
+
+That roll-forward orders one batch, not the stream. The next batch or single `new_v7` in the
+same real millisecond starts its counter just past the wrap and carries the supplied timestamp,
+so it sorts before the previous batch's tail, which was stamped a millisecond later. Two single
+`new_v7` calls either side of the wrap in one millisecond sort in reverse the same way. It
+happens at most once per 2²⁶ UUIDs the process mints.
 
 ### 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::TimestampOutOfRangeError` — the time cannot be embedded in a version 7: past
+  its 48-bit millisecond field, 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
@@ -84,8 +150,11 @@ Through 0.3.0 these were reachable only as `HyperUuid::Runtime::TimestampOutOfRa
 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.
+`Uuid` or a name that is not a `String`, for a version passed to `#rfc?` that is not an
+Integer; an `ArgumentError` for a count outside 0..`MAX_V7_BATCH`, for a layout other than
+`:rfc9562`/`:sql_server`, and for a batch too large for the platform to address (a 32-bit
+target such as ruby.wasm). The SQL Server conversions' one refusal (a value of the wrong
+version) comes from the core, as an `ArgumentError` worded the same on both backends.
 
 ### Is the native core there?
 
@@ -93,6 +162,8 @@ doors rather than left to whichever backend is live: a `TypeError` for a time th
 raising — for a consumer with a fallback of its own:
 
 ```ruby
+require "securerandom"
+
 id = HyperUuid.available? ? HyperUuid.new_v7.to_s : SecureRandom.uuid
 ```
 
@@ -105,18 +176,18 @@ looked for, or `HyperUuid::NativePlatform::UnsupportedPlatformError` naming the
 
 ## 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":
+`SecureRandom.uuid` gives you a random v4 UUID and `SecureRandom.uuid_v7` a v7 (Ruby 3.3 and later, so every Ruby this gem supports). Ruby's stdlib has no v5, nothing to read a timestamp back out, no batch form, and no SQL Server ordering. 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 nothing added to your `Gemfile.lock` beyond `Fiddle` — Ruby's own bundled FFI layer, not a third-party C extension to compile — and on the precompiled platform gems not even that.
+1. **The RFC 9562 versions new systems use, one gem, zero extra dependency.** v4/v5/v7 plus batch generation plus `Nil`/`Max`, and nothing added to your `Gemfile.lock` beyond `Fiddle` — Ruby's own bundled FFI layer, not a third-party C extension to compile — and on the precompiled platform gems not even that.
 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.
+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 one v4 or v7 at a time is all you need, `SecureRandom.uuid` and `SecureRandom.uuid_v7` are 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:
+`new_v7_batch_bytes` returns 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)
@@ -141,9 +212,7 @@ Real numbers, `benchmark-ips` on Ruby 4.0.7, linux-x64 on an Intel Core i9-11900
 |---|---:|---:|
 | `SecureRandom.uuid` | 943,917 | baseline |
 | `HyperUuid.new_v4` | 5,236,000 | **5.5x faster** |
-| `HyperUuid.new_v6` (explicit ms) | 3,811,000 | **4.0x faster** |
 | `HyperUuid.new_v7` (explicit ms) | 3,785,000 | **4.0x faster** |
-| `HyperUuid.new_v6` (current time) | 3,677,000 | **3.9x faster** |
 | `HyperUuid.new_v7` (current time) | 3,574,000 | **3.8x faster** |
 | `HyperUuid.new_v5` | 1,942,000 | 2.1x faster |
 
@@ -151,18 +220,16 @@ A `HyperUuid.new_v4` — real entropy, correct version/variant bits, minted by t
 
 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.16x slower than `SecureRandom.uuid` for v4 (1.24 µs against 1.07 µs in its own run) and about 1.3x 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.
+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.16x slower than `SecureRandom.uuid` for v4 (1.24 µs against 1.07 µs in its own run) and about 1.3x slower for 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,761 |
-| `new_v6_batch(1000)` | 4,857 (**1.3x**) |
 | `new_v7` × 1000 (individual) | 3,742 |
 | `new_v7_batch(1000)` | 4,850 (**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 206 µs on is building a thousand `Uuid` objects — the byte form above does the same native work in 5 µ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.
+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 206 µs on is building a thousand `Uuid` objects — the byte form above does the same native work in 5 µs. On the Fiddle backend, where each call costs 1.4 µs, the same batch is 6.7x the loop. If you need v5/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
 
@@ -248,8 +315,7 @@ one at `require` time:
 | 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
+What stands behind each cell: CI runs the whole suite through each Magnus extension — Ruby 4.0 on every pull request and Ruby 3.4 in the weekly and release builds, 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
@@ -326,7 +392,7 @@ bundle exec rbwasm build --ruby-version 4.0 -o ruby.wasm
 Load `ruby.wasm` with [`@ruby/wasm-wasi`](https://www.npmjs.com/package/@ruby/wasm-wasi)
 (`DefaultRubyVM` in a browser, `RubyVM.instantiateModule` under Node), then
 `require "/bundle/setup"` and `require "hyperuuid"` as anywhere else. `HyperUuid::BACKEND` is
-`:native`: every door, the batch and raw-bytes forms, and `new_v6`/`new_v7` with no argument,
+`:native`: every door, the batch and raw-bytes forms, and `new_v7` with no argument,
 which read the clock through WASI.
 
 - **Ruby 3.4 and 4.0**, one archive each, the same minors the platform gems cover, picked by
@@ -367,6 +433,7 @@ 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
+HYPERUUID_BIG_BATCH=1 bundle exec rspec spec/inspection_spec.rb  # adds the 1 GiB MAX_V7_BATCH batch
 bundle exec rake docs:check          # every public object carries a doc comment
 ruby benchmark/uuid_benchmark.rb     # prints the backend it measured
 ```
@@ -393,11 +460,12 @@ flags in the forge's `build-magnus.sh`, which is also what CI uses on every plat
 
 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:
+Alpine, with the checkout mounted read-only (`corpus/` comes along: `spec/corpus_spec.rb` finds
+it by walking up from the spec):
 
 ```sh
 docker run --rm -v "$PWD/..":/src:ro ruby:4.0-alpine sh -euc '
-  mkdir /work && cp -r /src/ruby /work/ruby
+  mkdir /work && cp -r /src/ruby /src/corpus /work/
   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
@@ -411,7 +479,7 @@ 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 /work && cp -r /src/ruby /src/corpus /work/
   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

data/lib/hyperuuid/errors.rb

@@ -1,12 +1,11 @@
 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
+  # the one way `new_v4`, `new_v7` and its 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.
+  # Raised when a timestamp cannot be embedded in the version 7 UUID being minted: one past
+  # RFC 9562's 48-bit millisecond field, or a negative one (a `Time` before the Unix epoch
+  # included). Carries the same message on every backend.
   class TimestampOutOfRangeError < StandardError; end
 end

data/lib/hyperuuid/runtime.rb

@@ -22,12 +22,27 @@ module HyperUuid
     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"
+    # One copy of the 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.
     V7_TIMESTAMP_OUT_OF_RANGE = "unix_millis must fit within the RFC 9562 48-bit field"
 
+    # The two batch-size refusals, shared the same way: a version 7 batch past the 26-bit
+    # counter space (the core's return code 4, which the doors in hyperuuid.rb refuse before
+    # either backend sees it), and a batch whose byte length the platform cannot address
+    # (code 3, reachable only on a 32-bit target such as ruby.wasm). Both are argument
+    # errors, never a random source failure.
+    V7_BATCH_TOO_LARGE = "a single version 7 batch takes at most 67108864 UUIDs (the 26-bit counter space)"
+    BATCH_TOO_LARGE_TO_ADDRESS = "the batch is too large to address on this platform"
+
+    # The SQL Server order conversions' one refusal, in the core's own words (the Magnus
+    # extension raises its SqlOrderError's text): a value that isn't a UUID of the
+    # conversion's version (code 5), an ArgumentError. Every version 7 converts.
+    SQL_ORDER_WRONG_VERSION = "the value is not a UUID of the version this conversion takes"
+
+    # The core's v7::MAX_BATCH, which hyperuuid.rb publishes as HyperUuid::MAX_V7_BATCH.
+    MAX_V7_BATCH = 1 << 26
+
     NATIVE_DIR = File.join(__dir__, "native")
 
     @mutex = Mutex.new
@@ -54,32 +69,6 @@ module HyperUuid
         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 = buffer(count * 16)
-        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)
@@ -96,37 +85,65 @@ module HyperUuid
 
       def new_v7_batch(count, unix_millis)
         return "" if count.zero?
+        # Before the buffer: a count past the counter space would otherwise allocate up to
+        # 64 GiB only for the core to refuse it with code 4.
+        raise ArgumentError, V7_BATCH_TOO_LARGE if count > MAX_V7_BATCH
 
         out = buffer(count * 16)
         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
+        when 3 then raise ArgumentError, BATCH_TOO_LARGE_TO_ADDRESS
+        when 4 then raise ArgumentError, V7_BATCH_TOO_LARGE
         else raise random_source_failure("uuid_new_v7_batch")
         end
       end
 
-      def v7_to_sql_order(bytes)
-        rewrite(:v7_to_sql_order, bytes)
+      # The inspection exports. +layout+ is the core's layout code (1 RFC 9562, 2 SQL Server),
+      # which Uuid has already validated; +bytes+ are 16, held in that layout's order.
+      def version(bytes, layout)
+        functions[:version].call(bytes, layout)
       end
 
-      def v7_to_rfc_order(bytes)
-        rewrite(:v7_to_rfc_order, bytes)
+      # The core's variant code: 1 NCS, 2 RFC 9562, 3 Microsoft, 4 future (Uuid#variant maps
+      # it to a Symbol, for both backends).
+      def variant(bytes)
+        functions[:variant].call(bytes)
+      end
+
+      # +version+ is 0-15 here: Uuid#rfc? answers false for anything else without asking.
+      def is_rfc(bytes, version, layout)
+        functions[:is_rfc].call(bytes, version, layout) == 1
+      end
+
+      # The Unix ms of an RFC 9562 version 7 UUID held in +layout+'s order, or nil for
+      # anything else — another version (a version 6 or 1 included), another variant. One
+      # core call; the version it answers with is not needed above Runtime, so it is dropped
+      # here.
+      def get_timestamp(bytes, layout)
+        out = millis_scratch
+        version = functions[:get_timestamp].call(bytes, layout, out)
+        version.zero? ? nil : out[0, 8].unpack1("Q")
       end
 
-      def v6_to_sql_order(bytes)
-        rewrite(:v6_to_sql_order, bytes)
+      def v7_unix_millis_in(bytes, layout)
+        functions[:v7_unix_millis_in].call(bytes, layout)
       end
 
-      def v6_to_rfc_order(bytes)
-        rewrite(:v6_to_rfc_order, bytes)
+      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
 
       # 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
+        functions[:packed_version].call
       end
 
       # The one failure every generating export shares, with the one message every backend
@@ -187,6 +204,12 @@ module HyperUuid
         Thread.current[:hyperuuid_scratch] ||= buffer(16)
       end
 
+      # The u64 get_timestamp writes, per thread for the same reason as #scratch, and apart from
+      # it so the UUID bytes passed in are never the buffer being written.
+      def millis_scratch
+        Thread.current[:hyperuuid_millis_scratch] ||= buffer(8)
+      end
+
       # Every Fiddle allocation goes through here, and loads the library first: that is what
       # keeps a missing library reported as missing_library_message instead of as whatever
       # touching Fiddle raises first. The scratch buffer pays for it once per thread.
@@ -196,12 +219,16 @@ module HyperUuid
       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.
+      # call genuinely mutates the buffer, and the input String is frozen. A refusal leaves
+      # the buffer as it was and raises what the Magnus extension raises for it.
       def rewrite(symbol, bytes)
         buf = scratch
         buf[0, 16] = bytes
-        functions[symbol].call(buf)
-        buf[0, 16]
+        case (rc = functions[symbol].call(buf))
+        when 0 then buf[0, 16]
+        when 5 then raise ArgumentError, SQL_ORDER_WRONG_VERSION
+        else raise "uuid_#{symbol}: unexpected return code #{rc}"
+        end
       end
 
       # Loaded lazily and exactly once, mirroring Java's class initializer / Swift's lazy
@@ -224,21 +251,6 @@ module HyperUuid
             [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],
@@ -257,25 +269,36 @@ module HyperUuid
           v7_to_sql_order: Fiddle::Function.new(
             handle["uuid_v7_to_sql_order"],
             [Fiddle::TYPE_VOIDP],
-            Fiddle::TYPE_VOID
+            Fiddle::TYPE_INT
           ),
           v7_to_rfc_order: Fiddle::Function.new(
             handle["uuid_v7_to_rfc_order"],
             [Fiddle::TYPE_VOIDP],
-            Fiddle::TYPE_VOID
+            Fiddle::TYPE_INT
           ),
-          v6_to_sql_order: Fiddle::Function.new(
-            handle["uuid_v6_to_sql_order"],
-            [Fiddle::TYPE_VOIDP],
-            Fiddle::TYPE_VOID
+          version: Fiddle::Function.new(
+            handle["uuid_version"],
+            [Fiddle::TYPE_VOIDP, Fiddle::TYPE_UINT32_T],
+            Fiddle::TYPE_UINT32_T
           ),
-          v6_to_rfc_order: Fiddle::Function.new(
-            handle["uuid_v6_to_rfc_order"],
-            [Fiddle::TYPE_VOIDP],
-            Fiddle::TYPE_VOID
+          variant: Fiddle::Function.new(handle["uuid_variant"], [Fiddle::TYPE_VOIDP], Fiddle::TYPE_UINT32_T),
+          is_rfc: Fiddle::Function.new(
+            handle["uuid_is_rfc"],
+            [Fiddle::TYPE_VOIDP, Fiddle::TYPE_UINT32_T, Fiddle::TYPE_UINT32_T],
+            Fiddle::TYPE_UINT32_T
+          ),
+          get_timestamp: Fiddle::Function.new(
+            handle["uuid_get_timestamp"],
+            [Fiddle::TYPE_VOIDP, Fiddle::TYPE_UINT32_T, Fiddle::TYPE_VOIDP],
+            Fiddle::TYPE_UINT32_T
+          ),
+          v7_unix_millis_in: Fiddle::Function.new(
+            handle["uuid_v7_unix_millis_in"],
+            [Fiddle::TYPE_VOIDP, Fiddle::TYPE_UINT32_T],
+            Fiddle::TYPE_UINT64_T
           ),
           # The one export that mints nothing: the zero-argument version probe.
-          version: Fiddle::Function.new(handle["hyperuuid_version"], [], Fiddle::TYPE_UINT32_T),
+          packed_version: Fiddle::Function.new(handle["hyperuuid_version"], [], Fiddle::TYPE_UINT32_T),
         }
       end
     end

data/lib/hyperuuid/uuid.rb

@@ -38,6 +38,17 @@ module HyperUuid
     HYPHENATED = /\A\h{8}-\h{4}-\h{4}-\h{4}-\h{12}\z/
     private_constant :HYPHENATED
 
+    # The byte orders a Uuid can hold, as the +layout:+ keyword of #version, #rfc? and
+    # #timestamp takes them, mapped to the native core's layout codes. +:rfc9562+ is RFC 9562
+    # order, what every other method here takes and returns. +:sql_server+ is the layout
+    # #to_sql_order returns, a version 8 that holds a converted version 7.
+    LAYOUTS = { rfc9562: 1, sql_server: 2 }.freeze
+
+    # The Symbols #variant returns, indexed by the native core's variant code (1-4; 0 is
+    # reserved and never returned). The one place that code becomes a Symbol, for both backends.
+    VARIANTS = [nil, :ncs, :rfc9562, :microsoft, :future].freeze
+    private_constant :VARIANTS
+
     # 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.
@@ -51,14 +62,57 @@ module HyperUuid
       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
+    # The version of this UUID, read by the native core in +layout+'s byte order.
+    #
+    # In +:rfc9562+ (the default) it is the version nibble (bits 48-51, the high nibble of
+    # octet 6), 0 through 15: Nil reads as 0 and Max as 15. It says nothing about the variant;
+    # #rfc? checks both. In +:sql_server+, the layout #to_sql_order returns, it is the version
+    # the value was converted from, 7, when the bytes carry the layout's version 8 and RFC
+    # variant, and 0 when they don't. It reads the bytes as given: an
+    # RFC-ordered value can happen to carry them (a random v4 does one time in 16), so the
+    # layout is the caller's to know.
+    #
+    # With the default layout, the value is read as RFC 9562 order. A SQL-ordered value — from
+    # #to_sql_order, or a +uniqueidentifier+ read back from SQL Server — needs
+    # +layout: :sql_server+, because the RFC-order read looks at the wrong bytes there. There
+    # is deliberately no layout-agnostic check: whoever holds the value knows its order.
+    #
+    # @raise [ArgumentError] if +layout+ isn't one of LAYOUTS' keys.
+    def version(layout: :rfc9562)
+      Runtime.version(bytes, layout_code(layout))
     end
 
-    # The RFC 9562 variant bits (top two bits of octet 8). +0b10+ means RFC 9562/4122.
+    # The variant of this UUID (RFC 9562 §4.1), read by the native core in RFC 9562 order, as a
+    # Symbol: +:rfc9562+ (+10xx+, every UUID this gem mints, and the only variant that has
+    # versions), +:ncs+ (+0xxx+, Nil among them), +:microsoft+ (+110x+) or +:future+ (+111x+,
+    # Max among them).
+    #
+    # RFC 9562 order only, with no layout form. The SQL Server layout keeps the variant in the
+    # same place, so a SQL-ordered value reads +:rfc9562+ here, but that says nothing about
+    # which version it holds. To validate one, or a +uniqueidentifier+ read back from SQL
+    # Server, use <tt>rfc?(7, layout: :sql_server)</tt>, which checks the layout's version 8
+    # and variant.
     def variant
-      (bytes.getbyte(8) >> 6) & 0b11
+      VARIANTS.fetch(Runtime.variant(bytes))
+    end
+
+    # Whether this is an RFC 9562 UUID of version +version+, read in +layout+'s byte order —
+    # the RFC 9562 variant and that version together, the guard to run before trusting a
+    # value's version-specific fields. In +:sql_server+ +version+ is the version the value was
+    # converted from, so only 7 can be true. A version outside 0-15 is simply false.
+    #
+    # With the default layout, the value is read as RFC 9562 order. A SQL-ordered value — from
+    # #to_sql_order, or a +uniqueidentifier+ read back from SQL Server — needs
+    # +layout: :sql_server+, because the RFC-order read looks at the wrong bytes there. There
+    # is deliberately no layout-agnostic check: whoever holds the value knows its order.
+    #
+    # @raise [TypeError] if +version+ isn't an Integer.
+    # @raise [ArgumentError] if +layout+ isn't one of LAYOUTS' keys.
+    def rfc?(version, layout: :rfc9562)
+      raise TypeError, "version must be an Integer; got #{version.class}" unless version.is_a?(Integer)
+
+      code = layout_code(layout)
+      version.between?(0, 15) && Runtime.is_rfc(bytes, version, code)
     end
 
     # The 8-4-4-4-12 hyphenated hex string representation.
@@ -68,92 +122,61 @@ module HyperUuid
     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.
+    # The UTC timestamp embedded in an RFC 9562 version 7 UUID, held in +layout+'s byte order:
+    # +:rfc9562+ (the default), or +:sql_server+ for a value #to_sql_order returned (the
+    # timestamp of the version 7 it was converted from). One native call that checks the
+    # variant as well as the version: a 7 in the version nibble under any variant but
+    # +:rfc9562+ is not a version 7 UUID, so it has no timestamp (#rfc? is the same check on
+    # its own). Every other version has none either, a version 6 or 1 from another generator
+    # included.
+    #
+    # Raises by default for anything that isn't an RFC 9562 version 7 UUID; 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.
     #
-    # 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
+    # @raise [ArgumentError] if this isn't an RFC 9562 version 7 UUID in +layout+ (unless
+    #   +raise_on_mismatch+ is false), or +layout+ isn't one of LAYOUTS' keys.
+    def timestamp(raise_on_mismatch: true, layout: :rfc9562)
+      millis = Runtime.get_timestamp(bytes, layout_code(layout))
+      return Time.at(millis / 1000, millis % 1000, :millisecond).utc if millis
+      return nil unless raise_on_mismatch
+
+      raise ArgumentError, timestamp_mismatch(layout)
     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.
+    # Converts an RFC 9562 version 7 UUID to the layout SQL Server's `uniqueidentifier` needs
+    # on the wire to sort by creation order: an RFC 9562 version 8 UUID (§5.8, the version for
+    # custom layouts, where §6.11 sends a byte order other than the network one).
     #
     # `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.
+    # 0,1,2,3, most significant first). The layout writes the version nibble 8 at octet 7 and
+    # the RFC variant at octet 8, where SQL Server's text form and a .NET `Guid` show them, and
+    # fills the other 122 bits in that comparison's order: the 48-bit millisecond timestamp,
+    # the 26-bit counter and the 48 random bits as one intact block. A version 7 has exactly
+    # those 122 free bits, so every one converts, and #from_sql_order gives back the exact
+    # original. 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 bit 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.
+    # @raise [ArgumentError] if this isn't an RFC 9562 version 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
+      self.class.new(Runtime.v7_to_sql_order(bytes), true)
     end
 
-    # Inverse of #to_sql_order — converts a SQL-Server-ordered version 6 or 7 UUID back to
-    # RFC 9562 order.
+    # Inverse of #to_sql_order — converts a SQL-Server-ordered value back to the RFC 9562
+    # version 7 UUID it was converted from, exactly. Refuses a value without the layout's
+    # version 8 and RFC variant, an RFC-ordered version 7 among them.
     #
-    # 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.
+    # The layout is the caller's to know: bytes alone cannot say which order they are in. A
+    # value that was never SQL-ordered can still carry the layout's 8 and variant, and is then
+    # converted rather than refused (a random RFC-ordered v4 does one time in 16, since its
+    # octet 8 already carries the RFC variant and its octet 7 is random).
     #
-    # 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.
+    # @raise [ArgumentError] if this isn't a SQL-ordered value converted from version 7.
     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
+      self.class.new(Runtime.v7_to_rfc_order(bytes), true)
     end
 
     # Whether +other+ wraps the same 16 raw bytes.
@@ -178,5 +201,24 @@ module HyperUuid
     def inspect
       "#<HyperUuid::Uuid #{self}>"
     end
+
+    private
+
+    # Why #timestamp found none: the message is worked out only once it is going to be raised.
+    def timestamp_mismatch(layout)
+      return "timestamp: not a SQL-ordered version 7 UUID" if layout == :sql_server
+
+      found = version
+      message = "timestamp is only defined for version 7 UUIDs, got version #{found}"
+      found == 7 ? "#{message} with the #{variant.inspect} variant" : message
+    end
+
+    # The native core's code for +layout+, the one place a layout is checked: an unknown one
+    # is refused here, never passed through to the core.
+    def layout_code(layout)
+      LAYOUTS.fetch(layout) do
+        raise ArgumentError, "layout must be one of #{LAYOUTS.keys.map(&:inspect).join(', ')}; got #{layout.inspect}"
+      end
+    end
   end
 end

data/lib/hyperuuid.rb

@@ -4,27 +4,42 @@ 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.
+# RFC 9562 UUID v4 (random), v5 (deterministic) and v7 (time-sortable) generation, with a
+# version 8 SQL Server order for v7, 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.7.0"
+  # This gem's own version — distinct from the RFC 9562 UUID *versions* (v4/v5/v7) the rest
+  # of this module generates.
+  VERSION = "0.9.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
 
+  # The most UUIDs one version 7 batch (#new_v7_batch, #new_v7_batch_bytes) mints:
+  # 67,108,864, the size of the 26-bit counter that orders UUIDs within a millisecond. A larger
+  # count is refused with ArgumentError before anything is allocated.
+  #
+  # Every batch up to this size is in strictly increasing order: the counter is one
+  # process-wide sequence, so a batch can straddle the point where it wraps back to 0, and the
+  # UUIDs from there on carry a timestamp one millisecond later than the one supplied.
+  # The roll-forward orders one batch, not the stream: the next batch or single #new_v7 in
+  # the same real millisecond starts its counter just past the wrap and carries the supplied
+  # timestamp, so it sorts before this batch's tail, which was stamped a millisecond later.
+  # Two single #new_v7 calls either side of the wrap in one millisecond sort in reverse the
+  # same way. It happens at most once per 2**26 UUIDs the process mints.
+  MAX_V7_BATCH = Runtime::MAX_V7_BATCH
+
   # Creates a random UUID version 4 (RFC 9562 §5.4).
   def self.new_v4
     Uuid.new(Runtime.new_v4, true)
@@ -53,7 +68,7 @@ module HyperUuid
   # 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
+  # `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
@@ -87,29 +102,6 @@ module HyperUuid
     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.
@@ -125,7 +117,18 @@ module HyperUuid
   # 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.
+  # Every batch is in strictly increasing order. The counter is one process-wide sequence, so
+  # a batch can straddle the point where it wraps back to 0; the UUIDs from there on carry a
+  # timestamp one millisecond later than the one supplied rather than sorting before the ones
+  # ahead of them. That is also why one batch takes at most MAX_V7_BATCH.
+  #
+  # The roll-forward orders one batch, not the stream: the next batch or single #new_v7 in
+  # the same real millisecond starts its counter just past the wrap and carries the supplied
+  # timestamp, so it sorts before this batch's tail, which was stamped a millisecond later.
+  # Two single #new_v7 calls either side of the wrap in one millisecond sort in reverse the
+  # same way. It happens at most once per 2**26 UUIDs the process mints.
+  #
+  # @raise [TypeError, ArgumentError] if +count+ isn't an Integer between 0 and MAX_V7_BATCH.
   # @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)
@@ -145,28 +148,17 @@ module HyperUuid
   # 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.
+  # Slice it with `bytes[i * 16, 16]`, which is what #new_v7_batch does internally. The
+  # order, the possible extra millisecond and the MAX_V7_BATCH limit are #new_v7_batch's.
   #
-  # @raise [TypeError, ArgumentError] if +count+ isn't an Integer between 0 and 2**32 - 1.
+  # @raise [TypeError, ArgumentError] if +count+ isn't an Integer between 0 and MAX_V7_BATCH.
   # @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
+    # First, so any count past the limit (2**32 and beyond included) names the limit itself.
+    raise ArgumentError, Runtime::V7_BATCH_TOO_LARGE if count.is_a?(Integer) && count > MAX_V7_BATCH
 
-  # 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))
+    Runtime.new_v7_batch(count, unix_millis_from(unix_millis, Runtime::V7_TIMESTAMP_OUT_OF_RANGE))
   end
 
   # The version of the native core actually loaded, as "major.minor.patch" — read from the

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hyperuuid-wasm
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.9.0
 platform: ruby
 authors:
 - Brian Buvinghausen