belote-cli 4.8.1__tar.gz → 4.8.2__tar.gz

{belote_cli-4.8.1 → belote_cli-4.8.2}/CHANGELOG.md

@@ -5,6 +5,116 @@ 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).
 
+## [4.8.2] - 2026-05-25
+
+Audit-driven correctness + perf-hygiene release. A deep multi-lane audit
+(bug hunt + logic + performance + game-mechanics-implementation review)
+surfaced two real Sans Atout AI bugs, a joker-registry footgun, a
+joker-state alias hazard, and a handful of low-severity loose ends. All
+findings landed; no rules changes; AI play is more accurate under SA.
+
+### Fixed
+
+- **(B1, HIGH) Hard AI no longer mis-scores off-suit cards as "winning" under
+  Sans Atout** (`src/belote/ai.py::_score_winning_strategy`). Pre-4.8.2 the
+  candidate's rank was `_NONTRUMP_ORDER[card.rank]` regardless of suit, while
+  `highest_rank` was computed from lead-suit cards only. An off-suit Ace
+  (rank 7) compared against a lead-suit Jack (rank 3) fired `win_bonus` even
+  though `_card_beats` (game.py) forbids off-suit cards from winning under SA.
+  The AI burned high off-suit cards when forced to discard. Fix: pin `rank=-1`
+  for off-suit candidates so `rank > highest_rank` is unreachable.
+- **(B2, MED) 2-ply opponent-trump-fear penalty suppressed under SA**
+  (`src/belote/ai.py::_score_winning_strategy`). The penalty assumes opponents
+  can trump the winner. Under SA `trump is None`, so the conditions
+  `trump not in opp_voids` (always True for `None`) and
+  `card.suit != trump` (always True) both passed — the AI penalized any
+  winning play by -8 when the right-hand opponent was known void in lead.
+  Wrapped in `if not is_sa:` so the entire block is moot under SA.
+- **(B3, MED) `ScoreAccumulator._handler_index` rebuilds on `_jokers` mutation**
+  (`src/belote/belatro/core/scoring.py::_fire_jokers`). Pre-4.8.2 the lazy
+  gate was `not self._handler_index and self._jokers`, which is False once
+  `attach_jokers([])` ran (the index has 5 truthy keys with empty lists).
+  Tests that appended to `_jokers` after the empty attach were silently
+  ignored. Fix: identity-set comparison (`_attached_joker_ids`) against the
+  current `_jokers` list — any drift triggers `attach_jokers(self._jokers)`.
+- **(B4, MED) `state._joker_state` alias preserved across post-trigger
+  mutations** (`src/belote/belatro/engine/round_driver.py`). The post-
+  `trigger_round_start` agent_double sabotage block used
+  `replace(state, _joker_state={...})`, which broke the ledger alias and
+  forced the heist block into a defensive dual-write. Replaced with in-place
+  mutation; the heist dual-write is gone too. Classic-Belote reads via
+  `state._joker_state.get(...)` once again see live ledger mutations for the
+  rest of the round.
+- **(B5, LOW) `_compute_belote_points` asserts the announcer↔tracker
+  invariant** (`src/belote/scoring.py`). Hand-built states with
+  `belote_announcer` set but `belote_tracker[0]=False` would silently award
+  belote points; now raises AssertionError.
+- **(B6, LOW) `ContractReward.honor_bonus` default switched to `int 0`**
+  (`src/belote/belatro/core/scoring.py`). Default was `0.0` (float) but the
+  TypedDict declared `int` — worked by numeric duck-typing but drifted from
+  the contract. No behavior change.
+
+### Performance
+
+- **(P1) Hard AI rank lookups consolidated** (`src/belote/ai.py::_hard_play`).
+  Pre-4.8.2 `_score_winning_strategy` called `trick_rank(card, trump, ...)`
+  once per candidate plus once per visible partner card — O(legal ×
+  partner_hand) recomputations. Now `_hard_play` builds `candidate_ranks`
+  and `partner_ranks` once, threaded through `_score_card_play` and
+  `_score_winning_strategy` as new kwargs. The SA off-suit `-1` short-circuit
+  from B1 is baked into the cache, so the canonical comparison is a dict
+  lookup.
+- **(P2) Dropped redundant `from collections import Counter` local in
+  `_hard_play`** — `Counter` is already imported at module top.
+
+### Internal / Doc
+
+- **(L1) `GameState._joker_state` docstring spells out the BelAtro
+  ledger-alias contract** (`src/belote/game.py`). After
+  `trigger_round_start` the dict is shared with `acc._ledger.joker_state`;
+  round-driver mutates in place to preserve the alias. Classic callers
+  outside that scope still use `replace()`.
+- **(L2) `UnlockTracker.on_event` logs at DEBUG on unhandled event types**
+  (`src/belote/belatro/progression/unlocks.py`). Silent no-op was the
+  contract, but a new unlock keyed off `TrickWonEvent` or `BeloteAnnouncedEvent`
+  would silently fail — the log line makes the miss visible under
+  `BELOTE_LOG_LEVEL=DEBUG`.
+- **(L3) `AIMemory.last_partner_hand_key` includes `hide_partner_hand`**
+  (`src/belote/ai.py`). Memo invalidates if the boss flag flips mid-round.
+  Defensive — no boss toggles it today, but a future voucher/joker that
+  changes visibility mid-round would otherwise see stale cached partner
+  cards.
+
+### Tests
+
+- **New file `tests/test_ai_sans_atout.py`** (3 tests) — pins B1 (off-suit
+  Ace not burned), B1 unit-level (no `win_bonus` for off-suit candidate),
+  B2 (2-ply penalty suppressed under SA).
+- **New file `tests/test_ai_deluge_voids.py`** (4 tests) — pins void
+  inference under La Déluge alone, Le Républicain alone, and both
+  combined; plus the negative case (non-wild off-lead card still proves
+  void under Le Républicain).
+- **New file `tests/belatro/test_handler_registry.py`** (3 tests) — B3
+  regression pins: `attach_jokers([])` + append, attach + replace, and the
+  no-drift no-rebuild sanity check.
+- **New file `tests/belatro/test_competition_malediction.py`** (3 tests)
+  — documents the actual stacking behaviour of La Compétition + La
+  Malédiction under `score_round`.
+- **Extended `tests/test_belote.py`** with B5 assertion test.
+- **Extended `tests/belatro/test_phase1_plumbing.py`** with B4 alias
+  survival test.
+- **Extended `tests/test_bidding_all_pass.py`** with end-to-end litige
+  pool consume after two all-pass redeals (T1).
+- Test count baseline: **1044** (4.8.1 had 1028; +16 in 4.8.2).
+
+### Speculative perf (measured, not implemented)
+
+Two speculative items from the plan (P4 `legal_cards` key-build cost; P5
+`ledger.transactional` wrapper overhead) were instrumented and closed.
+Measurement: legal_cards is ~3 % of round time (below the 5 % threshold to
+justify a hand-id-on-tuple refactor); BelAtro round mean is 13.69 ms /
+p95 18.49 ms (73 rounds/sec) — well below any user-visible jank threshold.
+
 ## [4.8.1] - 2026-05-21
 
 Maintenance release: outcome of a thorough multi-lane audit (logic / performance / state management, then four deeper passes). Audit headline: **zero critical or high-severity bugs** survived verification. The two micro-fixes below are pure consistency / micro-optimization. No rules, scoring, AI behavior, or UI behavior changes — `belatro` and `belote` play exactly the same.

{belote_cli-4.8.1 → belote_cli-4.8.2}/DEVELOPMENT.md

@@ -84,7 +84,7 @@ PYTHONPATH=src mypy --strict src/
 # Linting (0 violations expected)
 ruff check src/ tests/
 
-# Full test suite (1028 tests expected)
+# Full test suite (1044 tests expected)
 PYTHONPATH=src pytest
 ```
 

{belote_cli-4.8.1 → belote_cli-4.8.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: belote-cli
-Version: 4.8.1
+Version: 4.8.2
 Summary: A 4-player terminal card game
 Project-URL: Homepage, https://github.com/ElysiumDisc/belote
 Project-URL: Repository, https://github.com/ElysiumDisc/belote
@@ -264,7 +264,7 @@ belote/
 │   ├── input.py       # Platform-dispatched key reader and interruptible sleep
 │   ├── stats.py       # Global and session statistics tracking
 │   └── rules.py       # Game rules content
-├── tests/             # Comprehensive test suite (1028 tests)
+├── tests/             # Comprehensive test suite (1044 tests)
 ├── scripts/           # Performance benchmarks
 ├── pyproject.toml      # Build system and dev dependencies (ruff/mypy)
 ├── LICENSE             # MIT License
@@ -279,14 +279,14 @@ belote/
 PYTHONPATH=src pytest
 ```
 
-Currently **1028 tests** passing with 100% coverage on game-logic modules (4.8.1).
+Currently **1044 tests** passing with 100% coverage on game-logic modules (4.8.2).
 
 ## Technical Integrity
 
 The codebase is strictly validated with the following tools:
 - **mypy**: 0 errors (strict type safety)
 - **ruff**: 0 violations (linting & formatting)
-- **pytest**: 1028/1028 passed
+- **pytest**: 1044/1044 passed
 - **Functional Architecture**: Purely immutable state transitions using `dataclasses.replace`
 - **Performance**: High-efficiency rendering and sub-millisecond AI decision times (see `scripts/benchmark.py`)
 

{belote_cli-4.8.1 → belote_cli-4.8.2}/README.md

@@ -221,7 +221,7 @@ belote/
 │   ├── input.py       # Platform-dispatched key reader and interruptible sleep
 │   ├── stats.py       # Global and session statistics tracking
 │   └── rules.py       # Game rules content
-├── tests/             # Comprehensive test suite (1028 tests)
+├── tests/             # Comprehensive test suite (1044 tests)
 ├── scripts/           # Performance benchmarks
 ├── pyproject.toml      # Build system and dev dependencies (ruff/mypy)
 ├── LICENSE             # MIT License
@@ -236,14 +236,14 @@ belote/
 PYTHONPATH=src pytest
 ```
 
-Currently **1028 tests** passing with 100% coverage on game-logic modules (4.8.1).
+Currently **1044 tests** passing with 100% coverage on game-logic modules (4.8.2).
 
 ## Technical Integrity
 
 The codebase is strictly validated with the following tools:
 - **mypy**: 0 errors (strict type safety)
 - **ruff**: 0 violations (linting & formatting)
-- **pytest**: 1028/1028 passed
+- **pytest**: 1044/1044 passed
 - **Functional Architecture**: Purely immutable state transitions using `dataclasses.replace`
 - **Performance**: High-efficiency rendering and sub-millisecond AI decision times (see `scripts/benchmark.py`)
 

{belote_cli-4.8.1 → belote_cli-4.8.2}/pyproject.toml

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

{belote_cli-4.8.1 → belote_cli-4.8.2}/src/belote/__init__.py

@@ -1,3 +1,3 @@
-__version__ = "4.8.1"
+__version__ = "4.8.2"
 
 __all__ = ["__version__"]

{belote_cli-4.8.1 → belote_cli-4.8.2}/src/belote/ai.py

@@ -39,10 +39,12 @@ class AIMemory:
         # (completed_count, current_trick_len) of the last _update_voids call.
         # Lets us skip re-scanning a stable transient trick on each decision.
         self.last_voids_key: tuple[int, int] | None = None
-        # (completed_count, current_trick_len) of the last partner_hand
-        # rebuild. The partner's hand only changes when they play a card or
-        # a new round starts; same memo pattern as `last_voids_key`.
-        self.last_partner_hand_key: tuple[int, int] | None = None
+        # (completed_count, current_trick_len, hide_partner_hand) of the
+        # last partner_hand rebuild. The partner's hand only changes when
+        # they play a card or a new round starts; same memo pattern as
+        # `last_voids_key`. The third element (`hide_partner_hand`) is the
+        # 4.8.2 L3 addition — invalidates the memo if the boss flag flips.
+        self.last_partner_hand_key: tuple[int, int, bool] | None = None
 
 
 class AIPlayer:
@@ -111,14 +113,18 @@ class AIPlayer:
         # It only changes when partner plays a card (i.e. when
         # (completed_count, current_count) advances). Memo on the same key
         # the void cache uses; skip the rebuild on a no-op repeat call.
-        partner_key = (completed_count, current_count)
+        #
+        # 4.8.2 (L3): include `hide_partner_hand` in the memo key so the
+        # memo invalidates if the boss flag flips mid-round. The flag is
+        # set at round start in current code, but the assumption is
+        # defensive — a future boss or voucher that toggles visibility
+        # mid-round would otherwise see stale cached partner cards.
+        hide = bool(state.boss_modifiers.hide_partner_hand)
+        partner_key: tuple[int, int, bool] = (completed_count, current_count, hide)
         if self.memory.last_partner_hand_key != partner_key:
             p = partner(self.seat)
             self.memory.partner_hand.clear()
-            if (
-                state.phase in (Phase.PLAYING, Phase.SCORING)
-                and not state.boss_modifiers.hide_partner_hand
-            ):
+            if state.phase in (Phase.PLAYING, Phase.SCORING) and not hide:
                 for card in state.hand_of(p):
                     self.memory.partner_hand.add(card)
             self.memory.last_partner_hand_key = partner_key
@@ -597,8 +603,8 @@ class AIPlayer:
         # Precompute per-call counters used by every scoring branch — pre-3.1.0
         # these were recomputed per candidate card (n×4 walks of the hand and
         # memory.played for each legal card).
-        from collections import Counter
-
+        # 4.8.2 (P2): dropped redundant `from collections import Counter`
+        # local import — `Counter` is already imported at module top.
         my_hand = state.hand_of(self.seat)
         hand_suit_counts: dict[Suit, int] = Counter(c.suit for c in my_hand)
         # Under Tout Atout every card is a trump; under a normal contract
@@ -648,6 +654,28 @@ class AIPlayer:
         next_opp = self.seat.next_seat()
         opp_voids = self.memory.known_voids.get(next_opp, set())
 
+        # 4.8.2 (P1): pre-compute per-candidate rank once. `_score_winning_strategy`
+        # called `trick_rank(card, trump, self._se)` once for the candidate and
+        # again for every visible partner card on every legal candidate
+        # iteration — O(legal × partner_hand) recomputations. Building dicts
+        # here collapses that to O(legal + partner_hand) lookups.
+        # Under SA, off-suit candidates get rank -1 (B1 short-circuit) so they
+        # cannot win the trick; lead-suit candidates use `_NONTRUMP_ORDER`.
+        lead_suit_for_ranks = trick[0].card.suit if trick else None
+        if is_sa:
+            candidate_ranks: dict[Card, int] = {
+                c: (_NONTRUMP_ORDER[c.rank] if c.suit == lead_suit_for_ranks else -1)
+                for c in legal
+            }
+            partner_ranks: dict[Card, int] = {
+                c: _NONTRUMP_ORDER[c.rank] for c in self.memory.partner_hand
+            }
+        else:
+            candidate_ranks = {c: trick_rank(c, trump, self._se) for c in legal}
+            partner_ranks = {
+                c: trick_rank(c, trump, self._se) for c in self.memory.partner_hand
+            }
+
         # Score each legal card by expected outcome
         best_card = legal[0]
         best_score: float = -999.0
@@ -665,6 +693,8 @@ class AIPlayer:
                 is_sa=is_sa,
                 highest_rank=highest_rank,
                 opp_voids=opp_voids,
+                card_rank=candidate_ranks[card],
+                partner_ranks=partner_ranks,
             )
             if score > best_score:
                 best_score = score
@@ -685,8 +715,18 @@ class AIPlayer:
         is_sa: bool = False,
         highest_rank: int = -1,
         opp_voids: set[Suit] | None = None,
+        *,
+        card_rank: int | None = None,
+        partner_ranks: dict[Card, int] | None = None,
     ) -> float:
-        """Score a card play decision with advanced heuristics."""
+        """Score a card play decision with advanced heuristics.
+
+        4.8.2 (P1): `card_rank` and `partner_ranks` are pre-computed by
+        `_hard_play` once per call and threaded through so the per-candidate
+        recomputation of `trick_rank` / `_NONTRUMP_ORDER` is gone. Both
+        default to `None` for standalone callers (tests) — the downstream
+        helper falls back to deriving them itself.
+        """
         score = 0.0
         # 4.1.1: per-card point value must honor zero-rank boss flags
         # (kings_zero / aces_zero / jacks_zero / tens_zero / ban_clubs).
@@ -718,6 +758,8 @@ class AIPlayer:
             is_sa=is_sa,
             highest_rank=highest_rank,
             opp_voids=opp_voids,
+            card_rank=card_rank,
+            partner_ranks=partner_ranks,
         )
 
     def _score_leading_strategy(
@@ -778,6 +820,8 @@ class AIPlayer:
         *,
         highest_rank: int | None = None,
         opp_voids: set[Suit] | None = None,
+        card_rank: int | None = None,
+        partner_ranks: dict[Card, int] | None = None,
     ) -> float:
         """Heuristics for trying to win the trick or ducking.
 
@@ -788,9 +832,31 @@ class AIPlayer:
         per card was pure waste. Both default to `None` so standalone
         callers (tests, ad-hoc heuristics) can omit them and the function
         will derive them itself.
+
+        4.8.2 (P1): `card_rank` and `partner_ranks` are similarly hoisted.
+        `card_rank` is the candidate's pre-computed rank under the active
+        scale (`trick_rank` or `_NONTRUMP_ORDER`, with the B1 off-suit-SA
+        short-circuit baked in). `partner_ranks` is the rank lookup for
+        every visible card in `self.memory.partner_hand`. Both default to
+        `None` so standalone callers (tests) can omit them; the function
+        derives them itself.
         """
         score = 0.0
-        rank = trick_rank(card, trump, self._se) if not is_sa else _NONTRUMP_ORDER[card.rank]
+        lead_suit = trick[0].card.suit
+        # B1 (4.8.2): under Sans Atout an off-suit card cannot win the trick
+        # (per `_card_beats` in game.py). Pin `rank = -1` for off-suit
+        # candidates so `rank > highest_rank` is unreachable — pre-4.8.2 an
+        # off-suit Ace got rank=7 against highest_rank≤7 (lead-suit only) and
+        # fired `win_bonus`, causing the AI to dump high off-suit cards under
+        # SA when forced to discard.
+        if card_rank is not None:
+            rank = card_rank
+        elif is_sa and card.suit != lead_suit:
+            rank = -1
+        elif is_sa:
+            rank = _NONTRUMP_ORDER[card.rank]
+        else:
+            rank = trick_rank(card, trump, self._se)
         is_last_trick = len(state.completed_tricks) == 7
         if highest_rank is None:
             highest_rank = max(
@@ -799,13 +865,12 @@ class AIPlayer:
                     if not is_sa
                     else _NONTRUMP_ORDER[tc.card.rank]
                     for tc in trick
-                    if not is_sa or tc.card.suit == trick[0].card.suit
+                    if not is_sa or tc.card.suit == lead_suit
                 ),
                 default=-1,
             )
         if opp_voids is None:
             opp_voids = self.memory.known_voids.get(self.seat.next_seat(), set())
-        lead_suit = trick[0].card.suit
         p = partner(self.seat)
 
         if rank > highest_rank:
@@ -813,7 +878,12 @@ class AIPlayer:
             score += win_bonus
 
             # 2-PLY: If we are winning now, will the next player beat us?
-            if len(trick) < 3:
+            # B2 (4.8.2): suppressed under Sans Atout — there is no trump,
+            # so opponents cannot trump our winner; the entire heuristic is
+            # moot. Pre-4.8.2 it fired (since `None not in opp_voids` is True
+            # and `card.suit != trump` is always True under SA), incorrectly
+            # penalizing winning plays by -8.
+            if not is_sa and len(trick) < 3:
                 next_opp = self.seat.next_seat()
                 if (
                     next_opp != p
@@ -846,14 +916,25 @@ class AIPlayer:
         # happens to fall through to the same ordering today, but the SA
         # path is the canonical one and any future divergence in trick_rank
         # would silently break this heuristic.
+        #
+        # 4.8.2 (P1): rank lookups thread through `partner_ranks` (built
+        # once in `_hard_play`) and the candidate's own `card_rank` is now
+        # the canonical per-call rank. We compare against partner cards in
+        # the same suit using the SAME scale we used for the candidate — so
+        # for an off-suit-SA candidate (rank=-1) the comparison degrades to
+        # "any same-suit partner card strictly stronger" which is always
+        # true; harmless because the candidate doesn't win the trick.
         if self.memory.partner_hand:
-            my_rank = (
-                _NONTRUMP_ORDER[card.rank] if is_sa else trick_rank(card, trump, self._se)
-            )
+            if is_sa:
+                my_rank = _NONTRUMP_ORDER[card.rank]
+            else:
+                my_rank = rank if card_rank is not None else trick_rank(card, trump, self._se)
             for partner_card in self.memory.partner_hand:
                 if partner_card.suit != card.suit:
                     continue
-                if is_sa:
+                if partner_ranks is not None and partner_card in partner_ranks:
+                    partner_rank = partner_ranks[partner_card]
+                elif is_sa:
                     partner_rank = _NONTRUMP_ORDER[partner_card.rank]
                 else:
                     partner_rank = trick_rank(partner_card, trump, self._se)

{belote_cli-4.8.1 → belote_cli-4.8.2}/src/belote/belatro/core/scoring.py

@@ -94,6 +94,13 @@ class ScoreAccumulator:
     # cascade in `_fire_jokers`. Saves ~50–80μs/round (5 jokers × ~25
     # events × ~0.5μs per getattr).
     _handler_index: dict[str, list[tuple[Joker, Any]]] = field(default_factory=dict)
+    # 4.8.2 (B3): identity-set of the jokers passed to the most recent
+    # `attach_jokers` call. Compared against `set(map(id, self._jokers))`
+    # in `_fire_jokers` to detect post-attach mutation. `None` until the
+    # first attach; `set()` after `attach_jokers([])` (which is truthy-
+    # distinguishable from None). Excluded from `compare/repr` so test
+    # state-equality assertions don't break.
+    _attached_joker_ids: set[int] | None = field(default=None, compare=False, repr=False)
     # 4.6.2: RoundLedger lifetime is one round; created in
     # trigger_round_start, sealed in seal_round / materialize. Optional
     # because tests that construct an accumulator without calling
@@ -128,6 +135,12 @@ class ScoreAccumulator:
                     continue  # joker didn't override this handler
                 index[method_name].append((joker, method))
         self._handler_index = index
+        # 4.8.2 (B3): remember exactly which joker objects we registered for so
+        # `_fire_jokers` can detect post-attach mutation of `self._jokers` and
+        # rebuild before firing. A no-override joker still gets tracked here
+        # (so it doesn't trigger spurious rebuilds), even though it has no
+        # entries in `_handler_index`.
+        self._attached_joker_ids = {id(j) for j in jokers}
 
     def _make_ledger(self, state: GameState) -> RoundLedger:
         from .round_ledger import RoundLedger
@@ -283,7 +296,18 @@ class ScoreAccumulator:
             # so the per-event getattr cascade is gone. Lazy build on first
             # use if a caller forgot to call `attach_jokers` (this also
             # protects tests that mutate `self._jokers` directly).
-            if not self._handler_index and self._jokers:
+            #
+            # 4.8.2 (B3): also rebuild if the current `_jokers` list differs
+            # from the identity-set captured at the most recent attach. Pre-
+            # 4.8.2 the gate was `not _handler_index and _jokers` — False once
+            # `attach_jokers([])` runs (the index has 5 truthy keys with empty
+            # lists), so tests that appended to `_jokers` after the empty
+            # attach were silently ignored. Identity-set comparison catches
+            # that case and any other post-attach mutation.
+            if self._attached_joker_ids is None:
+                if self._jokers:
+                    self.attach_jokers(self._jokers)
+            elif self._attached_joker_ids != {id(j) for j in self._jokers}:
                 self.attach_jokers(self._jokers)
             for joker, method in self._handler_index.get(method_name, ()):
                 # 4.6.4: per-joker transactional + EventBus-style isolation.
@@ -379,7 +403,11 @@ class ScoreAccumulator:
                 # The Moon (Sans Atout): honor bonus per honor won
                 if event.trump is None:
                     moon_reward = self.contract_levels.get("sans_atout", {})
-                    honor_bonus = moon_reward.get("honor_bonus", 0.0)
+                    # 4.8.2 (B6): default to `0` (int) so the type-narrowed
+                    # path stays aligned with the `ContractReward.honor_bonus:
+                    # int` TypedDict declaration. The 0.0 default worked by
+                    # accident under Python's numeric duck-typing.
+                    honor_bonus = moon_reward.get("honor_bonus", 0)
                     if honor_bonus:
                         honors = sum(
                             1 for c in event.cards

{belote_cli-4.8.1 → belote_cli-4.8.2}/src/belote/belatro/engine/round_driver.py

@@ -179,6 +179,13 @@ def drive_round(
     # Sources: L'Agent Double boss (3 random tricks), BetrayalArc (tricks 4-8 via
     # agent_double_late_only flag), traitre joker (already populated above).
     # Reading the flag — not boss.id — keeps this site reusable.
+    #
+    # 4.8.2 (B4): mutate `state._joker_state` IN PLACE rather than via
+    # `replace(state, _joker_state={...})`. Post-`trigger_round_start` the
+    # dict IS `acc._ledger.joker_state`; preserving the alias means future
+    # ledger mutations remain visible to classic-Belote reads via
+    # `state._joker_state.get(...)`. Pre-4.8.2 this site broke the alias,
+    # forcing the heist code (below) into a defensive dual-write.
     if state.boss_modifiers.agent_double_active and not state._joker_state.get(
         "agent_double_tricks"
     ):
@@ -186,8 +193,7 @@ def drive_round(
             sabotage_tricks = frozenset(range(4, 9))
         else:
             sabotage_tricks = frozenset(rng.sample(range(1, 9), 3))
-        new_jstate = {**state._joker_state, "agent_double_tricks": sabotage_tricks}
-        state = replace(state, _joker_state=new_jstate)
+        state._joker_state["agent_double_tricks"] = sabotage_tricks
 
     # B4: Use partner trust-based difficulty for the North (partner) AI seat
     _north_diff_str = partner.difficulty_for(Seat.NORTH)
@@ -387,20 +393,17 @@ def drive_round(
     # AI takers never get the prompt — the UICallbacks default returns False
     # and the BelAtro override also gates on `state.taker == Seat.SOUTH`.
     #
-    # Write to BOTH `acc._ledger.joker_state` (the accumulator's source of
-    # truth read by process_event) and `state._joker_state` (the classic-
-    # read path). These usually alias to the same dict — `trigger_round_start`
-    # installs the ledger's dict as `state._joker_state` — but the post-
-    # trigger agent_double sabotage block at line ~175 does a
-    # `replace(state, _joker_state={**state._joker_state, ...})` that breaks
-    # the alias. Mutating both keeps both observers consistent regardless.
+    # 4.8.2 (B4): single-site mutation. `state._joker_state` IS
+    # `acc._ledger.joker_state` after `trigger_round_start` installs the
+    # alias — and the post-trigger sabotage block above now preserves the
+    # alias too (replaced its `replace(state, _joker_state=...)` with
+    # in-place mutation). The pre-4.8.2 dual-write was a workaround for
+    # the broken alias; with the alias hardened, single-write is enough.
     if (
         state.phase == Phase.PLAYING
         and state.taker == Seat.SOUTH
         and ui_callbacks.prompt_heist(state)
     ):
-        if acc is not None and acc._ledger is not None:
-            acc._ledger.joker_state["heist_declared"] = True
         state._joker_state["heist_declared"] = True
 
     # Phase: PLAYING

{belote_cli-4.8.1 → belote_cli-4.8.2}/src/belote/belatro/progression/unlocks.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import logging
 from typing import TYPE_CHECKING
 
 from belote.game import Seat
@@ -10,6 +11,8 @@ from .save import Profile, SaveManager
 if TYPE_CHECKING:
     from ..engine.event_bus import EventBus
 
+_log = logging.getLogger(__name__)
+
 
 class UnlockTracker:
     """
@@ -54,6 +57,13 @@ class UnlockTracker:
             dirty |= self._handle_round_end(event)
         elif isinstance(event, DeclarationScoredEvent):
             dirty |= self._handle_declaration(event)
+        else:
+            # 4.8.2 (L2): silent no-op was the contract pre-4.8.2, but it
+            # masked the case where a new unlock keys off a previously-
+            # unhandled event type (e.g. TrickWonEvent). A debug-level log
+            # lets future maintainers see misses via `BELOTE_LOG_LEVEL=DEBUG`
+            # without breaking prod (default log level is WARNING).
+            _log.debug("UnlockTracker: unhandled event type %s", type(event).__name__)
 
         if dirty:
             self.save_manager.save_profile(self.profile)

{belote_cli-4.8.1 → belote_cli-4.8.2}/src/belote/game.py

@@ -237,8 +237,18 @@ class GameState:
 
     # Same mutable-dict-inside-frozen contract as `belote_holders`. BelAtro
     # jokers and the round driver write per-round flags here. Values must be
-    # scalars (bool/int/str) — see tests/belatro/test_phase1_plumbing.py
+    # scalars (bool/int/str/frozenset) — see tests/belatro/test_phase1_plumbing.py
     # `test_joker_state_only_contains_scalar_values`.
+    #
+    # 4.8.2 (B4 wiring note): inside a BelAtro round this dict is *aliased*
+    # to `ScoreAccumulator._ledger.joker_state` from `trigger_round_start`
+    # onward. The round driver mutates the dict IN PLACE (heist declaration,
+    # agent_double sabotage sets, etc.) to preserve the alias — `replace(
+    # state, _joker_state={...})` would shallow-copy the dict and break it,
+    # making subsequent ledger writes invisible to classic-Belote reads
+    # (ai.py, scoring.py, game.py via `state._joker_state.get(...)`).
+    # Outside the BelAtro round driver, classic callers should still rebuild
+    # via `replace()` to keep the frozen-dataclass discipline.
     _joker_state: dict[str, object] = field(default_factory=dict)
     _chips: int = 0
     _mult: float = 1.0

{belote_cli-4.8.1 → belote_cli-4.8.2}/src/belote/scoring.py

@@ -694,6 +694,17 @@ def _compute_belote_points(ctx: _ScoringContext) -> tuple[int, int, bool, bool]:
     Returns (taker_belote, defender_belote, taker_rebelote, defender_rebelote).
     """
     state = ctx.state
+    # 4.8.2 (B5): pin the invariant that `belote_announcer` and
+    # `belote_tracker[0]` advance in lockstep — game.py:_record_belote_announcement
+    # only assigns the announcer at the moment the tracker flips True. A state
+    # with announcer set but tracker[0]=False would be a corruption from
+    # replay tooling or a hand-built fixture, and the scoring branches below
+    # would credit belote points despite no announcement having fired. Surface
+    # this as a hard assertion rather than silently mis-scoring.
+    assert state.belote_announcer is None or state.belote_tracker[0], (
+        "belote_announcer set without belote_tracker[0] flipped — "
+        "GameState invariant violated."
+    )
     # Prefer the captured announcer seat (recorded at the moment belote was
     # declared) over re-deriving from belote_holders — under L'Anarchie the
     # current state.trump differs from the trump at announcement time, and