hypercast-wasm 0.6.1 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 25e1d8efcfd0a330dc46665c67c6ab2fea5a6739c5101694b7fffc1e96676d1e
-  data.tar.gz: df0939ade9f6f8ce761ea44db684a3194624874a75deee25791cbf4873a4e63f
+  metadata.gz: 292a3d7a2650810b8c764162479aed060b9e05e04a15e12843bbe9d4a1e5f4ec
+  data.tar.gz: '066569a04c5f82dd1ca427c58b0483c3fa0505bd414fe80add69dea5002a9667'
 SHA512:
-  metadata.gz: f27aa076ab1ad70fd64317a6faa7de15f422d52a4b085e455eb8a0568c0287b245b529254f59638d676c8f8530ab804a9bf999ff96d013885862ea9135e6bc0e
-  data.tar.gz: cf3fddc48a1405b8a328f7fa5b39c15e3440d8eeda147336150faaf968610b78443c1d2455ed2050d9bab743f2429c49fbc0abc5a87e93b3a4210a604e81cf4f
+  metadata.gz: 4c654511c4167a2addf7cb4894811c755bd6a9a9a5b7ae9bf3c35b7d24ff36cac233af75d61e7430dc7b08ef84dacf53801bf7853415a0887cbb8a61d9839b6b
+  data.tar.gz: 3e7cefe5d32a2c8f0495eb37a93460499ed2673c7452b12f9eb6b2fa90ff5258607042564460e972027f23ba486b5210d758fa9efb49d4ae98534dc3b9754fa6

data/README.md

@@ -50,6 +50,10 @@ midnight, durations come back as exact `Rational` seconds across the core's whol
 | `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 | — |
+| `decimal_from_float(value)` | `HyperCast::Decimal`, the shortest that names the number (`0.1` is one tenth) | — |
+| `excel_serial_from_float(value, epoch)` | zone-less `DateTime`, as `datetime` | `:y1900` / `:y1904` |
+| `excel_time(value)` | `Integer` nanoseconds since midnight | — |
+| `excel_duration(value)` | exact `Rational` seconds | — |
 
 Every door returns a `Success` or a `Fault`; `HyperCast.optional(verdict)` folds `:empty`
 to `nil`. Beside the doors, `native_version` returns the loaded core's
@@ -156,6 +160,38 @@ Across the ABI a `NumFormat` is a 32-byte struct — the two separators as code
 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.
 
+## Interop: building on HyperCast's C ABI
+
+For a gem that carries HyperCast's verdicts across a C ABI of its own, as HyperTabular does:
+it reads the core's out-values out of its own buffers and needs the values the doors would
+have returned. `HyperCast::Interop` is the code the Fiddle backend's doors decode with, so
+the two cannot drift. It is loaded on every backend.
+
+- `SCALARS` — the `String#unpack` directive for one value of each scalar door (`:i32` is
+  `"l<"`; a bool is the byte 0 or 1).
+- `RECORDS` — for each record door (`:decimal`, `:uuid`, `:timestamp`, `:date`, …), the
+  directive that unpacks one value, how many fields that yields, and a lambda
+  `(fields, at)` that builds the Ruby value from them. To decode a column, append `"*"` and
+  step that many fields at a time.
+- `VALUE_BYTES` — the bytes one value of each door takes.
+- `decode(door, bytes)` — one value, from the bytes the core wrote for it.
+- `fault(code, offset, length)` — the `Fault` a nonzero verdict code names; a code that names
+  no reason is a `KeyError`.
+- `characters(bytes, offset, length)` — the core's byte span as the character span
+  `String#[]` slices by.
+- `version(word)` — a packed `*_version` word as `"major.minor.patch"`.
+- `library_path(library, native_dir, repo_root)` — the shared library to `dlopen`: the
+  staged `native/{rid}/` build, else the in-repo cargo build, else `nil`.
+
+`NativePlatform.rid_and_library_name(library: "hypertabular")` gives the `{rid}` directory
+and file name for any SkunkWerkx core; `library:` defaults to `"hypercast"`.
+
+```ruby
+HyperCast::Interop.decode(:i32, [-7].pack("l<"))           # => -7
+HyperCast::Interop.fault(2, 3, 1)                          # => Fault, reason :malformed
+HyperCast::Interop.version(0x000700)                       # => "0.7.0"
+```
+
 ## Why not `Integer()` / `Time.iso8601` / `Float()`?
 
 1. **Verdicts, not exceptions** — bad data is the expected case for untrusted text; a
@@ -169,12 +205,12 @@ and memoized by identity on every backend, so declaring a currency costs a cast
    boundary).
 4. **Faster than the stdlib on the Magnus backend, where the carrier is cheap** —
    benchmark-ips (`ruby benchmark/cast_benchmark.rb`, linux-x64 on an Intel Core
-   i9-11900H, Ruby 4.0.7): timestamp **447 ns vs 2.97 µs `Time.iso8601`** (6.6x) — while
+   i9-11900H, Ruby 4.0.7): timestamp **404 ns vs 2.70 µs `Time.iso8601`** (6.7x) — while
    returning exact `Rational` durations on the duration door. The Fiddle fallback lands at
-   3.25 µs: a little behind `Time.iso8601`, sitting on Fiddle's per-call marshalling floor.
+   2.85 µs: a little behind `Time.iso8601`, sitting on Fiddle's per-call marshalling floor.
 
    Separator detection is nearly free here: `1.234.567,89` under `NumFormat::DETECT` runs
-   at 178 ns against 170 ns for the same text under a declared eurozone format. Both cost
+   at 154 ns against 145 ns for the same text under a declared eurozone format. Both cost
    nearly twice that in 0.1.0, for a reason that had nothing to do with parsing: every format other than `INVARIANT` paid three method dispatches and two
    `String` allocations per call to read its separators back out of the `Data`. `DETECT`
    is now identity-matched like `INVARIANT`, and any other format is resolved once per
@@ -213,14 +249,14 @@ both backends:
 
 | Door | Magnus | Fiddle |
 |---|---:|---:|
-| `bool` | 112 ns | 2.35 µs |
-| `i32` | 133 ns | 2.63 µs |
-| `f64` | 166 ns | 2.70 µs |
-| `uuid` | 223 ns | 3.47 µs |
-| `timestamp` | 447 ns | 3.25 µs |
-| `datetime` (`1/7/2026 3:04 PM`) | 904 ns | 3.98 µs |
-| `duration` (ISO) | 632 ns | 2.91 µs |
-| `i32`, a fault | 225 ns | 3.18 µs |
+| `bool` | 109 ns | 2.30 µs |
+| `i32` | 120 ns | 2.30 µs |
+| `f64` | 134 ns | 2.44 µs |
+| `uuid` | 209 ns | 3.28 µs |
+| `timestamp` | 404 ns | 2.85 µs |
+| `datetime` (`1/7/2026 3:04 PM`) | 877 ns | 3.71 µs |
+| `duration` (ISO) | 578 ns | 2.72 µs |
+| `i32`, a fault | 202 ns | 2.88 µs |
 
 A lean door on the Magnus backend is little more than the native call: the extension builds
 the `Success` or `Fault` it returns directly — allocated, its members stored, frozen —

data/lib/hypercast/interop.rb

@@ -0,0 +1,118 @@
+module HyperCast
+  # The native core's C ABI values, presented — for a gem that carries HyperCast's verdicts
+  # across a C ABI of its own (HyperTabular does): how each door's out-value unpacks and what
+  # builds the Ruby value from it, the verdict code and span of a fault, the packed version
+  # word, and where a gem's native library is. The Fiddle backend's doors decode with exactly
+  # these, so a value read out of another library's buffer is the value the door would have.
+  #
+  # Every directive below unpacks one value. A gem decoding a whole column appends "*" and
+  # steps +fields+ at a time.
+  module Interop
+    # The doors whose value is one String#unpack directive away: the directive for one value.
+    # A bool is the byte 0 or 1, unpacked as "C" and compared with zero.
+    SCALARS = {
+      bool: "C", i8: "c", i16: "s<", i32: "l<", i64: "q<", u8: "C", u16: "S<", u32: "L<",
+      u64: "Q<", f32: "e", f64: "E", time: "Q<"
+    }.freeze
+
+    # The doors whose value is a record: the directive that unpacks one, how many fields that
+    # yields, and what builds the door's Ruby value from them, starting at field +at+.
+    RECORDS = {
+      decimal: ["Q<L<CCx2", 4, ->(fields, at) { decimal(fields[at], fields[at + 1], fields[at + 2], fields[at + 3]) }],
+      uuid: ["H8H4H4H4H12", 5, ->(fields, at) { fields[at, 5].join("-") }],
+      timestamp: ["q<l<x4", 2, ->(fields, at) { instant(fields[at], fields[at + 1]) }],
+      date: ["S<CC", 3, ->(fields, at) { Date.new(fields[at], fields[at + 1], fields[at + 2]) }],
+      datetime: ["S<CCx4Q<", 4, ->(fields, at) { civil(fields[at], fields[at + 1], fields[at + 2], fields[at + 3]) }],
+      duration: ["q<l<x4", 2, ->(fields, at) { duration(fields[at], fields[at + 1]) }]
+    }.tap do |records|
+      records[:unix] = records[:excel_serial] = records[:timestamp]
+      records[:date_ordered] = records[:date]
+    end.freeze
+
+    # The bytes one value of each door takes.
+    VALUE_BYTES = {
+      bool: 1, i8: 1, u8: 1, i16: 2, u16: 2, i32: 4, u32: 4, f32: 4, date: 4, date_ordered: 4,
+      i64: 8, u64: 8, f64: 8, time: 8,
+      decimal: 16, uuid: 16, timestamp: 16, unix: 16, excel_serial: 16, datetime: 16, duration: 16
+    }.freeze
+
+    # 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
+
+    module_function
+
+    # One value of +door+, from the bytes the core wrote for it.
+    def decode(door, bytes)
+      if (directive = SCALARS[door])
+        value = bytes.unpack1(directive)
+        door == :bool ? value != 0 : value
+      else
+        directive, _fields, build = RECORDS.fetch(door)
+        build.call(bytes.unpack(directive), 0)
+      end
+    end
+
+    # A UTC Time from the core's protobuf-shaped {seconds, nanos} pair, exactly — the
+    # timestamp, unix and excel_serial doors' value. (Time.at then #utc is the same Time as
+    # Time.at(..., in: "UTC"), at half the cost: the zone's name is not read each time.)
+    def instant(seconds, nanos)
+      Time.at(seconds, nanos, :nanosecond).utc
+    end
+
+    # The zone-less DateTime a civil date-time names, with exact Rational seconds — the
+    # datetime door's value. Its +00:00 offset is a carrier artifact, not data.
+    def civil(year, month, day, nanos_of_day)
+      second_of_day, frac = nanos_of_day.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
+
+    # Exact Rational seconds from the core's same-signed {seconds, nanos} pair — the duration
+    # door's value.
+    def duration(seconds, nanos)
+      Rational(seconds * 1_000_000_000 + nanos, 1_000_000_000)
+    end
+
+    # A Decimal from the core's {lo, hi, scale, negative} — the decimal door's value.
+    def decimal(lo, hi, scale, negative)
+      Decimal.new(magnitude: (hi << 64) | lo, scale: scale, negative: negative != 0)
+    end
+
+    # The Fault a nonzero verdict code and its span name. A code that names no reason is a
+    # binding bug, not data: a KeyError.
+    def fault(code, offset, length)
+      Fault.new(reason: REASONS.fetch(code), offset: offset, length: length)
+    end
+
+    # The core's byte span over +bytes+, 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.
+    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
+
+    # A native library's packed version word — major << 16 | minor << 8 | patch, as a
+    # *_version export returns it — as "major.minor.patch".
+    def version(word)
+      "#{word >> 16}.#{(word >> 8) & 0xFF}.#{word & 0xFF}"
+    end
+
+    # The shared library to dlopen for +library+ ("hypercast" for libhypercast.so): the
+    # gem's native/{rid}/{file} under +native_dir+, or — the development loop — the cargo
+    # build under +repo_root+/rust/target/release, exactly what the other bindings' local
+    # staging does. Nil when neither exists.
+    def library_path(library, native_dir, repo_root)
+      rid, file = NativePlatform.rid_and_library_name(library: library)
+      path = File.join(native_dir, rid, file)
+      return path if File.exist?(path)
+
+      repo_build = File.join(repo_root, "rust", "target", "release", file)
+      File.exist?(repo_build) ? repo_build : nil
+    end
+  end
+end

data/lib/hypercast/native_platform.rb

@@ -1,27 +1,29 @@
 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.
+  # runtimes/{rid}/native/ / native/{rid}/ convention) and file name of a native library.
+  # Every SkunkWerkx core ships the same way, so +library+ names whose: "hypercast" for this
+  # gem's libhypercast, "hypertabular" for HyperTabular's.
   module NativePlatform
     class UnsupportedPlatformError < StandardError; end
 
     # +platform+ is a parameter only so the specs can walk the whole table from one host;
     # every real caller takes the default.
-    def self.rid_and_library_name(platform = RUBY_PLATFORM)
+    def self.rid_and_library_name(platform = RUBY_PLATFORM, library: "hypercast")
       arch = platform.match?(/arm64|aarch64/) ? "arm64" : "x64"
 
       case platform
       when /mingw|mswin|windows/
-        ["win-#{arch}", "hypercast.dll"]
+        ["win-#{arch}", "#{library}.dll"]
       when /darwin/
-        ["osx-#{arch}", "libhypercast.dylib"]
+        ["osx-#{arch}", "lib#{library}.dylib"]
       when /linux/
         # Two C libraries, two builds: a glibc-linked library cannot be relied on to dlopen
         # into a musl process (Alpine), so musl gets RIDs of its own. Ruby names the libc
         # in its platform string there ("x86_64-linux-musl") and leaves it off on glibc.
         os = platform.include?("musl") ? "linux-musl" : "linux"
-        ["#{os}-#{arch}", "libhypercast.so"]
+        ["#{os}-#{arch}", "lib#{library}.so"]
       else
-        raise UnsupportedPlatformError, "hypercast: unsupported platform RUBY_PLATFORM=#{platform}"
+        raise UnsupportedPlatformError, "#{library}: unsupported platform RUBY_PLATFORM=#{platform}"
       end
     end
   end

data/lib/hypercast/runtime.rb

@@ -17,7 +17,9 @@ module HyperCast
     # Each door's C signature, by shape — resolved to Fiddle types only in load_functions,
     # so nothing here touches Fiddle until the Fiddle backend actually runs: plain is
     # (text, len, out, fault), numeric adds the packed NumFormat pointer before out, and
-    # declared a caller-declared u32 (precision, epoch, field order) in the same place.
+    # declared a caller-declared u32 (precision, epoch, field order) in the same place. The
+    # typed doors take a double instead of the text and its length: typed is (value, out,
+    # fault), typed_declared adds the u32 after the value.
     DOORS = {
       cast_bool: :plain,
       cast_i8: :numeric, cast_i16: :numeric, cast_i32: :numeric, cast_i64: :numeric,
@@ -26,7 +28,9 @@ module HyperCast
       cast_uuid: :plain,
       cast_timestamp: :plain, cast_unix: :declared, cast_excel_serial: :declared,
       cast_date: :plain, cast_date_ordered: :declared, cast_datetime: :declared,
-      cast_time: :plain, cast_duration: :plain
+      cast_time: :plain, cast_duration: :plain,
+      cast_decimal_from_f64: :typed, cast_excel_serial_from_f64: :typed_declared,
+      cast_excel_time: :typed, cast_excel_duration: :typed
     }.freeze
 
     # The one export that is not a door: the zero-argument version probe, returning the
@@ -60,12 +64,7 @@ module HyperCast
       # 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
+        Interop.library_path("hypercast", NATIVE_DIR, File.expand_path("../../..", __dir__))
       end
 
       # Why Fiddle found nothing to load. A precompiled platform gem is the one install where
@@ -114,7 +113,9 @@ module HyperCast
         signatures = {
           plain: plain,
           numeric: plain.dup.insert(2, Fiddle::TYPE_VOIDP),
-          declared: plain.dup.insert(2, Fiddle::TYPE_UINT32_T)
+          declared: plain.dup.insert(2, Fiddle::TYPE_UINT32_T),
+          typed: [Fiddle::TYPE_DOUBLE, Fiddle::TYPE_VOIDP, Fiddle::TYPE_VOIDP],
+          typed_declared: [Fiddle::TYPE_DOUBLE, Fiddle::TYPE_UINT32_T, Fiddle::TYPE_VOIDP, Fiddle::TYPE_VOIDP]
         }
         functions = DOORS.to_h do |name, shape|
           [name, Fiddle::Function.new(handle[name.to_s], signatures.fetch(shape), Fiddle::TYPE_INT32_T)]

data/lib/hypercast.rb

@@ -1,5 +1,6 @@
 require "date"
 require_relative "hypercast/native_platform"
+require_relative "hypercast/interop"
 require_relative "hypercast/runtime"
 
 # Allocation-lean scalar casts — booleans, numerics, exact decimals, UUIDs, temporals —
@@ -29,7 +30,7 @@ require_relative "hypercast/runtime"
 module HyperCast
   # This gem's own version — kept in lockstep with hypercast.gemspec by the
   # prepare-release workflow, so the two can never drift apart again.
-  VERSION = "0.6.1"
+  VERSION = "0.7.0"
 
   # The success case of a verdict: a cast value.
   Success = Data.define(:value)
@@ -216,13 +217,12 @@ module HyperCast
     # (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 }
+      plain(:cast_bool, text, 1) { |out| Interop.decode(:bool, out) }
     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)
+    %i[i8 i16 i32 i64 u8 u16 u32 u64].each do |door|
+      unpack = Interop::SCALARS.fetch(door)
+      size = Interop::VALUE_BYTES.fetch(door)
       # 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}"
@@ -237,12 +237,12 @@ module HyperCast
     # 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") }
+      numeric(:cast_f32, text, format, 4) { |out| Interop.decode(:f32, out) }
     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") }
+      numeric(:cast_f64, text, format, 8) { |out| Interop.decode(:f64, out) }
     end
 
     # Casts decimal text to an exact Decimal — the real doors' grammar (declared separators
@@ -252,32 +252,27 @@ module HyperCast
     # 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
+      numeric(:cast_decimal, text, format, 16) { |out| Interop.decode(:decimal, out) }
     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
+      plain(:cast_uuid, text, 16) { |out| Interop.decode(:uuid, out) }
     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) }
+      plain(:cast_timestamp, text, 16) { |out| Interop.decode(:timestamp, out) }
     end
 
     # Casts an integer Unix-epoch value under a caller-declared unit Symbol
     # (:seconds/:milliseconds/:microseconds/:nanoseconds) to a UTC Time. An unknown unit
     # is a caller bug (KeyError), never a verdict.
     def unix(text, precision)
-      declared(:cast_unix, text, UNIX_PRECISIONS.fetch(precision), 16) { |out| instant(out) }
+      declared(:cast_unix, text, UNIX_PRECISIONS.fetch(precision), 16) { |out| Interop.decode(:unix, out) }
     end
 
     # Casts an Excel date serial under a caller-declared epoch Symbol (:y1900/:y1904) to a
@@ -291,7 +286,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)
-      declared(:cast_excel_serial, text, EXCEL_EPOCHS.fetch(epoch), 16) { |out| instant(out) }
+      declared(:cast_excel_serial, text, EXCEL_EPOCHS.fetch(epoch), 16) { |out| Interop.decode(:excel_serial, out) }
     end
 
     # Casts a calendar date to a Date. With no order declared: the strict ISO 8601
@@ -301,15 +296,9 @@ module HyperCast
     # 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
+        plain(:cast_date, text, 4) { |out| Interop.decode(:date, out) }
       else
-        declared(:cast_date_ordered, text, DATE_ORDERS.fetch(order), 4) do |out|
-          year, month, day = out.unpack("S<CC")
-          Date.new(year, month, day)
-        end
+        declared(:cast_date_ordered, text, DATE_ORDERS.fetch(order), 4) { |out| Interop.decode(:date_ordered, out) }
       end
     end
 
@@ -322,29 +311,51 @@ 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)
-      declared(:cast_datetime, text, DATE_ORDERS.fetch(order), 16) do |out|
-        year, month, day, nanos = out.unpack("S<CCx4Q<")
-        second_of_day, frac = nanos.divmod(1_000_000_000)
-        hour, rest = second_of_day.divmod(3600)
-        minute, second = rest.divmod(60)
-        DateTime.new(year, month, day, hour, minute, second + Rational(frac, 1_000_000_000))
-      end
+      declared(:cast_datetime, text, DATE_ORDERS.fetch(order), 16) { |out| Interop.decode(:datetime, out) }
     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<") }
+      plain(:cast_time, text, 8) { |out| Interop.decode(:time, out) }
     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
+      plain(:cast_duration, text, 16) { |out| Interop.decode(:duration, out) }
+    end
+
+    # Reads a number a caller already holds — an Integer, Float or Rational, the way Ruby's
+    # own Float conversion takes it; anything else, a String included, is a TypeError — as
+    # the exact Decimal it names: the shortest decimal that rounds back to the Float, the
+    # digits a spreadsheet writes for it. 0.1 is magnitude 1, scale 1, not the binary
+    # fraction nearest it; 0.1 + 0.2 is 0.30000000000000004. NaN is :malformed; an infinity,
+    # a magnitude past 2**96 - 1 or more than 28 places is :out_of_range. A typed door's
+    # Fault has no span: offset and length are 0.
+    def decimal_from_float(value)
+      typed(:cast_decimal_from_f64, float(value), 16) { |out| Interop.decode(:decimal, out) }
+    end
+
+    # Reads an Excel serial number under a declared epoch Symbol (:y1900/:y1904) as the
+    # zone-less DateTime it names — the twin of excel_serial for a number a workbook reader
+    # already holds, on the same carrier datetime uses. The 1900 system's phantom serial 60
+    # is :out_of_range; a negative, NaN or infinite serial is :malformed.
+    def excel_serial_from_float(value, epoch)
+      number = float(value)
+      typed(:cast_excel_serial_from_f64, number, 16, EXCEL_EPOCHS.fetch(epoch)) { |out| Interop.decode(:datetime, out) }
+    end
+
+    # Reads the fraction of an Excel serial number as an exact Integer of nanoseconds since
+    # midnight, as time does; 0.75 and 45292.75 are both 18:00.
+    def excel_time(value)
+      typed(:cast_excel_time, float(value), 8) { |out| Interop.decode(:time, out) }
+    end
+
+    # Reads a number of days as exact Rational seconds, as duration does: 1.5 is 129600.
+    def excel_duration(value)
+      typed(:cast_excel_duration, float(value), 16) { |out| Interop.decode(:duration, out) }
     end
 
     # The version of the native core actually loaded, as "major.minor.patch" — read from
@@ -353,15 +364,11 @@ module HyperCast
     # 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}"
+      Interop.version(packed_version)
     end
 
     private
 
-    # Encodings whose bytes already are the UTF-8 (or byte-identical) form the core reads.
-    BYTE_COMPATIBLE = [Encoding::UTF_8, Encoding::US_ASCII, Encoding::ASCII_8BIT].freeze
-
     # Presents the input as UTF-8 bytes: already-compatible text crosses as-is (Fiddle
     # passes a String's own bytes for void* — no copy of them); only foreign encodings pay
     # a transcode, and text that cannot be transcoded raises String#encode's own
@@ -376,7 +383,7 @@ module HyperCast
           raise TypeError, "no implicit conversion of #{text.class} into String"
         text = converted
       end
-      BYTE_COMPATIBLE.include?(text.encoding) ? text : text.encode(Encoding::UTF_8)
+      Interop::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.
@@ -408,22 +415,10 @@ module HyperCast
       elsif rc == -1
         raise "hypercast: libhypercast reported a contract violation — a binding bug, please report it"
       else
-        offset, length = characters(bytes, *fault[0, 8].unpack("L<L<"))
-        Fault.new(reason: REASONS.fetch(rc), offset: offset, length: length)
+        Interop.fault(rc, *Interop.characters(bytes, *fault[0, 8].unpack("L<L<")))
       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)
@@ -452,6 +447,34 @@ module HyperCast
       verdict(rc, fault, bytes) { yield(out[0, out_size]) }
     end
 
+    # A typed door's number, converted the way the extension's argument is (C's
+    # rb_num2dbl), with the same exception and message: a Numeric converts (a Complex with an
+    # imaginary part is Complex#to_f's RangeError), anything else is a TypeError — a String
+    # among them, which Kernel#Float would have parsed.
+    def float(value)
+      case value
+      when Float then value
+      when Numeric then Float(value)
+      when String then raise TypeError, "no implicit conversion to float from string"
+      when nil, true, false then raise TypeError, "no implicit conversion to float from #{value.inspect}"
+      else raise TypeError, "can't convert #{value.class} into Float"
+      end
+    end
+
+    # The shared body of the typed doors: a double instead of the text, then the declared
+    # u32 when the door takes one.
+    def typed(symbol, number, out_size, *declared)
+      out, fault = scratch
+      rc = Runtime.function(symbol).call(number, *declared, out, fault)
+      if rc.zero?
+        Success.new(value: yield(out[0, out_size]))
+      elsif rc == -1
+        raise "hypercast: libhypercast reported a contract violation — a binding bug, please report it"
+      else
+        Interop.fault(rc, 0, 0)
+      end
+    end
+
     # The loaded core's version word, major << 16 | minor << 8 | patch, straight from the
     # library's zero-argument hypercast_version export.
     def packed_version
@@ -482,12 +505,6 @@ module HyperCast
         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
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hypercast-wasm
 version: !ruby/object:Gem::Version
-  version: 0.6.1
+  version: 0.7.0
 platform: ruby
 authors:
 - Brian Buvinghausen
@@ -53,6 +53,7 @@ files:
 - ext/hypercast_native/4.0/hypercast_native.a.gz
 - ext/hypercast_native/extconf.rb
 - lib/hypercast.rb
+- lib/hypercast/interop.rb
 - lib/hypercast/native_platform.rb
 - lib/hypercast/runtime.rb
 homepage: https://github.com/SkunkWerkx/HyperCast