duckling 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e13fe61846d4bc85faed37d388e0845de0bf0a6742d5b73796524987b0c85681
-  data.tar.gz: b8fec101cf3f92a760ef275261cbbebe3411185cb4ea84bd19756bd25b09bef1
+  metadata.gz: b5a2e1267025c49fdc9d0217f04a93543acc76d1a064eb8257cae7ca7c39c1fa
+  data.tar.gz: e2cfc90eb5fb08211176cc6d5b95c370ddd92d39abf6a209f871799dabc5023e
 SHA512:
-  metadata.gz: 93d4e3ce65576eb6ab27ec20b617b7bc4cdcab1a1be8bf61ccacbf33ede40daf5293e9ec10053a893986d424761012d3d5083ace5bf7681750a6cfb1fa40574e
-  data.tar.gz: 722c57d3d75412edc428b2476a6312ff5b6162a28537e50b523da94d41b0289f7c5b86a46072aa1a37ef72f580753ee9057c2452b0310580aba0843f76ff5a98
+  metadata.gz: 6d1fa9bb53e5c4869569678130cb7d492766bcbc40254629736efc383fc9dc04728d8fec5537a2d14326d85555c32b29f64b7f55ad64b3e215556949ac738301
+  data.tar.gz: 8e4ff2d3db274a3316261ab7ddb892f09c095dbed99de3b0d5edf36580df6cf1bac729a822ea8131da88f30b6a350bc2290fb5a9dcc25a1c8432708e2fdadd24

data/AGENTS.md

@@ -31,17 +31,23 @@ If you notice this file describing a not-yet-built piece as current, or vice ver
 | `lib/duckling.rb` | Ruby module entrypoint. Loads the compiled native extension from the running Ruby's ABI directory (`duckling/<major.minor>/duckling`, as a precompiled fat gem ships it), falling back to the plain `duckling/duckling` path a source-gem build or a local `rake compile` writes — see "Build model" below for why one binary can't serve every Ruby. The extension defines `Duckling::Native.parse` (the raw entrypoint — no thread spawn). `Duckling.parse` is then defined here as a thin Ruby-level wrapper that only dispatches through `Thread.new { Native.parse(...) }.value` when `Fiber.scheduler` is installed on the calling thread — see the "Rust/Magnus wiring" section's GVL-release bullet below for why a bare GVL release alone isn't sufficient for a Fiber to yield, and why plain thread-pool callers skip the thread spawn entirely. |
 | `lib/duckling/version.rb` | `Duckling::VERSION` constant — single source of truth for the gem version, read by `duckling.gemspec` and the release pipeline. |
 | `test/` | Minitest suite. `test_helper.rb` sets up the load path and requires `minitest/autorun`; test files follow `<name>_test.rb` / `class <Name>Test < Minitest::Test` naming. `test/gem/` is the exception on both counts — see its own row below. |
+| `test/support/` | Helpers required by `test_helper.rb`, not themselves test files (so outside the `*_test.rb` glob). `tz_capabilities.rb` holds the probes only the suite needs (see `Duckling::TZInfoCapabilities` under "Public and internal APIs" for why the split is by consumer); `tz_fixtures.rb` compiles `test/fixtures/tz/*.zi` into `tmp/tz-fixtures` with `zic`, and its `TZFixtures::Datasource` mixin swaps `TZInfo::DataSource` to them for the duration of each test in the including class (the datasource is process-global, so the `teardown` restore is mandatory, not hygiene). See "The tz-database axis" below. |
+| `test/fixtures/tz/` | `zic` source for the three synthetic zones (`Fixture/NegativeDst`, `Fixture/HalfHourGap`, `Fixture/LateGap`) plus the minimal `iso3166.tab`/`zone1970.tab` a zoneinfo directory needs to be recognized. Compiled at test time, never committed as binaries. |
+| `test/fixtures/zoneinfo-overrides/` | `zic` source for zones that `bin/build-stale-zoneinfo` compiles *over* a copy of the host's zoneinfo directory, rolling named zones back to earlier rules. Separate from `test/fixtures/tz/` on purpose: anything in that directory becomes a fixture-zone identifier, and the fixture datasource must expose only its own three. |
+| `test/capabilities/` | tz-capability-gated test files, one per probe in `TZCapabilities::CAPABILITIES`, named `<capability>_test.rb`. `test_helper.rb` loads a file only where its probe passes on the database in use, so these tests run wherever the capability exists and are absent where it doesn't. Excluded from the Rakefile's glob precisely so the gate can't be bypassed. See "The tz-database axis" below. |
+| `test/environments/` | Per-environment contracts, each a small `*_test.rb` invoked directly by the CI step that creates the environment (plain `ruby -Ilib -Itest`, the way `test/gem/` runs) — never loaded by the suite. Each asserts the environment's defining state positively, so a broken setup goes red instead of presenting as a smaller green suite. See "The tz-database axis" below. |
 | `test/gem/` | Two minitest suites that exercise a *built* or *installed* gem rather than this checkout's compiled extension. Neither requires `test_helper` and neither is in the default `test` glob (the `Rakefile` excludes the directory), because each needs a gem handed to it — see "Test guide" below for what each asserts and how to run it. |
 | `bin/` | Two kinds of scripts living side by side — see "bin/ scripts" below. Don't confuse the dev-workflow scripts (`worktree`, `check-worktree`, `claude-code-web-setup`, `lint`) with the gem's own build/test entrypoints (`setup`, `console`, `test`, `benchmark`, `benchmark-replay`). |
 | `benchmark/` | `benchmark-ips`-based suite exercising `Duckling.parse` (`parse_benchmark.rb`: ips + GC/allocation pressure + threaded-concurrency scenarios) and the environment-aware recording/reporting logic (`report.rb`: writes `docs/benchmarks/<environment>/<version>.json`, regenerates `docs/benchmarks/README.md`). `parse_benchmark.rb` tolerates `Duckling::Native` not existing (pre-issue-#64 implementations only defined `Duckling.parse` directly) by skipping the native-only scenarios — see `NATIVE_AVAILABLE` — since `bin/benchmark-replay` runs this harness against historical checkouts that may predate that split. Not part of what ships in the gem (excluded from packaging in `duckling.gemspec`) or of `task default:` (too slow/non-deterministic for every `bundle exec rake`). Run via `bin/benchmark` — see "Build and test commands" below. |
 | `docs/benchmarks/` | Per-environment, per-version benchmark history: `<environment>/<version>.json` raw results plus an auto-generated `README.md` (owned entirely by `DucklingBenchmark::Report.write_docs_readme!` — never hand-edited) with Mermaid charts comparing environments. `local` recordings are further bucketed by Ruby *minor* version (`local-3.3`, `local-3.4`, `local-4.0`, ...) since a dev machine's Ruby version drifts over a project's lifetime in a way CI runners' don't — see `Report.detect_environment`. Also holds `comparison-artifact-prompt.md`, a hand-maintained saved prompt (not auto-generated) for regenerating a richer interactive HTML cross-version comparison artifact than the README's latest-per-environment view supports — re-run it as new versions get recorded or `-rc` data changes. Committed to git but excluded from the packaged gem. Linked from the root `README.md`'s "Performance" section. |
+| `Gemfile` | Bundler deps beyond the gemspec's. `tzinfo-data` is declared here rather than in `duckling.gemspec`, and conditionally: `DUCKLING_TZINFO_DATA` unset installs the current version, `none` omits it (so tzinfo falls back to the host's zoneinfo), and a `X.Y…`-shaped value pins that exact version. Anything else raises, rather than reaching the resolver as an unsatisfiable constraint. Pair non-default values with `BUNDLE_LOCKFILE` — see "The tz-database axis" below. |
 | `Brewfile` | Homebrew deps for local macOS dev: `rust` (bundles `cargo`/`rustc`/`rustfmt`/`clippy`), `hk` (see `hk.pkl` below — local-dev-only, not installed in CI or remote/web sessions), and `gh` (GitHub CLI, used by `benchmark:record_pr` to open PRs — needs `gh auth login` before that task can push/open a PR). `bin/setup` runs `brew bundle` against it, then `hk install`, when Homebrew is present. |
-| `duckling.gemspec` | Gem spec. Declares `spec.extensions = ["ext/duckling/extconf.rb"]` (the native-extension build entrypoint), depends on `rb_sys` + `tzinfo`/`tzinfo-data` (the latter two back `reference_zone:` — see "Public and internal APIs") and dev-depends on `rake-compiler` + `benchmark-ips` — see the gemspec's `add_dependency`/`add_development_dependency` lines for the current version constraints. Packaged files come from `git ls-files`, excluding `bin/`, `Gemfile`, `.gitignore`, `.env.local.example`, `test/`, `.github/`, `.standard.yml`, `hk.pkl`, `benchmark/`, `docs/benchmarks/`, `cross_targets.rb`. |
-| `Rakefile` | `task default: %i[standard compile test]` — runs StandardRB lint, compiles the Rust extension, then Minitest. `test` also declares an explicit `task test: :compile` prerequisite (`Minitest::TestTask` has no built-in way to express this itself), so `bundle exec rake test` run in isolation still compiles first — not just `bundle exec rake` via the `default` array's ordering. Loads `.env.local` via `Dotenv.load` at the top (no-ops if absent, e.g. in CI); also defines an opt-in `:dev` task (not part of `default`) that sets `RB_SYS_CARGO_PROFILE=dev` directly — use `bundle exec rake dev compile test` for a one-off dev-profile build without `.env.local` in place. Also defines `benchmark` / `benchmark:record` / `benchmark:record_pr` (all deliberately excluded from `task default:`) — see "Build and test commands" below for how they relate. |
+| `duckling.gemspec` | Gem spec. Declares `spec.extensions = ["ext/duckling/extconf.rb"]` (the native-extension build entrypoint), depends on `rb_sys` + `tzinfo` (which backs `reference_zone:` — see "Public and internal APIs"; `tzinfo-data` is deliberately *not* a dependency, see "The tz-database axis") and dev-depends on `rake-compiler` + `benchmark-ips` — see the gemspec's `add_dependency`/`add_development_dependency` lines for the current version constraints. Packaged files come from `git ls-files`, excluding `bin/`, `Gemfile`, `.gitignore`, `.env.local.example`, `test/`, `.github/`, `.standard.yml`, `hk.pkl`, `benchmark/`, `docs/benchmarks/`, `cross_targets.rb`. |
+| `Rakefile` | `task default: %i[standard compile test]` — runs StandardRB lint, compiles the Rust extension, then Minitest. `test` also declares an explicit `compile` prerequisite (`Minitest::TestTask` has no built-in way to express one itself, and it must be a prerequisite rather than an extra `task :test do` block — rake *appends* actions, so a second block would run after the test subprocess had already exited), so `bundle exec rake test` run in isolation still compiles first — not just `bundle exec rake` via the `default` array's ordering. Loads `.env.local` via `Dotenv.load` at the top (no-ops if absent, e.g. in CI); also defines an opt-in `:dev` task (not part of `default`) that sets `RB_SYS_CARGO_PROFILE=dev` directly — use `bundle exec rake dev compile test` for a one-off dev-profile build without `.env.local` in place. Also defines `benchmark` / `benchmark:record` / `benchmark:record_pr` (all deliberately excluded from `task default:`) — see "Build and test commands" below for how they relate. |
 | `.env.local.example` | Tracked template for `.env.local` (gitignored) — sets `RB_SYS_CARGO_PROFILE=dev` so `bin/setup` (see below) makes the dev Cargo profile the local default. |
 | `.standard.yml` | StandardRB config — see its `ruby_version:` field for the Ruby version StandardRB targets. StandardRB wraps RuboCop internally; there is no separate `.rubocop.yml`. |
 | `hk.pkl` | `hk` config (StandardRB + rustfmt + clippy via `hk`'s builtin steps) — scoped to local dev only. `bin/setup` installs `hk` (via `Brewfile`) and runs `hk install` to wire up a `git commit` pre-commit hook from this config. Neither `bin/lint` (the cpb-harness PostToolUse hook) nor CI shell out to `hk` — both run the same underlying tools directly instead, since `hk`'s Pkl config needs to fetch its schema package from a GitHub release on every invocation, which isn't reliable in sandboxed/network-restricted environments (CI, remote/web sessions). **Git stash merge gotcha**: when resolving merge conflicts, `git stash` (used by `hk`'s pre-commit hook) unconditionally clears `.git/MERGE_HEAD`, which can silently downgrade a merge commit to a single-parent commit if any unstaged changes remain. **Workaround**: bypass the hook for merge-resolution commits with `HK=0 git commit ...` after manually running `standardrb --fix`/`rustfmt`/`cargo clippy --fix`. |
-| `.github/workflows/main.yml` | CI: runs StandardRB lint, cross-platform Rust checks (`cargo fmt --check`, `cargo clippy -- -D warnings` against `ext/duckling/`), then `bundle exec rake`. Split into two jobs: `baseline` (`name: "Ruby 3.3.6"`, hardcoded Ruby 3.3.6 + a Rust toolchain pinned to track the Claude Code Web sandbox — the only entry branch protection on `main` requires, matched by that exact `name` string) and `informational` (`needs: baseline`, a 3-entry matrix of forward-compat signals allowed to fail — Ruby 3.4, Ruby latest, Rust latest). Because `informational` declares `needs: baseline`, GitHub Actions automatically skips it when `baseline` fails, instead of always burning CI minutes running all 4 entries in parallel regardless of the baseline's outcome (see #98). Rename the `baseline` job's `name` without updating the required check in the same PR and merges silently have no required check at all. Runs for every push to `main` and every PR. |
+| `.github/workflows/main.yml` | CI: runs StandardRB lint, cross-platform Rust checks (`cargo fmt --check`, `cargo clippy -- -D warnings` against `ext/duckling/`), then `bundle exec rake`. Split into four jobs: `timezones` (`needs: baseline`, a 2-entry matrix covering the *stale* tz databases — see "The tz-database axis" below), `tz-containers` (`needs: baseline`, a 2-entry matrix of containerized tz environments no runner image provides — Debian + `tzdata-legacy` for system zoneinfo *with* the backward-compat links, and Alpine for vanguard modelling, which doubles as the suite's only musl source-build coverage; each leg is both a tz environment and a source build, which is what its name says, and the environment contract is what tells a changed tz answer from a toolchain break), `baseline` (`name: "Ruby 3.3.6"`, hardcoded Ruby 3.3.6 + a Rust toolchain pinned to track the Claude Code Web sandbox — the only entry branch protection on `main` requires, matched by that exact `name` string; it carries the three tz environments that must gate a merge — current `tzinfo-data`, then the host's zoneinfo, then the host's zoneinfo with the backward-compat links stripped — as extra steps rather than as matrix entries, specifically because `baseline` is the only required check) and `informational` (`needs: baseline`, a 3-entry matrix of forward-compat signals allowed to fail — Ruby 3.4, Ruby latest, Rust latest). Because every one of those seven matrix entries declares `needs: baseline`, GitHub Actions automatically skips them when `baseline` fails, instead of always burning CI minutes running them all in parallel regardless of the baseline's outcome (see #98). **Only `baseline` gates a merge, but `timezones` and `tz-containers` gate a release**: `release.yml` runs this workflow as its `ci` reusable-workflow job and `cross_gems`/`benchmark`/`publish` all `needs: ci`, and a reusable-workflow job succeeds only if every job in the called workflow does — so a stale-vintage disagreement or a musl/trixie build break holds a publish without holding a merge. Those container legs are also the only release-gating jobs that reach external package repositories at release time. Rename the `baseline` job's `name` without updating the required check in the same PR and merges silently have no required check at all. Runs for every push to `main` and every PR. |
 | `.github/workflows/release.yml` | Tag-triggered release workflow. Gates on CI, then runs cross-compilation and benchmarking in parallel. Builds the `ruby` source gem and pushes it with `x86_64-linux`/`x86_64-darwin`/`arm64-darwin`/`aarch64-linux` binary gems to RubyGems, then cuts a GitHub release. See "Gem release conventions" below. |
 | `cross_targets.rb` | Single source of truth for what the precompiled gems are built for: `RUBY_ABIS`, `PLATFORMS` (each platform's expected `file(1)` architecture and a runner label that can execute it), and the `required_ruby_version` ceiling those ABIs imply. Read by the `Rakefile`, both `test/gem/` suites, and `test/duckling_ci_test.rb`. `cross-gem.yml` is the one consumer that can't read it — YAML has no way to require Ruby — so it restates the matrix and `test/duckling_ci_test.rb` fails when the copy drifts. Excluded from the packaged gem. |
 | `.github/workflows/cross-gem.yml` | Reusable workflow that cross-compiles the native extension for `x86_64-linux`, `x86_64-darwin`, `arm64-darwin`, and `aarch64-linux` via Docker containers bundling their own Rust + cross-toolchain. Called from `release.yml` for releases; trigger manually with `gh workflow run cross-gem.yml --ref <branch>` to exercise cross-compilation. Two jobs: `cross_gems` builds each platform's fat gem and ends in a "Verify gem metadata and architecture" step running `ruby test/gem/packaged_gem_test.rb`; `smoke` (`needs: cross_gems`) then installs each gem on a real runner for that platform (`ubuntu-latest`, `ubuntu-24.04-arm`, `macos-15-intel`, `macos-latest`) once per Ruby ABI and runs `ruby test/gem/installed_gem_test.rb`. `smoke` is the only place a built gem is loaded and called; an ABI mismatch passes every metadata check and fails on the first call, so nothing earlier in the pipeline can catch it. Because `release.yml` needs the whole workflow, `smoke` gates publishing. |
@@ -53,7 +59,7 @@ If you notice this file describing a not-yet-built piece as current, or vice ver
 
 - **`bin/setup`** — runs `brew bundle` (installing the Rust toolchain and `hk` per `Brewfile`) and `hk install` (wiring up the local `git commit` pre-commit hook from `hk.pkl`) when Homebrew is present, then `bundle install`, then (if `.env.local` doesn't already exist, and `CI` isn't `true`) copies `.env.local.example` to `.env.local`, which sets `RB_SYS_CARGO_PROFILE=dev`. No-ops the Homebrew step gracefully on machines without `brew` (e.g. CI runners and remote/web sessions, which never install or need `hk` — see `hk.pkl` above), and skips the `.env.local` seed entirely in CI regardless (which always wants the release profile). Run this first in a fresh checkout/worktree.
 - **`bin/console`** — loads the gem and drops you into IRB for interactive experimentation.
-- **`bin/test [file:line]`** — routes through `bundle exec rake test` (not a raw `ruby -I test` invocation), so the Rakefile's `task test: :compile` prerequisite guarantees the extension is compiled first. `Minitest::TestTask` takes no CLI args directly, so arguments are "massaged" into the env vars it reads: a single `path/to/file.rb:LINE` ref (the `bin/worktree heal-reproduce` contract) is resolved to the nearest preceding `def test_*` method at/above that line and passed as `N=<name>` (`-i`/`--include`, exact method-name match); anything else passes through verbatim as `A="..."` (raw extra args, e.g. `-i test_foo`, `-v`, `--seed 123`). With no arguments, runs the full suite via `bundle exec rake` instead. In a remote Claude Code Web session (`CLAUDE_CODE_REMOTE=true`), it first JIT-installs gems via `bin/claude-web-deps.sh` (compiling the extension is no longer needed here — `bundle exec rake test` compiles it via the `:compile` prerequisite), since a bare Bash call doesn't trigger the Edit/Write-gated `bin/claude-code-web-setup` PreToolUse hook.
+- **`bin/test [file:line]`** — routes through `bundle exec rake test` (not a raw `ruby -I test` invocation), so the Rakefile's `compile` prerequisite on `test` guarantees the extension is compiled first. `Minitest::TestTask` takes no CLI args directly, so arguments are "massaged" into the env vars it reads: a single `path/to/file.rb:LINE` ref (the `bin/worktree heal-reproduce` contract) is resolved to the nearest preceding `def test_*` method at/above that line and passed as `N=<name>` (`-i`/`--include`, exact method-name match); anything else passes through verbatim as `A="..."` (raw extra args, e.g. `-i test_foo`, `-v`, `--seed 123`). With no arguments, runs the full suite via `bundle exec rake` instead. In a remote Claude Code Web session (`CLAUDE_CODE_REMOTE=true`), it first JIT-installs gems via `bin/claude-web-deps.sh` (compiling the extension is no longer needed here — `bundle exec rake test` compiles it via that prerequisite), since a bare Bash call doesn't trigger the Edit/Write-gated `bin/claude-code-web-setup` PreToolUse hook.
 - **`bin/lint`** — the cpb-harness PostToolUse hook, invoked after every Edit/Write with `$CLAUDE_FILE_PATHS`, including in remote/web sessions. Splits the changed paths by extension and auto-fixes them directly with the same tools CI runs (`bundle exec standardrb --fix` for `.rb` files, `rustfmt` + `cargo clippy --fix` against `ext/duckling/Cargo.toml` for `.rs` files) — it does not shell out to `hk` (see `hk.pkl` above), so no `hk` provisioning is needed for this hook to work anywhere, including remote/web sessions. Requires `standardrb` (via `bundle install`) and `rustfmt`/`cargo clippy` (rustup components) on `PATH`.
 - **`rake` / `bundle exec rake`** — default task: `standard` (StandardRB lint) + `compile` (builds the Rust extension via `RbSys::ExtensionTask`) + `test` (Minitest).
 - **Compiling the native extension**: `rake compile` (via `RbSys::ExtensionTask`, wired in the `Rakefile`) builds `ext/duckling/` and places the compiled artifact under `lib/duckling/`. After `bin/setup` has run, this builds Cargo's `dev` profile locally (faster compile, slower runtime) because `.env.local` sets `RB_SYS_CARGO_PROFILE=dev` and the Rakefile loads it via `Dotenv.load(".env.local")`. `.env.local` is gitignored and never present in CI, so `bundle exec rake` in CI (`main.yml`) and `rake release` always build the optimized `release` profile regardless of this.
@@ -70,20 +76,32 @@ If you notice this file describing a not-yet-built piece as current, or vice ver
 ## Public and internal APIs
 
 - **`Duckling.parse(text, locale: "en", dims: ["time"], reference_time: nil, with_latent: false, reference_zone: nil)`** — the public Ruby API. This is a thin wrapper around `Duckling::Native.parse` that conditionally dispatches through `Thread.new { ... }.value` when a `Fiber.scheduler` is installed on the calling thread (important for async frameworks like Falcon). Plain thread-pool callers skip the thread spawn. It also has two real behavioral differences from `Native.parse`, not just dispatch details: it coerces `reference_time:` via `#to_time` before it reaches `Native.parse` (see below), and it implements `reference_zone:` entirely on the Ruby side.
-- **`reference_zone:`** — an IANA zone name String (e.g. `"America/New_York"`), resolved via `tzinfo`/`tzinfo-data` (both runtime gemspec dependencies). It never crosses into `Native.parse`: the wrapped Rust crate has no zone concept, only the single `FixedOffset` it derives from `reference_time:`, so per-date-correct (DST-aware) offsets have to come from a real tz database on the Ruby side. `Duckling.parse` applies it as a two-part step around the native call — before, it validates the zone (unknown identifier → `ArgumentError`) and, when `reference_time:` is also given, requires that `reference_time:`'s fixed `utc_offset` agree with the zone's real offset at that instant (disagreement → `ArgumentError`, since silently preferring either would resolve results against an offset the caller never asked for). After, `Duckling.apply_reference_zone` re-anchors each `Naive` leaf's wall-clock fields in the zone, so a leaf's offset reflects *its own date* rather than one offset applied uniformly. A **primary** wall-clock (a `Single`'s `value`, or an `Interval`'s `from`/`to`) and a generated **recurrence** entry (a `values` element — and note *every* `Single` carries a populated `values` array, not just explicit recurrences) that a spring-forward gap skipped or a fall-back overlap made ambiguous are resolved identically — there's no benefit to raising over one and not the other, whether the value is caller-named or parser-generated. Both resolve deterministically — a gap shifts the wall clock forward by the transition's delta (2:30am on a US spring-forward day becomes 3:30am EDT), an overlap takes the first (pre-transition) occurrence. This matches `ActiveSupport::TimeZone#parse`/`#local` for typical zones, with two deliberate departures where Rails gets edge zones wrong: the gap shift uses the transition's real width rather than a hardcoded hour (Australia/Lord_Howe's 30-minute gap), and the overlap's "first occurrence" is selected by position rather than tzinfo's dst flag, which inverts for negative-DST zones (Europe/Dublin models winter GMT as its `dst?`-true period) — see `local_time_in_zone`/`gap_delta` in `lib/duckling.rb`. Shifting the gap forward, rather than keeping its wall clock and stamping the post-transition offset on it, is what keeps the resolved `Time`'s instant and its rendered local time in agreement: `02:30 -04:00` is `06:30Z`, and New York still observes EST at `06:30Z`. Given *without* `reference_time:`, `reference_zone:` only reinterprets result offsets after the fact — it does not anchor the parse, so relative expressions ("tomorrow") still anchor on the machine-local clock, not "now" in that zone (pass a `reference_time:` in the zone to anchor as well). `Instant` leaves are deliberately left untouched — their relative arithmetic already collapsed against one `FixedOffset` inside the wrapped crate, and that imprecision is out of scope (issue #83).
+- **`reference_zone:`** — an IANA zone name String (e.g. `"America/New_York"`), resolved via `tzinfo` (a runtime gemspec dependency; `tzinfo-data` is not, so *which* tz database answers is a property of the consumer's environment — see "The tz-database axis" below). It never crosses into `Native.parse`: the wrapped Rust crate has no zone concept, only the single `FixedOffset` it derives from `reference_time:`, so per-date-correct (DST-aware) offsets have to come from a real tz database on the Ruby side. `Duckling.parse` applies it as a two-part step around the native call — before, it validates the zone (unknown identifier → `ArgumentError`) and, when `reference_time:` is also given, requires that `reference_time:`'s fixed `utc_offset` agree with the zone's real offset at that instant (disagreement → `ArgumentError`, since silently preferring either would resolve results against an offset the caller never asked for). After, `Duckling.apply_reference_zone` re-anchors each `Naive` leaf's wall-clock fields in the zone, so a leaf's offset reflects *its own date* rather than one offset applied uniformly. A **primary** wall-clock (a `Single`'s `value`, or an `Interval`'s `from`/`to`) and a generated **recurrence** entry (a `values` element — and note *every* `Single` carries a populated `values` array, not just explicit recurrences) that a spring-forward gap skipped or a fall-back overlap made ambiguous are resolved identically — there's no benefit to raising over one and not the other, whether the value is caller-named or parser-generated. Both resolve deterministically — a gap shifts the wall clock forward by the transition's delta (2:30am on a US spring-forward day becomes 3:30am EDT), an overlap takes the first (pre-transition) occurrence. This matches `ActiveSupport::TimeZone#parse`/`#local` for typical zones, with two deliberate departures where Rails gets edge zones wrong: the gap shift uses the transition's real width rather than a hardcoded hour (Australia/Lord_Howe's 30-minute gap), and the overlap's "first occurrence" is selected by position rather than tzinfo's dst flag, which inverts for negative-DST zones (Europe/Dublin models winter GMT as its `dst?`-true period) — see `local_time_in_zone`/`gap_delta` in `lib/duckling.rb`. Shifting the gap forward, rather than keeping its wall clock and stamping the post-transition offset on it, is what keeps the resolved `Time`'s instant and its rendered local time in agreement: `02:30 -04:00` is `06:30Z`, and New York still observes EST at `06:30Z`. Given *without* `reference_time:`, `reference_zone:` only reinterprets result offsets after the fact — it does not anchor the parse, so relative expressions ("tomorrow") still anchor on the machine-local clock, not "now" in that zone (pass a `reference_time:` in the zone to anchor as well). `Instant` leaves are deliberately left untouched — their relative arithmetic already collapsed against one `FixedOffset` inside the wrapped crate, and that imprecision is out of scope (issue #83).
 - **`Duckling.apply_reference_zone(entities, reference_zone)`** — walks the `Single`/`Interval` tagged shape described under "Entity `:value` shapes" below, reinterpreting a `Single`'s `value` and every `values` recurrence entry, or an `Interval`'s `from`/`to` and every `values` endpoint pair's own `from`/`to` (an `Interval` leg is `Option<TimePoint>` in Rust, and serde emits `None` as a present key holding `nil`). It raises a `Duckling::ShapeError` (a named `RuntimeError` subclass — named, not bare, so it's greppable and can't be satisfied by the unrelated native-panic `RuntimeError`; mirrors `internal_error()` in `lib.rs`) on any tag it doesn't recognize at either the `TimeValue` or `TimePoint` layer: this shape must stay in lockstep with `patch_time_value` in `ext/duckling/src/lib.rs`, so a future drift there fails loudly instead of quietly returning results resolved against the wrong offset.
 - **`Duckling::Native.parse(...)`** — the raw Magnus/native entrypoint. Called directly by `Duckling.parse` and by benchmarks. Releases the GVL around the underlying Rust parse call. Its Magnus binding only accepts a strict `kind_of?(Time)` for `reference_time:` — passing an `ActiveSupport::TimeWithZone`, stdlib `DateTime`, or anything else that merely responds to `#to_time` raises a `TypeError`; `Duckling.parse` is what makes those work by coercing first (`lib/duckling.rb`).
 - **Entity `:value` shapes**: every entity hash carries `:body`/`:start`/`:end`/`:dim`/`:latent` plus a `:value` whose shape depends on the dimension. Every dimension, including `:time` (issue #91), gets its `:value` via the same generic-serialize-then-patch pattern: `serde_magnus` serializes the crate's `DimensionValue` and all Hash keys are symbolized in place (`ext/duckling/src/ruby_value.rs`), preserving serde's externally-tagged representation verbatim — the PascalCase tag key is kept uniformly at every enum layer (a deliberate choice: one consistent tagged shape rather than a mix of unwrapped and tagged layers). Resulting shapes: tagged scalars for number (`{Numeral: Float}`), ordinal (`{Ordinal: Integer}`), email/phone-number (`{Email:/PhoneNumber: String}` — normalized, separators stripped); tagged symbol-keyed Hashes for url (`{Url: {value:, domain:}}`), credit-card-number (`{CreditCardNumber: {value:, issuer:}}` — number normalized), duration (`{Duration: {value:, grain:, normalized_seconds:}}`), quantity (`{Quantity: {measurement:, product:}}` — `product` is an explicit `nil` when absent, serde emits `Option::None` as a present key); grain symbols (`:second`, `:no_grain`, …) for time-grain's payload (`{TimeGrain: :second}`) and duration's `:grain`, patched from serde's raw PascalCase variant names to match Time's `Grain::as_str()` convention. The five measurement dimensions (temperature, distance, volume, quantity's `:measurement`, amount-of-money) nest serde's `MeasurementValue` tag the same way: `{Temperature: {Value: {value:, unit:}}}` or `{AmountOfMoney: {Interval: {from: {value:, unit:}, to: {value:, unit:}}}}`. `:time` needs the deepest patching of the bunch, since `serde_magnus` has no escape hatch to emit a real Magnus `Time` mid-serialization (confirmed against `serde_magnus`'s `Serializer` impl — every method bottoms out in a primitive `serialize_*` call): `patch_time_value`/`patch_time_point` (`ext/duckling/src/lib.rs`) walk the generically-serialized `{Time: {Single: {value: {Naive:|Instant: {value:, grain:}}, values: [...], holidayBeta:}}}` / `{Time: {Interval: {from:, to:, values: [...]}}}` tree, using the already-typed `TimeValue`/`TimePoint` the serialization came from to overwrite every datetime leaf with a genuine Ruby `Time` (running `resolve_naive`'s reference-offset resolution for `Naive`, direct `IntoValue` for `Instant`) and every `grain` leaf with `Grain::as_str()`'s lowercase-snake_case symbol — `holidayBeta` and the rest of the structural shape pass through untouched.
+- **`Duckling::TZDataUnavailable`** — raised when `reference_zone:` is given on a host with neither zoneinfo files nor `tzinfo-data` (a scratch or distroless container). Only reachable since the `tzinfo-data` dependency was dropped; before that a datasource always existed. Deliberately *not* an `ArgumentError` — it is an environment fault, and a caller validating user input by rescuing `ArgumentError` around `reference_zone:` shouldn't swallow "this deployment can't resolve any zone". Named for the same reason as `ShapeError`.
+- **`Duckling::TZInfoCapabilities`** (`lib/duckling/tzinfo_capabilities.rb`) — describes which tz database `reference_zone:` resolved against, for `timezone_for`'s unknown-identifier error: `backward_compat_links?`, `identifier_count`, `datasource_description`, and the `unknown_identifier_diagnosis` that composes them. Behavioral because neither datasource exposes a version — `RubyDataSource` has no `version_info`, `ZoneinfoDataSource` offers only `zoneinfo_dir`. **Split by consumer, not by topic**: the suite discriminates the databases along more axes (`models_negative_dst?`, `greenland_2023_rules?`, `supports?`, `CAPABILITIES`), and those live in `test/support/tz_capabilities.rb` because `lib/` ships to every consumer and `test/` does not — a probe with no production caller has no business in the gem. `backward_compat_links?` is needed on both sides, so production owns it and the test module delegates. Nothing is memoized — `TZInfo::DataSource.set` can swap the database mid-process, and the fixture-zone tests do. Internal, not documented as public API.
+- **`unknown_identifier_diagnosis`'s remedy clause is phrased as a condition, not a claim.** It fires on a property of the *database* (no backward-compat links), which says nothing about whether the identifier the caller passed is one of the ~100 in IANA's `backward` file. Asserting "backward-compat names such as this one" would tell every typo on a links-less host that `tzdata-legacy` supplies it; shipping the list to decide properly would be worse, since a name the list missed would get no remedy at all. `test_reference_zone_error_offers_the_backward_compat_remedy_only_where_relevant` pins it by requiring the hedge (`"if that is what this is"`) to be present and the caller's identifier to be absent from the remedy clause — positively, because forbidding one claim-shaped phrasing only rules out the wording nobody would reach by accident.
 - **`Duckling::PanickingNativeFake`** — test-only mock for testing panic propagation. Not part of the public API; never use in production code.
 
+## The tz-database axis
+
+This gem depends on `tzinfo`. It deliberately does not depend on `tzinfo-data`. Which tz database answers `reference_zone:` is therefore a property of the consumer's environment, and the databases disagree: modelling (negative DST), backward-compat links, and vintage. A suite run cannot observe which database it ran against, so the coverage rests on four mechanisms: environments (`DUCKLING_TZINFO_DATA`, `DUCKLING_ZONEINFO_DIR`, `BUNDLE_LOCKFILE`), behavioral probes, capability-gated tests (`test/capabilities/`), and environment contracts (`test/environments/`).
+
+**See [docs/tz-database-axis.md](docs/tz-database-axis.md) for the full reference**: the drift axes, the seven CI environments and their gating, the probe rules, the error-message rules, the fixture zones, the build scripts, `expect_failure`, and how to run an environment locally. When you change any of those, update that doc in the same PR.
+
 ## Test guide
 
 The test suite covers several distinct concerns:
 
-- **API shape, `reference_time:`, and `reference_zone:` behavior**: `test/duckling_test.rb` (parse result/interval shape, `reference_time:` coercion and type-checking, and `reference_zone:`'s DST-transition/gap/interval-leg/zone-mismatch/unrecognized-shape cases — see "Public and internal APIs" below).
+- **API shape, `reference_time:`, and `reference_zone:` behavior**: `test/duckling_test.rb` (parse result/interval shape, `reference_time:` coercion and type-checking, and `reference_zone:`'s DST-transition/gap/interval-leg/zone-mismatch/unrecognized-shape cases — see "Public and internal APIs" below). `test_reference_zone_error_names_the_tz_datasource` runs on every environment — the diagnosis has to be right about whichever database is present, not just the impoverished one. The three database-dependent cases live in `test/capabilities/`: the `America/Nuuk` late-in-the-day gap, the `Europe/Dublin` negative-DST overlap, and the `US/Eastern` backward-compat lookup.
+- **tz-capability-gated tests**: `test/capabilities/` — one file per probe, loaded only where the database in use can answer (see "The tz-database axis" above). A file run directly by hand runs regardless of the probe, which is how you exercise one against a database that lacks the capability.
+- **Environment contracts**: `test/environments/` — one small file per synthesized/pinned environment, invoked by its CI step rather than by the suite. Each asserts the environment's defining state positively, so a broken setup goes red instead of presenting as a smaller green suite.
+- **DST edges against synthetic zones**: `test/duckling_tz_fixture_test.rb` (`Fixture/NegativeDst`'s overlap-by-position, `Fixture/HalfHourGap`'s sub-hour gap width, `Fixture/LateGap`'s transition past the next UTC midnight). Swaps `TZInfo::DataSource` in `setup`/`teardown` — the datasource is process-global, so the restore is mandatory. This is the coverage that holds on every environment; see "The tz-database axis" above.
 - **Time-expression corpus**: `test/duckling_parse_time_basic_test.rb`, `test/duckling_parse_time_dates_test.rb`, `test/duckling_parse_time_interval_test.rb`, `test/duckling_parse_time_relative_test.rb`, `test/duckling_parse_time_weekdays_test.rb` — one file per expression category, ported from wafer-inc-duckling's own Rust corpus and the pyduckling suite it descends from.
 - **Locale and latent-entity keyword args**: `test/duckling_parse_locale_test.rb` (`locale:` validation/defaulting), `test/duckling_parse_latent_test.rb` (`with_latent:` behavior).
-- **Known upstream limitations**: `test/duckling_comma_list_test.rb` (characterizes a bare comma-separated `<time>, <time>` run collapsing into a single entity and silently dropping the rest — a wafer-inc-duckling grammar limitation, not a bug in this wrapper).
+- **Known upstream limitations**: `test/duckling_comma_list_test.rb` (characterizes a bare comma-separated `<time>, <time>` run collapsing into a single entity and silently dropping the rest — a wafer-inc-duckling grammar limitation, not a bug in this wrapper) and the Monday pair in `test/duckling_parse_time_weekdays_test.rb`. These use `expect_failure` (`test_helper.rb`): the correct-behavior assertions run for real, report as skips while the limitation stands, and flunk the moment it stops reproducing.
 - **Non-Time dimension `:value` shapes**: `test/duckling_parse_dimensions_test.rb` (one representative case per non-Time dimension, pinning the exact shapes described under "Public and internal APIs" — these are also the tests that would catch a serde-representation drift in a future wrapped-crate upgrade).
 - **GC safety under stress**: `test/duckling_gc_stress_test.rb` (`GC.stress = true` across every dimension's conversion path; 2 passes by default to stay `bundle exec rake`-friendly, `DUCKLING_GC_STRESS_ITERATIONS=20` reproduces the full ~300-call verification).
 - **Native-extension infrastructure sanity**: `test/duckling_ci_test.rb` (build config files exist and are shaped correctly, and `cross-gem.yml`'s restatement of the build matrix — its ABI list, both platform matrices, and its runner labels — still agrees with `cross_targets.rb`).
@@ -123,7 +141,7 @@ The test suite covers several distinct concerns:
 - **Known gotchas**:
   - `rb_sys` is a *runtime* gemspec dependency because the source gem builds its extension at install time and `ext/duckling/extconf.rb` requires `rb_sys/mkmf` — RubyGems has no build-only dependency kind, so a development dependency would come too late. It is not loaded when the gem is used: `lib/duckling.rb` requires only `tzinfo` and the compiled extension. rb-sys's own `cross_compiling` hook (`rb_sys/extensiontask.rb`) therefore strips `rb_sys` from every precompiled gem's dependency list — verify with `gem spec <native gem> dependencies` if that ever looks suspect.
   - CI installs Rust via `dtolnay/rust-toolchain` and pins the version to track the Claude Code Web sandbox. Update `.github/workflows/main.yml`'s "Set up Rust" step when the sandbox image's Rust version changes.
-  - Third-party GitHub actions are pinned to full commit SHAs with version comments (e.g. `actions/checkout@<sha> # vX.Y.Z`), not floating tags. `.github/dependabot.yml` opens PRs to bump these pins.
+  - Third-party GitHub actions are pinned to full commit SHAs with version comments (e.g. `actions/checkout@<sha> # vX.Y.Z`), not floating tags. `.github/dependabot.yml` opens PRs to bump these pins. Container images in `tz-containers` follow the same rule for the same reason — a floating `ruby:3.4-alpine` rebases across Alpine releases, which can drop the versioned `clang22-*` packages that leg installs *and* move the host tz data a leg asserts against, both with no change in this repo.
   - Cross-compiling locally (`rake 'native_gem[<platform>]'`) requires Docker.
 
 ## Gem release conventions
@@ -137,21 +155,33 @@ The test suite covers several distinct concerns:
   4. Build the `ruby` source gem.
   5. Push every built gem — the source gem plus one per cross-compiled platform — to RubyGems via `gem push` (the workflow globs `pkg/*.gem`, so this needs no update when the platform matrix changes).
   6. Create a GitHub release with all of those gems attached.
-  7. Open and auto-merge a PR to update `CHANGELOG.md` (post-release documentation).
+  7. Open and auto-merge a PR to update `CHANGELOG.md` (post-release documentation). **It inserts a generated `## [X.Y.Z]` section immediately below `## [Unreleased]`, built from the GitHub release notes — it does not promote whatever is already under `## [Unreleased]`.** So hand-written entries staged there stay under "Unreleased" after the tag, with the generated section sitting above them. Whoever tags a release has to promote the hand-written section first (or merge the two afterwards); nothing in the pipeline does it.
   8. In parallel with the release publish path after CI, record benchmark data for this release under `docs/benchmarks/github-actions/` and open/auto-merge that PR.
 - **Tag protection**: `v*.*.*` tags can only be created/updated by repo admins. Configured via `.github/scripts/apply-tag-ruleset.sh`.
 - **Before a release**: test cross-compilation locally or via `gh workflow run cross-gem.yml --ref <branch>` — that dispatch runs the `smoke` job too, so it is the cheapest full rehearsal of what `release.yml` will publish. To rehearse one gem by hand (a Heroku-shaped, Rust-free install), download the artifact and run `test/gem/installed_gem_test.rb` against it in a plain Ruby container — see that file's own header for the one-liner. Capture additional benchmark data points from other environments via `gh workflow run benchmark.yml --ref <branch>` (adds `docs/benchmarks/<environment>/` data) or locally via `bin/benchmark` (see "Build and test commands" above). **`benchmark.yml` has real side effects even when dispatched ad hoc**: it always branches off `origin/main`, commits/pushes, and opens+auto-merges a PR (`bundle exec rake benchmark:record_pr`) — it is not read-only data capture.
 
-## `bin/` scripts (dev-workflow tooling, not part of the gem)
+## `bin/` scripts (dev-workflow tooling; the gem ships none of them)
 
 These come from the cpb Claude Code plugin's harness (commit `d69ba38`) and manage git worktrees / tmux / GitHub PR workflow for *this development environment* — they are not part of what ships in the gem and shouldn't be touched when working on the gem's actual functionality:
 
+Two exceptions *are* part of the gem's own test tooling, both building a zoneinfo directory no runner is in the state of — see "The tz-database axis" above:
+
+- `bin/build-stale-zoneinfo <output-dir>` copies the host's zoneinfo directory and compiles `test/fixtures/zoneinfo-overrides/*.zi` over it, rolling named zones back to earlier rules.
+- `bin/build-linkless-zoneinfo <output-dir>` copies it and removes the top-level backward-compat entries, so `US/Eastern` stops resolving. Its keep-list is transcribed from a real links-less host rather than guessed, and it hard-fails if `US/Eastern` survives the strip — a leg that silently stopped covering its own subject is the failure mode it exists to prevent. It does not reproduce the ~60 in-region aliases `tzdata-legacy` also owns (`Europe/Kiev` and friends), which are indistinguishable inside a region directory from aliases a stock host keeps, so the tree exposes a few more identifiers than a stock host's.
+
 - `bin/worktree` — large CLI (`add`, `cd`, `harness`, `cleanup`, `heal-poll`, etc.) for creating per-issue git worktrees and driving Claude/Gemini sessions in tmux.
 - `bin/check-worktree` — PreToolUse hook that blocks `Edit`/`Write` when on the `main` branch, steering you toward `bin/worktree add <branch>` instead.
-- `bin/claude-code-web-setup` — PreToolUse hook for remote/web Claude Code sessions. Before each `Edit`/`Write`, just-in-time installs gems (`bundle install`) and compiles the native extension (`bundle exec rake compile`) — each step cached via receipt files in `tmp/claude-web-receipts/` so it's a no-op after the first call per session. Does not provision `hk`: `bin/lint` (see above) calls the underlying lint tools directly, so remote sessions never need `hk` installed — it's local-dev-only (see `hk.pkl`/`Brewfile` above). The gems/extension installers live in `bin/claude-web-deps.sh` (sourced, not directly executable); `bin/test` shares its `install_gems` installer (called unconditionally, any-args or no-args) since Bash tool calls don't trigger this Edit/Write-gated hook — `bin/test` no longer needs `compile_extension` itself, since `bundle exec rake test`'s `:compile` prerequisite handles that.
+- `bin/claude-code-web-setup` — PreToolUse hook for remote/web Claude Code sessions. Before each `Edit`/`Write`, just-in-time installs gems (`bundle install`) and compiles the native extension (`bundle exec rake compile`) — each step cached via receipt files in `tmp/claude-web-receipts/` so it's a no-op after the first call per session. Does not provision `hk`: `bin/lint` (see above) calls the underlying lint tools directly, so remote sessions never need `hk` installed — it's local-dev-only (see `hk.pkl`/`Brewfile` above). The gems/extension installers live in `bin/claude-web-deps.sh` (sourced, not directly executable); `bin/test` shares its `install_gems` installer (called unconditionally, any-args or no-args) since Bash tool calls don't trigger this Edit/Write-gated hook — `bin/test` no longer needs `compile_extension` itself, since `bundle exec rake test`'s compile prerequisite handles that.
 
 ## Code comment conventions
 
+Inline comments are kept to the bare minimum. Anything longer than a line or
+two belongs in a central doc under `docs/` (for example
+[docs/tz-database-axis.md](docs/tz-database-axis.md)), with at most a
+one-line pointer left inline. All code comments and documentation are written
+in ASD-STE100 Simplified Technical English: short sentences, active voice,
+one idea per sentence, approved vocabulary, no idioms.
+
 Comments (in Ruby, Rust, and this file) are long-lived documentation, not a
 transcript of the PR or session that wrote them. Prefer explaining the
 durable *why* — the invariant, constraint, or measured behavior a future

data/CHANGELOG.md

@@ -8,6 +8,61 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ### Changed
 
+- **On a stock Debian/Ubuntu host, roughly a hundred IANA zone identifiers
+  stop resolving.** `reference_zone: "US/Eastern"` — and every other
+  backward-compatibility name, such as `"US/Pacific"`, `"Europe/Kiev"`, or
+  `"Japan"` — now raises `ArgumentError` there. Those names live in the
+  `tzdata-legacy` system package, which is not installed by default. Two ways
+  to get them back, either of which restores the previous behavior exactly:
+
+  ```ruby
+  gem "tzinfo-data"   # in your Gemfile
+  ```
+  ```bash
+  apt install tzdata-legacy   # on the host
+  ```
+
+  Canonical identifiers (`"America/New_York"`, `"Europe/Kyiv"`) are
+  unaffected. A host with no zoneinfo files at all — a scratch or distroless
+  container — needs the gem for `reference_zone:` to work at all.
+
+  The error message names the tz database that answered, how many identifiers
+  it has, and both remedies, so this is distinguishable from a typo. The
+  datasource and the count describe whichever database answered on your host,
+  so both differ from the example below:
+
+  ```
+  invalid reference_zone: "US/Eastern" (resolved against system zoneinfo at
+  /usr/share/zoneinfo, which provides 497 identifiers; this database has no
+  backward-compat names (US/Eastern and ~100 others), so if that is what this
+  is, it needs either the tzinfo-data gem or the tzdata-legacy system package)
+  ```
+
+  The remedy is worded as a condition rather than a claim about the name you
+  passed: whether a given identifier is one of the ~100 in IANA's `backward`
+  file isn't knowable without shipping that list, and asserting it would tell
+  every typo on such a host that `tzdata-legacy` will supply it.
+
+  A second, quieter difference comes with the same change: some distributions
+  compile tzdata in *rearguard* format, which strips negative DST, and on such
+  a host `Europe/Dublin` is modelled as an ordinary positive-DST zone rather
+  than a negative-DST one. Which distributions is not guessable — Ubuntu 24.04
+  is rearguard, Debian trixie is vanguard — so if you depend on tzinfo's
+  `dst?` flag, read it from the host rather than assuming. Resolved offsets
+  are the same either way, so no `Duckling.parse` result changes because of
+  it.
+
+- `tzinfo-data` is no longer a runtime dependency. `tzinfo` already prefers
+  that gem when it is installed and falls back to the host's zoneinfo files
+  otherwise, so depending on it forced bundled tz data on every consumer to
+  serve the ones who want it. This is the change that produces the identifier
+  behavior above. Consumers who add `gem "tzinfo-data"` themselves get exactly
+  the previous behavior with no code change, and can still pick up a
+  tz-database revision by bumping that one gem. Dropping it means the bundled
+  tz data is no longer loaded at boot, so the first zone lookup does less
+  work; steady-state parsing is unaffected either way, since `reference_zone:`
+  resolution goes through the same tzinfo call once a database is loaded.
+
 - **Breaking:** `reference_time:` now requires a Ruby `Time` object (or
   `nil`), not a Unix-seconds Integer. This lets the caller's `utc_offset` be
   preserved into offset-aware `Instant` results (e.g. `"in one hour"`),
@@ -40,6 +95,18 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
   entirely — check `interval[:to].nil?` rather than `interval.key?(:to)`
   to detect an unbounded endpoint.
 
+### Added
+
+- `Duckling::TZDataUnavailable`, raised when `reference_zone:` is given on a
+  host with no tz database at all — no zoneinfo files and no `tzinfo-data`
+  gem, as in a scratch or distroless container. Newly reachable because of the
+  dependency change above; previously a database always existed. It names both
+  fixes, where the underlying tzinfo error mentioned neither this gem nor
+  `reference_zone:`. Deliberately not an `ArgumentError`: it reports the
+  deployment's state, not a bad argument, so code rescuing `ArgumentError`
+  around caller-supplied zone names does not swallow it. Every other keyword
+  works without a tz database.
+
 ## [0.2.0] - 2026-07-01
 
 ## What's Changed

data/README.md

@@ -33,7 +33,7 @@ Duckling.parse("tomorrow", locale: "en")
 `Array` of entity `Hash`es (empty if nothing matched):
 
 ```ruby
-Duckling.parse(text, locale: "en", dims: ["time"], reference_time: nil, with_latent: false)
+Duckling.parse(text, locale: "en", dims: ["time"], reference_time: nil, with_latent: false, reference_zone: nil)
 ```
 
 ### Keyword arguments
@@ -55,9 +55,49 @@ Duckling.parse(text, locale: "en", dims: ["time"], reference_time: nil, with_lat
   raises `TypeError`; wrap it in `Time.at(seconds)` first.
 - `with_latent:` (Boolean, default `false`) — include ambiguous/latent
   matches (e.g. a bare "morning") in the results.
+- `reference_zone:` (String, default `nil`) — an IANA zone name, e.g.
+  `"America/New_York"`. Resolves each wall-clock result's UTC offset against
+  that zone on the result's *own* date, so a result before a DST transition
+  and one after it get different offsets instead of sharing
+  `reference_time:`'s single fixed one. An unknown identifier raises
+  `ArgumentError`; so does a `reference_time:` whose `utc_offset` disagrees
+  with the zone at that instant. It does not anchor the parse — see "Time
+  zone data" below.
 
 There is no `Duckling::Error` class — invalid `locale:`/`dims:` values raise
-plain `ArgumentError`.
+plain `ArgumentError`, as do an unknown `reference_zone:` and a
+`reference_time:` whose offset disagrees with it. The one named error a caller
+is likely to meet is `Duckling::TZDataUnavailable`, for a host with no tz
+database at all — see "Time zone data" below.
+
+### Time zone data
+
+`reference_zone:` resolves against [tzinfo][], which uses the `tzinfo-data`
+gem when it is installed and the host's own zoneinfo files otherwise. This gem
+does not depend on `tzinfo-data`, so by default you get the host's database.
+
+That is usually what you want, and it is the faster of the two to start up.
+Two cases where it is not:
+
+- **Backward-compatibility names.** Debian and Ubuntu ship names like
+  `"US/Eastern"` in a separate `tzdata-legacy` package that is not installed
+  by default, so roughly a hundred valid IANA identifiers raise
+  `ArgumentError` on a stock host. Either `gem "tzinfo-data"` or
+  `apt install tzdata-legacy` restores them. The error message names whichever
+  database answered and how many identifiers it has, so you can tell this
+  apart from a typo.
+- **No zoneinfo files at all**, as in a scratch or distroless container.
+  `reference_zone:` raises `Duckling::TZDataUnavailable` there, naming both
+  fixes. Add `gem "tzinfo-data"` to bundle the data with your app, where you
+  can also patch its vintage by bumping one gem, or install the system
+  `tzdata` package. Every other keyword works without a tz database.
+
+`reference_zone:` reinterprets result offsets; it does not anchor the parse.
+Given without `reference_time:`, a relative expression like `"tomorrow"` still
+anchors on the machine-local clock rather than on "now" in that zone — pass a
+`reference_time:` in the zone to anchor as well.
+
+[tzinfo]: https://github.com/tzinfo/tzinfo
 
 ### Return value
 

data/Rakefile

@@ -60,7 +60,7 @@ end
 # extconf.rb runs in its own subprocess. ENV changes made there do not
 # reach the parent process, and the parent process runs `make`.
 #
-# So this fix changes ENV here, in the Rakefile, not in extconf.rb.
+# So this fix changes ENV here, in the Rakefile.
 # The fix adds a prerequisite task to the local build's Makefile task.
 # This prerequisite task sets the correct host target. It runs before
 # the Makefile task, and before `make` runs later.
@@ -71,7 +71,7 @@ if (ruby_target = ENV["RUBY_TARGET"]) && ruby_target != RUBY_PLATFORM
   # away. Clearing RUST_TARGET alone lets rb_sys fall back to the target
   # baked into the container's $CARGO_HOME/config.toml, which is the
   # cross-compile target again. So a host triple that cannot be read is a
-  # hard error, not something to skip past.
+  # hard error.
   #
   # Both variables belong to the whole rake process, and the cross build
   # reads them too. This is safe only because rake generates the cross
@@ -121,8 +121,8 @@ end
 #
 # So build from a throwaway plain clone instead, whose .git is a real
 # directory under the mount. Two consequences: the gem carries *committed*
-# state, not the working tree, and the clone gets its own Cargo target
-# directory rather than reusing this checkout's.
+# state (uncommitted changes are excluded), and the clone gets its own Cargo
+# target directory separate from this checkout's.
 CLONE_DIR = "tmp/native_gem_clone"
 
 def build_native_gem(platform)
@@ -163,10 +163,10 @@ end
 
 task :benchmark_env do
   # Force a realistic release-profile build regardless of .env.local's
-  # RB_SYS_CARGO_PROFILE=dev (local dev checkouts only, never present in
-  # CI). Must reenable :compile in case it already ran earlier in this same
-  # rake process, so it's guaranteed to recompile under the forced profile
-  # rather than reusing a stale dev-profile build.
+  # RB_SYS_CARGO_PROFILE=dev (local dev checkouts only; CI never has it).
+  # Must reenable :compile in case it already ran earlier in this same
+  # rake process, so it recompiles under the forced profile. A stale
+  # dev-profile build would be reused otherwise.
   ENV.delete("RB_SYS_CARGO_PROFILE")
   Rake::Task[:compile].reenable
 end
@@ -184,8 +184,8 @@ namespace :benchmark do
 
   desc "Run :record on a fresh branch off origin/main, then commit/push and open+auto-merge a PR via gh"
   task record_pr: ["release:guard_clean"] do
-    # Explicit bash, not Rake's default `sh -c` (dash on Debian/Ubuntu
-    # runners): dash's `set` doesn't support the `-o pipefail` flag below.
+    # Explicit bash: Rake's default `sh -c` is dash on Debian/Ubuntu
+    # runners, and dash's `set` doesn't support the `-o pipefail` flag below.
     sh("bash", "-c", <<~SH)
       set -euo pipefail
       original_ref="$(git symbolic-ref -q --short HEAD || git rev-parse HEAD)"
@@ -214,12 +214,14 @@ namespace :benchmark do
 end
 
 # The default suite exercises the extension compiled in this checkout.
-# test/gem/ exercises a *built* or *installed* gem instead — it needs one
-# handed to it, and the installed suite must not see this checkout's lib/ at
-# all — so both run on their own, as plain `ruby test/gem/<file>`. See each
-# file's header.
+# Three test subtrees run outside it:
+# - test/gem/ exercises a *built* or *installed* gem instead — it needs one
+#   handed to it, and the installed suite must not see this checkout's lib/.
+# - test/capabilities/ is loaded by test_helper itself, gated on the tz probes.
+# - test/environments/ holds contracts invoked directly by their CI step.
+# See docs/tz-database-axis.md.
 Minitest::TestTask.create do |t|
-  t.test_globs = FileList["test/**/*_test.rb"].exclude("test/gem/**/*")
+  t.test_globs = FileList["test/**/*_test.rb"].exclude("test/gem/**/*", "test/capabilities/**/*", "test/environments/**/*")
 end
 
 # Minitest::TestTask has no built-in way to declare a task dependency, and
@@ -227,7 +229,7 @@ end
 # `bundle exec rake` itself — `bundle exec rake test` run directly has no
 # guarantee `compile` ran first, which would surface as a confusing
 # LoadError/stale-behavior failure unrelated to the code under test.
-task test: :compile
+task test: %i[compile]
 
 require "standard/rake"
 

data/docs/tz-database-axis.md

@@ -0,0 +1,454 @@
+# The tz-database axis
+
+This document is the central reference for time zone (tz) data in this gem.
+It replaces long inline comments. Keep inline comments short. Point here
+instead.
+
+## Why the tz database is an axis
+
+`reference_zone:` resolves zones with the `tzinfo` gem. tzinfo uses the
+`tzinfo-data` gem when that gem is installed. Without that gem, tzinfo uses
+the zoneinfo files of the host. This gem does not depend on `tzinfo-data`.
+Both configurations are valid production configurations.
+
+The two databases do not give the same answers. They differ on three
+independent axes:
+
+- **Modelling.** Some distributions compile tzdata in rearguard format.
+  Rearguard data strips negative DST. Example: `Europe/Dublin` is a
+  negative-DST zone in vanguard data. It is an ordinary positive-DST zone in
+  rearguard data. Ubuntu 24.04 and macOS ship rearguard data. Debian trixie,
+  Alpine, and FreeBSD ship vanguard data.
+- **Backward-compatibility links.** Debian and Ubuntu move the links to a
+  separate `tzdata-legacy` package. That package is not installed by
+  default. `US/Eastern` and approximately 100 other names then stop
+  resolving. The identifier count drops from approximately 600 to
+  approximately 500.
+- **Vintage.** A pinned `tzinfo-data` gem or an unpatched host can predate a
+  rule change. Example: `America/Nuuk` got new rules in tzdata 2023a. A
+  2021–2022 vintage resolves the zone and answers with the old rules. Before
+  2020a the name `America/Nuuk` does not exist at all.
+
+A host can also have no tz database at all. Scratch and distroless
+containers are examples. There `reference_zone:` raises
+`Duckling::TZDataUnavailable`.
+
+A suite run cannot observe which database it ran against. It passes
+identically on both. Four mechanisms keep the coverage honest: environments,
+probes, capability-gated tests, and environment contracts.
+
+## Mechanism 1: Environments
+
+Two environment variables select the database under test:
+
+- `DUCKLING_TZINFO_DATA` (read in the Gemfile) controls the `tzinfo-data`
+  gem in the bundle:
+  - unset: the current release of the gem. This is the default environment.
+  - `none`: no gem. tzinfo falls back to the zoneinfo files of the host.
+  - an exact version, for example `1.2022.7`: a stale database.
+- `DUCKLING_ZONEINFO_DIR` (read in `test/test_helper.rb`) points tzinfo at a
+  specific compiled zoneinfo directory. It is set before `duckling` is
+  required. Nothing then resolves a zone against the default source first.
+
+Always set `BUNDLE_LOCKFILE` for any environment except the default.
+Without it, `bundle install` overwrites the committed `Gemfile.lock`. The
+per-environment lockfiles are gitignored (`/Gemfile.*.lock`). A dirty tree
+also blocks `rake release` and `rake benchmark:record_pr`. Both are guarded
+by `release:guard_clean`. The error looks unrelated.
+
+An unrecognized `DUCKLING_TZINFO_DATA` value raises in the Gemfile. A typo
+must fail there. It must not fail deep in the resolver as an unsatisfiable
+constraint.
+
+Seven environments run in CI:
+
+| Environment | CI job | Database under test |
+|---|---|---|
+| default | `baseline` | current `tzinfo-data` gem |
+| system-zoneinfo | `baseline` step | zoneinfo files of the runner |
+| linkless-zoneinfo | `baseline` step | built by `bin/build-linkless-zoneinfo` |
+| tzinfo-data 1.2022.7 | `timezones` matrix | pinned gem |
+| stale system zoneinfo | `timezones` matrix | built by `bin/build-stale-zoneinfo` |
+| Debian + tzdata-legacy | `tz-containers` matrix | system zoneinfo with the links |
+| Alpine | `tz-containers` matrix | vanguard zoneinfo, musl source build |
+
+Gating:
+
+- Only `baseline` blocks a merge. It is the only required check. So the
+  three environments a consumer is actually on run there as steps.
+- `timezones` and `tz-containers` do not block a merge. They do block a
+  release. `release.yml` waits on the full workflow (`needs: ci`). A red
+  result there means "this vintage answers differently". It does not mean
+  "the gem is broken for anyone today".
+
+The linkless environment must be built. No runner is in that state.
+`ubuntu-latest` resolves `US/Eastern` from its own tzdata. macOS does too.
+Note: the runner is not a stock Ubuntu for tz data. A plain `ubuntu:24.04`
+container of an earlier tzdata point release does not resolve the links.
+The runner does. So no runner fact settles the links. The suite probes them.
+
+One configuration deliberately has no environment: a host with no tz
+database at all. A runner without tz data would break more than this gem.
+Every probe answers `false` there. So the suite loads and runs. The
+`DataSourceNotFound` arms assert this. `test/gem/installed_gem_test.rb`
+skips its `reference_zone:` case there for the same reason.
+
+## Mechanism 2: Behavioral probes
+
+Neither datasource exposes a version. `RubyDataSource` keeps `version_info`
+private. `ZoneinfoDataSource` exposes only `zoneinfo_dir`. So a probe asks
+the database a question. It does not read a release string.
+
+Probes are split by consumer:
+
+- `Duckling::TZInfoCapabilities` (`lib/duckling/tzinfo_capabilities.rb`)
+  ships in the gem. It holds only what the unknown-identifier error message
+  needs.
+- `TZCapabilities` (`test/support/tz_capabilities.rb`) holds the probes that
+  only the suite calls. `lib/` reaches every consumer. `test/` reaches
+  none. A probe with no production caller does not belong in `lib/`.
+
+`backward_compat_links?` is needed on both sides. Production owns it. The
+test module delegates to it.
+
+Probe rules:
+
+- A probe is a total boolean. It answers `false` on a host with no database.
+  It must not raise. `TZInfo::DataSourceNotFound` is a sibling of
+  `InvalidTimezoneIdentifier`. It is not a subclass. Rescue it explicitly.
+- Nothing is memoized. `TZInfo::DataSource.set` can swap the database
+  mid-process. The fixture-zone tests do this. A cached answer would
+  describe a database that is no longer in use.
+- `TZCapabilities.supports?` raises `ArgumentError` on an unknown capability
+  name. A typo must be a hard error. It must not be a silent `false`.
+
+The three probes:
+
+- `models_negative_dst?` asks about `Europe/Dublin`. IANA models it as
+  +01:00 standard all year, with a negative one-hour saving in winter. So
+  tzinfo reports January as the `dst?` period. Rearguard data re-expresses
+  the same offsets as ordinary positive DST.
+- `backward_compat_links?` asks for `US/Eastern`. It is a link to
+  `America/New_York` in IANA's `backward` file.
+- `greenland_2023_rules?` asks whether `America/Nuuk` skips
+  2026-03-28 23:30. Older vintages fail in two ways. Before 2020a the name
+  does not exist. The 2021–2022 vintages know the name but answer with the
+  old rules. The zone resolves and gives a different answer. That is the
+  harder failure to attribute.
+
+## Mechanism 3: Capability-gated tests
+
+A test whose premise is a capability lives in
+`test/capabilities/<capability>_test.rb`. The loader at the bottom of
+`test/test_helper.rb` loads the file only where the probe passes. On a
+database that cannot answer, the test is not in the run. It does not fail
+for want of the capability. It does not pass vacuously.
+
+The filename is the declaration. The loader calls `supports?` with the
+filename. An unknown name raises at load time.
+
+Rules:
+
+- A test whose weak mode is a vacuous pass must assert its own premise.
+  Example: `negative_dst_test.rb` asserts `models_negative_dst?` in the
+  test body. The probe gates the load. The assertion catches the day the
+  probe or the IANA data drifts. The test uses the same predicate as the
+  loader. Two definitions could drift apart.
+- A file run directly (`ruby -Itest test/capabilities/negative_dst_test.rb`)
+  runs regardless of the probe. This is how you exercise one test against a
+  database that lacks the capability.
+- Do not use `expect_failure` for environment-dependent tests. It cannot
+  tell an absent capability from a genuine regression. It would convert
+  either into the same skip.
+
+## Mechanism 4: Environment contracts
+
+Each synthesized or pinned environment has a contract in
+`test/environments/<name>_test.rb`. The CI step that creates the
+environment invokes the contract directly:
+
+```bash
+bundle exec ruby -Ilib -Itest test/environments/<name>_test.rb
+```
+
+The suite never loads the contracts. A contract asserts its state
+positively:
+
+- `tzinfo_data_test.rb`: the datasource is the gem, and all three probes
+  answer true. The default environment is the one place all three
+  capabilities are guaranteed. So this contract is the tripwire for the
+  loader. A probe that rotted to false would unload its capability file
+  silently everywhere else. Here it turns red.
+- `linkless_zoneinfo_test.rb`: `US/Eastern` raises, and the message names
+  both remedies. It also asserts the identifier count stays in the range of
+  a real links-less host. The build script's own check catches only
+  under-stripping. Over-stripping is the likelier drift. A future tzdata or
+  a different base image can add a top-level entry a real host keeps.
+- `stale_vintage_test.rb`: `America/Nuuk` answers with the pre-2023a rules.
+  The wrong answer is asserted on purpose. A stale database's dangerous
+  failure is a wrong answer. A missing zone is easier to attribute. If the
+  pin or the rollback
+  stops taking effect, the capability-gated test simply starts loading and
+  passing. The suite goes green against a different database than the
+  environment exists for. This contract turns red instead.
+- `system_zoneinfo_links_test.rb` and `alpine_vanguard_test.rb`: the
+  defining probe answers true. An environment that lost its defining
+  capability would silently run less. The contract is the loud half.
+
+Without a contract, a broken setup presents as a smaller green suite. The
+capability-gated files simply load less.
+
+## The error messages
+
+### Unknown identifier
+
+`timezone_for` raises `ArgumentError` for an unknown identifier. The
+message includes `unknown_identifier_diagnosis`. It names the database that
+answered and how many identifiers it has. The count separates the two
+databases legibly: approximately 600 against approximately 500.
+
+Rules for the remedy clause:
+
+- It is a condition the reader evaluates ("if that is what this is"). It is
+  not a claim about the identifier. Only the database is checked here.
+  Whether the name is one of the approximately 100 in IANA's `backward`
+  file is not knowable without shipping that list. A claim would tell every
+  typo on a links-less host that `tzdata-legacy` supplies it. A shipped
+  list would be worse: a name it missed would get no remedy at all.
+- The identifier the caller passed must not appear in the remedy clause.
+  Naming it there turns the condition back into a claim.
+- The clause appears only where the database has no links.
+- The remedies assume the datasource is the host's default. A caller who
+  pointed `TZInfo::DataSource` at their own directory must fix that
+  directory instead. The message names the directory. That makes the case
+  recognizable.
+
+Rules for `datasource_description`:
+
+- The zoneinfo case is detected by capability (`respond_to?(:zoneinfo_dir)`).
+  A caller can install a custom subclass. The directory is the useful part
+  of the answer.
+- The gem case is detected by class. Whether `tzinfo-data` is loaded says
+  nothing about whether it answered. A custom datasource in a bundle that
+  also carries the gem must not be described as tzinfo-data.
+- An unrecognized datasource is named by its own class. Do not describe it
+  as another database.
+- A host with no database gets its own string. This method builds failure
+  messages. It must not raise. Raising would replace the explanation with a
+  raw tzinfo error at the moment the explanation was wanted.
+
+### No database at all
+
+`timezone_for` raises `Duckling::TZDataUnavailable` when tzinfo raises
+`DataSourceNotFound`. tzinfo raises it before any identifier lookup. The
+zone name is beside the point. The message names the `reference_zone:`
+keyword and both fixes: the `tzinfo-data` gem, or the system `tzdata`
+package.
+
+`TZDataUnavailable` is deliberately not an `ArgumentError`. It reports the
+state of the deployment. A caller that validates user
+input by rescuing `ArgumentError` must not swallow it. It is a named class
+for the same reason as `ShapeError`: greppable, and not satisfiable by an
+unrelated `RuntimeError`.
+
+## Fixture zones
+
+`test/fixtures/tz/*.zi` files are compiled by `zic` into a private zoneinfo
+directory at test time. `TZFixtures::Datasource` swaps `TZInfo::DataSource`
+in `setup` and restores it in `teardown`.
+
+Why fixture zones:
+
+- A fixture zone is identical on every host and every vintage. Real zones
+  are not. Which real zones exist depends on the datasource. What they do
+  depends on the vintage.
+- The fixture directory exposes only its own three identifiers. Nothing
+  about the host's database can leak into a test.
+- The swap is process-global because `timezone_for` reaches the datasource
+  through `TZInfo::Timezone.get` inside `Duckling.parse`. No injection
+  point exists. This is also why Ruby doubles cannot replace the fixture
+  zones. A double can only reach `local_time_in_zone` directly. That stops
+  short of the outside-in path through `Duckling.parse`.
+- The restore in `teardown` is mandatory. A leaked fixture
+  datasource leaves every later test with three zones and nothing else.
+- `TZInfo::DataSource.get` creates the default source when none is set. It
+  raises when it cannot. So setup tolerates the absence. Teardown restores
+  conditionally: `set(nil)` raises `ArgumentError`. On a failed setup that
+  would replace the real error with a worse one.
+
+The tests reach the fixtures through `Duckling.parse`. The coverage stays
+outside-in. One exception: the half-hour gap test calls
+`local_time_in_zone` directly. No English expression lands reliably inside
+a 30-minute window.
+
+The three fixture zones:
+
+- `Fixture/NegativeDst`: shaped like `Europe/Dublin`. Negative DST. It
+  distinguishes first-occurrence-by-position from a `dst?`-flag lookup.
+  Picking by flag gives the second occurrence, an hour off as an instant.
+  `ActiveSupport::TimeZone#local` picks by flag (`period_for_local`'s
+  `dst=true` default).
+- `Fixture/HalfHourGap`: shaped like `Australia/Lord_Howe`. A 30-minute
+  gap. It distinguishes the transition's real width from a hardcoded
+  one-hour shift. ActiveSupport's `@time += 1.hour` retry overshoots.
+  Lord Howe is the only zone in current use with a sub-hour gap. The
+  coverage rested on one zone's continued existence.
+- `Fixture/LateGap`: shaped like `America/Nuuk`. A gap late in the local
+  day in a negative-offset zone. The transition instant falls past the next
+  UTC midnight. `gap_delta`'s scan window must center on the skipped wall
+  clock read as UTC. A midnight-anchored window misses the transition.
+  `gap_delta` then crashes with `NoMethodError` on a nil `find`.
+
+`zic` needs no provisioning except on Alpine:
+
+- Debian/Ubuntu: `zic` is in `libc-bin` (Priority: required, a dependency
+  of libc6). It is not in `tzdata`. A slim image without
+  `/usr/share/zoneinfo` still has it.
+- macOS: `/usr/sbin/zic` is a stock utility.
+- Alpine: `zic` is in `tzdata-utils`. The `tz-containers` job installs it.
+- `zic` lives in `sbin`. That is off a non-root `PATH`. `TZFixtures` and
+  `bin/build-stale-zoneinfo` search there explicitly.
+- A missing `zic` is a hard error. These fixtures exist because this
+  coverage kept degrading silently on hosts nobody watched. A skip would
+  reintroduce exactly that.
+
+## The build scripts
+
+### `bin/build-linkless-zoneinfo <output-dir>`
+
+Copies the host's zoneinfo directory and removes the top-level
+backward-compatibility entries. `ZONEINFO_DIR` overrides the source
+directory (default `/usr/share/zoneinfo`).
+
+- The keep-list is transcribed from a real links-less host: a Debian-family
+  container with `tzdata` and no `tzdata-legacy`, 497 identifiers. No name
+  is added defensively. `Factory` and `posixrules` stay because Ubuntu
+  24.04's tzdata 2025b still has them.
+- The script hard-fails if `US/Eastern` survives the strip. That check
+  catches under-stripping only. The environment contract's identifier-count
+  range catches over-stripping.
+- `cp -RL` dereferences the alias symlinks. Removing an entry cannot leave
+  a dangling link. It cannot follow one back into the host's directory.
+- The approximately 60 in-region aliases that `tzdata-legacy` also owns are
+  not removed (`America/Godthab`, `Europe/Kiev`, `Asia/Calcutta`). Inside a
+  region directory they are indistinguishable from aliases a stock host
+  keeps (`Asia/Istanbul`, `Pacific/Samoa`). So the tree exposes more
+  identifiers than a stock host. That costs nothing. The guarantee the
+  environment needs is that `US/Eastern` is genuinely gone. It is the probe
+  target and the name the CHANGELOG and the error message use.
+- The copy keeps the host's modelling. Only the links absence gets an
+  environment contract. Modelling follows the host. The capability-gated
+  Dublin test loads or does not load.
+
+### `bin/build-stale-zoneinfo <output-dir>`
+
+Copies the host's zoneinfo directory and compiles
+`test/fixtures/zoneinfo-overrides/*.zi` over it. The overrides roll named
+zones back to earlier rules. `America/Nuuk` goes back to the pre-2023a
+rules.
+
+- The copy keeps the host's modelling and links state. The capability-gated
+  tests absorb both.
+- Rolling back only the zones under assertion says plainly which staleness
+  is tested. Compiling a full old tzdata release would need a download.
+- The override replaces the zone's entire history, including the pre-2023a
+  rules. Harmless for the contract: it only looks at 2026. Every other zone
+  in the copied directory stays as the host has it.
+- This script needs `tzdata` installed. It copies `/usr/share/zoneinfo`. It
+  fails with a clear message if the directory is missing.
+- The override shadows a real identifier on purpose. The
+  `test/fixtures/tz/*.zi` zones are `Fixture/`-prefixed so they cannot be
+  mistaken for real ones. Here shadowing is the point. The environment must
+  be a plausible stale host. A synthetic zone would give nothing to assert
+  against.
+
+## `expect_failure`
+
+`expect_failure(reason)` in `test/test_helper.rb` is for known limitations
+that fail on every host. The upstream grammar and ranking gaps are the
+current cases. It runs the block for real:
+
+- A failure reports as a skip that names the reason.
+- A pass flunks. The limitation stopped reproducing. Drop the wrapper and
+  keep the assertions.
+- Only `Minitest::Assertion` is rescued. It inherits from `Exception`, not
+  from `StandardError`. A wider rescue would launder any crash before the
+  assertions into "known limitation". A genuine regression must surface as
+  a crash.
+- A `skip` inside the block is re-raised first. `Minitest::Skip` is a
+  subclass of `Minitest::Assertion`. Otherwise the real explanation would
+  be replaced by the reason.
+
+Do not use it for anything environment-dependent. Use
+`test/capabilities/` instead.
+
+## Running an environment locally
+
+Always pass `BUNDLE_LOCKFILE` to both the `bundle install` and the run.
+The suite adapts itself to whatever database it gets. There is no
+environment name to set. Run the matching contract afterward to prove you
+got the state you meant to.
+
+```bash
+# no tzinfo-data: the host's zoneinfo files
+export DUCKLING_TZINFO_DATA=none BUNDLE_LOCKFILE=Gemfile.system-zoneinfo.lock
+bundle install && bundle exec rake test
+
+# the same, with the backward-compat links stripped (US/Eastern stops resolving)
+bin/build-linkless-zoneinfo /tmp/linkless-zoneinfo
+DUCKLING_ZONEINFO_DIR=/tmp/linkless-zoneinfo bundle exec rake test
+DUCKLING_ZONEINFO_DIR=/tmp/linkless-zoneinfo \
+  bundle exec ruby -Ilib -Itest test/environments/linkless_zoneinfo_test.rb
+
+# a pinned stale vintage
+export DUCKLING_TZINFO_DATA=1.2022.7 BUNDLE_LOCKFILE=Gemfile.tzinfo-data-1.2022.7.lock
+bundle install && bundle exec rake test
+bundle exec ruby -Ilib -Itest test/environments/stale_vintage_test.rb
+
+# both axes at once
+bin/build-stale-zoneinfo /tmp/stale-zoneinfo
+export DUCKLING_TZINFO_DATA=none BUNDLE_LOCKFILE=Gemfile.stale-system-zoneinfo.lock
+bundle install && DUCKLING_ZONEINFO_DIR=/tmp/stale-zoneinfo bundle exec rake test
+DUCKLING_ZONEINFO_DIR=/tmp/stale-zoneinfo \
+  bundle exec ruby -Ilib -Itest test/environments/stale_vintage_test.rb
+```
+
+`DUCKLING_ZONEINFO_DIR` alone (pointing at `/usr/share/zoneinfo`, with
+`tzinfo-data` still bundled) reaches the same datasource as the system leg
+without re-resolving anything. It is the quick way to reproduce a
+system-zoneinfo failure. It is not the same configuration. The gem is still
+installed. So it does not exercise tzinfo's own fallback.
+
+## CI notes
+
+- `bundler-cache` is off in `timezones` and `tz-containers`. These
+  environments resolve a different bundle than the committed lockfile. The
+  cache is keyed on that lockfile.
+- The system-zoneinfo step in `baseline` runs
+  `bundle config unset --local deployment` (and `frozen`).
+  `bundler-cache: true` writes `deployment: true` into `.bundle/config`.
+  Deployment requires a committed lockfile. The environment lockfiles are
+  gitignored by design. It must be unset in the local config.
+  `BUNDLE_DEPLOYMENT` cannot override it. Bundler resolves local config first and environment
+  variables second (`Bundler::Settings#configs`). An env var cannot
+  override anything `bundle config --local` has written.
+- The Alpine image is pinned by digest. The floating `ruby:3.4-alpine` tag
+  silently rebases across Alpine releases. Alpine drops older versioned
+  clang packages as it rolls. A rebase also moves the host's tz data under
+  a leg that asserts against it. Bump by resolving the tag's current digest
+  (`docker buildx imagetools inspect ruby:3.4-alpine`). Then re-verify the
+  clang package names and the contract against the new release.
+- Alpine splits clang's resource headers (`stdckdint.h`, which ruby-3.4's
+  headers include) away from the library's default search path.
+  `BINDGEN_EXTRA_CLANG_ARGS=-I<resource-dir>` points bindgen at them. Any
+  musl consumer building the source gem needs the same. No precompiled gem
+  targets musl (`cross_targets.rb`). So the source build is the path musl
+  consumers actually take.
+- The banner line at suite start (`tz datasource: ...; negative_dst=true
+  ...`) records which database answered and which probes passed. Two images
+  with the same name can disagree about the links. The banner is what
+  reconciles a missing capability test with a CI log.
+- The container jobs run the image's own Ruby. `ruby/setup-ruby` does not
+  apply (it has no musl support). The toolchain comes from the image's
+  package manager, git included. That is why the install step precedes
+  checkout.

data/ext/duckling/Cargo.toml

@@ -2,6 +2,13 @@
 name = "duckling"
 version = "0.1.0"
 edition = "2024"
+# Edition 2024 already floors the compiler at 1.85; naming it lets cargo
+# fail with a clean MSRV error instead of a parse error. It is also the de
+# facto floor of the Debian-trixie CI leg, whose rustc is frozen at 1.85.0
+# for the life of Debian 13 — the first crate change requiring a newer
+# compiler turns that leg red, and this field is what makes the error
+# legible there.
+rust-version = "1.85"
 
 [lib]
 crate-type = ["cdylib"]

data/lib/duckling/tzinfo_capabilities.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require "tzinfo"
+
+module Duckling
+  # Which tz database `reference_zone:` resolves against, for the
+  # unknown-identifier error message. Behavioral because neither datasource
+  # exposes a version. Internal. See docs/tz-database-axis.md.
+  module TZInfoCapabilities
+    module_function
+
+    # DataSourceNotFound does not inherit from InvalidTimezoneIdentifier;
+    # name it explicitly. A host with no database answers false.
+    def backward_compat_links?
+      TZInfo::Timezone.get("US/Eastern")
+      true
+    rescue TZInfo::InvalidTimezoneIdentifier, TZInfo::DataSourceNotFound
+      false
+    end
+
+    def identifier_count
+      TZInfo::Timezone.all_identifiers.size
+    rescue TZInfo::DataSourceNotFound
+      0
+    end
+
+    # Zoneinfo is detected by capability (a caller may install a subclass),
+    # the gem by class (loaded is not answered). Must not raise: it builds
+    # failure messages.
+    def datasource_description
+      source = begin
+        TZInfo::DataSource.get
+      rescue TZInfo::DataSourceNotFound
+        return "no tz datasource (no zoneinfo files, no tzinfo-data gem)"
+      end
+
+      return "system zoneinfo at #{source.zoneinfo_dir}" if source.respond_to?(:zoneinfo_dir)
+
+      if defined?(TZInfo::DataSources::RubyDataSource) && source.is_a?(TZInfo::DataSources::RubyDataSource)
+        version = " (tzdata #{TZInfo::Data::Version::TZDATA})" if defined?(TZInfo::Data::Version::TZDATA)
+        return "the tzinfo-data gem#{version}"
+      end
+
+      "the #{source.class} tz datasource"
+    end
+
+    # The remedy is phrased as a condition: only the database is checked.
+    # See docs/tz-database-axis.md.
+    def unknown_identifier_diagnosis
+      diagnosis = "resolved against #{datasource_description}, " \
+        "which provides #{identifier_count} identifiers"
+      return diagnosis if backward_compat_links?
+
+      "#{diagnosis}; this database has no backward-compat names (US/Eastern and ~100 others), " \
+        "so if that is what this is, it needs either the tzinfo-data gem or the " \
+        "tzdata-legacy system package"
+    end
+  end
+end

data/lib/duckling/version.rb

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

data/lib/duckling.rb

@@ -3,6 +3,7 @@
 require "tzinfo"
 
 require_relative "duckling/version"
+require_relative "duckling/tzinfo_capabilities"
 
 # 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.
@@ -21,7 +22,7 @@ rescue LoadError => abi_load_error
     require_relative "duckling/duckling"
   rescue LoadError
     # The ABI directory is missing, and so is the plain path. Raise the first
-    # error, not the second.
+    # error.
     #
     # 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
@@ -41,6 +42,12 @@ module Duckling
   # internal_error() class in lib.rs.
   class ShapeError < RuntimeError; end
 
+  # Raised when `reference_zone:` is given on a host with no tz database at
+  # all (no zoneinfo files, no tzinfo-data gem). Deliberately outside
+  # ArgumentError: it reports the deployment, so input-validation rescues do
+  # not swallow it. See docs/tz-database-axis.md.
+  class TZDataUnavailable < 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
@@ -64,7 +71,7 @@ module Duckling
   # 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:
+  # reference_time: is coerced here because the native extension cannot:
   # 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
@@ -79,13 +86,12 @@ module Duckling
   #
   # 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.
+  # against an offset the caller never asked for — so that combination raises.
   #
   # 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
+  # ("tomorrow") still anchor on the machine-local clock. They do not anchor
+  # 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)
@@ -112,7 +118,8 @@ module Duckling
 
   # 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.
+  # date. reference_time: carries a single fixed offset, which cannot be right
+  # for every leaf.
   #
   # TimePoint::Instant leaves are left strictly alone: the wrapped crate
   # already collapsed their relative arithmetic against one FixedOffset before
@@ -121,7 +128,7 @@ module Duckling
   #
   # 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
+  # Rust side must fail loudly here. The outcome to prevent is quiet results
   # resolved against the wrong offset.
   def self.apply_reference_zone(entities, reference_zone)
     return entities unless reference_zone
@@ -131,8 +138,8 @@ module Duckling
 
   # 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.
+  # zone is looked up once per call. Validation and reinterpretation share the
+  # lookup.
   def self.reinterpret_entities!(entities, zone)
     entities.each do |entity|
       next unless entity[:dim] == :time
@@ -160,7 +167,7 @@ module Duckling
 
   # 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.
+  # in reinterpret_time_point!. A missing-key check here would reject that shape.
   def self.reinterpret_interval_endpoints!(endpoints, zone)
     reinterpret_time_point!(endpoints[:from], zone)
     reinterpret_time_point!(endpoints[:to], zone)
@@ -227,19 +234,19 @@ module Duckling
   # `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
+  # as UTC. The UTC midnight of its date would be the wrong anchor. 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.
+  # this method crashed.
   #
-  # Read from the transition rather than assumed to be 3600. ActiveSupport's
+  # Read from the transition. Do not assume 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
+  # that lands half an hour past the gap's end (02:15 → 03:15; the correct
+  # answer is 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)
@@ -252,7 +259,16 @@ module Duckling
   def self.timezone_for(reference_zone)
     TZInfo::Timezone.get(reference_zone)
   rescue TZInfo::InvalidTimezoneIdentifier
-    raise ArgumentError, "invalid reference_zone: #{reference_zone.inspect}"
+    raise ArgumentError,
+      "invalid reference_zone: #{reference_zone.inspect} " \
+      "(#{TZInfoCapabilities.unknown_identifier_diagnosis})"
+  rescue TZInfo::DataSourceNotFound => error
+    # tzinfo raises this before any identifier lookup, so restate it in
+    # terms of the keyword the caller passed, naming both fixes.
+    raise TZDataUnavailable,
+      "cannot resolve reference_zone: #{reference_zone.inspect} — this host has no tz database. " \
+      "Add `gem \"tzinfo-data\"` to bundle the IANA data with your app, or install the system " \
+      "tzdata package to provide zoneinfo files. (#{error.message.lines.first.to_s.strip})"
   end
   private_class_method :timezone_for
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: duckling
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Caleb Buxton
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-08-05 00:00:00.000000000 Z
+date: 2026-08-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rb_sys
@@ -38,20 +38,6 @@ dependencies:
     - - "~>"
       - !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
@@ -114,11 +100,13 @@ files:
 - README.md
 - Rakefile
 - docs/2026-07-01-roadmap.md
+- docs/tz-database-axis.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/tzinfo_capabilities.rb
 - lib/duckling/version.rb
 homepage: https://github.com/cpb/duckling
 licenses: