Status: Active
Date: March 27, 2026
Owners: OSHUN Shell, OSHUN Auth Platform
Related:
docs/releases/v1/specs/todos.mddocs/releases/v1/specs/search-ranking-strategy.mddocs/adr/ADR-0062-oshun-assistant-led-continuity-journey-model.mddocs/adr/ADR-0069-oshun-assistant-persona-switching-ui-behavior.mdlibs/oshun/auth/src/personalization.tsapps/oshun/bff/src/routes/recommendations.tsapps/oshun/bff/src/routes/assistant.ts
1. Purpose#
This document defines the canonical personalization inputs, recommendation ranking inputs, and suppression rules that drive OSHUN shell home ordering, recommendation shaping, and assistant behavior.
The contract exists so onboarding, profile preferences, recommendation ranking, and assistant session creation all use the same user model instead of parallel per-surface heuristics.
2. Canonical Personalization Inputs#
The runtime contract is rooted in OshunPreferences.personalization plus the
existing assistant, notification, language, and accessibility settings already
stored in shared preferences.
Primary personalization inputs:
goals: declared outcomes such as calm baseline, consistent practice, source-backed clarity, deeper study, night-sky ritual, and daily progresspreferredDomains: explicit domain affinity ordering captured in onboarding or later profile editsinterests: explicit content-mode interests such as steady practice, evidence-backed briefings, primary text study, night-sky context, habit rhythm, and cross-domain synthesisroutineTiming: preferred dayparts for recurring engagementcurrentFocusThemes: short-lived freeform focus tags for future continuity and follow-up rankingnotificationTopics: per-topic opt-in state for daily, events, achievements, and research prompts
Supporting personalization inputs reused by ranking and assistant behavior:
assistant.defaultPersonaId: preferred guide familylanguage: reading and copy preferenceaccessibility.reducedMotionandaccessibility.highContrast: presentation intensity and clarity modifiersaccessibility.timezone: local daypart resolutionnotifications.pushEnabled,notifications.emailDigestEnabled,notifications.quietHoursEnabled: proactive delivery constraintsassistant.voiceResponsesEnabled,assistant.avatarPresenceEnabled: allowed delivery modesassistant.memory.scope,assistant.memory.consentGranted, andassistant.memory.categories: durable memory eligibility and lane-level exclusions
3. Recommendation Ranking Inputs#
Recommendation ordering resolves through
buildOshunRecommendationRankingProfile(...) and
rankOshunPersonalizedDomains(...).
Domain preference order is computed from:
- explicit preferred domains
- goal-to-domain affinity
- interest-to-domain affinity
- preferred guide affinity
- resolved current daypart
- routine timing affinity
- canonical tie-break order:
tara,arete,veritas,nyx,nisaba
Active ranking inputs:
preferred_domain_matchwith weight0.30goal_alignmentwith weight0.24interest_alignmentwith weight0.18routine_timingwith weight0.14guide_affinitywith weight0.08language_alignmentwith weight0.03accessibility_emphasiswith weight0.03
The recommendation scorer in apps/oshun/bff/src/recommendations/scoring.ts
consumes the resulting preferred domain order as a dedicated
preferenceAlignment factor rather than duplicating the upstream weighting
logic.
4. Recommendation Suppression Rules#
Recommendation suppression rules control proactive delivery and visual emphasis, not whether a user can manually browse a domain.
Current rule set:
quiet_hours: suppress proactive deliverydaily_topic_disabled: suppress ritual and daypart prompt familiesevents_topic_disabled: suppress event and schedule prompt familiesachievements_topic_disabled: suppress streak and progress prompt familiesresearch_topic_disabled: suppress study and evidence-follow-up prompt familiesreduced_motion: prefer low-stimulation recommendation presentationhigh_contrast: prefer text-first recommendation presentation
5. Assistant Suppression Rules#
Assistant suppression rules limit which delivery lanes and memory lanes may be used when creating and running a session.
Current rule set:
voice_output_disabled: enforce text-only responsesavatar_presence_disabled: disable avatar-led presentationprofile_memory_disabled: exclude durable profile memory when consent or scope does not allow itroutines_memory_disabled: exclude routine memorysaved_items_memory_disabled: exclude saved-item memorywellbeing_memory_disabled: exclude wellbeing memorystudy_memory_disabled: exclude study-context memorysensitive_traits_disabled: fallback exclusion for unsupported memory lanes
6. Runtime Consumers#
The contract is wired into the following runtime surfaces:
- onboarding writes canonical personalization fields into shared preferences
- profile preference patch routes validate and persist canonical personalization updates
- home cold-start ordering resolves through the shared domain-ranking helper
- BFF recommendations build a ranking profile and apply preference-aware domain alignment
- assistant session creation builds a behavior profile and passes ranking inputs plus suppression rule ids into session context and prompt assembly
7. Verification#
The contract is covered by:
- auth preference and personalization unit tests
- BFF recommendation scoring, profile-route, and contract tests
- assistant engine and system prompt tests
- web onboarding and cold-start recommendation tests