hypercast 0.6.0-aarch64-linux-musl

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f3faf9c988a5e8ff5d927aa1ca98f838a4b0cc1b2226bcf8cd041471f8769acb
+  data.tar.gz: '085185fd364b6b9c77db85264e4485bcd2ef1607d57f7da134203113e02cc916'
+SHA512:
+  metadata.gz: a117b491a68581472304827e62beab4443c6bd15b4232d2387f07d0b5b9ea8a72bb97d37a038c7009ecb23c25288bd303ad9cac086e406c9c1732a751c50916f
+  data.tar.gz: 754deef4beefe1905da6537811c57ca5ad4c5daccd4394683c1f97e57f994f394a28b42e315253feaf49f847fe417c066524850604537def6383a89e460aee5e

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Skunk Werkx
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,440 @@
+# hypercast
+
+[![CI](https://github.com/SkunkWerkx/HyperCast/actions/workflows/ci.yml/badge.svg)](https://github.com/SkunkWerkx/HyperCast/actions/workflows/ci.yml)
+[![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 span that offended. Two backends, one public surface: a Magnus
+native extension where a precompiled platform gem covers you, stdlib Fiddle as the last
+resort everywhere else — selected automatically, zero compiles either way.**
+
+Allocation-lean scalar casts — booleans, the full integer family, reals, exact decimals,
+UUIDs, temporals — calling directly into the native `libhypercast` Rust core. Ruby 3.3 is the
+floor. The fast path links the core straight into a Ruby extension (Magnus): on require it
+redefines the doors in place on the `HyperCast` module — no delegation layer, no second
+surface, which is exactly what keeps the backends provably in agreement.
+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 #{offset}"
+end
+```
+
+Door names mirror the native ABI (`i32`, `f64`, `timestamp`, …). Ruby-flavored fidelity,
+stated proudly — nothing the core parses is lost on the way out: `Integer` is
+unbounded (u64 comes back as the true unsigned value), `Time` carries full nanoseconds
+across the whole 0001–9999 window, time-of-day is an exact Integer of nanoseconds since
+midnight, durations come back as exact `Rational` seconds across the core's whole
+±10,000-year window, and `decimal` returns an exact `HyperCast::Decimal` that never rounds
+— no truncation anywhere, no wrapping.
+
+## The doors
+
+| Door | Value | Declares |
+|---|---|---|
+| `bool(text)` | `true`/`false` | — |
+| `i8` `i16` `i32` `i64` `u8` `u16` `u32` `u64` `(text, format)` | `Integer` (unbounded — u64 is the true unsigned value) | a `NumFormat` |
+| `f32` `f64` `(text, format)` | `Float` (f32 widened losslessly) | a `NumFormat` |
+| `decimal(text, format)` | `HyperCast::Decimal` — exact sign, 96-bit magnitude, base-10 scale | a `NumFormat` |
+| `uuid(text)` | lowercase hyphenated `String` (`SecureRandom.uuid`'s shape) | — |
+| `timestamp(text)` | UTC `Time`, full nanoseconds | — |
+| `unix(text, precision)` | UTC `Time` | `:seconds` / `:milliseconds` / `:microseconds` / `:nanoseconds` |
+| `excel_serial(text, epoch)` | UTC `Time` | `:y1900` / `:y1904` |
+| `date(text, order = nil)` | `Date` | strict ISO, or `:year_month_day` / `:month_day_year` / `:day_month_year` |
+| `datetime(text, order)` | zone-less `DateTime`, exact `Rational` seconds | a field order, as `date` |
+| `time(text)` | `Integer` nanoseconds since midnight | — |
+| `duration(text)` | exact `Rational` seconds | — |
+
+Every door returns a `Success` or a `Fault`; `HyperCast.optional(verdict)` folds `:empty`
+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
+
+A `Fault`'s `offset`/`length` are in the units `String#[]` slices by on your own input:
+character offsets for text — in any encoding; the core reads UTF-8, and the span is mapped
+back, an identity for ASCII — and byte offsets for a binary (`ASCII-8BIT`) String, whose
+characters are its bytes. Either way `text[offset, length]` is the offending text with no
+arithmetic on your side:
+
+```ruby
+HyperCast.i32("1€", HyperCast::NumFormat::INVARIANT)     # => Fault(reason: :malformed, offset: 1, length: 1)
+HyperCast.i32("1€".b, HyperCast::NumFormat::INVARIANT)   # => Fault(reason: :malformed, offset: 1, length: 3)
+```
+
+The mapping happens only on the failure path, so a `Success` never pays for it.
+
+### `decimal`: exact, never rounded
+
+`HyperCast::Decimal` is a `Data` of `magnitude` (an unbounded `Integer`, at most 2⁹⁶ − 1),
+`scale` (0–28: places the magnitude is shifted right) and `negative` — the shape .NET's
+`decimal` stores and `BigDecimal` builds from directly. No float is ever formed, so `"0.1"`
+is one tenth and `"50%"` is exactly `0.5`. The triple is canonical: exact trailing zeros in
+the fraction are always trimmed, so the scale is minimal — `"1.10"`, `"1.1"` and `"1.1000"`
+are all magnitude 11, scale 1, while `"100"` stays magnitude 100, scale 0 — and zero is
+scale 0 and never negative. Nothing but a zero is ever dropped: text carrying more precision
+than 96 bits and 28 places can hold is an `:out_of_range` `Fault`, not an approximation.
+
+```ruby
+value = HyperCast.decimal("-1,234.50", HyperCast::NumFormat::INVARIANT).value
+value.to_s   # => "-1234.5"  (the canonical text, every binding renders the same)
+value.to_r   # => (-2469/2)
+value.to_d   # => BigDecimal("-1234.5")
+```
+
+`to_d` requires the `bigdecimal` gem lazily on first call — a bundled gem since Ruby 3.4,
+deliberately not a dependency of this one, so under Bundler add it to your own Gemfile.
+
+### `NumFormat`: declared separators, and a declared currency
+
+```ruby
+HyperCast::NumFormat.new(decimal_sep: ".", group_sep: ",", flags: HyperCast::ALL_STYLES, currency: "$")
+```
+
+The flags are `GROUPING`, `PARENTHESES`, `EXPONENT`, `RADIX_PREFIXES`, `PERCENT` and
+`CURRENCY` (`ALL_STYLES` is all six), plus the `SEPARATOR_DETECT` policy. The currency
+symbol is the one field a culture table would fill in: it is declared, never looked up, and
+honored only while `CURRENCY` is set — once, leading (`$5`, `-$5`, `$ -5`) or trailing
+(`5 €`, `1.234,50 kr.`), with optional ASCII whitespace between symbol and digits, and
+accounting parentheses wrapping symbol and digits together (`($5)`). Declared with the
+flag off, the symbol is a `:malformed` `Fault` at the symbol; the flag with nothing declared
+(`currency: ""`, the default — `INVARIANT` and `DETECT` declare none) matches nothing. A
+symbol longer than 16 UTF-8 bytes, or carrying an ASCII digit or ASCII whitespace, is an
+`ArgumentError` at construction, the same caller-bug treatment equal separators get.
+
+```ruby
+dollars = HyperCast::NumFormat.new(decimal_sep: ".", group_sep: ",", flags: HyperCast::ALL_STYLES, currency: "$")
+HyperCast.i32("($1,234)", dollars)        # => Success(value: -1234)
+HyperCast.decimal("$1,234.50", dollars)   # => Success(value: Decimal(magnitude: 12345, scale: 1, negative: false))
+HyperCast.i32("$5", HyperCast::NumFormat::INVARIANT)   # => Fault(reason: :malformed, offset: 0, length: 1)
+```
+
+Across the ABI a `NumFormat` is a 32-byte struct — the two separators as code points, the
+flags, and the symbol's length and UTF-8 bytes held inline — packed once per format object
+and memoized by identity on every backend, so declaring a currency costs a cast nothing.
+
+## Why not `Integer()` / `Time.iso8601` / `Float()`?
+
+1. **Verdicts, not exceptions** — bad data is the expected case for untrusted text; a
+   `Fault` is a Symbol and two integers, not an `ArgumentError` to rescue.
+2. **The vocabulary untrusted sources actually send** — twenty boolean lexemes, accounting
+   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 both backends, full corpus replay;
+   cross-backend agreement specs compare Magnus against Fiddle across a subprocess
+   boundary).
+4. **Faster than the stdlib on the Magnus backend, where the carrier is cheap** —
+   benchmark-ips (`ruby benchmark/cast_benchmark.rb`, linux-x64 on an Intel Core
+   i9-11900H, Ruby 4.0.7): timestamp **447 ns vs 2.97 µs `Time.iso8601`** (6.6x) — while
+   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
+   never be a recycled address — which turned the per-call cost into one pointer compare.
+   The three reason Symbols and the option Symbols (`:seconds`, `:month_day_year`, …) are
+   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:** 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. 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` for the other backend. The stdlib comparisons are in
+[the section above](#why-not-integer--timeiso8601--float); this is the two backends against
+each other.
+
+Measured on Ruby 4.0.7, linux-x64 (an Intel Core i9-11900H), `benchmark-ips`, same session,
+both backends:
+
+| Door | Magnus | Fiddle |
+|---|---:|---:|
+| `bool` | 112 ns | 2.35 µs |
+| `i32` | 133 ns | 2.63 µs |
+| `f64` | 166 ns | 2.70 µs |
+| `uuid` | 223 ns | 3.47 µs |
+| `timestamp` | 447 ns | 3.25 µs |
+| `datetime` (`1/7/2026 3:04 PM`) | 904 ns | 3.98 µs |
+| `duration` (ISO) | 632 ns | 2.91 µs |
+| `i32`, a fault | 225 ns | 3.18 µs |
+
+A lean door on the Magnus backend is little more than the native call: the extension builds
+the `Success` or `Fault` it returns directly — allocated, its members stored, frozen —
+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 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 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:
+
+```sh
+gem fetch hypercast -v X.Y.Z --platform <platform>   # or omit --platform for the universal gem
+gh attestation verify hypercast-X.Y.Z-<platform>.gem --repo SkunkWerkx/HyperCast
+```
+
+That's the release's second layer of checking, not the only one: before any gem gets built,
+the same job verifies every native binary it packs — the Fiddle libraries, the Magnus
+extensions (one per Ruby ABI per platform) — 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
+verbatim" into a per-release measurement rather than an assumption — see
+[csharp/README.md's provenance section](../csharp/README.md#native-binary-provenance) for
+more on why `--signer-repo` is needed for some artifacts here and not others.
+
+## Install
+
+```sh
+gem install hypercast
+```
+
+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
+the way [the Python binding's](../python/) wheels do — so each platform gem is a "fat" gem
+carrying one compiled extension per supported Ruby, under `lib/hypercast/<minor>/`, and picks
+one at `require` time:
+
+| Ruby | Linux (glibc and musl), Apple silicon macOS, Windows — x64 and arm64 | Gem installed |
+| --- | --- | --- |
+| a newer Ruby than the release covers (4.1+) | Fiddle | universal |
+| 4.0 (primary) | Magnus, `BACKEND == :native` | platform |
+| 3.4 (until its EOL 2028-03-31) | Magnus, `BACKEND == :native` | platform |
+| 3.3 (the floor, until its EOL 2027-03-31) | Fiddle | universal |
+
+What stands behind each cell: CI replays the whole suite, shared corpus included, through
+each Magnus extension on every push — Ruby 3.4 and 4.0 on all seven platform-gem platforms,
+the two musl ones inside each Ruby's own Alpine image — and the Fiddle suite on Ruby 4.0 on
+every one of them, plus on Ruby 3.3 inside Alpine. Intel macOS has no CI leg: its library is
+cross-built and tested at the core, and Ruby there runs the universal gem's Fiddle backend
+over it. Anywhere else — a platform with no native build at all — the universal gem installs
+but `HyperCast.available?` answers `false`, and the first call raises
+`HyperCast::NativePlatform::UnsupportedPlatformError`.
+
+The platform gems declare `required_ruby_version >= 3.4, < 4.1` precisely so RubyGems
+*declines* them outside that range and resolves the universal gem instead — a wrong-ABI
+extension must never be installed in the first place. On Windows it would at least fail to
+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.
+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
+`aarch64-mingw-ucrt`, both `supported: true` in its own `data/toolchains.json`); the one it
+has no support for is MSVC. Windows is also where the Fiddle fallback cost the most, so these
+are the most worthwhile gems in the set. Both extensions are built for the `gnullvm` Rust
+targets rather than `gnu` — the same mingw-w64/UCRT ABI RubyInstaller's Ruby uses, linked
+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 `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

@@ -0,0 +1,28 @@
+module HyperCast
+  # Maps the running RUBY_PLATFORM to the RID-style directory (matching the other bindings'
+  # runtimes/{rid}/native/ / native/{rid}/ convention) and native library filename to load.
+  module NativePlatform
+    class UnsupportedPlatformError < StandardError; end
+
+    # +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 platform
+      when /mingw|mswin|windows/
+        ["win-#{arch}", "hypercast.dll"]
+      when /darwin/
+        ["osx-#{arch}", "libhypercast.dylib"]
+      when /linux/
+        # 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=#{platform}"
+      end
+    end
+  end
+end

data/lib/hypercast/runtime.rb

@@ -0,0 +1,128 @@
+# 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 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")
+
+    # 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: :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
+    # core's packed version word (major << 16 | minor << 8 | patch) rather than a verdict
+    # code — so it gets its own Fiddle signature beside DOORS instead of a row in it.
+    VERSION_PROBE = :hypercast_version
+
+    @mutex = Mutex.new
+    @functions = nil
+
+    class << self
+      # The door's (or VERSION_PROBE's) Fiddle::Function, for the caller to invoke directly
+      # — a splat-through `call(symbol, *args)` here built and re-splatted an Array on
+      # every cast.
+      def function(symbol)
+        functions.fetch(symbol)
+      end
+
+      # 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
+
+      # The shared library to dlopen: this install's native/{rid}/{lib}, or — the
+      # development loop — the in-repo cargo build, exactly what the other bindings' local
+      # staging does. Nil when neither exists.
+      def library_path
+        rid, lib_name = NativePlatform.rid_and_library_name
+        path = File.join(NATIVE_DIR, rid, lib_name)
+        return path if File.exist?(path)
+
+        repo_build = File.expand_path(File.join(__dir__, "../../../rust/target/release", lib_name))
+        File.exist?(repo_build) ? repo_build : nil
+      end
+
+      # 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
+      # real slice of the door cost; the benign race re-checks under the lock.
+      def functions
+        @functions || @mutex.synchronize { @functions ||= load_functions }
+      end
+
+      def load_functions
+        path = library_path
+        raise LoadError, missing_library_message if path.nil?
+
+        handle = Fiddle.dlopen(path)
+        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)
+        functions
+      end
+    end
+  end
+end

data/lib/hypercast.rb

@@ -0,0 +1,538 @@
+require "date"
+require_relative "hypercast/native_platform"
+require_relative "hypercast/runtime"
+
+# Allocation-lean scalar casts — booleans, numerics, exact decimals, UUIDs, temporals —
+# from one Rust core, reached through whichever of 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 #{offset}"
+#   end
+#
+# Door names mirror the native ABI (i32, f64, timestamp, ...) so the polyglot surface reads
+# identically across bindings. Ruby-flavored fidelity: Integer is unbounded (u64 comes back
+# as the true unsigned value), Time carries full nanoseconds across the whole 0001-9999
+# window, time-of-day is an exact Integer of nanoseconds since midnight, durations come
+# back as exact Rational seconds, and the decimal door returns an exact Decimal (sign,
+# 96-bit magnitude, base-10 scale) that never rounds — no truncation anywhere, and no
+# wrapping: Ruby and the JVM are the fidelity kings of this roster.
+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.6.0"
+
+  # The success case of a verdict: a cast value.
+  Success = Data.define(:value)
+
+  # The failure case: a closed reason Symbol (:empty, :malformed, :out_of_range) plus the
+  # offending span, in the units String#[] slices by on the text you passed: character
+  # offsets for text (in any encoding — the core reads UTF-8 and the span is mapped back),
+  # byte offsets for a binary (ASCII-8BIT) String, whose characters are its bytes. Either
+  # way `text[offset, length]` is the offending text, with no mapping on your side.
+  # Nothing is captured — slicing it out of the input is the caller's choice.
+  Fault = Data.define(:reason, :offset, :length)
+
+  # The native core's failure codes, mapped to the closed reason Symbols a Fault carries.
+  REASONS = { 1 => :empty, 2 => :malformed, 3 => :out_of_range }.freeze
+
+  # Caller-declared numeric notation for the integer, real and decimal doors — declared out
+  # loud (INVARIANT, or a literal), never defaulted, the same stance every binding takes.
+  # The currency symbol is the one field a culture table would fill in: it is declared
+  # here, never looked up, and honored only while the CURRENCY flag is set — declared with
+  # the flag off, the symbol is a :malformed Fault at the symbol, and the flag with no
+  # symbol ("" — the default) matches nothing. Equal separators, or a symbol longer than
+  # 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
+    # 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. 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)
+      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 ]/)
+
+      super(decimal_sep: decimal_sep, group_sep: group_sep, flags: flags, currency: symbol)
+    end
+
+    # The 32-byte little-endian form the native ABI's NumFormat struct expects: the two
+    # separators as code points, the flags, the symbol's byte length, then the symbol's
+    # UTF-8 bytes zero-padded to 16.
+    def packed
+      [decimal_sep.ord, group_sep.ord, flags, currency.bytesize].pack("L<L<L<L<") + [currency].pack("a16")
+    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.
+  PARENTHESES = 1 << 1
+  # Permit exponent notation. Integer doors reject a negative exponent.
+  EXPONENT = 1 << 2
+  # Permit 0x/&H/0b two's-complement radix prefixes (0xFF is -1 for an i8).
+  RADIX_PREFIXES = 1 << 3
+  # Permit a trailing %, dividing by 100. Real and decimal doors only.
+  PERCENT = 1 << 4
+  # Resolve the ./, roles per input from structure instead of the declared separators
+  # (which are ignored while this flag is set). Detection, not sniffing: a repeated
+  # separator is grouping ("1.234.567,89"); with both present the rightmost is the
+  # decimal; a single separator with a non-3-digit right run is the decimal ("3,1415");
+  # with exactly 3 digits right, only a 0 integer part proves decimal ("0,785").
+  # Genuinely ambiguous input ("12.185", "1,000") is a :malformed Fault at the separator,
+  # never guessed.
+  SEPARATOR_DETECT = 1 << 5
+  # Permit the format's declared currency symbol at either edge of the numeric body —
+  # leading ("$5", "-$5", "$ -5") or trailing ("5 €", "1.234,50 kr."), once, with optional
+  # ASCII whitespace between symbol and digits; accounting parentheses wrap the symbol
+  # along with the digits ("($5)"). With no symbol declared the flag matches nothing.
+  # Integer, real and decimal doors.
+  CURRENCY = 1 << 6
+  # Every lenience on (SEPARATOR_DETECT is a separator policy, not a lenience, and is
+  # deliberately not included).
+  ALL_STYLES = GROUPING | PARENTHESES | EXPONENT | RADIX_PREFIXES | PERCENT | CURRENCY
+
+  # The invariant profile — '.' decimal, ',' grouping, every lenience on, no currency
+  # symbol declared.
+  NumFormat::INVARIANT = NumFormat.new(decimal_sep: ".", group_sep: ",", flags: ALL_STYLES)
+
+  # The detection profile — every lenience on, ./, roles resolved per input by
+  # SEPARATOR_DETECT's structural rules.
+  NumFormat::DETECT = NumFormat.new(decimal_sep: ".", group_sep: ",",
+                                    flags: ALL_STYLES | SEPARATOR_DETECT)
+
+  # The declared unit of a Unix-epoch value — no magnitude guessing, ever.
+  UNIX_PRECISIONS = { seconds: 1, milliseconds: 2, microseconds: 3, nanoseconds: 4 }.freeze
+
+  # The date system an Excel serial number is expressed in. Spreadsheets carry no marker
+  # for this — it is a workbook-level setting — so the caller states it, the same way
+  # UNIX_PRECISIONS and DATE_ORDERS are declared rather than guessed.
+  EXCEL_EPOCHS = { y1900: 1, y1904: 2 }.freeze
+
+  # The declared field order of a separated calendar date — no guessing, ever: "1/7/2026"
+  # is January 7th (:month_day_year, the en-US order) or July 1st (:day_month_year, the
+  # en-GB order) only because the caller said which.
+  DATE_ORDERS = { year_month_day: 1, month_day_year: 2, day_month_year: 3 }.freeze
+
+  # An exact decimal, the decimal door's value: an unbounded Integer magnitude (the core's
+  # 96-bit unsigned, so at most 2**96 - 1), an Integer base-10 scale (0..28 — the number of
+  # places the magnitude is shifted right), and a negative flag. The value is
+  # (negative ? -1 : 1) * magnitude * 10**-scale. The triple is canonical: exact trailing
+  # zeros in the fraction are always trimmed, so the scale is minimal ("1.10", "1.1" and
+  # "1.1000" are all magnitude 11, scale 1; "100" stays magnitude 100, scale 0), and zero
+  # is scale 0 and never negative. Nothing but a zero is ever dropped — text carrying more
+  # precision than the core holds is an :out_of_range Fault, never an approximation.
+  # Convert with to_r (exact Rational), to_s (the canonical text), or to_d (BigDecimal).
+  Decimal = Data.define(:magnitude, :scale, :negative) do
+    # True for a negative value; zero is never negative.
+    def negative?
+      negative
+    end
+
+    # The value as an exact Rational.
+    def to_r
+      value = Rational(magnitude, 10**scale)
+      negative ? -value : value
+    end
+
+    # The canonical text form — "-1234.5", "-0.025", "0": the minimal scale rendered
+    # plainly, no exponent — the same string every binding renders and the conformance
+    # corpus pins as `value`.
+    def to_s
+      digits = magnitude.to_s.rjust(scale + 1, "0")
+      text = scale.zero? ? digits : "#{digits[0, digits.length - scale]}.#{digits[-scale, scale]}"
+      negative ? "-#{text}" : text
+    end
+
+    # The value as a BigDecimal, built exactly from the canonical text. Requires the
+    # bigdecimal gem (a bundled gem since Ruby 3.4, not a dependency of this one — add it
+    # to your Gemfile under Bundler), loaded lazily on first use so a consumer who never
+    # calls this pays nothing for it.
+    def to_d
+      require "bigdecimal"
+      BigDecimal(to_s)
+    end
+  end
+
+  class << self
+    # Presents a verdict optionally: an :empty fault becomes nil (Ruby's absent),
+    # everything else flows through untouched.
+    def optional(verdict)
+      return nil if verdict in Fault(reason: :empty)
+
+      verdict
+    end
+
+    # 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 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?
+
+      @available = begin
+        native_version.is_a?(String)
+      rescue LoadError, StandardError
+        false
+      end
+    end
+
+    # Casts boolean text: true/false plus the conventions untrusted sources actually send
+    # (t/f, yes/no, y/n, 1/0, on/off, enabled/disabled, active/inactive,
+    # checked/unchecked, in/out), ASCII case-insensitive.
+    def bool(text)
+      plain(:cast_bool, text, 1) { |out| out.unpack1("C") != 0 }
+    end
+
+    { i8: "c", i16: "s<", i32: "l<", i64: "q<", u8: "C", u16: "S<", u32: "L<", u64: "Q<" }
+      .each do |door, unpack|
+      sizes = { "c" => 1, "C" => 1, "s<" => 2, "S<" => 2, "l<" => 4, "L<" => 4, "q<" => 8, "Q<" => 8 }
+      size = sizes.fetch(unpack)
+      # Resolved once here, not inside the method: interpolating a Symbol per call built a
+      # String and interned it on every integer cast.
+      symbol = :"cast_#{door}"
+      # Integer doors: the target type's own range, declared grouping, accounting parens,
+      # non-negative exponent, and 0x/&H/0b two's-complement radix prefixes. Ruby Integer
+      # is unbounded, so u64 comes back as the true unsigned value.
+      define_method(door) do |text, format|
+        numeric(symbol, text, format, size) { |out| out.unpack1(unpack) }
+      end
+    end
+
+    # Casts real text to an IEEE single (widened losslessly on the way out): finite values
+    # only, declared separators and grouping, parens, exponent, and trailing percent.
+    def f32(text, format)
+      numeric(:cast_f32, text, format, 4) { |out| out.unpack1("e") }
+    end
+
+    # Casts real text to an IEEE double. Notation rules as f32.
+    def f64(text, format)
+      numeric(:cast_f64, text, format, 8) { |out| out.unpack1("E") }
+    end
+
+    # Casts decimal text to an exact Decimal — the real doors' grammar (declared separators
+    # and grouping, parens, exponent, trailing percent, declared currency), but no float is
+    # ever formed: "0.1" is one tenth, "50%" is exactly 0.5 (magnitude 5, scale 1), and
+    # "1.10" is canonical magnitude 11, scale 1 — exact trailing zeros are always trimmed.
+    # A magnitude past 2**96 - 1, or more fractional precision than 28 places can hold, is
+    # an :out_of_range Fault — the door never rounds.
+    def decimal(text, format)
+      numeric(:cast_decimal, text, format, 16) do |out|
+        lo, hi, scale, negative = out.unpack("Q<L<CCx2")
+        Decimal.new(magnitude: (hi << 64) | lo, scale: scale, negative: negative != 0)
+      end
+    end
+
+    # Casts UUID text — all five .NET Guid formats (D/N/B/P/X) plus urn:uuid:/GUID:/UUID:
+    # prefixes — to Ruby's UUID lingua franca: the lowercase hyphenated String (the same
+    # shape SecureRandom.uuid returns).
+    def uuid(text)
+      plain(:cast_uuid, text, 16) do |out|
+        out.unpack("H8H4H4H4H12").join("-")
+      end
+    end
+
+    # Casts an RFC 3339 instant — zone mandatory — to a UTC Time at full nanosecond
+    # fidelity across the whole 0001-9999 window.
+    def timestamp(text)
+      plain(:cast_timestamp, text, 16) { |out| instant(out) }
+    end
+
+    # Casts an integer Unix-epoch value under a caller-declared unit Symbol
+    # (:seconds/:milliseconds/:microseconds/:nanoseconds) to a UTC Time. An unknown unit
+    # is a caller bug (KeyError), never a verdict.
+    def unix(text, precision)
+      declared(:cast_unix, text, UNIX_PRECISIONS.fetch(precision), 16) { |out| instant(out) }
+    end
+
+    # Casts an Excel date serial under a caller-declared epoch Symbol (:y1900/:y1904) to a
+    # UTC Time. The whole part counts days from the system's own day zero and the fraction
+    # is the time of day, so "45292.75" is 2024-01-01T18:00:00Z; a cell carries no zone and
+    # none is invented.
+    #
+    # 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 :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)
+      declared(:cast_excel_serial, text, EXCEL_EPOCHS.fetch(epoch), 16) { |out| instant(out) }
+    end
+
+    # Casts a calendar date to a Date. With no order declared: the strict ISO 8601
+    # yyyy-MM-dd form only. With a declared order Symbol (:year_month_day,
+    # :month_day_year, :day_month_year), also the separated forms — "1/7/2026" is
+    # January 7th or July 1st only because the caller said which; an unknown order is a
+    # caller bug (KeyError), never a verdict.
+    def date(text, order = nil)
+      if order.nil?
+        plain(:cast_date, text, 4) do |out|
+          year, month, day = out.unpack("S<CC")
+          Date.new(year, month, day)
+        end
+      else
+        declared(:cast_date_ordered, text, DATE_ORDERS.fetch(order), 4) do |out|
+          year, month, day = out.unpack("S<CC")
+          Date.new(year, month, day)
+        end
+      end
+    end
+
+    # Casts a zone-less civil date-time — the shape untrusted feeds actually send
+    # ("1/7/2026 3:04 PM", "2026-01-07 15:04:05") — under a declared order Symbol to a
+    # stdlib DateTime with exact Rational seconds. No zone is *read*: the text names no
+    # instant, and the parse applies no offset. Ruby has no zone-less date-time type, so
+    # the value rides a DateTime, whose offset defaults to +00:00 — that zero is a carrier
+    # artifact, not data (the same caveat PHP's UTC-labeled DateTimeImmutable carries);
+    # fusing a real zone is the caller's job, and timestamp stays the strict RFC 3339
+    # instant door. An unknown order is a caller bug (KeyError).
+    def datetime(text, order)
+      declared(:cast_datetime, text, DATE_ORDERS.fetch(order), 16) do |out|
+        year, month, day, nanos = out.unpack("S<CCx4Q<")
+        second_of_day, frac = nanos.divmod(1_000_000_000)
+        hour, rest = second_of_day.divmod(3600)
+        minute, second = rest.divmod(60)
+        DateTime.new(year, month, day, hour, minute, second + Rational(frac, 1_000_000_000))
+      end
+    end
+
+    # Casts an ISO 24-hour time-of-day to an exact Integer of nanoseconds since midnight
+    # (Ruby has no time-of-day type; the integer keeps every digit).
+    def time(text)
+      plain(:cast_time, text, 8) { |out| out.unpack1("Q<") }
+    end
+
+    # Casts a duration (ISO 8601 fixed components, invariant colon form, or protobuf JSON
+    # seconds) to exact Rational seconds — full fidelity across the core's ±10,000-year
+    # window, no wrapping and no truncation.
+    def duration(text)
+      plain(:cast_duration, text, 16) do |out|
+        seconds, nanos = out.unpack("q<l<")
+        Rational(seconds * 1_000_000_000 + nanos, 1_000_000_000)
+      end
+    end
+
+    # The version of the native core actually loaded, as "major.minor.patch" — read from
+    # the library itself, not from this gem, so a consumer can prove the core behind the
+    # doors is the one this binding was built against (and name the mismatch when it is
+    # not). The cheapest possible probe that the backend resolved at all: takes nothing,
+    # cannot fail.
+    def native_version
+      word = packed_version
+      "#{word >> 16}.#{(word >> 8) & 0xFF}.#{word & 0xFF}"
+    end
+
+    private
+
+    # Encodings whose bytes already are the UTF-8 (or byte-identical) form the core reads.
+    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 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
+
+    # Fiddle spells a null pointer as nil — the core's contract for empty input.
+    def input_ptr(bytes)
+      bytes.empty? ? nil : bytes
+    end
+
+    # One 24-byte scratch allocation per thread, reused by every call: out-value at 0
+    # (16 bytes covers every door, and malloc's alignment covers the decimal's 8), fault
+    # span at 16. Two Fiddle::Pointer.malloc(..., RUBY_FREE) calls per cast — each
+    # 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. 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 = Runtime.buffer(24)
+        [base, base + 16]
+      end
+    end
+
+    # Presents a native return code as the verdict union: 0 yields a Success, a failure
+    # code becomes a Fault over `bytes` (the UTF-8 the core read), and -1 (contract
+    # violation) is a binding bug that raises.
+    def verdict(rc, fault, bytes)
+      if rc.zero?
+        Success.new(value: yield)
+      elsif rc == -1
+        raise "hypercast: libhypercast reported a contract violation — a binding bug, please report it"
+      else
+        offset, length = characters(bytes, *fault[0, 8].unpack("L<L<"))
+        Fault.new(reason: REASONS.fetch(rc), offset: offset, length: length)
+      end
+    end
+
+    # The core's byte span in the units String#[] slices by: an identity for a binary
+    # String (its characters are its bytes) and for ASCII text (`ascii_only?` reads the
+    # cached coderange — no scan), a byte-to-character remap otherwise. Character counts
+    # survive transcoding, so a span mapped on the UTF-8 form indexes the caller's own
+    # String whatever encoding it arrived in. Failure path only: a Success never pays.
+    def characters(bytes, offset, length)
+      return [offset, length] if bytes.encoding == Encoding::ASCII_8BIT || bytes.ascii_only?
+
+      [bytes.byteslice(0, offset).length, bytes.byteslice(offset, length).length]
+    end
+
+    # The shared body of every format-free door: one native call over the scratch buffers.
+    def plain(symbol, text, out_size)
+      bytes = utf8(text)
+      out, fault = scratch
+      rc = Runtime.function(symbol).call(input_ptr(bytes), bytes.bytesize, out, fault)
+      verdict(rc, fault, bytes) { yield(out[0, out_size]) }
+    end
+
+    # The shared body of the integer/real/decimal doors: plain, plus the format's own
+    # packed pointer, passed straight through — no per-call copy of the 32 bytes into
+    # scratch.
+    def numeric(symbol, text, format, out_size)
+      bytes = utf8(text)
+      out, fault = scratch
+      rc = Runtime.function(symbol).call(input_ptr(bytes), bytes.bytesize, packed_cache[format], out, fault)
+      verdict(rc, fault, bytes) { yield(out[0, out_size]) }
+    end
+
+    # 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 Fiddle crossing.
+    def declared(symbol, text, code, out_size)
+      bytes = utf8(text)
+      out, fault = scratch
+      rc = Runtime.function(symbol).call(input_ptr(bytes), bytes.bytesize, code, out, fault)
+      verdict(rc, fault, bytes) { yield(out[0, out_size]) }
+    end
+
+    # The loaded core's version word, major << 16 | minor << 8 | patch, straight from the
+    # library's zero-argument hypercast_version export.
+    def packed_version
+      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 = Runtime.buffer(32)
+        pointer[0, 32] = format.packed
+        cache[format] = pointer
+      end.compare_by_identity
+    end
+
+    # Builds a UTC Time from the core's protobuf-shaped {seconds, nanos} pair, exactly.
+    def instant(bytes)
+      seconds, nanos = bytes.unpack("q<l<")
+      Time.at(seconds, nanos, :nanosecond, in: "UTC")
+    end
+  end
+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 — 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.
+#
+# 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_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), 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. 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
+    rescue LoadError
+      begin
+        require "hypercast_native"
+        :native
+      rescue LoadError
+        :fiddle
+      end
+    end
+  end

metadata

@@ -0,0 +1,88 @@
+--- !ruby/object:Gem::Specification
+name: hypercast
+version: !ruby/object:Gem::Version
+  version: 0.6.0
+platform: aarch64-linux-musl
+authors:
+- Brian Buvinghausen
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+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: []
+files:
+- LICENSE
+- README.md
+- lib/hypercast.rb
+- lib/hypercast/3.4/hypercast_native.so
+- lib/hypercast/4.0/hypercast_native.so
+- lib/hypercast/native_platform.rb
+- lib/hypercast/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
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.4'
+  - - "<"
+    - !ruby/object:Gem::Version
+      version: '4.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.20
+specification_version: 4
+summary: Scalar parsing as Success/Fault verdicts over a native Rust core, shipped
+  prebuilt
+test_files: []