fix(frontend): enforce canonical reveal fooled-player refs

frontend/src/api/mappers.ts

@@ -141,24 +141,25 @@ function mapSessionDetail(payload: unknown): SessionDetailResponse {
         };
       }),
       guesses: guessesRaw.map((guess, index) => {
-        const record = asRecord(guess, `session_detail.reveal.guesses[${index}]`);
-        const fooledPlayerId = readNullableNumber(
-          record,
-          'fooled_player_id',
-          `session_detail.reveal.guesses[${index}]`
-        );
+        const path = `session_detail.reveal.guesses[${index}]`;
+        const record = asRecord(guess, path);
+        const fooledPlayerId = readNullableNumber(record, 'fooled_player_id', path);
         const fooledPlayerNickname = record.fooled_player_nickname;
-        if (fooledPlayerNickname !== undefined && !isString(fooledPlayerNickname)) {
-          throw new Error(`Invalid API contract: expected string at session_detail.reveal.guesses[${index}].fooled_player_nickname`);
+        if (fooledPlayerId === null) {
+          if (fooledPlayerNickname !== undefined) {
+            throw new Error(`Invalid API contract: expected ${path}.fooled_player_nickname to be omitted when fooled_player_id is null`);
+          }
+        } else if (!isString(fooledPlayerNickname)) {
+          throw new Error(`Invalid API contract: expected string at ${path}.fooled_player_nickname when fooled_player_id is set`);
         }
         return {
-          player_id: readNumber(record, 'player_id', `session_detail.reveal.guesses[${index}]`),
-          nickname: readString(record, 'nickname', `session_detail.reveal.guesses[${index}]`),
-          selected_text: readString(record, 'selected_text', `session_detail.reveal.guesses[${index}]`),
-          is_correct: readBoolean(record, 'is_correct', `session_detail.reveal.guesses[${index}]`),
+          player_id: readNumber(record, 'player_id', path),
+          nickname: readString(record, 'nickname', path),
+          selected_text: readString(record, 'selected_text', path),
+          is_correct: readBoolean(record, 'is_correct', path),
           fooled_player_id: fooledPlayerId,
           ...(fooledPlayerNickname === undefined ? {} : { fooled_player_nickname: fooledPlayerNickname }),
-          created_at: readString(record, 'created_at', `session_detail.reveal.guesses[${index}]`)
+          created_at: readString(record, 'created_at', path)
         };
       })
     };

frontend/tests/angular-api-client.test.ts

@@ -463,6 +463,130 @@ describe('createAngularApiClient', () => {
     expect(mapped.reveal?.guesses[0]).not.toHaveProperty('fooled_player_nickname');
   });
 
+  it('rejects canonical reveal payloads that include fooled_player_nickname without fooled_player_id', () => {
+    expect(() =>
+      mapSessionDetailResponse({
+        session: { code: 'ABCD12', status: 'reveal', host_id: 1, current_round: 1, players_count: 2 },
+        players: [
+          { id: 2, nickname: 'Maja', score: 10, is_connected: true },
+          { id: 3, nickname: 'Bo', score: 7, is_connected: true }
+        ],
+        round_question: {
+          id: 77,
+          round_number: 1,
+          prompt: 'Q?',
+          shown_at: '2026-03-01T18:00:00Z',
+          answers: [{ text: 'A' }, { text: 'B' }]
+        },
+        reveal: {
+          round_question_id: 77,
+          round_number: 1,
+          prompt: 'Q?',
+          correct_answer: 'A',
+          lies: [],
+          guesses: [
+            {
+              player_id: 3,
+              nickname: 'Bo',
+              selected_text: 'A',
+              is_correct: true,
+              fooled_player_nickname: 'Maja',
+              created_at: '2026-03-01T18:00:15Z'
+            }
+          ]
+        },
+        phase_view_model: {
+          status: 'reveal',
+          round_number: 1,
+          players_count: 2,
+          constraints: {
+            min_players_to_start: 2,
+            max_players_mvp: 8,
+            min_players_reached: true,
+            max_players_allowed: true
+          },
+          host: {
+            can_start_round: false,
+            can_show_question: false,
+            can_mix_answers: false,
+            can_calculate_scores: false,
+            can_reveal_scoreboard: true,
+            can_start_next_round: false,
+            can_finish_game: false
+          },
+          player: {
+            can_join: true,
+            can_submit_lie: false,
+            can_submit_guess: false,
+            can_view_final_result: false
+          }
+        }
+      })
+    ).toThrow('fooled_player_nickname to be omitted when fooled_player_id is null');
+  });
+
+  it('rejects canonical reveal payloads that omit fooled_player_nickname when fooled_player_id is set', () => {
+    expect(() =>
+      mapSessionDetailResponse({
+        session: { code: 'ABCD12', status: 'reveal', host_id: 1, current_round: 1, players_count: 2 },
+        players: [
+          { id: 2, nickname: 'Maja', score: 10, is_connected: true },
+          { id: 3, nickname: 'Bo', score: 7, is_connected: true }
+        ],
+        round_question: {
+          id: 77,
+          round_number: 1,
+          prompt: 'Q?',
+          shown_at: '2026-03-01T18:00:00Z',
+          answers: [{ text: 'A' }, { text: 'B' }]
+        },
+        reveal: {
+          round_question_id: 77,
+          round_number: 1,
+          prompt: 'Q?',
+          correct_answer: 'A',
+          lies: [],
+          guesses: [
+            {
+              player_id: 3,
+              nickname: 'Bo',
+              selected_text: 'B',
+              is_correct: false,
+              fooled_player_id: 2,
+              created_at: '2026-03-01T18:00:15Z'
+            }
+          ]
+        },
+        phase_view_model: {
+          status: 'reveal',
+          round_number: 1,
+          players_count: 2,
+          constraints: {
+            min_players_to_start: 2,
+            max_players_mvp: 8,
+            min_players_reached: true,
+            max_players_allowed: true
+          },
+          host: {
+            can_start_round: false,
+            can_show_question: false,
+            can_mix_answers: false,
+            can_calculate_scores: false,
+            can_reveal_scoreboard: true,
+            can_start_next_round: false,
+            can_finish_game: false
+          },
+          player: {
+            can_join: true,
+            can_submit_lie: false,
+            can_submit_guess: false,
+            can_view_final_result: false
+          }
+        }
+      })
+    ).toThrow('fooled_player_nickname when fooled_player_id is set');
+  });
+
   it('maps host/player gameplay endpoints through typed response mappers', async () => {
     const get = vi.fn<AngularHttpClientLike['get']>(async <T>(url: string) => {
       if (url === '/lobby/sessions/ABCD12/scoreboard') {