hyperuuid 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 86a714e730984407a83b898dd7640790d927f03eeef37eff80d8de08534b4d5a
-  data.tar.gz: 7b851c9c73462a20aac2eea3dd99b516802f4c8c245c7cc089755fe75dac9167
+  metadata.gz: 9469a1d25a10c66127020801f9773f8dc64325fb3e9567c76ab50d3182641ca9
+  data.tar.gz: bf59070f36ce9d2fef96080649dcd0392a01d3e0b18b6311804d2839ed465bfc
 SHA512:
-  metadata.gz: 7e16c54c980bb8f2bdc4717d0e04abbfd67857053d9ae6ad96c1d01909e48e5df7f27c4a5e92a94a4893b990e4cb8d91b6dcb57b439b52e085f157c21ff652c7
-  data.tar.gz: d56f5683376fea00dfe8189e4a722232de1d99b2f1829712973ef1c601b9f6b1c77573ab3638d88e12021693f38583f6e92c469efe69a4a3705e97494779b8bf
+  metadata.gz: 978ee6cf29cb949cf22dfca9a02ec2c3c129a66a4a7b9db461e06028d948246eef50ad5d3e326b53ab4dc888836f147b76d9391717c3660369751cc1afd7bdb5
+  data.tar.gz: 7606abc5a1ec909559dd1cefc0dedf2272c0bdd46bd113210123cf543d92523668589baf4bf297c302a4b0d56a0dd4c6ccf31f7de687de5192b36f60e6482a78

data/README.md

@@ -7,17 +7,15 @@
 **Ruby's own stdlib stops at `SecureRandom.uuid` — random v4, full stop. No v5, no v6, no v7. This gem is the whole RFC, with zero gem dependency beyond `Fiddle` (which ships with every Ruby install) — and it's faster than `SecureRandom.uuid` too.**
 
 RFC 9562 UUID v4 (random), v5 (deterministic), v6 and v7 (time-sortable) generation, with
-three backends sharing one public surface. Ruby 3.3 is the floor. The fast path is a native
+two backends sharing one public surface. Ruby 3.3 is the floor. The fast path is a native
 extension built with [Magnus](https://github.com/matsadler/magnus) — the Rust core linked
 directly into the Ruby VM, auto-selected when loadable — which redefines the low-level
 `Runtime` methods in place on require; everything above them (`Uuid`, the module doors and
 their argument checks, batch slicing) is shared byte-for-byte between backends. The
-universal fallback calls the native `libhyperuuid` shared library via
-[`Fiddle`](https://docs.ruby-lang.org/en/master/Fiddle.html) — dlopen/dlsym plus a raw C-ABI
-call, no runtime bridge. A third backend runs the same core as a WebAssembly module inside
-the [`wasmtime`](https://rubygems.org/gems/wasmtime) gem, for any platform with no native
-build at all. `HyperUuid::BACKEND` reports which one is live; `HYPERUUID_PURE=1` forces
-Fiddle, `HYPERUUID_WASM=1` the wasm module — see [Backends](#backends).
+last-resort fallback, in the universal gem only, calls the native `libhyperuuid` shared
+library via [`Fiddle`](https://docs.ruby-lang.org/en/master/Fiddle.html) — dlopen/dlsym plus
+a raw C-ABI call, no runtime bridge. `HyperUuid::BACKEND` reports which one is live;
+`HYPERUUID_PURE=1` forces Fiddle for testing — see [Backends](#backends).
 
 ```ruby
 require "hyperuuid"
@@ -114,7 +112,7 @@ looked for, or `HyperUuid::NativePlatform::UnsupportedPlatformError` naming the
 3. **Batch generation.** `new_v7_batch(1000)` shares one timestamp capture, one random-bytes fetch, and one counter reservation across the whole batch instead of paying per-item overhead a thousand times over.
 4. **Cross-language consistency.** The same Rust core mints v5 namespace UUIDs for Python, Go, C#, and every other binding in this repo — verified in CI to match Python's own `uuid.uuid5` byte-for-byte. If your system isn't Ruby-only, no Ruby-only gem can offer that.
 
-The honest trade-off: this gem `dlopen`s a native library instead of being pure Ruby, so it needs a platform-specific `libhyperuuid.so`/`.dylib`/`.dll` bundled alongside it. If plain v4 randomness is all you need, `SecureRandom.uuid` is simpler and already in stdlib — that's a completely reasonable choice.
+The honest trade-off: this gem is native code, not pure Ruby — a precompiled extension in each platform gem, and on the universal gem a platform-specific `libhyperuuid.so`/`.dylib`/`.dll` loaded through Fiddle — so it runs only where one of those was built. If plain v4 randomness is all you need, `SecureRandom.uuid` is simpler and already in stdlib — that's a completely reasonable choice.
 
 ## Bulk generation into bytes
 
@@ -135,7 +133,7 @@ Slice it with `bytes[i * 16, 16]` — which is exactly what `new_v7_batch` does
 
 `ruby benchmark/uuid_benchmark.rb` reproduces every table here and the bytes-versus-objects
 comparison above. Its first line names the backend, core version and Ruby it measured, so
-run it again under `HYPERUUID_PURE=1` or `HYPERUUID_WASM=1` for the other two backends.
+run it again under `HYPERUUID_PURE=1` for the other backend.
 
 Real numbers, `benchmark-ips` on Ruby 4.0.7, linux-x64 on an Intel Core i9-11900H (`ruby benchmark/uuid_benchmark.rb`) — not claimed, measured. With the Magnus backend (the default wherever the extension loads):
 
@@ -170,86 +168,33 @@ The multiplier is small on this backend for the best reason available: the indiv
 
 | `HyperUuid::BACKEND` | What runs | Chosen when |
 |---|---|---|
-| `:native` | the core linked into a Magnus extension | a precompiled platform gem carries an extension for this Ruby's ABI — see [Install](#install) |
-| `:fiddle` | `libhyperuuid` for this platform, `dlopen`ed through Fiddle | no extension loads; also the answer when nothing loads at all |
-| `:wasm` | the core as a `wasm32-wasip1` module inside the `wasmtime` gem | no extension and no library for this platform, and `wasmtime` is installed — see [WebAssembly (wasmtime)](#webassembly-wasmtime) |
+| `:native` | the core linked into a Magnus extension | a precompiled platform gem is installed — every one carries an extension for each Ruby it installs on; see [Install](#install) |
+| `:fiddle` | `libhyperuuid` for this platform, `dlopen`ed through Fiddle | no extension loads: the universal gem, on a Ruby or platform no platform gem covers; also the answer when nothing loads at all |
 
-Selection happens once, at `require`, in that order. Two environment variables override it:
+Selection happens once, at `require`, in that order.
 
-| Variable | Effect |
-|---|---|
-| `HYPERUUID_WASM` | forces `:wasm`; `require` raises a `LoadError` naming the gem if `wasmtime` is missing |
-| `HYPERUUID_PURE` | forces `:fiddle`, even where an extension would load |
-
-Both 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. A forced
-backend that turns out to have nothing to load does not fall through to another one: the
-first call raises, and `HyperUuid.available?` answers `false`.
+`HYPERUUID_PURE` forces `:fiddle`, even where an extension would load. It is a testing and
+diagnostic switch — CI runs the whole suite through it, and it is how to rule an extension
+problem in or out — not a setting a deployment needs. It is read for presence, not value: set
+to anything at all, `0` and the empty string included, it forces Fiddle. A forced backend that
+turns out to have nothing to load does not fall through to another one: the first call raises,
+and `HyperUuid.available?` answers `false`. That is what happens inside a platform gem, which
+carries no Fiddle library: the `LoadError` names the universal gem
+(`gem install hyperuuid --platform ruby`, or Bundler's `force_ruby_platform`), where the
+Fiddle backend lives.
 
 **Threads.** Every backend is safe to call from any number of threads. The extension runs
 under the GVL. Fiddle releases the GVL for the duration of each call, so that is the one
 backend where Ruby threads run the core truly in parallel — each through its own scratch
-buffer, with the core's v7 counter shared and atomic. The wasm backend serializes every call
-on one Mutex around one instance. `spec/hyperuuid_spec.rb`'s "concurrent callers" examples
-run under all three.
+buffer, with the core's v7 counter shared and atomic. `spec/hyperuuid_spec.rb`'s "concurrent
+callers" examples run under both.
 
 **Ractors.** Main Ractor only, on every backend: called from another Ractor the doors raise
-`Ractor::UnsafeError` (`Ractor::IsolationError` under wasm).
-
-## WebAssembly (wasmtime)
-
-The Rust core also ships inside this gem as a `wasm32-wasip1` module
-(`lib/hyperuuid/native/wasm32-wasip1/hyperuuid.wasm`), and the
-[`wasmtime`](https://rubygems.org/gems/wasmtime) gem can run it in-process. This is the
-inverse of ruby.wasm — not Ruby inside a wasm sandbox, but a wasm module inside Ruby — and
-it is the one backend that needs no shared library for the platform it runs on: no
-`dlopen`, no Magnus extension, nothing compiled against this Ruby's ABI. Everything above
-`Runtime` (`Uuid`, the module doors, batch slicing) is the same code the other two backends
-run, and `spec/wasm_backend_spec.rb` pins that the outputs agree with the Fiddle backend
-byte for byte.
-
-`wasmtime` is deliberately **not** a dependency of this gem; a consumer who wants this path
-installs it:
-
-```sh
-gem install wasmtime
-HYPERUUID_WASM=1 ruby -rhyperuuid -e 'p HyperUuid::BACKEND'   # => :wasm
-```
-
-`HYPERUUID_WASM=1` forces the backend (and raises a `LoadError` naming the gem if it is
-missing). Without it, the wasm backend is only ever chosen automatically when there is no
-native library for this platform at all — no Magnus extension and no `libhyperuuid` for the
-RID — and `wasmtime` happens to be installed. No supported platform's behavior changes just
-because this backend exists.
-
-Two things are different under the sandbox, both by necessity. A wasm guest only sees its own
-linear memory, so every buffer the core fills comes from the module's own exported `malloc`
-(the same wasi-libc allocator Rust's std uses on that target) and is read back with
-`Memory#read` — using the guest's allocator rather than a host-picked offset is what keeps a
-batch from being clobbered by the guest's next allocation. And a `Wasmtime::Store` is
-single-threaded, so every call is serialized under one Mutex around one shared instance,
-which is also what keeps the core's v7 counter (it lives inside the instance) monotonic
-across threads and batches, exactly as the one dlopen'd library does natively.
-
-Measured, same box and same session as the benchmarks above (Ruby 4.0.7, linux-x64,
-wasmtime 48.0.1), all three backends:
-
-| Call | wasmtime | Fiddle | Magnus |
-|---|---:|---:|---:|
-| `new_v4` | 1.07 µs | 1.26 µs | 234 ns |
-| `new_v7` (explicit ms) | 1.44 µs | 1.47 µs | 284 ns |
-| `new_v7_batch_bytes(1000)` | 22.6 µs | 13.6 µs | 10.4 µs |
-| `new_v7_batch(1000)` → `Uuid` objects | 233 µs | 227 µs | 210 µs |
-
-So a single call costs what it costs on Fiddle, about five times the Magnus extension, and
-the batch doors amortize it the same way they do for Fiddle: the byte batch is twice the
-native cost, and the object batch is nearly the same on all three because building the objects is
-the whole of it. The guest's own work is not where the time goes — the identical module
-fills a thousand UUIDs in 11 µs under GraalWasm's JIT — it is the crossing.
+`Ractor::UnsafeError`.
 
 ## Verifying provenance
 
-Every gem RubyGems.org serves — the universal fallback and each of the five precompiled
+Every gem RubyGems.org serves — the universal fallback and each of the seven precompiled
 platform gems — carries its own GitHub build-provenance attestation, signed directly by
 this repo's own `release.yml` (the `rubygems-publish` job attests `ruby/pkg/*.gem` right
 before the push), so plain `--repo` verifies any of them:
@@ -261,7 +206,7 @@ gh attestation verify hyperuuid-X.Y.Z-<platform>.gem --repo SkunkWerkx/HyperUuid
 
 That's the release's second layer of checking, not the only one: before any gem gets built,
 the same job verifies every native binary it packs — the Fiddle libraries, the Magnus
-extensions (one per Ruby ABI per platform) and the wasm module — against *their own*
+extensions (one per Ruby ABI per platform) — against *their own*
 attestations — those are signed from `SkunkWerkx/.github` by `hyper-build-native.yml`, so
 that check needs `--signer-repo SkunkWerkx/.github` added — and refuses to proceed on an
 unverified one. RubyGems.org has no unpublish and no
@@ -278,15 +223,16 @@ more on why `--signer-repo` is needed for some artifacts here and not others.
 gem install hyperuuid
 ```
 
-Six gems are published per release: one universal `ruby`-platform gem (Fiddle, with every
-platform's native library and the wasm module bundled) plus five precompiled Magnus platform
-gems (`x86_64-linux`, `aarch64-linux`, `arm64-darwin`, `x64-mingw-ucrt`,
-`aarch64-mingw-ucrt`) that `gem install` and `bundle` auto-select when they match. There is
-no `x86_64-darwin` platform gem: an Intel Mac installs the universal gem and runs on Fiddle
-over the bundled `osx-x64` library, as Alpine does. A platform
-gem carries the same libraries and module beside its extensions, so the Fiddle and wasm
-backends are still there behind `HYPERUUID_PURE` and `HYPERUUID_WASM`. No extra configuration
-needed either way.
+Eight gems are published per release: seven precompiled Magnus platform gems that
+`gem install` and `bundle` auto-select when they match — `x86_64-linux-gnu`,
+`aarch64-linux-gnu`, `x86_64-linux-musl`, `aarch64-linux-musl`, `arm64-darwin`,
+`x64-mingw-ucrt` and `aarch64-mingw-ucrt` — and one universal `ruby`-platform gem. A platform gem carries its
+Magnus extensions and nothing else native: no Fiddle library at all. The universal gem is
+the last resort, Fiddle with every platform's native library bundled, and it is what
+RubyGems resolves for a Ruby the platform gems do not cover (3.3, or a Ruby newer than the
+release, such as 4.1 before a release ships for it) and on a platform no platform gem is
+built for — Intel macOS among them, which runs on Fiddle. No extra configuration needed either
+way.
 
 Selection has **two** axes here, unlike every other binding in this repo. A Magnus extension
 is bound to one Ruby minor ABI — there's no `abi3` equivalent to collapse the version axis the
@@ -294,20 +240,20 @@ way [the Python binding's](../python/) wheels do — so each platform gem is a "
 carrying one compiled extension per supported Ruby, under `lib/hyperuuid/<minor>/`, and picks
 one at `require` time:
 
-| Ruby | glibc Linux, macOS, Windows — x64 and arm64 | musl Linux (Alpine) — x64 and arm64 | anywhere else |
-| --- | --- | --- | --- |
-| 4.0 (primary) | Magnus, `BACKEND == :native` | Fiddle | wasm, if `wasmtime` is installed |
-| 3.4 (until its EOL 2028-03-31) | Magnus, `BACKEND == :native` | Fiddle | wasm, if `wasmtime` is installed |
-| 3.3 (the floor) | Fiddle | Fiddle | wasm, if `wasmtime` is installed |
-
-What stands behind each cell: CI runs the whole suite for the first column on every push —
-Magnus on Ruby 3.4 and 4.0, Fiddle and wasm on 4.0, on all five platforms with a CI leg
-(Intel macOS has none) — and the Fiddle
-suite for the musl column inside an Alpine container. The 3.3 row is the same Fiddle code
-path, run with the Docker command under [Development](#development) (Ruby 3.3 with the
-Fiddle 1.1.2 it ships) rather than on every push. The last column — wasm chosen
-automatically because nothing native exists — has no leg of its own: CI runs the wasm
-backend's suite forced, on platforms that have native builds too.
+| Ruby | Linux (glibc and musl), Apple silicon macOS, Windows — x64 and arm64 | Gem installed |
+| --- | --- | --- |
+| a newer Ruby than the release covers (4.1+) | Fiddle | universal |
+| 4.0 (primary) | Magnus, `BACKEND == :native` | platform |
+| 3.4 (until its EOL 2028-03-31) | Magnus, `BACKEND == :native` | platform |
+| 3.3 (the floor, until its EOL 2027-03-31) | Fiddle | universal |
+
+What stands behind each cell: CI runs the whole suite through each Magnus extension on every
+push — Ruby 3.4 and 4.0 on all seven platform-gem platforms, the two musl ones inside each
+Ruby's own Alpine image — and the Fiddle suite on Ruby 4.0 on every one of them, plus on Ruby
+3.3 inside Alpine. Intel macOS has no CI leg: its library is cross-built and tested at the
+core, and Ruby there runs the universal gem's Fiddle backend over it. Anywhere else — a platform with no native build at
+all — the universal gem installs but `HyperUuid.available?` answers `false`, and the first
+call raises `HyperUuid::NativePlatform::UnsupportedPlatformError`.
 
 The platform gems declare `required_ruby_version >= 3.4, < 4.1` precisely so RubyGems
 *declines* them outside that range and resolves the universal gem instead — a wrong-ABI
@@ -318,15 +264,13 @@ don't link libruby at all, so one can load successfully against the wrong ABI an
 later. When 3.4 goes EOL it simply leaves the matrix and its users fall back to Fiddle, which
 is exactly what the fallback is for.
 
-**musl.** RubyGems does not tell musl from glibc for these gems: on Alpine, `gem install`
-picks the `x86_64-linux` or `aarch64-linux` platform gem exactly as it does on any other
-Linux (checked with RubyGems 4.0.20 on `x86_64-linux-musl`). The Magnus extension inside is
-linked against glibc and cannot load there — `require` fails cleanly on the missing
-`ld-linux` loader — so the gem falls back to Fiddle, which loads the musl build of the core
-(`native/linux-musl-x64` or `native/linux-musl-arm64`, chosen from `RUBY_PLATFORM`) that
-every gem carries. Alpine therefore works as installed, on the Fiddle backend and at Fiddle's
-speed. Releases through 0.3.0 carried no musl library: there the fallback found only the
-glibc one, and the first call raised `Fiddle::DLError`.
+**musl.** Alpine has platform gems of its own, `x86_64-linux-musl` and
+`aarch64-linux-musl`, whose extensions are built inside each Ruby's official `ruby:*-alpine`
+image and need nothing beyond musl's libc. The glibc gems name their libc too
+(`x86_64-linux-gnu`, `aarch64-linux-gnu`), which is what makes both `gem install` and
+Bundler pick the right one on every supported Ruby: next to a plain `x86_64-linux` gem,
+RubyGems before 4.0 resolves that one on Alpine instead, even under
+`--platform x86_64-linux-musl`.
 
 **Nothing in this gem is ever compiled, on any platform.** Its one dependency can be:
 `fiddle` is a bundled gem on Ruby 4.0 and a default gem on 3.3 and 3.4, and `gem install` is
@@ -353,7 +297,7 @@ forge's `ruby-magnus` action (`build-magnus.sh`), shared with every other Hyper*
 ## Development
 
 Everything below runs from a checkout, with `rust/` beside `ruby/`; none of it is needed to
-use the gem. The Fiddle and wasm backends find the in-repo builds on their own when nothing
+use the gem. The Fiddle backend finds the in-repo build on its own when nothing
 is staged under `lib/hyperuuid/native/`. The Magnus backend does not — an extension has to be
 built for the Ruby you are running and put where `require` looks — and that is what
 `rake native:dev` is for.
@@ -361,14 +305,12 @@ built for the Ruby you are running and put where `require` looks — and that is
 ```sh
 cd rust
 cargo cdylib                           # libhyperuuid, what the Fiddle backend loads
-cargo wasm-module                      # hyperuuid.wasm, what the wasm backend loads
 
 cd ../ruby
 bundle install
 bundle exec rake native:dev          # build the Magnus extension for this Ruby and stage it
 bundle exec rspec                    # BACKEND == :native
 HYPERUUID_PURE=1 bundle exec rspec   # BACKEND == :fiddle
-HYPERUUID_WASM=1 bundle exec rspec   # BACKEND == :wasm
 bundle exec rake docs:check          # every public object carries a doc comment
 ruby benchmark/uuid_benchmark.rb     # prints the backend it measured
 ```
@@ -403,8 +345,8 @@ docker run --rm -v "$PWD/..":/src:ro ruby:4.0-alpine sh -euc '
   mkdir -p /work/ruby/lib/hyperuuid/native/linux-musl-x64
   cp /src/rust/target/musl/linux-musl-x64/libhyperuuid.so /work/ruby/lib/hyperuuid/native/linux-musl-x64/
   cd /work/ruby && rm -f Gemfile.lock
-  BUNDLE_WITHOUT=wasm bundle install --quiet --prefer-local
-  HYPERUUID_PURE=1 BUNDLE_WITHOUT=wasm bundle exec rspec'
+  bundle install --quiet --prefer-local
+  HYPERUUID_PURE=1 bundle exec rspec'
 ```
 
 The floor's test is the same container on `ruby:3.3-alpine`. Bundler would compile a newer
@@ -421,6 +363,11 @@ docker run --rm -v "$PWD/..":/src:ro ruby:3.3-alpine sh -euc '
   HYPERUUID_PURE=1 rspec'
 ```
 
+The musl Magnus extension is built the way CI builds it by the forge's
+`ruby-magnus-musl/build-magnus-musl.sh`, which runs on any machine with Docker: from the repo
+root, `build-magnus-musl.sh hyperuuid linux-musl-x64 4.0 . <dir with the musl libhyperuuid.so> <out-dir>`
+compiles it in `ruby:4.0-alpine`, then runs this suite through it on a bare copy of that image.
+
 See [the repo root README](../README.md) for the full RFC 9562 coverage table and the state of every other language binding.
 
 ## License

data/lib/hyperuuid/runtime.rb

@@ -2,15 +2,13 @@ require "fiddle"
 
 module HyperUuid
   # Fiddle plumbing for the native libhyperuuid shared library — dlopen/dlsym plus a raw
-  # C-ABI call, no runtime bridge (the same "no shim" positioning as the Go/Swift bindings'
-  # purego/dlopen approach). Fiddle ships with every Ruby install; it's a plain gem
-  # dependency here (see hyperuuid.gemspec) rather than a third-party one — mirroring Go's
-  # "no cgo" and Python's zero-dependency PyO3 wheels.
+  # C-ABI call, no runtime bridge (the same "no shim" positioning as the Swift binding's
+  # dlopen approach). Fiddle ships with every Ruby install; it's a plain gem dependency here
+  # (see hyperuuid.gemspec) rather than a third-party one — mirroring Python's
+  # zero-dependency PyO3 wheels.
   #
-  # Unlike the Go/Swift bindings, which embed their native builds inside a single compiled
-  # archive and must extract to a temp file before dlopen can see a real path, a Ruby gem's
-  # files are already plain files on disk once installed — native/{rid}/{lib} can be
-  # dlopen'd directly, no extraction step needed.
+  # A Ruby gem's files are plain files on disk once installed, so native/{rid}/{lib} can be
+  # dlopen'd directly, with no extraction step.
   module Runtime
     # The package's two exceptions live on HyperUuid itself (errors.rb). These are the names
     # they had through 0.3.0, kept as aliases of the very same classes so a
@@ -19,7 +17,7 @@ module HyperUuid
     RandomSourceError = HyperUuid::RandomSourceError
     TimestampOutOfRangeError = HyperUuid::TimestampOutOfRangeError
 
-    # One copy of each out-of-range message for the Fiddle and wasm backends and for the
+    # 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"
@@ -128,16 +126,6 @@ module HyperUuid
         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, 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?
-        !library_path.nil?
-      rescue NativePlatform::UnsupportedPlatformError
-        false
-      end
-
       private
 
       # The shared library to dlopen: this install's native/{rid}/{lib}, or — the
@@ -153,6 +141,35 @@ module HyperUuid
         File.exist?(repo_build) ? repo_build : nil
       end
 
+      # Why Fiddle found nothing to load. A precompiled platform gem is the one install where
+      # that is by design rather than a gap: it carries only its Magnus extensions, and the
+      # Fiddle backend is reached there only by forcing it (HYPERUUID_PURE) or because none
+      # of its extensions loaded — a gem RubyGems matched to a Ruby it was not built for,
+      # such as the glibc Linux gem that `gem install` on RubyGems 3.x picks on Alpine. So
+      # that case names its fix, the universal gem, which carries every platform's library,
+      # instead of a missing path that reads like a packaging bug. Both arguments are
+      # parameters only so the specs can ask for every wording.
+      def missing_library_message(gem_platform = Gem.loaded_specs["hyperuuid"]&.platform,
+                                  forced = ENV.key?("HYPERUUID_PURE"))
+        rid, lib_name = NativePlatform.rid_and_library_name
+        missing = File.join(NATIVE_DIR, rid, lib_name)
+        if gem_platform && gem_platform.to_s != Gem::Platform::RUBY
+          reason =
+            if forced
+              "HYPERUUID_PURE forces the Fiddle backend (unset it to use the extension)"
+            else
+              "none of its extensions loads on this Ruby (#{RUBY_VERSION}, #{RUBY_PLATFORM})"
+            end
+          "hyperuuid: this #{gem_platform} platform gem carries only Magnus extensions, no " \
+            "Fiddle library, and #{reason}. The universal gem has the Fiddle backend for every " \
+            "platform: `gem install hyperuuid --platform ruby`, or Bundler's force_ruby_platform " \
+            "(#{missing} not found)"
+        else
+          "hyperuuid: #{missing} not found (unsupported platform, or this gem was built " \
+            "without a native library for it)"
+        end
+      end
+
       # One 16-byte scratch allocation per thread, reused by every single-item call —
       # Fiddle::Pointer.malloc(..., RUBY_FREE) registers a GC finalizer per call, measured
       # (in HyperCast, same mechanism) as the dominant per-call cost by an order of
@@ -170,7 +187,7 @@ module HyperUuid
         buf[0, 16]
       end
 
-      # Loaded lazily and exactly once, mirroring the Go binding's sync.Once / Swift's lazy
+      # Loaded lazily and exactly once, mirroring Java's class initializer / Swift's lazy
       # static let — the native library and its function pointers live for the process's
       # lifetime, same as every other binding (never dlclose'd). The unsynchronized read is
       # the hot path; the mutex only guards the one-time load (a benign race — idempotent).
@@ -180,12 +197,7 @@ module HyperUuid
 
       def load_functions
         path = library_path
-        if path.nil?
-          rid, lib_name = NativePlatform.rid_and_library_name
-          raise LoadError,
-                "hyperuuid: #{File.join(NATIVE_DIR, rid, lib_name)} not found (unsupported " \
-                "platform, or this gem was built without a native library for it)"
-        end
+        raise LoadError, missing_library_message if path.nil?
 
         handle = Fiddle.dlopen(path)
         {

data/lib/hyperuuid/uuid.rb

@@ -1,7 +1,7 @@
 module HyperUuid
   # A parsed 16-byte RFC 9562 UUID value. Minimal by design — this gem has no runtime
   # dependency on the `uuid` gem, the same "no extra dependency" positioning as the Go
-  # binding's purego-only/no-cgo approach and the Python binding's dependency-free PyO3
+  # binding's lone google/uuid requirement and the Python binding's dependency-free PyO3
   # wheels.
   class Uuid
     include Comparable

data/lib/hyperuuid.rb

@@ -5,12 +5,11 @@ 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 three backends this install can load: the core
+# 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),
-# 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
+# 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
@@ -19,7 +18,7 @@ require_relative "hyperuuid/runtime"
 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.5.0"
+  VERSION = "0.6.0"
 
   # The widest batch count, and the longest v5 name in bytes, the native ABI carries (a u32).
   # (The millisecond count is a u64; unix_millis_from refuses anything wider.)
@@ -62,7 +61,7 @@ module HyperUuid
   # 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.
+  # value from Fiddle.
   #
   # The two common arguments go first and cheapest: no argument is the clock, which needs no
   # range check, and an Integer is checked by its bit length rather than against 2**64 - 1: a
@@ -185,11 +184,10 @@ module HyperUuid
   # 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.
+  # raises: a missing shared library, an unsupported platform, or an older core without the
+  # version export all answer false. The doors themselves keep their own behavior — the
+  # first call on an unavailable backend raises its precise error — this only answers the
+  # question quietly.
   def self.available?
     return @available unless @available.nil?
 
@@ -205,31 +203,18 @@ end
 # above in place (no delegation layer) — Fiddle's measured per-call marshalling floor drops
 # to an ordinary extension call, while everything above Runtime (Uuid, the module doors,
 # batch slicing) stays shared byte-for-byte between backends. The pure-Fiddle definitions
-# remain the universal zero-compile fallback; precompiled platform gems are how the
-# extension ships without ever making a consumer compile anything. Set HYPERUUID_PURE=1 to
-# force Fiddle.
+# remain the universal zero-compile fallback — the last resort, for a Ruby or a platform no
+# platform gem covers; precompiled platform gems are how the extension ships without ever
+# making a consumer compile anything, and they carry no Fiddle library at all.
 #
-# The third backend is WebAssembly (lib/hyperuuid/wasm_runtime.rb): the same core as a
-# wasm32-wasip1 module, run in-process by the `wasmtime` gem, which is deliberately not a
-# runtime dependency of this gem — a consumer who wants it installs it. HYPERUUID_WASM=1
-# 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_PURE forces Fiddle. It is a testing and diagnostic switch — CI runs the whole suite
+# through it, and it is how a suspected extension bug is ruled in or out — not a setting a
+# deployment needs. It is read for presence, not value, so "0" and the empty string force it
+# too. Inside a platform gem there is no library for it to load: BACKEND still reads :fiddle,
+# HyperUuid.available? answers false, and the first door call raises a LoadError naming the
+# universal gem, which is where the Fiddle backend lives.
 HyperUuid::BACKEND =
-  if ENV["HYPERUUID_WASM"]
-    begin
-      require "wasmtime"
-    rescue LoadError
-      raise LoadError,
-            "hyperuuid: HYPERUUID_WASM=1 needs the wasmtime gem — `gem install wasmtime` (or add it to your Gemfile)"
-    end
-    require_relative "hyperuuid/wasm_runtime"
-    :wasm
-  elsif ENV["HYPERUUID_PURE"]
+  if ENV["HYPERUUID_PURE"]
     :fiddle
   else
     # Two layouts, and both have to work. A released platform gem is a "fat" gem carrying one
@@ -243,7 +228,11 @@ HyperUuid::BACKEND =
     # 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.
+    # precompiled extension, which is precisely what the Fiddle backend below is for. A
+    # platform with no shared library either still lands on Fiddle, so the first call raises
+    # its own precise error — a "not found" LoadError naming the path, or
+    # NativePlatform::UnsupportedPlatformError naming the platform. HyperUuid.available? is
+    # the quiet way to ask.
     begin
       require "hyperuuid/#{RUBY_VERSION[/\d+\.\d+/]}/hyperuuid_native"
       :native
@@ -252,22 +241,7 @@ HyperUuid::BACKEND =
         require "hyperuuid_native"
         :native
       rescue LoadError
-        if HyperUuid::Runtime.fiddle_library_available?
-          :fiddle
-        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 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"
-            :wasm
-          rescue LoadError
-            :fiddle
-          end
-        end
+        :fiddle
       end
     end
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hyperuuid
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Brian Buvinghausen
@@ -53,11 +53,10 @@ dependencies:
         version: '0.9'
 description: |
   RFC 9562 UUID v4 (random), v5 (deterministic), v6 and v7 (time-sortable) generation, with
-  batch and raw-bytes forms, from one native Rust core. Three backends behind one surface,
-  selected automatically and all shipped prebuilt: a Magnus extension where a precompiled
-  platform gem matches, stdlib Fiddle everywhere else, and the same core as a WebAssembly
-  module for anyone who installs the wasmtime gem. No runtime bridge, no dependencies
-  beyond Fiddle.
+  batch and raw-bytes forms, from one native Rust core. Two backends behind one surface,
+  selected automatically and both shipped prebuilt: a Magnus extension where a precompiled
+  platform gem matches, and stdlib Fiddle everywhere else. No runtime bridge, no
+  dependencies beyond Fiddle.
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -73,13 +72,11 @@ files:
 - lib/hyperuuid/native/linux-x64/libhyperuuid.so
 - lib/hyperuuid/native/osx-arm64/libhyperuuid.dylib
 - lib/hyperuuid/native/osx-x64/libhyperuuid.dylib
-- lib/hyperuuid/native/wasm32-wasip1/hyperuuid.wasm
 - lib/hyperuuid/native/win-arm64/hyperuuid.dll
 - lib/hyperuuid/native/win-x64/hyperuuid.dll
 - lib/hyperuuid/native_platform.rb
 - lib/hyperuuid/runtime.rb
 - lib/hyperuuid/uuid.rb
-- lib/hyperuuid/wasm_runtime.rb
 homepage: https://github.com/SkunkWerkx/HyperUuid
 licenses:
 - MIT

data/lib/hyperuuid/wasm_runtime.rb

@@ -1,259 +0,0 @@
-require "wasmtime"
-
-module HyperUuid
-  # The WebAssembly backend: the same Rust core, compiled once to a `wasm32-wasip1` module
-  # (lib/hyperuuid/native/wasm32-wasip1/hyperuuid.wasm) and run inside this process by the
-  # `wasmtime` gem — no per-platform shared library needed, and nothing dlopen'd. This is the
-  # inverse of ruby.wasm: not Ruby running inside a wasm sandbox, but a wasm module running
-  # inside Ruby.
-  #
-  # 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 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:
-  #
-  # * A wasm guest only sees its own linear memory, so no Fiddle::Pointer can cross. Every
-  #   buffer the core writes into is obtained from the module's own exported `malloc` (the
-  #   wasi-libc allocator Rust's std already uses on this target) and read back with
-  #   `Memory#read`. Using the guest's allocator rather than a host-picked offset is
-  #   load-bearing: dlmalloc claims the tail of the initial memory on first use, and a batch
-  #   written at a guessed offset was observed corrupted by the guest's next allocation.
-  # * A `Wasmtime::Store` is single-threaded, so every call is serialized under one Mutex.
-  #   One shared instance per process is also what keeps the core's v7 counter — which lives
-  #   inside the instance — monotonic across threads and batches, exactly as the one dlopen'd
-  #   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
-    # the process. Batches and v5 names get a `malloc`/`free` pair per call instead — one
-    # allocation amortized over `count` IDs, the same shape as the Fiddle backend's per-batch
-    # Pointer.malloc.
-    class WasmInstance
-      attr_reader :memory, :in, :out
-
-      EXPORTS = %i[
-        malloc free
-        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)"
-        end
-
-        engine = Wasmtime::Engine.new
-        mod = Wasmtime::Module.from_file(engine, path)
-        linker = Wasmtime::Linker.new(engine)
-        # The module imports five WASI preview1 functions (random_get is the one that
-        # matters: it is the core's only entropy source; the rest are wasi-libc's startup
-        # plumbing). A default WasiConfig — no stdio, no filesystem, no environment — is all
-        # any of them need.
-        Wasmtime::WASI::P1.add_to_linker_sync(linker)
-        store = Wasmtime::Store.new(engine, wasi_p1_config: Wasmtime::WasiConfig.new)
-        instance = linker.instantiate(store, mod)
-
-        @memory = instance.export("memory").to_memory
-        @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
-
-      def fn(name)
-        @fn.fetch(name)
-      end
-
-      def malloc(size)
-        ptr = @fn[:malloc].call(size)
-        raise NoMemoryError, "hyperuuid: wasm malloc(#{size}) failed" if ptr.zero?
-        ptr
-      end
-
-      def free(ptr)
-        @fn[:free].call(ptr)
-      end
-
-      # Runs `block` with a `size`-byte guest buffer, freeing it afterwards even on error.
-      def with_buffer(size)
-        ptr = malloc(size)
-        begin
-          yield ptr
-        ensure
-          free(ptr)
-        end
-      end
-    end
-
-    @wasm_mutex = Mutex.new
-    @wasm = nil
-
-    class << self
-      def new_v4
-        wasm do |w|
-          rc = w.fn(:uuid_new_v4).call(w.out)
-          raise random_source_failure("uuid_new_v4") unless rc.zero?
-          w.memory.read(w.out, 16)
-        end
-      end
-
-      def new_v5(namespace_bytes, name_bytes)
-        wasm do |w|
-          w.memory.write(w.in, namespace_bytes)
-          # A zero-length name still needs a valid (non-null) pointer inside the guest —
-          # the `in` scratch, already holding the namespace, serves; nothing reads past
-          # a zero length.
-          rc =
-            if name_bytes.empty?
-              w.fn(:uuid_new_v5).call(w.in, w.in, 0, w.out)
-            else
-              w.with_buffer(name_bytes.bytesize) do |name|
-                w.memory.write(name, name_bytes)
-                w.fn(:uuid_new_v5).call(w.in, name, name_bytes.bytesize, w.out)
-              end
-            end
-          raise random_source_failure("uuid_new_v5") unless rc.zero?
-          w.memory.read(w.out, 16)
-        end
-      end
-
-      def new_v6(unix_millis)
-        wasm do |w|
-          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, V6_TIMESTAMP_OUT_OF_RANGE
-          else raise random_source_failure("uuid_new_v6")
-          end
-        end
-      end
-
-      def v6_unix_millis(bytes)
-        wasm do |w|
-          w.memory.write(w.in, bytes)
-          u64(w.fn(:uuid_v6_unix_millis).call(w.in))
-        end
-      end
-
-      def new_v6_batch(count, unix_millis)
-        return "" if count.zero?
-        wasm do |w|
-          w.with_buffer(count * 16) do |out|
-            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, V6_TIMESTAMP_OUT_OF_RANGE
-            else raise random_source_failure("uuid_new_v6_batch")
-            end
-          end
-        end
-      end
-
-      def new_v7(unix_millis)
-        wasm do |w|
-          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, V7_TIMESTAMP_OUT_OF_RANGE
-          else raise random_source_failure("uuid_new_v7")
-          end
-        end
-      end
-
-      def v7_unix_millis(bytes)
-        wasm do |w|
-          w.memory.write(w.in, bytes)
-          u64(w.fn(:uuid_v7_unix_millis).call(w.in))
-        end
-      end
-
-      def new_v7_batch(count, unix_millis)
-        return "" if count.zero?
-        wasm do |w|
-          w.with_buffer(count * 16) do |out|
-            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, V7_TIMESTAMP_OUT_OF_RANGE
-            else raise random_source_failure("uuid_new_v7_batch")
-            end
-          end
-        end
-      end
-
-      def v7_to_sql_order(bytes)
-        rewrite(:uuid_v7_to_sql_order, bytes)
-      end
-
-      def v7_to_rfc_order(bytes)
-        rewrite(:uuid_v7_to_rfc_order, bytes)
-      end
-
-      def v6_to_sql_order(bytes)
-        rewrite(:uuid_v6_to_sql_order, bytes)
-      end
-
-      def v6_to_rfc_order(bytes)
-        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,
-      # let the core rewrite them there, read the result back.
-      def rewrite(export, bytes)
-        wasm do |w|
-          w.memory.write(w.in, bytes)
-          w.fn(export).call(w.in)
-          w.memory.read(w.in, 16)
-        end
-      end
-
-      # Every call holds the one lock: the Store is single-threaded, and the lazily created
-      # instance is shared by every thread for the life of the process (never torn down,
-      # same as the dlopen'd library natively).
-      def wasm
-        @wasm_mutex.synchronize do
-          @wasm ||= WasmInstance.new(WASM_MODULE_PATH)
-          yield @wasm
-        end
-      end
-
-      # 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. 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
-
-      def u64(value)
-        value.negative? ? value + 2**64 : value
-      end
-    end
-  end
-end