# OSHUN V1 Personalization and Suppression Contract

Status: Active

Date: March 27, 2026

Owners: OSHUN Shell, OSHUN Auth Platform

Related:

- `docs/releases/v1/specs/todos.md`
- `docs/releases/v1/specs/search-ranking-strategy.md`
- `docs/adr/ADR-0062-oshun-assistant-led-continuity-journey-model.md`
- `docs/adr/ADR-0069-oshun-assistant-persona-switching-ui-behavior.md`
- `libs/oshun/auth/src/personalization.ts`
- `apps/oshun/bff/src/routes/recommendations.ts`
- `apps/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 progress
- `preferredDomains`: explicit domain affinity ordering captured in onboarding
  or later profile edits
- `interests`: explicit content-mode interests such as steady practice,
  evidence-backed briefings, primary text study, night-sky context, habit
  rhythm, and cross-domain synthesis
- `routineTiming`: preferred dayparts for recurring engagement
- `currentFocusThemes`: short-lived freeform focus tags for future continuity
  and follow-up ranking
- `notificationTopics`: 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 family
- `language`: reading and copy preference
- `accessibility.reducedMotion` and `accessibility.highContrast`: presentation
  intensity and clarity modifiers
- `accessibility.timezone`: local daypart resolution
- `notifications.pushEnabled`, `notifications.emailDigestEnabled`,
  `notifications.quietHoursEnabled`: proactive delivery constraints
- `assistant.voiceResponsesEnabled`, `assistant.avatarPresenceEnabled`: allowed
  delivery modes
- `assistant.memory.scope`, `assistant.memory.consentGranted`, and
  `assistant.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:

1. explicit preferred domains
2. goal-to-domain affinity
3. interest-to-domain affinity
4. preferred guide affinity
5. resolved current daypart
6. routine timing affinity
7. canonical tie-break order: `tara`, `arete`, `veritas`, `nyx`, `nisaba`

Active ranking inputs:

- `preferred_domain_match` with weight `0.30`
- `goal_alignment` with weight `0.24`
- `interest_alignment` with weight `0.18`
- `routine_timing` with weight `0.14`
- `guide_affinity` with weight `0.08`
- `language_alignment` with weight `0.03`
- `accessibility_emphasis` with weight `0.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 delivery
- `daily_topic_disabled`: suppress ritual and daypart prompt families
- `events_topic_disabled`: suppress event and schedule prompt families
- `achievements_topic_disabled`: suppress streak and progress prompt families
- `research_topic_disabled`: suppress study and evidence-follow-up prompt
  families
- `reduced_motion`: prefer low-stimulation recommendation presentation
- `high_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 responses
- `avatar_presence_disabled`: disable avatar-led presentation
- `profile_memory_disabled`: exclude durable profile memory when consent or
  scope does not allow it
- `routines_memory_disabled`: exclude routine memory
- `saved_items_memory_disabled`: exclude saved-item memory
- `wellbeing_memory_disabled`: exclude wellbeing memory
- `study_memory_disabled`: exclude study-context memory
- `sensitive_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
