# OSHUN V1 Customer Event Taxonomy

Status: Canonical Date: 2026-04-26 Owners: OSHUN Product, OSHUN Platform
Engineering, OSHUN Data Engineering Tracks: `V1-OBS-001` from
`OSHUN_V1_TODOS.md` Spec source: `libs/oshun/analytics/src/customer-taxonomy.ts`

This document is the canonical, human-readable companion to the machine-readable
V1 customer event taxonomy in `@oshun/analytics`.

The machine-readable taxonomy is the single source of truth. Any divergence
between this document and `customer-taxonomy.ts` is a bug in this document —
follow the code.

---

## 1. Scope

This taxonomy defines every analytics event a customer-facing surface (web
shell, mobile shell, PWA, deep-link handler, native notification handler, domain
app launched from the shell) is permitted to emit during OSHUN V1.

It is intentionally narrower than the global `OshunEventPayloadMap` in
`libs/oshun/analytics/src/types.ts`, which also contains studio/admin and ops
events. Out-of-scope event categories deferred to other V1 tasks:

- Studio / admin surfaces — `V1-OBS-002`
- Assistant interactions, memory state, grounding state, persona identity —
  `V1-OBS-003`
- Review, moderation, appeal, incident flows — `V1-OBS-004`
- Model intake, promotion, media release gates — `V1-OBS-005`

The taxonomy is consistent with:

- ADR-0006 — `docs/adr/ADR-0012-analytics-taxonomy-and-event-naming.md`
- ADR-0006 event dictionary — `docs/releases/v1/reports/analytics-events.md`
- Customer information architecture — `libs/oshun/navigation/src/customer-ia.ts`
- Existing typed payload map — `libs/oshun/analytics/src/types.ts`

---

## 2. Naming and envelope

### 2.1 Canonical name format

All names follow the ADR-0006 format `<namespace>.<entity>.<action>`:

- lowercase ASCII only
- dot-delimited, exactly three segments
- snake_case words within a segment
- past-tense or completed-action verb in `action` where applicable

### 2.2 Required envelope

Every customer event includes the envelope defined in ADR-0006:

| Field               | Required when                                      |
| ------------------- | -------------------------------------------------- |
| `event_id`          | always                                             |
| `event_name`        | always                                             |
| `event_version`     | always (starts at `1`)                             |
| `occurred_at`       | always (ISO-8601 UTC)                              |
| `platform`          | always (`ios`, `android`, `web`, `pwa`, `server`)  |
| `surface`           | always (`mobile_shell`, `web_shell`, `domain_app`) |
| `session_id`        | always                                             |
| `domain_context`    | always                                             |
| `consent_analytics` | always                                             |
| `user_id`           | when authenticated                                 |
| `anonymous_id`      | when unauthenticated                               |
| `app_version`       | when known                                         |
| `locale`            | when known                                         |

At least one of `user_id` or `anonymous_id` is always present.

### 2.3 Property rules

- Property names are snake_case.
- No PII in any property value (no email, phone, full name, raw IP).
- Stable enum values are defined per property and locked by tests.
- High-cardinality string properties are kept under the ADR-0006 cap of 1,000
  unique values per day; cardinality hints (`low`, `medium`, `high`) are
  recorded on each property to drive monitoring.

---

## 3. Surfaces

The taxonomy uses the following customer-surface taxonomy. Every event declares
one or more of these as the only places it is permitted to be emitted from.
Surfaces align with `OSHUN_WEB_SHELL_SURFACES`, `OSHUN_MOBILE_SHELL_SURFACES`
and the cross-shell entry points defined in `customer-ia.ts`.

| Surface                | Description                                                   |
| ---------------------- | ------------------------------------------------------------- |
| `web_shell`            | Web shell, surface-agnostic (lifecycle, performance, errors). |
| `mobile_shell`         | Mobile shell, surface-agnostic.                               |
| `pwa_shell`            | PWA shell, surface-agnostic.                                  |
| `web_home`             | Web Home tab.                                                 |
| `web_explore`          | Web Explore tab.                                              |
| `web_activity`         | Web Activity tab.                                             |
| `web_library`          | Web Library tab.                                              |
| `web_profile`          | Web Profile tab.                                              |
| `web_assistant`        | Web continuity assistant surface.                             |
| `web_search`           | Web universal search surface.                                 |
| `mobile_home`          | Mobile Home tab.                                              |
| `mobile_explore`       | Mobile Explore tab.                                           |
| `mobile_activity`      | Mobile Activity tab.                                          |
| `mobile_library`       | Mobile Library tab.                                           |
| `mobile_profile`       | Mobile Profile tab.                                           |
| `mobile_assistant`     | Mobile continuity assistant surface.                          |
| `mobile_search`        | Mobile universal search surface.                              |
| `deep_link`            | Deep-link entry handler.                                      |
| `notification_handler` | Push/email/in-app notification handler.                       |
| `background`           | Background or service-worker context.                         |
| `domain_app`           | Customer-facing domain app launched from the shell.           |

---

## 4. Families

Events are grouped into the following families, an extension of ADR-0006
§"Taxonomy Families":

| Family           | Description                                                       |
| ---------------- | ----------------------------------------------------------------- |
| `lifecycle`      | App / shell open, background, resume, terminate, update install.  |
| `auth`           | Sign-in, sign-out, token refresh, auth failure.                   |
| `onboarding`     | Onboarding start, step, completion, abandonment.                  |
| `profile`        | Profile initialization KPI events.                                |
| `navigation`     | Tab views, route transitions, deep-link opens, domain launches.   |
| `continuity`     | Home continuation, activity reentry, item resume.                 |
| `engagement`     | Item save/unsave/share and other engagement signals.              |
| `value_action`   | Canonical KPI value-action completions.                           |
| `search`         | Universal search query, zero-result, result-open, filter-apply.   |
| `recommendation` | Cross-domain recommendation impressions, taps, feedback.          |
| `notification`   | Notification received, opened, dismissed, actioned.               |
| `study`          | Nisaba customer study/notes/inspector/expert-mode/passage events. |
| `performance`    | Startup metrics, web vitals, route transition timings.            |
| `error`          | Error boundary triggers and customer-visible API failures.        |
| `privacy`        | Consent grant/revoke transitions.                                 |
| `commerce`       | Paywall views and purchase flow stages.                           |
| `accessibility`  | Accessibility preference toggles.                                 |
| `preferences`    | Other profile-preference updates.                                 |

---

## 5. Canonical KPI events

The following events form the OSHUN V1 customer KPI set per ADR-0006 §"Canonical
OSHUN KPI Events". Tests in `customer-taxonomy.test.ts` lock this list to the
taxonomy:

- `oshun.app.opened`
- `oshun.auth.completed`
- `oshun.profile.initialized`
- `oshun.domain.launched`
- `oshun.value_action.completed`
- `oshun.item.saved`
- `oshun.item.resumed`
- `oshun.search.executed`
- `oshun.notification.opened`

`oshun.value_action.completed` carries `value_action_type`,
`completion_quality`, `entity_id`, and `duration_ms`. The supported value action
types are `ritual_completed`, `article_completed`, `observation_logged`,
`checkin_completed`, `study_passage_completed`, and `lesson_completed`.

---

## 6. Event index

The complete, authoritative event list is in
`libs/oshun/analytics/src/customer-taxonomy.ts`. Each entry includes:

- canonical `name`
- `namespace` (must match the name's first segment)
- `version` (starts at 1; bump on breaking property change)
- `family`
- `domainContext` (envelope dimension)
- `surfaces` (allowed emit sites)
- `kpi` (`true` only for the canonical KPI set above)
- `consentRequired` (false only for lifecycle/auth/onboarding/error/performance)
- `description`
- `implementationStatus` (`implemented` | `planned` | `deprecated`)
- `payloadKey` (existing `OshunEventPayloadMap` key, when implemented)
- `legacyNames` (snake_case names adapters must canonicalize from)
- `owner` (signoff team)
- `properties` (full property descriptors with types, allowed values,
  required-ness, descriptions, cardinality hints)

### 6.1 Events by family

| Family         | Events                                                                                                                                                                                                                                                                          |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| lifecycle      | `oshun.app.opened`, `oshun.app.backgrounded`, `oshun.app.resumed`, `oshun.app.terminated`, `oshun.app.update_installed`                                                                                                                                                         |
| auth           | `oshun.auth.completed`, `oshun.auth.signed_out`, `oshun.auth.token_refreshed`, `oshun.auth.failed`                                                                                                                                                                              |
| onboarding     | `oshun.onboarding.started`, `oshun.onboarding.step_completed`, `oshun.onboarding.completed`, `oshun.onboarding.abandoned`                                                                                                                                                       |
| profile        | `oshun.profile.initialized`                                                                                                                                                                                                                                                     |
| preferences    | `oshun.profile.preferences_updated`                                                                                                                                                                                                                                             |
| privacy        | `oshun.profile.consent_updated`, `oshun.privacy.consent_granted`, `oshun.privacy.consent_revoked`                                                                                                                                                                               |
| navigation     | `oshun.tab.viewed`, `oshun.route.transitioned`, `oshun.deep_link.opened`, `oshun.domain.launch_requested`, `oshun.domain.launched`                                                                                                                                              |
| continuity     | `oshun.home_continuation.impressed`, `oshun.home_continuation.clicked`, `oshun.activity.reentry_opened`, `oshun.item.resumed`                                                                                                                                                   |
| engagement     | `oshun.item.saved`, `oshun.item.unsaved`, `oshun.item.shared`, `tara.session.started`, `tara.session.abandoned`, `veritas.article.viewed`, `veritas.article.read_depth`, `nyx.sky_event.viewed`, `arete.habit.streak_updated`, `metis.lesson.started`, `metis.lesson.abandoned` |
| value_action   | `oshun.value_action.completed`, `tara.session.completed`, `veritas.article.completed`, `nyx.observation.logged`, `arete.checkin.completed`, `metis.lesson.completed`                                                                                                            |
| search         | `oshun.search.executed`, `oshun.search.zero_results`, `oshun.search.result_opened`, `oshun.search.filter_applied`                                                                                                                                                               |
| recommendation | `oshun.recommendation.impressed`, `oshun.recommendation.tapped`, `oshun.recommendation.feedback`, `oshun.cross_domain_recommendations.served`                                                                                                                                   |
| notification   | `oshun.notification.received`, `oshun.notification.opened`, `oshun.notification.dismissed`, `oshun.notification.actioned`                                                                                                                                                       |
| study          | `nisaba.study.action_triggered`, `nisaba.inspector.opened`, `nisaba.expert_mode.toggled`, `nisaba.note.saved`, `nisaba.passage.opened`                                                                                                                                          |
| performance    | `oshun.performance.startup`, `oshun.performance.web_vitals`, `oshun.performance.route_transition`                                                                                                                                                                               |
| error          | `oshun.error.boundary_triggered`, `oshun.error.api_failure`                                                                                                                                                                                                                     |
| commerce       | `oshun.paywall.viewed`, `oshun.purchase.started`, `oshun.purchase.completed`                                                                                                                                                                                                    |
| accessibility  | `oshun.accessibility.preference_toggled`                                                                                                                                                                                                                                        |

### 6.2 Implementation status

The canonical taxonomy distinguishes `implemented`, `planned`, and `deprecated`.
As of V1 baseline:

- `implemented`: 23 events have a backing entry in `OshunEventPayloadMap` and at
  least one production emission site.
- `planned`: events whose contracts are locked here but whose emitters land in
  subsequent V1-OBS / domain-specific tasks.

Any new customer event requires:

1. an entry in `customer-taxonomy.ts`
2. a passing `customer-taxonomy.test.ts` run
3. a corresponding emitter and ingestion contract update before status may
   transition from `planned` to `implemented`

---

## 7. Legacy mapping

Adapter layers must canonicalize the following legacy names per ADR-0006
§"Legacy-to-Canonical Mapping Requirements". The full list lives in the spec;
the helper `resolveLegacyEventName` performs the lookup at runtime.

| Legacy name                    | Canonical name                  |
| ------------------------------ | ------------------------------- |
| `shell_opened`                 | `oshun.app.opened`              |
| `oshun.app_opened`             | `oshun.app.opened`              |
| `auth_signed_in`               | `oshun.auth.completed`          |
| `oshun.auth_completed`         | `oshun.auth.completed`          |
| `oshun.profile_initialized`    | `oshun.profile.initialized`     |
| `oshun.domain_card_opened`     | `oshun.domain.launch_requested` |
| `oshun.value_action_completed` | `oshun.value_action.completed`  |
| `oshun.item_saved`             | `oshun.item.saved`              |
| `oshun.item_resumed`           | `oshun.item.resumed`            |
| `oshun.search_executed`        | `oshun.search.executed`         |
| `search_query`                 | `oshun.search.executed`         |
| `oshun.notification_opened`    | `oshun.notification.opened`     |
| `article_view`                 | `veritas.article.viewed`        |
| `article_complete`             | `veritas.article.completed`     |

---

## 8. Governance

### 8.1 Amendments

Adding, changing, or deprecating an event requires:

1. updating `customer-taxonomy.ts` with the new or changed entry
2. updating tests (the lock-style tests fail closed if entries drift)
3. updating this document if the change is structurally significant
4. signoff from the listed `owner` namespace's product and engineering leads

### 8.2 Versioning

- Additive, backward-compatible property additions keep the same `event_name`
  and same `version`.
- Breaking changes (semantic rename or removal of a property's meaning) require
  bumping `version` and may require a dual-write window to preserve dashboards.
- Renaming an event creates a new entry; the old entry transitions to
  `deprecated` and remains in place until adapters have stopped emitting the old
  name and dashboards have migrated.

### 8.3 Cardinality and PII

- The validation library (`validation.ts`) already enforces a per-day
  cardinality cap; this taxonomy adds explicit `cardinalityHint` values that the
  data-quality dashboards use to scope alerting.
- PII in customer events is forbidden; tests fail closed on any property flagged
  `isPii: true`.

---

## 9. Out-of-scope

This taxonomy intentionally does not define:

- studio / admin surface events (V1-OBS-002)
- assistant interaction events (V1-OBS-003)
- review / moderation / appeal / incident events (V1-OBS-004)
- model intake / promotion / media release events (V1-OBS-005)
- system / SDK ingestion telemetry (operational only, not customer)

When those follow-up taxonomies are defined, they will register their canonical
names in their own taxonomy spec files (mirror of this one) and will be
cross-validated against the global `validateEventName` regex and namespace
allowlist.

---

## 10. Change log

- 2026-04-26 — Initial canonical V1 customer event taxonomy published alongside
  `libs/oshun/analytics/src/customer-taxonomy.ts` (V1-OBS-001).
