hyperuuid 0.3.0 → 0.5.0

data/lib/hyperuuid/runtime.rb

@@ -12,8 +12,18 @@ module HyperUuid
   # 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
+    # The package's two exceptions live on HyperUuid itself (errors.rb). These are the names
+    # they had through 0.3.0, kept as aliases of the very same classes so a
+    # `rescue HyperUuid::Runtime::TimestampOutOfRangeError` written against an earlier
+    # release still catches.
+    RandomSourceError = HyperUuid::RandomSourceError
+    TimestampOutOfRangeError = HyperUuid::TimestampOutOfRangeError
+
+    # One copy of each out-of-range message for the Fiddle and wasm backends and for the
+    # doors' own range check in hyperuuid.rb; the Magnus extension (rust/src/ruby_ext.rs)
+    # carries the same text, and spec/native_backend_spec.rb pins that the two agree.
+    V6_TIMESTAMP_OUT_OF_RANGE = "unix_millis does not fit the 60-bit v6 timestamp field"
+    V7_TIMESTAMP_OUT_OF_RANGE = "unix_millis must fit within the RFC 9562 48-bit field"
 
     NATIVE_DIR = File.join(__dir__, "native")
 
@@ -24,17 +34,18 @@ module HyperUuid
       def new_v4
         out = scratch
         rc = functions[:new_v4].call(out)
-        raise RandomSourceError, "uuid_new_v4 failed with code #{rc}" unless rc.zero?
+        raise random_source_failure("uuid_new_v4") unless rc.zero?
         out[0, 16]
       end
 
       def new_v5(namespace_bytes, name_bytes)
         out = scratch
-        # Fiddle passes a String's 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?
+        # Fiddle passes a String's own bytes for void* (read-only, no copy of them) — the
+        # same crossing every other input here uses. An empty name crosses as it is, a
+        # valid pointer with length 0, never as nil: NULL is not part of this export's
+        # contract.
+        rc = functions[:new_v5].call(namespace_bytes, name_bytes, name_bytes.bytesize, out)
+        raise random_source_failure("uuid_new_v5") unless rc.zero?
         out[0, 16]
       end
 
@@ -43,8 +54,8 @@ module HyperUuid
         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}"
+        when 2 then raise TimestampOutOfRangeError, V6_TIMESTAMP_OUT_OF_RANGE
+        else raise random_source_failure("uuid_new_v6")
         end
       end
 
@@ -58,8 +69,8 @@ module HyperUuid
         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}"
+        when 2 then raise TimestampOutOfRangeError, V6_TIMESTAMP_OUT_OF_RANGE
+        else raise random_source_failure("uuid_new_v6_batch")
         end
       end
 
@@ -68,8 +79,8 @@ module HyperUuid
         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}"
+        when 2 then raise TimestampOutOfRangeError, V7_TIMESTAMP_OUT_OF_RANGE
+        else raise random_source_failure("uuid_new_v7")
         end
       end
 
@@ -83,8 +94,8 @@ module HyperUuid
         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}"
+        when 2 then raise TimestampOutOfRangeError, V7_TIMESTAMP_OUT_OF_RANGE
+        else raise random_source_failure("uuid_new_v7_batch")
         end
       end
 
@@ -104,18 +115,44 @@ module HyperUuid
         rewrite(:v6_to_rfc_order, bytes)
       end
 
+      # The loaded core's version word, major << 16 | minor << 8 | patch, straight from the
+      # library's zero-argument hyperuuid_version export. HyperUuid.native_version unpacks
+      # it; like every method here, each backend replaces this one in place.
+      def packed_version
+        functions[:version].call
+      end
+
+      # The one failure every generating export shares, with the one message every backend
+      # raises for it: the export's name, and that the system's random source failed.
+      def random_source_failure(export)
+        RandomSourceError.new("#{export}: the system random source failed")
+      end
+
       # Whether this platform has a shared library for Fiddle to dlopen at all: a known RID
-      # and the file actually present in this install. Backend selection (hyperuuid.rb)
-      # asks this before falling back to the WebAssembly backend, which needs neither.
+      # and the file actually present — in this install, or in the in-repo cargo build the
+      # dev loop falls back to. Backend selection (hyperuuid.rb) asks this before falling
+      # back to the WebAssembly backend, which needs neither.
       def fiddle_library_available?
-        rid, lib_name = NativePlatform.rid_and_library_name
-        File.exist?(File.join(NATIVE_DIR, rid, lib_name))
+        !library_path.nil?
       rescue NativePlatform::UnsupportedPlatformError
         false
       end
 
       private
 
+      # The shared library to dlopen: this install's native/{rid}/{lib}, or — the
+      # development loop — the in-repo cargo build, exactly what the other bindings' local
+      # staging does (HyperCast's runtime has had this since its first release). Nil when
+      # neither exists.
+      def library_path
+        rid, lib_name = NativePlatform.rid_and_library_name
+        path = File.join(NATIVE_DIR, rid, lib_name)
+        return path if File.exist?(path)
+
+        repo_build = File.expand_path(File.join(__dir__, "../../../rust/target/release", lib_name))
+        File.exist?(repo_build) ? repo_build : nil
+      end
+
       # 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
@@ -142,11 +179,12 @@ module HyperUuid
       end
 
       def load_functions
-        rid, lib_name = NativePlatform.rid_and_library_name
-        path = File.join(NATIVE_DIR, rid, lib_name)
-        unless File.exist?(path)
+        path = library_path
+        if path.nil?
+          rid, lib_name = NativePlatform.rid_and_library_name
           raise LoadError,
-                "hyperuuid: #{path} not found (unsupported platform, or this gem was built without a native library for it)"
+                "hyperuuid: #{File.join(NATIVE_DIR, rid, lib_name)} not found (unsupported " \
+                "platform, or this gem was built without a native library for it)"
         end
 
         handle = Fiddle.dlopen(path)
@@ -207,6 +245,8 @@ module HyperUuid
             [Fiddle::TYPE_VOIDP],
             Fiddle::TYPE_VOID
           ),
+          # The one export that mints nothing: the zero-argument version probe.
+          version: Fiddle::Function.new(handle["hyperuuid_version"], [], Fiddle::TYPE_UINT32_T),
         }
       end
     end

data/lib/hyperuuid/uuid.rb

@@ -9,12 +9,22 @@ module HyperUuid
     # 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.
+    # Wraps a raw 16-byte RFC 9562 (big-endian) UUID value. The bytes are copied, so the
+    # String passed in stays the caller's.
+    #
+    # +owned+ is for this gem's own use: it says +bytes+ is a String the native core has
+    # just produced — sixteen bytes, already ASCII-8BIT, held by nothing else — so there is
+    # nothing to check, copy or re-tag, and that copy is most of what constructing one costs.
     #
     # @raise [ArgumentError] if +bytes+ isn't exactly 16 bytes.
-    def initialize(bytes)
-      raise ArgumentError, "bytes must be exactly 16 bytes" unless bytes.bytesize == 16
-      @bytes = bytes.dup.force_encoding(Encoding::BINARY).freeze
+    def initialize(bytes, owned = false)
+      if owned
+        @bytes = bytes.freeze
+      else
+        raise ArgumentError, "bytes must be exactly 16 bytes" unless bytes.bytesize == 16
+
+        @bytes = bytes.dup.force_encoding(Encoding::BINARY).freeze
+      end
     end
 
     # The RFC 9562 §5.9 Nil UUID — all 128 bits zero.
@@ -23,13 +33,22 @@ module HyperUuid
     # 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.
+    # The one text shape .parse accepts: 8-4-4-4-12 hex digits, either case, the four hyphens
+    # exactly where #to_s puts them.
+    HYPHENATED = /\A\h{8}-\h{4}-\h{4}-\h{4}-\h{12}\z/
+    private_constant :HYPHENATED
+
+    # Parses an 8-4-4-4-12 hyphenated hex UUID string — exactly the shape #to_s produces, in
+    # either case. Nothing else parses: not the bare 32 hex digits, not hyphens anywhere but
+    # those four positions, not braces or a `urn:uuid:` prefix.
     #
-    # @raise [ArgumentError] if +string+ isn't a valid UUID string.
+    # @raise [ArgumentError] if +string+ isn't a String in that shape.
     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*"))
+      unless string.is_a?(String) && string.match?(HYPHENATED)
+        raise ArgumentError, "invalid UUID string: #{string.inspect}"
+      end
+
+      new([string.delete("-")].pack("H*"))
     end
 
     # The RFC 9562 version nibble (bits 48-51, the high nibble of octet 6).
@@ -100,8 +119,8 @@ module HyperUuid
     # 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))
+      when 7 then self.class.new(Runtime.v7_to_sql_order(bytes), true)
+      when 6 then self.class.new(Runtime.v6_to_sql_order(bytes), true)
       else raise ArgumentError, "to_sql_order is only defined for version 6 or 7 UUIDs, got version #{version}"
       end
     end
@@ -127,9 +146,9 @@ module HyperUuid
       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))
+        self.class.new(Runtime.v6_to_rfc_order(bytes), true)
       elsif octet7_version == 7
-        self.class.new(Runtime.v7_to_rfc_order(bytes))
+        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

data/lib/hyperuuid/wasm_runtime.rb

@@ -10,9 +10,10 @@ module HyperUuid
   # Same integration shape as the Magnus extension: on require (after runtime.rb has defined
   # the Fiddle backend) this redefines the `HyperUuid::Runtime` singleton methods **in place**
   # — no delegation layer, no second surface. Everything above Runtime (the `Uuid` class, the
-  # module doors, batch slicing) stays shared byte-for-byte across all three backends, and the
-  # same `Runtime::RandomSourceError` / `Runtime::TimestampOutOfRangeError` classes carry the
-  # same messages.
+  # module doors and their argument checks, batch slicing) stays shared byte-for-byte across
+  # all three backends, and the same `HyperUuid::RandomSourceError` /
+  # `HyperUuid::TimestampOutOfRangeError` classes carry the same messages — literally the
+  # same constants and helper runtime.rb defines for the Fiddle backend.
   #
   # Two things differ from the native backends, both forced by the sandbox:
   #
@@ -28,6 +29,11 @@ module HyperUuid
   #   library does natively.
   module Runtime
     WASM_MODULE_PATH = File.join(NATIVE_DIR, "wasm32-wasip1", "hyperuuid.wasm")
+    # Development loop: the in-repo cargo build, the same fallback runtime.rb takes for the
+    # native library, so `HYPERUUID_WASM=1 bundle exec rspec` needs nothing staged by hand.
+    WASM_REPO_BUILD_PATH = File.expand_path(
+      File.join(__dir__, "../../../rust/target/wasm32-wasip1/release/hyperuuid.wasm")
+    )
 
     # One instantiated module: the exported functions, the exported memory, and the two
     # 16-byte scratch buffers (one in, one out) the single-item doors reuse for the life of
@@ -42,9 +48,11 @@ module HyperUuid
         uuid_new_v4 uuid_new_v5 uuid_new_v6 uuid_v6_unix_millis uuid_new_v6_batch
         uuid_new_v7 uuid_v7_unix_millis uuid_new_v7_batch
         uuid_v7_to_sql_order uuid_v7_to_rfc_order uuid_v6_to_sql_order uuid_v6_to_rfc_order
+        hyperuuid_version
       ].freeze
 
       def initialize(path)
+        path = WASM_REPO_BUILD_PATH if !File.exist?(path) && File.exist?(WASM_REPO_BUILD_PATH)
         unless File.exist?(path)
           raise LoadError,
                 "hyperuuid: #{path} not found (this gem was built without its WebAssembly module)"
@@ -62,7 +70,11 @@ module HyperUuid
         instance = linker.instantiate(store, mod)
 
         @memory = instance.export("memory").to_memory
-        @fn = EXPORTS.to_h { |name| [name, instance.export(name.to_s).to_func] }
+        @fn = EXPORTS.to_h do |name|
+          export = instance.export(name.to_s) or
+            raise LoadError, "hyperuuid: #{path} does not export #{name} (a module older than this binding)"
+          [name, export.to_func]
+        end
         @in = malloc(16)
         @out = malloc(16)
       end
@@ -99,7 +111,7 @@ module HyperUuid
       def new_v4
         wasm do |w|
           rc = w.fn(:uuid_new_v4).call(w.out)
-          raise RandomSourceError, "uuid_new_v4 failed with code #{rc}" unless rc.zero?
+          raise random_source_failure("uuid_new_v4") unless rc.zero?
           w.memory.read(w.out, 16)
         end
       end
@@ -119,7 +131,7 @@ module HyperUuid
                 w.fn(:uuid_new_v5).call(w.in, name, name_bytes.bytesize, w.out)
               end
             end
-          raise RandomSourceError, "uuid_new_v5 failed with code #{rc}" unless rc.zero?
+          raise random_source_failure("uuid_new_v5") unless rc.zero?
           w.memory.read(w.out, 16)
         end
       end
@@ -129,8 +141,8 @@ module HyperUuid
           rc = w.fn(:uuid_new_v6).call(i64(unix_millis), w.out)
           case rc
           when 0 then w.memory.read(w.out, 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}"
+          when 2 then raise TimestampOutOfRangeError, V6_TIMESTAMP_OUT_OF_RANGE
+          else raise random_source_failure("uuid_new_v6")
           end
         end
       end
@@ -149,8 +161,8 @@ module HyperUuid
             rc = w.fn(:uuid_new_v6_batch).call(i64(unix_millis), count, out)
             case rc
             when 0 then w.memory.read(out, 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}"
+            when 2 then raise TimestampOutOfRangeError, V6_TIMESTAMP_OUT_OF_RANGE
+            else raise random_source_failure("uuid_new_v6_batch")
             end
           end
         end
@@ -161,8 +173,8 @@ module HyperUuid
           rc = w.fn(:uuid_new_v7).call(i64(unix_millis), w.out)
           case rc
           when 0 then w.memory.read(w.out, 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}"
+          when 2 then raise TimestampOutOfRangeError, V7_TIMESTAMP_OUT_OF_RANGE
+          else raise random_source_failure("uuid_new_v7")
           end
         end
       end
@@ -181,8 +193,8 @@ module HyperUuid
             rc = w.fn(:uuid_new_v7_batch).call(i64(unix_millis), count, out)
             case rc
             when 0 then w.memory.read(out, 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}"
+            when 2 then raise TimestampOutOfRangeError, V7_TIMESTAMP_OUT_OF_RANGE
+            else raise random_source_failure("uuid_new_v7_batch")
             end
           end
         end
@@ -204,6 +216,10 @@ module HyperUuid
         rewrite(:uuid_v6_to_rfc_order, bytes)
       end
 
+      def packed_version
+        wasm { |w| w.fn(:hyperuuid_version).call }
+      end
+
       private
 
       # The in-place byte-order rewrites: copy the caller's frozen bytes into the guest,
@@ -228,7 +244,9 @@ module HyperUuid
 
       # wasm has no unsigned integers: a u64 crosses as an i64. The core's own range checks
       # (48-bit v7, 60-bit v6) still see the exact value the caller passed, they just see
-      # it through a two's-complement reinterpretation on the way in and back.
+      # it through a two's-complement reinterpretation on the way in and back. Exact only
+      # for a value that is a u64 to begin with, which the doors in hyperuuid.rb guarantee
+      # before any backend is called.
       def i64(value)
         value >= 2**63 ? value - 2**64 : value
       end

data/lib/hyperuuid.rb

@@ -1,49 +1,91 @@
-require "time"
-
+require_relative "hyperuuid/errors"
 require_relative "hyperuuid/uuid"
 require_relative "hyperuuid/namespaces"
 require_relative "hyperuuid/native_platform"
 require_relative "hyperuuid/runtime"
 
-# RFC 9562 UUID v4 (random), v5 (deterministic), v6 and v7 (time-sortable) generation, 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.
+# RFC 9562 UUID v4 (random), v5 (deterministic), v6 and v7 (time-sortable) generation from one
+# Rust core, reached through whichever of three backends this install can load: the core
+# linked straight into a Magnus native extension (shipped precompiled in the platform gems),
+# the native libhyperuuid shared library called through Fiddle (the universal gem bundles
+# one per supported platform, picked by HyperUuid::NativePlatform), or the same core as a
+# WebAssembly module inside the wasmtime gem. No runtime bridge in any of them, 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.3.0"
+  VERSION = "0.5.0"
+
+  # The widest batch count, and the longest v5 name in bytes, the native ABI carries (a u32).
+  # (The millisecond count is a u64; unix_millis_from refuses anything wider.)
+  U32_MAX = 0xFFFF_FFFF
+  private_constant :U32_MAX
 
   # Creates a random UUID version 4 (RFC 9562 §5.4).
   def self.new_v4
-    Uuid.new(Runtime.new_v4)
+    Uuid.new(Runtime.new_v4, true)
   end
 
   # Creates a deterministic UUID version 5 (RFC 9562 §5.5) from a namespace and a name. The
   # same (namespace, name) pair always produces the same UUID. `name` may be a text String
-  # (encoded as UTF-8) or already-raw ASCII-8BIT bytes, which are used as-is.
+  # (encoded as UTF-8) or already-raw ASCII-8BIT bytes, which are used as-is; it may be empty.
+  #
+  # @raise [TypeError] if +namespace+ isn't a HyperUuid::Uuid or +name+ isn't a String.
   def self.new_v5(namespace, name)
+    raise TypeError, "namespace must be a HyperUuid::Uuid; got #{namespace.class}" unless namespace.is_a?(Uuid)
+    raise TypeError, "name must be a String; got #{name.class}" unless name.is_a?(String)
+
     name_bytes =
       if name.encoding == Encoding::ASCII_8BIT
         name
       else
         name.encode(Encoding::UTF_8).dup.force_encoding(Encoding::BINARY)
       end
-    Uuid.new(Runtime.new_v5(namespace.bytes, name_bytes))
+    raise ArgumentError, "name must be at most #{U32_MAX} bytes" if name_bytes.bytesize > U32_MAX
+
+    Uuid.new(Runtime.new_v5(namespace.bytes, name_bytes), true)
   end
 
   # Converts +value+ to a Unix-epoch millisecond integer: +nil+ becomes the current time, a
   # +Time+ is converted exactly (via its own Rational seconds, avoiding float rounding), and
-  # anything else (an Integer millisecond count) passes through unchanged. Shared by every
+  # an Integer millisecond count passes through unchanged. Shared by every
   # `new_v6`/`new_v7`/batch door below so a caller can pass either a `Time` or a raw
   # millisecond count interchangeably.
-  private_class_method def self.unix_millis_from(value)
-    case value
-    when nil then Process.clock_gettime(Process::CLOCK_REALTIME, :millisecond)
-    when Time then (value.to_r * 1000).to_i
-    else value
-    end
+  #
+  # This is also where a caller bug is caught once, for every backend: anything else is a
+  # TypeError, and a count that cannot cross the ABI as a u64 at all — negative (a `Time`
+  # before the epoch included) or past 64 bits — is the same TimestampOutOfRangeError, with
+  # the same +out_of_range+ message, the core raises for a value it can see but not embed.
+  # Left to the backends those cases diverged: a RangeError from the extension, a wrapped
+  # value from Fiddle, a silently truncated one from wasm.
+  #
+  # The two common arguments go first and cheapest: no argument is the clock, which needs no
+  # range check, and an Integer is checked by its bit length rather than against 2**64 - 1: a
+  # comparison with a number that size is a bignum comparison, and cost more than the mint.
+  private_class_method def self.unix_millis_from(value, out_of_range)
+    return Process.clock_gettime(Process::CLOCK_REALTIME, :millisecond) if value.nil?
+
+    millis =
+      if value.is_a?(Integer) then value
+      elsif value.is_a?(Time) then (value.to_r * 1000).floor
+      else raise TypeError, "unix_millis must be a Time, an Integer or nil; got #{value.class}"
+      end
+    raise TimestampOutOfRangeError, out_of_range unless millis >= 0 && millis.bit_length <= 64
+
+    millis
+  end
+
+  # Checks a batch +count+ once, for every backend: an Integer the ABI's u32 can carry.
+  private_class_method def self.batch_count(count)
+    raise TypeError, "count must be an Integer; got #{count.class}" unless count.is_a?(Integer)
+    raise ArgumentError, "count must be between 0 and #{U32_MAX}; got #{count}" unless count.between?(0, U32_MAX)
+
+    count
   end
 
   # Creates a time-sortable UUID version 6 (RFC 9562 §5.6), a field-compatible reordering of
@@ -51,49 +93,66 @@ module HyperUuid
   # `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)))
+    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 = Runtime.new_v6_batch(count, unix_millis_from(unix_millis))
-    Array.new(count) { |i| Uuid.new(bytes[i * 16, 16]) }
+    bytes = new_v6_batch_bytes(count, unix_millis)
+    Array.new(count) { |i| Uuid.new(bytes[i * 16, 16], true) }
   end
 
   # Creates a time-sortable UUID version 7 (RFC 9562 §6.2). Defaults to the current time; pass
   # an explicit `Time` or Unix-epoch millisecond integer (non-negative, fitting in 48 bits) to
   # embed a specific time instead.
+  #
+  # @raise [TimestampOutOfRangeError] if the time is negative or past the 48-bit v7 field.
+  # @raise [TypeError] if +unix_millis+ isn't a Time, an Integer or nil.
   def self.new_v7(unix_millis = nil)
-    Uuid.new(Runtime.new_v7(unix_millis_from(unix_millis)))
+    Uuid.new(Runtime.new_v7(unix_millis_from(unix_millis, Runtime::V7_TIMESTAMP_OUT_OF_RANGE)), true)
   end
 
   # Creates `count` time-sortable version 7 UUIDs sharing one timestamp capture and one
   # contiguous block of the monotonic counter — one FFI call and one random-bytes fetch
   # instead of `count` of each. Defaults to the current time; pass an explicit `Time` or
   # Unix-epoch millisecond integer to embed a specific time instead.
+  #
+  # @raise [TypeError, ArgumentError] if +count+ isn't an Integer between 0 and 2**32 - 1.
+  # @raise [TimestampOutOfRangeError] if the time is negative or past the 48-bit v7 field.
   def self.new_v7_batch(count, unix_millis = nil)
-    bytes = Runtime.new_v7_batch(count, unix_millis_from(unix_millis))
-    Array.new(count) { |i| Uuid.new(bytes[i * 16, 16]) }
+    bytes = new_v7_batch_bytes(count, unix_millis)
+    Array.new(count) { |i| Uuid.new(bytes[i * 16, 16], true) }
   end
 
   # Returns `count` version 7 UUIDs as one binary String of raw RFC 9562-ordered bytes,
   # 16 per UUID, instead of an Array of Uuid objects.
   #
-  # Roughly 11x faster than #new_v7_batch for a 1000-UUID batch (about 35 us versus 400 us).
-  # The difference is not the native call — that is identical — it is that #new_v7_batch then
-  # allocates `count` Uuid objects and `count` String slices on top of it. This hands back the
-  # bytes the native core already produced, untouched.
+  # Far faster than #new_v7_batch for a large batch — the README's "Bulk generation into
+  # bytes" section carries the measured figures. The difference is not the native call —
+  # that is identical — it is that #new_v7_batch then allocates `count` Uuid objects and
+  # their byte Strings on top of it. This hands back the bytes the native core already
+  # produced, untouched.
   #
   # Use it when bytes are the destination: a BYTEA/uniqueidentifier bind parameter, a wire
   # format, a bulk COPY. If you need Uuid objects, keep using #new_v7_batch — slicing this
   # String into them yourself just moves the same allocations into your own code.
   #
   # Slice it with `bytes[i * 16, 16]`, which is what #new_v7_batch does internally.
+  #
+  # @raise [TypeError, ArgumentError] if +count+ isn't an Integer between 0 and 2**32 - 1.
+  # @raise [TimestampOutOfRangeError] if the time is negative or past the 48-bit v7 field.
   def self.new_v7_batch_bytes(count, unix_millis = nil)
-    Runtime.new_v7_batch(count, unix_millis_from(unix_millis))
+    count = batch_count(count)
+    Runtime.new_v7_batch(count, unix_millis_from(unix_millis, Runtime::V7_TIMESTAMP_OUT_OF_RANGE))
   end
 
   # Returns `count` version 6 UUIDs as one binary String of raw RFC 9562-ordered bytes,
@@ -103,8 +162,42 @@ module HyperUuid
   # 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)
-    Runtime.new_v6_batch(count, unix_millis_from(unix_millis))
+    count = batch_count(count)
+    Runtime.new_v6_batch(count, unix_millis_from(unix_millis, Runtime::V6_TIMESTAMP_OUT_OF_RANGE))
+  end
+
+  # The version of the native core actually loaded, as "major.minor.patch" — read from the
+  # library itself (its `hyperuuid_version` export), not from this gem, so a consumer can
+  # prove the core behind the doors is the one this binding was built against (and name the
+  # mismatch against HyperUuid::VERSION when it is not). The cheapest possible probe that the
+  # backend resolved at all: takes nothing, mints nothing, cannot fail once the backend loads.
+  #
+  # @raise [LoadError] if no backend could be loaded for this platform.
+  def self.native_version
+    word = Runtime.packed_version
+    "#{word >> 16}.#{(word >> 8) & 0xFF}.#{word & 0xFF}"
+  end
+
+  # Whether a backend actually loaded and exports the ABI this binding was built against —
+  # what a consumer with a fallback of its own (SecureRandom.uuid, say) checks before
+  # committing to these doors. Probed once (a native_version round trip), cached, and never
+  # raises: a missing shared library, an unsupported platform, an older core without the
+  # version export, or a wasm module the wasmtime gem cannot instantiate all answer false.
+  # The doors themselves keep their own behavior — the first call on an unavailable backend
+  # raises its precise error — and so does require-time selection under HYPERUUID_WASM=1
+  # without wasmtime; this only answers the question quietly.
+  def self.available?
+    return @available unless @available.nil?
+
+    @available = begin
+      native_version.is_a?(String)
+    rescue LoadError, StandardError
+      false
+    end
   end
 end
 
@@ -122,6 +215,10 @@ end
 # forces it (and fails loudly if wasmtime is missing); otherwise it is only ever chosen when
 # there is no native library for this platform at all and wasmtime happens to be available,
 # so no supported platform's behavior changes by its existence.
+#
+# Both variables are read for presence, not value — set to anything at all, "0" and the
+# empty string included, they force their backend — and HYPERUUID_WASM wins when both are
+# set.
 HyperUuid::BACKEND =
   if ENV["HYPERUUID_WASM"]
     begin
@@ -138,9 +235,12 @@ HyperUuid::BACKEND =
     # Two layouts, and both have to work. A released platform gem is a "fat" gem carrying one
     # extension per supported Ruby ABI under lib/hyperuuid/<minor>/ (see the Rakefile's
     # native:gem task for why an ABI-per-file is unavoidable — Magnus has no `abi3`
-    # equivalent). CI's in-job staging and a local `cargo build --release --features ruby`
-    # instead drop a single extension flat at lib/. Trying the versioned path first and the
-    # flat one second means neither has to know the other exists.
+    # equivalent), and `rake native:dev` — the local dev loop — stages its own build at that
+    # same versioned path. CI's in-job staging additionally drops a single extension flat at
+    # lib/, which is also where a hand copy of `cargo ruby-ext`'s output goes (the alias only
+    # builds into rust/target/ruby/release/; nothing but that rake task copies it here).
+    # Trying the versioned path first and the flat one second means neither has to know the
+    # other exists.
     #
     # A miss on both is not an error: it means this Ruby/platform combination has no
     # precompiled extension, which is precisely what the Fiddle backend below is for.
@@ -157,8 +257,9 @@ HyperUuid::BACKEND =
         else
           # No shared library for this platform either. wasmtime, if the consumer has it,
           # is the only backend left that can run here; without it, stay on Fiddle so the
-          # first call raises its own precise "not found" LoadError rather than a vaguer one
-          # from here.
+          # first call raises its own precise error — a "not found" LoadError naming the
+          # path, or NativePlatform::UnsupportedPlatformError naming the platform — rather
+          # than a vaguer one from here. HyperUuid.available? is the quiet way to ask.
           begin
             require "wasmtime"
             require_relative "hyperuuid/wasm_runtime"