I built a card game mostly with AI. The real work was the guardrails.

/// Runs the full plan pipeline for [observation].
ClassicHareegCpuMovePlan plan(CpuObservation observation) {
  final actions = decodeLegalActions(observation);
  if (actions.isEmpty) {
    return const ClassicHareegCpuMovePlan(
      scenario: ClassicHareegCpuMoveScenario.noLegalActions,
      actionId: null,
    );
  }

  // ... mid-proof on a claimed Fifty: replay the engine's validated step.

  final fifty = firstActionOfKind(
    actions,
    ClassicHareegActionKind.claimFifty,
  );
  if (fifty != null && policy.shouldClaimFifty(observation)) {
    return ClassicHareegCpuMovePlan(
      scenario: ClassicHareegCpuMoveScenario.fiftyClaim,
      actionId: fifty.actionId,
    );
  }

  // ... draw phase: pending-discard handling, take-discard, or draw-stock.

  // Joker replacement is checked BEFORE meld plays: the swap needs the
  // natural card still in hand, and the best meld may consume exactly that
  // card (e.g. three natural 8s whose 8♣ could first reclaim a table joker
  // representing it) — melding first destroys the swap forever, while
  // swapping first keeps the same meld playable with the freed joker.
  final replacement = firstActionOfKind(
    actions,
    ClassicHareegActionKind.replaceJoker,
  );
  if (replacement != null && policy.gateJokerReplacement(observation)) {
    return ClassicHareegCpuMovePlan(
      scenario: ClassicHareegCpuMoveScenario.jokerReplacement,
      actionId: replacement.actionId,
    );
  }

  final holdForFifty = policy.shouldHoldNormalFinishForFifty(observation);
  if (!holdForFifty) {
    final meldAction = bestMeldAction(
      observation,
      partitionLimit: defaultPartitionLimit,
    );
    if (meldAction != null) {
      return ClassicHareegCpuMovePlan(
        scenario: ClassicHareegCpuMoveScenario.meldPlay,
        actionId: meldAction,
      );
    }
    // ... allowAnyLegalMeldFallback for tiers without a partition ranker.
  }

  // ... the cover walk.

  final discard = bestDiscardAction(observation, actions);
  if (discard != null) {
    return ClassicHareegCpuMovePlan(
      scenario: ClassicHareegCpuMoveScenario.safeDiscard,
      actionId: discard.actionId,
    );
  }

  return policy.fallback(observation);
}

static bool holdsNormalFinishForFifty(CpuObservation observation) {
  if (observation.finishingPartition() == null ||
      observation.stockCount < _fiftyHoldStockFloor ||
      handPipValue(observation.ownHand) <= _fiftyHoldHandValueFloor) {
    return false;
  }

  if (observation.ownScore >= _highRiskScoreFloor) {
    return true;
  }
  final target = fiftyPunishTarget(observation);
  return target != null &&
      observation.scoreFor(target) >= _highRiskScoreFloor;
}

/// The only seat a Fifty claimed by [observation]'s seat can punish: the
/// active seat immediately before it in turn order, whose discard the claim
/// would take. Null in the degenerate no-opponents state.
static PlayerSeat? fiftyPunishTarget(CpuObservation observation) {
  final opponents = observation.opponents;
  return opponents.isEmpty ? null : opponents.last;
}

/// Returns priority-sorted coaching insights for [seat] given [controller].
///
/// Highest-priority insight is first; callers may show only `result.first`
/// (the live table routes the list through [CoachInsightFlow] so stage
/// banners dedupe per round).
static List<CoachingInsight> adviseFor(
  ClassicHareegGameController controller,
  PlayerSeat seat,
) {
  final observation = _observationFor(controller, seat);
  // One shared read model for the whole call: the best meld partition, the
  // keep-scores, and the Expert plan are each derived at most once (lazily)
  // and reused by every builder, instead of each builder re-enumerating the
  // same partition lattice.
  final analysis = _CoachingAnalysis(
    controller: controller,
    seat: seat,
    observation: observation,
  );
  final insights = <CoachingInsight>[];

  _addFinish(controller, seat, observation, analysis, insights);
  _addFifty(controller, seat, observation, insights);
  _addTakeAndFinish(controller, seat, observation, insights);
  _addOpening(controller, seat, observation, analysis, insights);
  _addPlayMeld(controller, seat, analysis, insights);
  _addPickup(controller, seat, observation, insights);
  // Cover advice is driven by the Expert plan (see _addCover). Order matters:
  // it runs before _addDiscardSuggestion, which suppresses its floor when the
  // plan surfaced a cover instead.
  _addCover(controller, seat, analysis, insights);
  _addJokerAdvice(controller, seat, insights);
  _addStageBanners(controller, seat, observation, insights);
  _addDiscardSuggestion(controller, seat, observation, analysis, insights);
  _addDrawStock(seat, observation, insights);

  insights.sort((left, right) => right.priority.compareTo(left.priority));
  return List.unmodifiable(insights);
}

/// Returns a bounded legal action surface for CPU turns.
///
/// [legalActionIdsFor] intentionally exposes every legal table play for
/// rules tests and rich UI affordances. CPU turns only need one candidate
/// per high-value category, plus discard fallbacks. Keeping this list small
/// avoids combinatorial meld/opening enumeration blocking the UI isolate.
List<String> cpuActionIdsFor(PlayerSeat seat) {
  // ... timing/debug-log setup, a local finish() helper, and a mid-proof
  // Fifty short-circuit are elided here.

  final plan = _actionSurfacePlanFor(
    seat,
    ClassicHareegActionSurfacePurpose.cpu,
    logSearches: true,
  );
  var ids = plan.actionIds;
  var reason = plan.reason;

  // ... strip static mistake-class ids when the strictness rules out CPU
  // mistakes.

  // A CPU must never be offered a Fifty claim it cannot validly finish. On
  // mistake-allowing tiers (Strict/Table) the claim is advertised so a human
  // can opt into a paid wrong-claim, but for the CPU it is a guaranteed
  // self-penalty — and on Table tier a self-removal. `claim-fifty` is not a
  // static mistake-class id (its mistake-ness depends on the hand), so the
  // filter above cannot catch it; resolve the actual claim and strip it
  // unless it backs a real finish.
  if (ids.contains(ClassicHareegActionIds.claimFifty) &&
      _fiftyClaimPlanFor(
            seat,
            purpose: ClassicHareegFiftyClaimPurpose.apply,
          ).finishPlan ==
          null) {
    ids = [
      for (final id in ids)
        if (id != ClassicHareegActionIds.claimFifty) id,
    ];
    reason = '$reason+nofiftymistake';
  }

  return finish(reason, ids);
}

// ... the public entry partitionsOf(...) is a lazy generator that runs this
// recursive search without materializing all partitions.

Iterable<MeldPartition> _search({
  required List<HareegCard> available,
  required List<HareegCard> leftovers,
  required List<PlacedMeld> melds,
  required List<HareegCard> cardsUsed,
  required List<JokerMeldAssignment> jokerAssignments,
}) sync* {
  _traversed += 1;
  if (_traversed >= safetyCap) {
    return;
  }

  if (melds.length >= minMelds) {
    final partition = MeldPartition(
      melds: melds,
      cardsUsed: cardsUsed,
      cardsRemaining: [...leftovers, ...available],
      jokerAssignments: jokerAssignments,
    );
    if (_passesFilters(partition) && _seen.add(_partitionKey(partition))) {
      yield partition;
      if (_traversed >= safetyCap) {
        return;
      }
    }
  }

  if (available.length < 3 || melds.length >= maxMelds) {
    return;
  }

  final anchor = available.first;
  for (final group in _candidateGroupsContainingAnchor(available, anchor)) {
    if (_traversed >= safetyCap) {
      return;
    }
    final groupIds = group.map((card) => card.id).toSet();
    final remaining = [
      for (final card in available)
        if (!groupIds.contains(card.id)) card,
    ];

    for (final resolved in _resolvedMelds(group)) {
      if (_traversed >= safetyCap) {
        return;
      }
      yield* _search(
        available: remaining,
        leftovers: leftovers,
        melds: [...melds, resolved.meld],
        cardsUsed: [...cardsUsed, ...resolved.meld.cards],
        jokerAssignments: [...jokerAssignments, ...resolved.jokerAssignments],
      );
    }
  }

  if (mustUseCardId == anchor.id) {
    return;
  }

  yield* _search(
    available: List.unmodifiable(available.skip(1)),
    leftovers: [...leftovers, anchor],
    melds: melds,
    cardsUsed: cardsUsed,
    jokerAssignments: jokerAssignments,
  );
}

/// Regression for the "CPU spam-claims Fifty in a loop" bug.
///
/// The rules engine advertises `claim-fifty` whenever the Fifty window is
/// open and points at the seat — even when the seat has no provable finish,
/// because human players still need the affordance to attempt a wrong claim
/// (penalty + lose-turn under Strict / Table). For a CPU the upside of
/// attempting a wrong claim is zero (it eats a penalty and the next loop tick
/// re-advertises the same claim-fifty), so each planner must filter it back
/// out when the seat lacks a finishing partition.
///
/// The bug surfaced as CPU East racking up huge scores (240 in Round 1) from
/// looping a wrong Fifty claim. This file pins the filter into Skilled,
/// Expert, and Priority planners.
void main() {
  group('CPU Fifty filter — claim-fifty without finishing partition', () {
    test(
      'SkilledCpuMovePlanner.plan does not return claim-fifty without proof',
      () {
        const planner = SkilledCpuMovePlanner();
        final plan = planner.plan(
          _FakeCpuObservation(
            legalActionIds: const [
              ClassicHareegActionIds.claimFifty,
              ClassicHareegActionIds.drawStock,
            ],
            ownIsFiftyClaimant: true,
            topDiscard: _card(CardRank.nine, CardSuit.clubs),
            turnPhase: TurnPhase.draw,
          ),
        );

        expect(
          plan.actionId,
          isNot(ClassicHareegActionIds.claimFifty),
          reason:
              'BUG: Skilled must drop claim-fifty when no finishing '
              'partition exists. Without this filter the CPU loops a wrong '
              'claim and inflates the score.',
        );
      },
    );

    // ...the identical assertion is pinned for Expert and Priority planners,
    // plus a positive case proving all three KEEP claim-fifty when the finish
    // is provable (and the same filter holds at the chooseMove boundary).
  });
}