hypercast 0.3.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a5a3b3e6d5955b7431ae3452f9f80b9aecaae1c795408951cdfabd913d025e30
-  data.tar.gz: 871aef11a7d72f3a025adf92340a3d66783d009604cf17d2c234ce25b0fbf60b
+  metadata.gz: f482418099cb3b96492d839da3f627716b4b4ba6a1b083d66f47f337edb197b3
+  data.tar.gz: 92e9560c193bd102dbbff75ace2b3aaa8dba75527a217c2b7f730f227af3e27b
 SHA512:
-  metadata.gz: 8664495fde8462e5e3886b7e0b72733e16c4c8dc4cb85e6d71b21c66bdc949ba9d3729c5291349f31c15a4da1b17403db85adbcc5815d55615e223fea77be022
-  data.tar.gz: 6e9396ad08a6634853726727121096fabbbf654275d81656725c0f7b620ccfea59b534d75f8ccc31812bdd01fd49220cb020e6c5f2999da2657a0ad9de20cba2
+  metadata.gz: 7f24fc4d78125c73b521c631318b778367321438c1791ee8e6055805d8bd2c274f2dd358d30af309350a201faba1aba0772815974a1c187d64896ad4f3f92af0
+  data.tar.gz: f349625cd4fd7b6dfa1311484186c924705a4c480213ace67aa1a6dea6b68e78d464f9187fbf0da88129c6995cc5f40e99fc01ae001088751ffe66b6e288af14

data/README.md

@@ -1,28 +1,28 @@
 # hypercast
 
 [![CI](https://github.com/SkunkWerkx/HyperCast/actions/workflows/ci.yml/badge.svg)](https://github.com/SkunkWerkx/HyperCast/actions/workflows/ci.yml)
-[![Gem](https://img.shields.io/gem/v/hypercast.svg)](https://rubygems.org/gems/hypercast)
+[![RubyGems](https://img.shields.io/gem/v/hypercast.svg)](https://rubygems.org/gems/hypercast)
 [![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 byte 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.2 is the floor
-(`Data.define` for the verdict case types). 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
-[WebAssembly (wasmtime)](#webassembly-wasmtime).
+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.
+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)
 in HyperCast::Success(value:) then puts "got #{value}"          # -1234
-in HyperCast::Fault(reason:, offset:) then puts "#{reason} at byte #{offset}"
+in HyperCast::Fault(reason:, offset:) then puts "#{reason} at #{offset}"
 end
 ```
 
@@ -52,13 +52,45 @@ midnight, durations come back as exact `Rational` seconds across the core's whol
 | `duration(text)` | exact `Rational` seconds | — |
 
 Every door returns a `Success` or a `Fault`; `HyperCast.optional(verdict)` folds `:empty`
-to `nil`. Beside the doors, `HyperCast.native_version` reads the loaded core's own version
-(`"major.minor.patch"`, from the library's `hypercast_version` export — the cheapest probe
-that the backend resolved at all, and the way to name a mismatch against
-`HyperCast::VERSION` before the first cast), and `HyperCast.available?` answers whether a
-backend loaded and exports that ABI at all — probed once, cached, never raising — for a
-consumer with a fallback of its own. (The doors keep raising their precise `LoadError` on an
-unavailable backend; `available?` only asks quietly.)
+to `nil`. Beside the doors, `native_version` returns the loaded core's
+`"major.minor.patch"` and `available?` answers `true`/`false` without ever raising — see
+[Is the native core there?](#is-the-native-core-there).
+
+### Errors
+
+Bad data is never an exception — it is a `Fault`. What raises is a caller bug, and it raises
+the same exception on every backend:
+
+- `ArgumentError` from `NumFormat.new` for a malformed format: separators that are not single
+  characters or not distinct, a currency symbol that is too long or carries an ASCII digit or
+  whitespace.
+- `KeyError` — `Hash#fetch`'s own, `key not found: …` — for a precision, epoch or date order
+  that names nothing: an unknown Symbol, or anything that is not a Symbol (`"seconds"`
+  included). `date(text, nil)` is not one of these: an explicit `nil` order is the strict ISO
+  door, exactly as if it were left off.
+- `TypeError` for text that is not a `String` (anything with `to_str` is taken as one).
+- `String#encode`'s own `Encoding::` error for text in another encoding that cannot be
+  transcoded to UTF-8.
+
+### Is the native core there?
+
+`HyperCast.available?` answers whether a backend actually loaded and exports the ABI this
+binding was built against — probed once, cached, never raising — for a consumer with a
+fallback of its own:
+
+```ruby
+value = HyperCast.available? ? HyperCast.i32(text, format) : my_own_parse(text)
+```
+
+`HyperCast.native_version` reads the version out of the loaded core itself (its
+`hypercast_version` export — the cheapest probe that the backend resolved at all), so a
+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. 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
 
@@ -132,19 +164,18 @@ 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-arm64): timestamp **713 ns vs
-   2.88 µs `Time.iso8601`** (4.0x) — while returning exact `Rational` durations on the
-   duration door. The Fiddle fallback lands at ~3.5 µs: parity with `Time.iso8601`, sitting
-   on Fiddle's measured 1.6 µs per-call marshalling floor.
-
-   Separator detection is free here: `1.234.567,89` under `NumFormat::DETECT` runs at
-   591 ns against 570 ns for the same text under a declared eurozone format — inside the
-   error bars. Both of those were ~990 ns in 0.1.0, for a reason that had nothing to do
-   with parsing: every format other than `INVARIANT` paid three method dispatches and two
+   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
+   returning exact `Rational` durations on the duration door. The Fiddle fallback lands at
+   3.25 µs: a little behind `Time.iso8601`, sitting on Fiddle's per-call marshalling floor.
+
+   Separator detection is nearly free here: `1.234.567,89` under `NumFormat::DETECT` runs
+   at 178 ns against 170 ns for the same text under a declared eurozone format. Both cost
+   nearly twice that in 0.1.0, for a reason that had nothing to do with parsing: every format other than `INVARIANT` paid three method dispatches and two
    `String` allocations per call to read its separators back out of the `Data`. `DETECT`
    is now identity-matched like `INVARIANT`, and any other format is resolved once per
    thread and memoized by identity — anchored in a thread-variable so the memo's key can
@@ -153,86 +184,79 @@ and memoized by identity on every backend, so declaring a currency costs a cast
    cached the same way, so a fault or a declared option is a pointer compare too, never a
    `Symbol#name` materialization.
 
-**The honest trade-off, and Ruby's one real loss:** the civil date-time door is *slower*
-than `strptime` — 1.30 µs against `DateTime.strptime`'s 1.02 µs, and the date door 1.04 µs
-against `Date.strptime`'s 619 ns. The parse isn't the problem; the carrier is. Building a
-stdlib `DateTime` with an exact `Rational` second costs more than the whole native call,
-where the timestamp door's `Time` is built by a single cheap `rb_time_nano_new`. Printed
-because it's real: if you want Ruby's fastest civil parse and don't need the verdict or the
-declared order, `strptime` wins. Also note the carrier's other caveat — `DateTime`'s offset
-defaults to `+00:00`, which is an artifact of the type, not a zone the parse assigned.
+**The honest trade-off:** the civil doors do not beat `strptime`. The date-time door is
+level with `DateTime.strptime` (904 ns against 901 ns) and the date door a little behind
+`Date.strptime` (620 ns against 513 ns). The parse isn't the cost; the carrier is. Building
+a stdlib `DateTime` with an exact `Rational` second costs more than the whole native call,
+where the timestamp door's `Time` is built by a single cheap `rb_time_nano_new`. If you want
+Ruby's fastest civil parse and don't need the verdict or the declared order, `strptime` is
+as good. Also note the carrier's other caveat — `DateTime`'s offset defaults to `+00:00`,
+which is an artifact of the type, not a zone the parse assigned.
 
 On the Fiddle fallback the doors are parity-at-best — Fiddle's
 per-call floor is the mechanism's price, kept because it's the universal zero-compile
-path. 0.2.0 still took ~20% off its numeric doors (`i32` 3.37 → 2.62 µs, `f64` 3.31 →
-2.76 µs, same session) by not building things per call that never changed: the integer
-doors interpolated and interned their `:cast_*` Symbol on every call, every door went
-through a splat-and-resplat dispatcher, and every numeric call copied the format's 12
-packed bytes into scratch — each format now owns one native pointer, memoized by identity,
-passed straight through. (Benchmark forensics worth knowing: the doors read 4.3 µs until
+path. Its doors build nothing per call that does not change between calls: each format
+owns one native pointer, memoized by identity and passed straight through. (Benchmark forensics worth knowing: the doors read 4.3 µs until
 per-call `Fiddle::Pointer.malloc` finalizers were hoisted to thread-local scratch —
 receipts include their own archaeology.)
 
-## WebAssembly (wasmtime)
+## Benchmarks
 
-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.
+`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` 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.
 
-`wasmtime` is deliberately **not** a dependency of this gem; a consumer who wants this path
-installs it:
+Measured on Ruby 4.0.7, linux-x64 (an Intel Core i9-11900H), `benchmark-ips`, same session,
+both backends:
 
-```sh
-gem install wasmtime
-HYPERCAST_WASM=1 ruby -rhypercast -e 'p HyperCast::BACKEND'   # => :wasm
-```
+| 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 —
+rather than through `Data.new`, whose keyword handling alone cost more than the cast.
 
-`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, same box as the benchmarks above (Ruby 4.0.6, linux-arm64 under WSL2, wasmtime
-48.0.1, `benchmark-ips`, same session, all three backends):
-
-| Door | Magnus | Fiddle | wasmtime |
-|---|---:|---:|---:|
-| `bool` | 484 ns | 2.55 µs | 2.07 µs |
-| `i32` | 555 ns | 2.78 µs | 2.65 µs |
-| `f64` | 529 ns | 2.72 µs | 2.73 µs |
-| `uuid` | 640 ns | 3.32 µs | 3.53 µs |
-| `timestamp` | 769 ns | 3.12 µs | 3.10 µs |
-| `datetime` (`1/7/2026 3:04 PM`) | 1.36 µs | 3.97 µs | 3.66 µs |
-| `duration` (ISO) | 975 ns | 2.84 µs | 2.47 µs |
-| `i32`, a fault | 658 ns | 2.89 µs | 2.42 µs |
-
-The finding worth stating: in Ruby the wasm backend lands at Fiddle parity, door for door.
-Fiddle's per-call floor is interpreted marshalling; wasmtime's is the host-to-guest crossing
-plus the guest memory copies; on this box they cost the same, and both sit 4-5x behind the
-Magnus extension. So on a platform with no native build, the fallback costs a consumer
-nothing they were not already paying on the universal gem.
+## Backends
+
+| `HyperCast::BACKEND` | What runs | Chosen when |
+|---|---|---|
+| `: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` | `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.
+
+`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. `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`.
 
 ## Verifying provenance
 
-Every gem RubyGems.org serves — the universal fallback and each of the six 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:
@@ -243,10 +267,11 @@ 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 (six FFI libs, twelve Magnus extensions —
-two ABIs 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.
+the same job verifies every native binary it packs — the Fiddle libraries, the Magnus
+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 duplicate-version overwrite, so this all happens while a
 bad artifact is still reversible. The release run's job summary then re-fetches every gem
 from the CDN and records attested-vs-served digests, turning "rubygems.org stores an upload
@@ -260,10 +285,16 @@ more on why `--signer-repo` is needed for some artifacts here and not others.
 gem install hypercast
 ```
 
-Seven gems are published per release: one universal `ruby`-platform gem (pure Fiddle, all
-six platforms' natives bundled) plus six precompiled Magnus platform gems (`x86_64-linux`,
-`aarch64-linux`, `x86_64-darwin`, `arm64-darwin`, `x64-mingw-ucrt`, `aarch64-mingw-ucrt`)
-that `gem install` auto-selects when they match. Nobody ever compiles anything.
+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 is no `abi3` equivalent to collapse the version axis
@@ -271,11 +302,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 | the six platforms above | anywhere else (musl/Alpine, …) |
+| Ruby | Linux (glibc and musl), Apple silicon macOS, Windows — x64 and arm64 | Gem installed |
 | --- | --- | --- |
-| 4.0 (primary) | Magnus, `backend: :native` | Fiddle |
-| 3.4 (floor, until its EOL 2028-03-31) | Magnus, `backend: :native` | Fiddle |
-| 3.2 / 3.3 | Fiddle | Fiddle |
+| 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
@@ -283,7 +324,28 @@ extension must never be installed in the first place. On Windows it would at lea
 load cleanly (the extension imports `<arch>-ucrt-ruby<minor>.dll` by name —
 `x64-ucrt-ruby400.dll` on x64, `aarch64-ucrt-ruby400.dll` on ARM), but Linux extensions don't
 link libruby at all, so one can load successfully against the wrong ABI and misbehave later.
-Every cell in that table replays the same corpus green.
+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.** 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
@@ -294,7 +356,85 @@ targets rather than `gnu` — the same mingw-w64/UCRT ABI RubyInstaller's Ruby u
 with LLVM and compiler-rt instead of GCC and a statically-linked libgcc, which is what keeps
 the shipped extension small. The build script, and the two flags that are load-bearing on
 the ARM leg (a static libunwind, and a clang-spelled `--target` for bindgen), live in the
-forge's `hyper-build-native.yml`, shared with every other Hyper* repo.
+forge's `ruby-magnus` action (`build-magnus.sh`), shared with every other Hyper* repo.
+
+## Development
+
+Everything below runs from a checkout, with `rust/` and `corpus/` beside `ruby/`; none of it
+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 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
+bundle exec rake docs:check          # every public object carries a doc comment
+ruby benchmark/cast_benchmark.rb     # prints the backend it measured
+```
+
+`rake native:dev` runs `cargo ruby-ext` (an alias in `rust/.cargo/config.toml` that builds the
+`ruby` feature into `rust/target/ruby/`, never over the plain library in
+`rust/target/release/`) and copies the result to
+`lib/hypercast/<minor>/hypercast_native.<so|bundle>` — the path `lib/hypercast.rb` tries
+first. The copy is also a rename, and it is the step `cargo ruby-ext` alone does not do: cargo
+names its output `libhypercast.so`, and Ruby derives the `Init_` function it calls from the
+file name it was asked to `require`. Three things worth knowing:
+
+- **Run it again after changing `rust/`.** The staged file is a copy; nothing rebuilds it.
+- **One staging per Ruby.** An extension is bound to one Ruby minor, so under a second Ruby
+  (`RBENV_VERSION=3.4.11 bundle exec rake native:dev`, say) the task rebuilds for that ABI
+  and stages beside the first, each Ruby loading its own.
+- **Without it, `bundle exec rspec` still passes — on Fiddle.** The examples under "native
+  backend" report themselves pending with `BACKEND=fiddle`; that line, or
+  `ruby -Ilib -rhypercast -e 'p HyperCast::BACKEND'`, is how to tell which backend a run
+  exercised. Deleting `lib/hypercast/<minor>/` goes back to Fiddle.
+
+The task covers Linux and macOS. The Windows extensions need the `gnullvm` targets and linker
+flags in the forge's `build-magnus.sh`, which is also what CI uses on every platform.
+
+The musl build has no host to run on outside a container. With the core built for musl at
+`rust/target/musl/linux-musl-x64/libhypercast.so`, this runs the Fiddle suite — corpus replay
+included — against it on Alpine, with the checkout mounted read-only:
+
+```sh
+docker run --rm -v "$PWD/..":/src:ro ruby:4.0-alpine sh -euc '
+  mkdir /work && cp -r /src/ruby /work/ruby && cp -r /src/corpus /work/corpus
+  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 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
+Fiddle there (see [Install](#install)), so this one goes around Bundler and runs against the
+Fiddle that Ruby 3.3 ships:
+
+```sh
+docker run --rm -v "$PWD/..":/src:ro ruby:3.3-alpine sh -euc '
+  mkdir /work && cp -r /src/ruby /work/ruby && cp -r /src/corpus /work/corpus
+  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 Gemfile.lock
+  gem install rspec -v "~> 3.13" --no-document --silent
+  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.
+
+## License
+
+[MIT](https://github.com/SkunkWerkx/HyperCast/blob/master/LICENSE)

data/lib/hypercast/native_platform.rb

@@ -4,18 +4,24 @@ module HyperCast
   module NativePlatform
     class UnsupportedPlatformError < StandardError; end
 
-    def self.rid_and_library_name
-      is_arm = RUBY_PLATFORM.match?(/arm64|aarch64/)
+    # +platform+ is a parameter only so the specs can walk the whole table from one host;
+    # every real caller takes the default.
+    def self.rid_and_library_name(platform = RUBY_PLATFORM)
+      arch = platform.match?(/arm64|aarch64/) ? "arm64" : "x64"
 
-      case RUBY_PLATFORM
+      case platform
       when /mingw|mswin|windows/
-        is_arm ? ["win-arm64", "hypercast.dll"] : ["win-x64", "hypercast.dll"]
+        ["win-#{arch}", "hypercast.dll"]
       when /darwin/
-        is_arm ? ["osx-arm64", "libhypercast.dylib"] : ["osx-x64", "libhypercast.dylib"]
+        ["osx-#{arch}", "libhypercast.dylib"]
       when /linux/
-        is_arm ? ["linux-arm64", "libhypercast.so"] : ["linux-x64", "libhypercast.so"]
+        # Two C libraries, two builds: a glibc-linked library cannot be relied on to dlopen
+        # into a musl process (Alpine), so musl gets RIDs of its own. Ruby names the libc
+        # in its platform string there ("x86_64-linux-musl") and leaves it off on glibc.
+        os = platform.include?("musl") ? "linux-musl" : "linux"
+        ["#{os}-#{arch}", "libhypercast.so"]
       else
-        raise UnsupportedPlatformError, "hypercast: unsupported platform RUBY_PLATFORM=#{RUBY_PLATFORM}"
+        raise UnsupportedPlatformError, "hypercast: unsupported platform RUBY_PLATFORM=#{platform}"
       end
     end
   end

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,16 +3,20 @@ require_relative "hypercast/native_platform"
 require_relative "hypercast/runtime"
 
 # Allocation-lean scalar casts — booleans, numerics, exact decimals, UUIDs, temporals —
-# calling directly into the native libhypercast shared library via Fiddle. Every door
-# returns a verdict: Success or Fault (a closed reason plus the offending byte span), never
-# an exception for bad data — the only exceptions here are caller bugs (a malformed
-# NumFormat), never data.
+# from one Rust core, reached through whichever of two backends this install can load:
+# the core linked straight into a Magnus native extension (shipped precompiled in the
+# platform gems), or the native 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.
 #
 # Consume with Ruby's own pattern matching over the two Data case types:
 #
 #   case HyperCast.i32("(1,234)", HyperCast::NumFormat::INVARIANT)
 #   in HyperCast::Success(value:) then puts "got #{value}"          # -1234
-#   in HyperCast::Fault(reason:, offset:) then puts "#{reason} at byte #{offset}"
+#   in HyperCast::Fault(reason:, offset:) then puts "#{reason} at #{offset}"
 #   end
 #
 # Door names mirror the native ABI (i32, f64, timestamp, ...) so the polyglot surface reads
@@ -25,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.3.0"
+  VERSION = "0.6.0"
 
   # The success case of a verdict: a cast value.
   Success = Data.define(:value)
@@ -50,25 +54,29 @@ module HyperCast
   # 16 UTF-8 bytes or carrying an ASCII digit or ASCII whitespace, are a caller bug
   # (ArgumentError), never a verdict.
   NumFormat = Data.define(:decimal_sep, :group_sep, :flags, :currency) do
-    # The widest currency symbol the native ABI carries inline, in UTF-8 bytes.
-    CURRENCY_MAX_BYTES = 16
-
     # Validates the declared separators up front — single characters, and distinct from
     # each other — and the currency symbol (a String of at most 16 UTF-8 bytes with no
     # ASCII digit or ASCII whitespace, since those would collide with the digit scan and
     # the trimming around the symbol), so a malformed format fails loudly as the caller bug
-    # it is. The symbol is stored transcoded to UTF-8, the encoding the core reads.
+    # it is. All three are stored transcoded to UTF-8, the encoding the core reads — a
+    # separator handed over in another encoding (a no-break space read from a Latin-1
+    # file, say) is the same code point on every backend rather than whatever its bytes
+    # happened to spell in the encoding it arrived in.
     def initialize(decimal_sep:, group_sep:, flags:, currency: "")
       raise ArgumentError, "separators must be single characters" unless
         decimal_sep.is_a?(String) && decimal_sep.length == 1 &&
         group_sep.is_a?(String) && group_sep.length == 1
+
+      decimal_sep = decimal_sep.encode(Encoding::UTF_8)
+      group_sep = group_sep.encode(Encoding::UTF_8)
       raise ArgumentError, "decimal and group separators must differ; both are #{decimal_sep.inspect}" if
         decimal_sep == group_sep
       raise ArgumentError, "currency symbol must be a String; got #{currency.inspect}" unless currency.is_a?(String)
 
       symbol = currency.encode(Encoding::UTF_8)
-      raise ArgumentError, "currency symbol #{currency.inspect} exceeds #{CURRENCY_MAX_BYTES} UTF-8 bytes" if
-        symbol.bytesize > CURRENCY_MAX_BYTES
+      limit = self.class::CURRENCY_MAX_BYTES
+      raise ArgumentError, "currency symbol #{currency.inspect} exceeds #{limit} UTF-8 bytes" if
+        symbol.bytesize > limit
       raise ArgumentError, "currency symbol #{currency.inspect} must not contain an ASCII digit or whitespace" if
         symbol.match?(/[0-9\t\n\f\r ]/)
 
@@ -83,6 +91,11 @@ module HyperCast
     end
   end
 
+  # The widest currency symbol the native ABI carries inline, in UTF-8 bytes. Assigned out
+  # here rather than inside the Data.define block above: a constant written in that block
+  # is scoped lexically, and landed on HyperCast instead of on NumFormat.
+  NumFormat::CURRENCY_MAX_BYTES = 16
+
   # Permit the group separator between digits (sizes not validated — between digits is the rule).
   GROUPING = 1
   # Permit accounting parentheses as negation: (1,234) is -1234.
@@ -185,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?
 
@@ -275,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)
@@ -351,9 +363,19 @@ module HyperCast
     BYTE_COMPATIBLE = [Encoding::UTF_8, Encoding::US_ASCII, Encoding::ASCII_8BIT].freeze
 
     # Presents the input as UTF-8 bytes: already-compatible text crosses as-is (Fiddle
-    # passes a String's bytes for void* directly — no Pointer wrapper, no dup); only
-    # foreign encodings pay a transcode.
+    # passes a String's own bytes for void* — no copy of them); only foreign encodings pay
+    # a transcode, and text that cannot be transcoded raises String#encode's own
+    # Encoding:: error, the same one the Magnus extension raises through the same call.
+    #
+    # Text that is not a String is a caller bug, and the same TypeError on every backend:
+    # the extension takes its argument through Ruby's implicit String conversion (to_str,
+    # or a TypeError), so this does too.
     def utf8(text)
+      unless text.is_a?(String)
+        converted = String.try_convert(text) or
+          raise TypeError, "no implicit conversion of #{text.class} into String"
+        text = converted
+      end
       BYTE_COMPATIBLE.include?(text.encoding) ? text : text.encode(Encoding::UTF_8)
     end
 
@@ -368,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
@@ -421,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
@@ -437,14 +458,26 @@ module HyperCast
       Runtime.function(:hypercast_version).call
     end
 
+    # How many formats packed_cache remembers before it starts forgetting the oldest. Far
+    # more than a process that reuses its formats ever holds; what it bounds is the one
+    # that builds a NumFormat per request.
+    PACKED_CACHE_LIMIT = 64
+
     # Identity-keyed memo (compare_by_identity — a pointer hash, not Data's structural
     # #hash over three Strings and an Integer) of a native 32-byte RawNumFormat per format
     # object, filled once from NumFormat#packed. Formats are reused constants in practice,
     # so the common call finds its pointer in one lookup and packs nothing. The Hash holds
     # the format, so a key can never be a recycled address; the race is benign (idempotent).
+    #
+    # Bounded, oldest entry out first (a Hash keeps insertion order): unbounded, it held
+    # every format ever cast with and its 32-byte allocation for the life of the process,
+    # which a consumer building a format per request experienced as a leak. A format
+    # evicted and then used again is simply packed again, and an evicted pointer stays
+    # alive for any call already holding it — the caller's own reference outlives the cache's.
     def packed_cache
       @packed_cache ||= Hash.new do |cache, format|
-        pointer = Fiddle::Pointer.malloc(32, Fiddle::RUBY_FREE)
+        cache.shift while cache.size >= PACKED_CACHE_LIMIT
+        pointer = Runtime.buffer(32)
         pointer[0, 32] = format.packed
         cache[format] = pointer
       end.compare_by_identity
@@ -461,37 +494,36 @@ 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.
+# 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
     # extension per supported Ruby ABI under lib/hypercast/<minor>/ (see the Rakefile's
     # native:gem task for why an ABI-per-file is unavoidable — Magnus has no `abi3`
-    # equivalent). CI's in-job staging and a local `cargo build --release --features ruby`
-    # instead drop a single extension flat at lib/. Trying the versioned path first and the
-    # flat one second means neither has to know the other exists.
+    # equivalent), and `rake native:dev` — the local dev loop — stages its own build at that
+    # same versioned path. CI's in-job staging additionally drops a single extension flat at
+    # lib/, which is also where a hand copy of `cargo ruby-ext`'s output goes (the alias only
+    # builds into rust/target/ruby/release/; nothing but that rake task copies it here).
+    # Trying the versioned path first and the flat one second means neither has to know the
+    # other exists.
     #
     # A miss on both is not an error: it means this Ruby/platform combination has no
-    # precompiled extension, which is precisely what the Fiddle backend 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
@@ -500,21 +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 "not found" LoadError rather than a vaguer one
-          # from here.
-          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.3.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Brian Buvinghausen
@@ -51,12 +51,13 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.9'
-description: 'Booleans, numerics, 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. Two backends behind one surface,
-  selected automatically with nothing ever compiled: a Magnus extension where a precompiled
-  platform gem matches, stdlib Fiddle everywhere else. No runtime bridge, no dependencies
-  beyond Fiddle.'
+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. 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: []
@@ -65,20 +66,24 @@ files:
 - README.md
 - lib/hypercast.rb
 - lib/hypercast/native/linux-arm64/libhypercast.so
+- lib/hypercast/native/linux-musl-arm64/libhypercast.so
+- lib/hypercast/native/linux-musl-x64/libhypercast.so
 - 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
 metadata:
   source_code_uri: https://github.com/SkunkWerkx/HyperCast
+  changelog_uri: https://github.com/SkunkWerkx/HyperCast/blob/master/CHANGELOG.md
+  bug_tracker_uri: https://github.com/SkunkWerkx/HyperCast/issues
+  documentation_uri: https://github.com/SkunkWerkx/HyperCast/tree/master/ruby#readme
+  rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
 - lib
@@ -86,15 +91,15 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.2'
+      version: '3.3'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.16
+rubygems_version: 4.0.20
 specification_version: 4
-summary: Allocation-free scalar parsing as Success/Fault verdicts over a native Rust
-  core
+summary: Scalar parsing as Success/Fault verdicts over a native Rust core, shipped
+  prebuilt
 test_files: []

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