hypercast 0.4.0 → 0.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 319ce95965918c4804c0ebbd9183e93d5ca2e53d50ada708706faef12507d344
-  data.tar.gz: d750c75771186f9b218530fcc29de061d3462efcd1cf81b0a524860b11b87b98
+  metadata.gz: 53866363cee28bda9e47267c85d4c835708fb9aa20635c3968cb32985d12c264
+  data.tar.gz: 654ae196935c0fb5cb8b0393ad11c1a5c5f52845321d1ac6468dfc4dc3159663
 SHA512:
-  metadata.gz: c86acda45e6c9aa7044ac2c2671854d3f43a340ab9b0269c0220342454340517c049148865ad657df47ed32b57261ea2cfa1470d5e35b014407041b7e6d075e5
-  data.tar.gz: c89ea288c80ebaaffc0071ed61ed376e8fa8656d1b88da83f1c04c05f2bd589fff901f54fb79dc6024f0aa4389e3c67c0a24a5964acf0cbcccc8388e731f447c
+  metadata.gz: 5fb20b6b023d88e80fc8ea334925310b5436c3aaca0ebcf86606f8794da375823019cc0efbf60445472bdcf6cee4cefd8f76eeb1475d87e3cbead7e26988d8e3
+  data.tar.gz: f51ff3c89feaaa99f38fec564f779364b358f1ba7f76c783e24202890e751183172df49352c7eeef6caf8bf54edf10b0493c8d453981e3136dd40791d969d31a

data/README.md

@@ -5,18 +5,19 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/SkunkWerkx/HyperCast/blob/master/LICENSE)
 
 **Ruby's own pattern matching over two `Data` case types — the value, or a closed reason
-Symbol plus the exact span that offended. Three backends, one public surface: a Magnus
-native extension where a precompiled platform gem covers you, stdlib Fiddle everywhere
-else — selected automatically, zero compiles either way — and the same core as a
-WebAssembly module inside the `wasmtime` gem for any platform with no native build at all.**
+Symbol plus the exact span that offended. Two backends, one public surface: a Magnus
+native extension where a precompiled platform gem covers you, stdlib Fiddle as the last
+resort everywhere else — selected automatically, zero compiles either way.**
 
 Allocation-lean scalar casts — booleans, the full integer family, reals, exact decimals,
 UUIDs, temporals — calling directly into the native `libhypercast` Rust core. Ruby 3.3 is the
 floor. The fast path links the core straight into a Ruby extension (Magnus): on require it
 redefines the doors in place on the `HyperCast` module — no delegation layer, no second
 surface, which is exactly what keeps the backends provably in agreement.
-`HyperCast::BACKEND` reports which is live; `HYPERCAST_PURE=1` forces Fiddle,
-`HYPERCAST_WASM=1` the wasm module — see [Backends](#backends).
+The last-resort fallback, in the universal gem only, calls the native `libhypercast` shared
+library via [`Fiddle`](https://docs.ruby-lang.org/en/master/Fiddle.html) — dlopen/dlsym plus
+raw C-ABI calls, no runtime bridge. `HyperCast::BACKEND` reports which one is live;
+`HYPERCAST_PURE=1` forces Fiddle for testing — see [Backends](#backends).
 
 ```ruby
 case HyperCast.i32("(1,234)", HyperCast::NumFormat::INVARIANT)
@@ -87,7 +88,9 @@ mismatch against `HyperCast::VERSION` can be named before the first cast.
 `HyperCast::BACKEND` says which backend was *selected*, which is not the same question: it
 reads `:fiddle` on a platform with no library at all, because that is the backend whose
 first call explains what is missing — a `LoadError` naming the path it looked for, or
-`HyperCast::NativePlatform::UnsupportedPlatformError` naming the platform.
+`HyperCast::NativePlatform::UnsupportedPlatformError` naming the platform. Inside a platform
+gem, which carries no Fiddle library, that `LoadError` names the universal gem instead (see
+[Backends](#backends)).
 
 ### Fault spans index the String you passed
 
@@ -161,9 +164,9 @@ and memoized by identity on every backend, so declaring a currency costs a cast
    parentheses, declared separators, radix prefixes, all five .NET `Guid` text forms plus
    `urn:uuid:` prefixes, protobuf JSON durations.
 3. **One engine across a polyglot system** — bit-for-bit verdicts with every other binding,
-   held by the shared corpus (the whole suite green on *all three* backends, full
-   corpus replay; cross-backend agreement specs compare Magnus against Fiddle
-   and wasm against Fiddle across a subprocess boundary).
+   held by the shared corpus (the whole suite green on both backends, full corpus replay;
+   cross-backend agreement specs compare Magnus against Fiddle across a subprocess
+   boundary).
 4. **Faster than the stdlib on the Magnus backend, where the carrier is cheap** —
    benchmark-ips (`ruby benchmark/cast_benchmark.rb`, linux-x64 on an Intel Core
    i9-11900H, Ruby 4.0.7): timestamp **447 ns vs 2.97 µs `Time.iso8601`** (6.6x) — while
@@ -201,23 +204,23 @@ receipts include their own archaeology.)
 
 `ruby benchmark/cast_benchmark.rb` pairs each door with Ruby's closest stdlib parse. Its
 first line names the backend, core version and Ruby it measured, so run it again under
-`HYPERCAST_PURE=1` or `HYPERCAST_WASM=1` for the other two backends. The stdlib comparisons
-are in [the section above](#why-not-integer--timeiso8601--float); this is the three backends
-against each other.
-
-Measured on Ruby 4.0.7, linux-x64 (an Intel Core i9-11900H), wasmtime 48.0.1,
-`benchmark-ips`, same session, all three backends:
-
-| Door | Magnus | Fiddle | wasmtime |
-|---|---:|---:|---:|
-| `bool` | 112 ns | 2.35 µs | 1.75 µs |
-| `i32` | 133 ns | 2.63 µs | 1.80 µs |
-| `f64` | 166 ns | 2.70 µs | 1.84 µs |
-| `uuid` | 223 ns | 3.47 µs | 2.65 µs |
-| `timestamp` | 447 ns | 3.25 µs | 2.42 µs |
-| `datetime` (`1/7/2026 3:04 PM`) | 904 ns | 3.98 µs | 3.14 µs |
-| `duration` (ISO) | 632 ns | 2.91 µs | 2.10 µs |
-| `i32`, a fault | 225 ns | 3.18 µs | 2.50 µs |
+`HYPERCAST_PURE=1` for the other backend. The stdlib comparisons are in
+[the section above](#why-not-integer--timeiso8601--float); this is the two backends against
+each other.
+
+Measured on Ruby 4.0.7, linux-x64 (an Intel Core i9-11900H), `benchmark-ips`, same session,
+both backends:
+
+| Door | Magnus | Fiddle |
+|---|---:|---:|
+| `bool` | 112 ns | 2.35 µs |
+| `i32` | 133 ns | 2.63 µs |
+| `f64` | 166 ns | 2.70 µs |
+| `uuid` | 223 ns | 3.47 µs |
+| `timestamp` | 447 ns | 3.25 µs |
+| `datetime` (`1/7/2026 3:04 PM`) | 904 ns | 3.98 µs |
+| `duration` (ISO) | 632 ns | 2.91 µs |
+| `i32`, a fault | 225 ns | 3.18 µs |
 
 A lean door on the Magnus backend is little more than the native call: the extension builds
 the `Success` or `Fault` it returns directly — allocated, its members stored, frozen —
@@ -227,84 +230,34 @@ rather than through `Data.new`, whose keyword handling alone cost more than the
 
 | `HyperCast::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` | `libhypercast` 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) — or the `hypercast-wasm` gem is linked into a ruby.wasm interpreter; see [Ruby in the browser](#ruby-in-the-browser) |
+| `:fiddle` | `libhypercast` 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 |
-|---|---|
-| `HYPERCAST_WASM` | forces `:wasm`; `require` raises a `LoadError` naming the gem if `wasmtime` is missing |
-| `HYPERCAST_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 `HYPERCAST_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 `HyperCast.available?` answers `false`.
+`HYPERCAST_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 `HyperCast.available?` answers `false`. That is what happens inside a platform gem, which
+carries no Fiddle library: the `LoadError` names the universal gem
+(`gem install hypercast --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
-buffers; the core itself keeps no state between calls. The wasm backend serializes every call
-on one Mutex around one instance. `spec/cast_spec.rb`'s concurrent-callers example runs under
-all three.
+buffers; the core itself keeps no state between calls. `spec/cast_spec.rb`'s
+concurrent-callers example runs 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/hypercast/native/wasm32-wasip1/hypercast.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. The Magnus
-extension replaces every public door in place; this backend replaces only the four private
-bodies underneath them (`plain`, `numeric`, `declared`, `packed_version` — the whole native
-crossing), so every door, both verdict `Data` types, the Symbol tables and the
-`Time`/`DateTime`/`Rational`/`Decimal` carriers are the exact code the other two backends
-run. `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
-HYPERCAST_WASM=1 ruby -rhypercast -e 'p HyperCast::BACKEND'   # => :wasm
-```
-
-`HYPERCAST_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 `libhypercast` 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 the input is copied into a grow-only guest buffer and the out-value, fault
-span and `NumFormat` live in guest allocations made once at load — all from the module's own
-exported `malloc` (the same wasi-libc allocator Rust's std uses on that target), read back
-with `Memory#read`; using the guest's allocator rather than a host-picked offset is what keeps
-a buffer 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.
-
-Measured against the other two backends in the same session — the `wasmtime` column of the
-table under [Benchmarks](#benchmarks).
-
-The finding worth stating: in Ruby the wasm backend is no slower than Fiddle, and on the
-x64 box that table comes from it is the faster of the two on every door, by a fifth to a
-third. Fiddle's per-call floor is interpreted marshalling; wasmtime's is the host-to-guest
-crossing plus the guest memory copies; on the lean doors wasmtime sits eleven to sixteen
-times behind the Magnus extension and Fiddle sixteen to twenty-one, narrowing to three to
-five times where building the Ruby value dominates. So on a platform with no native build, the fallback costs a consumer nothing
-they were not already paying on the universal gem.
+`Ractor::UnsafeError`.
 
 ## Verifying provenance
 
-Every gem RubyGems.org serves — the universal fallback and each of the five precompiled
-platform gems — carries its own GitHub build-provenance attestation, signed directly by
+Every gem RubyGems.org serves — the universal fallback, each of the seven precompiled
+platform gems and `hypercast-wasm` — 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:
 
@@ -315,8 +268,9 @@ gh attestation verify hypercast-X.Y.Z-<platform>.gem --repo SkunkWerkx/HyperCast
 
 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*
-attestations — those are signed from `SkunkWerkx/.github` by `hyper-build-native.yml`, so
+extensions (one per Ruby ABI per platform), the `wasm32-wasip1` archives — against *their own*
+attestations — those are signed from `SkunkWerkx/.github` by `hyper-build-native.yml` and
+`hyper-build-wasm.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 duplicate-version overwrite, so this all happens while a
@@ -332,15 +286,16 @@ more on why `--signer-repo` is needed for some artifacts here and not others.
 gem install hypercast
 ```
 
-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 `HYPERCAST_PURE` and `HYPERCAST_WASM`. No extra configuration
-needed either way.
+Nine gems are published per release. This section is about eight of them: 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. The ninth, `hypercast-wasm`, is only for ruby.wasm; see [Ruby in the browser](#ruby-in-the-browser).
 
 Selection has **two** axes here, unlike every other binding in this repo. A Magnus extension
 is bound to one Ruby minor ABI — there is no `abi3` equivalent to collapse the version axis
@@ -348,19 +303,21 @@ the way [the Python binding's](../python/) wheels do — so each platform gem is
 carrying one compiled extension per supported Ruby, under `lib/hypercast/<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 replays the whole suite, shared corpus included, 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 replays the whole suite, shared corpus included, 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 `HyperCast.available?` answers `false`, and the first call raises
+`HyperCast::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
@@ -371,24 +328,25 @@ link libruby at all, so one can load successfully against the wrong ABI and misb
 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, `HyperCast.available?` answered `false`, and the first cast raised
-`Fiddle::DLError`.
-
-**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
-satisfied by the copy Ruby ships. Bundler resolves the newest `fiddle` on rubygems.org
-instead, and when that is newer than the one your Ruby ships — true today on 3.3 and 3.4, not
-on 4.0 — it builds Fiddle's own C extension, which takes a compiler and libffi's headers
-(`apk add build-base libffi-dev` on Alpine). Holding `fiddle` at your Ruby's version in the
-`Gemfile.lock` avoids that.
+**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.** The platform gems depend on nothing
+at all. The universal gem depends on `fiddle`, which 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 satisfied by the copy Ruby ships.
+Bundler resolves the newest `fiddle` on rubygems.org instead, and when that is newer than the
+one your Ruby ships — true today on 3.3 and 3.4, not on 4.0 — it builds Fiddle's own C
+extension, which takes a compiler and libffi's headers (`apk add build-base libffi-dev` on
+Alpine). That only reaches you where the universal gem installs: Ruby 3.3, Intel macOS, a
+Ruby newer than the release, or a platform with no platform gem. `bundle install
+--prefer-local` makes Bundler use the copy Ruby ships where it can (it did on Ruby 3.4's
+Bundler 2.6, not on 3.3's 2.5); otherwise install the compiler and headers. Pinning `fiddle`
+to your Ruby's version in the `Gemfile.lock` does not stop the build.
 
 Both Windows architectures get a Magnus gem, and the reasoning that once kept them on Fiddle
 was backwards: MinGW is the *only* Windows flavour `rb-sys` targets (`x64-mingw-ucrt` and
@@ -401,25 +359,77 @@ the shipped extension small. The build script, and the two flags that are load-b
 the ARM leg (a static libunwind, and a clang-spelled `--target` for bindgen), live in the
 forge's `ruby-magnus` action (`build-magnus.sh`), shared with every other Hyper* repo.
 
+## Ruby in the browser
+
+ruby.wasm cannot load an extension at runtime. `rbwasm build` cross-compiles the extension of
+every gem in a Gemfile and links them all into the one interpreter it builds, so the browser
+gets a gem of its own: `hypercast-wasm`, the same library and the same Magnus extension,
+prebuilt for `wasm32-wasip1`. List it **instead of** `hypercast` in the Gemfile you build the
+interpreter from (the two carry the same `lib/` files):
+
+```ruby
+source "https://rubygems.org"
+
+gem "hypercast-wasm"
+gem "js" # JavaScript interop, which a browser app almost always wants
+gem "bigdecimal" # only for Decimal#to_d; see below
+
+group :development do
+  gem "ruby_wasm"
+end
+```
+
+```sh
+bundle install
+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 "hypercast"` as anywhere else. `HyperCast::BACKEND` is
+`:native`, and every door works as it does on a host Ruby.
+
+- **Ruby 3.4 and 4.0**, one archive each, the same minors the platform gems cover, picked by
+  `--ruby-version`. Any other minor stops the build with a message naming the ones the gem
+  carries. Built and tested against ruby_wasm 2.10.
+- **No Rust toolchain.** The gem's `extconf.rb` only hands rbwasm the prebuilt archive, and
+  rbwasm downloads its own wasi-sdk. The first `rbwasm build` compiles Ruby itself and takes
+  15–20 minutes; later builds reuse it.
+- **`Decimal#to_d` needs `gem "bigdecimal"` in that Gemfile.** bigdecimal is a bundled gem
+  with a C extension, and ruby.wasm builds a bundled gem's extension only when the Gemfile
+  names it; without it, `to_d` raises `LoadError`. `to_s` and `to_r` need nothing.
+- **Static linking only,** into ruby.wasm's default `wasm32-unknown-wasip1` interpreter.
+  rbwasm's dynamic-linking build (a pic target, for the component model) is not supported.
+- **Size.** rbwasm packs every gem's files into the interpreter, the archives included, so the
+  gem adds about 2 MB to `ruby.wasm` (both archives are gzipped).
+- **With HyperUuid.** `hyperuuid-wasm` links into the same interpreter. Every Rust extension
+  that carries std defines a few of the same symbols (`rust_eh_personality`, which ruby.wasm's
+  own wasi-vfs defines too, rb-sys's `ruby_abi_version`, and one of std's), and both gems
+  rename them to names of their own when CI builds the archive, which also fails if a newer
+  Rust starts exporting another.
+
+What stands behind it: CI builds each minor's archive from the commit, packs the gem the way
+it ships, links it into a fresh interpreter and runs [`wasm-smoke/test.rb`](wasm-smoke/test.rb)
+under Node and in headless Chrome (the forge's `hyper-build-wasm.yml`). The published gem is
+packed around those attested archives.
+
 ## Development
 
 Everything below runs from a checkout, with `rust/` and `corpus/` 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 is staged under `lib/hypercast/native/`. The Magnus backend does not — an
+is needed to use the gem. The Fiddle backend finds the in-repo build on its own when nothing
+is staged under `lib/hypercast/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.
 
 ```sh
 cd rust
-cargo build --release                           # libhypercast, what the Fiddle backend loads
-cargo build --release --target wasm32-wasip1    # hypercast.wasm, what the wasm backend loads
+cargo cdylib                           # libhypercast, what the Fiddle 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
 HYPERCAST_PURE=1 bundle exec rspec   # BACKEND == :fiddle
-HYPERCAST_WASM=1 bundle exec rspec   # BACKEND == :wasm
 bundle exec rake docs:check          # every public object carries a doc comment
 ruby benchmark/cast_benchmark.rb     # prints the backend it measured
 ```
@@ -454,8 +464,8 @@ docker run --rm -v "$PWD/..":/src:ro ruby:4.0-alpine sh -euc '
   mkdir -p /work/ruby/lib/hypercast/native/linux-musl-x64
   cp /src/rust/target/musl/linux-musl-x64/libhypercast.so /work/ruby/lib/hypercast/native/linux-musl-x64/
   cd /work/ruby && rm -f Gemfile.lock
-  BUNDLE_WITHOUT=wasm bundle install --quiet --prefer-local
-  HYPERCAST_PURE=1 BUNDLE_WITHOUT=wasm bundle exec rspec'
+  bundle install --quiet --prefer-local
+  HYPERCAST_PURE=1 bundle exec rspec'
 ```
 
 The floor's test is the same container on `ruby:3.3-alpine`. Bundler would compile a newer
@@ -472,6 +482,11 @@ docker run --rm -v "$PWD/..":/src:ro ruby:3.3-alpine sh -euc '
   HYPERCAST_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 hypercast linux-musl-x64 4.0 . <dir with the musl libhypercast.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 door table, the receipts, and the
 state of every other language binding.
 

data/lib/hypercast/runtime.rb

@@ -1,28 +1,32 @@
-require "fiddle"
+# Autoloaded, not required: the platform gems carry no library for Fiddle to open and do not
+# declare fiddle, so loading it eagerly would make `require "hypercast"` fail under Bundler
+# wherever fiddle is a bundled rather than a default gem (Ruby 4.0). It loads the first time
+# the Fiddle backend runs, and every path there goes through `functions` first, so a platform
+# gem forced onto Fiddle still gets missing_library_message rather than a bare LoadError.
+autoload :Fiddle, "fiddle"
 
 module HyperCast
   # Fiddle plumbing for the native libhypercast shared library — dlopen/dlsym plus raw
   # C-ABI calls, no runtime bridge. Fiddle ships with every Ruby install; it's a plain gem
-  # dependency here rather than a third-party one. A Ruby gem's files are already plain
-  # files on disk once installed, so native/{rid}/{lib} dlopen's directly — no extraction.
+  # dependency of the universal gem (see hypercast.gemspec) rather than a third-party one.
+  # A Ruby gem's files are already plain files on disk once installed, so native/{rid}/{lib}
+  # dlopen's directly — no extraction.
   module Runtime
     NATIVE_DIR = File.join(__dir__, "native")
 
-    PLAIN = [Fiddle::TYPE_VOIDP, Fiddle::TYPE_SIZE_T, Fiddle::TYPE_VOIDP, Fiddle::TYPE_VOIDP].freeze
-    NUMERIC = [Fiddle::TYPE_VOIDP, Fiddle::TYPE_SIZE_T, Fiddle::TYPE_VOIDP, Fiddle::TYPE_VOIDP,
-               Fiddle::TYPE_VOIDP].freeze
-    UNIX = [Fiddle::TYPE_VOIDP, Fiddle::TYPE_SIZE_T, Fiddle::TYPE_UINT32_T, Fiddle::TYPE_VOIDP,
-            Fiddle::TYPE_VOIDP].freeze
-
+    # Each door's C signature, by shape — resolved to Fiddle types only in load_functions,
+    # so nothing here touches Fiddle until the Fiddle backend actually runs: plain is
+    # (text, len, out, fault), numeric adds the packed NumFormat pointer before out, and
+    # declared a caller-declared u32 (precision, epoch, field order) in the same place.
     DOORS = {
-      cast_bool: PLAIN,
-      cast_i8: NUMERIC, cast_i16: NUMERIC, cast_i32: NUMERIC, cast_i64: NUMERIC,
-      cast_u8: NUMERIC, cast_u16: NUMERIC, cast_u32: NUMERIC, cast_u64: NUMERIC,
-      cast_f32: NUMERIC, cast_f64: NUMERIC, cast_decimal: NUMERIC,
-      cast_uuid: PLAIN,
-      cast_timestamp: PLAIN, cast_unix: UNIX, cast_excel_serial: UNIX,
-      cast_date: PLAIN, cast_date_ordered: UNIX, cast_datetime: UNIX,
-      cast_time: PLAIN, cast_duration: PLAIN
+      cast_bool: :plain,
+      cast_i8: :numeric, cast_i16: :numeric, cast_i32: :numeric, cast_i64: :numeric,
+      cast_u8: :numeric, cast_u16: :numeric, cast_u32: :numeric, cast_u64: :numeric,
+      cast_f32: :numeric, cast_f64: :numeric, cast_decimal: :numeric,
+      cast_uuid: :plain,
+      cast_timestamp: :plain, cast_unix: :declared, cast_excel_serial: :declared,
+      cast_date: :plain, cast_date_ordered: :declared, cast_datetime: :declared,
+      cast_time: :plain, cast_duration: :plain
     }.freeze
 
     # The one export that is not a door: the zero-argument version probe, returning the
@@ -41,14 +45,13 @@ module HyperCast
         functions.fetch(symbol)
       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 (hypercast.rb) asks this before falling
-      # back to the WebAssembly backend, which needs neither.
-      def fiddle_library_available?
-        !library_path.nil?
-      rescue NativePlatform::UnsupportedPlatformError
-        false
+      # 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 per-thread scratch buffer and each packed NumFormat
+      # (hypercast.rb) pay for it once apiece.
+      def buffer(size)
+        functions
+        Fiddle::Pointer.malloc(size, Fiddle::RUBY_FREE)
       end
 
       private
@@ -65,6 +68,35 @@ module HyperCast
         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 (HYPERCAST_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["hypercast"]&.platform,
+                                  forced = ENV.key?("HYPERCAST_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
+              "HYPERCAST_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
+          "hypercast: 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 hypercast --platform ruby`, or Bundler's force_ruby_platform " \
+            "(#{missing} not found)"
+        else
+          "hypercast: #{missing} not found (unsupported platform, or this gem was built " \
+            "without a native library for it)"
+        end
+      end
+
       # Loaded lazily and exactly once; 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 fast path — a per-call mutex acquisition measured as a
@@ -75,16 +107,17 @@ module HyperCast
 
       def load_functions
         path = library_path
-        if path.nil?
-          rid, lib_name = NativePlatform.rid_and_library_name
-          raise LoadError,
-                "hypercast: #{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)
-        functions = DOORS.to_h do |name, signature|
-          [name, Fiddle::Function.new(handle[name.to_s], signature, Fiddle::TYPE_INT32_T)]
+        plain = [Fiddle::TYPE_VOIDP, Fiddle::TYPE_SIZE_T, Fiddle::TYPE_VOIDP, Fiddle::TYPE_VOIDP]
+        signatures = {
+          plain: plain,
+          numeric: plain.dup.insert(2, Fiddle::TYPE_VOIDP),
+          declared: plain.dup.insert(2, Fiddle::TYPE_UINT32_T)
+        }
+        functions = DOORS.to_h do |name, shape|
+          [name, Fiddle::Function.new(handle[name.to_s], signatures.fetch(shape), Fiddle::TYPE_INT32_T)]
         end
         functions[VERSION_PROBE] =
           Fiddle::Function.new(handle[VERSION_PROBE.to_s], [], Fiddle::TYPE_UINT32_T)

data/lib/hypercast.rb

@@ -3,12 +3,11 @@ require_relative "hypercast/native_platform"
 require_relative "hypercast/runtime"
 
 # Allocation-lean scalar casts — booleans, numerics, exact decimals, UUIDs, temporals —
-# from one Rust core, reached through whichever of three backends this install can load:
+# 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), the native libhypercast shared library called through Fiddle (the
-# universal gem bundles one per supported platform), or the same core as a WebAssembly
-# module inside the wasmtime gem. HyperCast::BACKEND names the one that loaded; the
-# selection logic is at the bottom of this file. Every door returns a verdict: Success or
+# platform gems), or the native libhypercast shared library called through Fiddle (the
+# universal gem bundles one per supported platform). HyperCast::BACKEND names the one that
+# loaded; the selection logic is at the bottom of this file. Every door returns a verdict: Success or
 # Fault (a closed reason plus the offending span), never an exception for bad data — the
 # only exceptions here are caller bugs (a malformed NumFormat, an undeclared option, text
 # that is not a String), never data, and the same exception on every backend.
@@ -30,7 +29,7 @@ require_relative "hypercast/runtime"
 module HyperCast
   # This gem's own version — kept in lockstep with hypercast.gemspec by the
   # prepare-release workflow, so the two can never drift apart again.
-  VERSION = "0.4.0"
+  VERSION = "0.6.1"
 
   # The success case of a verdict: a cast value.
   Success = Data.define(:value)
@@ -199,11 +198,10 @@ module HyperCast
     # Whether a backend actually loaded and exports the ABI this binding was built against
     # — what a consumer with a fallback of its own checks before committing to these doors.
     # Probed once (a native_version round trip: the cheapest call the core has), cached,
-    # and never raises: a missing shared library, 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 LoadError, exactly as before — and so does require-time selection
-    # under HYPERCAST_WASM=1 without wasmtime; this only answers the question quietly.
+    # and never 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 LoadError —
+    # this only answers the question quietly.
     def available?
       return @available unless @available.nil?
 
@@ -289,7 +287,7 @@ module HyperCast
     #
     # The 1900 system contains a day that never existed: serial 60 is 1900-02-29, kept
     # deliberately because Lotus 1-2-3 wrongly treated 1900 as a leap year and Excel copied
-    # the bug for file compatibility. It is :malformed here — the same verdict .date gives
+    # the bug for file compatibility. It is :out_of_range here — the same verdict .date gives
     # the text "1900-02-29" — so every serial above it is shifted one day against a naive
     # count. An unknown epoch is a caller bug (KeyError), never a verdict.
     def excel_serial(text, epoch)
@@ -392,10 +390,11 @@ module HyperCast
     # registering a GC finalizer — measured as the dominant per-call cost by an order of
     # magnitude. The NumFormat no longer lives here: each format owns its own packed
     # pointer (see packed_cache), so a numeric call copies nothing into scratch before
-    # crossing.
+    # crossing. Allocated through Runtime.buffer, which loads the library first, so a
+    # missing one is reported as such before Fiddle is touched.
     def scratch
       Thread.current[:hypercast_scratch] ||= begin
-        base = Fiddle::Pointer.malloc(24, Fiddle::RUBY_FREE)
+        base = Runtime.buffer(24)
         [base, base + 16]
       end
     end
@@ -445,9 +444,7 @@ module HyperCast
 
     # The shared body of the four doors that take a caller-declared u32 — a precision, an
     # epoch, or a field order — already resolved from its Symbol by the door. These bodies
-    # (plain, numeric, declared, and packed_version below) are the whole native crossing:
-    # the wasm backend (wasm_runtime.rb) redefines exactly these four in place and nothing
-    # above them.
+    # (plain, numeric, declared, and packed_version below) are the whole Fiddle crossing.
     def declared(symbol, text, code, out_size)
       bytes = utf8(text)
       out, fault = scratch
@@ -480,7 +477,7 @@ module HyperCast
     def packed_cache
       @packed_cache ||= Hash.new do |cache, format|
         cache.shift while cache.size >= PACKED_CACHE_LIMIT
-        pointer = Fiddle::Pointer.malloc(32, Fiddle::RUBY_FREE)
+        pointer = Runtime.buffer(32)
         pointer[0, 32] = format.packed
         cache[format] = pointer
       end.compare_by_identity
@@ -497,30 +494,18 @@ end
 # --- backend selection: the Magnus extension, when present, replaces the doors above in
 # place on this module (no delegation layer) — Fiddle's measured 1.6 µs per-call floor
 # drops to an ordinary extension call. The pure-Fiddle definitions stay the universal
-# zero-compile fallback; precompiled platform gems are how the extension ships without
-# ever making a consumer compile anything. Set HYPERCAST_PURE=1 to force Fiddle.
+# 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/hypercast/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. HYPERCAST_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 HYPERCAST_WASM wins when both are
-# set.
+# HYPERCAST_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, HyperCast.available? answers false, and the first door call raises a
+# LoadError naming the universal gem, which is where the Fiddle backend lives.
 HyperCast::BACKEND =
-  if ENV["HYPERCAST_WASM"]
-    begin
-      require "wasmtime"
-    rescue LoadError
-      raise LoadError,
-            "hypercast: HYPERCAST_WASM=1 needs the wasmtime gem — `gem install wasmtime` (or add it to your Gemfile)"
-    end
-    require_relative "hypercast/wasm_runtime"
-    :wasm
-  elsif ENV["HYPERCAST_PURE"]
+  if ENV["HYPERCAST_PURE"]
     :fiddle
   else
     # Two layouts, and both have to work. A released platform gem is a "fat" gem carrying one
@@ -534,7 +519,11 @@ HyperCast::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 is for.
+    # precompiled extension, which is precisely what the Fiddle backend 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. HyperCast.available? is
+    # the quiet way to ask.
     begin
       require "hypercast/#{RUBY_VERSION[/\d+\.\d+/]}/hypercast_native"
       :native
@@ -543,22 +532,7 @@ HyperCast::BACKEND =
         require "hypercast_native"
         :native
       rescue LoadError
-        if HyperCast::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. HyperCast.available? is the quiet way to ask.
-          begin
-            require "wasmtime"
-            require_relative "hypercast/wasm_runtime"
-            :wasm
-          rescue LoadError
-            :fiddle
-          end
-        end
+        :fiddle
       end
     end
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hypercast
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.6.1
 platform: ruby
 authors:
 - Brian Buvinghausen
@@ -54,11 +54,10 @@ dependencies:
 description: |
   Booleans, numerics, exact decimals, UUIDs, and temporals cast from untrusted text by a
   native Rust core — every parse returns a verdict (the value, or a reason plus the
-  offending span), never an exception for bad data. 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.
+  offending span), never an exception for bad data. 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: []
@@ -72,12 +71,10 @@ files:
 - lib/hypercast/native/linux-x64/libhypercast.so
 - lib/hypercast/native/osx-arm64/libhypercast.dylib
 - lib/hypercast/native/osx-x64/libhypercast.dylib
-- lib/hypercast/native/wasm32-wasip1/hypercast.wasm
 - lib/hypercast/native/win-arm64/hypercast.dll
 - lib/hypercast/native/win-x64/hypercast.dll
 - lib/hypercast/native_platform.rb
 - lib/hypercast/runtime.rb
-- lib/hypercast/wasm_runtime.rb
 homepage: https://github.com/SkunkWerkx/HyperCast
 licenses:
 - MIT

data/lib/hypercast/wasm_runtime.rb

@@ -1,169 +0,0 @@
-require "wasmtime"
-
-module HyperCast
-  # The WebAssembly backend: the same Rust core, compiled once to a `wasm32-wasip1` module
-  # (lib/hypercast/native/wasm32-wasip1/hypercast.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 hypercast.rb has
-  # defined the pure-Fiddle module) this redefines methods **in place** on HyperCast — no
-  # delegation layer, no second surface. The Magnus extension replaces every public door;
-  # this file replaces only the four private bodies underneath them (`plain`, `numeric`,
-  # `declared`, `packed_version` — the whole native crossing), so every door, every verdict
-  # type, `utf8`, `verdict`, `instant` and the Symbol tables stay the exact code the other
-  # two backends run, byte for byte.
-  #
-  # 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. The
-  #   input text is copied into a grow-only guest buffer, and the three out-params the doors
-  #   fill — the 16-byte out-value, the 8-byte fault span, the 32-byte NumFormat — are guest
-  #   allocations made once at load, all 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
-  #   HyperUuid observed a buffer written at a guessed offset corrupted by the guest's next
-  #   allocation.
-  # * A `Wasmtime::Store` is single-threaded, so every call is serialized under one Mutex
-  #   around one shared instance per process.
-  module WasmRuntime
-    MODULE_PATH = File.join(Runtime::NATIVE_DIR, "wasm32-wasip1", "hypercast.wasm")
-    # Development loop: the in-repo cargo build, the same fallback runtime.rb takes for the
-    # native library.
-    REPO_BUILD_PATH = File.expand_path(
-      File.join(__dir__, "../../../rust/target/wasm32-wasip1/release/hypercast.wasm")
-    )
-
-    DOORS = Runtime::DOORS.keys.freeze
-
-    # One instantiated module: the exported functions, the exported memory, and the guest
-    # buffers every door crosses through for the life of the process.
-    class Instance
-      attr_reader :memory, :out, :fault, :format
-
-      def initialize
-        path = File.exist?(MODULE_PATH) ? MODULE_PATH : REPO_BUILD_PATH
-        unless File.exist?(path)
-          raise LoadError,
-                "hypercast: #{MODULE_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 four WASI preview1 functions — wasi-libc's startup and panic
-        # plumbing (environ_*, fd_write, proc_exit); the core itself needs no clock and no
-        # entropy. 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 = (DOORS + [Runtime::VERSION_PROBE] + %i[malloc free]).to_h do |name|
-          export = instance.export(name.to_s) or
-            raise LoadError, "hypercast: #{path} does not export #{name} (a module older than this binding)"
-          [name, export.to_func]
-        end
-        # dlmalloc hands back 8-byte-aligned (in fact 16) blocks, which covers the
-        # decimal out-value's 8-byte alignment.
-        @out = malloc(16)
-        @fault = malloc(8)
-        @format = malloc(32)
-        # Grow-only buffer for the input text, so a steady stream of ordinary scalars never
-        # touches the guest allocator again.
-        @in = 0
-        @in_cap = 0
-        # The format currently written at @format, memoized by identity: formats are reused
-        # constants in practice, and NumFormat is a frozen Data, so one `equal?` skips the
-        # 32-byte write on the overwhelming majority of numeric calls. The Instance holds
-        # the format it memoized, so the key can never be a recycled object.
-        @last_format = nil
-      end
-
-      def fn(name)
-        @fn.fetch(name)
-      end
-
-      def malloc(size)
-        ptr = @fn[:malloc].call(size)
-        raise NoMemoryError, "hypercast: wasm malloc(#{size}) failed" if ptr.zero?
-
-        ptr
-      end
-
-      # Copies the input into the guest and returns its address — 0 (the ABI's NULL) for
-      # empty input, which the core never dereferences.
-      def stage_input(bytes)
-        size = bytes.bytesize
-        return 0 if size.zero?
-
-        if size > @in_cap
-          @fn[:free].call(@in) unless @in.zero?
-          @in = malloc(size)
-          @in_cap = size
-        end
-        @memory.write(@in, bytes)
-        @in
-      end
-
-      def stage_format(format)
-        unless format.equal?(@last_format)
-          @memory.write(@format, format.packed)
-          @last_format = format
-        end
-        @format
-      end
-    end
-
-    @mutex = Mutex.new
-    @instance = nil
-
-    # 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 self.with_instance
-      @mutex.synchronize do
-        @instance ||= Instance.new
-        yield @instance
-      end
-    end
-  end
-
-  class << self
-    private
-
-    # The four crossing bodies, redefined over the guest. Each door body reads the
-    # out-value back only on success and the fault span only on a failure code, so
-    # `verdict` sees exactly what the Fiddle path hands it.
-    def plain(symbol, text, out_size)
-      bytes = utf8(text)
-      WasmRuntime.with_instance do |w|
-        rc = w.fn(symbol).call(w.stage_input(bytes), bytes.bytesize, w.out, w.fault)
-        verdict(rc, rc.zero? ? nil : w.memory.read(w.fault, 8), bytes) { yield(w.memory.read(w.out, out_size)) }
-      end
-    end
-
-    def numeric(symbol, text, format, out_size)
-      bytes = utf8(text)
-      WasmRuntime.with_instance do |w|
-        rc = w.fn(symbol).call(w.stage_input(bytes), bytes.bytesize, w.stage_format(format), w.out, w.fault)
-        verdict(rc, rc.zero? ? nil : w.memory.read(w.fault, 8), bytes) { yield(w.memory.read(w.out, out_size)) }
-      end
-    end
-
-    def declared(symbol, text, code, out_size)
-      bytes = utf8(text)
-      WasmRuntime.with_instance do |w|
-        rc = w.fn(symbol).call(w.stage_input(bytes), bytes.bytesize, code, w.out, w.fault)
-        verdict(rc, rc.zero? ? nil : w.memory.read(w.fault, 8), bytes) { yield(w.memory.read(w.out, out_size)) }
-      end
-    end
-
-    def packed_version
-      WasmRuntime.with_instance { |w| w.fn(Runtime::VERSION_PROBE).call }
-    end
-  end
-end