Eve library

OSHUN V1 Customer Event Taxonomy

Spec

Revision 1

On this page

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).