Merge branch 'wl-CG-0MM33XZXJ0KC9H2V-golf-ai-fair-play' into main

Author: rgardler-msft

example-games/golf/AiStrategy.ts

@@ -4,44 +4,51 @@
  * Provides:
  *   - AiStrategy interface: chooseAction(playerState, shared, rng)
  *   - RandomStrategy: uniformly random legal action
- *   - GreedyStrategy: minimizes visible score after the move
+ *   - GreedyStrategy: minimizes visible score after the move (fair play)
  *   - AiPlayer: wrapper that binds a strategy and RNG
  *
  * Uses shared AI module (`@ai`) for base types and utility functions.
+ *
+ * **Fair play guarantee**: All strategies operate on AI-visible state
+ * projections that hide face-down cards and stock pile contents. The AI
+ * cannot peek at hidden information; the information boundary is enforced
+ * structurally by the type system.
  */
 
 import type { Card } from '../../src/card-system/Card';
-import type { GolfGrid } from './GolfGrid';
-import { createGolfGrid } from './GolfGrid';
-import type { GolfMove } from './GolfRules';
-import { applyMove } from './GolfRules';
-import { scoreGrid } from './GolfScoring';
+import type { GolfMove, DrawSource } from './GolfRules';
+import { scoreAiVisibleGrid, simulateAiMoveScore } from './GolfScoring';
 import type {
-  GolfPlayerState,
-  GolfSharedState,
+  AiVisiblePlayerState,
+  AiVisibleSharedState,
+  AiVisibleGrid,
   GolfAction,
 } from './GolfGame';
-import { enumerateLegalMoves, enumerateDrawSources } from './GolfGame';
+import { enumerateAiLegalMoves, enumerateAiDrawSources } from './GolfGame';
 import type { AiStrategyBase } from '../../src/ai';
-import { AiPlayer as AiPlayerBase, pickRandom } from '../../src/ai';
+import { AiPlayer as AiPlayerBase, pickRandom, pickBest } from '../../src/ai';
 
 // ── Strategy interface ──────────────────────────────────────
 
 /**
- * An AI strategy chooses a GolfAction given the current state.
+ * An AI strategy chooses a GolfAction given only AI-visible state.
+ *
+ * The strategy receives filtered state projections that hide face-down
+ * cards and stock pile contents. This makes cheating structurally
+ * impossible — the AI simply cannot access hidden data.
  */
 export interface AiStrategy extends AiStrategyBase {
   /**
    * Choose an action (draw source + move) for the current player.
    *
-   * @param playerState  The AI player's current state.
-   * @param shared       Shared game state (stock pile, discard pile, round end).
+   * @param playerState  The AI player's visible state (face-down cards hidden).
+   * @param shared       Visible shared game state (no stock pile access).
    * @param rng          Random number generator (for tie-breaking or random choice).
    * @returns            The chosen action.
    */
   chooseAction(
-    playerState: GolfPlayerState,
-    shared: GolfSharedState,
+    playerState: AiVisiblePlayerState,
+    shared: AiVisibleSharedState,
     rng: () => number,
   ): GolfAction;
 }
@@ -50,18 +57,21 @@ export interface AiStrategy extends AiStrategyBase {
 
 /**
  * Selects a uniformly random legal action each turn.
+ *
+ * Fair play: uses only `stockHasCards` boolean and `discardTop`
+ * card — never accesses hidden card data.
  */
 export const RandomStrategy: AiStrategy = {
   name: 'random',
 
   chooseAction(
-    playerState: GolfPlayerState,
-    shared: GolfSharedState,
+    playerState: AiVisiblePlayerState,
+    shared: AiVisibleSharedState,
     rng: () => number,
   ): GolfAction {
-    const drawSource = pickRandom(enumerateDrawSources(shared), rng);
+    const drawSource = pickRandom(enumerateAiDrawSources(shared), rng);
 
-    const legalMoves = enumerateLegalMoves(playerState.grid);
+    const legalMoves = enumerateAiLegalMoves(playerState.grid);
     if (legalMoves.length === 0) {
       throw new Error('No legal moves available');
     }
@@ -74,102 +84,157 @@ export const RandomStrategy: AiStrategy = {
 // ── GreedyStrategy ──────────────────────────────────────────
 
 /**
- * Selects the action that minimizes the visible score after the move.
+ * A fair greedy strategy that makes decisions in two phases:
+ *
+ * **Phase 1 — Choose draw source (without peeking at stock):**
+ * The AI evaluates the discard top card (which is visible to all).
+ * If drawing from discard would yield a good score improvement
+ * (compared to the current grid), it prefers discard. Otherwise,
+ * it draws from stock (blind draw — the AI does not know what
+ * card it will get).
+ *
+ * The draw source decision is *committed* before seeing the
+ * stock card. This is structurally enforced because the AI-visible
+ * shared state does not expose any stock pile card data.
  *
- * For each draw source, the strategy simulates drawing, then evaluates
- * every legal move by computing the resulting visible score. The action
- * with the lowest resulting score is chosen. Ties are broken randomly.
+ * **Phase 2 — Evaluate moves with the drawn card:**
+ * After drawing (in the scene), the drawn card becomes known.
+ * The strategy evaluates each legal move using fair AI-visible
+ * scoring (face-down cards scored at average value, no peeking).
  *
- * Note: For stock draws, the card is unknown until drawn, so the greedy
- * strategy draws first, then evaluates. For discard draws, the card is
- * known (peek at top of discard).
+ * Because the GreedyStrategy must commit to a draw source before
+ * seeing the stock card, the `chooseAction` method is split into
+ * two cooperating methods:
+ * - `chooseDrawSource()` — Phase 1
+ * - `chooseMoveForCard()` — Phase 2
  *
- * Implementation approach: since the greedy strategy needs to actually
- * see the drawn card to evaluate moves, we evaluate two scenarios:
- *   1. What if we draw from stock? (We peek at the stock top to decide.)
- *   2. What if we draw from discard? (We peek at the discard top.)
- * Then pick whichever source + move yields the lowest score.
+ * The `chooseAction()` method combines both phases for testing
+ * convenience: when the draw source is 'discard', the discard top
+ * card is known and can be used directly; when 'stock', a move
+ * must be deferred. For the full game flow, the scene calls
+ * the two phases separately.
  */
 export const GreedyStrategy: AiStrategy = {
   name: 'greedy',
 
   chooseAction(
-    playerState: GolfPlayerState,
-    shared: GolfSharedState,
+    playerState: AiVisiblePlayerState,
+    shared: AiVisibleSharedState,
     rng: () => number,
   ): GolfAction {
-    const legalMoves = enumerateLegalMoves(playerState.grid);
+    const drawSource = chooseDrawSource(playerState, shared, rng);
+
+    if (drawSource === 'discard' && shared.discardTop) {
+      // We know the discard card — evaluate moves with it
+      const move = chooseMoveForCard(
+        playerState.grid,
+        shared.discardTop,
+        rng,
+      );
+      return { drawSource, move };
+    }
+
+    // Stock draw: we don't know the card yet, so pick a default move.
+    // In the full game flow, the scene will call chooseMoveForCard()
+    // after the actual draw. For testing/simulation, we need to
+    // return *something* — pick a random legal move as placeholder.
+    const legalMoves = enumerateAiLegalMoves(playerState.grid);
     if (legalMoves.length === 0) {
       throw new Error('No legal moves available');
     }
+    const move = pickRandom(legalMoves, rng);
+    return { drawSource, move };
+  },
+};
+
+/**
+ * Phase 1: Choose whether to draw from stock or discard.
+ *
+ * Heuristic: If the discard top card would improve the grid score
+ * (by swapping with a visible high-value card or completing a column
+ * match), prefer discard. Otherwise, draw from stock (the unknown
+ * might be better than the known-unhelpful discard).
+ *
+ * This decision is made using ONLY visible information:
+ * - The discard top card (visible to all players)
+ * - The AI's own face-up cards
+ * - Whether stock has cards
+ *
+ * @returns 'stock' or 'discard'
+ */
+export function chooseDrawSource(
+  playerState: AiVisiblePlayerState,
+  shared: AiVisibleSharedState,
+  _rng: () => number,
+): DrawSource {
+  const sources = enumerateAiDrawSources(shared);
+  if (sources.length === 1) return sources[0];
 
-    const drawSources = enumerateDrawSources(shared);
+  // If there's no discard card, must draw from stock
+  if (!shared.discardTop) return 'stock';
 
-    interface Candidate {
-      drawSource: typeof drawSources[number];
-      move: GolfMove;
-      score: number;
-    }
+  // If stock is empty, must draw from discard
+  if (!shared.stockHasCards) return 'discard';
 
-    const candidates: Candidate[] = [];
-
-    for (const drawSource of drawSources) {
-      // Peek at the card we'd draw (without actually drawing)
-      let peekCard: Card | undefined;
-      if (drawSource === 'stock') {
-        // Stock: peek at top (last element)
-        peekCard = shared.stockPile.length > 0
-          ? shared.stockPile[shared.stockPile.length - 1]
-          : undefined;
-      } else {
-        peekCard = shared.discardPile.peek();
-      }
-
-      if (!peekCard) continue;
-
-      for (const move of legalMoves) {
-        const score = simulateMoveScore(playerState.grid, peekCard, move);
-        candidates.push({ drawSource, move, score });
-      }
-    }
+  // Evaluate: what's the best score we can achieve with the discard card?
+  const discardCard = shared.discardTop;
+  const currentScore = scoreAiVisibleGrid(playerState.grid);
+  const legalMoves = enumerateAiLegalMoves(playerState.grid);
 
-    if (candidates.length === 0) {
-      // Fallback: random
-      return RandomStrategy.chooseAction(playerState, shared, rng);
+  let bestDiscardScore = Infinity;
+  for (const move of legalMoves) {
+    const score = simulateAiMoveScore(
+      playerState.grid,
+      discardCard,
+      move,
+    );
+    if (score < bestDiscardScore) {
+      bestDiscardScore = score;
     }
+  }
 
-    // Find the minimum score
-    const minScore = Math.min(...candidates.map((c) => c.score));
-    const best = candidates.filter((c) => c.score === minScore);
+  // If the discard card would improve our score, prefer it
+  const discardImprovement = currentScore - bestDiscardScore;
 
-    // Break ties randomly
-    const chosen = pickRandom(best, rng);
-    return { drawSource: chosen.drawSource, move: chosen.move };
-  },
-};
+  if (discardImprovement > 0) {
+    // Discard card helps — take it
+    return 'discard';
+  }
+
+  // Discard card doesn't help — draw from stock (unknown, might be better)
+  return 'stock';
+}
 
 /**
- * Simulate applying a move to a copy of the grid and return the
- * resulting total score (including face-down cards).
+ * Phase 2: Given a drawn card (now known), choose the best move.
+ *
+ * Evaluates every legal move using fair AI-visible scoring:
+ * - Swaps replace the target slot with the known drawn card.
+ * - Discard-and-flip discards the drawn card and flips a face-down
+ *   card (whose value is unknown, estimated as the average).
  *
- * Uses scoreGrid (not scoreVisibleCards) so that revealing a face-down
- * card doesn't artificially penalize the evaluation -- the hidden card's
- * value is always counted either way.
+ * Picks the move that minimizes the resulting score. Ties are broken
+ * randomly.
  */
-function simulateMoveScore(
-  grid: GolfGrid,
+export function chooseMoveForCard(
+  grid: AiVisibleGrid,
   drawnCard: Card,
-  move: GolfMove,
-): number {
-  // Deep-copy the grid (cards are small objects)
-  const gridCopy = createGolfGrid(
-    grid.map((c) => ({ ...c })),
-  );
-  // Deep-copy the drawn card
-  const cardCopy: Card = { ...drawnCard };
-
-  applyMove(gridCopy, cardCopy, move);
-  return scoreGrid(gridCopy);
+  rng: () => number,
+): GolfMove {
+  const legalMoves = enumerateAiLegalMoves(grid);
+  if (legalMoves.length === 0) {
+    throw new Error('No legal moves available');
+  }
+
+  // Score each legal move
+  const scored = legalMoves.map((move) => ({
+    move,
+    score: simulateAiMoveScore(grid, drawnCard, move),
+  }));
+
+  // Pick the best (lowest score), breaking ties randomly
+  const best = pickBest(scored, (c) => -c.score, rng);
+  return best.move;
 }
 
 // ── AiPlayer ────────────────────────────────────────────────
@@ -183,11 +248,33 @@ function simulateMoveScore(
 export class AiPlayer extends AiPlayerBase<AiStrategy> {
   /**
    * Choose an action for the current game state.
+   *
+   * Accepts AI-visible state projections only — cannot access
+   * hidden game data.
    */
   chooseAction(
-    playerState: GolfPlayerState,
-    shared: GolfSharedState,
+    playerState: AiVisiblePlayerState,
+    shared: AiVisibleSharedState,
   ): GolfAction {
     return this.strategy.chooseAction(playerState, shared, this.rng);
   }
+
+  /**
+   * Phase 1: Choose whether to draw from stock or discard.
+   * Used by the scene for two-phase AI turn flow.
+   */
+  chooseDrawSource(
+    playerState: AiVisiblePlayerState,
+    shared: AiVisibleSharedState,
+  ): DrawSource {
+    return chooseDrawSource(playerState, shared, this.rng);
+  }
+
+  /**
+   * Phase 2: Given a drawn card, choose the best move.
+   * Used by the scene after the actual draw for stock draws.
+   */
+  chooseMoveForCard(grid: AiVisibleGrid, drawnCard: Card): GolfMove {
+    return chooseMoveForCard(grid, drawnCard, this.rng);
+  }
 }