duckling 0.2.0 → 0.3.0

data/ext/duckling/src/ruby_value.rs

@@ -0,0 +1,104 @@
+use magnus::r_hash::ForEach;
+use magnus::value::ReprValue;
+use magnus::{Error, RArray, RHash, RString, Ruby, Symbol, Value};
+
+/// Recursively rewrites every `Hash` reachable from `value` (including
+/// through `Array` elements, at any depth) so its keys are `Symbol`s instead
+/// of `String`s, mutating in place rather than allocating replacement
+/// Hashes/Arrays. Keys that aren't `String` (e.g. already a `Symbol`) pass
+/// through unchanged; non-Hash, non-Array values are untouched.
+///
+/// This is deliberately an in-place rewrite rather than a recursive rebuild:
+/// `serde_magnus::serialize`'s externally-tagged output already allocates one
+/// Hash per enum layer (e.g. `{"Naive" => {...}}`), so a rebuild pass would
+/// double that cost by discarding and reallocating the whole tree just to
+/// change key types.
+///
+/// GC safety note: keys collected off the `Hash` are staged in a Ruby
+/// `RArray`, never a Rust-native `Vec<Value>`. A `Value` held only in a
+/// `Vec` (heap-allocated Rust memory) is invisible to MRI's conservative
+/// stack-scanning GC once it's no longer reachable from any Ruby-visible
+/// root — deleting an entry from its `Hash` and stashing the freed key/value
+/// `Value`s in a `Vec` across further Magnus calls (which can trigger GC) is
+/// a real use-after-free, not just a style concern. Keeping them in an
+/// `RArray` instead means the GC treats them as reachable for as long as
+/// the array itself is reachable (it lives in a local, stack-scanned
+/// `RArray` variable for the duration of this function).
+pub fn symbolize_keys_in_place(ruby: &Ruby, value: Value) -> Result<(), Error> {
+    if let Some(hash) = RHash::from_value(value) {
+        let keys = ruby.ary_new();
+        hash.foreach(|k: Value, _v: Value| {
+            keys.push(k)?;
+            Ok(ForEach::Continue)
+        })?;
+
+        for i in 0..keys.len() as isize {
+            let k: Value = keys.entry(i)?;
+            // Only a String key needs the hash structure itself touched
+            // (delete under the old key, reinsert under the new Symbol);
+            // serde_magnus already emits Symbol keys for struct fields,
+            // so most entries just need their value recursed into.
+            //
+            // Tested with `RString::from_value` (an Option-returning type
+            // check) rather than `String::try_convert` (a Result-returning
+            // conversion): the latter builds a full TypeError — exception
+            // object plus its formatted message String plus the class-name
+            // String — for every already-Symbol key it rejects, which is most
+            // of them. That is three throwaway allocations per key on the
+            // hot path, purely to answer a question `from_value` answers for
+            // free.
+            match RString::from_value(k) {
+                Some(s) => {
+                    let v: Value = hash.delete(k)?;
+                    symbolize_keys_in_place(ruby, v)?;
+                    // Interned via String#to_sym on the key's own VALUE
+                    // rather than round-tripping through Rust: `as_str` +
+                    // `to_owned` + `ruby.to_symbol` costs a Rust String copy
+                    // plus a fresh Ruby String (magnus 0.8.2's
+                    // `&str.into_symbol_with` is `rb_to_symbol(str_new(..))`)
+                    // per key, where `to_sym` interns the existing String
+                    // directly. `s` stays GC-reachable across the recursion
+                    // above through the `keys` array (see the note on this
+                    // function), so the deferred use is safe.
+                    let sym: Symbol = s.funcall("to_sym", ())?;
+                    hash.aset(sym, v)?;
+                }
+                None => {
+                    let v: Value = hash.aref(k)?;
+                    symbolize_keys_in_place(ruby, v)?;
+                }
+            }
+        }
+        return Ok(());
+    }
+
+    if let Some(arr) = RArray::from_value(value) {
+        for i in 0..arr.len() as isize {
+            let item: Value = arr.entry(i)?;
+            symbolize_keys_in_place(ruby, item)?;
+        }
+    }
+
+    Ok(())
+}
+
+/// Serializes `input` via `serde_magnus` and symbolizes every Hash key in
+/// the result, preserving serde's externally-tagged representation verbatim
+/// (e.g. `{Numeral: 42.0}`, `{Url: {value:, domain:}}`,
+/// `{Temperature: {Value: {value:, unit:}}}`). The PascalCase tag key is
+/// kept uniformly across every enum layer — the outer `DimensionValue` tag
+/// and nested tags like `MeasurementValue`'s `Value`/`Interval` get the same
+/// treatment, so consumers see one consistent tagged shape rather than a
+/// mix of unwrapped and tagged layers.
+///
+/// GC safety: the serialized `Value` lives in a stack-scanned local for the
+/// duration of this function — see `symbolize_keys_in_place`'s note for why
+/// heap-held `Vec<Value>`s are the thing to avoid.
+pub fn serialize_symbolized<T>(ruby: &Ruby, input: &T) -> Result<Value, Error>
+where
+    T: serde::Serialize + ?Sized,
+{
+    let serialized: Value = serde_magnus::serialize(ruby, input)?;
+    symbolize_keys_in_place(ruby, serialized)?;
+    Ok(serialized)
+}

data/lib/duckling/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Duckling
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

data/lib/duckling.rb

@@ -1,4 +1,268 @@
 # frozen_string_literal: true
 
+require "tzinfo"
+
 require_relative "duckling/version"
-require_relative "duckling/duckling"
+
+# A precompiled gem carries one binary per Ruby ABI, each in its own
+# lib/duckling/<major.minor>/ directory. Load the one for the running Ruby.
+#
+# rb-sys reads Ruby's internal object layout through the headers it compiles
+# against, so a binary understands only the Ruby that built it. Load the wrong
+# one and it misreads objects: magnus rejects a genuine Time as not a Time.
+#
+# A source-gem build, and a plain `rake compile` in a checkout, write one
+# binary straight to lib/duckling/ instead. That build always matches the
+# running Ruby, so it needs no version directory.
+begin
+  require_relative "duckling/#{RUBY_VERSION[/\d+\.\d+/]}/duckling"
+rescue LoadError => abi_load_error
+  begin
+    require_relative "duckling/duckling"
+  rescue LoadError
+    # The ABI directory is missing, and so is the plain path. Raise the first
+    # error, not the second.
+    #
+    # A binary that exists but refuses to load fails here too, and its error
+    # says why. An Alpine install does this: RubyGems matches an unversioned
+    # -linux gem against a musl runtime, so the binary is present and asks for
+    # glibc. Reporting a missing file there would hide the real reason.
+    raise abi_load_error
+  end
+end
+
+module Duckling
+  # Raised when the serialized :time :value shape drifts from the typed walk in
+  # ext/duckling/src/lib.rs's patch_time_value/patch_time_point — a wrapper bug.
+  # Deliberately a RuntimeError subclass (not ArgumentError) so a caller
+  # rescuing ArgumentError around bad locale:/reference_zone: input can't
+  # swallow it, and a *named* one (not bare RuntimeError) so it's greppable and
+  # can't be satisfied by the unrelated native-panic RuntimeError. Mirrors the
+  # internal_error() class in lib.rs.
+  class ShapeError < RuntimeError; end
+
+  # Native.parse already releases the GVL around the native call, but a bare
+  # GVL release alone does not hand control back to an Async::Reactor —
+  # Ruby 3.4's Fiber::Scheduler#blocking_operation_wait auto-offload path
+  # requires a flag rb_thread_call_without_gvl never sets. Spawning a real
+  # background Thread lets the calling Fiber yield to the reactor via
+  # Thread#value's block/unblock scheduler hooks instead, which have been
+  # present since Ruby 3.0. See
+  # https://github.com/cpb/duckling/wiki/research-fiber-scheduler-mechanism-spike
+  # for the empirical result driving this.
+  #
+  # Only worth paying for when a Fiber scheduler is actually installed on the
+  # calling thread: a plain thread pool (Puma/Sidekiq-style, no reactor to
+  # yield to) already gets its concurrency from Native.parse's own GVL
+  # release, so the extra Thread.new there is a pure spawn+join tax. Calling
+  # Native.parse directly (no thread) is also the benchmark suite's baseline
+  # for measuring the dispatch overhead itself.
+  #
+  # report_on_exception is disabled from the very first line inside the
+  # spawned thread (not set on the Thread object afterward, which would race
+  # a fast-failing call) so a rescued error doesn't also print a
+  # thread-termination backtrace to stderr — Thread#value still re-raises it
+  # to the caller as ordinary control flow.
+  #
+  # reference_time: is coerced here, not in the native extension:
+  # Native.parse's Magnus binding only accepts a strict kind_of?(Time) (issue
+  # #45), which rejects ActiveSupport::TimeWithZone and stdlib DateTime even
+  # though both carry the same to_i/utc_offset a real Time does — #to_time
+  # normalizes any of those (and anything else that offers the same
+  # conversion) to a real Time before it crosses into Rust.
+  # reference_zone: never crosses into Native.parse — the wrapped Rust crate
+  # has no IANA-zone concept at all, only the single FixedOffset it derives
+  # from reference_time:. Per-date-correct offsets therefore have to come from
+  # a real tz database on the Ruby side, so reference_zone: is applied as a
+  # two-part step around the native call: validate the zone (and reference_time:'s
+  # agreement with it) before, then reinterpret Naive results after.
+  #
+  # A fixed offset and a zone that disagree at the reference instant have no
+  # principled resolution — silently preferring either would resolve results
+  # against an offset the caller never asked for — so that combination raises
+  # rather than guessing.
+  #
+  # reference_zone: only reinterprets result offsets after the fact; it does
+  # NOT anchor the parse. Given without reference_time:, relative expressions
+  # ("tomorrow") still anchor on the machine-local clock, not on "now" in that
+  # zone, so on a US host reference_zone: "Asia/Tokyo" can land on the wrong
+  # calendar day. Pass a reference_time: in the zone to anchor as well.
+  def self.parse(text, locale: "en", dims: ["time"], reference_time: nil, with_latent: false, reference_zone: nil)
+    reference_time = reference_time.to_time if reference_time && !reference_time.is_a?(Time) && reference_time.respond_to?(:to_time)
+
+    if reference_zone
+      zone = timezone_for(reference_zone)
+      verify_reference_time_offset!(reference_time, zone, reference_zone) if reference_time
+    end
+
+    kwargs = {locale: locale, dims: dims, with_latent: with_latent}
+    kwargs[:reference_time] = reference_time if reference_time
+
+    entities = if Fiber.scheduler
+      Thread.new do
+        Thread.current.report_on_exception = false
+        Native.parse(text, **kwargs)
+      end.value
+    else
+      Native.parse(text, **kwargs)
+    end
+
+    zone ? reinterpret_entities!(entities, zone) : entities
+  end
+
+  # Reinterprets every TimePoint::Naive (wall-clock) leaf of each :time entity
+  # against `reference_zone`, using the real IANA offset for that leaf's own
+  # date rather than the single fixed offset reference_time: carries.
+  #
+  # TimePoint::Instant leaves are left strictly alone: the wrapped crate
+  # already collapsed their relative arithmetic against one FixedOffset before
+  # this gem ever saw the result, so there is no wall-clock left to reinterpret.
+  # That arithmetic's DST imprecision is known and out of scope (issue #83).
+  #
+  # Walks the externally-tagged shape ext/duckling/src/lib.rs's patch_time_value
+  # produces, and raises on any tag it doesn't recognize: a shape drift on the
+  # Rust side must fail loudly here rather than quietly returning results
+  # resolved against the wrong offset.
+  def self.apply_reference_zone(entities, reference_zone)
+    return entities unless reference_zone
+
+    reinterpret_entities!(entities, timezone_for(reference_zone))
+  end
+
+  # Zone-object core of apply_reference_zone. parse calls this directly with
+  # the TZInfo::Timezone it already resolved for offset validation, so the
+  # zone is looked up once per call rather than once for validation and again
+  # for reinterpretation.
+  def self.reinterpret_entities!(entities, zone)
+    entities.each do |entity|
+      next unless entity[:dim] == :time
+      reinterpret_time_value!(entity[:value][:Time], zone)
+    end
+    entities
+  end
+  private_class_method :reinterpret_entities!
+
+  # Walks the Single/Interval + Naive/Instant tagged shape. A primary value
+  # (single[:value], or an interval's from/to) and every `values` recurrence
+  # entry are resolved identically — see local_time_in_zone.
+  def self.reinterpret_time_value!(value, zone)
+    if (single = value && value[:Single])
+      reinterpret_time_point!(single[:value], zone)
+      single[:values]&.each { |point| reinterpret_time_point!(point, zone) }
+    elsif (interval = value && value[:Interval])
+      reinterpret_interval_endpoints!(interval, zone)
+      interval[:values]&.each { |endpoints| reinterpret_interval_endpoints!(endpoints, zone) }
+    else
+      raise ShapeError, "unrecognized :time value shape, expected a :Single or :Interval tag: #{value.inspect}"
+    end
+  end
+  private_class_method :reinterpret_time_value!
+
+  # An Interval's from/to are Option<TimePoint> on the Rust side, and serde
+  # emits Option::None as a present key holding nil — hence the nil tolerance
+  # in reinterpret_time_point!, rather than a missing-key check here.
+  def self.reinterpret_interval_endpoints!(endpoints, zone)
+    reinterpret_time_point!(endpoints[:from], zone)
+    reinterpret_time_point!(endpoints[:to], zone)
+  end
+  private_class_method :reinterpret_interval_endpoints!
+
+  def self.reinterpret_time_point!(point, zone)
+    return if point.nil?
+
+    if (naive = point[:Naive])
+      naive[:value] = local_time_in_zone(zone, naive[:value])
+    elsif !point.key?(:Instant)
+      raise ShapeError, "unrecognized TimePoint shape, expected a :Naive or :Instant tag: #{point.inspect}"
+    end
+  end
+  private_class_method :reinterpret_time_point!
+
+  # The Rust side already resolved this Naive wall-clock against reference_time:'s
+  # fixed offset, so the Time's own calendar fields still read as that intended
+  # wall-clock — re-anchoring those same fields in `zone` is what picks up the
+  # per-date DST offset.
+  #
+  # A wall-clock that a spring-forward gap skipped, or that a fall-back overlap
+  # made ambiguous, has no single correct offset — but there's no benefit to
+  # raising over it either, whether the value is a primary one the caller
+  # literally named or a generated recurrence entry: both get the same
+  # deterministic resolution — a gap shifts the wall clock forward by the
+  # transition's delta (02:30 on a US spring-forward day becomes 03:30 EDT),
+  # an overlap takes the first (pre-transition) occurrence.
+  #
+  # The first occurrence is selected via the block form (periods_for_local
+  # yields periods in chronological order), NOT tzinfo's dst flag: dst=true
+  # only means "first" where the pre-transition period observes DST, and
+  # negative-DST zones invert that — Europe/Dublin models winter GMT as its
+  # dst?==true period, so dst=true there would pick the second occurrence, an
+  # hour off as an instant. (ActiveSupport::TimeZone#local has exactly that
+  # Dublin behavior, via period_for_local's dst=true default — a deliberate
+  # departure here, like the Lord Howe one on gap_delta.) The explicit nil dst
+  # argument keeps a global Timezone.default_dst setting from pre-filtering
+  # the periods before the block sees them.
+  #
+  # Preserving the gap's original wall clock and merely stamping the
+  # post-transition offset on it would produce a Time whose offset the zone
+  # does not observe at that instant — 02:30 -04:00 is 06:30Z, and at 06:30Z
+  # New York is still on EST — so it would read back as 01:30 EST, an hour
+  # before the occurrence it stands for and on the wrong side of the
+  # transition. Shifting forward keeps the instant and its rendered local
+  # time in agreement.
+  def self.local_time_in_zone(zone, time)
+    first_occurrence = lambda do |t|
+      zone.local_time(t.year, t.month, t.day, t.hour, t.min, t.sec, t.subsec, nil) do |periods|
+        periods.first
+      end
+    end
+    first_occurrence.call(time)
+  rescue TZInfo::PeriodNotFound
+    first_occurrence.call(time + gap_delta(zone, time))
+  end
+  private_class_method :local_time_in_zone
+
+  # How wide the spring-forward gap `time` fell into is — i.e. how far forward
+  # a skipped wall clock must move to land on a real one. DST transitions are
+  # months apart, so the single offset-increasing transition within a day of
+  # `time` is necessarily the one whose gap it landed in.
+  #
+  # The ±1-day scan window is centered on the skipped wall clock itself read
+  # as UTC — not on the UTC midnight of its date. The transition's UTC instant
+  # is the wall clock minus a zone offset, and offsets never reach a day, so
+  # this window always contains it; a midnight-anchored window does not. A
+  # gap late in the local day in a negative-offset zone (America/Nuuk springs
+  # forward at 23:00 local) has its transition instant past the *next* UTC
+  # midnight, outside a midnight-anchored window — `find` returned nil and
+  # this method crashed instead of resolving.
+  #
+  # Read from the transition rather than assumed to be 3600. ActiveSupport's
+  # TimeWithZone#get_period_and_ensure_valid_local_time instead hardcodes
+  # `@time += 1.hour` and retries: for Australia/Lord_Howe's 30-minute gap
+  # that lands half an hour past the gap's end (02:15 → 03:15 rather than
+  # 02:45). Every one-hour gap — i.e. every zone in current use but Lord Howe
+  # — resolves identically either way.
+  def self.gap_delta(zone, time)
+    wall_clock = Time.utc(time.year, time.month, time.day, time.hour, time.min, time.sec)
+    transition = zone.transitions_up_to(wall_clock + 86400, wall_clock - 86400)
+      .find { |t| t.offset.observed_utc_offset > t.previous_offset.observed_utc_offset }
+    transition.offset.observed_utc_offset - transition.previous_offset.observed_utc_offset
+  end
+  private_class_method :gap_delta
+
+  def self.timezone_for(reference_zone)
+    TZInfo::Timezone.get(reference_zone)
+  rescue TZInfo::InvalidTimezoneIdentifier
+    raise ArgumentError, "invalid reference_zone: #{reference_zone.inspect}"
+  end
+  private_class_method :timezone_for
+
+  def self.verify_reference_time_offset!(reference_time, zone, reference_zone)
+    zone_offset = zone.period_for(reference_time).observed_utc_offset
+    return if reference_time.utc_offset == zone_offset
+
+    raise ArgumentError,
+      "reference_time's utc_offset (#{reference_time.utc_offset}) does not match " \
+      "reference_zone #{reference_zone.inspect}'s utc_offset (#{zone_offset}) at that instant"
+  end
+  private_class_method :verify_reference_time_offset!
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: duckling
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Caleb Buxton
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-07-01 00:00:00.000000000 Z
+date: 2026-08-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rb_sys
@@ -16,28 +16,84 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.9.39
+        version: 0.9.128
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.9.39
+        version: 0.9.128
+- !ruby/object:Gem::Dependency
+  name: tzinfo
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: tzinfo-data
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2024'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2024'
 - !ruby/object:Gem::Dependency
   name: rake-compiler
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.2.0
+        version: 1.3.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.3.1
+- !ruby/object:Gem::Dependency
+  name: benchmark-ips
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: async
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.41'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.2.0
+        version: '2.41'
 description: Duckling NER without an HTTP service for Ruby
 email:
 - me@cpb.ca
@@ -46,15 +102,22 @@ extensions:
 - ext/duckling/extconf.rb
 extra_rdoc_files: []
 files:
+- ".claude/settings.json"
+- AGENTS.md
+- Brewfile
 - CHANGELOG.md
+- CLAUDE.md
 - CODE_OF_CONDUCT.md
+- Cargo.lock
+- Cargo.toml
 - LICENSE.txt
 - README.md
 - Rakefile
-- ext/duckling/Cargo.lock
+- docs/2026-07-01-roadmap.md
 - ext/duckling/Cargo.toml
 - ext/duckling/extconf.rb
 - ext/duckling/src/lib.rs
+- ext/duckling/src/ruby_value.rs
 - lib/duckling.rb
 - lib/duckling/version.rb
 homepage: https://github.com/cpb/duckling