zic-rs

A memory-safe Rust timezone compiler for IANA tzdata, producing TZif files with deterministic output and reference-zic comparison.

What this is

zic-rs compiles a declared subset of IANA tzdata source files (Zone / Rule / Link lines) into binary TZif zoneinfo files, as specified by RFC 9636 / tzfile(5). It is built as a small compiler with a hostile reference oracle: every supported construct is checked against the canonical C zic.

It is library-first — the compiler lives in the tzcompile library; the zic-rs binary is a thin CLI over it.

A producer, not a datetime library. Rust already has timezone consumers and bundlers (tz-rs, tzdb, jiff/jiff-tzdb). zic-rs sits upstream of them: it compiles and audits the TZif those consumers read. If you need to read local time in an app, use a consumer; if you need to compile IANA source into verified TZif for a pinned release, that's zic-rs. See docs/rust-ecosystem.md and the generated-data contract.

Current trust ladder

zic-rs is best read not as "a Rust rewrite of zic" but as a reference-admitted TZif compiler candidate whose claims are typed, witnessed, report-backed, and bounded. Each stage below answers a distinct trust question and is sealed with a close receipt; start at docs/reviewer-orientation.md before the details.

Public reports (all --format json, hand-rolled + deterministic): support-report · structural-report · semantic-report · tzif-validate · aux-table-validate · release-diff · doctor · size-report · compile --manifest. Each carries an oracle_mode (oracle absence is never silent), negative_capabilities (what is not claimed, each with its enforcing guard), and a bounded conformance_status (never an unqualified compatible).

The live behaviour claim (never inflated): zic-rs behaviour-matches reference zic/zdump for all 341/341 canonical zones in tzdata.zi 2026b over 1900..2040 — 0 mismatch · 0 fail-closed (CORE.1). Structural / byte / diagnostic / operational parity are separate axes, never collapsed into one verdict.

What this is not

• It is not yet a full replacement for reference zic.
• It does not install into /usr/share/zoneinfo; all output goes under an explicit --out directory.
• It refuses unsupported syntax with a clear diagnostic rather than emitting an approximate timezone file. Correctness is measured, not asserted.
• It does not decide timezone policy or curate timezone history. It compiles IANA tzdata according to reference-zic behaviour; it never editorialises or "normalises" civil-time rules beyond what zic does. (The tz database is maintained through IANA's process — RFC 6557 / BCP 175.)

Current implementation status

Implemented and verified:

• parsing of Zone / Rule / Link records, continuation lines, comments, quoting, and input-hardening limits;
• compilation of fixed-offset zones (RULES = -), finite rule-driven DST zones, recurring (TO = maximum) DST zones with a synthesised recurring POSIX footer (e.g. EST5EDT,M3.2.0,M11.1.0), inline-save eras (RULES = a clock value → a constant STDOFF + SAVE type, literal or %z), and multi-era zones (UNTIL continuations) with correct cross-era state — including lastSun/Sun>=N/Sun<=N day forms, wall/standard/UT AT suffixes, and %s/STD/DST/%z formats;
• real IANA-zone slices (tzdb 2026b): Europe/London (zdump-matched over 1830..2045; final EU era effectively recurring-only) and America/New_York (1883..2040; a genuinely mixed-in-era final era — Rule US finite DST 1967..2006 plus recurring 2007..max);
• Links (copy or symlink), with --zone <alias> resolving to the canonical zone;
• a safe output tree (path-traversal-proof, atomic exclusive create, no clobber without --force);
• a two-mode oracle (compare): zdump behaviour over a declared horizon (default; the real correctness criterion, used for DST/recurring zones) and decoded-TZif structural comparison (fixed-offset/debugging). Byte parity is reported only against pinned blobs.

For the fixed-offset fixtures (Etc/UTC, Test/Fixed), our output is byte-for-byte identical to the reference zic blobs pinned in fixtures/expected/ (produced with tzcode 2026b; see fixtures/MANIFEST.toml). For everything else the binding contract is semantic parity, checked by zic-rs compare against your local reference zic via the zdump behaviour oracle over a declared year horizon. Finite-DST, recurring-DST, and multi-era zones all match the oracle (see docs/compatibility.md). Source is read in both the canonical Rule/Zone/Link spelling and the zishrink-abbreviated R/Z/L form, so the installed single-file /usr/share/zoneinfo/tzdata.zi parses directly (record keywords match as zic-style unambiguous prefixes, like month/weekday names).

Whole-database status. As of tzdata.zi 2026b, zic-rs compiles all 341 / 341 canonical zones and behaviour-matches reference zic/zdump for every one over 1900..2040 — a comprehensive per-zone sweep with 0 mismatches and 0 fail-closed (compile-clean and behaviour-match are still tracked separately as different claims). The entire canonical-zone behaviour frontier is closed. This is reference-verified behaviour for the canonical zones over a declared horizon — not a full zic replacement and not infinity: leap-second modes, CLI/install policy, right//posix/, backzone/rearguard, warning parity, slim/-r/-R/-b emission, and TZif v4 remain a declared operational roadmap (see docs/roadmap.md, T9–T17).

Structural parity is a separate, measured axis (campaign T8). The structural-report command inventories how our TZif bytes differ from reference zic: across all 341 zones, isutcnt/isstdcnt/leapcnt/typecnt/version/footer are at full parity — ttisstd/ttisut is not a gap (both emit zero in this slim-default build); version+footer match 341/341 after T8-v3 pinned zic.c's compat >= 2013 version rule (the day-shift, not the displayed time's range, makes America/Santiago/Pacific/Easter v3); and charcnt matches 341/341 after T8-abbrev ported zic's abbreviation suffix-sharing packer (HST⊂AHST, LMT⊂PLMT). The last axis, the slim/fat timecnt window, is addressed by T8-slim: --emit-style zic-slim reproduces reference zic's slim explicit-transition set, collapsing the slim/fat-timecnt class 75 → 1 (only Europe/Lisbon, a ref-fatter-by-1 no-op) and raising byte-identical to 141/341 — while the default emission stays the behaviour-matched fat output. Behaviour is 341/0/0 in both modes (all zdump-equivalent). See docs/structural-parity.md. Behaviour parity stays the contract; byte parity is claimed only in zic-slim mode (or where a blob is pinned).

Canonical-zone behaviour over 1900..2040 is closed for tzdata.zi 2026b — no canonical zone fails closed (negative SAVE → law 7, and the non-POSIX Sat<=30-style recurring ON → law 10, are both solved). What remains is deferred / outside the verified canonical-zone path, none of it forced by tzdata.zi 2026b: inline-save eras with a %s or STD/DST slash FORMAT; a recurring rule whose ON is a fixed numeric day (no weekday, hence no Mm.w.d footer); 24:00/negative compiled AT times outside the implemented footer cases; leap-second / right/ modes; and the operational zic shell (CLI/install, -r/-R/-b, warning parity) — all tracked in docs/roadmap.md (T9–T21). (Accepted breadth — matching reference zic: both mixed finite+recurring final-era shapes, inline-save with a literal or %z FORMAT, and the obsolete FROM = minimum coerced to 1900.) See the pinned behaviour ledger docs/reference-zic-semantics.md.

Quick start

# Compile a fixed-offset zone and its link into ./zoneinfo
cargo run -- compile --input fixtures/minimal --out ./zoneinfo --zone Etc/UTC

# See what a zone would compile to (or why it is unsupported)
cargo run -- explain --input fixtures/minimal --zone Test/Fixed

# Compare our output against the system reference zic (semantic + byte)
cargo run -- compare --input fixtures/minimal --zone Etc/UTC --reference-zic zic

# Print the supported syntax subset
cargo run -- supported-syntax

# Map the whole installed tzdb: which zones compile, and why the rest don't (the frontier map)
cargo run -- support-report --input /usr/share/zoneinfo/tzdata.zi

# Inventory how our TZif *bytes* differ structurally from reference zic (separate from behaviour)
cargo run -- structural-report --input /usr/share/zoneinfo/tzdata.zi --reference-zic zic

Documentation

Acknowledgements

zic-rs builds on decades of work by the IANA Time Zone Database community. See ACKNOWLEDGEMENTS.md — and note that this project is not affiliated with or endorsed by IANA/ICANN, the TZ Coordinator, or the tzdb maintainers; bugs here are ours alone.

License

Dual-licensed under either of MIT or Apache-2.0, at your option.