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/chronotope/chrono 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 the board

• Last commit 5w ago
• 35+ active contributors
• Distributed ownership (top contributor 49% of recent commits)
• Other licensed
• CI configured
• Tests present
• ⚠ Non-standard license (Other) — review terms

_{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 chronotope/chrono repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/chronotope/chrono.

What it runs against: a local clone of chronotope/chrono — 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 chronotope/chrono | Confirms the artifact applies here, not a fork | | 2 | License is still Other | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 62 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of chronotope/chrono. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/chronotope/chrono.git
#   cd chrono
#
# 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 chronotope/chrono and re-run."
  exit 2
fi

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

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

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main 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 "src/datetime/mod.rs" \\
  && ok "src/datetime/mod.rs" \\
  || miss "missing critical file: src/datetime/mod.rs"
test -f "src/naive/datetime/mod.rs" \\
  && ok "src/naive/datetime/mod.rs" \\
  || miss "missing critical file: src/naive/datetime/mod.rs"
test -f "src/offset/mod.rs" \\
  && ok "src/offset/mod.rs" \\
  || miss "missing critical file: src/offset/mod.rs"
test -f "src/format/mod.rs" \\
  && ok "src/format/mod.rs" \\
  || miss "missing critical file: src/format/mod.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 62 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~32d)"
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/chronotope/chrono"
  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).

Chrono is a production-grade timezone-aware date and time library for Rust providing the DateTime<Tz> type with nanosecond accuracy, strftime-inspired formatting/parsing, and support for the proleptic Gregorian calendar. It handles timezone-naive operations via NaiveDateTime/NaiveDate/NaiveTime types and timezone-aware operations with pluggable timezone backends (UTC, fixed offsets, and compatibility with external crates like chrono-tz). Single-crate architecture with modular structure: src/naive/ contains timezone-naive types (date.rs, datetime/), src/datetime/ wraps them with timezone awareness, src/format/ handles parsing (parse.rs, scan.rs) and formatting (formatting.rs, strftime.rs), src/offset/ (inferred) manages timezone implementations. Serialization support isolated in datetime/serde.rs and naive/datetime/serde.rs. Benchmarks in bench/ and fuzz targets in fuzz/fuzz_targets/ for regression detection.

Rust developers building systems that need accurate date/time handling: backend services processing timestamps, financial applications requiring precise calculations, distributed systems needing timezone conversions, and CLI tools that format/parse user-provided dates. Contributors are typically Rust maintainers working on calendar logic, serialization support (serde/rkyv integration), or cross-platform timezone handling.

Highly mature and production-ready: version 0.4.44 with comprehensive CI (test.yml, lint.yml, codecov.yml workflows), test suites in src/datetime/tests.rs and src/naive/datetime/tests.rs, fuzzing infrastructure in fuzz/ directory, and active maintenance visible in the detailed Cargo.toml with multiple feature gates. This is a foundational crate widely used across the Rust ecosystem.

Relatively low risk: minimal dependency surface (num-traits, serde, pure-rust-locales only as optionals) reduces supply-chain attack surface. No timezone data shipped by design avoids binary bloat and maintenance burden, but users must explicitly add chrono-tz or tzfile for full timezone support—this is a deliberate architecture choice, not a gap. The MSRV (Rust 1.62.0) is conservative and well-maintained.

Active maintenance on v0.4.x branch with focus on serde/rkyv serialization compatibility, locale support (unstable-locales feature), and platform-specific fixes (winapi for Windows, wasm-bindgen for WebAssembly). Fuzzing infrastructure (fuzz_format.rs, fuzz_reader.rs) actively run in CI to catch edge cases in parsing/formatting.

git clone https://github.com/chronotope/chrono.git
cd chrono
cargo build
cargo test

Daily commands: No server to run—this is a library. For development: cargo build --all-features to compile with all serialization/locale/platform support. Run tests with cargo test --all-features. Benchmarks: cargo bench --bench chrono from the bench/ directory.

• src/lib.rs — Entry point and public API surface; defines all major types (DateTime, NaiveDateTime, Date, Time) and feature gates.
• src/datetime/mod.rs — Core DateTime<Tz> type with timezone-aware operations; the most-used abstraction in the library.
• src/naive/datetime/mod.rs — NaiveDateTime implementation (timezone-naive); foundation for timezone-aware DateTime calculations.
• src/offset/mod.rs — Offset trait and implementations (UTC, Fixed, Local); defines how timezones are represented and converted.
• src/format/mod.rs — Formatting and parsing orchestration; handles strftime directives and serialization across features.
• src/naive/internals.rs — Low-level calendar math and day-of-year calculations; critical for date arithmetic correctness.
• src/offset/local/mod.rs — Local timezone detection (platform-specific: Unix, Windows, WASM); enables Local offset resolution.

Add a new strftime format directive

1. Define the directive in the Spec enum (src/format/strftime.rs)
2. Implement formatting logic in the match statement (src/format/formatting.rs)
3. Implement parsing logic in the match statement (src/format/parse.rs)
4. Add test cases in the module's tests section (src/format/mod.rs)

Add support for a new timezone representation

1. Create a new struct implementing the Offset trait (src/offset/mod.rs)
2. Implement from_utc_datetime and with_offset methods (src/offset/mod.rs)
3. Add serialization support if needed (src/datetime/serde.rs)
4. Export the type from src/lib.rs if public (src/lib.rs)
5. Add tests in the offset module (src/offset/mod.rs)

Extend date/time arithmetic operations

1. Add method to the Datelike or Timelike trait (src/traits.rs)
2. Implement for NaiveDateTime (or NaiveDate/NaiveTime) (src/naive/datetime/mod.rs)
3. Implement for DateTime<Tz> via delegation (src/datetime/mod.rs)
4. Add tests to respective test modules (src/naive/datetime/tests.rs)

Add a new localization or locale variant

1. Add locale definition and month/weekday names (src/format/locales.rs)
2. Register in the locale matching logic (src/format/mod.rs)
3. Test locale resolution with various inputs (src/format/mod.rs)

• Rust generics and traits — Enable timezone-aware operations without runtime overhead; DateTime<Tz> parameterization is core to correctness and performance
• Proleptic Gregorian calendar math — Required for astronomical and historical correctness; implemented in src/naive/internals.rs with careful overflow handling
• strftime formatting — De facto standard for date formatting across languages; allows compatibility with C libraries and user expectations
• Feature flags (alloc, std, clock, wasmbind) — Support embedded, no_std, and WASM environments; granular control over platform dependencies
• Serde integration (optional) — First-class JSON/binary serialization support; essential for API and storage use cases
• Platform-specific offset resolution (libc, winapi) — Necessary for Local timezone; different APIs on Unix, Windows, and WASM; conditional compilation avoids bloat

• Naive types separate from timezone-aware types

  • Why: Prevents accidental mixed-timezone arithmetic and makes temporal logic explicit
  • Consequence: Users must consciously decide between NaiveDateTime and DateTime<Tz>; adds API surface but increases type safety

• Offset trait is zero-sized (stateless)

  • Why: Enables compile-time timezone verification and zero runtime cost for Fixed offsets
  • Consequence: Dynamic timezone databases (e.g., IANA tzdata with historical rules) require wrapper types; not built-in

• i64 nanoseconds for TimeDelta precision

  • Why: Matches system precision and enables cross-platform consistency
  • Consequence: Range is ±262 years; insufficient for very long durations (geological timescales)

• Strftime parsing is best-effort

  • Why: Some format strings are ambiguous (e.g., %d could be day or zero-padded day); avoids over-engineering
  • Consequence: Parsed values may differ slightly from intent; users should validate or use RFC 3339

• No built-in IANA tzdata; users must provide via external crates

  • Why: Reduces binary size and maintenance burden; tzdata changes frequently
  • Consequence: Real-world applications require chrono-

Feature combinations matter: some features are mutually exclusive (rkyv-16/32/64) and will compile-fail if combined—test with cargo build --features rkyv-16 --features rkyv-32 to catch this. MSRV is enforced: code must compile on Rust 1.62.0; newer syntax (e.g., let-else, bool::then_some) may fail on CI. Leap second handling is incomplete: NaiveTime can represent :60 but operations don't fully support it—document this when working with time. Timezone-naive by default: new users forget that DateTime::now() requires the clock feature; build fails silently if feature-gated code is not enabled. Fuzz corpus in fuzz/fuzz_targets/: corpus files may grow large and cause slow CI if not pruned; check fuzz/README.md for guidance.

• Proleptic Gregorian calendar — Chrono extends the Gregorian calendar backward to dates before its historical adoption (Oct 1582), which is essential for applications handling historical or fictional dates without discontinuities
• Offset trait pattern — Chrono's timezone-aware type DateTime<Tz> is generic over an Offset trait, allowing pluggable timezone backends (UTC, fixed, IANA) without core library changes—understanding this generic design is key to extending chrono
• MappedLocalTime enum — Handles ambiguous/invalid local times during DST transitions (e.g., 2:30 AM during spring-forward exists twice); Chrono returns MappedLocalTime::Ambiguous/Single/None instead of panicking—critical for correct timezone-aware code
• Ordinal date (day-of-year) numbering — Chrono uses ordinal dates (1–366) internally for efficient calculations; understanding Julian day number and ordinal conversions is essential when debugging calendar edge cases or implementing custom date algorithms
• Strftime format syntax — Chrono's formatting/parsing uses strftime directives (%Y, %m, %d, etc.); familiarity with this syntax is required to modify src/format/strftime.rs or document custom format strings
• Feature-gated serialization — Chrono's serde/rkyv support is optional and feature-gated; understanding why serialization is not always compiled (to keep binary size small) is crucial for troubleshooting 'no method serialize' errors in no_std contexts
• Nanosecond precision limits — Chrono uses i64 nanoseconds internally, limiting accuracy to ±262,000 years from epoch; understanding this bound is important when validating input or designing long-duration calculations

• chronotope/chrono-tz — Official companion crate providing IANA timezone data and implementations of the Offset trait for full timezone support beyond UTC/fixed offsets
• time-rs/time — Alternative Rust datetime library emphasizing const-time operations and no_std compatibility; common comparison point for users choosing between chrono and time
• servo/rust-chrono — Historical predecessor/inspiration; some design patterns in chrono's offset trait and naive types influenced by this project
• rustadventure/tzfile — IANA timezone file parser providing an alternative to chrono-tz for users wanting lighter-weight timezone resolution without bundling a database
• rust-lang/libs-team — Rust standard library discussion forum; chrono's design influences and is influenced by stdlib's time/duration types—relevant for understanding why chrono uses Duration rather than std::time::Duration in some contexts

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 timezone offset edge case tests in src/offset/fixed.rs

The fixed offset module handles critical timezone conversion logic but lacks explicit test coverage for edge cases like minute-level offsets, boundary values (±14:00), and invalid offset creation. This is high-value because offset bugs can silently corrupt datetime calculations across the entire library.

• [ ] Review src/offset/fixed.rs for undocumented edge cases (non-hour offsets, extreme values)
• [ ] Add unit tests for minute-level offsets (e.g., ±05:30, ±05:45)
• [ ] Add tests for boundary offsets (±14:00, ±13:00) and invalid creation attempts
• [ ] Add tests for offset arithmetic and comparison operations
• [ ] Verify tests run in both std and no_std contexts

Implement comprehensive fuzzing targets for format parsing in fuzz/fuzz_targets/

The fuzz directory has only 2 targets (fuzz_format.rs and fuzz_reader.rs) but src/format/parse.rs is complex with multiple format specifiers and parsing states. Expanding fuzzing coverage here would catch parsing panics and incorrect output that unit tests miss, protecting users from DoS or silent data corruption.

• [ ] Analyze src/format/parse.rs and src/format/strftime.rs for parsing edge cases
• [ ] Add fuzz_targets/fuzz_strftime_parsing.rs targeting strftime format specifier combinations
• [ ] Add fuzz_targets/fuzz_offset_parsing.rs targeting timezone offset string parsing
• [ ] Add fuzz_targets/fuzz_datetime_parse_from_str.rs targeting DateTime::parse_from_str edge cases
• [ ] Run fuzzing locally and commit seed corpus if crashes found

Add platform-specific timezone behavior tests for src/offset/local/

The local timezone module has platform-specific implementations (unix.rs, windows.rs, tz_data.rs) but src/offset/local/tests.rs is missing or sparse. Platform-specific bugs in timezone detection cause silent failures across major deployment environments. Adding tests for DST transitions, timezone database consistency, and platform behavior would catch regressions.

• [ ] Check if tests exist in src/offset/local/mod.rs or create src/offset/local/tests.rs
• [ ] Add tests for DST transition dates (spring forward, fall back edge cases)
• [ ] Add tests verifying local offset matches system clock at known times
• [ ] Add Windows-specific tests (via #[cfg(windows)]) for windows.rs timezone detection
• [ ] Add Unix-specific tests for tz_info parsing against standard IANA database samples
• [ ] Add integration tests in tests/ directory that verify local timezone matches system

• Add locale-specific formatting tests to src/format/tests.rs for non-English day/month names—the unstable-locales feature exists but test coverage is sparse; start by running cargo test --all-features and noting which locale combinations fail, then add test cases to src/format/mod.rs.
• Document leap second behavior in docstrings for src/naive/datetime/mod.rs and src/naive/time.rs (search for 'leap' in README shows this is a known limitation)—write a detailed explanation with examples of what works and what doesn't, then link it from the 'Limitations' section in README.md.
• Extend fuzz_targets/fuzz_format.rs to cover custom strftime format strings beyond the current corpus—add a grammar-based fuzzer that generates valid/invalid format strings from src/format/strftime.rs patterns, then run locally to find edge cases in parsing logic.

The Chrono codebase shows a generally secure posture as a well-maintained date/time library. Key strengths include: proper use of optional dependencies with feature flags, inclusion of fuzzing infrastructure, and clear separation of platform-specific code. Primary concerns are: (1) an incomplete/truncated dependency specification in Cargo.toml that requires immediate attention, (2) the need for robust timezone data management and update procedures, and (3) standard considerations for any library dealing with time-sensitive security operations. No hardcoded secrets, injection vulnerabilities, or obvious misconfigurations were detected in the provided file structure.

• Medium · Incomplete Windows Dependency Configuration — Cargo.toml (line with windows-link dependency). The Cargo.toml file has a truncated dependency specification for 'windows-link' under [target.'cfg(windows)'.dependencies]. The line ends with 'op' which appears to be incomplete, potentially indicating a misconfigured dependency version or feature specification that could lead to unexpected behavior or security issues on Windows platforms. Fix: Complete the windows-link dependency specification with proper version constraints and validate all platform-specific dependencies are correctly configured.
• Low · Fuzzing Infrastructure Accessibility — fuzz/ directory. The repository includes a fuzzing harness directory (/fuzz) with fuzz targets for format parsing and reader functionality. While fuzzing is a good security practice, ensure the fuzzing infrastructure and any discovered crashes are tracked and remediated promptly. Fix: Establish a process for regular fuzzing runs and timely patching of discovered issues. Consider integrating continuous fuzzing via OSS-Fuzz or similar services.
• Low · Timezone Data Security Considerations — src/offset/local/tz_data.rs, src/offset/local/tz_info/. The codebase includes timezone data handling (tz_data.rs, tz_info/) and local timezone resolution for multiple platforms (Unix, Windows, WASM). Timezone database updates are critical for security and correctness, especially for DST transitions and security-relevant time calculations. Fix: Implement automatic updates for timezone data files and document the source and update frequency of timezone information. Monitor for timezone-related security advisories.

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.