Event Envelope

The Universal Event Envelope is the wire format for every record on the ledger. Its published contract is the OpenAPI schema components.schemas.EventEnvelope in the API reference; the server validates every submission against it.

Required fields

{
  "event_family":            "claim",                    // one of EVENT_FAMILIES
  "event_type":              "CLAIM_SUBMITTED",
  "tenant_id":               "acme",
  "member_id":               "01HZZMEMBERID...",
  "source_system":           "EDI_CLAIMS_GW",
  "source_record_type":      "x12_837",
  "source_record_id":        "GW-2026-05-23-000123",
  "event_effective_timestamp": "2026-05-23T12:00:00Z",
  "payload":                 { "claim_amount_cents": 24500 }
}

Time model (BR-004)

Three timestamps are tracked separately and never collapsed:

• source_event_timestamp — when the source system says the event happened. Optional.
• event_effective_timestamp — when the event takes effect per the domain (e.g. a coverage start date). Required.
• event_observed_timestamp — when the platform first saw the event. Optional; the server stamps it on ingest if absent.

Provenance (BR-003)

Every envelope must identify the source system + record sufficient to recover the original artifact: source_system + source_record_type + source_record_id together act as a stable natural key. source_event_id is optional but recommended when the source emits its own per-event ID.

Correlation

Optional fields for graph linkage:

• correlation_id, causation_id — generic tracing IDs.
• parent_event_id — the prior event in a workflow chain.
• related_*_ids arrays — bind an envelope to claims, authorizations, prescriptions, disputes, documents, and rules. Each array caps at 256 IDs.

Outcome + classification

• outcome + outcome_reason — domain-specific enums (APPROVED, DENIED, etc.).
• data_classification — e.g. PHI, PII, PUBLIC.
• legal_hold_status, retention_policy_id — overrides for retention sweeps.

Payload

payload is a free-form JSON object. The envelope only guarantees it’s an object; each event_type has its own payload schema, validated by the domain module that handles that event downstream, not at the envelope boundary.

Hashing + chaining

On commit the server computes envelope_hash as SHA-256 over the canonical JSON serialization of the envelope. Events are chained per (tenant_id, member_id): each event’s chain_hash is SHA-256 over the previous event’s chain_hash, its chain_seqposition, and the event’s stored integrity fields (including envelope_hash). Editing any event breaks the next event’s chain_hash, and the verifier reports the first break. prev_event_hash still carries the previous envelope’s hash for compatibility; it is a pointer, not the chain. The full envelope bytes are also persisted to the WORM store; see WORM storage.