hypercast 0.3.0-x86_64-linux → 0.4.0-x86_64-linux

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: aee53d1b8f673abe7b19e073c8b50a5a26681ad0336ac9ce8667d2f3a6a7d429
-  data.tar.gz: a4639b10ee385435c10e180ac3697dab2dfb1ce28167246e8592c0d537eab333
+  metadata.gz: 39c6dc5065dbf206aa1760bf0385ea8bea8f131f11dea3489d92423614393e13
+  data.tar.gz: fbcb0af9091c853eebdb56aa1c85fb229844c52cb9995281396ad004f5500ae5
 SHA512:
-  metadata.gz: 6003a655d3dc6506a850b36514cae0e2b5a975197c66602b88dbd4008210ca0258e1bb42d4659c9b442cd5e1eade858bc7c0a0f9afdabc32d6664be3ecc1b081
-  data.tar.gz: 11511326d7eecf6bfe4431f215bc473db094e98d1d1c8420d027bc71fa2e04b473d19e16e32cfc9c3a5e6d17aca9e876c0c19b27591725520924b4e3838d4fcf
+  metadata.gz: 74f52267197d0934ff760441a2be4e4435891bb067bb6357f60c378a7a00bc58d52d53307698f9ba2e65e8a380596bbb7c2a32fb6701682f4c4a5335ae60269f
+  data.tar.gz: 9701f13462c868a190ab02f3acbd9e43acc71d30c4684a3160c291b22427bbbfaac6b890308468ae4a1283908250cfa494157aa3007aa874f40ce364ef148c74

data/README.md

@@ -1,28 +1,27 @@
 # 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
+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.**
 
 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.
+`HyperCast::BACKEND` reports which is live; `HYPERCAST_PURE=1` forces Fiddle,
+`HYPERCAST_WASM=1` the wasm module — 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 +51,43 @@ 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.
 
 ### Fault spans index the String you passed
 
@@ -136,15 +165,14 @@ and memoized by identity on every backend, so declaring a currency costs a cast
    corpus replay; cross-backend agreement specs compare Magnus against Fiddle
    and wasm 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,26 +181,78 @@ 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.)
 
+## Benchmarks
+
+`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 |
+
+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.
+
+## Backends
+
+| `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) |
+
+Selection happens once, at `require`, in that order. Two environment variables override it:
+
+| 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`.
+
+**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.
+
+**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
@@ -210,29 +290,20 @@ with `Memory#read`; using the guest's allocator rather than a host-picked offset
 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):
+Measured against the other two backends in the same session — the `wasmtime` column of the
+table under [Benchmarks](#benchmarks).
 
-| 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.
+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.
 
 ## 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 five 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 +314,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) and the wasm module — 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 +332,15 @@ 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.
+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.
 
 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 +348,19 @@ 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, …) |
-| --- | --- | --- |
-| 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 |
+| 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.
 
 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 +368,27 @@ 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.** 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.
 
 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 +399,82 @@ 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 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
+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
+
+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
+```
+
+`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_WITHOUT=wasm bundle install --quiet --prefer-local
+  HYPERCAST_PURE=1 BUNDLE_WITHOUT=wasm 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'
+```
 
 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.rb

@@ -3,16 +3,21 @@ 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 three 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
+# 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 +30,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.4.0"
 
   # The success case of a verdict: a cast value.
   Success = Data.define(:value)
@@ -50,25 +55,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 +92,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.
@@ -351,9 +365,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
 
@@ -437,13 +461,25 @@ 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|
+        cache.shift while cache.size >= PACKED_CACHE_LIMIT
         pointer = Fiddle::Pointer.malloc(32, Fiddle::RUBY_FREE)
         pointer[0, 32] = format.packed
         cache[format] = pointer
@@ -470,6 +506,10 @@ end
 # forces it (and fails loudly if wasmtime is missing); otherwise it is only ever chosen when
 # there is no native library for this platform at all and wasmtime happens to be available,
 # so no supported platform's behavior changes by its existence.
+#
+# Both variables are read for presence, not value — set to anything at all, "0" and the
+# empty string included, they force their backend — and HYPERCAST_WASM wins when both are
+# set.
 HyperCast::BACKEND =
   if ENV["HYPERCAST_WASM"]
     begin
@@ -486,9 +526,12 @@ HyperCast::BACKEND =
     # Two layouts, and both have to work. A released platform gem is a "fat" gem carrying one
     # extension per supported Ruby ABI under lib/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.
@@ -505,8 +548,9 @@ HyperCast::BACKEND =
         else
           # No shared library for this platform either. wasmtime, if the consumer has it,
           # is the only backend left that can run here; without it, stay on Fiddle so the
-          # first call raises its own precise "not found" LoadError rather than a vaguer one
-          # from here.
+          # first call raises its own precise error — a "not found" LoadError naming the
+          # path, or NativePlatform::UnsupportedPlatformError naming the platform — rather
+          # than a vaguer one from here. HyperCast.available? is the quiet way to ask.
           begin
             require "wasmtime"
             require_relative "hypercast/wasm_runtime"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hypercast
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: x86_64-linux
 authors:
 - Brian Buvinghausen
@@ -51,12 +51,14 @@ 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. 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.
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -67,6 +69,8 @@ files:
 - lib/hypercast/3.4/hypercast_native.so
 - lib/hypercast/4.0/hypercast_native.so
 - 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
@@ -81,6 +85,10 @@ 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
@@ -98,8 +106,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !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: []