Crate timeglyph 

timeglyph — forensic timestamp decipherment.

A timestamp is time inscribed as a symbol — the raw integer or bytes a system writes to mean an instant. This crate deciphers those inscriptions: it decodes a known format to an instant, encodes an instant to any format, and — the differentiator — identifies an unknown value by reporting every plausible interpretation, scored, with stated assumptions, never “the answer” (a single integer is usually underdetermined).

Design (see HANDOFF.md for the full record)

• Canonical spine: PosixNs — nanoseconds since the Unix epoch, proleptic Gregorian, leap-second-ignoring (POSIX). It is not called UTC: UTC has discontinuities POSIX pretends away. Leap-aware scales (TAI/GPS/NTP) get their own instant types (to be added behind a hifitime feature).
• Calendar/tz math is reused (jiff), never reinvented. The value-add is the cited forensic format registry + scored auto-detection + byte decode.
• Panic-free (Paranoid Gatekeeper): every length/offset/width is checked.

Example

// Identify an unknown value: every plausible reading, ranked and scored —
// never a single verdict (a raw value is usually underdetermined).
let candidates = timeglyph::interpret::interpret_int(1_577_836_800);
let top = &candidates[0];
assert_eq!(top.format_id, "unix");
assert_eq!(top.rendered.as_deref(), Some("2020-01-01T00:00:00Z"));

// Or decode under one known format by id.
let filetime = timeglyph::format("filetime").unwrap();
let instant = filetime.decode_int(132_223_104_000_000_000).unwrap();
assert_eq!(instant.to_rfc3339().as_deref(), Some("2020-01-01T00:00:00Z"));

Further reading

The authoritative, primary-source-cited reference for every supported format — epochs, encodings, calendars, leap seconds, and the rollovers that eventually break them — lives at https://securityronin.github.io/timeglyph/.

Modules

csv_enrich

CSV enrichment: add human-readable timestamp columns to a CSV.

interpret

Auto-detection: identify an unknown value by reporting EVERY plausible interpretation, scored, with stated assumptions — never “the detected format.” A single integer is usually underdetermined: a 64-bit value can be a plausible Unix-s, Java-ms, Chrome-µs, FILETIME, .NET-ticks and Cocoa-s date all at once. Presenting one as the answer would fabricate certainty, which a forensic tool must never do (epistemics: “consistent with”, not a verdict).

registry

The forensic format registry.

Structs

Format

One forensic timestamp format: evidence metadata, not just a converter.

PosixNs

The canonical internal instant: nanoseconds since 1970-01-01, POSIX (leap-ignoring), proleptic Gregorian. i128 because some source epochs sit

Enums

ChronoError

Errors from decoding, encoding, or rendering a timestamp.

LeapSemantics

Leap-second semantics — the partition Codex flagged. Most forensic epochs are POSIX (leap-ignoring); only the GPS/TAI/NTP family needs true leap math.

Strategy

How a stored value maps to an instant.

TzSemantics

Timezone semantics of a format’s stored value — NOT garnish: FAT stores local time, EXIF often lacks an offset, Event Logs store UTC but display local.

Unit

The tick unit a format counts in.

Functions

format

Look up a registered format by id.