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

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

@@ -5,6 +5,57 @@ 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.

{belote_cli-3.3.2 → 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.2 → belote_cli-3.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: belote-cli
-Version: 3.3.2
+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.2 → 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.2 → belote_cli-3.3.3}/pyproject.toml

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

{belote_cli-3.3.2 → 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.2 → 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.2 → 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.2 → belote_cli-3.3.3}/src/belote/game.py

@@ -1059,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.2 → 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.2 → 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.2 → 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)

belote_cli-3.3.3/tests/test_properties.py

@@ -0,0 +1,166 @@
+from __future__ import annotations
+
+import random
+
+from belote.deck import Suit, card_points, deal, make_deck, shuffle
+from belote.game import (
+    Phase,
+    legal_cards,
+    new_game,
+    place_bid,
+    play_card,
+    start_round,
+)
+from belote.scoring import score_round
+
+
+def test_point_conservation_property() -> None:
+    """Total card points must always be 152 for any deal."""
+    deck = make_deck()
+    for _ in range(20):  # 20 random deals
+        rng = random.Random()
+        shuffled = shuffle(deck, rng)
+        hands, up_card, remaining = deal(shuffled)
+
+        # Iterate over standard card-suit trumps only; TOUT_ATOUT scores every
+        # card as trump and intentionally breaks the 152 invariant.
+        for trump in up_card.suit.__class__:
+            if not trump.is_card_suit:
+                continue
+            total = card_points(up_card, trump)
+            for hand in hands:
+                total += sum(card_points(c, trump) for c in hand)
+            total += sum(card_points(c, trump) for c in remaining)
+            assert total == 152
+
+
+def test_legal_moves_never_empty() -> None:
+    """In PLAYING phase, legal_cards() should never return an empty tuple if hand is not empty."""
+    for _ in range(5):  # 5 full game simulations
+        rng = random.Random()
+        state = start_round(new_game(), rng)
+
+        # Mock taking the first suit to enter PLAYING phase
+        from belote.game import place_bid
+
+        state = place_bid(state, state.up_card.suit)
+
+        while state.phase == Phase.PLAYING:
+            seat = state.turn
+            hand = state.hand_of(seat)
+            # An empty hand mid-PLAYING is a deal/play bug; surface it loudly
+            # rather than silently bailing.
+            assert hand, (
+                f"Empty hand for {seat} mid-PLAYING at trick "
+                f"{len(state.completed_tricks)} — invariant violation"
+            )
+
+            legal = legal_cards(state, seat)
+            assert len(legal) > 0, (
+                f"No legal moves for {seat} with hand {hand} at trick {len(state.completed_tricks)}"
+            )
+
+            # Play a random legal card (use the seeded rng for determinism).
+            card = rng.choice(legal)
+            state = play_card(state, card)
+
+
+# ---------------------------------------------------------------------------
+# 3.3.3 T1 — Post-round scoring invariants
+#
+# Drive seeded rounds to completion via the same legal_cards + play_card loop
+# as test_legal_moves_never_empty, then assert post-round invariants. These
+# are the kind of property tests that 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 they existed at the time.
+# ---------------------------------------------------------------------------
+
+
+def _drive_full_round(rng: random.Random, contract_bid: object) -> object:
+    """Play a complete round to terminal phase under the given first-bid.
+
+    `contract_bid` is whatever `place_bid` accepts: a card Suit (normal),
+    `Suit.TOUT_ATOUT`, or `"sans_atout"`. TA/SA are only legal in round 2,
+    so for those we pass 4× to step into round 2 first.
+    """
+    state = start_round(new_game(), rng)
+    is_round_2_only = contract_bid == Suit.TOUT_ATOUT or contract_bid == "sans_atout"
+    if is_round_2_only:
+        for _ in range(4):
+            state = place_bid(state, None)
+    state = place_bid(state, contract_bid)
+    while state.phase == Phase.PLAYING:
+        seat = state.turn
+        legal = legal_cards(state, seat)
+        assert legal, f"No legal moves for {seat} — deal/play bug"
+        card = rng.choice(legal)
+        state = play_card(state, card)
+    return state
+
+
+def test_full_round_consumes_every_card_normal_contract() -> None:
+    """Invariant: after a full round under a normal contract, every hand is
+    empty and exactly 8 completed tricks are recorded. Trip-wire for any
+    bug that leaks a card or short-circuits a trick.
+    """
+    for seed in range(15):
+        rng = random.Random(seed)
+        state = _drive_full_round(rng, Suit.SPADES)
+        # Every hand should be drained.
+        for seat_idx, hand in enumerate(state.hands):
+            assert hand == (), f"seed={seed}: seat {seat_idx} still holds {hand}"
+        # 8 tricks complete.
+        assert len(state.completed_tricks) == 8, (
+            f"seed={seed}: expected 8 tricks, got {len(state.completed_tricks)}"
+        )
+
+
+def test_score_round_sums_to_card_total_normal_contract() -> None:
+    """Invariant: for a successful (non-litige, non-zero-table) normal-suit
+    contract, table_taker_pts + table_defender_pts = 162 (152 card pts +
+    10 dix de der). Boss zero-rank flags would lower this; with no boss
+    active and a normal contract, the sum is exact.
+    """
+    for seed in range(15):
+        rng = random.Random(seed)
+        state = _drive_full_round(rng, Suit.SPADES)
+        bd = score_round(state)
+        table_total = bd.table_taker_pts + bd.table_defender_pts
+        # 152 card pts + 10 dix de der = 162. The card-point conservation
+        # property (152) is already pinned by test_point_conservation_property;
+        # this extends it through scoring to include the last-trick bonus.
+        assert table_total == 162, (
+            f"seed={seed}: table_taker+defender = {table_total}, expected 162"
+        )
+
+
+def test_score_round_sums_to_card_total_tout_atout() -> None:
+    """Invariant: Tout Atout deck = 248 card pts (every card on trump scale)
+    + 10 dix de der = 258. The 3.3.3 sort_hand TA fix (F1) is upstream of
+    this — it doesn't change scoring, but if the TA branch ever bled into
+    card_points the invariant would break and surface here.
+    """
+    for seed in range(15):
+        rng = random.Random(seed)
+        state = _drive_full_round(rng, Suit.TOUT_ATOUT)
+        bd = score_round(state)
+        table_total = bd.table_taker_pts + bd.table_defender_pts
+        assert table_total == 258, (
+            f"seed={seed}: TA table_taker+defender = {table_total}, expected 258"
+        )
+
+
+def test_score_round_sums_to_card_total_sans_atout() -> None:
+    """Invariant: Sans Atout deck = 120 card pts (every card on non-trump
+    scale, 30 per suit × 4) + 10 dix de der = 130. Pin against the
+    L'Anarchie-style "scoring keys on rotated trump" class of bug.
+    (`config.TOTAL_POINTS_SANS_ATOUT` is the authoritative constant.)
+    """
+    for seed in range(15):
+        rng = random.Random(seed)
+        state = _drive_full_round(rng, "sans_atout")
+        bd = score_round(state)
+        table_total = bd.table_taker_pts + bd.table_defender_pts
+        assert table_total == 130, (
+            f"seed={seed}: SA table_taker+defender = {table_total}, expected 130"
+        )