fix(golf): classify remaining CoachHelm no-rounds empty states as expected

src/app/golf/actions/coachhelm-data.ts

@@ -101,6 +101,12 @@ interface ActionSuccess<T> {
 interface ActionError {
   success: false;
   error: string;
+  /**
+   * Stable machine code for the soft-failure observer (observe-action-result):
+   * expected empty states carry a code from EXPECTED_EMPTY_STATE_CODES so a
+   * brand-new player browsing CoachHelm doesn't register as a prod error.
+   */
+  code?: string;
 }
 
 type ActionResult<T> = ActionSuccess<T> | ActionError;
@@ -291,7 +297,24 @@ async function getPlayerProfileImpl(
     }
 
     if (!roundsData || roundsData.length === 0) {
-      return { success: false, error: 'No completed rounds found for this player' };
+      // The main query filters out completed rounds with a NULL total_score,
+      // so an empty result is ambiguous: brand-new player (expected empty
+      // state) vs. completed rounds that all lack scores (data-quality
+      // problem). Only the former may carry the globally-silenced
+      // `no_completed_rounds` code — see EXPECTED_EMPTY_STATE_CODES contract.
+      const { count: completedCount, error: countError } = await supabase
+        .from('golf_rounds')
+        .select('id', { count: 'exact', head: true })
+        .eq('player_id', playerId)
+        .eq('status', 'completed');
+      // A failed count must not fall through to the globally-silenced code.
+      if (countError) {
+        return { success: false, error: 'Failed to fetch round data' };
+      }
+      if ((completedCount ?? 0) > 0) {
+        return { success: false, error: 'Completed rounds exist but are missing score data' };
+      }
+      return { success: false, error: 'No completed rounds found for this player', code: 'no_completed_rounds' };
     }
 
     // Build baseline from round data
@@ -591,7 +614,23 @@ async function getPlayerTrendAnalysisImpl(
     }
 
     if (!roundsData || roundsData.length < 3) {
-      return { success: false, error: 'Need at least 3 completed rounds for trend analysis' };
+      // Same ambiguity as getPlayerProfile: the main query drops completed
+      // rounds with a NULL score_to_par, so "fewer than 3 usable rounds" may
+      // mean 3+ completed rounds whose scores never populated — a data-quality
+      // failure that must not carry the globally-silenced code.
+      const { count: completedCount, error: countError } = await supabase
+        .from('golf_rounds')
+        .select('id', { count: 'exact', head: true })
+        .eq('player_id', playerId)
+        .eq('status', 'completed');
+      // A failed count must not fall through to the globally-silenced code.
+      if (countError) {
+        return { success: false, error: 'Failed to fetch round data' };
+      }
+      if ((completedCount ?? 0) >= 3) {
+        return { success: false, error: 'Completed rounds exist but lack score data for trend analysis' };
+      }
+      return { success: false, error: 'Need at least 3 completed rounds for trend analysis', code: 'insufficient_rounds' };
     }
 
     // Extract score_to_par values (chronological, oldest first)
@@ -714,7 +753,7 @@ async function getPlayerShotContextImpl(
     }
 
     if (!roundsData || roundsData.length === 0) {
-      return { success: false, error: 'No completed rounds found in the specified period' };
+      return { success: false, error: 'No completed rounds found in the specified period', code: 'no_rounds_in_period' };
     }
 
     const roundIds = roundsData.map((r) => r.id);
@@ -1027,7 +1066,22 @@ async function getPlayerWhatIfImpl(
     const scores = (roundsData ?? []).map((r) => r.score_to_par ?? 0);
 
     if (scores.length < 3) {
-      return { success: false, error: 'Need at least 3 completed rounds for scenario analysis' };
+      // Mirror the trend-analysis guard: the query above drops NULL
+      // score_to_par rounds, so only a true shortage of completed rounds may
+      // carry the globally-silenced code.
+      const { count: completedCount, error: countError } = await supabase
+        .from('golf_rounds')
+        .select('id', { count: 'exact', head: true })
+        .eq('player_id', playerId)
+        .eq('status', 'completed');
+      // A failed count must not fall through to the globally-silenced code.
+      if (countError) {
+        return { success: false, error: 'Failed to fetch scoring data' };
+      }
+      if ((completedCount ?? 0) >= 3) {
+        return { success: false, error: 'Completed rounds exist but lack score data for scenario analysis' };
+      }
+      return { success: false, error: 'Need at least 3 completed rounds for scenario analysis', code: 'insufficient_rounds' };
     }
 
     const mean = scores.reduce((s, v) => s + v, 0) / scores.length;

src/lib/admin/__tests__/observe-action-result.test.ts

@@ -73,6 +73,31 @@ describe('observe-action-result', () => {
     expect(isExpectedEmptyStateCode(null)).toBe(false);
   });
 
+  it('classifies the coachhelm-data empty-state codes as expected empty states', () => {
+    expect(isExpectedEmptyStateCode('no_rounds_in_period')).toBe(true);
+    expect(isExpectedEmptyStateCode('no_completed_rounds')).toBe(true);
+    expect(isExpectedEmptyStateCode('insufficient_rounds')).toBe(true);
+  });
+
+  it.each([
+    ['no_rounds_in_period', 'No completed rounds found in the specified period'],
+    ['no_completed_rounds', 'No completed rounds found for this player'],
+    ['insufficient_rounds', 'Need at least 3 completed rounds for trend analysis'],
+  ])('logs %s via logServerEvent at info severity with skipSentry', (code, error) => {
+    observeActionSoftFailure(
+      { success: false, error, code },
+      { action: 'getPlayerProfile', sport: 'golf', feature: 'intelligence_dashboard', source: 'server_action' },
+    );
+
+    expect(mocks.logServerError).not.toHaveBeenCalled();
+    expect(mocks.logServerEvent).toHaveBeenCalledTimes(1);
+    const infoCall = mocks.logServerEvent.mock.calls[0] as
+      | [string, Record<string, unknown> | undefined, 'info' | 'warning' | 'error' | 'critical']
+      | undefined;
+    expect(infoCall?.[2]).toBe('info');
+    expect(infoCall?.[1]).toMatchObject({ skipSentry: true });
+  });
+
   it('logs unexpected soft failures at error severity', () => {
     observeActionSoftFailure(
       { success: false, error: 'Could not save document' },

src/lib/admin/observe-action-result.ts

@@ -48,12 +48,23 @@ const EXPECTED_SOFT_FAILURE_CODES: ReadonlySet<string> = new Set([
  * toward the Errors tab / Sentry — see admin/data/incident-feed.ts (default
  * view excludes only 'info') and admin/data/overview.ts (KPI counts key off
  * severity IN ('error','critical')).
+ *
+ * CONTRACT: classification is by code GLOBALLY, not per action — a code in
+ * this set silences Sentry for every envelope that carries it. Only attach
+ * one of these codes to a genuinely-empty outcome; a real failure must never
+ * reuse them.
  */
 const EXPECTED_EMPTY_STATE_CODES: ReadonlySet<string> = new Set([
   'engine_no_recent_rounds',
-  // getPlayerShotAnalytics: player has no completed rounds in the selected
-  // lookback window — the analytics page's normal brand-new-player state.
+  // getPlayerShotAnalytics / getPlayerShotContext: player has no completed
+  // rounds in the selected lookback window — the analytics/CoachHelm pages'
+  // normal brand-new-player state.
   'no_rounds_in_period',
+  // getPlayerProfile (coachhelm-data): player has no completed rounds at all.
+  'no_completed_rounds',
+  // getPlayerTrendAnalysis / what-if scenarios: fewer than the 3 completed
+  // rounds those analyses mathematically require.
+  'insufficient_rounds',
 ]);
 
 export function extractActionSoftFailure(