/** * v1.4.23 H4 — per-user Coach prompt-tuning preferences. * * Persisted as a Json blob on `User.coachPrefsJson`. Null = legacy * defaults (tone="warm", verbosity="default", no metrics excluded, * evidence disclosure closed by default). The Coach prompt builder + * snapshot builder both read this shape — the snapshot must filter on * `excludeMetrics` BEFORE landing in the system prompt so the model * never sees data the user opted out of. * * v1.4.25 W5 — extended with `defaultWindow`. The picker lives in the * settings sheet; the drawer header carries a per-conversation override * pill so a single chat can narrow the window without flipping the * global default. The chat route folds the saved preference into the * snapshot scope when the client didn't supply a window override. */ import { z } from "zod/v4"; /** * Tone presets the Coach system-prompt prefix toggles between. v1.4.22 * landed `warm` as the default; `neutral` strips the warmth language * for users who prefer a clinical-adjacent style; `concise` caps * verbosity and skips the optional motivational-interviewing micro- * moves entirely. */ export const coachToneEnum = z.enum(["warm", "neutral", "concise"]); export type CoachTone = z.infer; /** * Verbosity presets. Maps onto the prompt's "60-180 words" guidance: * `brief` ≈ 30-90 words, `default` keeps the v1.4.22 range, `detailed` * lifts the cap to 250 words. The `concise` tone overrides verbosity * down to `brief` regardless of the verbosity selection — same * intuition as concise == short, the picker just keeps the controls * orthogonal in the UI for clarity. */ export const coachVerbosityEnum = z.enum(["brief", "default", "detailed"]); export type CoachVerbosity = z.infer; /** * Metric scopes the user can exclude from every Coach turn. Matches * `CoachScopeSource` (`src/lib/ai/coach/types.ts`) so the snapshot * builder can filter without a translation step. Apple Health-only * metrics (hrv / sleep / resting_hr / steps) are listed alongside the * core five so iOS users have a single surface to manage their privacy * preferences. */ export const coachExcludeMetricEnum = z.enum([ "bp", "weight", "pulse", "mood", "compliance", "hrv", "sleep", "resting_hr", "steps", // v1.4.36 W3 T2 — optional context blocks the user can opt out of. // `medications` covers the snapshot's compliance + GLP-1 weeklyContext; // `anthropometrics` covers height / age / gender on `context`. Each // gates a single labelled block at the snapshot/feature layer, so an // excluded block never lands in the prompt at all (not even as a // labelled-empty key). "medications", "anthropometrics", ]); export type CoachExcludeMetric = z.infer; /** * v1.4.25 W5 — default analysis window the Coach uses when the client * doesn't supply a per-conversation override. Mirrors * `CoachScopeWindow` (`src/lib/ai/coach/types.ts`) so the chat route * can fold the preference into `scope.window` without a translation * layer. The default stays `allTime` to preserve the v1.4.24 behaviour * — every legacy row reads as "no opinion" until the user explicitly * picks a tighter default. */ export const coachDefaultWindowEnum = z.enum([ "last7days", "last30days", "last90days", "allTime", ]); export type CoachDefaultWindow = z.infer; /** * v1.7.0 — clustered, opt-in Coach data sources. Each cluster groups a * set of `CoachScopeSource` / `MeasurementType` / model reads behind a * single toggle in the Coach settings sheet. The snapshot builder * expands the enabled clusters into the source set when the request * does not carry an explicit `scope.sources` list, then subtracts * `excludeMetrics` as a post-filter (a cluster can be on while a single * metric inside it is excluded). * * The cluster set is the opt-in source of truth going forward; * `excludeMetrics` stays valid for back-compat and only narrows. */ export const coachDataClusterEnum = z.enum([ "cardio", "body", "activity", "workouts", "sleep", "mood", "glucose", "medication", "mobility", "environment", ]); export type CoachDataCluster = z.infer; /** * Clusters enabled when the user has never touched the cluster picker * (`dataClusters === undefined`). These four reproduce today's legacy * five domains: cardio carries BP + pulse, body carries weight, mood * and medication map straight through. The additive members riding * inside cardio/body (HRV, resting HR, body-composition) only surface * when the user actually has rows for them — empty blocks are dropped — * so a web-only account stays close to the legacy 5-domain output while * an iOS account quietly gains the extra signals it already stores. */ export const DEFAULT_COACH_CLUSTERS: ReadonlyArray = [ "cardio", "body", "mood", "medication", ]; /** * v1.18.1 (Workstream C) — Coach cadence-suggestion state. Persisted * inside the same `coachPrefsJson` blob so the suggestion engine has a * single, atomic place for the non-naggy machinery: * * - `enabled`: master opt-out for cadence suggestions (default ON; the * toggle lives under Coach / Reminders settings). * - `stopped`: the explicit "you measure enough — stop" path. Once the * user picks it the Coach never suggests a cadence again until they * re-enable. Distinct from `enabled:false` only in provenance (the user * said "stop" from the card vs flipped the settings toggle); both * suppress. * - `dismissedCadences`: cadence ids the user dismissed. A dismissed * cadence is never re-suggested (dismissal memory). * - `lastSuggestedAt`: ISO instant of the last suggestion actually shown. * Drives the cooldown (no second suggestion within the cooldown window). * * The shape is fully optional + defaulted so every legacy blob parses as * "suggestions on, nothing dismissed". */ export const coachReminderSuggestionPrefsSchema = z.object({ enabled: z.boolean().default(true), stopped: z.boolean().default(false), dismissedCadences: z.array(z.string().max(64)).max(32).default([]), lastSuggestedAt: z.string().max(40).nullable().default(null), }); export type CoachReminderSuggestionPrefs = z.infer< typeof coachReminderSuggestionPrefsSchema >; export const DEFAULT_REMINDER_SUGGESTION_PREFS: CoachReminderSuggestionPrefs = { enabled: true, stopped: false, dismissedCadences: [], lastSuggestedAt: null, }; /** * Full preferences shape. Defaults are inlined into the schema so a * `safeParse({})` call returns the legacy v1.4.22 defaults — saves a * sprinkle of `?? defaultX` calls at the call sites. */ export const coachPrefsSchema = z.object({ tone: coachToneEnum.default("warm"), verbosity: coachVerbosityEnum.default("default"), excludeMetrics: z.array(coachExcludeMetricEnum).max(11).default([]), showEvidenceByDefault: z.boolean().default(false), defaultWindow: coachDefaultWindowEnum.default("allTime"), // v1.7.0 — opt-in cluster selection. `undefined` (key absent) is the // back-compat sentinel: the snapshot builder expands // `DEFAULT_COACH_CLUSTERS` so a legacy user who never opened the // picker keeps the legacy domains. We deliberately do NOT `.default([])` // — an empty array means "the user turned everything off", which is a // distinct, valid state from "never picked". dataClusters: z.array(coachDataClusterEnum).max(10).optional(), // v1.18.1 (Workstream C) — cadence-suggestion state. Optional with NO // top-level default so a legacy blob (and `parse({})`) stays byte- // identical: an absent key reads as `undefined`, and call sites fall // back to `DEFAULT_REMINDER_SUGGESTION_PREFS`. When the key IS present, // its inner fields default (so `{}` fills to the all-on shape). reminderSuggestions: coachReminderSuggestionPrefsSchema.optional(), }); export type CoachPrefs = z.infer; /** * Default preferences applied when the user has never opened the * settings cog. Equivalent to `coachPrefsSchema.parse({})` but * returned as a plain object so call sites can compare references * (e.g., short-circuit a snapshot rebuild when prefs match defaults). */ export const DEFAULT_COACH_PREFS: CoachPrefs = { tone: "warm", verbosity: "default", excludeMetrics: [], showEvidenceByDefault: false, defaultWindow: "allTime", }; /** * Parse a row's `coachPrefsJson` Json blob into a typed `CoachPrefs`, * falling back to defaults when the row is null OR the persisted shape * has drifted (a forward-compat field rename, an admin-side hand-edit, * etc.). Keeps the call sites at `src/lib/ai/coach/snapshot.ts` and * `src/lib/ai/coach/system-prompt.ts` free of the null/parse plumbing. */ export function parseCoachPrefs(raw: unknown): CoachPrefs { if (raw == null) return DEFAULT_COACH_PREFS; const parsed = coachPrefsSchema.safeParse(raw); return parsed.success ? parsed.data : DEFAULT_COACH_PREFS; }