hypercast 0.0.1-x86_64-linux

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 85037e8e8a6ed9d74ec0f8aef3e75d8155414ad98a4aa2e2027eaad5b67ad167
+  data.tar.gz: 66dc72911256b109d1eb81f657aa480baf94f19caa84941527c192df3ad173eb
+SHA512:
+  metadata.gz: b949139ee23e8458242d4dbc23fd0bb7202a39d2099bd9a1826a7d3cff48cd473a5b33a76de97f328fbee347b6f8bb0c2554288507a4cb3d9e8ac7179e170a80
+  data.tar.gz: ef46835aa9fa469b0b40061f1b5e52c50f316dcca6881ada3d549295eee398b45a21471610e60c76388e267a842c682d52b97e1f4a7d08516158b138a9183490

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,79 @@
+# hypercast
+
+[![CI](https://github.com/SkunkWerkx/HyperCast/actions/workflows/ci.yml/badge.svg)](https://github.com/SkunkWerkx/HyperCast/actions/workflows/ci.yml)
+
+**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
+   1.073M i/s against 1.092M i/s for the same text under a declared eurozone format —
+   inside the error bars.
+
+**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. (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.)
+
+## Install
+
+Not on RubyGems yet — the release pipeline is staged (`.github/workflows/release.yml`,
+Trusted Publishing pending): 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. Until the first tag: clone
+the repo, `cargo build --release` in `rust/` (plus `--features ruby`, staged to
+`lib/hypercast_native.so`, for the Magnus backend), and `bundle exec rspec`.
+
+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,68 @@
+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
+      def call(symbol, *args)
+        functions.fetch(symbol).call(*args)
+      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,334 @@
+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.0.1"
+
+  # 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)
+      # 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) }
+      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.call(:cast_unix, 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.call(:cast_excel_serial, 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.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")
+          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.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<")
+        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 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.
+    def scratch
+      Thread.current[:hypercast_scratch] ||= begin
+        base = Fiddle::Pointer.malloc(36, Fiddle::RUBY_FREE)
+        [base, base + 16, base + 24]
+      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.call(symbol, 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 packed NumFormat.
+    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]) }
+    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).
+    def packed_cache
+      @packed_cache ||= Hash.new { |cache, format| cache[format] = format.packed }
+    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
+    begin
+      require "hypercast_native"
+      :native
+    rescue LoadError
+      :fiddle
+    end
+  end

metadata

@@ -0,0 +1,99 @@
+--- !ruby/object:Gem::Specification
+name: hypercast
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: x86_64-linux
+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/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
+- lib/hypercast_native.so
+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.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Allocation-free scalar parsing as Success/Fault verdicts over a native Rust
+  core
+test_files: []