I Built a Card Game Mostly With AI. The Real Work Was the Guardrails.

/// Runs the full plan pipeline for [observation]. The pipeline owns the whole
/// turn — the policy only supplies the per-stage scoring for each branch below.
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 verbatim.

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

  // ...draw phase: take the top discard or draw stock (pending-discard handled above).

  // 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 —
  // 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.
  }

  // ...cover walk, then the threat-ranked safe discard.

  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;
  }

  // Worth the gamble only when the -3 buys me breathing room...
  if (observation.ownScore >= _highRiskScoreFloor) {
    return true;
  }
  // ...or the +3 can actually land on a high-scoring, punishable seat.
  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].
///
/// A pure function of the passed-in state: no mutation, no I/O, no time. It
/// reuses the same analysis brain the Expert CPU uses ([CpuObservation] /
/// [MeldPartitionEnumerator] / cover rules) to classify the human's situation.
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);
  // ...take-and-finish, opening, play-meld, pickup builders, in priority order.
  // Cover advice runs before _addDiscardSuggestion, which suppresses its floor
  // when the Expert 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);
}

/// A bounded legal surface for CPU turns. [legalActionIdsFor] exposes every
/// legal table play for the UI; CPU turns only need one candidate per
/// high-value category plus discard fallbacks, so the heavy meld/opening
/// enumeration never blocks the UI isolate.
List<String> cpuActionIdsFor(PlayerSeat seat) {
  // ...an active Fifty claim replays the engine's validated finish plan step
  // by step, so a CPU claim plays its proof out visibly at normal pacing.

  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 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's mistake-ness depends on the hand,
  // so the static filter above can't catch it — resolve the actual claim and
  // strip it unless it backs a real finishing partition.
  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';
  }

  // finish() logs the timed search, then returns List.unmodifiable(ids).
  return finish(reason, ids);
}

// Public entry: a lazy generator that yields legal partitions one at a time.
//   static Iterable<MeldPartition> partitionsOf(List<HareegCard> hand, {...})

// The recursive core. Every recursion node bumps [_traversed]; the moment it
// reaches [safetyCap] the whole search unwinds, so a pathological hand stops
// the walk instead of exploding (callers take the top slice they can afford).
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;
  }

  // A node with enough melds is itself a legal partition — yield it (deduped).
  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 (available.length < 3 || melds.length >= maxMelds) {
    return;
  }

  // Anchor-based branching: either build a meld CONTAINING the first card...
  final anchor = available.first;
  for (final group in _candidateGroupsContainingAnchor(available, anchor)) {
    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)) {
      yield* _search(
        available: remaining,
        melds: [...melds, resolved.meld],
        cardsUsed: [...cardsUsed, ...resolved.meld.cards],
        // ...carry leftovers + joker assignments forward.
      );
    }
  }

  // ...or skip the anchor into leftovers (unless it is the mustUse card).
  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 with no provable finish, because humans
/// still need the affordance to attempt a wrong claim. For a CPU the upside is
/// zero, so each planner must filter it back out without a finishing partition.
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).
  });
}