hypercast 0.2.0-aarch64-mingw-ucrt

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b5854bf2c44466f015a6d7a3be2638666676b3da2dd94ec122623873f6028fbc
+  data.tar.gz: 491e38ce3e41dca9da6b3d423c9781781691f0c751d4ef091a3fe0366dad9982
+SHA512:
+  metadata.gz: f9f7abd169594ec16b7c8b793b69a916765fbb6805c243eb9df219253c46817ee47bcf5fbe1df43a2e3e22dc77561e2cd758ce478f34f07d312bdf94ab77b127
+  data.tar.gz: 853a3b9083791629c3301830c4286de12f37619cab6c36f890ac5012142813d3a3da39ca0303339777e82ee8ca5ed99caefcf3c6359c5a41a6f7dd70f12eb333

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,150 @@
+# hypercast
+
+[![CI](https://github.com/SkunkWerkx/HyperCast/actions/workflows/ci.yml/badge.svg)](https://github.com/SkunkWerkx/HyperCast/actions/workflows/ci.yml)
+[![Gem](https://img.shields.io/gem/v/hypercast.svg)](https://rubygems.org/gems/hypercast)
+[![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
+native extension where a precompiled platform gem covers you, stdlib Fiddle everywhere
+else — selected automatically, zero compiles either way.**
+
+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
+(`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.
+
+```ruby
+case HyperCast.i32("(1,234)", HyperCast::NumFormat::INVARIANT)
+in HyperCast::Success(value:) then puts "got #{value}"          # -1234
+in HyperCast::Fault(reason:, offset:) then puts "#{reason} at byte #{offset}"
+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, and durations come back as exact `Rational` seconds across the core's whole
+±10,000-year window — no truncation anywhere, no wrapping.
+
+## 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 (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).
+4. **Faster than the stdlib on the Magnus backend, where the carrier is cheap** —
+   benchmark-ips (`ruby benchmark/cast_benchmark.rb`, linux-arm64): timestamp **713 ns vs
+   2.88 µs `Time.iso8601`** (4.0x) — while returning exact `Rational` durations on the
+   duration door. The Fiddle fallback lands at ~3.5 µs: parity with `Time.iso8601`, sitting
+   on Fiddle's measured 1.6 µs per-call marshalling floor.
+
+   Separator detection is free here: `1.234.567,89` under `NumFormat::DETECT` runs at
+   591 ns against 570 ns for the same text under a declared eurozone format — inside the
+   error bars. Both of those were ~990 ns in 0.1.0, for a reason that had nothing to do
+   with parsing: every format other than `INVARIANT` paid three method dispatches and two
+   `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
+against `Date.strptime`'s 619 ns. The parse isn't the problem; the carrier is. Building a
+stdlib `DateTime` with an exact `Rational` second costs more than the whole native call,
+where the timestamp door's `Time` is built by a single cheap `rb_time_nano_new`. Printed
+because it's real: if you want Ruby's fastest civil parse and don't need the verdict or the
+declared order, `strptime` wins. Also note the carrier's other caveat — `DateTime`'s offset
+defaults to `+00:00`, which is an artifact of the type, not a zone the parse assigned.
+
+On the Fiddle fallback the doors are parity-at-best — Fiddle's
+per-call floor is the mechanism's price, kept because it's the universal zero-compile
+path. 0.2.0 still took ~20% off its numeric doors (`i32` 3.37 → 2.62 µs, `f64` 3.31 →
+2.76 µs, same session) by not building things per call that never changed: the integer
+doors interpolated and interned their `:cast_*` Symbol on every call, every door went
+through a splat-and-resplat dispatcher, and every numeric call copied the format's 12
+packed bytes into scratch — each format now owns one native pointer, memoized by identity,
+passed straight through. (Benchmark forensics worth knowing: the doors read 4.3 µs until
+per-call `Fiddle::Pointer.malloc` finalizers were hoisted to thread-local scratch —
+receipts include their own archaeology.)
+
+## 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
+
+```sh
+gem install hypercast
+```
+
+Seven gems are published per release: one universal `ruby`-platform gem (pure Fiddle, all
+six platforms' natives bundled) plus six precompiled Magnus platform gems (`x86_64-linux`,
+`aarch64-linux`, `x86_64-darwin`, `arm64-darwin`, `x64-mingw-ucrt`, `aarch64-mingw-ucrt`)
+that `gem install` auto-selects when they match. Nobody ever compiles anything.
+
+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/native_platform.rb

@@ -0,0 +1,22 @@
+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
+
+    def self.rid_and_library_name
+      is_arm = RUBY_PLATFORM.match?(/arm64|aarch64/)
+
+      case RUBY_PLATFORM
+      when /mingw|mswin|windows/
+        is_arm ? ["win-arm64", "hypercast.dll"] : ["win-x64", "hypercast.dll"]
+      when /darwin/
+        is_arm ? ["osx-arm64", "libhypercast.dylib"] : ["osx-x64", "libhypercast.dylib"]
+      when /linux/
+        is_arm ? ["linux-arm64", "libhypercast.so"] : ["linux-x64", "libhypercast.so"]
+      else
+        raise UnsupportedPlatformError, "hypercast: unsupported platform RUBY_PLATFORM=#{RUBY_PLATFORM}"
+      end
+    end
+  end
+end

data/lib/hypercast/runtime.rb

@@ -0,0 +1,70 @@
+require "fiddle"
+
+module HyperCast
+  # Fiddle plumbing for the native libhypercast shared library — dlopen/dlsym plus raw
+  # C-ABI calls, no runtime bridge. Fiddle ships with every Ruby install; it's a plain gem
+  # dependency here rather than a third-party one. A Ruby gem's files are already plain
+  # files on disk once installed, so native/{rid}/{lib} dlopen's directly — no extraction.
+  module Runtime
+    NATIVE_DIR = File.join(__dir__, "native")
+
+    PLAIN = [Fiddle::TYPE_VOIDP, Fiddle::TYPE_SIZE_T, Fiddle::TYPE_VOIDP, Fiddle::TYPE_VOIDP].freeze
+    NUMERIC = [Fiddle::TYPE_VOIDP, Fiddle::TYPE_SIZE_T, Fiddle::TYPE_VOIDP, Fiddle::TYPE_VOIDP,
+               Fiddle::TYPE_VOIDP].freeze
+    UNIX = [Fiddle::TYPE_VOIDP, Fiddle::TYPE_SIZE_T, Fiddle::TYPE_UINT32_T, Fiddle::TYPE_VOIDP,
+            Fiddle::TYPE_VOIDP].freeze
+
+    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_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
+
+    @mutex = Mutex.new
+    @functions = nil
+
+    class << self
+      # The door'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
+
+      private
+
+      # 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
+        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)
+          raise LoadError,
+                "hypercast: #{path} 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|
+          [name, Fiddle::Function.new(handle[name.to_s], signature, Fiddle::TYPE_INT32_T)]
+        end
+      end
+    end
+  end
+end

data/lib/hypercast.rb

@@ -0,0 +1,360 @@
+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.
+#
+# Consume with Ruby's own pattern matching over the two Data case types:
+#
+#   case HyperCast.i32("(1,234)", HyperCast::NumFormat::INVARIANT)
+#   in HyperCast::Success(value:) then puts "got #{value}"          # -1234
+#   in HyperCast::Fault(reason:, offset:) then puts "#{reason} at byte #{offset}"
+#   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, 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.
+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.2.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.
+  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
+    # 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:)
+      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
+    end
+
+    # The 12-byte little-endian form the native ABI's NumFormat struct expects.
+    def packed
+      [decimal_sep.ord, group_sep.ord, flags].pack("L<L<L<")
+    end
+  end
+
+  # 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 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
+  # 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
+
+  # The invariant profile — '.' decimal, ',' grouping, every lenience on.
+  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
+
+  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
+
+    # 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 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)
+      code = UNIX_PRECISIONS.fetch(precision)
+      bytes = utf8(text)
+      out, fault, = scratch
+      rc = Runtime.function(:cast_unix).call(input_ptr(bytes), bytes.bytesize, code, out, fault)
+      verdict(rc, fault) { instant(out[0, 16]) }
+    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 :malformed 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)
+      code = EXCEL_EPOCHS.fetch(epoch)
+      bytes = utf8(text)
+      out, fault, = scratch
+      rc = Runtime.function(:cast_excel_serial).call(input_ptr(bytes), bytes.bytesize, code, out, fault)
+      verdict(rc, fault) { instant(out[0, 16]) }
+    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
+        code = DATE_ORDERS.fetch(order)
+        bytes = utf8(text)
+        out, fault, = scratch
+        rc = Runtime.function(:cast_date_ordered).call(input_ptr(bytes), bytes.bytesize, code, out, fault)
+        verdict(rc, fault) do
+          year, month, day = out[0, 4].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)
+      code = DATE_ORDERS.fetch(order)
+      bytes = utf8(text)
+      out, fault, = scratch
+      rc = Runtime.function(:cast_datetime).call(input_ptr(bytes), bytes.bytesize, code, out, fault)
+      verdict(rc, fault) do
+        year, month, day, nanos = out[0, 16].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
+
+    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 bytes for void* directly — no Pointer wrapper, no dup); only
+    # foreign encodings pay a transcode.
+    def utf8(text)
+      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), 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(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)
+      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<")
+        Fault.new(reason: REASONS.fetch(rc), offset: offset, length: length)
+      end
+    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) { yield(out[0, out_size]) }
+    end
+
+    # The shared body of the integer/real doors: plain, plus the format's own packed
+    # pointer, passed straight through — no per-call copy of the 12 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) { yield(out[0, out_size]) }
+    end
+
+    # Identity-keyed memo (compare_by_identity — a pointer hash, not Data's structural
+    # #hash over two Strings and an Integer) of a native 12-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 do |cache, format|
+        pointer = Fiddle::Pointer.malloc(12, Fiddle::RUBY_FREE)
+        pointer[0, 12] = 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; precompiled platform gems are how the extension ships without
+# ever making a consumer compile anything. Set HYPERCAST_PURE=1 to force Fiddle.
+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). 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/#{RUBY_VERSION[/\d+\.\d+/]}/hypercast_native"
+      :native
+    rescue LoadError
+      begin
+        require "hypercast_native"
+        :native
+      rescue LoadError
+        :fiddle
+      end
+    end
+  end

metadata

@@ -0,0 +1,103 @@
+--- !ruby/object:Gem::Specification
+name: hypercast
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: aarch64-mingw-ucrt
+authors:
+- Brian Buvinghausen
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: fiddle
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !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, UUIDs, and temporals cast from untrusted text by
+  a native Rust core — every parse returns a verdict (the value, or a reason plus
+  the offending span), never an exception for bad data. Two backends behind one surface,
+  selected automatically with nothing ever compiled: a Magnus extension where a precompiled
+  platform gem matches, stdlib Fiddle everywhere else. No runtime bridge, no dependencies
+  beyond Fiddle.'
+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/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/win-arm64/hypercast.dll
+- lib/hypercast/native/win-x64/hypercast.dll
+- 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
+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.16
+specification_version: 4
+summary: Allocation-free scalar parsing as Success/Fault verdicts over a native Rust
+  core
+test_files: []