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
actionwhere 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.openedoshun.auth.completedoshun.profile.initializedoshun.domain.launchedoshun.value_action.completedoshun.item.savedoshun.item.resumedoshun.search.executedoshun.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)familydomainContext(envelope dimension)surfaces(allowed emit sites)kpi(trueonly for the canonical KPI set above)consentRequired(false only for lifecycle/auth/onboarding/error/performance)descriptionimplementationStatus(implemented|planned|deprecated)payloadKey(existingOshunEventPayloadMapkey, 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 inOshunEventPayloadMapand 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:
- an entry in
customer-taxonomy.ts - a passing
customer-taxonomy.test.tsrun - a corresponding emitter and ingestion contract update before status may
transition from
plannedtoimplemented
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:
- updating
customer-taxonomy.tswith the new or changed entry - updating tests (the lock-style tests fail closed if entries drift)
- updating this document if the change is structurally significant
- signoff from the listed
ownernamespace's product and engineering leads
8.2 Versioning#
- Additive, backward-compatible property additions keep the same
event_nameand sameversion. - Breaking changes (semantic rename or removal of a property's meaning) require
bumping
versionand may require a dual-write window to preserve dashboards. - Renaming an event creates a new entry; the old entry transitions to
deprecatedand 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 explicitcardinalityHintvalues 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).