Timestamp, serialization, and deprecated cleanup

Author: Affie

docs/src/GraphData.md

@@ -44,7 +44,17 @@ Labels are the principle identifier of a variable or factor.
 
 #### Timestamps
 
-Each variable or factor can have a timestamp associated with it.
+Each variable or factor can have a timestamp associated with it representing when the physical event/observation occurred.
+
+**Time Standard**: Timestamps use UTC-based time (Coordinated Universal Time) via the `TimeDateZone` type, not TAI (International Atomic Time). The key difference is that UTC includes leap seconds to keep synchronized with Earth's rotation, while TAI is a continuous monotonic time scale without leap seconds.
+
+**Timezone Support**: While timestamps default to UTC (`tz"UTC"`), `TimeDateZone` supports any timezone (e.g., `tz"America/New_York"`, `tz"Europe/London"`). The timezone offset is preserved when stored and retrieved.
+
+**Event Time vs Database Time**: The timestamp represents the physical event time (when a sensor measurement was taken, when a robot was at a pose, etc.), not when the variable was added to the database. Database metadata timestamps may be tracked separately by specific backend implementations.
+
+**Temporal Uncertainty**: This single timestamp value is metadata and does not represent temporal uncertainty in non-parametric beliefs. For problems where time itself is a state variable requiring inference (e.g., using `SGal3` which includes temporal components), include time as part of your state type rather than relying on this metadata field.
+
+Related functions:
 
 - [`getTimestamp`](@ref)
 

src/Common.jl

@@ -187,7 +187,13 @@ function calcDeltatime(from::TimeDateZone, to::TimeDateZone)
 end
 calcDeltatime(from_node, to_node) = calcDeltatime(from_node.timestamp, to_node.timestamp)
 
-function tdz_now(zone = tz"UTC") #TODO or default to slower localzone()? 
+Timestamp(args...) = TimeDateZone(args...)
+Timestamp(epoch::Val{:unix}, t::Nanosecond, zone = tz"UTC") = TimeDateZone(TimeDate(1970) + t, zone)
+Timestamp(epoch::Val{:unix}, t::Float64, zone = tz"UTC") = Timestamp(epoch, Nanosecond(t * 10^9), zone)
+Timestamp(t::Float64, zone = tz"UTC") = Timestamp(Val(:unix), t, zone)
+Timestamp(epoch::Val{:rata}, t::Float64, zone = tz"UTC") = TimeDateZone(convert(DateTime,Millisecond(t*10^3)), zone)
+
+function now_tdz(zone = tz"UTC")
     t = time()
-    return TimeDateZone(TimeDate(1970) + Nanosecond(t * 10^9), zone)
+    return Timestamp(t, zone)
 end

src/DataBlobs/entities/BlobEntry.jl

@@ -44,7 +44,7 @@ StructUtils.@kwarg struct Blobentry
     """ Storage for a couple of bytes directly in the graph. Use with caution and keep it small and simple."""
     metadata::JSONText = JSONText("{}")
     """ When the Blob itself was first created. Serialized as an ISO 8601 string."""
-    timestamp::TimeDateZone = tdz_now()
+    timestamp::TimeDateZone = now_tdz()
     """ Type version of this Blobentry."""
     version::VersionNumber = DFG.version(Blobentry)
 end