Module timestamp 

Shared timestamp-unit normalization for all STT input adaptors.

Every input reader — the GeoParquet scalar (--time-field) and per-vertex (vertex_timestamps) paths in stt-build, the DuckDB reader, and the stt-optimize analysis loader — must scale a producer’s raw integer timestamp to the STT wire unit (Unix milliseconds) identically. This is the one source of truth for that arithmetic so a new reader can’t silently disagree.

Enums

TimestampUnit

Precision of a raw integer timestamp value. Used to normalize any producer’s unit to the STT wire unit (Unix milliseconds).

Functions

normalize_timestamp_to_ms

Normalize a raw integer timestamp value in unit to Unix milliseconds, rejecting pre-1970 (negative) instants and overflow-checking the second→millisecond multiply. row is the absolute row index, used only for error context.

reject_negative_timestamp

Pre-1970 timestamps cannot be represented — the temporal index stores unsigned ms-since-epoch, so a negative value would wrap to a huge positive one (as u64) and silently corrupt the index. This hard-errors regardless of strictness mode; coercion is never sound here.

scale_timestamp_to_ms

Scale a raw timestamp value in unit to signed Unix milliseconds WITHOUT the non-negative guard. Second→ms is overflow-CHECKED (any realistic date fits; a value that doesn’t is corrupt input and must error, never silently saturate). This is the single source of truth for timestamp-unit scaling arithmetic — Second ×1000, Millisecond passthrough, Microsecond ÷1_000, Nanosecond ÷1_000_000 — shared by normalize_timestamp_to_ms (which adds the guard + u64 cast) and the DuckDB reader’s timestamp_unit_to_ms (which keeps signed ms so a timestamp emitted as a plain property may legitimately be pre-1970). Callers that need a wire timestamp apply reject_negative_timestamp themselves.