# OSHUN Analytics Event Dictionary

> Canonical event definitions for the OSHUN platform. Naming follows
> [ADR-0006](adr/ADR-0006-analytics-taxonomy-and-event-naming.md):
> `<namespace>.<entity>.<action>` (dot-delimited, lowercase, snake_case words).

---

## Event Envelope (Required Fields)

Every event MUST include the following envelope fields:

| Field               | Type    | Description                                      |
| ------------------- | ------- | ------------------------------------------------ |
| `event_id`          | string  | Globally unique ID (`evt_<random>`)              |
| `event_name`        | string  | Canonical dot-delimited name                     |
| `event_version`     | integer | Schema version, starts at `1`                    |
| `occurred_at`       | string  | ISO-8601 UTC timestamp                           |
| `platform`          | enum    | `ios`, `android`, `web`, `pwa`, `server`         |
| `surface`           | enum    | `mobile_shell`, `web_shell`, `domain_app`, `bff` |
| `session_id`        | string  | Client session identifier                        |
| `domain_context`    | enum    | `oshun_shell`, `tara`, `veritas`, `nyx`, `arete` |
| `consent_analytics` | boolean | Whether user has granted analytics consent       |
| `user_id`           | string? | Authenticated user ID (if available)             |
| `anonymous_id`      | string? | Anonymous device/session ID (if no user_id)      |
| `app_version`       | string? | Application version string                       |
| `locale`            | string? | User locale (e.g. `en-US`)                       |

At least one of `user_id` or `anonymous_id` MUST be present.

---

## Lifecycle Events

### `oshun.app.opened`

Fired when the OSHUN shell starts up.

| Property         | Type    | Description                            |
| ---------------- | ------- | -------------------------------------- |
| `entry`          | enum    | `cold` or `warm`                       |
| `startup_ms`     | integer | Time from process start to first frame |
| `had_font_error` | boolean | Whether custom fonts failed to load    |

### `oshun.app.backgrounded`

Fired when the app moves to the background.

| Property     | Type    | Description                        |
| ------------ | ------- | ---------------------------------- |
| `session_ms` | integer | Duration of the foreground session |
| `active_tab` | string  | Tab visible when backgrounded      |

### `oshun.app.resumed`

Fired when the app returns from background.

| Property        | Type    | Description              |
| --------------- | ------- | ------------------------ |
| `background_ms` | integer | Time spent in background |

---

## Authentication Events

### `oshun.auth.completed`

Fired when a user signs in or signs up.

| Property | Type    | Description                                                      |
| -------- | ------- | ---------------------------------------------------------------- |
| `method` | enum    | `email`, `google`, `apple`, `github`, `other`                    |
| `is_new` | boolean | Whether this was a new registration                              |
| `source` | string  | Screen that initiated auth (`onboarding`, `settings`, `paywall`) |

### `oshun.auth.signed_out`

Fired when a user signs out.

| Property | Type | Description                         |
| -------- | ---- | ----------------------------------- |
| `reason` | enum | `user`, `session_expired`, `forced` |

### `oshun.auth.token_refreshed`

Fired when an access token is silently refreshed.

| Property     | Type    | Description                             |
| ------------ | ------- | --------------------------------------- |
| `success`    | boolean | Whether the refresh succeeded           |
| `latency_ms` | integer | Round-trip time for the refresh request |

---

## Onboarding Events

### `oshun.onboarding.started`

Fired when the onboarding flow begins.

| Property | Type | Description                                 |
| -------- | ---- | ------------------------------------------- |
| `source` | enum | `first_launch`, `account_created`, `forced` |

### `oshun.onboarding.step_completed`

Fired when an onboarding step is completed.

| Property      | Type    | Description                                                             |
| ------------- | ------- | ----------------------------------------------------------------------- |
| `step_name`   | string  | Name of the step (`welcome`, `domains`, `preferences`, `notifications`) |
| `step_index`  | integer | 0-based step index                                                      |
| `total_steps` | integer | Total steps in the flow                                                 |
| `duration_ms` | integer | Time spent on this step                                                 |

### `oshun.onboarding.completed`

Fired when onboarding finishes.

| Property            | Type     | Description                      |
| ------------------- | -------- | -------------------------------- |
| `total_duration_ms` | integer  | Total time spent in onboarding   |
| `steps_completed`   | integer  | Number of steps completed        |
| `steps_skipped`     | integer  | Number of steps skipped          |
| `domains_selected`  | string[] | Domains the user chose to enable |

### `oshun.onboarding.abandoned`

Fired when the user exits onboarding without completing.

| Property      | Type    | Description                            |
| ------------- | ------- | -------------------------------------- |
| `last_step`   | string  | The last step viewed before abandoning |
| `step_index`  | integer | 0-based index of the last step         |
| `duration_ms` | integer | Total time before abandoning           |

---

## Navigation Events

### `oshun.tab.viewed`

Fired when a tab becomes visible.

| Property        | Type    | Description                              |
| --------------- | ------- | ---------------------------------------- |
| `tab`           | enum    | `home`, `explore`, `activity`, `profile` |
| `route`         | string  | Full route path                          |
| `transition_ms` | integer | Navigation transition time               |

### `oshun.route.transitioned`

Fired on every route change.

| Property        | Type    | Description                            |
| --------------- | ------- | -------------------------------------- |
| `from_route`    | string? | Previous route (null on first load)    |
| `to_route`      | string  | Destination route                      |
| `transition_ms` | integer | Navigation transition time             |
| `source`        | enum    | `app_start`, `navigation`, `deep_link` |

### `oshun.domain.launched`

Fired when a domain module is opened from the shell.

| Property     | Type    | Description                                              |
| ------------ | ------- | -------------------------------------------------------- |
| `domain`     | enum    | `tara`, `veritas`, `nyx`, `arete`                        |
| `source`     | enum    | `home`, `explore`, `deep_link`, `notification`, `search` |
| `latency_ms` | integer | Time to domain-ready state                               |
| `success`    | boolean | Whether the launch succeeded                             |

---

## Engagement Events

### `oshun.item.saved`

Fired when a user saves/bookmarks content.

| Property       | Type     | Description                                                                                       |
| -------------- | -------- | ------------------------------------------------------------------------------------------------- |
| `domain`       | enum     | `tara`, `veritas`, `nyx`, `arete`, `nisaba`                                                       |
| `item_id`      | string   | Domain-specific item identifier                                                                   |
| `item_type`    | string   | Canonical saved object type (`meditation`, `claim`, `source`, `passage`, `notebook`, `sky-event`) |
| `source`       | enum?    | Optional origin surface: `home`, `explore`, `assistant`, `library`                                |
| `surface`      | enum?    | Optional UI surface: `panel`, `dashboard`, `results-page`, `message`, `saved-items`               |
| `target_path`  | string?  | Optional launch path captured for the saved item                                                  |
| `query_length` | integer? | Optional query length when the save happened from search                                          |
| `result_count` | integer? | Optional rendered result count when the save happened from search                                 |
| `position`     | integer? | Optional rendered result position when the save happened from search                              |

### `oshun.item.unsaved`

Fired when a user removes a bookmark.

| Property       | Type     | Description                                                                                       |
| -------------- | -------- | ------------------------------------------------------------------------------------------------- |
| `domain`       | enum     | `tara`, `veritas`, `nyx`, `arete`, `nisaba`                                                       |
| `item_id`      | string   | Domain-specific item identifier                                                                   |
| `item_type`    | string   | Canonical saved object type (`meditation`, `claim`, `source`, `passage`, `notebook`, `sky-event`) |
| `source`       | enum?    | Optional origin surface: `home`, `explore`, `assistant`, `library`                                |
| `surface`      | enum?    | Optional UI surface: `panel`, `dashboard`, `results-page`, `message`, `saved-items`               |
| `target_path`  | string?  | Optional launch path captured for the unsaved item                                                |
| `query_length` | integer? | Optional query length when the unsave happened from search                                        |
| `result_count` | integer? | Optional rendered result count when the unsave happened from search                               |
| `position`     | integer? | Optional rendered result position when the unsave happened from search                            |

### `oshun.activity.reentry_opened`

Fired when a user follows a re-entry affordance from the Activity timeline.

| Property            | Type     | Description                                                                    |
| ------------------- | -------- | ------------------------------------------------------------------------------ |
| `surface`           | enum     | `timeline`                                                                     |
| `trigger`           | enum     | `thread`, `step`, `assistant-highlight`, `study-continuation`                  |
| `target_kind`       | enum     | `domain`, `library`, `workspace`, `shell`                                      |
| `target_path`       | string   | Destination path opened from Activity                                          |
| `primary_domain`    | enum     | `tara`, `veritas`, `nyx`, `arete`, `nisaba`                                    |
| `item_domain`       | enum     | `tara`, `veritas`, `nyx`, `arete`, `nisaba`                                    |
| `thread_id`         | string   | Continuity thread identifier                                                   |
| `thread_position`   | integer  | 0-based position of the rendered thread within the filtered timeline           |
| `step_id`           | string?  | Timeline step identifier when the re-entry came from a step-level affordance   |
| `step_position`     | integer? | 0-based position of the step within its continuity thread                      |
| `item_id`           | string   | Logical entity identifier for the clicked affordance                           |
| `item_type`         | string   | Logical entity kind (`continuity-thread`, `note`, `assistant-highlight`, etc.) |
| `unread_count`      | integer  | Unread step count remaining in the continuity thread                           |
| `thread_step_count` | integer  | Total number of steps inside the continuity thread                             |
| `domain_filter`     | enum     | `all`, `tara`, `veritas`, `nyx`, `arete`, `nisaba`                             |
| `kind_filter`       | enum     | `all`, `update`, `reminder`, `event`, `insight`                                |
| `is_cross_domain`   | boolean  | Whether the continuity thread spans more than one domain                       |

### `oshun.item.resumed`

Fired when a user resumes previously started content.

| Property       | Type   | Description                                |
| -------------- | ------ | ------------------------------------------ |
| `domain`       | enum   | `tara`, `veritas`, `nyx`, `arete`          |
| `item_id`      | string | Domain-specific item identifier            |
| `item_type`    | string | Content type                               |
| `progress_pct` | number | Progress percentage at resume time (0-100) |

### `oshun.value_action.completed`

Normalized high-value action for KPI computation.

| Property             | Type   | Description                                                                                     |
| -------------------- | ------ | ----------------------------------------------------------------------------------------------- |
| `domain`             | enum   | `tara`, `veritas`, `nyx`, `arete`                                                               |
| `value_action_type`  | string | Action type (`meditation_completed`, `article_read`, `observation_logged`, `checkin_completed`) |
| `completion_quality` | enum   | `partial`, `full`                                                                               |
| `entity_id`          | string | Domain entity reference                                                                         |

---

## Search Events

### `oshun.search.executed`

Fired when a search query is submitted.

| Property          | Type    | Description                              |
| ----------------- | ------- | ---------------------------------------- |
| `query_length`    | integer | Character count of the query             |
| `source`          | enum    | `home`, `explore`, `bff`                 |
| `surface`         | enum    | `results`, `suggestions`                 |
| `result_count`    | integer | Number of results returned               |
| `domain_filter`   | enum    | `all`, `tara`, `veritas`, `nyx`, `arete` |
| `partial_failure` | boolean | Whether any domain backend failed        |

### `oshun.search.zero_results`

Fired when a search returns no results.

| Property        | Type    | Description                              |
| --------------- | ------- | ---------------------------------------- |
| `query_length`  | integer | Character count of the query             |
| `source`        | enum    | `home`, `explore`, `bff`                 |
| `surface`       | enum    | `results`, `suggestions`                 |
| `domain_filter` | enum    | `all`, `tara`, `veritas`, `nyx`, `arete` |

### `oshun.search.result_opened`

Fired when a search result is tapped.

| Property       | Type    | Description                       |
| -------------- | ------- | --------------------------------- |
| `domain`       | enum    | `tara`, `veritas`, `nyx`, `arete` |
| `item_id`      | string  | ID of the opened item             |
| `item_type`    | string  | Content type of the result        |
| `position`     | integer | 0-based position in results list  |
| `query_length` | integer | Length of the original query      |

---

## Notification Events

### `oshun.notification.received`

Fired when a push notification is received.

| Property  | Type   | Description                                |
| --------- | ------ | ------------------------------------------ |
| `domain`  | enum   | `oshun`, `tara`, `veritas`, `nyx`, `arete` |
| `kind`    | string | Notification kind                          |
| `channel` | enum   | `push`, `in_app`, `email`                  |

### `oshun.notification.opened`

Fired when a notification is opened/actioned.

| Property     | Type    | Description                                |
| ------------ | ------- | ------------------------------------------ |
| `domain`     | enum    | `oshun`, `tara`, `veritas`, `nyx`, `arete` |
| `kind`       | string  | Notification kind                          |
| `latency_ms` | integer | Time from receive to open                  |
| `source`     | enum    | `banner`, `center`, `push_tap`             |

### `oshun.notification.dismissed`

Fired when a notification is dismissed without action.

| Property | Type   | Description                                |
| -------- | ------ | ------------------------------------------ |
| `domain` | enum   | `oshun`, `tara`, `veritas`, `nyx`, `arete` |
| `kind`   | string | Notification kind                          |

---

## Recommendation Events

### `oshun.recommendation.impressed`

Fired when recommendation cards are visible.

| Property  | Type     | Description                        |
| --------- | -------- | ---------------------------------- |
| `count`   | integer  | Number of recommendations shown    |
| `domains` | string[] | Domains represented in visible set |
| `source`  | string   | Source screen (e.g. `home`)        |

### `oshun.recommendation.tapped`

Fired when a recommendation is tapped.

| Property    | Type    | Description                       |
| ----------- | ------- | --------------------------------- |
| `item_id`   | string  | ID of the recommended item        |
| `domain`    | enum    | `tara`, `veritas`, `nyx`, `arete` |
| `item_type` | string  | Content type                      |
| `position`  | integer | Position in carousel              |
| `reason`    | string  | Recommendation reason category    |
| `score`     | number  | Composite relevance score         |

### `oshun.recommendation.feedback`

Fired when a user gives feedback on a recommendation.

| Property  | Type   | Description                       |
| --------- | ------ | --------------------------------- |
| `item_id` | string | ID of the item                    |
| `domain`  | enum   | `tara`, `veritas`, `nyx`, `arete` |
| `signal`  | enum   | `hide`, `less`, `more`            |

---

## Performance Events

### `oshun.performance.startup`

Fired once per app session with startup metrics.

| Property                 | Type    | Description                        |
| ------------------------ | ------- | ---------------------------------- |
| `cold_start`             | boolean | Whether this was a cold start      |
| `time_to_interactive_ms` | integer | Time until first interaction ready |
| `js_bundle_ms`           | integer | JS bundle load time                |
| `native_init_ms`         | integer | Native layer initialization time   |

### `oshun.performance.web_vitals`

Fired on web/PWA with Core Web Vitals.

| Property  | Type   | Description                         |
| --------- | ------ | ----------------------------------- |
| `lcp_ms`  | number | Largest Contentful Paint in ms      |
| `fid_ms`  | number | First Input Delay in ms             |
| `cls`     | number | Cumulative Layout Shift score       |
| `ttfb_ms` | number | Time to First Byte in ms            |
| `inp_ms`  | number | Interaction to Next Paint in ms     |
| `route`   | string | Route on which vitals were captured |

---

## Error Events

### `oshun.error.boundary_triggered`

Fired when an error boundary catches an exception.

| Property    | Type    | Description                     |
| ----------- | ------- | ------------------------------- |
| `component` | string  | Component tree path             |
| `message`   | string  | Error message (PII-scrubbed)    |
| `recovered` | boolean | Whether the user chose to retry |

### `oshun.error.api_failure`

Fired when a BFF/API request fails.

| Property      | Type    | Description                             |
| ------------- | ------- | --------------------------------------- |
| `endpoint`    | string  | Sanitized endpoint path                 |
| `status_code` | integer | HTTP status code (0 for network errors) |
| `latency_ms`  | integer | Request duration                        |
| `retried`     | boolean | Whether a retry was attempted           |

---

## Commerce Events

### `oshun.paywall.viewed`

Fired when a paywall/upgrade prompt is displayed.

| Property | Type   | Description                       |
| -------- | ------ | --------------------------------- |
| `source` | string | Screen that triggered the paywall |
| `tier`   | enum   | `free`, `pro`, `premium`          |

### `oshun.purchase.started`

Fired when a purchase flow begins.

| Property     | Type   | Description                    |
| ------------ | ------ | ------------------------------ |
| `product_id` | string | Product/plan identifier        |
| `tier`       | enum   | `pro`, `premium`               |
| `source`     | string | Screen that initiated purchase |

### `oshun.purchase.completed`

Fired when a purchase succeeds.

| Property     | Type    | Description                        |
| ------------ | ------- | ---------------------------------- |
| `product_id` | string  | Product/plan identifier            |
| `tier`       | enum    | `pro`, `premium`                   |
| `amount_usd` | number  | Purchase amount in USD cents       |
| `trial`      | boolean | Whether this is a trial conversion |

---

## Tara Domain Events

### `tara.session.started`

| Property        | Type    | Description               |
| --------------- | ------- | ------------------------- |
| `meditation_id` | string  | Meditation content ID     |
| `category`      | string  | Meditation category       |
| `duration_sec`  | integer | Expected session duration |

### `tara.session.completed`

| Property            | Type    | Description              |
| ------------------- | ------- | ------------------------ |
| `meditation_id`     | string  | Meditation content ID    |
| `active_listen_sec` | integer | Actual listened duration |
| `completed_full`    | boolean | Whether played to end    |

### `tara.session.abandoned`

| Property            | Type    | Description                     |
| ------------------- | ------- | ------------------------------- |
| `meditation_id`     | string  | Meditation content ID           |
| `progress_pct`      | number  | Progress at abandonment (0-100) |
| `active_listen_sec` | integer | Actual listened duration        |

---

## Veritas Domain Events

### `veritas.article.viewed`

| Property     | Type   | Description                                   |
| ------------ | ------ | --------------------------------------------- |
| `article_id` | string | Article identifier                            |
| `topic`      | string | Primary topic                                 |
| `source`     | enum   | `feed`, `search`, `notification`, `deep_link` |

### `veritas.article.read_depth`

| Property       | Type    | Description                             |
| -------------- | ------- | --------------------------------------- |
| `article_id`   | string  | Article identifier                      |
| `depth_pct`    | integer | Read depth percentage (25, 50, 75, 100) |
| `read_time_ms` | integer | Time spent reading                      |

### `veritas.topic.followed`

| Property   | Type   | Description                     |
| ---------- | ------ | ------------------------------- |
| `topic_id` | string | Topic identifier                |
| `source`   | enum   | `article`, `search`, `settings` |

---

## Nyx Domain Events

### `nyx.sky_event.viewed`

| Property     | Type   | Description                                                |
| ------------ | ------ | ---------------------------------------------------------- |
| `event_id`   | string | Sky event identifier                                       |
| `event_type` | string | Event category (`meteor_shower`, `eclipse`, `conjunction`) |

### `nyx.observation.logged`

| Property      | Type    | Description                              |
| ------------- | ------- | ---------------------------------------- |
| `object_id`   | string  | Celestial object identifier              |
| `object_type` | string  | Object type (`star`, `planet`, `galaxy`) |
| `has_notes`   | boolean | Whether user added notes                 |

### `nyx.sky_map.opened`

| Property  | Type    | Description                       |
| --------- | ------- | --------------------------------- |
| `ar_mode` | boolean | Whether AR mode was activated     |
| `source`  | enum    | `home`, `explore`, `event_detail` |

---

## Arete Domain Events

### `arete.checkin.completed`

| Property        | Type    | Description                            |
| --------------- | ------- | -------------------------------------- |
| `duration_sec`  | integer | Time to complete check-in              |
| `mood_recorded` | boolean | Whether mood was recorded              |
| `reflection`    | boolean | Whether a journal reflection was added |

### `arete.goal.created`

| Property   | Type   | Description            |
| ---------- | ------ | ---------------------- |
| `horizon`  | enum   | `short`, `mid`, `long` |
| `category` | string | Goal category          |

### `arete.habit.streak_updated`

| Property         | Type    | Description             |
| ---------------- | ------- | ----------------------- |
| `habit_id`       | string  | Habit identifier        |
| `streak_days`    | integer | Current streak length   |
| `longest_streak` | integer | All-time longest streak |

---

## Retention Funnel

The following events form the core retention funnel for KPI tracking:

1. `oshun.app.opened` - User opens the app
2. `oshun.auth.completed` - User authenticates (or skips for anonymous)
3. `oshun.onboarding.completed` - User completes onboarding
4. `oshun.domain.launched` - User enters a domain
5. `oshun.value_action.completed` - User completes a high-value action
6. `oshun.item.saved` - User saves content (engagement signal)

### Activation Definition

A user is **activated** when they have completed at least one
`oshun.value_action.completed` event within their first 7 days.

### Retention Definition

A user is **retained** when they fire at least one `oshun.app.opened` event in a
given measurement window (D1, D7, D14, D30).

---

## Data Quality Rules

1. **Required fields**: All envelope fields must be present. Events missing
   `event_id`, `event_name`, `occurred_at`, `platform`, or `session_id` are
   rejected.
2. **Name format**: Event names must match
   `^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*){2}$`.
3. **Consent gate**: Events with `consent_analytics=false` are excluded from KPI
   aggregation.
4. **Timestamp bounds**: `occurred_at` must be within 24 hours of server receive
   time.
5. **Deduplication**: Events with duplicate `event_id` within a 1-hour window
   are dropped.
6. **Cardinality limits**: String properties with >1000 unique values per day
   are flagged for review.
