hypercast-wasm 0.8.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 120ea39dc2cdbbac9c8dc5a4c2e8b4caf96b353a0822b890a8a02aebfd18823b
-  data.tar.gz: '08ff59eee9eaf739e985da0a8a9a06091e37ea7cbc6a24d6970d031b72f9bf67'
+  metadata.gz: e8fba4b024f4c3f507d9c5d31187c8434d704e8ce0b613a5dd0d8de1100716e8
+  data.tar.gz: 9156a91e12b17035fa8e7cca34d79d0990e20388b6037386a1555e2a7f9526a9
 SHA512:
-  metadata.gz: e33bef99a50f5f76ea13278877fe9ea895473ca69f066f5db9b6fd079be2f454884aa75603f29ad2628bcc8dbb0ce1584b75659ab4e1608517ae806bda797973
-  data.tar.gz: c0e152cb5deb06d5f0e4ffdc14b8120f559926229b1f03fd42668b45a38e2f6c18668d2f2706628f20501168222e2ff6a5541c6d44e38486536f130f16dc5f96
+  metadata.gz: c18b51f977271062987a6c62a34154786b37fdee697661c921846c7034d07178c49b731cce9074aff07864d63a9027f77e11d4c88a9cf101cdb514aa9419aa05
+  data.tar.gz: 6f6ab24b0d6331b2d8020c93ebfb831ebc84df0bb796b6add5a6b733c938bf83d3c8525f307f5141273a81c86e448f46981bb0b27f0496936871c06618c02f8f

data/README.md

@@ -48,7 +48,7 @@ midnight, durations come back as exact `Rational` seconds across the core's whol
 | `unix(text, precision)` | UTC `Time` | `:seconds` / `:milliseconds` / `:microseconds` / `:nanoseconds` |
 | `excel_serial(text, epoch)` | UTC `Time` | `:y1900` / `:y1904` |
 | `date(text, order = nil)` | `Date` | strict ISO, or `:year_month_day` / `:month_day_year` / `:day_month_year` |
-| `datetime(text, order)` | zone-less `DateTime`, exact `Rational` seconds | a field order, as `date` |
+| `datetime(text, order, am: nil, pm: nil)` | zone-less `DateTime`, exact `Rational` seconds | a field order, as `date`; optionally a culture's own AM/PM words, read beside the English ones — see [`datetime`: a culture's AM/PM](#datetime-a-cultures-ampm) |
 | `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) | — |
@@ -67,9 +67,13 @@ Bad data is never an exception — it is a `Fault`. What raises is a caller bug,
 the same exception on every backend:
 
 - `ArgumentError` from `NumFormat.new`, `NumFormat#override` (and so the `separator:`,
-  `delimiter:` and `unit:` keywords) or `NumFormat.from_i18n` for a malformed format: separators that are not single
-  characters or not distinct, a currency symbol that is too long or carries an ASCII digit or
-  whitespace.
+  `delimiter:` and `unit:` keywords) or `NumFormat.from_i18n` for a malformed format: a
+  separator that is empty, longer than 8 UTF-8 bytes or not distinct from its partner
+  (the pair in force for currency amounts included), any symbol carrying an ASCII digit, a
+  sign, percent or currency symbol carrying ASCII whitespace, a currency symbol longer than
+  16 bytes, or a digit zero that is ASCII or starts no digit block. And from `datetime` for
+  a day-period designator that is empty, longer than 16 bytes, carries an ASCII digit or
+  starts or ends in ASCII whitespace.
 - `KeyError` — `Hash#fetch`'s own, `key not found: …` — for a precision, epoch or date order
   that names nothing: an unknown Symbol, or anything that is not a Symbol (`"seconds"`
   included). `date(text, nil)` is not one of these: an explicit `nil` order is the strict ISO
@@ -134,41 +138,98 @@ value.to_d   # => BigDecimal("-1234.5")
 `to_d` requires the `bigdecimal` gem lazily on first call — a bundled gem since Ruby 3.4,
 deliberately not a dependency of this one, so under Bundler add it to your own Gemfile.
 
-### `NumFormat`: declared separators, and a declared currency
+### `NumFormat`: declared separators, symbols and digits
 
 ```ruby
 HyperCast::NumFormat.new(decimal_sep: ".", group_sep: ",", flags: HyperCast::ALL_STYLES, currency: "$")
 ```
 
 The flags are `GROUPING`, `PARENTHESES`, `EXPONENT`, `RADIX_PREFIXES`, `PERCENT` and
-`CURRENCY` (`ALL_STYLES` is all six), plus the `SEPARATOR_DETECT` policy. The currency
-symbol is the one field a culture table would fill in: it is declared, never looked up, and
-honored only while `CURRENCY` is set — once, leading (`$5`, `-$5`, `$ -5`) or trailing
-(`5 €`, `1.234,50 kr.`), with optional ASCII whitespace between symbol and digits, and
-accounting parentheses wrapping symbol and digits together (`($5)`). Declared with the
-flag off, the symbol is a `:malformed` `Fault` at the symbol; the flag with nothing declared
-(`currency: ""`, the default — `INVARIANT` and `DETECT` declare none) matches nothing. A
-symbol longer than 16 UTF-8 bytes, or carrying an ASCII digit or ASCII whitespace, is an
-`ArgumentError` at construction, the same caller-bug treatment equal separators get.
+`CURRENCY` (`ALL_STYLES` is all six), plus `TRAILING_SIGN` — deliberately not in
+`ALL_STYLES`; see below — and the `SEPARATOR_DETECT` policy. A separator is 1 to 8 UTF-8
+bytes (`", "`, comma then space, is a separator).
+
+Everything past the separators and the flags is what a culture table would fill in, and
+every such field is declared, never looked up — `from_i18n` fills what Rails' locale data
+offers, and the rest is a keyword on `new` or `Data#with`. The rule for all of them: **a
+declared symbol is read beside its ASCII default, never instead of it.** ASCII `-`, `+`,
+`%` and `0`–`9` are always read, so a format that declares nothing (`""` everywhere, the
+default — `INVARIANT` and `DETECT` declare none) reads exactly as the invariant culture,
+and nothing that parsed before stops parsing when a symbol is declared.
+
+- `currency:` — honored only while `CURRENCY` is set: once, leading (`$5`, `-$5`, `$ -5`)
+  or trailing (`5 €`, `1.234,50 kr.`), with optional ASCII whitespace between symbol and
+  digits, and accounting parentheses wrapping symbol and digits together (`($5)`). Declared
+  with the flag off, the symbol is a `:malformed` `Fault` at the symbol; the flag with
+  nothing declared matches nothing.
+- `currency_decimal_sep:`, `currency_group_sep:` — the separators a currency amount is
+  written with, for a culture whose plain numbers and amounts differ (Swiss German writes
+  `1.234,5` and `CHF 1'234.50`). Read in place of the number separators when `CURRENCY` is
+  set, the symbol is declared, and the symbol is found in the text at either edge; each
+  `""` keeps its number counterpart. Under `SEPARATOR_DETECT`, detection governs the whole
+  token and these are ignored.
+- `minus_sign:`, `plus_sign:` — further spellings of the signs (`"−"`, U+2212, for Estonian
+  and Basque; `"＋"` fullwidth), read wherever ASCII `-`/`+` are: ahead of the digits, before
+  or after a leading currency symbol. Two signs are `:malformed` at the later one.
+- `TRAILING_SIGN` — permits the sign *after* the digits, the way a locale whose negative
+  pattern is `n-` writes it: `5-`, `5 -`, `5+`, `5 €-`, `5- €`, `2.5%-`, ASCII or
+  declared, once, never beside a leading sign nor inside parentheses. It is a flag, not a
+  symbol, and it is not in `ALL_STYLES`: `from_i18n` turns it on from the locale's own
+  `negative_format` rather than assuming it.
+- `percent:` — a further spelling of the percent symbol (`"٪"` in Arabic-script cultures,
+  `"％"` fullwidth), read as a trailing `%` is while `PERCENT` is set, on the real and
+  decimal doors; integer doors never read a percent.
+- `digit_zero:` — the culture's own digits, as their zero: `"٠"` (U+0660) declares the ten
+  Arabic-Indic digits, `"０"` the fullwidth ones. They are read beside ASCII `0`–`9`
+  everywhere digits are — integer part, fraction, exponent — and may be mixed with them;
+  radix-prefixed (`0x`, `0b`) digits stay ASCII.
 
 ```ruby
 dollars = HyperCast::NumFormat.new(decimal_sep: ".", group_sep: ",", flags: HyperCast::ALL_STYLES, currency: "$")
 HyperCast.i32("($1,234)", dollars)        # => Success(value: -1234)
 HyperCast.decimal("$1,234.50", dollars)   # => Success(value: Decimal(magnitude: 12345, scale: 1, negative: false))
 HyperCast.i32("$5", HyperCast::NumFormat::INVARIANT)   # => Fault(reason: :malformed, offset: 0, length: 1)
+
+estonian = HyperCast::NumFormat.new(decimal_sep: ",", group_sep: " ", flags: HyperCast::ALL_STYLES, minus_sign: "−")
+HyperCast.f64("−1 234,5", estonian)       # => Success(value: -1234.5)   (U+2212 minus; ASCII "-" still reads)
+
+francs = HyperCast::NumFormat.new(decimal_sep: ",", group_sep: ".", flags: HyperCast::ALL_STYLES | HyperCast::TRAILING_SIGN,
+                                  currency: "CHF", currency_decimal_sep: ".", currency_group_sep: "'")
+HyperCast.f64("CHF 1'234.50", francs)     # => Success(value: 1234.5)    (the currency separators, the symbol being present)
+HyperCast.f64("1.234,50", francs)         # => Success(value: 1234.5)    (the number separators)
+HyperCast.i32("5 CHF-", francs)           # => Success(value: -5)        (TRAILING_SIGN)
+
+arabic = HyperCast::NumFormat.new(decimal_sep: "٫", group_sep: "٬", flags: HyperCast::ALL_STYLES, percent: "٪", digit_zero: "٠")
+HyperCast.f64("١٬٢٣٤٫٥", arabic)          # => Success(value: 1234.5)
+HyperCast.decimal("٥٠٪", arabic)          # => Success(value: Decimal(magnitude: 5, scale: 1, negative: false))
 ```
 
-Across the ABI a `NumFormat` is a 32-byte struct — the two separators as code points, the
-flags, and the symbol's length and UTF-8 bytes held inline — packed once per format object
-and memoized by identity on every backend, so declaring a currency costs a cast nothing.
+A malformed field is an `ArgumentError` at construction, naming the field — the same
+caller-bug treatment equal separators have always had: an empty or over-long separator, an
+equal pair (the number pair, or the pair in force for currency amounts), a symbol carrying
+an ASCII digit, a sign, percent or currency symbol carrying ASCII whitespace, a currency
+symbol over 16 bytes, a digit zero that is ASCII or does not start a digit block. The
+limits are `NumFormat::SYMBOL_MAX_BYTES` (8) and `NumFormat::CURRENCY_MAX_BYTES` (16).
+
+Across the ABI a `NumFormat` is a 92-byte, size-tagged struct that the core reads in
+place — `NumFormat#packed` is exactly those bytes: the size word, the flags, the digit
+zero's code point, then each symbol's UTF-8 bytes and length held inline. It is packed
+once per format object and memoized by identity on every backend, so declaring a currency
+or a culture's digits costs a cast nothing.
+
+**What stays English: the boolean lexicon.** `bool` reads its twenty lexemes
+(`true`/`false`, `yes`/`no`, `on`/`off`, …) in English only. No platform carries culture
+data for boolean words, so there is no bridge that could fill them; a caller with a
+localized source maps its words before the door.
 
 ### Rails' words for a format: `separator:`, `delimiter:`, `unit:`
 
 Ruby's standard library carries no locale number data, so the vocabulary Ruby code already
 speaks is Rails' — the number helpers' and I18n's `number.format`: `separator` (the decimal
-mark), `delimiter` (grouping) and `unit` (the currency symbol). Every numeric door takes
-them as keywords that replace those fields of the format for the call, and
-`NumFormat.from_i18n` builds a format from the Hash I18n hands back:
+mark), `delimiter` (grouping), `unit` (the currency symbol) and `negative_format` (where
+the sign goes). Every numeric door takes the first three as keywords that replace those
+fields of the format for the call, and `NumFormat.from_i18n` builds a format from the Hash
+I18n hands back:
 
 ```ruby
 inv = HyperCast::NumFormat::INVARIANT
@@ -177,19 +238,63 @@ HyperCast.decimal("1.234,50 kr.", inv, separator: ",", delimiter: ".", unit: "kr
 
 german = HyperCast::NumFormat.from_i18n(I18n.t("number.format"))      # {separator: ",", delimiter: ".", ...}
 HyperCast.i32("1.234", german)                                        # => Success(value: 1234)
+
+# A locale whose currency amounts use other separators than its numbers: both Hashes.
+swiss = HyperCast::NumFormat.from_i18n(I18n.t("number.format"), currency_format: I18n.t("number.currency.format"))
+HyperCast.f64("CHF 1'234.50", swiss)                                  # => Success(value: 1234.5)
+HyperCast.f64("1.234,50", swiss)                                      # => Success(value: 1234.5)
 ```
 
 The keywords go through `NumFormat#override`, which is public: the result is validated like
-any `NumFormat`, and the flags are left alone, so a `unit:` on a format without `CURRENCY`
-is declared but not honored, as it would be in the constructor. `from_i18n` reads Symbol or
-String keys and ignores every other key, so `number.currency.format` works as well. Missing
-keys keep the invariant's fields. An empty `delimiter` (a locale that writes no grouping)
-turns `GROUPING` off. `flags:` defaults to `ALL_STYLES`.
-
-A call without the keywords is exactly the call it was, with no extra allocation on either
-backend. A call with them builds a format each time (a few microseconds), so in a loop,
+any `NumFormat`, and the flags and every other field are left alone, so a `unit:` on a
+format without `CURRENCY` is declared but not honored, as it would be in the constructor.
+`from_i18n` reads Symbol or String keys and ignores every other key, so
+`number.currency.format` passed alone works as well. Missing keys keep the invariant's
+fields, except that a missing mark never repeats the one the Hash declares:
+`{separator: ","}` groups with `"."`, as Python's and PHP's locale bridges do. An empty `delimiter` (a locale that writes no grouping) turns `GROUPING` off. A
+`negative_format` that writes the sign after the number (`"%n-"`, `"%n %u-"`) turns
+`TRAILING_SIGN` on; `"-%n"`, the Rails default, leaves it off. `currency_format:` takes
+`number.currency.format` beside `number.format`: its `separator` and `delimiter` become
+`currency_decimal_sep` and `currency_group_sep` (a key it lacks declares nothing, so the
+number separator stands in, unless that would repeat the currency mark it does declare), its `unit` the currency symbol, and its `negative_format`
+counts the same way. `flags:` defaults to `ALL_STYLES`.
+
+That is everything the Hash offers. Rails carries no minus or plus sign, no percent symbol
+and no digits, so `from_i18n` leaves those undeclared — the core reads ASCII `-`, `+`, `%`
+and `0`–`9` — and a locale that writes them differently declares them on the result:
+`from_i18n(I18n.t("number.format")).with(minus_sign: "−")` for Estonian.
+
+A call without the keywords allocates nothing extra on either backend. A call with them builds a format each time (a few microseconds), so in a loop,
 build it once with `override` or `from_i18n` and pass that instead.
 
+### `datetime`: a culture's AM/PM
+
+The civil date-time door reads a 12-hour clock's `AM`/`PM` ASCII case-insensitively, after
+the clock (`3:04 PM`) or ahead of it (`PM 3:04`). `am:` and `pm:` declare a culture's own
+words beside the English ones — German's `vorm.`/`nachm.`, Korean's `오전`/`오후`
+(written ahead of the clock), Spanish's `a. m.`/`p. m.` (a space inside is fine) — matched
+exactly, with or without a space between word and clock. English is still read whatever is
+declared; `nil`, the default, declares nothing, so a call without the keywords reads the
+English pair only. Like a `NumFormat`'s symbols the words are declared, never looked up:
+Ruby's stdlib has no day-period data, and `I18n.t("time.am")`/`("time.pm")` are where a
+Rails app finds them.
+
+```ruby
+HyperCast.datetime("1/7/2026 3:04 nachm.", :day_month_year, am: "vorm.", pm: "nachm.")
+# => Success(value: #<DateTime: 2026-07-01T15:04:00+00:00 ...>)
+HyperCast.datetime("2026-01-07 오후 3:04", :year_month_day, am: "오전", pm: "오후")
+# => Success(value: #<DateTime: 2026-01-07T15:04:00+00:00 ...>)
+HyperCast.datetime("1/7/2026 3:04 nachm.", :day_month_year)   # => Fault(reason: :malformed, offset: 13, length: 1)
+```
+
+A designator is 1 to 16 UTF-8 bytes with no ASCII digit and no ASCII whitespace at either
+end; anything else is an `ArgumentError`. Only `datetime` reads them — `date` has no time
+part. Across the ABI they are a 40-byte, size-tagged struct passed beside the order, null
+when nothing is declared. The designators are keywords, so they are read, validated and
+packed per call — the Fiddle backend packs them into its per-thread scratch — and a call
+that declares them costs about twice the plain call on the Magnus backend (the keyword
+scan is the cost: `am: nil, pm: nil` pays the same) and about half again on Fiddle.
+
 [^overrides]: Plus the optional keywords `separator:`, `delimiter:` and `unit:`, which
     override those fields of `format` for the call. See
     [Rails' words for a format](#rails-words-for-a-format-separator-delimiter-unit).
@@ -244,19 +349,24 @@ HyperCast::Interop.version(0x000700)                       # => "0.7.0"
    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 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
-   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.
+   at 154 ns against 145 ns for the same text under a declared eurozone format. Reading a
+   format costs one pointer compare: `DETECT` is 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.
+
+   A declared currency symbol costs text that does not carry one about 6 ns on the Magnus
+   backend: in a run for 0.9.0, separate from the [Benchmarks](#benchmarks) table, `1,234,567`
+   took 151 ns under `INVARIANT` and 157 ns under a format declaring `$`. A fault costs more than a success: the same run returned the `Fault` for
+   `12345x7` in 222 ns, against 101 ns for `Integer("12345x7", exception: false)` returning
+   `nil`. The door builds a reason and a span where `Integer()` hands back nothing.
    The three reason Symbols and the option Symbols (`:seconds`, `:month_day_year`, …) are
    cached the same way, so a fault or a declared option is a pointer compare too, never a
    `Symbol#name` materialization.
 
 **The honest trade-off:** the civil doors do not beat `strptime`. The date-time door is
-level with `DateTime.strptime` (904 ns against 901 ns) and the date door a little behind
-`Date.strptime` (620 ns against 513 ns). The parse isn't the cost; the carrier is. Building
+level with `DateTime.strptime` (877 ns against 851 ns, the session of the
+[table below](#benchmarks)) and the date door a little behind `Date.strptime` (620 ns against
+513 ns, measured for 0.4.0 and not re-timed since). The parse isn't the cost; the carrier is. Building
 a stdlib `DateTime` with an exact `Rational` second costs more than the whole native call,
 where the timestamp door's `Time` is built by a single cheap `rb_time_nano_new`. If you want
 Ruby's fastest civil parse and don't need the verdict or the declared order, `strptime` is
@@ -266,9 +376,8 @@ which is an artifact of the type, not a zone the parse assigned.
 On the Fiddle fallback the doors are parity-at-best — Fiddle's
 per-call floor is the mechanism's price, kept because it's the universal zero-compile
 path. Its doors build nothing per call that does not change between calls: each format
-owns one native pointer, memoized by identity and passed straight through. (Benchmark forensics worth knowing: the doors read 4.3 µs until
-per-call `Fiddle::Pointer.malloc` finalizers were hoisted to thread-local scratch —
-receipts include their own archaeology.)
+owns one native pointer, memoized by identity and passed straight through, and its scratch
+is thread-local rather than a `Fiddle::Pointer.malloc` per call.
 
 ## Benchmarks
 
@@ -322,33 +431,41 @@ buffers; the core itself keeps no state between calls. `spec/cast_spec.rb`'s
 concurrent-callers example runs under both.
 
 **Ractors.** Main Ractor only, on every backend: called from another Ractor the doors raise
-`Ractor::UnsafeError`.
+(`Ractor::UnsafeError` from the Magnus extension, `Ractor::IsolationError` on Fiddle).
 
 ## Verifying provenance
 
-Every gem RubyGems.org serves — the universal fallback, each of the seven precompiled
-platform gems and `hypercast-wasm` — 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:
+Every gem RubyGems.org serves — the universal fallback, each of the seven precompiled platform
+gems and `hypercast-wasm` — verifies from the release tag alone: the release attestation,
+signed by this repository's `release.yml` at the tag, names every one of them, with the
+release inventory as its predicate.
+
+```sh
+gem fetch hypercast -v <version> --platform <platform>   # or omit --platform for the universal gem
+gh attestation verify hypercast-<version>-<platform>.gem --repo SkunkWerkx/HyperCast \
+  --source-ref refs/tags/v<version> --predicate-type https://github.com/SkunkWerkx/.github/predicates/release/v1
+```
+
+Each gem's build provenance is this repository's too: the `ruby-pack` job attests
+`ruby/pkg/*.gem` as soon as they are built and `rubygems-publish` pushes those preserved
+bytes, so plain `--repo` verifies it:
 
 ```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
+gh attestation verify hypercast-<version>-<platform>.gem --repo SkunkWerkx/HyperCast
 ```
 
-That's the release's second layer of checking, not the only one: before any gem gets built,
-the same job verifies every native binary it packs — the Fiddle libraries, the Magnus
-extensions (one per Ruby ABI per platform), the `wasm32-wasip1` archives — against *their own*
-attestations — those are signed from `SkunkWerkx/.github` by `hyper-build-native.yml` and
-`hyper-build-wasm.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.
+That is the release's second layer of checking, not the only one: before any gem is built, the
+same job verifies every native binary it packs — the Fiddle libraries, the Magnus extensions
+(one per Ruby ABI per platform), the `wasm32-wasip1` archives — against *their own* build
+provenance, signed from `SkunkWerkx/.github` by `hyper-build-native.yml` and
+`hyper-build-wasm.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 all of this happens while a bad artifact is still reversible,
+and the push itself is a separate dispatch from the preserved bytes. The release run then
+re-fetches every gem from rubygems.org and fails unless each matches the attested bytes
+exactly, turning "rubygems.org stores an upload verbatim" into a per-release check rather than
+an assumption. The root README's [Provenance](../README.md#provenance) section has the whole
+picture.
 
 ## Install
 
@@ -418,8 +535,7 @@ Ruby newer than the release, or a platform with no platform gem. `bundle install
 Bundler 2.6, not on 3.3's 2.5); otherwise install the compiler and headers. Pinning `fiddle`
 to your Ruby's version in the `Gemfile.lock` does not stop the build.
 
-Both Windows architectures get a Magnus gem, and the reasoning that once kept them on Fiddle
-was backwards: MinGW is the *only* Windows flavour `rb-sys` targets (`x64-mingw-ucrt` and
+Both Windows architectures get a Magnus gem: 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
@@ -465,6 +581,12 @@ Load `ruby.wasm` with [`@ruby/wasm-wasi`](https://www.npmjs.com/package/@ruby/wa
 - **No Rust toolchain.** The gem's `extconf.rb` only hands rbwasm the prebuilt archive, and
   rbwasm downloads its own wasi-sdk. The first `rbwasm build` compiles Ruby itself and takes
   15–20 minutes; later builds reuse it.
+- **macOS with Homebrew: limit pkg-config to `openssl@3`.** Run the build as
+  `PKG_CONFIG_LIBDIR="$(brew --prefix openssl@3)/lib/pkgconfig" bundle exec rbwasm build …`.
+  Without it Homebrew's pkg-config files reach into the build twice: its `openssl` is OpenSSL
+  4, which the native Ruby rbwasm builds first does not compile against, and its `libyaml`
+  is a macOS library that psych then links into the wasm interpreter, which fails for Ruby
+  4.0.
 - **`Decimal#to_d` needs `gem "bigdecimal"` in that Gemfile.** bigdecimal is a bundled gem
   with a C extension, and ruby.wasm builds a bundled gem's extension only when the Gemfile
   names it; without it, `to_d` raises `LoadError`. `to_s` and `to_r` need nothing.

data/lib/hypercast/runtime.rb

@@ -16,10 +16,11 @@ 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. 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.
+    # (text, len, out, fault), numeric adds the packed NumFormat pointer before out,
+    # declared a caller-declared u32 (precision, epoch, field order) in the same place, and
+    # civil the field order then the packed DayPeriods pointer (null for none). 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_char: :plain,
       cast_i8: :numeric, cast_i16: :numeric, cast_i32: :numeric, cast_i64: :numeric,
@@ -27,7 +28,7 @@ module HyperCast
       cast_f32: :numeric, cast_f64: :numeric, cast_decimal: :numeric,
       cast_uuid: :plain,
       cast_timestamp: :plain, cast_unix: :declared, cast_excel_serial: :declared,
-      cast_date: :plain, cast_date_ordered: :declared, cast_datetime: :declared,
+      cast_date: :plain, cast_date_ordered: :declared, cast_datetime: :civil,
       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
@@ -114,6 +115,7 @@ module HyperCast
           plain: plain,
           numeric: plain.dup.insert(2, Fiddle::TYPE_VOIDP),
           declared: plain.dup.insert(2, Fiddle::TYPE_UINT32_T),
+          civil: plain.dup.insert(2, Fiddle::TYPE_UINT32_T, Fiddle::TYPE_VOIDP),
           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]
         }

data/lib/hypercast.rb

@@ -30,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.8.0"
+  VERSION = "1.0.0"
 
   # The success case of a verdict: a cast value.
   Success = Data.define(:value)
@@ -48,50 +48,72 @@ module HyperCast
 
   # Caller-declared numeric notation for the integer, real and decimal doors — declared out
   # loud (INVARIANT, or a literal), never defaulted, the same stance every binding takes.
-  # The currency symbol is the one field a culture table would fill in: it is declared
-  # here, never looked up, and honored only while the CURRENCY flag is set — declared with
-  # the flag off, the symbol is a :malformed Fault at the symbol, and the flag with no
-  # symbol ("" — the default) matches nothing. Equal separators, or a symbol longer than
-  # 16 UTF-8 bytes or carrying an ASCII digit or ASCII whitespace, are a caller bug
-  # (ArgumentError), never a verdict.
-  NumFormat = Data.define(:decimal_sep, :group_sep, :flags, :currency) do
-    # Validates the declared separators up front — single characters, and distinct from
-    # each other — and the currency symbol (a String of at most 16 UTF-8 bytes with no
-    # ASCII digit or ASCII whitespace, since those would collide with the digit scan and
-    # the trimming around the symbol), so a malformed format fails loudly as the caller bug
-    # it is. All three are stored transcoded to UTF-8, the encoding the core reads — a
-    # separator handed over in another encoding (a no-break space read from a Latin-1
-    # file, say) is the same code point on every backend rather than whatever its bytes
-    # happened to spell in the encoding it arrived in.
-    def initialize(decimal_sep:, group_sep:, flags:, currency: "")
-      raise ArgumentError, "separators must be single characters" unless
-        decimal_sep.is_a?(String) && decimal_sep.length == 1 &&
-        group_sep.is_a?(String) && group_sep.length == 1
-
-      decimal_sep = decimal_sep.encode(Encoding::UTF_8)
-      group_sep = group_sep.encode(Encoding::UTF_8)
+  # Past the separators and the flags, every field is one a culture table would fill in,
+  # and each is declared here, never looked up: the currency symbol; the separators a
+  # currency amount is written with (currency_decimal_sep, currency_group_sep — read in
+  # place of the number separators when the symbol is found in the text, each "" keeping
+  # its number counterpart); further spellings of the minus and plus signs and of the
+  # percent symbol; and the culture's own digits (digit_zero — the ten code points from
+  # that zero up, "٠" for the Arabic-Indic digits). A declared symbol is read *beside* its
+  # ASCII default, never instead of it — ASCII "-", "+", "%" and 0-9 are always read — so a
+  # format that declares nothing ("" everywhere; the default) reads exactly as the
+  # invariant culture, and nothing that parsed before stops parsing. The currency symbol is
+  # honored only while the CURRENCY flag is set — declared with the flag off, the symbol is
+  # a :malformed Fault at the symbol, and the flag with no symbol matches nothing — and the
+  # percent symbol while PERCENT is. A separator may be wider than one character (", " —
+  # comma, space — is a separator), up to 8 UTF-8 bytes. A malformed format is a caller bug
+  # (ArgumentError), never a verdict: an empty or over-long separator, equal separators (or
+  # an equal pair in force for currency amounts), a symbol carrying an ASCII digit, a sign
+  # or percent symbol carrying ASCII whitespace, a currency symbol longer than 16 bytes or
+  # carrying a digit or whitespace, or a digit zero that is ASCII or starts no digit block.
+  NumFormat = Data.define(:decimal_sep, :group_sep, :flags, :currency,
+                          :currency_decimal_sep, :currency_group_sep,
+                          :minus_sign, :plus_sign, :percent, :digit_zero) do
+    # Validates every declared field up front — the separators (1 to 8 UTF-8 bytes each,
+    # distinct from each other, and so the pair in force for currency amounts), the signs,
+    # the percent and currency symbols (no ASCII digit, since a digit is a digit before it
+    # is anything else, and no ASCII whitespace, which would collide with the trimming
+    # around them) and the digit zero (one non-ASCII character whose ten successors share
+    # its UTF-8 prefix, which every Unicode digit block's zero does) — so a malformed
+    # format fails loudly as the caller bug it is. Every field is stored transcoded to
+    # UTF-8, the encoding the core reads — a separator handed over in another encoding (a
+    # no-break space read from a Latin-1 file, say) is the same code point on every backend
+    # rather than whatever its bytes happened to spell in the encoding it arrived in.
+    def initialize(decimal_sep:, group_sep:, flags:, currency: "", currency_decimal_sep: "",
+                   currency_group_sep: "", minus_sign: "", plus_sign: "", percent: "", digit_zero: "")
+      limit = self.class::SYMBOL_MAX_BYTES
+      decimal_sep = declared("decimal separator", decimal_sep, limit, required: true)
+      group_sep = declared("group separator", group_sep, limit, required: true)
       raise ArgumentError, "decimal and group separators must differ; both are #{decimal_sep.inspect}" if
         decimal_sep == group_sep
-      raise ArgumentError, "currency symbol must be a String; got #{currency.inspect}" unless currency.is_a?(String)
 
-      symbol = currency.encode(Encoding::UTF_8)
-      limit = self.class::CURRENCY_MAX_BYTES
-      raise ArgumentError, "currency symbol #{currency.inspect} exceeds #{limit} UTF-8 bytes" if
-        symbol.bytesize > limit
-      raise ArgumentError, "currency symbol #{currency.inspect} must not contain an ASCII digit or whitespace" if
-        symbol.match?(/[0-9\t\n\f\r ]/)
+      currency_decimal_sep = declared("currency decimal separator", currency_decimal_sep, limit)
+      currency_group_sep = declared("currency group separator", currency_group_sep, limit)
+      money_decimal = currency_decimal_sep.empty? ? decimal_sep : currency_decimal_sep
+      money_group = currency_group_sep.empty? ? group_sep : currency_group_sep
+      raise ArgumentError, "currency decimal and group separators must differ; both are #{money_decimal.inspect}" if
+        money_decimal == money_group
 
-      super(decimal_sep: decimal_sep, group_sep: group_sep, flags: flags, currency: symbol)
+      super(decimal_sep: decimal_sep, group_sep: group_sep, flags: flags,
+            currency: declared("currency symbol", currency, self.class::CURRENCY_MAX_BYTES, flush: true),
+            currency_decimal_sep: currency_decimal_sep, currency_group_sep: currency_group_sep,
+            minus_sign: declared("minus sign", minus_sign, limit, flush: true),
+            plus_sign: declared("plus sign", plus_sign, limit, flush: true),
+            percent: declared("percent symbol", percent, limit, flush: true),
+            digit_zero: digit_zero_of(digit_zero))
     end
 
     # This format with the fields Ruby's number vocabulary names replaced — the words Rails'
     # number helpers and I18n's number.format use: separator: (the decimal mark),
     # delimiter: (grouping) and unit: (the currency symbol). A nil keyword leaves its
     # field alone, so with none given this is the format itself, not a copy. The result is
-    # validated like any NumFormat (single, distinct separators; a declarable symbol), and
-    # the flags are untouched: a unit: declared on a format without CURRENCY is a :malformed
-    # Fault at the symbol, exactly as declaring it in the constructor would be. Every
-    # numeric door takes the same three keywords and applies them through this method.
+    # validated like any NumFormat (declarable, distinct separators; a declarable symbol),
+    # and the flags and every other field are untouched: a unit: declared on a format
+    # without CURRENCY is a :malformed Fault at the symbol, exactly as declaring it in the
+    # constructor would be. Every numeric door takes the same three keywords and applies
+    # them through this method; the fields Rails has no word for (the signs, the percent
+    # symbol, the digits, the currency separators) are declared in the constructor or
+    # through Data#with.
     def override(separator: nil, delimiter: nil, unit: nil)
       return self unless separator || delimiter || unit
 
@@ -99,40 +121,138 @@ module HyperCast
     end
 
     # A format from a Hash shaped like I18n's number.format (or number.currency.format):
-    # :separator, :delimiter and :unit, Symbol or String keys, every other key (precision,
-    # format, significant, ...) ignored — so `NumFormat.from_i18n(I18n.t("number.format"))`
-    # drops a Rails locale straight in, with no I18n dependency here. A missing or nil key
-    # keeps the invariant's "." / "," / no symbol. An empty delimiter — the locale writes no
-    # grouping — turns GROUPING off rather than declaring a separator, since a NumFormat
-    # always carries one; the placeholder it gets is whichever of "," and "." the decimal
-    # mark is not. flags defaults to every lenience, the same as INVARIANT.
+    # :separator, :delimiter, :unit and :negative_format, Symbol or String keys, every other
+    # key (precision, format, significant, ...) ignored — so
+    # `NumFormat.from_i18n(I18n.t("number.format"))` drops a Rails locale straight in, with
+    # no I18n dependency here. A missing or nil key keeps the invariant's "." / "," / no
+    # symbol, except where that would repeat the mark the Hash does declare: a separator of
+    # "," with no delimiter groups with ".", and a delimiter of "." with no separator takes
+    # "," for the decimal mark. An empty delimiter — the locale writes no grouping — turns GROUPING off rather
+    # than declaring a separator, since a NumFormat always carries one; the placeholder it
+    # gets is whichever of "," and "." the decimal mark is not. A negative_format that writes
+    # the sign after the number ("%n-", "%n %u-") turns TRAILING_SIGN on; "-%n", the Rails
+    # default, leaves it off. flags defaults to every lenience, the same as INVARIANT.
     #
-    # Only the separators and the unit carry over; the native format has no field for the
-    # rest. The core reads ASCII "+" and "-" only, so a locale that writes negatives with
-    # another sign (U+2212 for Estonian and Basque, for instance) faults on them; currency
-    # amounts in a locale whose number.currency.format separators differ from number.format's
-    # read with whichever Hash is passed, so pass the currency one for currency columns; and
-    # percent is an ASCII "%". Every lenience is on, radix prefixes and percent included;
+    # currency_format: takes the locale's number.currency.format Hash beside number.format,
+    # for a column that mixes plain numbers and currency amounts in a locale whose two
+    # differ (the Swiss German franc, say — "1'234.50" beside "1.234,50"): its separator and
+    # delimiter become the currency separators, read in place of the number ones when the
+    # unit is found in the text, and its unit the currency symbol. A missing key there
+    # declares nothing, keeping the number separator it stands in for, unless that would
+    # repeat the currency mark it does declare, in which case the missing one is whichever
+    # of "," and "." that mark is not; an explicitly empty
+    # delimiter gets the same placeholder rule as above; its negative_format turns
+    # TRAILING_SIGN on the same way. Passed alone, number.currency.format reads as the one
+    # number format, as before.
+    #
+    # The rest of the format is what the Hash cannot offer: Rails carries no minus or plus
+    # sign, no percent symbol and no digits, so those stay undeclared here — the core reads
+    # ASCII "-", "+", "%" and 0-9 — and a locale that writes negatives with another sign
+    # (U+2212 for Estonian and Basque, for instance) declares it on the result with
+    # Data#with (minus_sign: "−"). Every lenience is on, radix prefixes and percent included;
     # narrow flags: for anything stricter.
-    def self.from_i18n(number_format, flags: ALL_STYLES)
+    def self.from_i18n(number_format, currency_format: nil, flags: ALL_STYLES)
+      entries = i18n_entries(number_format)
+      separator = entries[:separator] || (entries[:delimiter] == "." ? "," : ".")
+      delimiter = entries[:delimiter]
+      if delimiter.nil? || delimiter == ""
+        flags &= ~GROUPING if delimiter == ""
+        delimiter = separator == "," ? "." : ","
+      end
+      flags |= TRAILING_SIGN if trailing_sign?(entries[:negative_format])
+      currency = entries[:unit] || ""
+      currency_separator = currency_delimiter = ""
+      if currency_format
+        money = i18n_entries(currency_format)
+        currency = money[:unit] || currency
+        currency_separator = money[:separator] || ""
+        currency_delimiter = money[:delimiter] || ""
+        currency_delimiter = (money[:separator] || separator) == "," ? "." : "," if money[:delimiter] == ""
+        if currency_separator.empty? && currency_delimiter == separator
+          currency_separator = currency_delimiter == "," ? "." : ","
+        elsif currency_delimiter.empty? && currency_separator == delimiter
+          currency_delimiter = currency_separator == "," ? "." : ","
+        end
+        flags |= TRAILING_SIGN if trailing_sign?(money[:negative_format])
+      end
+      new(decimal_sep: separator, group_sep: delimiter, flags: flags, currency: currency,
+          currency_decimal_sep: currency_separator, currency_group_sep: currency_delimiter)
+    end
+
+    # The I18n Hash's entries under Symbol keys, whatever keys it arrived with.
+    def self.i18n_entries(number_format)
       raise ArgumentError, "expected a Hash-like number format; got #{number_format.inspect}" unless
         number_format.respond_to?(:to_h)
 
-      entries = number_format.to_h.transform_keys { |key| key.respond_to?(:to_sym) ? key.to_sym : key }
-      separator = entries[:separator] || "."
-      delimiter = entries[:delimiter] || ","
-      if delimiter == ""
-        flags &= ~GROUPING
-        delimiter = separator == "," ? "." : ","
-      end
-      new(decimal_sep: separator, group_sep: delimiter, flags: flags, currency: entries[:unit] || "")
+      number_format.to_h.transform_keys { |key| key.respond_to?(:to_sym) ? key.to_sym : key }
     end
+    private_class_method :i18n_entries
 
-    # The 32-byte little-endian form the native ABI's NumFormat struct expects: the two
-    # separators as code points, the flags, the symbol's byte length, then the symbol's
-    # UTF-8 bytes zero-padded to 16.
+    # Whether an I18n negative_format ("-%n", "%n-", "-%u%n", "%n %u-") writes the sign
+    # after the number: a "-" to the right of the "%n" placeholder.
+    def self.trailing_sign?(negative_format)
+      return false unless negative_format.is_a?(String)
+
+      number = negative_format.index("%n")
+      sign = negative_format.rindex("-")
+      !number.nil? && !sign.nil? && sign > number
+    end
+    private_class_method :trailing_sign?
+
+    # The 92-byte little-endian form of the native ABI's size-tagged NumFormat struct, the
+    # layout the core reads in place: the size word (92), the flags, the digit zero's code
+    # point (0 for none), then each symbol as its UTF-8 bytes zero-padded to its field
+    # followed by its byte length — eight bytes and a length for each of the two number
+    # separators, the two currency separators, the two signs and the percent symbol, in
+    # that order; sixteen and a length for the currency symbol. A length of 0 declares
+    # nothing.
     def packed
-      [decimal_sep.ord, group_sep.ord, flags, currency.bytesize].pack("L<L<L<L<") + [currency].pack("a16")
+      head = [self.class::PACKED_BYTES, flags, digit_zero.empty? ? 0 : digit_zero.ord].pack("L<L<L<")
+      symbols = [decimal_sep, group_sep, currency_decimal_sep, currency_group_sep, minus_sign, plus_sign, percent]
+      head + symbols.map { |symbol| [symbol, symbol.bytesize].pack("a8C") }.join +
+        [currency, currency.bytesize].pack("a16C")
+    end
+
+    private
+
+    # The declared text of one field as the UTF-8 the core reads: a String of 1 to `limit`
+    # UTF-8 bytes with no ASCII digit — nor, for a symbol that sits flush against the
+    # digits (the signs, the percent and currency symbols), any ASCII whitespace — or ""
+    # where the field may be left undeclared. Anything else is the caller bug it names.
+    def declared(field, text, limit, flush: false, required: false)
+      raise ArgumentError, "#{field} must be a String; got #{text.inspect}" unless text.is_a?(String)
+
+      symbol = text.encode(Encoding::UTF_8)
+      if symbol.empty?
+        raise ArgumentError, "#{field} must not be empty" if required
+
+        return symbol
+      end
+      raise ArgumentError, "#{field} #{text.inspect} exceeds #{limit} UTF-8 bytes" if symbol.bytesize > limit
+
+      if flush
+        raise ArgumentError, "#{field} #{text.inspect} must not contain an ASCII digit or whitespace" if
+          symbol.match?(/[0-9\t\n\f\r ]/)
+      elsif symbol.match?(/[0-9]/)
+        raise ArgumentError, "#{field} #{text.inspect} must not contain an ASCII digit"
+      end
+      symbol
+    end
+
+    # The declared digit zero as UTF-8: "" for none, else exactly one character that is not
+    # ASCII and whose code point modulo 64 is at most 54 — true of the zero of every decimal
+    # digit block Unicode defines, and the shape the core recognises a digit by its last
+    # byte from.
+    def digit_zero_of(text)
+      raise ArgumentError, "digit zero must be a String; got #{text.inspect}" unless text.is_a?(String)
+
+      zero = text.encode(Encoding::UTF_8)
+      return zero if zero.empty?
+
+      raise ArgumentError, "digit zero #{text.inspect} must be one non-ASCII character that starts a digit block" unless
+        zero.length == 1 && zero.ord >= 0x80 && zero.ord % 64 <= 54
+
+      zero
     end
   end
 
@@ -141,6 +261,13 @@ module HyperCast
   # is scoped lexically, and landed on HyperCast instead of on NumFormat.
   NumFormat::CURRENCY_MAX_BYTES = 16
 
+  # The widest separator, sign or percent symbol the native ABI carries inline, in UTF-8
+  # bytes: enough for every separator a real culture declares (one or two characters).
+  NumFormat::SYMBOL_MAX_BYTES = 8
+
+  # The size of NumFormat#packed — the native ABI's size-tagged NumFormat layout — in bytes.
+  NumFormat::PACKED_BYTES = 92
+
   # 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.
@@ -149,7 +276,8 @@ module HyperCast
   EXPONENT = 1 << 2
   # Permit 0x/&H/0b two's-complement radix prefixes (0xFF is -1 for an i8).
   RADIX_PREFIXES = 1 << 3
-  # Permit a trailing %, dividing by 100. Real and decimal doors only.
+  # Permit a trailing % (or the format's declared percent symbol), dividing by 100. Real
+  # and decimal doors only.
   PERCENT = 1 << 4
   # Resolve the ./, roles per input from structure instead of the declared separators
   # (which are ignored while this flag is set). Detection, not sniffing: a repeated
@@ -165,8 +293,15 @@ module HyperCast
   # along with the digits ("($5)"). With no symbol declared the flag matches nothing.
   # Integer, real and decimal doors.
   CURRENCY = 1 << 6
-  # Every lenience on (SEPARATOR_DETECT is a separator policy, not a lenience, and is
-  # deliberately not included).
+  # Permit the sign after the digits ("5-", "5 -", "5 €-", "5- €"), the way a locale whose
+  # negative_format is "%n-" writes it: ASCII - and + or the format's declared signs, once,
+  # with optional ASCII whitespace before it, and never beside a leading sign or inside
+  # accounting parentheses. Not part of ALL_STYLES — NumFormat.from_i18n sets it from the
+  # locale's own negative_format rather than assuming it.
+  TRAILING_SIGN = 1 << 7
+  # Every lenience on — every one there was before TRAILING_SIGN, which is declared from a
+  # locale's pattern rather than assumed (SEPARATOR_DETECT is a separator policy, not a
+  # lenience, and is deliberately not included either).
   ALL_STYLES = GROUPING | PARENTHESES | EXPONENT | RADIX_PREFIXES | PERCENT | CURRENCY
 
   # The invariant profile — '.' decimal, ',' grouping, every lenience on, no currency
@@ -373,8 +508,21 @@ module HyperCast
     # artifact, not data (the same caveat PHP's UTC-labeled DateTimeImmutable carries);
     # fusing a real zone is the caller's job, and timestamp stays the strict RFC 3339
     # instant door. An unknown order is a caller bug (KeyError).
-    def datetime(text, order)
-      declared(:cast_datetime, text, DATE_ORDERS.fetch(order), 16) { |out| Interop.decode(:datetime, out) }
+    #
+    # A 12-hour clock's AM/PM is read, before or after the clock ("3:04 PM", "PM 3:04"),
+    # ASCII case-insensitively; am: and pm: declare a culture's own designators beside
+    # them — "vorm."/"nachm.", "오전"/"오후", "a. m."/"p. m." — matched exactly, after the
+    # clock ("3:04 nachm.") or ahead of it ("오후 3:04"), with or without a space between.
+    # Declared, never looked up, like a NumFormat's symbols; nil (the default) declares
+    # nothing, so a call without them is exactly the call it was. A designator is 1 to 16
+    # UTF-8 bytes with no ASCII digit and no ASCII whitespace at either end (a space inside
+    # is fine); anything else is a caller bug (ArgumentError). The designators are read,
+    # validated and packed per call: a call that declares them costs about twice the plain
+    # call on the Magnus backend (the keyword scan itself — nil keywords pay the same) and
+    # about half again here on Fiddle.
+    def datetime(text, order, am: nil, pm: nil)
+      periods = packed_day_periods(am, pm) if am || pm
+      civil(:cast_datetime, text, DATE_ORDERS.fetch(order), periods, 16) { |out| Interop.decode(:datetime, out) }
     end
 
     # Casts an ISO 24-hour time-of-day to an exact Integer of nanoseconds since midnight
@@ -454,18 +602,19 @@ module HyperCast
       bytes.empty? ? nil : bytes
     end
 
-    # One 24-byte scratch allocation per thread, reused by every call: out-value at 0
+    # One 64-byte scratch allocation per thread, reused by every call: out-value at 0
     # (16 bytes covers every door, and malloc's alignment covers the decimal's 8), fault
-    # span at 16. Two Fiddle::Pointer.malloc(..., RUBY_FREE) calls per cast — each
-    # registering a GC finalizer — measured as the dominant per-call cost by an order of
-    # magnitude. The NumFormat no longer lives here: each format owns its own packed
-    # pointer (see packed_cache), so a numeric call copies nothing into scratch before
-    # crossing. Allocated through Runtime.buffer, which loads the library first, so a
-    # missing one is reported as such before Fiddle is touched.
+    # span at 16, and the datetime door's packed day periods at 24 (40 bytes, 4-aligned,
+    # written only by a call that declares them). 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 does not live here: each format owns
+    # its own packed pointer (see packed_cache), so a numeric call copies nothing into
+    # scratch before crossing. Allocated through Runtime.buffer, which loads the library
+    # first, so a missing one is reported as such before Fiddle is touched.
     def scratch
       Thread.current[:hypercast_scratch] ||= begin
-        base = Runtime.buffer(24)
-        [base, base + 16]
+        base = Runtime.buffer(64)
+        [base, base + 16, base + 24]
       end
     end
 
@@ -491,7 +640,7 @@ module HyperCast
     end
 
     # The shared body of the integer/real/decimal doors: plain, plus the format's own
-    # packed pointer, passed straight through — no per-call copy of the 32 bytes into
+    # packed pointer, passed straight through — no per-call copy of the 92 bytes into
     # scratch.
     def numeric(symbol, text, format, out_size)
       bytes = utf8(text)
@@ -500,6 +649,47 @@ module HyperCast
       verdict(rc, fault, bytes) { yield(out[0, out_size]) }
     end
 
+    # The civil date-time door's body: declared, plus the day periods after the order — the
+    # 40 packed bytes copied into this thread's scratch and passed from there, or nil
+    # (Fiddle's null) when none are declared, which the core reads as English AM/PM only.
+    def civil(symbol, text, code, periods, out_size)
+      bytes = utf8(text)
+      out, fault, slot = scratch
+      if periods
+        slot[0, periods.bytesize] = periods
+      else
+        slot = nil
+      end
+      rc = Runtime.function(symbol).call(input_ptr(bytes), bytes.bytesize, code, slot, out, fault)
+      verdict(rc, fault, bytes) { yield(out[0, out_size]) }
+    end
+
+    # The 40-byte little-endian form of the native ABI's size-tagged DayPeriods struct: the
+    # size word (40), then each designator as its UTF-8 bytes zero-padded to 16 followed by
+    # its byte length — am, then pm — and two bytes of padding. A nil designator is a
+    # length of 0: nothing declared beside AM or PM.
+    def packed_day_periods(am, pm)
+      am = designator("am", am)
+      pm = designator("pm", pm)
+      [40].pack("L<") + [am, am.bytesize, pm, pm.bytesize].pack("a16Ca16C") + "\0\0"
+    end
+
+    # A declared day-period designator as the UTF-8 the core reads — 1 to 16 bytes, no
+    # ASCII digit, no ASCII whitespace at either end (the grammar around it reads that) —
+    # or "" for nil. Anything else is the caller bug it names, the same ArgumentError on
+    # every backend.
+    def designator(name, text)
+      return "" if text.nil?
+      raise ArgumentError, "#{name} designator must be a String; got #{text.inspect}" unless text.is_a?(String)
+
+      designator = text.encode(Encoding::UTF_8)
+      unless designator.bytesize.between?(1, 16) && !designator.match?(/[0-9]|\A[\t\n\f\r ]|[\t\n\f\r ]\z/)
+        raise ArgumentError, "#{name} designator #{text.inspect} must be 1 to 16 UTF-8 bytes with no ASCII digit " \
+                             "and no ASCII whitespace at either end"
+      end
+      designator
+    end
+
     # The shared body of the four doors that take a caller-declared u32 — a precision, an
     # epoch, or a field order — already resolved from its Symbol by the door. These bodies
     # (plain, numeric, declared, and packed_version below) are the whole Fiddle crossing.
@@ -550,21 +740,22 @@ module HyperCast
     PACKED_CACHE_LIMIT = 64
 
     # Identity-keyed memo (compare_by_identity — a pointer hash, not Data's structural
-    # #hash over three Strings and an Integer) of a native 32-byte RawNumFormat per format
+    # #hash over nine Strings and an Integer) of a native 92-byte RawNumFormat per format
     # object, filled once from NumFormat#packed. Formats are reused constants in practice,
     # so the common call finds its pointer in one lookup and packs nothing. The Hash holds
     # the format, so a key can never be a recycled address; the race is benign (idempotent).
     #
     # Bounded, oldest entry out first (a Hash keeps insertion order): unbounded, it held
-    # every format ever cast with and its 32-byte allocation for the life of the process,
+    # every format ever cast with and its 92-byte allocation for the life of the process,
     # which a consumer building a format per request experienced as a leak. A format
     # evicted and then used again is simply packed again, and an evicted pointer stays
     # alive for any call already holding it — the caller's own reference outlives the cache's.
     def packed_cache
       @packed_cache ||= Hash.new do |cache, format|
         cache.shift while cache.size >= PACKED_CACHE_LIMIT
-        pointer = Runtime.buffer(32)
-        pointer[0, 32] = format.packed
+        size = NumFormat::PACKED_BYTES
+        pointer = Runtime.buffer(size)
+        pointer[0, size] = format.packed
         cache[format] = pointer
       end.compare_by_identity
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hypercast-wasm
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 1.0.0
 platform: ruby
 authors:
 - Brian Buvinghausen