feat(core): timeglyph-core — zero-dependency, MSRV-1.75 epoch arithmetic (ADR-0019)

[h4x0r]

Extracts timeglyph's epoch arithmetic into a new workspace member, timeglyph-core, per ADR-0019. Built under strict TDD: RED then GREEN.

Why

timeglyph cannot serve as a FOUNDATION dependency. It declares forensicnomicon = "1.3" (so the reverse edge is a cycle), pins rust-version = "1.96.0" (which has already raised a published parser's MSRV floor), and caps jiff below 0.2.33. ADR-0013 prescribes the mechanism: the lean <x>-core library plus the full <x> binary, for a dependency that is both a library primitive and a heavy tool.

The seam is integer arithmetic below, calendar and rendering above. (ft - EPOCH_OFFSET) * 100 needs nothing; ISO-8601 formatting needs jiff.

API

pub const FILETIME_EPOCH_OFFSET: u64 = 116_444_736_000_000_000;
pub const WEBKIT_EPOCH_OFFSET: u64 = 11_644_473_600_000_000;
pub const COCOA_EPOCH_OFFSET_SECS: i64 = 978_307_200;
pub const HFS_EPOCH_OFFSET_SECS: u32 = 2_082_844_800;

pub fn filetime_to_unix_ns(ft: u64) -> Option<i64>;
pub fn webkit_micros_to_unix_ns(us: u64) -> Option<i64>;
pub fn cocoa_secs_to_unix_ns(secs: f64) -> Option<i64>;
pub fn hfs_secs_to_unix_ns(secs: u32) -> Option<i64>;

Sentinel policy (the parser-facing contract): None for a zeroed field, for a value below the format's own epoch offset, and for i64-nanosecond overflow. Zero is not a special case — it is the smallest value below the offset, so one checked_sub covers both. Cocoa is the documented exception: a 2001 reference date makes negative values ordinary dates, so only 0.0 and the non-finite values are rejected there.

HFS+ fell out cleanly and is included. DOS/FAT is skipped: its packed date word needs a civil-date-to-day-count conversion, which is calendar math and belongs above the seam.

timeglyph is unchanged

No call site was migrated and no dependency was added, because no substitution is behaviour-preserving. timeglyph's converters are generic over an (epoch_ns, unit) pair from forensicnomicon's knowledge table, run on an i128 spine, and return a diagnostic ChronoError. Swapping in timeglyph-core would narrow the spine, replace the diagnostic with a bare None, and impose parser sentinels on the scanner. In particular secs::filetime still returns Some(-11_644_473_600) for input 0 — correct for a tool whose job is identifying what a value could decode to.

Provenance of the test vectors

No expected value was computed by hand. Each is a published epoch constant, or an instant an implementation independent of this crate already decodes the same way:

Value	Source
FILETIME / WebKit 1601 offsets	[MS-DTYP] §2.3.3; Chromium base/time/time.h (kTimeTToMicrosecondsOffset)
Cocoa 2001 offset	NSTimeIntervalSince1970, Foundation NSDate.h
HFS+ 1904 offset	Apple TN1150, HFS Plus Volume Format
FILETIME 132_223_104_000_000_000 = 2020-01-01T00:00:00Z	timeglyph's own crate-level doctest, which reaches that instant through jiff and the forensicnomicon table
Unix 1_614_601_815 = 2021-03-01T12:30:15Z (WebKit + Cocoa vectors)	secs::tests::civil_known_dates, likewise via jiff

A gate hole this found

cargo llvm-cov report does not inherit the previous run's package selection and rejects --workspace. A bare report --lcov therefore writes an LCOV with no record at all for a second member — the line half of the coverage gate passes over it having measured nothing, while the JSON/function half still sees it. That asymmetry is what makes it quiet. Both commands now name every member; verified the LCOV carries LF:23 LH:23 for timeglyph-core.

ci.yml test/clippy/fmt and the pre-commit clippy hook likewise needed --workspace/--all: with a root package present, cargo's default selection is that package alone.

Verification

Gate	Result
cargo test --workspace --all-features	537 passed, 0 failed (514 timeglyph unchanged, 23 new)
cargo clippy --workspace --all-targets --all-features -- -D warnings	clean
cargo fmt --all --check	clean
cargo deny check	advisories / bans / licenses / sources ok
coverage gate	timeglyph-core 23/23 lines, 4/4 functions
cargo +nightly fuzz run core_epochs	200,000 execs, no crash

MSRV. cargo +1.75.0 check -p timeglyph-core cannot run in-workspace: cargo 1.75 rejects the v4 Cargo.lock before it ever looks at this crate. Verified the way a crates.io consumer sees it instead, by copying core/ out of the repo — cargo +1.75.0 check --all-targets and cargo +1.75.0 test both pass, and the lockfile cargo generates there contains exactly one package, timeglyph-core. That is the zero-dependency claim checked rather than asserted.

Not done here

• No README badge or docs page for timeglyph-core yet.
• fuzz.yml's smoke loop still omits the pre-existing inspect_text target — unrelated to this change, left alone rather than folded in.

🤖 Generated with Claude Code