home issue 1

Research & Planning — Issue #1: Ship duckling gem (time extraction via Magnus + Duckling (Rust))

What this answers: How to ship a Ruby gem that extracts time/date entities from text using the duckling Rust crate wrapped via Magnus — no Haskell runtime, no HTTP call — and publish it as duckling 0.2.0.

Status: 0.2.0 has shipped. The implementation plans below fully executed — see Stale Plans — Fully Executed (0.2.0 Shipped). What's left is tracked as GitHub issues, summarized in the roadmap (kept in the repo, not the wiki, so it stays close to the code it tracks).

Reading Order

Start here, then follow the path for your role:

Implementer (picking up follow-on work): the roadmap — lists the open GitHub issues by theme.

Reviewer (understanding design): Research Key Findings → Plans Key Decisions → Plans.

Newcomer (orienting to the space): Research → Plans.

Table of Contents

Research

• Research — Issue #1: Ship duckling gem (time extraction via Magnus + Duckling (Rust)) — Breadth-first summary and key findings across all research topics.
  • Duckling (Rust) API Surface — Complete public Rust API: parse functions, types, time semantics, locale system.
    • Public Parse Functions — parse() and parse_en() signatures; crate type (rlib); no Magnus dependency.
    • Public Types — All public types with Mermaid diagrams; Naive vs Instant distinction.
    • Locale System — 49 Lang variants, 25 Region variants, Context, Options (with_latent defaults false).
  • Build Wiring Research — Magnus + rb-sys native extension build plumbing.
    • Extension Crate Layout — cdylib crate layout; duckling path dep; crates.io blocker.
    • extconf.rb Pattern — Verified 3-line extconf.rb from rust_blank example.
    • Rakefile Setup — ExtensionTask and lib_dir.
    • CI Configuration — Rust toolchain action; source vs. binary gem tradeoff.
  • Type Mapping Strategy — Rust→Ruby type conversion options.
    • Serialization Options: Rust to Ruby — serde_magnus vs. manual Magnus vs. JSON; verified serde attributes; recommendation.
    • Target Ruby Hash Schema (0.2.0 — Time Entities Only) — Target Ruby hash shape; NaiveDateTime tension; Grain string mapping.
    • Magnus Type Conversions — IntoValue table; chrono feature; working Rust example for entity hash.
  • Test Coverage Research — Test cases and minitest design.
    • Corpus Cases: Duckling (Rust) English Time Corpus — duckling time corpus; 10 categories; Rust test helper patterns.
    • Ruby Minitest Test Suite Design — REFERENCE_TIME, assertion helpers, 8 test classes.
    • pyduckling Reference Tests — pyduckling test inventory; port vs. skip decisions.
  • FFI Binding Risks — Hypotheses and Test Results — Tested evaluation of FFI binding risks (GVL blocking, panic safety, GC pressure, date rot, day-of-week validation gap).

Plans

• the roadmap — The live plan: what's left after 0.2.0, tracked as GitHub issues by theme (environment/tooling, Rakefile workflow, API design exploration, test coverage, performance). Lives in the repo, not the wiki.
  • Stale Plans — Fully Executed (0.2.0 Shipped) — The original three-plan implementation sequence (native extension → Ruby API → test suite/CI). Fully executed; kept here for historical record only.

Settled Decisions (0.2.0, verified shipped)

• duckling on crates.io — Published as duckling = "0.4". Use crates.io dep in Cargo.toml. No publish blocker. (Resolved in commit b17070e.)
• Symbol vs. String keys — All entity hash keys and dim/type/grain values are Ruby Symbols (:body, :dim, :value, :type, :grain, :day, etc.). Settled by the hill tests in PR #2, confirmed shipped in test/duckling_test.rb on main. → See Target Ruby Hash Schema (0.2.0 — Time Entities Only)
• NaiveDateTime format — Option N1 (bare ISO8601, no offset). Shipped as-is for 0.2.0. → See Target Ruby Hash Schema (0.2.0 — Time Entities Only)

Open Questions (all now tracked as GitHub issues — see the roadmap)

Both items below were open when this research was written; neither is unresolved prose anymore:

1. reference_time: timezone loss. Shipped as documented (Unix i64, reconstructs at UTC+0). Accepting a Ruby Time object instead is tracked as issue #45.

2. NoGrain → "nosec" vs. "no_grain". Shipped "no_grain" for 0.2.0. Whether any real Time entity in the extended corpus actually carries NoGrain is folded into issue #34 (extended test corpus).