hypercast 0.1.0-x86_64-linux → 0.3.0-x86_64-linux

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 407ae1ab9906171822de8b0f52ae3e87cbafccb300817c2924dd57a5c3704334
-  data.tar.gz: 7599c7638a989cd6e928e9684d6df90394dbe1b494ea8ff1cf8f2253d8b4e19c
+  metadata.gz: aee53d1b8f673abe7b19e073c8b50a5a26681ad0336ac9ce8667d2f3a6a7d429
+  data.tar.gz: a4639b10ee385435c10e180ac3697dab2dfb1ce28167246e8592c0d537eab333
 SHA512:
-  metadata.gz: c6dc288ee5102b23c16eebc5b88516352b73b984a5976459b69b14fc96d4e014df3b46a4a0a3495ef63e0da92dd714094c6a058ec1dcd85b2f7b2906cbfa874b
-  data.tar.gz: edd8eb78d4505ff350b51f957b275086f4d9a8d587c146e8449ea3f5a4fb01128fdc4c7ec8f8e72a956637e8d7ea489a3454c966c7bc6aeb9a83bf0fde49214e
+  metadata.gz: 6003a655d3dc6506a850b36514cae0e2b5a975197c66602b88dbd4008210ca0258e1bb42d4659c9b442cd5e1eade858bc7c0a0f9afdabc32d6664be3ecc1b081
+  data.tar.gz: 11511326d7eecf6bfe4431f215bc473db094e98d1d1c8420d027bc71fa2e04b473d19e16e32cfc9c3a5e6d17aca9e876c0c19b27591725520924b4e3838d4fcf

data/README.md

@@ -5,17 +5,19 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/SkunkWerkx/HyperCast/blob/master/LICENSE)
 
 **Ruby's own pattern matching over two `Data` case types — the value, or a closed reason
-Symbol plus the exact byte span that offended. Two backends, one public surface: a Magnus
+Symbol plus the exact byte span that offended. Three backends, one public surface: a Magnus
 native extension where a precompiled platform gem covers you, stdlib Fiddle everywhere
-else — selected automatically, zero compiles either way.**
+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, UUIDs, temporals —
-calling directly into the native `libhypercast` Rust core. Ruby 3.2 is the floor
+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.
+forces Fiddle, `HYPERCAST_WASM=1` the wasm module — see
+[WebAssembly (wasmtime)](#webassembly-wasmtime).
 
 ```ruby
 case HyperCast.i32("(1,234)", HyperCast::NumFormat::INVARIANT)
@@ -28,8 +30,99 @@ Door names mirror the native ABI (`i32`, `f64`, `timestamp`, …). Ruby-flavored
 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, and durations come back as exact `Rational` seconds across the core's whole
-±10,000-year window — no truncation anywhere, no wrapping.
+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, `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.)
+
+### 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()`?
 
@@ -39,18 +132,26 @@ midnight, and durations come back as exact `Rational` seconds across the core's
    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 (24 examples green on *both* backends, full twelve-file corpus
-   replay; a cross-backend agreement spec compares Magnus and Fiddle outputs across a
-   subprocess boundary).
+   held by the shared corpus (the whole suite green on *all three* backends, full
+   corpus replay; cross-backend agreement specs compare Magnus against Fiddle
+   and wasm against Fiddle across a subprocess boundary).
 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
-   1.073M i/s against 1.092M i/s for the same text under a declared eurozone format —
-   inside the error bars.
+   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
+   `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, 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
@@ -63,9 +164,95 @@ defaults to `+00:00`, which is an artifact of the type, not a zone the parse ass
 
 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. (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.)
+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
+per-call `Fiddle::Pointer.malloc` finalizers were hoisted to thread-local scratch —
+receipts include their own archaeology.)
+
+## WebAssembly (wasmtime)
+
+The Rust core also ships inside this gem as a `wasm32-wasip1` module
+(`lib/hypercast/native/wasm32-wasip1/hypercast.wasm`), and the
+[`wasmtime`](https://rubygems.org/gems/wasmtime) gem can run it in-process. This is the
+inverse of ruby.wasm — not Ruby inside a wasm sandbox, but a wasm module inside Ruby — and
+it is the one backend that needs no shared library for the platform it runs on: no
+`dlopen`, no Magnus extension, nothing compiled against this Ruby's ABI. The Magnus
+extension replaces every public door in place; this backend replaces only the four private
+bodies underneath them (`plain`, `numeric`, `declared`, `packed_version` — the whole native
+crossing), so every door, both verdict `Data` types, the Symbol tables and the
+`Time`/`DateTime`/`Rational`/`Decimal` carriers are the exact code the other two backends
+run. `spec/wasm_backend_spec.rb` pins that the outputs agree with the Fiddle backend byte for
+byte.
+
+`wasmtime` is deliberately **not** a dependency of this gem; a consumer who wants this path
+installs it:
+
+```sh
+gem install wasmtime
+HYPERCAST_WASM=1 ruby -rhypercast -e 'p HyperCast::BACKEND'   # => :wasm
+```
+
+`HYPERCAST_WASM=1` forces the backend (and raises a `LoadError` naming the gem if it is
+missing). Without it, the wasm backend is only ever chosen automatically when there is no
+native library for this platform at all — no Magnus extension and no `libhypercast` for the
+RID — and `wasmtime` happens to be installed. No supported platform's behavior changes just
+because this backend exists.
+
+Two things are different under the sandbox, both by necessity. A wasm guest only sees its own
+linear memory, so the input is copied into a grow-only guest buffer and the out-value, fault
+span and `NumFormat` live in guest allocations made once at load — all from the module's own
+exported `malloc` (the same wasi-libc allocator Rust's std uses on that target), read back
+with `Memory#read`; using the guest's allocator rather than a host-picked offset is what keeps
+a buffer from being clobbered by the guest's next allocation. And a `Wasmtime::Store` is
+single-threaded, so every call is serialized under one Mutex around one shared instance.
+
+Measured, same box as the benchmarks above (Ruby 4.0.6, linux-arm64 under WSL2, wasmtime
+48.0.1, `benchmark-ips`, same session, all three backends):
+
+| Door | Magnus | Fiddle | wasmtime |
+|---|---:|---:|---:|
+| `bool` | 484 ns | 2.55 µs | 2.07 µs |
+| `i32` | 555 ns | 2.78 µs | 2.65 µs |
+| `f64` | 529 ns | 2.72 µs | 2.73 µs |
+| `uuid` | 640 ns | 3.32 µs | 3.53 µs |
+| `timestamp` | 769 ns | 3.12 µs | 3.10 µs |
+| `datetime` (`1/7/2026 3:04 PM`) | 1.36 µs | 3.97 µs | 3.66 µs |
+| `duration` (ISO) | 975 ns | 2.84 µs | 2.47 µs |
+| `i32`, a fault | 658 ns | 2.89 µs | 2.42 µs |
+
+The finding worth stating: in Ruby the wasm backend lands at Fiddle parity, door for door.
+Fiddle's per-call floor is interpreted marshalling; wasmtime's is the host-to-guest crossing
+plus the guest memory copies; on this box they cost the same, and both sit 4-5x behind the
+Magnus extension. So on a platform with no native build, the fallback costs a consumer
+nothing they were not already paying on the universal gem.
+
+## Verifying provenance
+
+Every gem RubyGems.org serves — the universal fallback and each of the six 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 (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.
+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
 
@@ -73,11 +260,41 @@ include their own archaeology.)
 gem install hypercast
 ```
 
-Five gems are published per release: one universal `ruby`-platform gem (pure Fiddle, all six
-platforms' natives bundled) plus four precompiled Magnus platform gems (`x86_64-linux`,
-`aarch64-linux`, `x86_64-darwin`, `arm64-darwin`) that `gem install` auto-selects when they
-match. Nobody ever compiles anything; Windows and any unmatched platform land on the
-universal gem's Fiddle backend, which replays the same corpus green.
+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.
+
+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 | 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 |
+
+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.
+Every cell in that table replays the same corpus green.
+
+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 `hyper-build-native.yml`, shared with every other Hyper* repo.
 
 See [the repo root README](../README.md) for the full door table, the receipts, and the
 state of every other language binding.

data/lib/hypercast/runtime.rb

@@ -18,23 +18,53 @@ module HyperCast
       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_f32: NUMERIC, cast_f64: NUMERIC, cast_decimal: NUMERIC,
       cast_uuid: PLAIN,
       cast_timestamp: PLAIN, cast_unix: UNIX, cast_excel_serial: UNIX,
       cast_date: PLAIN, cast_date_ordered: UNIX, cast_datetime: UNIX,
       cast_time: PLAIN, cast_duration: PLAIN
     }.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
-      def call(symbol, *args)
-        functions.fetch(symbol).call(*args)
+      # 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
+
+      # Whether this platform has a shared library for Fiddle to dlopen at all: a known RID
+      # and the file actually present — in this install, or in the in-repo cargo build the
+      # dev loop falls back to. Backend selection (hypercast.rb) asks this before falling
+      # back to the WebAssembly backend, which needs neither.
+      def fiddle_library_available?
+        !library_path.nil?
+      rescue NativePlatform::UnsupportedPlatformError
+        false
       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
+
       # 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
@@ -44,24 +74,21 @@ module HyperCast
       end
 
       def load_functions
-        rid, lib_name = NativePlatform.rid_and_library_name
-        path = File.join(NATIVE_DIR, rid, lib_name)
-        unless File.exist?(path)
-          # Development loop: fall back to the in-repo cargo build, exactly what the other
-          # bindings' local staging does.
-          repo_build = File.expand_path(File.join(__dir__, "../../../rust/target/release", lib_name))
-          path = repo_build if File.exist?(repo_build)
-        end
-        unless File.exist?(path)
+        path = library_path
+        if path.nil?
+          rid, lib_name = NativePlatform.rid_and_library_name
           raise LoadError,
-                "hypercast: #{path} not found (unsupported platform, or this gem was built " \
-                "without a native library for it)"
+                "hypercast: #{File.join(NATIVE_DIR, rid, lib_name)} not found (unsupported " \
+                "platform, or this gem was built without a native library for it)"
         end
 
         handle = Fiddle.dlopen(path)
-        DOORS.to_h do |name, signature|
+        functions = DOORS.to_h do |name, signature|
           [name, Fiddle::Function.new(handle[name.to_s], signature, Fiddle::TYPE_INT32_T)]
         end
+        functions[VERSION_PROBE] =
+          Fiddle::Function.new(handle[VERSION_PROBE.to_s], [], Fiddle::TYPE_UINT32_T)
+        functions
       end
     end
   end

data/lib/hypercast/wasm_runtime.rb

@@ -0,0 +1,169 @@
+require "wasmtime"
+
+module HyperCast
+  # The WebAssembly backend: the same Rust core, compiled once to a `wasm32-wasip1` module
+  # (lib/hypercast/native/wasm32-wasip1/hypercast.wasm) and run inside this process by the
+  # `wasmtime` gem — no per-platform shared library needed, and nothing dlopen'd. This is the
+  # inverse of ruby.wasm: not Ruby running inside a wasm sandbox, but a wasm module running
+  # inside Ruby.
+  #
+  # Same integration shape as the Magnus extension: on require (after hypercast.rb has
+  # defined the pure-Fiddle module) this redefines methods **in place** on HyperCast — no
+  # delegation layer, no second surface. The Magnus extension replaces every public door;
+  # this file replaces only the four private bodies underneath them (`plain`, `numeric`,
+  # `declared`, `packed_version` — the whole native crossing), so every door, every verdict
+  # type, `utf8`, `verdict`, `instant` and the Symbol tables stay the exact code the other
+  # two backends run, byte for byte.
+  #
+  # Two things differ from the native backends, both forced by the sandbox:
+  #
+  # * A wasm guest only sees its own linear memory, so no Fiddle::Pointer can cross. The
+  #   input text is copied into a grow-only guest buffer, and the three out-params the doors
+  #   fill — the 16-byte out-value, the 8-byte fault span, the 32-byte NumFormat — are guest
+  #   allocations made once at load, all from the module's own exported `malloc` (the
+  #   wasi-libc allocator Rust's std already uses on this target) and read back with
+  #   `Memory#read`. Using the guest's allocator rather than a host-picked offset is
+  #   load-bearing: dlmalloc claims the tail of the initial memory on first use, and
+  #   HyperUuid observed a buffer written at a guessed offset corrupted by the guest's next
+  #   allocation.
+  # * A `Wasmtime::Store` is single-threaded, so every call is serialized under one Mutex
+  #   around one shared instance per process.
+  module WasmRuntime
+    MODULE_PATH = File.join(Runtime::NATIVE_DIR, "wasm32-wasip1", "hypercast.wasm")
+    # Development loop: the in-repo cargo build, the same fallback runtime.rb takes for the
+    # native library.
+    REPO_BUILD_PATH = File.expand_path(
+      File.join(__dir__, "../../../rust/target/wasm32-wasip1/release/hypercast.wasm")
+    )
+
+    DOORS = Runtime::DOORS.keys.freeze
+
+    # One instantiated module: the exported functions, the exported memory, and the guest
+    # buffers every door crosses through for the life of the process.
+    class Instance
+      attr_reader :memory, :out, :fault, :format
+
+      def initialize
+        path = File.exist?(MODULE_PATH) ? MODULE_PATH : REPO_BUILD_PATH
+        unless File.exist?(path)
+          raise LoadError,
+                "hypercast: #{MODULE_PATH} not found (this gem was built without its WebAssembly module)"
+        end
+
+        engine = Wasmtime::Engine.new
+        mod = Wasmtime::Module.from_file(engine, path)
+        linker = Wasmtime::Linker.new(engine)
+        # The module imports four WASI preview1 functions — wasi-libc's startup and panic
+        # plumbing (environ_*, fd_write, proc_exit); the core itself needs no clock and no
+        # entropy. A default WasiConfig — no stdio, no filesystem, no environment — is all
+        # any of them need.
+        Wasmtime::WASI::P1.add_to_linker_sync(linker)
+        store = Wasmtime::Store.new(engine, wasi_p1_config: Wasmtime::WasiConfig.new)
+        instance = linker.instantiate(store, mod)
+
+        @memory = instance.export("memory").to_memory
+        @fn = (DOORS + [Runtime::VERSION_PROBE] + %i[malloc free]).to_h do |name|
+          export = instance.export(name.to_s) or
+            raise LoadError, "hypercast: #{path} does not export #{name} (a module older than this binding)"
+          [name, export.to_func]
+        end
+        # dlmalloc hands back 8-byte-aligned (in fact 16) blocks, which covers the
+        # decimal out-value's 8-byte alignment.
+        @out = malloc(16)
+        @fault = malloc(8)
+        @format = malloc(32)
+        # Grow-only buffer for the input text, so a steady stream of ordinary scalars never
+        # touches the guest allocator again.
+        @in = 0
+        @in_cap = 0
+        # The format currently written at @format, memoized by identity: formats are reused
+        # constants in practice, and NumFormat is a frozen Data, so one `equal?` skips the
+        # 32-byte write on the overwhelming majority of numeric calls. The Instance holds
+        # the format it memoized, so the key can never be a recycled object.
+        @last_format = nil
+      end
+
+      def fn(name)
+        @fn.fetch(name)
+      end
+
+      def malloc(size)
+        ptr = @fn[:malloc].call(size)
+        raise NoMemoryError, "hypercast: wasm malloc(#{size}) failed" if ptr.zero?
+
+        ptr
+      end
+
+      # Copies the input into the guest and returns its address — 0 (the ABI's NULL) for
+      # empty input, which the core never dereferences.
+      def stage_input(bytes)
+        size = bytes.bytesize
+        return 0 if size.zero?
+
+        if size > @in_cap
+          @fn[:free].call(@in) unless @in.zero?
+          @in = malloc(size)
+          @in_cap = size
+        end
+        @memory.write(@in, bytes)
+        @in
+      end
+
+      def stage_format(format)
+        unless format.equal?(@last_format)
+          @memory.write(@format, format.packed)
+          @last_format = format
+        end
+        @format
+      end
+    end
+
+    @mutex = Mutex.new
+    @instance = nil
+
+    # Every call holds the one lock: the Store is single-threaded, and the lazily created
+    # instance is shared by every thread for the life of the process (never torn down,
+    # same as the dlopen'd library natively).
+    def self.with_instance
+      @mutex.synchronize do
+        @instance ||= Instance.new
+        yield @instance
+      end
+    end
+  end
+
+  class << self
+    private
+
+    # The four crossing bodies, redefined over the guest. Each door body reads the
+    # out-value back only on success and the fault span only on a failure code, so
+    # `verdict` sees exactly what the Fiddle path hands it.
+    def plain(symbol, text, out_size)
+      bytes = utf8(text)
+      WasmRuntime.with_instance do |w|
+        rc = w.fn(symbol).call(w.stage_input(bytes), bytes.bytesize, w.out, w.fault)
+        verdict(rc, rc.zero? ? nil : w.memory.read(w.fault, 8), bytes) { yield(w.memory.read(w.out, out_size)) }
+      end
+    end
+
+    def numeric(symbol, text, format, out_size)
+      bytes = utf8(text)
+      WasmRuntime.with_instance do |w|
+        rc = w.fn(symbol).call(w.stage_input(bytes), bytes.bytesize, w.stage_format(format), w.out, w.fault)
+        verdict(rc, rc.zero? ? nil : w.memory.read(w.fault, 8), bytes) { yield(w.memory.read(w.out, out_size)) }
+      end
+    end
+
+    def declared(symbol, text, code, out_size)
+      bytes = utf8(text)
+      WasmRuntime.with_instance do |w|
+        rc = w.fn(symbol).call(w.stage_input(bytes), bytes.bytesize, code, w.out, w.fault)
+        verdict(rc, rc.zero? ? nil : w.memory.read(w.fault, 8), bytes) { yield(w.memory.read(w.out, out_size)) }
+      end
+    end
+
+    def packed_version
+      WasmRuntime.with_instance { |w| w.fn(Runtime::VERSION_PROBE).call }
+    end
+  end
+end

data/lib/hypercast.rb

@@ -2,10 +2,11 @@ require "date"
 require_relative "hypercast/native_platform"
 require_relative "hypercast/runtime"
 
-# Allocation-lean scalar casts — booleans, numerics, 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.
+# 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.
 #
 # Consume with Ruby's own pattern matching over the two Data case types:
 #
@@ -17,43 +18,68 @@ require_relative "hypercast/runtime"
 # 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, and durations come
-# back as exact Rational seconds — no truncation anywhere, and no wrapping: Ruby and the
-# JVM are the fidelity kings of this roster.
+# 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.1.0"
+  VERSION = "0.3.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 as byte offsets into the UTF-8 input. Nothing is captured — slicing the
-  # offending text out of the input is the caller's choice.
+  # 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 and real doors — declared out loud
-  # (INVARIANT, or a literal), never defaulted, the same stance every binding takes.
-  # Equal separators are a caller bug (ArgumentError), never a verdict.
-  NumFormat = Data.define(:decimal_sep, :group_sep, :flags) do
+  # 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
+    # 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 — so a malformed format fails loudly as the caller bug it is.
-    def initialize(decimal_sep:, group_sep:, flags:)
+    # 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.
+    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
       raise ArgumentError, "decimal and group separators must differ; both are #{decimal_sep.inspect}" if
         decimal_sep == group_sep
-      super
+      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
+      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 12-byte little-endian form the native ABI's NumFormat struct expects.
+    # 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].pack("L<L<L<")
+      [decimal_sep.ord, group_sep.ord, flags, currency.bytesize].pack("L<L<L<L<") + [currency].pack("a16")
     end
   end
 
@@ -65,7 +91,7 @@ module HyperCast
   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 doors only.
+  # 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
@@ -75,11 +101,18 @@ module HyperCast
   # 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
+  ALL_STYLES = GROUPING | PARENTHESES | EXPONENT | RADIX_PREFIXES | PERCENT | CURRENCY
 
-  # The invariant profile — '.' decimal, ',' grouping, every lenience on.
+  # 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
@@ -100,6 +133,46 @@ module HyperCast
   # 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.
@@ -109,6 +182,24 @@ module HyperCast
       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 older core without the version
+    # export, or a wasm module the wasmtime gem cannot instantiate all answer false. The
+    # doors themselves keep their own behavior — the first call on an unavailable backend
+    # raises its precise LoadError, exactly as before — and so does require-time selection
+    # under HYPERCAST_WASM=1 without wasmtime; this only answers the question quietly.
+    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.
@@ -120,11 +211,14 @@ module HyperCast
       .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(:"cast_#{door}", text, format, size) { |out| out.unpack1(unpack) }
+        numeric(symbol, text, format, size) { |out| out.unpack1(unpack) }
       end
     end
 
@@ -139,6 +233,19 @@ module HyperCast
       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).
@@ -158,11 +265,7 @@ module HyperCast
     # (:seconds/:milliseconds/:microseconds/:nanoseconds) to a UTC Time. An unknown unit
     # is a caller bug (KeyError), never a verdict.
     def unix(text, precision)
-      code = UNIX_PRECISIONS.fetch(precision)
-      bytes = utf8(text)
-      out, fault, = scratch
-      rc = Runtime.call(:cast_unix, input_ptr(bytes), bytes.bytesize, code, out, fault)
-      verdict(rc, fault) { instant(out[0, 16]) }
+      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
@@ -176,11 +279,7 @@ module HyperCast
     # 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)
-      code = EXCEL_EPOCHS.fetch(epoch)
-      bytes = utf8(text)
-      out, fault, = scratch
-      rc = Runtime.call(:cast_excel_serial, input_ptr(bytes), bytes.bytesize, code, out, fault)
-      verdict(rc, fault) { instant(out[0, 16]) }
+      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
@@ -195,12 +294,8 @@ module HyperCast
           Date.new(year, month, day)
         end
       else
-        code = DATE_ORDERS.fetch(order)
-        bytes = utf8(text)
-        out, fault, = scratch
-        rc = Runtime.call(:cast_date_ordered, input_ptr(bytes), bytes.bytesize, code, out, fault)
-        verdict(rc, fault) do
-          year, month, day = out[0, 4].unpack("S<CC")
+        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
@@ -215,12 +310,8 @@ module HyperCast
     # 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)
-      code = DATE_ORDERS.fetch(order)
-      bytes = utf8(text)
-      out, fault, = scratch
-      rc = Runtime.call(:cast_datetime, input_ptr(bytes), bytes.bytesize, code, out, fault)
-      verdict(rc, fault) do
-        year, month, day, nanos = out[0, 16].unpack("S<CCx4Q<")
+      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)
@@ -244,6 +335,16 @@ module HyperCast
       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.
@@ -261,51 +362,92 @@ module HyperCast
       bytes.empty? ? nil : bytes
     end
 
-    # One 36-byte scratch allocation per thread, reused by every call: out-value at 0
-    # (16 bytes covers every door), fault span at 16, NumFormat at 24. 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.
+    # 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.
     def scratch
       Thread.current[:hypercast_scratch] ||= begin
-        base = Fiddle::Pointer.malloc(36, Fiddle::RUBY_FREE)
-        [base, base + 16, base + 24]
+        base = Fiddle::Pointer.malloc(24, Fiddle::RUBY_FREE)
+        [base, base + 16]
       end
     end
 
     # Presents a native return code as the verdict union: 0 yields a Success, a failure
-    # code becomes a Fault, and -1 (contract violation) is a binding bug that raises.
-    def verdict(rc, fault)
+    # 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 = fault[0, 8].unpack("L<L<")
+        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.call(symbol, input_ptr(bytes), bytes.bytesize, out, fault)
-      verdict(rc, fault) { yield(out[0, out_size]) }
+      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 doors: plain, plus the packed NumFormat.
+    # 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, raw_format = scratch
-      raw_format[0, 12] = packed_cache[format]
-      rc = Runtime.call(symbol, input_ptr(bytes), bytes.bytesize, raw_format, out, fault)
-      verdict(rc, fault) { yield(out[0, out_size]) }
+      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 native crossing:
+    # the wasm backend (wasm_runtime.rb) redefines exactly these four in place and nothing
+    # above them.
+    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
 
-    # Identity-keyed memo of NumFormat#packed — formats are reused constants in practice,
-    # and re-packing per call is a measurable allocation. The race is benign (idempotent).
+    # 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
+
+    # 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).
     def packed_cache
-      @packed_cache ||= Hash.new { |cache, format| cache[format] = format.packed }
+      @packed_cache ||= Hash.new do |cache, format|
+        pointer = Fiddle::Pointer.malloc(32, Fiddle::RUBY_FREE)
+        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.
@@ -321,14 +463,58 @@ end
 # drops to an ordinary extension call. The pure-Fiddle definitions stay the universal
 # zero-compile fallback; precompiled platform gems are how the extension ships without
 # ever making a consumer compile anything. Set HYPERCAST_PURE=1 to force Fiddle.
+#
+# The third backend is WebAssembly (lib/hypercast/wasm_runtime.rb): the same core as a
+# wasm32-wasip1 module, run in-process by the `wasmtime` gem, which is deliberately not a
+# runtime dependency of this gem — a consumer who wants it installs it. HYPERCAST_WASM=1
+# forces it (and fails loudly if wasmtime is missing); otherwise it is only ever chosen when
+# there is no native library for this platform at all and wasmtime happens to be available,
+# so no supported platform's behavior changes by its existence.
 HyperCast::BACKEND =
-  if ENV["HYPERCAST_PURE"]
+  if ENV["HYPERCAST_WASM"]
+    begin
+      require "wasmtime"
+    rescue LoadError
+      raise LoadError,
+            "hypercast: HYPERCAST_WASM=1 needs the wasmtime gem — `gem install wasmtime` (or add it to your Gemfile)"
+    end
+    require_relative "hypercast/wasm_runtime"
+    :wasm
+  elsif ENV["HYPERCAST_PURE"]
     :fiddle
   else
+    # Two layouts, and both have to work. A released platform gem is a "fat" gem carrying one
+    # extension per supported Ruby ABI under lib/hypercast/<minor>/ (see the Rakefile's
+    # native:gem task for why an ABI-per-file is unavoidable — Magnus has no `abi3`
+    # equivalent). CI's in-job staging and a local `cargo build --release --features ruby`
+    # instead drop a single extension flat at lib/. Trying the versioned path first and the
+    # flat one second means neither has to know the other exists.
+    #
+    # 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.
     begin
-      require "hypercast_native"
+      require "hypercast/#{RUBY_VERSION[/\d+\.\d+/]}/hypercast_native"
       :native
     rescue LoadError
-      :fiddle
+      begin
+        require "hypercast_native"
+        :native
+      rescue LoadError
+        if HyperCast::Runtime.fiddle_library_available?
+          :fiddle
+        else
+          # No shared library for this platform either. wasmtime, if the consumer has it,
+          # is the only backend left that can run here; without it, stay on Fiddle so the
+          # first call raises its own precise "not found" LoadError rather than a vaguer one
+          # from here.
+          begin
+            require "wasmtime"
+            require_relative "hypercast/wasm_runtime"
+            :wasm
+          rescue LoadError
+            :fiddle
+          end
+        end
+      end
     end
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hypercast
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: x86_64-linux
 authors:
 - Brian Buvinghausen
@@ -64,15 +64,18 @@ files:
 - LICENSE
 - README.md
 - lib/hypercast.rb
+- 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-x64/libhypercast.so
 - lib/hypercast/native/osx-arm64/libhypercast.dylib
 - lib/hypercast/native/osx-x64/libhypercast.dylib
+- lib/hypercast/native/wasm32-wasip1/hypercast.wasm
 - lib/hypercast/native/win-arm64/hypercast.dll
 - lib/hypercast/native/win-x64/hypercast.dll
 - lib/hypercast/native_platform.rb
 - lib/hypercast/runtime.rb
-- lib/hypercast_native.so
+- lib/hypercast/wasm_runtime.rb
 homepage: https://github.com/SkunkWerkx/HyperCast
 licenses:
 - MIT
@@ -85,14 +88,17 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.2'
+      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: 3.6.9
+rubygems_version: 4.0.16
 specification_version: 4
 summary: Allocation-free scalar parsing as Success/Fault verdicts over a native Rust
   core