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

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

@@ -5,6 +5,30 @@ 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.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.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: belote-cli
-Version: 3.3.1
+Version: 3.3.2
 Summary: A 4-player terminal card game
 Project-URL: Homepage, https://github.com/ElysiumDisc/belote
 Project-URL: Repository, https://github.com/ElysiumDisc/belote

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

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

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

{belote_cli-3.3.1 → belote_cli-3.3.2}/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.2}/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.2}/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.2}/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.2}/tests/test_replay.py

@@ -2,6 +2,8 @@
 
 from __future__ import annotations
 
+import random
+
 from belote.deck import Card, Rank, Suit
 from belote.game import GameState, Phase, Seat, TrickCard
 from belote.replay import DecisionReport, analyze_round, summarize
@@ -46,3 +48,41 @@ def test_analyze_round_returns_one_report_per_south_decision() -> None:
     assert len(out) == 1
     assert out[0].chosen == only
     assert out[0].matched is True
+
+
+def test_analyze_round_deterministic_under_seeded_rng() -> None:
+    """3.3.2: `analyze_round` must thread the caller's seeded RNG into the
+    Hard AI so the same decisions reproduce. Pre-3.3.2 the constructor
+    fell back to an unseeded `random.Random()`, so the SA fallback path
+    (`_hard_play` → `_easy_play` → `rng.choice(legal)`) returned a
+    different suggested card between runs on the same data.
+    """
+    # Sans Atout state with multiple legal cards. `_hard_play` falls through
+    # to `_easy_play` under SA (trump is None) → `self._rng.choice(legal)`
+    # is the only thing picking the suggested card; an unseeded RNG makes
+    # the report non-reproducible.
+    hand = (
+        Card(Suit.HEARTS, Rank.SEVEN),
+        Card(Suit.SPADES, Rank.ACE),
+        Card(Suit.DIAMONDS, Rank.KING),
+        Card(Suit.CLUBS, Rank.JACK),
+    )
+    state = GameState(
+        hands=(hand, (), (), ()),
+        trump=None,
+        contract="sans_atout",
+        turn=Seat.SOUTH,
+        phase=Phase.PLAYING,
+    )
+    chosen = hand[0]
+
+    reports_a = analyze_round([(state, chosen)], rng=random.Random(42))
+    reports_b = analyze_round([(state, chosen)], rng=random.Random(42))
+    reports_c = analyze_round([(state, chosen)], rng=random.Random(42))
+    assert reports_a == reports_b == reports_c
+
+    # Different seed may or may not pick the same card — but each seed
+    # must be self-consistent.
+    reports_d = analyze_round([(state, chosen)], rng=random.Random(7))
+    reports_e = analyze_round([(state, chosen)], rng=random.Random(7))
+    assert reports_d == reports_e