belote-cli 3.3.1__tar.gz → 3.3.3__tar.gz

{belote_cli-3.3.1 → belote_cli-3.3.3}/CHANGELOG.md

@@ -5,6 +5,81 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.3.3] - 2026-05-10
+
+Audit-of-audit release — a fresh three-agent codebase pass (classic engine / BelAtro mode / tests + UI) produced ~50 candidate findings. Verification cut that to **3 real fixes** plus **3 net-new invariant test suites** for properties the prior 3.3.x cycles silently relied on. ~14 rejected claims are catalogued at the bottom of this entry so they aren't re-investigated next cycle. 549 tests passing (up from 537), ruff and mypy strict still clean. Plan file at `/home/mrrobot/.claude/plans/bug-hunt-code-performance-tingly-barto.md`.
+
+### Fixed
+
+- **`src/belote/game.py::sort_hand` (F1)** — Under the Tout Atout contract every card should sort by the trump rank ladder (`J > 9 > A > 10 > K > Q > 8 > 7`). Pre-3.3.3 the sort key gated `_TRUMP_RANK_IDX` on `c.suit == trump`, which is *always* false when `trump is Suit.TOUT_ATOUT` because `Card.suit` is one of `SPADES/HEARTS/DIAMONDS/CLUBS` (TA is a contract-level marker, not a card suit). Result: the South hand displayed in the non-trump order whenever the player bid or held TA. Fix: explicit `all_trump = trump is Suit.TOUT_ATOUT` branch in `sort_key`. Also extends `_SUIT_IDX_CACHE` to pre-build the TA entry so the hot path stays cache-resident. UI-only — no scoring impact. Regression test in `tests/test_game_logic.py::test_sort_hand_uses_trump_ladder_under_tout_atout`.
+- **`src/belote/belatro/main.py::_play_blind` (F2)** — Boss assignment on the boss blind now draws from `self.run._get_rng().choice(ALL_BOSS_MODIFIERS)`. Pre-3.3.3 the function imported `random` inline and called `random.choice()` on the module-level RNG — the same class of bug the 3.2.0 release fixed for shop generation and the three RNG-using tarots (`LeJugement` / `LaPretresse` / `LeFou`). Boss assignment was the last unseeded RNG site in the BelAtro round flow; ghost-run reproducibility now observes the same boss for the same seed regardless of prior process-wide RNG state. Regression tests in `tests/belatro/test_belatro.py::TestBossSelectionDeterminism` (behaviour + source-grep against the anti-pattern).
+- **`src/belote/belatro/items/tarots.py::LeJugement` (F3)** — The tarot's description promises *"a random Common Joker"* but the implementation drew from `registry.get_available_jokers(run.profile)` — the full unlocked pool across all rarities. Late-run players with Rare/Legendary jokers unlocked could roll Legendary off this tarot, which is strictly stronger than advertised and mis-prices the consumable. Fix: filter the pool to `getattr(v, "rarity", Rarity.COMMON) == Rarity.COMMON` before the choice; existing empty-pool guard handles the (rare) case where no Commons are available. Regression tests in `tests/belatro/test_belatro.py::TestLeJugementRarity`.
+
+### Added — invariant tests
+
+These are the three test suites the 3.3.x bug cycle has been silently asking for. Each one would have caught at least one prior bug from below.
+
+- **`tests/test_properties.py` — scoring conservation per contract (T1)** — Three new tests drive seeded full rounds and assert `table_taker_pts + table_defender_pts == 162` (normal) / `258` (Tout Atout) / `130` (Sans Atout). Plus a card-consumption invariant: after a full round every hand is empty and exactly 8 tricks were recorded. Would have caught the L'Anarchie belote-zero (3.3.1) and the La Rupture HUD divergence (3.3.1/3.3.2) years earlier had it existed at the time. Also includes a small `_drive_full_round` helper for future scoring-pin tests (handles the round-2-only TA/SA bidding flow).
+- **`tests/test_replay.py` — replay round-trip + seeded determinism (T2)** — Two new tests: (a) record each played card from a seeded run, replay them into a fresh `GameState` built from the same seed, assert identical final state across `team_scores` / `completed_tricks` / `belote_tracker` / `belote_announcer` / `last_trick_winner`; (b) drive the same seed twice and assert identical 32-card sequences. Pins the determinism promise the 3.3.1 AI-RNG fix and the 3.3.2 replay-RNG fix established.
+- **`tests/belatro/test_hud_synergy.py` — solo-half pair test (T3)** — The existing file already exercises the "both halves present → badge fires" direction. The new test adds the negative direction: for each pair in `_SYNERGY_PAIRS`, feed a single half into `detect_synergies` and assert no badge fires. Trip-wire for any change to the synergy matcher that accidentally promotes lone jokers to a pair badge.
+
+### Internal
+
+- **Tests**: 537 → 549 (+12 — 3 F-regressions + 4 T1 + 2 T2 + 1 T3 + extra cross-suit / TA sanity assertions).
+- **Strict gates**: pytest 549/549, mypy 0 errors (76 files), ruff 0 violations.
+- **`_SUIT_IDX_CACHE` widened**: now pre-builds for `(None, Suit.TOUT_ATOUT, *_SUITS_ORDER)` instead of just `(None, *_SUITS_ORDER)`. Removes a per-render cache miss under TA but is otherwise a no-op.
+
+### Rejected — claims catalogued (so they aren't re-investigated)
+
+The three Explore agents that drove this audit surfaced many plausible-sounding findings; the ones below fell apart on direct read of the current code and are documented here to save the next cycle from re-investigating them.
+
+**Already fixed in 3.3.1/3.3.2 (agents read against stale priors):**
+- "`_hard_play` returns `legal[0]` under Sans Atout" — fixed in 3.3.1.
+- "`AIPlayer.__init__` constructs unseeded `Random()`" — fixed in 3.3.1; `analyze_round` followed in 3.3.2.
+- "`AIMemory.last_voids_key` not reset on mid-round undo" — fixed in 3.3.1.
+- "Live HUD diverges from final score under La Rupture" — fixed in 3.3.1 (`compute_trick_winners`) + 3.3.2 (`is_capot(tricks=…)`).
+- "Belote/Rebelote silently zeroed under L'Anarchie when trump rotates" — fixed in 3.3.1 via `GameState.belote_announcer`.
+
+**Interpretive, not bugs:**
+- "`ScoreAccumulator` applies edition before partner-tier scaling, so Holo isn't tier-scaled" — by design. Editions ride along once per joker trigger; tier extras re-apply the *base* joker result. Otherwise an elite-tier Polychrome partner joker would compound geometrically.
+- "Libra's `coinche_multiplier=1.0 × event.coinche_level` makes coinche pay ×5, not ×4" — description is ambiguous; the math matches the Phase 3 design doc (`+1 Mult per coinche level on success`).
+- "Pluto `capot_bonus = 48` is additive to 252 = 300" — that *is* the advertised behaviour.
+- "`_TIERCE_LIKE` has title-case dead entries (`Tierce`/`Quarte`/`Quinte`)" — `decl.kind` is always lowercase (`sequence`/`carre`/`belote`/`rebelote`), so only `"sequence"` ever matches. The joker fires correctly on every Tierce/Quarte/Quinte; the title-case entries are dead but harmless.
+- "QuinteRoyale arms on `event.points >= 100` instead of declaration length" — Quinte = 100 pts in classic Belote and `event.points` is the unmodified `get_declaration_points([...])` computed inline at emit time; the proxy is sound.
+- "`EventBus.emit` has no try/except around handlers" — broad-except would mask real bugs in joker/accumulator code. Current handlers are internal; an exception should surface in dev/test rather than be swallowed.
+- "Negative-edition jokers still pay the 1.5× shop markup" — design: Negative is the rarest edition and grants a permanent +1 joker slot.
+- "Boss `random.choice` doesn't respect profile unlocks" — there is no boss-unlock system in the data model; all bosses are always available by design.
+- "ToutStreak / LeSergent reset semantics don't match flavour text" — joker authoring judgment call. Behaviour matches the registry definition.
+
+**Already addressed by existing code:**
+- "`ScoreAccumulator.update_state` clones `_joker_state` per event" — intentional shallow copy; `test_joker_state_only_contains_scalar_values` pins the scalar invariant.
+- "Registry duplicate-ID overwrites silently" — fixed in 3.2.0; all four `register_*` methods assert same-class re-registration.
+- "`_SUIT_IDX_CACHE` missing TOUT_ATOUT" — addressed as part of F1 (now in the cache).
+
+## [3.3.2] - 2026-05-10
+
+Residual-audit release — a fresh full-codebase pass after 3.3.1 turned up three real findings (a HIGH live-HUD divergence under La Rupture, a MEDIUM determinism leak in `replay.analyze_round`, and a LOW cosmetic chips display). The same pass flagged ~5 plausible-sounding "performance wins" and other claims that fell apart on verification — catalogued in the plan file at `/home/mrrobot/.claude/plans/bug-hunt-code-performance-cheeky-globe.md` so they aren't re-investigated. 537 tests passing (up from 535), ruff and mypy strict still clean.
+
+### Fixed
+
+- **`src/belote/scoring.py::is_capot` + `src/belote/game.py::compute_trick_winners` (F1)** — `is_capot(state, tricks=[…])` now honors La Rupture (`no_consecutive_team_wins`) in the explicit-tricks branch, matching the default-branch behaviour the 3.3.1 La Rupture fix established. The 8th-trick live-HUD CAPOT announcement (`gameflow.py:211-217`) passes an explicit list (`completed_tricks + [current_trick]`) and previously re-derived winners with raw `trick_winner_seat`, falsely shouting "CAPOT!" under La Rupture even though the final score correctly resolved as non-capot. Fix: `compute_trick_winners` now accepts an optional `tricks` override and `is_capot` delegates both branches through it — single source of truth for Rupture-aware winner resolution. Regression test in `tests/belatro/test_boss_modifiers_integration.py::test_is_capot_honors_rupture_in_explicit_tricks_branch`.
+- **`src/belote/replay.py::analyze_round` + `src/belote/gameflow.py` (F2)** — The 3.3.1 fix made `AIPlayer.__init__` accept a seeded `rng` parameter; the round driver threaded it through, but `replay.analyze_round` kept the legacy unseeded fallback. Post-round replay analysis on the 'R' key thus ran the Hard AI with an unseeded `random.Random()`, so "Optimal plays: 6/8 (75%)" could become "5/8 (62%)" between consecutive runs on the same data — most visibly under Sans Atout, where `_hard_play` falls through to `_easy_play` and `rng.choice(legal)` is the sole arbiter. Fix: `analyze_round` takes an optional `rng`, and the gameflow caller passes `current._rng` from the final round state. Regression test in `tests/test_replay.py::test_analyze_round_deterministic_under_seeded_rng`.
+- **`src/belote/belatro/core/scoring.py::get_popup_lines` (F3)** — Score popup now displays clamped chips (`max(0, state._chips)`) to match `get_total()`'s clamp boundary. Pre-3.3.2 L'Égoïste partner-win-heavy rounds rendered "Chips -12 × Mult 2.0 = 0" — internally consistent but visually a bug. Cosmetic only; no logic change.
+
+### Internal
+
+- **Tests**: 535 → 537 (+2 regressions for F1 and F2).
+- **Strict gates**: pytest 537/537, mypy 0 errors (76 files), ruff 0 violations.
+- **`compute_trick_winners` signature widened**: optional `tricks` parameter (default `None` preserves the existing behaviour). Single source of truth for La Rupture-aware winner resolution across both live-HUD and final-scoring paths.
+
+### Rejected — performance "wins" catalogued (so they aren't re-investigated)
+
+- **"`_hard_play` recomputes `Counter` per candidate card"** — falsified. `hand_suit_counts` is hoisted at `ai.py:531` *before* the `for card in legal:` loop and threaded into `_score_card_play` as a parameter.
+- **"`score_round` walks tricks 4×"** — falsified post-3.2.0. `winners` is computed once at `scoring.py:600` and threaded into `_calculate_base_points` and `_apply_scoring_modifiers`. Remaining trick-count passes are two cheap `sum(1 for …)` walks of an 8-element list.
+- **"`play_card` does a wholesale `replace()`"** — true but irreducible. Frozen+slotted GameState is a deliberate design choice; the "fix" would re-introduce the mutation class of bugs the 2.x rewrites eliminated.
+- **"`stats.py` per-round full-rewrite is a regression"** — falsified. It's the B2 (3.3.1) fix for crash-safety, intentional.
+- **"Event-bus `list(self._handlers)` per emit is wasteful"** — defensive copy enabling sub/unsub during emit. Handler counts are static and tiny.
+
 ## [3.3.1] - 2026-05-10
 
 Audit-of-audit release — an inbound LLM audit produced a 18-bug list with mixed accuracy (B1/B2/B7/B8/B9/B10/B14/B16/B17 real; B3/B5/B12/B18 and the ruff-violation claim either self-refuted or hallucinated). The verified subset was fixed, then a fresh independent pass turned up seven additional high-confidence bugs the original audit missed — chiefly La Rupture and L'Anarchie scoring divergences, an unseeded AI RNG that broke ghost-run determinism, and a stale-void inference leak across mid-round undo. All 17 fixes ship in this release. 535 tests passing, ruff and mypy strict still clean.

{belote_cli-3.3.1 → belote_cli-3.3.3}/DEVELOPMENT.md

@@ -84,14 +84,15 @@ PYTHONPATH=src mypy --strict src/
 # Linting (0 violations expected)
 ruff check src/ tests/
 
-# Full test suite (535 tests expected)
+# Full test suite (549 tests expected)
 PYTHONPATH=src pytest
 ```
 
-Current baseline (3.3.1):
-- **mypy**: 0 errors (strict mode)
+Current baseline (3.3.3):
+- **mypy**: 0 errors (strict mode, 76 files)
 - **ruff**: 0 violations
-- **pytest**: 535 tests, 0 failures
+- **pytest**: 549 tests, 0 failures
+- 3.3.3 covered: boss-RNG seeding, Tout Atout hand sort, Le Jugement Common-only filter, plus three new invariant suites (scoring conservation, replay round-trip, HUD synergy negative test).
 
 Run all gates before committing:
 

{belote_cli-3.3.1 → belote_cli-3.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: belote-cli
-Version: 3.3.1
+Version: 3.3.3
 Summary: A 4-player terminal card game
 Project-URL: Homepage, https://github.com/ElysiumDisc/belote
 Project-URL: Repository, https://github.com/ElysiumDisc/belote
@@ -45,6 +45,15 @@ Description-Content-Type: text/markdown
 
 Complete implementation of the French card game Belote for the terminal, with a full-screen green felt table and full card graphics at compass positions (N/W/E/S).
 
+## What's new in 3.3.3
+
+- **Determinism** — Boss assignment in BelAtro mode now draws from the run's seeded RNG instead of the module-level `random`. This was the last unseeded RNG site in the round flow (shop and tarots were converted in 3.2.0, AI in 3.3.1, replay analysis in 3.3.2). Same seed now reproduces the same boss on the boss blind.
+- **UI** — Hands sort by the trump-rank ladder under Tout Atout (Jack first, then 9 / A / 10 / K / Q / 8 / 7). Pre-3.3.3 the predicate `c.suit == trump` was always false under TA because Card.suit is never `Suit.TOUT_ATOUT`, so the South hand displayed in the non-trump order whenever the player bid TA.
+- **Tarot** — Le Jugement now correctly grants only Common jokers as advertised. Pre-3.3.3 the code drew from the full unlocked pool, so late-run players with Rare/Legendary unlocks could roll out-of-rarity jokers off this tarot.
+- **Test moat** — Three new invariant test suites added: scoring-conservation property (`table_taker + table_defender == 162 / 258 / 130` for normal / Tout Atout / Sans Atout), seeded-round replay determinism (same seed → same card sequence → same final state), and HUD synergy-badge negative test (solo half of a pair must not fire the badge). These would have caught most of the 3.3.x bug cycle from below.
+- **Audit reconciliation** — A fresh three-agent codebase pass surfaced ~50 candidate findings; the three above held up under verification and the rest are catalogued in `CHANGELOG.md` so they aren't re-investigated.
+- **Test coverage** — 549 tests (up from 537). Strict gates still clean: pytest 549/549, mypy 0 errors (76 files), ruff 0 violations.
+
 ## What's new in 3.3.1
 
 - **Scoring correctness under bosses** — La Rupture (`no_consecutive_team_wins`) used to be applied to the live HUD but silently ignored by `score_round`, so the running total and final score diverged and impossible capots could be reported. L'Anarchie (dynamic trump) rotated `state.trump` mid-round, after which scoring's `belote_holders.get(trump)` lookup missed any Belote announced on the original trump and silently zeroed the 20/40 bonus. Both are fixed: a new `compute_trick_winners` helper is the single source of truth for La Rupture-aware winner resolution, and a new `belote_announcer: Seat` field captures the announcing seat at declaration time so the rotated trump no longer matters.

{belote_cli-3.3.1 → belote_cli-3.3.3}/README.md

@@ -2,6 +2,15 @@
 
 Complete implementation of the French card game Belote for the terminal, with a full-screen green felt table and full card graphics at compass positions (N/W/E/S).
 
+## What's new in 3.3.3
+
+- **Determinism** — Boss assignment in BelAtro mode now draws from the run's seeded RNG instead of the module-level `random`. This was the last unseeded RNG site in the round flow (shop and tarots were converted in 3.2.0, AI in 3.3.1, replay analysis in 3.3.2). Same seed now reproduces the same boss on the boss blind.
+- **UI** — Hands sort by the trump-rank ladder under Tout Atout (Jack first, then 9 / A / 10 / K / Q / 8 / 7). Pre-3.3.3 the predicate `c.suit == trump` was always false under TA because Card.suit is never `Suit.TOUT_ATOUT`, so the South hand displayed in the non-trump order whenever the player bid TA.
+- **Tarot** — Le Jugement now correctly grants only Common jokers as advertised. Pre-3.3.3 the code drew from the full unlocked pool, so late-run players with Rare/Legendary unlocks could roll out-of-rarity jokers off this tarot.
+- **Test moat** — Three new invariant test suites added: scoring-conservation property (`table_taker + table_defender == 162 / 258 / 130` for normal / Tout Atout / Sans Atout), seeded-round replay determinism (same seed → same card sequence → same final state), and HUD synergy-badge negative test (solo half of a pair must not fire the badge). These would have caught most of the 3.3.x bug cycle from below.
+- **Audit reconciliation** — A fresh three-agent codebase pass surfaced ~50 candidate findings; the three above held up under verification and the rest are catalogued in `CHANGELOG.md` so they aren't re-investigated.
+- **Test coverage** — 549 tests (up from 537). Strict gates still clean: pytest 549/549, mypy 0 errors (76 files), ruff 0 violations.
+
 ## What's new in 3.3.1
 
 - **Scoring correctness under bosses** — La Rupture (`no_consecutive_team_wins`) used to be applied to the live HUD but silently ignored by `score_round`, so the running total and final score diverged and impossible capots could be reported. L'Anarchie (dynamic trump) rotated `state.trump` mid-round, after which scoring's `belote_holders.get(trump)` lookup missed any Belote announced on the original trump and silently zeroed the 20/40 bonus. Both are fixed: a new `compute_trick_winners` helper is the single source of truth for La Rupture-aware winner resolution, and a new `belote_announcer: Seat` field captures the announcing seat at declaration time so the rotated trump no longer matters.

{belote_cli-3.3.1 → belote_cli-3.3.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "belote-cli"
-version = "3.3.1"
+version = "3.3.3"
 description = "A 4-player terminal card game"
 readme = "README.md"
 requires-python = ">=3.10"

{belote_cli-3.3.1 → belote_cli-3.3.3}/src/belote/__init__.py

@@ -1,3 +1,3 @@
-__version__ = "3.3.1"
+__version__ = "3.3.3"
 
 __all__ = ["__version__"]

{belote_cli-3.3.1 → belote_cli-3.3.3}/src/belote/belatro/core/scoring.py

@@ -253,5 +253,9 @@ class ScoreAccumulator:
         return int(chips * mult)
 
     def get_popup_lines(self, state: GameState) -> list[str]:
-        return [*self._log, f"Chips {state._chips} × Mult {state._mult:.1f} = {self.get_total(state)}"]
+        # Match the clamp in get_total(): L'Égoïste can push _chips negative
+        # mid-round; the popup line would otherwise read "Chips -12 × Mult …
+        # = 0" which looks like a UI bug rather than the intended clamp.
+        chips_display = max(0, state._chips)
+        return [*self._log, f"Chips {chips_display} × Mult {state._mult:.1f} = {self.get_total(state)}"]
 

{belote_cli-3.3.1 → belote_cli-3.3.3}/src/belote/belatro/items/tarots.py

@@ -32,9 +32,17 @@ class LeJugement(Tarot):
     description = "Instantly gain a random Common Joker."
 
     def use(self, run: BelAtroRun, context: object) -> None:
+        from .base import Rarity
         from .registry import registry
         run.last_tarot_message = None
-        avail = registry.get_available_jokers(run.profile)
+        # Description promises a Common joker — pre-3.3.3 the pool was the
+        # full unlocked set, so late-run players could roll Rare/Legendary
+        # off this tarot and mis-price it. Filter to Rarity.COMMON only.
+        avail = {
+            k: v
+            for k, v in registry.get_available_jokers(run.profile).items()
+            if getattr(v, "rarity", Rarity.COMMON) == Rarity.COMMON
+        }
         if not avail:
             run.last_tarot_message = "Le Jugement: no jokers available to grant."
             return

{belote_cli-3.3.1 → belote_cli-3.3.3}/src/belote/belatro/main.py

@@ -270,11 +270,13 @@ class BelAtroGame:
             if self.run.card_enhancements.pop("disable_next_boss", False):
                 pass  # boss stays None; deliberately skip the reveal animation
             else:
-                import random
-
                 from .run.boss import ALL_BOSS_MODIFIERS
 
-                boss_cls = random.choice(ALL_BOSS_MODIFIERS)
+                # Use the run's seeded RNG, not the module-level random — same
+                # determinism fix the 3.2.0 release applied to shop generation
+                # and the three RNG-using tarots. Boss assignment was the last
+                # unseeded RNG site in the BelAtro round flow.
+                boss_cls = self.run._get_rng().choice(ALL_BOSS_MODIFIERS)
                 boss = boss_cls()
                 BelAtroAnnounce.boss_reveal(boss, self.reader)
 

{belote_cli-3.3.1 → belote_cli-3.3.3}/src/belote/game.py

@@ -757,6 +757,7 @@ def compute_trick_winners(
     state: GameState,
     trump: Suit | None,
     is_sans_atout: bool,
+    tricks: tuple[tuple[TrickCard, ...], ...] | list[tuple[TrickCard, ...]] | None = None,
 ) -> list[Seat | None]:
     """Resolve the winner of each completed trick, honoring La Rupture.
 
@@ -766,12 +767,18 @@ def compute_trick_winners(
     to live HUD but the final scoring path re-derived winners from raw
     `trick_winner_seat` — silently restoring the original winner and double-
     crediting the round.
+
+    When `tricks` is None (the default), resolves `state.completed_tricks`.
+    Callers building an in-flight trick list (live HUD CAPOT detection on the
+    8th trick) may pass an explicit sequence so the same Rupture rule applies
+    to the projected final state.
     """
     se_trump = state.boss_modifiers.seven_eight_trump
     rupture = state.boss_modifiers.no_consecutive_team_wins
+    source = state.completed_tricks if tricks is None else tricks
     winners: list[Seat | None] = []
     prev_winner: Seat | None = None
-    for trick in state.completed_tricks:
+    for trick in source:
         w = trick_winner_seat(trick, trump, se_trump, is_sans_atout)
         if (
             rupture
@@ -1052,21 +1059,27 @@ def _build_suit_idx(trump: Suit | None) -> dict[Suit, int]:
 
 
 # Pre-compute suit→position maps for every possible trump value (None + the
-# four card suits). sort_hand is called frequently during rendering and this
-# keeps the hot path branch-free.
+# four card suits + TOUT_ATOUT). sort_hand is called frequently during
+# rendering and this keeps the hot path branch-free.
 _SUIT_IDX_CACHE: Final[dict[Suit | None, dict[Suit, int]]] = {
-    trump: _build_suit_idx(trump) for trump in (None, *_SUITS_ORDER)
+    trump: _build_suit_idx(trump) for trump in (None, Suit.TOUT_ATOUT, *_SUITS_ORDER)
 }
 
 
 def sort_hand(hand: tuple[Card, ...], trump: Suit | None) -> tuple[Card, ...]:
     """Sort hand by suit and rank (trump first, then others, honors together)."""
     suit_idx = _SUIT_IDX_CACHE.get(trump) or _build_suit_idx(trump)
+    # Under Tout Atout every card is trump, so the trump-rank ladder applies
+    # to *every* suit. `c.suit == trump` would always be False here because
+    # Card.suit is one of SPADES/HEARTS/DIAMONDS/CLUBS — TOUT_ATOUT is a
+    # contract-level marker, never a card suit.
+    all_trump = trump is Suit.TOUT_ATOUT
 
     def sort_key(c: Card) -> tuple[int, int]:
+        is_trump = all_trump or c.suit == trump
         return (
             suit_idx[c.suit],
-            _TRUMP_RANK_IDX[c.rank] if c.suit == trump else _NORMAL_RANK_IDX[c.rank],
+            _TRUMP_RANK_IDX[c.rank] if is_trump else _NORMAL_RANK_IDX[c.rank],
         )
 
     return tuple(sorted(hand, key=sort_key))

{belote_cli-3.3.1 → belote_cli-3.3.3}/src/belote/gameflow.py

@@ -397,7 +397,7 @@ def run_round(
             sys.stdout.write(f"  Team EW: {ew_pts} points\r\n")
             if replay_decisions:
                 from .replay import analyze_round, summarize
-                reports = analyze_round(replay_decisions)
+                reports = analyze_round(replay_decisions, rng=current._rng)
                 sys.stdout.write(f"  Replay: {summarize(reports)}\r\n")
             sys.stdout.write(f"{'=' * 50}\r\n\r\n")
             sys.stdout.flush()

{belote_cli-3.3.1 → belote_cli-3.3.3}/src/belote/replay.py

@@ -10,6 +10,7 @@ on the round summary screen.
 
 from __future__ import annotations
 
+import random
 from dataclasses import dataclass
 
 from .ai import AIPlayer, Difficulty
@@ -26,15 +27,23 @@ class DecisionReport:
 
 
 def analyze_round(
-    decisions: list[tuple[GameState, Card]], seat: Seat = Seat.SOUTH
+    decisions: list[tuple[GameState, Card]],
+    seat: Seat = Seat.SOUTH,
+    rng: random.Random | None = None,
 ) -> list[DecisionReport]:
     """Replay the given decisions through the Hard AI for `seat` and return
     a per-decision report.
 
     Each tuple is the (state-just-before-the-decision, card-actually-played).
     The function is pure; it doesn't mutate any inputs.
+
+    Pass `rng` to make the report deterministic — the 3.3.1 fix threaded
+    seeded RNG into `AIPlayer.__init__` so personality jitter and easy-AI
+    fallbacks reproduce under a fixed run seed; without an explicit `rng`
+    here, "Optimal: 6/8" can flip to "5/8" between calls on the same data.
+    Default falls through to the legacy unseeded path.
     """
-    ai = AIPlayer(seat, Difficulty.HARD)
+    ai = AIPlayer(seat, Difficulty.HARD, rng=rng)
     reports: list[DecisionReport] = []
     for state, chosen in decisions:
         # Decide_card requires the state's turn to be the seat. Skip otherwise.

{belote_cli-3.3.1 → belote_cli-3.3.3}/src/belote/scoring.py

@@ -18,7 +18,6 @@ from .game import (
     compute_trick_winners,
     reset_round_fields,
     team_of,
-    trick_winner_seat,
 )
 
 # Rank numeric values for sequence detection (ascending order)
@@ -318,9 +317,12 @@ def resolve_declarations(
 def is_capot(state: GameState, tricks: list[tuple[TrickCard, ...]] | None = None) -> int | None:
     """Check if either team won all 8 tricks. Returns team index (0=NS, 1=EW) or None.
 
-    Honors La Rupture (`no_consecutive_team_wins`) when reading the state's
-    own tricks — capot under La Rupture is effectively impossible, but the
-    resolved winners are what the round was actually scored against.
+    Honors La Rupture (`no_consecutive_team_wins`) for both the default
+    (`state.completed_tricks`) and explicit-tricks branches. Capot under La
+    Rupture is effectively impossible; the live HUD CAPOT announcement on the
+    8th trick (`gameflow.py` passes `tricks=completed + [current]`) must use
+    the same Rupture-aware resolution as the final scoring path or it will
+    falsely announce CAPOT mid-round.
     """
     is_sa = state.contract == "sans_atout"
     if tricks is None:
@@ -328,8 +330,7 @@ def is_capot(state: GameState, tricks: list[tuple[TrickCard, ...]] | None = None
     else:
         if not tricks or len(tricks) < 8:
             return None
-        se_trump = state.boss_modifiers.seven_eight_trump
-        winners = [trick_winner_seat(t, state.trump, se_trump, is_sa) for t in tricks]
+        winners = compute_trick_winners(state, state.trump, is_sa, tuple(tricks))
 
     if not winners or len(winners) < 8:
         return None

{belote_cli-3.3.1 → belote_cli-3.3.3}/tests/belatro/test_belatro.py

@@ -1796,3 +1796,101 @@ class TestShop:
         result = self.shop.buy_item(0)
         assert result is True
         assert self.shop.last_buy_failure is None
+
+
+# ===========================================================================
+# 3.3.3 F2 — Boss selection determinism
+# ===========================================================================
+
+
+class TestBossSelectionDeterminism:
+    """F2: BelAtroGame._play_blind now picks the boss via run._get_rng()
+    instead of the module-level random.choice. Same fix class as 3.2.0 for
+    shop and tarots; boss was the last unseeded RNG site."""
+
+    def test_seeded_runs_pick_same_boss_class(self) -> None:
+        from belote.belatro.core.run_state import BelAtroRun
+        from belote.belatro.run.boss import ALL_BOSS_MODIFIERS
+
+        run1 = BelAtroRun(seed=42)
+        run2 = BelAtroRun(seed=42)
+        # The exact call _play_blind now performs.
+        b1 = run1._get_rng().choice(ALL_BOSS_MODIFIERS)
+        b2 = run2._get_rng().choice(ALL_BOSS_MODIFIERS)
+        assert b1 is b2
+
+    def test_play_blind_does_not_use_module_random_for_boss(self) -> None:
+        """Source-level guard: the pre-3.3.3 anti-pattern
+        `random.choice(ALL_BOSS_MODIFIERS)` must not return. If someone
+        reverts to module-level random, this fails before the determinism
+        regression can ship.
+        """
+        import inspect
+
+        from belote.belatro.main import BelAtroGame
+
+        source = inspect.getsource(BelAtroGame)
+        assert "random.choice(ALL_BOSS_MODIFIERS)" not in source, (
+            "Boss selection must go through self.run._get_rng().choice() — "
+            "see 3.3.3 F2."
+        )
+
+
+# ===========================================================================
+# 3.3.3 F3 — LeJugement Common-only rarity
+# ===========================================================================
+
+
+class TestLeJugementRarity:
+    """F3: LeJugement description promises a Common joker; pre-3.3.3 the
+    pool was the full unlocked set so Rare/Legendary unlocks could roll
+    off this tarot. Now filtered to Rarity.COMMON.
+    """
+
+    def test_le_jugement_only_grants_common_jokers(self) -> None:
+        from belote.belatro.core.run_state import BelAtroRun
+        from belote.belatro.items.base import Rarity
+        from belote.belatro.items.tarots import LeJugement
+
+        # Drive enough trials to cover the available pool many times over.
+        # Each pass adds a joker → the slot guard fires after joker_slots
+        # grants and short-circuits. Reset jokers between trials so each
+        # call actually grants.
+        for seed in range(20):
+            run = BelAtroRun(seed=seed)
+            run.jokers = []  # ensure slots aren't full
+            LeJugement().use(run, None)
+            if not run.jokers:
+                # Pool was empty for this seed/profile — the tarot left
+                # a message and returned. Acceptable.
+                continue
+            granted = run.jokers[-1]
+            assert getattr(granted, "rarity", Rarity.COMMON) == Rarity.COMMON, (
+                f"Le Jugement granted {granted.__class__.__name__} of "
+                f"rarity {getattr(granted, 'rarity', None)} — expected Common"
+            )
+
+    def test_le_jugement_empty_pool_sets_message(self) -> None:
+        """If the Common pool is empty (e.g., all jokers are higher-rarity
+        unlockables), LeJugement should fall through to the empty-pool path
+        and set last_tarot_message rather than crash.
+        """
+        from belote.belatro.core.run_state import BelAtroRun
+        from belote.belatro.items.tarots import LeJugement
+
+        run = BelAtroRun(seed=1)
+        run.jokers = []
+        # Monkey-patch the registry lookup to return an empty pool.
+        import belote.belatro.items.tarots as tarot_mod
+        from belote.belatro.items import registry as reg_mod
+
+        orig = reg_mod.registry.get_available_jokers
+        reg_mod.registry.get_available_jokers = lambda profile: {}  # type: ignore[assignment]
+        try:
+            LeJugement().use(run, None)
+            assert run.last_tarot_message is not None
+            assert "no jokers" in run.last_tarot_message.lower()
+            assert run.jokers == []
+        finally:
+            reg_mod.registry.get_available_jokers = orig  # type: ignore[assignment]
+        _ = tarot_mod  # silence unused-import lint

{belote_cli-3.3.1 → belote_cli-3.3.3}/tests/belatro/test_boss_modifiers_integration.py

@@ -2,9 +2,11 @@
 
 from __future__ import annotations
 
+from dataclasses import replace
+
 from belote.deck import Card, Rank, Suit
 from belote.game import BossModifiers, GameState, Phase, Seat, TrickCard
-from belote.scoring import score_round
+from belote.scoring import is_capot, score_round
 
 
 def test_boss_no_belote():
@@ -135,6 +137,54 @@ def test_boss_invert_scoring():
     assert any("Malédiction" in m for m in breakdown.messages)
 
 
+# ── La Rupture: is_capot must honor Rupture in explicit-tricks branch ─────
+
+
+def test_is_capot_honors_rupture_in_explicit_tricks_branch() -> None:
+    """Live HUD CAPOT announcement (`gameflow.py` 8th-trick path) calls
+    `is_capot(state, tricks=completed + [current])`. Pre-3.3.2 that branch
+    re-derived winners with raw `trick_winner_seat`, ignoring La Rupture —
+    so a raw NS sweep falsely shouted CAPOT mid-round while the final score
+    correctly resolved as non-capot via `compute_trick_winners`. Lock the
+    fix: both branches of `is_capot` must agree under La Rupture.
+    """
+    # Eight tricks where the raw winner is SOUTH every time. South leads
+    # Spades (non-trump under trump=HEARTS); others follow with lower
+    # Spades. Cross-trick rank uniqueness doesn't matter for winner
+    # detection.
+    def south_wins(lead_rank: Rank) -> tuple[TrickCard, ...]:
+        return (
+            TrickCard(Seat.SOUTH, Card(Suit.SPADES, lead_rank)),
+            TrickCard(Seat.WEST, Card(Suit.SPADES, Rank.SEVEN)),
+            TrickCard(Seat.NORTH, Card(Suit.SPADES, Rank.EIGHT)),
+            TrickCard(Seat.EAST, Card(Suit.SPADES, Rank.NINE)),
+        )
+
+    high = [Rank.ACE, Rank.TEN, Rank.KING, Rank.QUEEN,
+            Rank.JACK, Rank.ACE, Rank.TEN, Rank.KING]
+    tricks = tuple(south_wins(r) for r in high)
+
+    rupture_state = GameState(
+        hands=((), (), (), ()),
+        trump=Suit.HEARTS,
+        taker=Seat.SOUTH,
+        phase=Phase.SCORING,
+        boss_modifiers=BossModifiers(no_consecutive_team_wins=True),
+        completed_tricks=tricks,
+    )
+
+    # Default branch (tricks=None): already honored Rupture pre-3.3.2.
+    assert is_capot(rupture_state) is None
+
+    # Explicit-tricks branch: must also honor Rupture (the 3.3.2 fix).
+    assert is_capot(rupture_state, tricks=list(tricks)) is None
+
+    # Sanity: without Rupture, both branches see the raw NS sweep.
+    no_rupture = replace(rupture_state, boss_modifiers=BossModifiers())
+    assert is_capot(no_rupture) == 0
+    assert is_capot(no_rupture, tricks=list(tricks)) == 0
+
+
 # ── Anti-pattern lock (3.1.0 modifier_patch shim removal) ──────────────────
 
 

{belote_cli-3.3.1 → belote_cli-3.3.3}/tests/belatro/test_hud_synergy.py

@@ -59,3 +59,23 @@ def test_detect_synergies_empty_for_unrelated_pair() -> None:
         return
     out = detect_synergies([cls() for cls in unrelated])
     assert out == []
+
+
+def test_detect_synergies_does_not_fire_for_solo_half() -> None:
+    """3.3.3 T3: a pair badge must NOT fire when only one half of the pair
+    is owned. Trip-wire for any future change to detect_synergies that
+    accidentally matches single jokers against pair entries.
+    """
+    for left_id, right_id in _SYNERGY_PAIRS:
+        # Confirm the right half is registered (the validate test above
+        # already pins this, but be defensive).
+        if right_id not in registry.jokers or left_id not in registry.jokers:
+            continue
+        left_cls = registry.jokers[left_id]
+        out = detect_synergies([left_cls()])
+        assert (left_id, right_id) not in out, (
+            f"Pair ({left_id}, {right_id}) fired for solo {left_id}"
+        )
+        assert (right_id, left_id) not in out, (
+            f"Pair ({right_id}, {left_id}) fired for solo {left_id}"
+        )

{belote_cli-3.3.1 → belote_cli-3.3.3}/tests/test_game_logic.py

@@ -2,7 +2,8 @@ from __future__ import annotations
 
 import random
 
-from belote.game import GameState, Phase, Seat, new_game, start_round
+from belote.deck import Card, Rank, Suit
+from belote.game import GameState, Phase, Seat, new_game, sort_hand, start_round
 from belote.scoring import ScoringBreakdown, apply_round_score
 
 
@@ -79,3 +80,52 @@ def test_start_round_integrity() -> None:
         assert len(h) == 5
 
     assert state.phase == Phase.BIDDING
+
+
+def test_sort_hand_uses_trump_ladder_under_tout_atout() -> None:
+    """3.3.3 F1: under Tout Atout every card should sort by the trump rank
+    ladder (J > 9 > A > 10 > K > Q > 8 > 7), not the non-trump ladder.
+
+    Pre-3.3.3 the predicate `c.suit == trump` was always false because
+    Card.suit is never Suit.TOUT_ATOUT (TA is a contract-level marker,
+    not a card suit), so all cards fell through to the non-trump ladder
+    and the South hand displayed in the wrong order under TA.
+    """
+    hand = (
+        Card(Suit.SPADES, Rank.SEVEN),
+        Card(Suit.SPADES, Rank.JACK),
+        Card(Suit.SPADES, Rank.NINE),
+        Card(Suit.SPADES, Rank.ACE),
+    )
+    sorted_ta = sort_hand(hand, Suit.TOUT_ATOUT)
+    ranks = [c.rank for c in sorted_ta]
+    assert ranks == [Rank.JACK, Rank.NINE, Rank.ACE, Rank.SEVEN], (
+        f"Tout Atout hand must use trump ladder; got {ranks}"
+    )
+
+    # Cross-suit sanity: with two suits, suits are still grouped (by the
+    # natural _SUITS_ORDER) and within each suit the trump ladder applies.
+    mixed = (
+        Card(Suit.HEARTS, Rank.SEVEN),
+        Card(Suit.SPADES, Rank.JACK),
+        Card(Suit.HEARTS, Rank.JACK),
+        Card(Suit.SPADES, Rank.SEVEN),
+    )
+    sorted_mixed = sort_hand(mixed, Suit.TOUT_ATOUT)
+    # Spades first (suit_idx[SPADES]=0), then hearts; within each: J before 7.
+    assert sorted_mixed == (
+        Card(Suit.SPADES, Rank.JACK),
+        Card(Suit.SPADES, Rank.SEVEN),
+        Card(Suit.HEARTS, Rank.JACK),
+        Card(Suit.HEARTS, Rank.SEVEN),
+    )
+
+    # Regression guard: normal-trump path unchanged. Hearts trump → hearts
+    # use trump ladder, spades use non-trump ladder.
+    sorted_hearts = sort_hand(mixed, Suit.HEARTS)
+    # Hearts comes first (now suit_idx[HEARTS]=0 because trump-shift), and
+    # within hearts: J before 7 (trump ladder). Spades after, non-trump
+    # ladder so JACK is *lower* than 7 in terms of rank-pts but `sort_hand`
+    # uses the rank-index list — JACK_idx=4, SEVEN_idx=7 → J before 7.
+    assert sorted_hearts[0] == Card(Suit.HEARTS, Rank.JACK)
+    assert sorted_hearts[1] == Card(Suit.HEARTS, Rank.SEVEN)