Add extended runtime + ParsedDateTime API for large years

[abhishekpradhan]

Summary

• add ExtendedDateTime runtime support for years beyond Jiff's in-range civil datetime support
• introduce ParsedDateTime (InRange | Extended) as the direct return type from parser entry points
• route parsing/building through an extended path for large-year and boundary-rollover cases
• preserve GNU-compatible relative month/year semantics in both in-range and extended flows
• add focused regression/coverage tests for rollover, parity behavior, offsets, error paths, named-timezone in-range transitions, and fuzz lockfile consistency

Breaking Change

This PR intentionally changes the public API of parse_datetime:

• parse_datetime(...) now returns Result<ParsedDateTime, ParseDateTimeError>
• parse_datetime_at_date(...) now returns Result<ParsedDateTime, ParseDateTimeError>

To reflect that, the crate version is bumped from 0.14.0 to 0.15.0.

Context

• follows merged groundwork PR: Groundwork: widen year parsing bounds for GNU max year #261
• this PR is the runtime/API step, including the tests needed to keep CI and coverage green
• the remaining follow-up after this is limited to parity coverage cleanup on top of this API shape

Reviewer Guide

1. Breaking API surface
   • src/lib.rs
   • README.md
2. Runtime behavior and correctness
   • src/items/builder.rs
   • src/extended.rs
3. Parser wiring updates
   • src/items/mod.rs
   • src/items/epoch.rs
   • src/items/offset.rs
4. Behavioral evidence tests
   • tests/large_year.rs
   • tests/time.rs
   • module tests in src/items/mod.rs, src/items/builder.rs, src/extended.rs

Validation

• cargo fmt --all -- --check
• cargo clippy --all-targets -- -D warnings
• cargo test -q
• cd fuzz && cargo generate-lockfile

[codecov]

Codecov Report

❌ Patch coverage is 99.53846% with 6 lines in your changes missing coverage. Please review.
✅ Project coverage is 99.29%. Comparing base (4a1b3f3) to head (379042f).
⚠️ Report is 9 commits behind head on main.

Files with missing lines	Patch %	Lines
src/items/builder.rs	99.06%	4 Missing ⚠️
src/items/mod.rs	99.41%	1 Missing ⚠️
src/lib.rs	98.76%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #263      +/-   ##
==========================================
+ Coverage   98.92%   99.29%   +0.37%     
==========================================
  Files          18       20       +2     
  Lines        2605     3847    +1242     
  Branches       69      121      +52     
==========================================
+ Hits         2577     3820    +1243     
+ Misses         27       26       -1     
  Partials        1        1              

Flag	Coverage Δ
macos_latest	99.29% <99.53%> (+0.37%)	⬆️
ubuntu_latest	99.29% <99.53%> (+0.37%)	⬆️
windows_latest	14.21% <1.38%> (-6.21%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[abhishekpradhan]

Status update: I closed the two superseded fork-only stacked PRs to reduce review noise.

• Add extended runtime + ParsedDateTime API for large years abhishekpradhan/parse_datetime#1
• Add large-year parity tests and README updates abhishekpradhan/parse_datetime#2

This PR is now the active runtime/API review path. The tests/docs follow-up (clean PR3 branch) is prepared and will be opened upstream immediately after this merges.

[abhishekpradhan]

Quick status update: this PR is now back on the direct ParsedDateTime API and bumped to 0.15.0, per the thread above. The README/docs, tests, and fuzz lockfile have been updated to match that shape, and local fmt / clippy / test checks are clean.

The only follow-up I still have staged separately is some additional parity coverage in tests/date.rs. My preference is to keep that as a small PR3 so review here stays focused on the runtime/API change, but I can also fold it into this PR if that’s preferable.

[abhishekpradhan]

Heads up: the repo About text still says this crate returns a jiff::Zoned, will have to be updated after we merge this PR

[sylvestre]

thanks!
i will push a follow up pr