#MVP Event Scope

Source of truth: ../simiaroom-cx-v5.md Event Dictionary.

MVP does not require every dictionary event on day one. Prioritize events that power funnel, retention, risk, fit, and light actions.

#Initial integration slice — first 8–12 authoritative events

Before expanding across the full P0 target set, prove collection, reconciliation, state derivation, and reporting with this backend-first slice:

Expansion is allowed only after the slice meets the agreed completeness, duplicate, latency, and invalid-event targets.

#Priority P0 target set — introduce incrementally

#Priority P1 — Month 2–3 if capacity

#Priority P2 — post-MVP / nice-to-have

Fine-grained UI clicks that do not change state (many ENT/GA micro-events), optional insurance/refund deep paths, advanced quality review events — keep schema-ready but do not block MVP screens.

#Event envelope (canonical) — locked v1

Status: locked for SDK + collector (T0.4). Delivery, retries, and validation live in SDK-AND-DATA-INGESTION.md and must not contradict this section.

Every ingested event maps to envelope v1 below. SDKs never write storage; they only send this envelope to the collector.

#Required sender fields

Also required on the wire (already in the SDK contract): event_version, project_id, environment.

#Compatibility with the SDK wire shape

Do not treat these as different events:

source is a producer ID (simiaroom_backend, simiaroom_booking, cx_orbit_browser, porsline, import, cx_orbit_system, …). The older sketch enum browser\|backend\|ga\|… is a channel hint only; do not use it as the uniqueness key.

#Identity refs

"identity": {
  "anonymous_id": "string|null",
  "user_id": "string|null",
  "session_id": "string|null"
}

• session_id here is the analytics/web session, not the therapy session. Therapy sessions use entity.type = "session" and/or properties.session_id.
• Authoritative backend P0 outcomes require user_id.
• Browser behavioral events may send anonymous_id with user_id: null until identify/link.
• At least one of anonymous_id or user_id is required except for approved actor.type = system events that are not client-scoped (rare; must be in the event contract).
• Browser consent, ID storage, and send-minimization: BROWSER-CONSENT-POLICY.md (T1.14). Backend P0 events are not consent-gated.

actor (required): { "type": "user|system|staff|internal", "id": "string" }.

#Entity refs

"entity": { "type": "booking|session|payment|assessment|client|therapist|case|identity_link|…", "id": "string" }

Related entities go in properties (e.g. therapist_id on a booking event). properties must not repeat a different ID for the same entity.type.

#Collector-owned fields (never trusted from sender)

received_at, ingestion / request ID, authentication result, validation status, collector version.

#Idempotency (locked)

Canonical idempotency key = project_id + source + source_event_id.

This is the DoD key source + source_event_id, scoped by project_id (envelope already includes project_id; MVP project is simiaroom).

source_event_id must uniquely identify one fact within that source. Do not reuse a bare entity PK across different event types (a booking can be confirmed and later cancelled). Prefer the source outcome row ID. If the source has no outcome ID and the type can fire at most once per entity, use {canonical_type}:{entity.id}.

Transport dedup (SDK retries of the same envelope, unchanged from the ingestion doc) = project_id + event_id. This does not replace the canonical key. Same event_id retry → one raw row. New event_id with the same canonical key → no second canonical fact (see duplicate behavior).

#Duplicate / late / out-of-order

Exactly-once delivery is out of scope. At-least-once + these keys is the contract.

Collector HTTP success/partial/reject shapes, retryable vs permanent codes, quarantine fields, and resubmit item codes (DUPLICATE_EVENT_ID, DUPLICATE_CANONICAL_KEY, IDEMPOTENCY_CONFLICT, EVENT_ID_REUSED) are locked in SDK-AND-DATA-INGESTION.md §11 (T1.13).

#Timezone (locked)

• Store occurred_at, sent_at, and collector received_at as UTC (Z).
• If the sender supplies offset/local time, convert to UTC; keep the sender zone in context.timezone when known.
• properties.user_timezone / slot local times are scheduling display fields, not the storage clock.
• Display in CX Orbit UI and calendar-day metrics: Asia/Tehran (IANA; DST handled by the zone), unless a report explicitly says otherwise.

#Locked envelope shape

{
  "event_id": "0198a1c2-3b4d-7e8f-9a0b-1c2d3e4f5a6b",
  "canonical_type": "booking_confirmed",
  "event_name": "booking_confirmed",
  "event_version": 1,
  "project_id": "simiaroom",
  "environment": "production",
  "source": "simiaroom_backend",
  "source_event_id": "bkg_evt_confirm_789",
  "source_version": "3.18.0",
  "occurred_at": "2026-08-03T10:20:30.123Z",
  "sent_at": "2026-08-03T10:20:31.004Z",
  "sdk": { "name": "@cx-orbit/node", "version": "0.2.0" },
  "actor": { "type": "system", "id": "booking-service" },
  "identity": {
    "anonymous_id": null,
    "user_id": "usr_123",
    "session_id": null
  },
  "entity": { "type": "booking", "id": "bkg_789" },
  "journey_ref": "J-04",
  "context": {
    "request_id": "req_123",
    "timezone": "Asia/Tehran",
    "locale": "fa"
  },
  "properties": {
    "therapist_id": "thr_456",
    "payment_id": "pay_456",
    "slot_id": "slot_1001",
    "session_number": 1,
    "user_timezone": "Asia/Tehran",
    "booking_context": "first_session",
    "scheduled_start_utc": "2026-08-10T14:00:00Z"
  }
}

#P0 examples

Full JSON for three initial-slice types is in SDK-AND-DATA-INGESTION.md §7.6. Summary:

#Producer-of-record rules

Every canonical event must have one producer of record. Duplicate observations from other sources may be retained as diagnostic events but must not create duplicate business facts.

#State update rule

Current Event + Current State + Accumulated History + Global Flags → Interpretation → Next State / Action

Not every click changes state. Prefer PRODUCT/status events for stage transitions; use GA for conversion diagnostics.

#Mapping checklist (engineering)

• Publish mapping table: Simiaroom source field → canonical event + properties — SOURCE-EVENT-MAPPING.md (T1.3)
• Define idempotency keys per source — locked: project_id + source + source_event_id (T0.4)
• Define late/duplicate event handling — locked in envelope section above (T0.4)
• Define timezone policy (store UTC, display Asia/Tehran) — locked (T0.4)
• Define which events trigger SYS-01 recompute — initial list in SOURCE-EVENT-MAPPING.md § SYS-01 recompute triggers (T1.3)
• Assign producer of record and owner to every P0 event — SOURCE-EVENT-MAPPING.md + SOURCE-OWNERSHIP.md (T1.3)
• Add event version, privacy class, required fields, and allowed enums — initial 12-event slice in fixtures/events/contracts.yaml (T1.12)
• Add schema fixtures to CI for backend and browser SDKs — backend 12-event slice: docs/fixtures/events/, packages/shared/schemas/events/, pnpm --filter @cx-orbit/shared test (T1.12; browser SDK deferred T2.13)
• Define retryable/non-retryable collector responses — locked T1.13 in SDK-AND-DATA-INGESTION.md §11.5–§11.6
• Define reconciliation query for every authoritative P0 event — per-type queries in SOURCE-EVENT-MAPPING.md § Initial 12-event slice (T1.3); remaining authoritative rows include CDC target table