Timestamp Semantics Reference

Metadata

• Owner: Origo Engineering
• Last updated: 2026-04-14
• Slice/version reference: S45

Purpose and scope

• Runtime and operator reference for how Origo interprets source_event_time_utc and auxiliary time fields for every canonical family.
• Scope covers the central timestamp-semantics registry, the closed quality taxonomy, canonical-vs-auxiliary timing meaning, and the runtime surfaces that consume those meanings.
• This is a runtime reference. The authoritative machine contract is contracts/canonical-source-timestamp-semantics-v1.json.

Authoritative surfaces

• Machine-readable registry:
  • contracts/canonical-source-timestamp-semantics-v1.json
• Envelope field governed by the registry:
  • contracts/canonical-event-envelope-v1.json
  • origo/events/envelope.py
• Supporting but subordinate timing surfaces:
  • contracts/canonical-source-authority-v1.json
  • contracts/canonical-source-precision-v1.json

Quality taxonomy

• realtime_event
  • canonical time is normalized directly from a source-native event timestamp
• batch_observation_day
  • canonical time is the UTC-midnight observation boundary derived from a date-valued fact
• consensus_time
  • canonical time is blockchain consensus-declared time and is not guaranteed monotonic
• snapshot_time
  • canonical time is Origo capture snapshot time rather than a source-native event-occurrence clock

Cross-family rules

• The registry is keyed by (source_id, stream_id).
• source_event_time_utc is the canonical family time reference, not always the highest-precision source-native event clock.
• DateTime64(9, 'UTC') is the storage container, not a claim that all families provide nanosecond precision.
• contracts/canonical-source-precision-v1.json stays subordinate numeric-field metadata only; it does not define canonical-vs-auxiliary timing meaning.
• Aligned projection always buckets on canonical source_event_time_utc.
• API/operator freshness may use canonical time or an explicitly declared auxiliary time basis, depending on family.

Family summary

• Binance / OKX / Bybit
  • canonical time: exchange trade timestamp
  • quality class: realtime_event
  • freshness basis: canonical source_event_time_utc
• ETF
  • canonical time: UTC-midnight observation boundary derived from as_of_date
  • quality class: batch_observation_day
  • freshness basis: latest_observed_day_from_source_event_time_utc
  • auxiliary times may include proof_of_reserves_timestamp_utc and fund_data_updated_at_utc
• FRED
  • canonical time: UTC-midnight observation boundary derived from observation_date
  • quality class: batch_observation_day
  • freshness basis: provenance.last_updated_utc
  • auxiliary times include provenance.realtime_start, provenance.realtime_end, and provenance.last_updated_utc
• Bitcoin blockchain-derived families
  • canonical time: consensus block time
  • quality class: consensus_time
  • freshness basis: canonical source_event_time_utc
  • monotonicity is not guaranteed relative to block height
• Bitcoin mempool
  • canonical time: Origo capture snapshot time
  • quality class: snapshot_time
  • freshness basis: canonical source_event_time_utc
  • auxiliary time: first_seen_timestamp from Bitcoin Core payload

Operator reading rules

• Canonical time answers “what time reference should serving, aligned projection, and current-truth runtime use for this family?”
• Auxiliary time answers “what other time-like facts should operators use for freshness or provenance?”
• ETF and FRED are intentionally not precise event-time families even though they still occupy a timestamp column.
• Bitcoin consensus time must never be treated as monotonic ordering authority; block height remains the durable cadence reference.
• Bitcoin mempool first_seen_timestamp is provenance only. It does not replace canonical snapshot time.