Canonical event definitions for the OSHUN platform. Naming follows
ADR-0006:
<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 |
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 |
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:
oshun.app.opened - User opens the app
oshun.auth.completed - User authenticates (or skips for anonymous)
oshun.onboarding.completed - User completes onboarding
oshun.domain.launched - User enters a domain
oshun.value_action.completed - User completes a high-value action
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#
- Required fields: All envelope fields must be present. Events missing
event_id, event_name, occurred_at, platform, or session_id are
rejected.
- Name format: Event names must match
^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*){2}$.
- Consent gate: Events with
consent_analytics=false are excluded from KPI
aggregation.
- Timestamp bounds:
occurred_at must be within 24 hours of server receive
time.
- Deduplication: Events with duplicate
event_id within a 1-hour window
are dropped.
- Cardinality limits: String properties with >1000 unique values per day
are flagged for review.