Source ID & Revisions

Source ID Generation

Source IDs are deterministic hashes generated by Nexus:

source_id = sha256_hex(event_type + ":" + provider + ":" + provider_native_id)

Properties

• Idempotent — Same input always produces the same ID. Safe for re-fetch and replay.
• Collision-free — Scoped by event type and provider.
• Opaque — Does not leak provider internals to consumers.

The raw provider ID is always preserved in provider_ref for debugging and provider API lookups.

Example

For a Fitbit activity with provider ID "12345":

sha256_hex("activity:fitbit:12345")
// → "a1b2c3d4e5f6..."

Revision Semantics

The revision field on data items signals whether a delivery is a first observation or a correction:

revision	Meaning
1	First delivery of this data point.
2+	Provider retroactively corrected or updated the data. Consumers should upsert by source_id.

Nexus determines revisions by comparing the incoming normalized payload against the previously stored version for the same source_id. If the payload differs, revision increments.

Tip

Consumer upsert pattern: Use source_id as the unique key and revision to decide whether to update. A higher revision always supersedes a lower one for the same source_id.

Replay and Backfill

During replay or backfill:

• The source_id remains the same (deterministic from the same underlying data).
• The event_id on the envelope is new (unique per emission).
• The sources array is empty [] (no notification triggered the event).
• Consumers should use source_id + revision for deduplication, not event_id.