duckling 0.2.0 → 0.3.0

data/ext/duckling/src/lib.rs

@@ -1,29 +1,207 @@
-use chrono::DateTime;
+use chrono::{FixedOffset, TimeZone};
 use duckling::{
-    parse as duckling_parse, Context, DimensionKind, DimensionValue, Entity, Lang, Locale, Options,
-    Region, TimePoint, TimeValue,
+    Context, DimensionKind, DimensionValue, Entity, Lang, Locale, Options, Region, TimePoint,
+    TimeValue, parse as duckling_parse,
 };
-use magnus::{function, prelude::*, scan_args, Error, RArray, Ruby, Value};
+use magnus::{
+    Error, RArray, RHash, Ruby, Time as RubyTime, Value, function, prelude::*, scan_args,
+};
+use std::os::raw::c_void;
+use std::panic::{AssertUnwindSafe, catch_unwind};
+
+mod ruby_value;
+use ruby_value::serialize_symbolized;
 
-// `Duckling` is the gem's whole public surface today (one module, one method),
-// so Magnus defines it directly rather than nesting a separate binding module
-// underneath it — there's no second Ruby-level API to keep stable independent
-// of the native layer yet. Revisit if/when the gem grows enough public Ruby
-// behavior (e.g. locale/dimension helpers) to warrant its own file.
+// `Duckling::Native` holds the raw Magnus-defined entrypoint; `Duckling.parse`
+// itself is a thin Ruby-level wrapper (see lib/duckling.rb) that dispatches
+// through a `Thread.new { ... }.value` so a calling Fiber on an Async::Reactor
+// can yield to sibling Fibers while the GVL-released native call runs (issue
+// #64). Keeping the native singleton method under a separate `Native` module
+// — rather than directly on `Duckling` — is what makes that split possible:
+// it gives Ruby code something to call *without* the thread-spawn, which the
+// benchmark suite also relies on to measure the dispatch overhead directly.
 #[magnus::init]
 fn init(ruby: &Ruby) -> Result<(), Error> {
     let module = ruby.define_module("Duckling")?;
-    module.define_singleton_method("parse", function!(parse, -1))?;
+    let native = module.define_module("Native")?;
+    native.define_singleton_method("parse", function!(parse, -1))?;
+    let panicking_fake = module.define_module("PanickingNativeFake")?;
+    panicking_fake.define_singleton_method("parse", function!(panicking_parse, -1))?;
     Ok(())
 }
 
-/// `Duckling.parse(text, locale: "en", dims: ["time"], reference_time: nil, with_latent: false)`
+/// Everything the off-GVL callback needs, and everything it produces.
+/// Deliberately holds only fully-owned Rust data — no `magnus::Value`, no
+/// `magnus::Error`, no other Ruby-VM-touching type crosses this struct in
+/// either direction (this repo's established rule: never stash a bare
+/// `magnus::Value`, or anything wrapping one, across a Magnus call boundary —
+/// a past incident here caused a real GC-safety segfault).
+struct ParsePayload {
+    text: String,
+    locale: Locale,
+    dims: Vec<DimensionKind>,
+    context: Context,
+    options: Options,
+    result: Option<Result<Vec<Entity>, String>>,
+}
+
+/// The raw callback handed to `rb_thread_call_without_gvl` as `func`. Runs
+/// with the GVL released: no Ruby method calls, no `Value`/`RArray`
+/// construction, no `magnus::Error` construction or raising is permitted
+/// here — only the plain Rust computation and writing plain Rust data back
+/// into `*payload`. Wraps the call in `std::panic::catch_unwind` directly
+/// (not `magnus::rb_sys::catch_unwind`) to keep the payload's "plain Rust
+/// data only" invariant simple and mechanically checkable.
+///
+/// This guard is required unconditionally, not just as release-profile
+/// defense-in-depth: the wrapped `duckling` crate's own internal
+/// `catch_unwind` is compiled out entirely under `#[cfg(not(debug_assertions))]`,
+/// which is absent from this repo's own `dev`-profile local default
+/// (`RB_SYS_CARGO_PROFILE=dev`, set via `.env.local`).
+unsafe extern "C" fn parse_without_gvl(payload: *mut c_void) -> *mut c_void {
+    // Edition 2024 requires unsafe operations to be wrapped in their own
+    // `unsafe` block even inside an `unsafe fn` (unsafe_op_in_unsafe_fn).
+    let payload = unsafe { &mut *(payload as *mut ParsePayload) };
+
+    let outcome = catch_unwind(AssertUnwindSafe(|| {
+        duckling_parse(
+            &payload.text,
+            &payload.locale,
+            &payload.dims,
+            &payload.context,
+            &payload.options,
+        )
+    }));
+
+    payload.result = Some(match outcome {
+        Ok(entities) => Ok(entities),
+        Err(panic_payload) => Err(panic_message(&*panic_payload)),
+    });
+
+    // Return value is unused by our caller (the real result is read back out
+    // of `*payload`); the C API just requires we return *something*.
+    std::ptr::null_mut()
+}
+
+/// Mirrors duckling's own panic_payload_message downcast (`&str` / `String` /
+/// fallback), kept local since we don't have access to duckling's private helper.
+fn panic_message(payload: &(dyn std::any::Any + Send)) -> String {
+    if let Some(&s) = payload.downcast_ref::<&'static str>() {
+        s.to_string()
+    } else if let Some(s) = payload.downcast_ref::<String>() {
+        s.clone()
+    } else {
+        "no panic message".to_string()
+    }
+}
+
+/// Converts a caught `duckling::parse` panic into the Ruby error the
+/// extension raises. Single choke point for the panic → exception mapping,
+/// shared by the real entrypoint and `Duckling::PanickingNativeFake`, so
+/// tests exercising the fake exercise the exact mapping callers see.
+///
+/// Deliberately `RuntimeError` (a `StandardError`), not magnus's own
+/// `Error::from_panic` convention of `fatal`: a native panic already cost
+/// the caller nothing but this one call, so it must be an ordinary
+/// `rescue => e`-able error, not one that also tears down the calling
+/// Thread's `Thread#value`/`Thread#join` propagation as unrescuable.
+fn panic_error(ruby: &Ruby, message: &str) -> Error {
+    Error::new(
+        ruby.exception_runtime_error(),
+        format!("duckling::parse panicked: {message}"),
+    )
+}
+
+/// Shorthand for the `Error::new(ruby.exception_arg_error(), ...)` pattern
+/// repeated across `parse_locale`, `parse_dims`, and `build_context`.
+fn arg_error(ruby: &Ruby, message: impl Into<String>) -> Error {
+    Error::new(ruby.exception_arg_error(), message.into())
+}
+
+/// Shorthand for internal invariant violations in the generic-serialize-then-
+/// patch walk (`patch_time_point`, `patch_time_value`, and `entity_to_ruby`'s
+/// `Time` branch): these only fire if `serde_magnus`'s serialization of
+/// `TimeValue`/`TimePoint` drifts from the typed walk built against it — a
+/// wrapper bug, not anything the caller did wrong. Deliberately
+/// `RuntimeError` (matching `panic_error`'s convention for "shouldn't happen"
+/// cases), not `arg_error`'s `ArgumentError`, so a caller `rescue
+/// ArgumentError`-ing their own bad `locale:`/`dims:` input handling doesn't
+/// inadvertently swallow a real bug here.
+fn internal_error(ruby: &Ruby, message: impl Into<String>) -> Error {
+    Error::new(ruby.exception_runtime_error(), message.into())
+}
+
+/// Payload for the test-only panicking fake below — same "plain owned Rust
+/// data only" rule as `ParsePayload`.
+struct PanicFakePayload {
+    result: Option<Result<Vec<Entity>, String>>,
+}
+
+/// Off-GVL callback for `Duckling::PanickingNativeFake.parse`: identical
+/// shape to `parse_without_gvl`, but the guarded computation always panics —
+/// standing in for a `duckling::parse` panic without needing a real
+/// panic-triggering input.
+unsafe extern "C" fn panic_fake_without_gvl(payload: *mut c_void) -> *mut c_void {
+    let payload = unsafe { &mut *(payload as *mut PanicFakePayload) };
+
+    let outcome = catch_unwind(AssertUnwindSafe(|| -> Vec<Entity> {
+        panic!("intentional panic from Duckling::PanickingNativeFake")
+    }));
+
+    payload.result = Some(match outcome {
+        Ok(entities) => Ok(entities),
+        Err(panic_payload) => Err(panic_message(&*panic_payload)),
+    });
+
+    std::ptr::null_mut()
+}
+
+/// `Duckling::PanickingNativeFake.parse(*)` — test-only stand-in for
+/// `Duckling::Native` whose native call always panics. Accepts (and
+/// ignores) `Native.parse`'s arguments so tests can swap the `Native`
+/// constant and drive the public `Duckling.parse` through the real
+/// GVL-release + `catch_unwind` + `panic_error` path, observing exactly
+/// what a `duckling::parse` panic does to a Ruby caller. Not part of the
+/// public API.
+fn panicking_parse(ruby: &Ruby, _args: &[Value]) -> Result<RArray, Error> {
+    let mut payload = PanicFakePayload { result: None };
+
+    unsafe {
+        rb_sys::rb_thread_call_without_gvl(
+            Some(panic_fake_without_gvl),
+            &mut payload as *mut PanicFakePayload as *mut c_void,
+            None,
+            std::ptr::null_mut(),
+        );
+    }
+
+    match payload
+        .result
+        .expect("panic_fake_without_gvl always sets result before returning")
+    {
+        Ok(_) => Ok(ruby.ary_new()),
+        Err(message) => Err(panic_error(ruby, &message)),
+    }
+}
+
+/// `Duckling::Native.parse(text, locale: "en", dims: ["time"], reference_time: nil, with_latent: false)`
+///
+/// The raw native entrypoint — no Thread spawn, no GVL-release considerations
+/// visible at the call site. `Duckling.parse` (see lib/duckling.rb) is the
+/// public API; it wraps this in `Thread.new { ... }.value` for thread-per-call
+/// dispatch. Called directly (no thread), this is also the "without" baseline
+/// the benchmark suite compares thread-per-call dispatch overhead against.
 ///
 /// - `locale`: BCP-47 tag (e.g. `"en"`, `"en-GB"`); unsupported codes raise `ArgumentError`.
 /// - `dims`: dimension names to extract; only `"time"` is implemented in 0.2.0,
 ///   other values raise `ArgumentError`.
-/// - `reference_time`: Unix seconds anchoring relative expressions like "tomorrow";
-///   defaults to `Context::default()` (now, UTC).
+/// - `reference_time`: a Ruby `Time` anchoring relative expressions like "tomorrow";
+///   its `utc_offset` is preserved into every time result's `:value` — both
+///   `Instant` results (e.g. "in one hour") and `Naive` (wall-clock) results
+///   (e.g. "tomorrow", "5pm"), which are resolved against this offset before
+///   being returned. `:value` is always a real Ruby `Time`, never a string.
+///   Defaults to `Context::default()` (now, UTC) when `nil`/omitted. A
+///   non-`Time` value raises `TypeError`.
 /// - `with_latent`: include ambiguous/latent matches (e.g. bare "morning").
 fn parse(ruby: &Ruby, args: &[Value]) -> Result<RArray, Error> {
     let args = scan_args::scan_args::<(String,), (), (), (), _, ()>(args)?;
@@ -33,7 +211,7 @@ fn parse(ruby: &Ruby, args: &[Value]) -> Result<RArray, Error> {
         (
             Option<String>,
             Option<Vec<String>>,
-            Option<i64>,
+            Option<RubyTime>,
             Option<bool>,
         ),
         (),
@@ -44,21 +222,54 @@ fn parse(ruby: &Ruby, args: &[Value]) -> Result<RArray, Error> {
     )?;
 
     let text = args.required.0;
-    let (locale_str, dims_strs, ref_time_i, with_latent) = kw.optional;
+    let (locale_str, dims_strs, ref_time, with_latent) = kw.optional;
     let locale_str = locale_str.unwrap_or_else(|| "en".to_string());
     let dims_strs = dims_strs.unwrap_or_else(|| vec!["time".to_string()]);
     let with_latent = with_latent.unwrap_or(false);
 
     let locale = parse_locale(ruby, &locale_str)?;
     let dims = parse_dims(ruby, &dims_strs)?;
-    let context = build_context(ruby, ref_time_i)?;
+    let context = build_context(ruby, ref_time)?;
     let options = Options { with_latent };
 
-    let entities = duckling_parse(&text, &locale, &dims, &context, &options);
+    // Release the GVL, call duckling::parse off-GVL, and block until the
+    // GVL is reacquired (rb_thread_call_without_gvl's documented step 4)
+    // before touching any Ruby Value again. The payload lives on this stack
+    // frame: rb_thread_call_without_gvl runs the callback to completion
+    // before returning, so no heap allocation or ownership transfer is
+    // needed — the borrow ends when the call returns.
+    let mut payload = ParsePayload {
+        text,
+        locale,
+        dims,
+        context,
+        options,
+        result: None,
+    };
+
+    unsafe {
+        rb_sys::rb_thread_call_without_gvl(
+            Some(parse_without_gvl),
+            &mut payload as *mut ParsePayload as *mut c_void,
+            None, // ubf: no cancellation hook (Thread#raise/#kill against an
+            // in-flight parse isn't handled — see issue #64's "Out of scope")
+            std::ptr::null_mut(),
+        );
+    }
+
+    let offset = payload.context.timezone();
+    let entities = match payload
+        .result
+        .expect("parse_without_gvl always sets result before returning")
+    {
+        Ok(entities) => entities,
+        // Safe to construct/raise now: the GVL is confirmed held again.
+        Err(message) => return Err(panic_error(ruby, &message)),
+    };
 
     let out = ruby.ary_new();
     for e in &entities {
-        out.push(entity_to_ruby(ruby, e)?)?;
+        out.push(entity_to_ruby(ruby, e, offset)?)?;
     }
     Ok(out)
 }
@@ -68,20 +279,14 @@ fn parse_locale(ruby: &Ruby, locale_str: &str) -> Result<Locale, Error> {
     let lang_code = parts.next().unwrap_or("");
     let region_code = parts.next();
 
-    let lang = lang_from_code(lang_code).ok_or_else(|| {
-        Error::new(
-            ruby.exception_arg_error(),
-            format!("unsupported locale: {locale_str:?}"),
-        )
-    })?;
+    let lang = lang_from_code(lang_code)
+        .ok_or_else(|| arg_error(ruby, format!("unsupported locale: {locale_str:?}")))?;
 
     let region = match region_code {
-        Some(code) => Some(region_from_code(code).ok_or_else(|| {
-            Error::new(
-                ruby.exception_arg_error(),
-                format!("unsupported locale: {locale_str:?}"),
-            )
-        })?),
+        Some(code) => Some(
+            region_from_code(code)
+                .ok_or_else(|| arg_error(ruby, format!("unsupported locale: {locale_str:?}")))?,
+        ),
         None => None,
     };
 
@@ -192,82 +397,165 @@ fn parse_dims(ruby: &Ruby, dims_strs: &[String]) -> Result<Vec<DimensionKind>, E
             "credit-card-number" => Ok(DimensionKind::CreditCardNumber),
             "time-grain" => Ok(DimensionKind::TimeGrain),
             "duration" => Ok(DimensionKind::Duration),
-            other => Err(Error::new(
-                ruby.exception_arg_error(),
-                format!("unsupported dimension: {other:?}"),
-            )),
+            other => Err(arg_error(ruby, format!("unsupported dimension: {other:?}"))),
         })
         .collect()
 }
 
-fn build_context(ruby: &Ruby, ref_time_i: Option<i64>) -> Result<Context, Error> {
-    match ref_time_i {
-        Some(secs) => {
-            let utc = DateTime::from_timestamp(secs, 0)
-                .ok_or_else(|| Error::new(ruby.exception_arg_error(), "invalid reference_time"))?;
-            Ok(Context::new(utc.fixed_offset(), Locale::default()))
+fn build_context(ruby: &Ruby, ref_time: Option<RubyTime>) -> Result<Context, Error> {
+    match ref_time {
+        Some(time) => {
+            let ts = time.timespec()?;
+            let offset = FixedOffset::east_opt(time.utc_offset() as i32).ok_or_else(|| {
+                arg_error(ruby, "invalid reference_time: utc_offset out of range")
+            })?;
+            let anchor = offset
+                .timestamp_opt(ts.tv_sec, ts.tv_nsec as u32)
+                .single()
+                .ok_or_else(|| arg_error(ruby, "invalid reference_time: timestamp out of range"))?;
+            Ok(Context::new(anchor, Locale::default()))
         }
         None => Ok(Context::default()),
     }
 }
 
-fn time_point_to_ruby(ruby: &Ruby, tp: &TimePoint) -> Result<Value, Error> {
-    let h = ruby.hash_new();
-    h.aset(ruby.to_symbol("type"), ruby.to_symbol("value"))?;
+/// Resolves a bare `NaiveDateTime` (wall-clock, no offset) against the
+/// reference offset into an absolute `DateTime<FixedOffset>`. Shared by
+/// `time_point_to_ruby` and `time_value_to_ruby` so the two call sites can't
+/// drift apart on error message or ambiguity-handling strategy.
+/// `FixedOffset` has no DST, so `.single()` is total in practice for any
+/// `NaiveDateTime` duckling can produce; the `ok_or_else` is defensive.
+fn resolve_naive(
+    ruby: &Ruby,
+    offset: FixedOffset,
+    value: &chrono::NaiveDateTime,
+) -> Result<chrono::DateTime<FixedOffset>, Error> {
+    offset
+        .from_local_datetime(value)
+        .single()
+        .ok_or_else(|| arg_error(ruby, "invalid or ambiguous naive time for reference offset"))
+}
+
+/// Patches a single generically-serialized `TimePoint` leaf in place: `point`
+/// is the externally-tagged one-key Hash `serde_magnus` produced for it
+/// (`{Naive: {value:, grain:}}` or `{Instant: {value:, grain:}}`), still
+/// holding serde's placeholder String datetime and raw PascalCase grain. `tp`
+/// is the typed Rust value the serialization came from, giving us everything
+/// needed to overwrite both leaves with the real thing: a genuine Magnus
+/// `Time` (running `resolve_naive`'s reference-offset resolution for
+/// `Naive`, direct `IntoValue` for `Instant`) and `Grain::as_str()`'s
+/// lowercase-snake_case symbol.
+fn patch_time_point(
+    ruby: &Ruby,
+    point: Value,
+    tp: &TimePoint,
+    offset: FixedOffset,
+) -> Result<(), Error> {
+    let outer = RHash::from_value(point)
+        .ok_or_else(|| internal_error(ruby, "expected serialized TimePoint to be a Hash"))?;
+    let tag = match tp {
+        TimePoint::Naive { .. } => "Naive",
+        TimePoint::Instant { .. } => "Instant",
+    };
+    let inner: Value = outer.aref(ruby.to_symbol(tag))?;
+    let inner = RHash::from_value(inner).ok_or_else(|| {
+        internal_error(ruby, "expected serialized TimePoint payload to be a Hash")
+    })?;
     match tp {
         TimePoint::Naive { value, grain } => {
-            h.aset(
-                ruby.to_symbol("value"),
-                value.format("%Y-%m-%dT%H:%M:%S").to_string(),
-            )?;
-            h.aset(ruby.to_symbol("grain"), ruby.to_symbol(grain.as_str()))?;
+            inner.aset(ruby.to_symbol("value"), resolve_naive(ruby, offset, value)?)?;
+            inner.aset(ruby.to_symbol("grain"), ruby.to_symbol(grain.as_str()))?;
         }
         TimePoint::Instant { value, grain } => {
-            h.aset(ruby.to_symbol("value"), value.to_rfc3339())?;
-            h.aset(ruby.to_symbol("grain"), ruby.to_symbol(grain.as_str()))?;
+            inner.aset(ruby.to_symbol("value"), *value)?;
+            inner.aset(ruby.to_symbol("grain"), ruby.to_symbol(grain.as_str()))?;
         }
     }
-    Ok(h.as_value())
+    Ok(())
 }
 
-fn time_value_to_ruby(ruby: &Ruby, tv: &TimeValue) -> Result<Value, Error> {
-    let h = ruby.hash_new();
+/// Patches every datetime/grain leaf reachable from a generically-serialized
+/// `TimeValue` (`serialized` is the `{Single: {...}}` / `{Interval: {...}}`
+/// payload, i.e. `entity.value`'s serialization with the outer `Time` tag
+/// already unwrapped) using the typed `tv` this serialization came from to
+/// walk to exactly the same positions `serde_magnus` placed them at: the
+/// `Single` case's primary `value` plus every `values` recurrence entry, or
+/// the `Interval` case's `from`/`to` plus every `values` recurrence entry's
+/// own `from`/`to`. Every other field `serde_magnus` produced (`values`
+/// array framing, `holidayBeta`) is left untouched — this only overwrites
+/// the known problem leaves, per issue #91's "generic-serialize-then-patch"
+/// design.
+fn patch_time_value(
+    ruby: &Ruby,
+    serialized: Value,
+    tv: &TimeValue,
+    offset: FixedOffset,
+) -> Result<(), Error> {
+    let outer = RHash::from_value(serialized)
+        .ok_or_else(|| internal_error(ruby, "expected serialized TimeValue to be a Hash"))?;
     match tv {
         TimeValue::Single { value, values, .. } => {
-            h.aset(ruby.to_symbol("type"), ruby.to_symbol("value"))?;
-            match value {
-                TimePoint::Naive { value: dt, grain } => {
-                    h.aset(
-                        ruby.to_symbol("value"),
-                        dt.format("%Y-%m-%dT%H:%M:%S").to_string(),
-                    )?;
-                    h.aset(ruby.to_symbol("grain"), ruby.to_symbol(grain.as_str()))?;
-                }
-                TimePoint::Instant { value: dt, grain } => {
-                    h.aset(ruby.to_symbol("value"), dt.to_rfc3339())?;
-                    h.aset(ruby.to_symbol("grain"), ruby.to_symbol(grain.as_str()))?;
-                }
-            }
-            let vals = ruby.ary_new();
-            for tp in values {
-                vals.push(time_point_to_ruby(ruby, tp)?)?;
+            let inner: Value = outer.aref(ruby.to_symbol("Single"))?;
+            let inner = RHash::from_value(inner).ok_or_else(|| {
+                internal_error(ruby, "expected serialized Single payload to be a Hash")
+            })?;
+
+            let point: Value = inner.aref(ruby.to_symbol("value"))?;
+            patch_time_point(ruby, point, value, offset)?;
+
+            let vals: Value = inner.aref(ruby.to_symbol("values"))?;
+            let vals = RArray::from_value(vals).ok_or_else(|| {
+                internal_error(ruby, "expected serialized Single values to be an Array")
+            })?;
+            for (i, tp) in values.iter().enumerate() {
+                let entry: Value = vals.entry(i as isize)?;
+                patch_time_point(ruby, entry, tp, offset)?;
             }
-            h.aset(ruby.to_symbol("values"), vals)?;
         }
-        TimeValue::Interval { from, to, .. } => {
-            h.aset(ruby.to_symbol("type"), ruby.to_symbol("interval"))?;
+        TimeValue::Interval {
+            from, to, values, ..
+        } => {
+            let inner: Value = outer.aref(ruby.to_symbol("Interval"))?;
+            let inner = RHash::from_value(inner).ok_or_else(|| {
+                internal_error(ruby, "expected serialized Interval payload to be a Hash")
+            })?;
+
             if let Some(tp) = from {
-                h.aset(ruby.to_symbol("from"), time_point_to_ruby(ruby, tp)?)?;
+                let point: Value = inner.aref(ruby.to_symbol("from"))?;
+                patch_time_point(ruby, point, tp, offset)?;
             }
             if let Some(tp) = to {
-                h.aset(ruby.to_symbol("to"), time_point_to_ruby(ruby, tp)?)?;
+                let point: Value = inner.aref(ruby.to_symbol("to"))?;
+                patch_time_point(ruby, point, tp, offset)?;
+            }
+
+            let vals: Value = inner.aref(ruby.to_symbol("values"))?;
+            let vals = RArray::from_value(vals).ok_or_else(|| {
+                internal_error(ruby, "expected serialized Interval values to be an Array")
+            })?;
+            for (i, endpoints) in values.iter().enumerate() {
+                let entry: Value = vals.entry(i as isize)?;
+                let entry = RHash::from_value(entry).ok_or_else(|| {
+                    internal_error(
+                        ruby,
+                        "expected serialized IntervalEndpoints entry to be a Hash",
+                    )
+                })?;
+                if let Some(tp) = &endpoints.from {
+                    let point: Value = entry.aref(ruby.to_symbol("from"))?;
+                    patch_time_point(ruby, point, tp, offset)?;
+                }
+                if let Some(tp) = &endpoints.to {
+                    let point: Value = entry.aref(ruby.to_symbol("to"))?;
+                    patch_time_point(ruby, point, tp, offset)?;
+                }
             }
         }
     }
-    Ok(h.as_value())
+    Ok(())
 }
 
-fn entity_to_ruby(ruby: &Ruby, entity: &Entity) -> Result<Value, Error> {
+fn entity_to_ruby(ruby: &Ruby, entity: &Entity, offset: FixedOffset) -> Result<Value, Error> {
     let h = ruby.hash_new();
     h.aset(ruby.to_symbol("body"), entity.body.clone())?;
     h.aset(ruby.to_symbol("start"), entity.start)?;
@@ -277,8 +565,52 @@ fn entity_to_ruby(ruby: &Ruby, entity: &Entity) -> Result<Value, Error> {
     if let Some(latent) = entity.latent {
         h.aset(ruby.to_symbol("latent"), latent)?;
     }
-    if let DimensionValue::Time(ref tv) = entity.value {
-        h.aset(ruby.to_symbol("value"), time_value_to_ruby(ruby, tv)?)?;
+    match &entity.value {
+        DimensionValue::Time(tv) => {
+            // Generic serialize-then-patch (issue #91), same convention #90
+            // uses for the other 13 dimensions: serde_magnus gives us the
+            // structural shape (`Single`/`Interval` discrimination, `values`,
+            // `holidayBeta`) for free; `patch_time_value` then overwrites the
+            // known-problem leaves (datetime placeholders, raw-PascalCase
+            // grains) using the typed `tv` this serialization came from.
+            let serialized = serialize_symbolized(ruby, &entity.value)?;
+            let outer = RHash::from_value(serialized).ok_or_else(|| {
+                internal_error(ruby, "expected serialized DimensionValue to be a Hash")
+            })?;
+            let time_payload: Value = outer.aref(ruby.to_symbol("Time"))?;
+            patch_time_value(ruby, time_payload, tv, offset)?;
+            h.aset(ruby.to_symbol("value"), serialized)?;
+        }
+        // `Grain` serde-serializes as PascalCase variant names ("Second",
+        // "NoGrain"); the shipped convention is `Grain::as_str()` symbols
+        // (:second, :no_grain) — see time_point_to_ruby. For TimeGrain the
+        // grain *is* the whole tagged payload, so the hash is built directly
+        // rather than serialized-then-patched.
+        DimensionValue::TimeGrain(grain) => {
+            let value = ruby.hash_new();
+            value.aset(ruby.to_symbol("TimeGrain"), ruby.to_symbol(grain.as_str()))?;
+            h.aset(ruby.to_symbol("value"), value)?;
+        }
+        // Duration has exactly three scalar fields, so — like TimeGrain above
+        // — the tagged hash is built directly rather than serialized then
+        // patched: a serialize-then-patch here would silently no-op if the
+        // crate's serde representation of Duration ever changed shape.
+        DimensionValue::Duration {
+            value: count,
+            grain,
+            normalized_seconds,
+        } => {
+            let payload = ruby.hash_new();
+            payload.aset(ruby.to_symbol("value"), *count)?;
+            payload.aset(ruby.to_symbol("grain"), ruby.to_symbol(grain.as_str()))?;
+            payload.aset(ruby.to_symbol("normalized_seconds"), *normalized_seconds)?;
+            let tagged = ruby.hash_new();
+            tagged.aset(ruby.to_symbol("Duration"), payload)?;
+            h.aset(ruby.to_symbol("value"), tagged)?;
+        }
+        other => {
+            h.aset(ruby.to_symbol("value"), serialize_symbolized(ruby, other)?)?;
+        }
     }
     Ok(h.as_value())
 }