If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/BurntSushi/jiff shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across all four use cases

• Last commit 2w ago
• 9 active contributors
• Unlicense licensed
• CI configured
• Tests present
• ⚠ Single-maintainer risk — top contributor 88% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live BurntSushi/jiff repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/BurntSushi/jiff.

What it runs against: a local clone of BurntSushi/jiff — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in BurntSushi/jiff | Confirms the artifact applies here, not a fork | | 2 | License is still Unlicense | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 45 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of BurntSushi/jiff. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/BurntSushi/jiff.git
#   cd jiff
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of BurntSushi/jiff and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "BurntSushi/jiff(\\.git)?\\b" \\
  && ok "origin remote is BurntSushi/jiff" \\
  || miss "origin remote is not BurntSushi/jiff (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Unlicense)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Unlicense\"" package.json 2>/dev/null) \\
  && ok "license is Unlicense" \\
  || miss "license drift — was Unlicense at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "src/lib.rs" \\
  && ok "src/lib.rs" \\
  || miss "missing critical file: src/lib.rs"
test -f "Cargo.toml" \\
  && ok "Cargo.toml" \\
  || miss "missing critical file: Cargo.toml"
test -f "DESIGN.md" \\
  && ok "DESIGN.md" \\
  || miss "missing critical file: DESIGN.md"
test -f "crates/jiff-static/src/lib.rs" \\
  && ok "crates/jiff-static/src/lib.rs" \\
  || miss "missing critical file: crates/jiff-static/src/lib.rs"
test -f "crates/jiff-cli/main.rs" \\
  && ok "crates/jiff-cli/main.rs" \\
  || miss "missing critical file: crates/jiff-cli/main.rs"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 45 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~15d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/BurntSushi/jiff"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Jiff is a Rust datetime library that provides high-level, hard-to-misuse primitives for working with dates, times, and timezones, with built-in support for the IANA Time Zone Database, DST-aware arithmetic, and lossless RFC 3339 formatting. It is inspired by the TC39 Temporal proposal and emphasizes correctness and ergonomics over bare-metal performance. Monorepo structure: /src contains the core Jiff library (date/time/timezone primitives), /crates/jiff-cli wraps it as a CLI tool with code generation capabilities (generate/tzdb.rs, generate/zoneinfo.rs), /crates/jiff-diesel provides Diesel ORM integration, /crates/jiff-tzdb and /crates/jiff-tzdb-platform handle timezone database bundling. Benchmarks live in /bench with modular suites (parse.rs, print.rs, tz.rs, zoned.rs).

Rust developers building applications that need reliable, timezone-aware datetime handling without the footgun-prone patterns of older libraries like chrono. System developers, backend engineers, and library authors who need to serialize/deserialize timestamps across timezones losslessly.

Production-ready. The crate is at v0.2.24, has comprehensive dual-licensing (MIT/UNLICENSE), active CI/CD pipeline (.github/workflows/ci.yml), and a detailed CHANGELOG.md tracking evolution. The author (BurntSushi) is well-established in the Rust ecosystem, and the library has clear documentation at docs.rs with design rationale in DESIGN.md and platform support matrix in PLATFORM.md.

Low-to-moderate risk. The library appears actively maintained with solid engineering practices (Cross.toml for platform testing, benchmarks in /bench), but the single maintainer model (BurntSushi) creates potential bus-factor risk. The integration with system timezone data (tz-system feature) adds platform-specific complexity. However, the MSRV is reasonable (Rust 1.70) and feature flags allow opt-in complexity (serde, logging).

The library is actively developed with tooling around timezone data management (the jiff-cli crate contains generate/tzdb.rs and generate/windows_zones.rs code generation). Recent additions appear focused on ORM integration (jiff-diesel) and platform abstraction (jiff-tzdb-platform). The workspace structure suggests ongoing work on multiple integration points. No specific milestone visible, but CHANGELOG.md will reveal recent feature additions.

git clone https://github.com/BurntSushi/jiff.git
cd jiff
cargo build
cargo test

Or to use as a dependency: cargo add jiff in your Rust project.

Daily commands: For library development: cargo test to run tests, cargo doc --open to view docs locally. For CLI tool: cargo run -p jiff-cli -- --help to see available commands (generate commands exist at /crates/jiff-cli/cmd/generate/). For benchmarks: cd bench && cargo bench --bench bench.

• src/lib.rs — Main library entry point; exports all public APIs and establishes the high-level abstractions (DateTime, Zoned, Date, Time, Duration).
• Cargo.toml — Defines feature flags (std, serde, icu-provider-blob) and tzdb strategy; critical for understanding which datetime backends are available.
• DESIGN.md — Rationale for all API design decisions; essential for understanding why Jiff prioritizes pit-of-success behavior over flexibility.
• crates/jiff-static/src/lib.rs — Implements static timezone database loading and TZif file parsing; core to timezone-aware datetime operations.
• crates/jiff-cli/main.rs — CLI tool entry point; demonstrates idiomatic usage of the library and serves as integration example.
• COMPARE.md — Comparative analysis with chrono, time, hifitime, and icu; clarifies when to use Jiff and its tradeoffs versus competitors.
• bench/src/lib.rs — Benchmarking infrastructure; shows performance expectations and testing patterns for contributors.

Add Support for a New Database ORM

1. Create new crate at crates/jiff-{orm-name}/ (crates/jiff-{orm-name}/Cargo.toml)
2. Implement type wrappers and serialization logic mirroring jiff-diesel pattern (crates/jiff-{orm-name}/src/wrappers.rs)
3. Add database-specific adapters (e.g., postgres.rs, sqlite.rs) with bind/read implementations (crates/jiff-{orm-name}/src/postgres.rs)
4. Export public API in lib.rs and add to workspace Cargo.toml (crates/jiff-{orm-name}/src/lib.rs)

Add a New DateTime Operation or Rounding Mode

1. Review existing DateTime methods in src/datetime.rs (or similar) to understand patterns (src/lib.rs)
2. Add method to the appropriate type (DateTime, Zoned, Duration) following pit-of-success naming (src/datetime.rs)
3. Ensure DST-aware logic by delegating to timezone provider in jiff-static (crates/jiff-static/src/lib.rs)
4. Add benchmark in bench/src/datetime.rs to document performance (bench/src/datetime.rs)
5. Document design decision in DESIGN.md if a new API principle is introduced (DESIGN.md)

Update Embedded Timezone Database from IANA TZDB

1. Download latest IANA TZDB release and place in known location (crates/jiff-cli/cmd/generate/tzdb.rs)
2. Run CLI generator: jiff generate tzdb --src <path> --out <dest> (crates/jiff-cli/main.rs)
3. Generator parses TZDB rules and invokes zoneinfo.rs to serialize TZif format (crates/jiff-cli/cmd/generate/zoneinfo.rs)
4. Compiled artifact is embedded via jiff-static at compile time (crates/jiff-static/src/shared/tzif.rs)
5. Run benchmarks and tests to validate transitions and DST rules (bench/src/tz.rs)

Add Serde Serialization for a Custom Type

1. Check if serde feature is enabled in Cargo.toml (Cargo.toml)
2. Implement Serialize and Deserialize for the type using RFC3339 or ISO8601 format (src/lib.rs)
3. Follow existing datetime serde patterns to ensure lossless round-tripping (src/datetime.rs)
4. Add test coverage in integration tests to verify serialization format stability (tests/lib.rs)

• Rust + no_std compatible — Ensures library works in embedded and WASM environments; core datetime logic has minimal runtime dependencies.
• Embedded static timezone database (TZif binary) — Eliminates runtime TZDB lookups and system-level dependencies; guarantees consistent timezone behavior across platforms.
• Opt-in Serde support — Keeps core library lightweight while enabling seamless serialization for web APIs and databases.
• Feature-gated ORM integrations (Diesel, SQLx) — Allows users to choose their database layer without bloating core library; each adapter is independently versioned.
• Temporal-inspired API design — Leverages TC39 Temporal proposal idioms proven in JavaScript; reduces misuse by enforcing explicit handling of edge cases (DST, leap seconds, ambiguous times).

• Pit of success via explicit type safety over flexible generics

  • Why: Prevents subtle bugs from naive datetime arithmetic across timezone boundaries.
  • Consequence: Slightly more verbose API in edge cases; users must explicitly opt into operations that could fail (e.g., ambiguous local times during DST fall-back).

• Embedded static timezone database over dynamic platform TZDB

  • Why: Ensures reproducible behavior across all platforms without relying on system tzdb.
  • Consequence: Larger binary footprint (~800KB–2MB depending on optimization); requires periodic updates from IANA TZDB via CLI tool.

• Separate crates for ORM/ICU integrations

  • Why: Avoids strong coupling to specific databases or internationalization libraries.
  • Consequence: Users must manage multiple Cargo.toml entries and version coordination

1. Feature interactions: The tzdb features (tzdb-bundle-platform, tzdb-zoneinfo, tzdb-concatenated) are not always mutually exclusive; enabling all may increase binary size unexpectedly. 2. Platform-specific timezone detection: The tz-system feature uses heuristics on Unix (/etc/localtime symlink) and Windows registry calls; behavior is platform-specific and may fail gracefully or panic depending on OS. 3. DST arithmetic complexity: Adding durations across DST boundaries requires understanding the library's chosen semantics (absolute vs. wall-clock time); misuse is easy. 4. MSRV constraint: Rust 1.70 minimum; some dependency upgrades may break this silently. 5. No-std limitations: While marked as no-std capable, most features require alloc; testing no-std variants requires explicit Cargo feature combinations.

• IANA Time Zone Database (TZDB) and zoneinfo format — Jiff must correctly parse and embed the TZDB to handle DST transitions and timezone rules; the /crates/jiff-cli/cmd/generate/ modules exist solely to process this data format into Jiff's internal representation
• Daylight Saving Time (DST) arithmetic and disambiguation — Adding time across DST boundaries has multiple valid interpretations (absolute vs. wall-clock); Jiff's core design choice (prefer wall-clock, explicit errors on ambiguity) is explained in DESIGN.md and requires deep understanding to avoid footguns
• RFC 3339 datetime serialization — Jiff emphasizes lossless round-trip parsing/formatting of RFC 3339 strings with timezone offsets; the To/FromStr traits for Timestamp and Zoned depend on correct RFC 3339 parsing
• Proleptic Gregorian calendar (with year 1 support) — Unlike some datetime libraries that only support years 1–9999, Jiff's Date type may support wider ranges; understanding calendar math edge cases (leap second handling, year 0) is critical for calendar arithmetic
• Zero-copy immutable datetime representations — Jiff's API design prioritizes immutability and minimal allocations (Timestamp, Date, Time are often stack-allocated); this influences how the library handles conversions and cloning
• Feature gating and conditional compilation in Rust workspaces — Jiff's rich feature matrix (std, tz-system, serde, logging, tzdb-* variants) requires careful understanding of how Cargo features compose; the workspace members (jiff-cli, jiff-diesel) depend on these gates
• Cross-platform timezone detection heuristics — The tz-system feature uses OS-specific logic (Unix /etc/localtime symlinks, Windows registry) to determine system timezone; failures are platform-dependent and can degrade gracefully or fail loudly

• chronotope/chrono — The incumbent Rust datetime library that Jiff explicitly improves upon; developers often migrate from chrono to Jiff and need side-by-side comparison
• time-rs/time — Alternative datetime library in Rust ecosystem; COMPARE.md explicitly contrasts Jiff's design with time's approach
• unicode-org/icu4x — ICU internationalization library that can complement Jiff for locale-aware formatting; Jiff focuses on correctness, icu4x adds i18n layer
• dieselrs/diesel — SQL ORM for Rust; jiff-diesel crate (in workspace) is the official integration point, so Diesel users are primary consumers
• estebank/wyz — BurntSushi's personal utility crate used throughout Rust ecosystem; style and patterns in jiff reflect the author's broader Rust philosophy

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive integration tests for jiff-diesel database adapters

The jiff-diesel crate (crates/jiff-diesel/src) has implementations for MySQL, PostgreSQL, and SQLite database integrations, but there are no visible integration test files in the repo structure. This is critical for a database adapter library since behavior varies significantly across databases. New contributors could add integration tests that verify correct datetime serialization/deserialization across all three databases, including edge cases like timezone-aware timestamps, daylight saving time transitions, and null value handling.

• [ ] Create tests/jiff_diesel_mysql.rs to test MySQL datetime roundtrips using crates/jiff-diesel/src/mysql.rs
• [ ] Create tests/jiff_diesel_postgres.rs to test PostgreSQL datetime roundtrips using crates/jiff-diesel/src/postgres.rs
• [ ] Create tests/jiff_diesel_sqlite.rs to test SQLite datetime roundtrips using crates/jiff-diesel/src/sqlite.rs
• [ ] Add test containers or Docker Compose setup to CI workflow (.github/workflows/ci.yml) to run these tests

Add comprehensive benches for timezone-aware datetime arithmetic operations

The bench/src directory shows benchmarks exist for individual components (parse.rs, print.rs, tz.rs), but there's no dedicated benchmark for complex datetime arithmetic with timezone transitions—a core feature mentioned in the README. Since Jiff advertises 'DST aware arithmetic,' new contributors could add benchmarks that measure performance of operations like adding months/years across DST boundaries, which is critical for performance-conscious users.

• [ ] Create bench/src/arithmetic_dst.rs with benchmarks for operations like adding months that cross DST transitions
• [ ] Add benchmarks for rounding operations (mentioned in README) across timezone boundaries
• [ ] Integrate new benchmarks into bench/src/lib.rs and bench/Cargo.toml
• [ ] Document expected performance characteristics in DESIGN.md or a new bench/README.md

Add missing documentation for jiff-icu crate ICU integration features

The jiff-icu crate (crates/jiff-icu) exists with src/lib.rs, src/error.rs, and src/traits.rs files but has no specific documentation explaining how to use ICU integration for locale-aware formatting or parsing. The main README mentions Jiff's features but doesn't explain the jiff-icu integration. New contributors could add comprehensive docs showing practical examples of using ICU for timezone and locale handling.

• [ ] Create or expand crates/jiff-icu/README.md with specific examples of locale-aware formatting using ICU
• [ ] Document the traits in crates/jiff-icu/src/traits.rs with code examples in inline doc comments
• [ ] Add a section to the main README.md linking to jiff-icu as an optional integration
• [ ] Add example code to crates/jiff-icu showing integration with Jiff's datetime types

• Add integration tests for DST edge cases (e.g., 2:30 AM during spring-forward transitions) in new test file /tests/dst_edge_cases.rs; this exercises the checked_add() logic that is most error-prone.
• Expand examples/ or documentation in DESIGN.md with a concrete walkthrough of why chrono's chrono::Local::now() can silently fail vs. Jiff's explicit Zoned::now() error handling pattern.
• Add Serde roundtrip tests (parse JSON → Zoned → serialize back) under /src/ to ensure the serde feature (behind cfg) doesn't regress losslessness guarantees across releases.

The jiff datetime library codebase demonstrates strong security posture. No critical or high-severity vulnerabilities were identified. The codebase appears well-structured with proper separation of concerns across multiple crates (jiff-cli, jiff-diesel, jiff-sqlx, jiff-static, jiff-icu). No hardcoded secrets, credential files, or suspicious injection patterns were detected in the file structure. The library uses dual licensing (MIT/UNLICENSE), indicating transparency. Minor observations include incomplete feature documentation and the need for regular dependency auditing, particularly for platform-specific bindings. The Rust language choice provides memory safety guarantees that mitigate many common vulnerability classes. Recommendations focus on maintenance practices rather than remediation of existing issues.

• Low · Incomplete Cargo.toml Documentation — Cargo.toml. The Cargo.toml file has truncated documentation for the 'tz-fat' feature. The feature description ends abruptly with 'This uses a little extra heap memory (or binary size, when embe', which may indicate incomplete configuration or documentation. Fix: Complete the feature documentation to ensure all configuration options are clearly documented and properly understood by users.
• Low · Windows-sys Conditional Dependency — Cargo.toml (tz-system feature). The 'tz-system' feature conditionally includes 'windows-sys' as a dependency. While necessary for Windows platform support, ensure this dependency is regularly updated to patch any security vulnerabilities in the Windows FFI bindings. Fix: Regularly audit and update the windows-sys dependency. Consider using cargo-audit in CI/CD to detect known security vulnerabilities.
• Low · Test Configuration in Package Include — Cargo.toml (include field). The Cargo.toml includes '/tests/lib.rs' in the package to suppress warnings, but doesn't include the full test suite. This may cause confusion about test coverage and could mask missing test configurations. Fix: Either include the complete test suite or use a .gitignore approach instead. Document the rationale for this approach in comments.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.