belote-cli 4.9.4__tar.gz → 4.9.6__tar.gz

{belote_cli-4.9.4 → belote_cli-4.9.6}/CHANGELOG.md

@@ -5,6 +5,103 @@ 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.9.6] - 2026-06-01
+
+Follow-up bug-hunt, logic, and performance audit. Three parallel Explore agents
+re-swept the classic engine, BelAtro mechanics, and the UI/render layer; every
+"major" finding was then traced to exact code and verified before acting. The
+result: **no critical or major bug survived verification.** The flagged items
+were all either false positives (Le Passeur "double-payout" — the post-coinche
+`BidMadeEvent` re-emit carries the taker's seat + a real trump, so the
+North-pass gate never matches; Le Carnet's +1 Mult *is* wired via
+`acc.carnet_active`; Tout Streak / Quinte Royale re-emit guards are already
+present; `modifier_patch` is a fresh per-instance proxy each round) or
+intentional, test-pinned behaviour (Le Patriote's `// 2`). Benchmarks confirmed
+the render/scoring/AI paths are already well within budget (render ≈0.4 ms, E2E
+round ≈4–6 ms). This release therefore lands the one genuine latent gap the
+audit surfaced plus a layer of behaviour-locking tests. Test count 1079 → 1111.
+
+### Added
+
+- **Minimal wide-character (wcwidth) support** (`src/belote/ansi.py`). `visible_len()`
+  previously counted codepoints, so `ansi_center()` / `ansi_ljust()` and the
+  render diff's per-row width would mis-align by one cell per wide glyph (emoji,
+  CJK). A new dependency-free `char_width()` (stdlib `unicodedata`) returns 0
+  for combining/zero-width marks, 2 for East-Asian Wide/Fullwidth, 1 otherwise,
+  and `visible_len()` now measures display **cells**. A pure-ASCII escape-free
+  fast path keeps the hot render path allocation-free and byte-identical, so
+  there is no performance regression. A new `ansi_truncate()` (cell-aware,
+  escape-skipping) replaces the raw byte-slices that trimmed BelAtro HUD joker
+  names and synergy lines (`belatro/ui/hud.py`), which could previously split a
+  wide glyph.
+- **Behaviour-locking tests** that freeze what the audit confirmed correct:
+  `tests/test_render_golden.py` (full-frame snapshot + per-row cell-width
+  fingerprint — the regression guard for the wcwidth change),
+  `tests/test_wcwidth.py` (per-character widths and helper cell-correctness),
+  `tests/test_scoring_totals.py` (the canonical 152 / 120 / 248 point totals,
+  belote 20, capot bases 252 / 220 / 348, dix de der +10), and
+  `tests/belatro/test_registry_integrity.py` (item-census counts 42 jokers /
+  8 planets / 12 tarots / 12 vouchers, id↔key consistency, no duplicate display
+  names — so a duplicate-id registration that silently overwrites an item now
+  fails a test).
+
+## [4.9.5] - 2026-05-28
+
+Bug-hunt, logic, and performance audit pass. Three parallel Explore agents
+swept the classic engine, BelAtro mechanics, and the UI/render layer; every
+finding below was traced to exact code and the high-severity ones reproduced at
+runtime before fixing. Test count 1066 → 1079.
+
+### Fixed
+
+- **Crash: `legal_cards` returned an empty set under La Déluge**
+  (`src/belote/game.py`). With the `seven_eight_trump` boss active, every 7/8
+  is a trump — but the trump-follow set was built from `c.suit == lead_suit`,
+  which dropped off-suit 7/8s. A player void of the trump *suit* but holding
+  only off-suit 7/8 (which ARE trumps) got zero legal cards on a trump lead,
+  tripping `AIPlayer.decide_card`'s empty-legal assertion. A single
+  `is_trump_card` predicate now drives both the trump-led and non-trump-led
+  follow/overtrump paths. Regression tests in `tests/test_deluge_legal_cards.py`.
+- **AI partner-signal double-count after a mid-round undo** (`src/belote/ai.py`).
+  The undo-regression branch reset the void cache and `processed_tricks_count`
+  but not the partner-signal tally; because `_update_voids` re-walks surviving
+  tricks from zero, their signals were counted twice. Both reset paths now share
+  a single `_reset_round_memory()` helper so they can't drift again.
+- **Belote + Rebelote scored 40 instead of the official 20** (`src/belote/config.py`).
+  Holding the King and Queen of trump is worth 20 points *total* in official
+  French Belote — and the in-game Rules screen already said 20. `REBELOTE_POINTS`
+  is now 20, matching both.
+- **Coinche round-end animation showed the pre-multiplier score**
+  (`src/belote/gameflow.py`). The score counter animated to the raw breakdown
+  total while the stored score applied `2 ** coinche_level`. Both now use the
+  shared `scoring.coinche_adjusted_credits()` helper, so the animation lands on
+  the real total.
+- **Joker money not reconciled on a failed-but-survived round**
+  (`src/belote/belatro/main.py`). Signed `JokerResult.add_money` (e.g.
+  LePrêteur's −$5 skim, baked into the round's ×Mult) was only applied on the
+  success path, handing a free multiplier when a chute was survived via Capot
+  Insurance. A shared `_reconcile_bonus_money()` helper now runs on both paths.
+- **La Symbiose fired ×1.2 Mult on zero-point declarations under Le Mime**
+  (`src/belote/belatro/items/partner_jokers/passive.py`). Now gated on
+  `event.points > 0`, mirroring Le Mathématicien.
+
+### Changed
+
+- **BelAtro HUD / TrustBar now invalidate the render diff** after their direct
+  stdout writes (`belatro/ui/hud.py`, `trust_bar.py`), matching the 4.0.0
+  overlay convention so a static-state `display()` can't leave a stale top bar.
+  The convention is now enforced for both files by
+  `tests/test_alt_screen_scroll.py`.
+- **Performance**: `_pip_at`'s LRU cache raised 4096 → 8192 so wide-terminal
+  felt mats (>5000 cells/frame) stop thrashing it (`ui/render.py`);
+  `visible_len` no longer spends cache slots on plain (no-ANSI) strings
+  (`ansi.py`); the BelAtro [H] history overlay caches its line list on
+  `(term_w, entry_count)` instead of rebuilding every keystroke
+  (`belatro/ui/history.py`).
+- **Docs**: corrected the trust tier-0 docstring (it claimed "effects halved";
+  the implementation applies the baseline once with no penalty) and the tier
+  bonus percentages to match the `(0, 0, 1, 1, 2)` extra-applies model.
+
 ## [4.9.4] - 2026-05-26
 
 Audit + maintenance pass. Three parallel Explore agents reviewed game-logic

{belote_cli-4.9.4 → belote_cli-4.9.6}/DEVELOPMENT.md

@@ -84,7 +84,7 @@ PYTHONPATH=src mypy --strict src/
 # Linting (0 violations expected)
 ruff check src/ tests/
 
-# Full test suite (1066 tests expected)
+# Full test suite (1111 tests expected)
 PYTHONPATH=src pytest
 ```
 
@@ -221,6 +221,10 @@ PYTHONPATH=src python scripts/benchmark.py
 If you suspect a per-frame allocation regression, the canonical hot paths to
 profile live (e.g. with `py-spy record --rate 100`) are `render()` in
 `src/belote/ui/render.py` and `_calculate_legal_cards_impl` in
-`src/belote/game.py`. The 4.9.4 audit pass found no quick wins beyond those
-already landed in the 4.6.x / 4.7.x perf cleanups — start from a profiler
-trace, not from guesswork, before adding new caches.
+`src/belote/game.py`. The 4.9.4 / 4.9.5 / 4.9.6 audit passes found only minor wins
+beyond those already landed in the 4.6.x / 4.7.x perf cleanups (4.9.5 bumped
+the `_pip_at` cache to 8192, trimmed `visible_len`'s cache to ANSI strings,
+and memoised the BelAtro history overlay; 4.9.6 made `visible_len` measure
+terminal *cells* via a minimal `char_width`, keeping the allocation-free
+ASCII fast path so the hot path is unchanged) — start from a profiler trace,
+not from guesswork, before adding new caches.

{belote_cli-4.9.4 → belote_cli-4.9.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: belote-cli
-Version: 4.9.4
+Version: 4.9.6
 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 (1069 tests)
+├── tests/             # Comprehensive test suite (1111 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 **1069 tests** passing with 100% coverage on game-logic modules (4.9.4).
+Currently **1111 tests** passing with 100% coverage on game-logic modules (4.9.6).
 
 ## Technical Integrity
 
 The codebase is strictly validated with the following tools:
 - **mypy**: 0 errors (strict type safety)
 - **ruff**: 0 violations (linting & formatting)
-- **pytest**: 1044/1044 passed
+- **pytest**: 1111/1111 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.9.4 → belote_cli-4.9.6}/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 (1069 tests)
+├── tests/             # Comprehensive test suite (1111 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 **1069 tests** passing with 100% coverage on game-logic modules (4.9.4).
+Currently **1111 tests** passing with 100% coverage on game-logic modules (4.9.6).
 
 ## Technical Integrity
 
 The codebase is strictly validated with the following tools:
 - **mypy**: 0 errors (strict type safety)
 - **ruff**: 0 violations (linting & formatting)
-- **pytest**: 1044/1044 passed
+- **pytest**: 1111/1111 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.9.4 → belote_cli-4.9.6}/pyproject.toml

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

{belote_cli-4.9.4 → belote_cli-4.9.6}/src/belote/__init__.py

@@ -1,3 +1,3 @@
-__version__ = "4.9.4"
+__version__ = "4.9.6"
 
 __all__ = ["__version__"]

{belote_cli-4.9.4 → belote_cli-4.9.6}/src/belote/ai.py

@@ -74,6 +74,27 @@ class AIPlayer:
         # All ranking helpers in this class read it via self._se.
         self._se = False
 
+    def _reset_round_memory(self) -> None:
+        """Clear all per-round derived memory back to a clean slate.
+
+        Shared by the new-round and mid-round-undo paths in ``update_memory`` so
+        the two can't drift: a partial reset (e.g. clearing the void cache but
+        not the partner-signal tally) would let ``_update_voids`` re-walk the
+        surviving tricks and double-count their signals.
+        """
+        self.memory.played.clear()
+        for s in Seat:
+            self.memory.known_voids[s].clear()
+        self.memory.partner_hand.clear()
+        self.memory.processed_tricks_count = 0
+        self.memory.last_voids_key = None
+        self.memory.last_partner_hand_key = None
+        # 4.9.0 / G2: partner-signal tally and our emit-counter follow
+        # the same reset pattern as the void cache.
+        for suit in Suit:
+            self.memory.signals[suit] = 0
+        self.memory.signals_emitted = 0
+
     def update_memory(self, state: GameState) -> None:
         """Update memory with currently visible information."""
         completed_count = len(state.completed_tricks)
@@ -84,18 +105,7 @@ class AIPlayer:
             # this a (0, 0) / (0, 1) key from the first decision of *this* round
             # could coincidentally match a leftover from the previous round and
             # cause _update_voids to skip processing entirely.
-            self.memory.played.clear()
-            for s in Seat:
-                self.memory.known_voids[s].clear()
-            self.memory.partner_hand.clear()
-            self.memory.processed_tricks_count = 0
-            self.memory.last_voids_key = None
-            self.memory.last_partner_hand_key = None
-            # 4.9.0 / G2: partner-signal tally and our emit-counter follow
-            # the same triple-reset pattern as the void cache.
-            for suit in Suit:
-                self.memory.signals[suit] = 0
-            self.memory.signals_emitted = 0
+            self._reset_round_memory()
         elif (
             self.memory.last_voids_key is not None
             and (completed_count, current_count) < self.memory.last_voids_key
@@ -104,13 +114,12 @@ class AIPlayer:
             # we've processed. `known_voids` and `processed_tricks_count`
             # are monotonic and would carry stale inferences forward
             # (a void inferred from a now-rolled-back trick). Rebuild from
-            # the current state instead of trying to subtract.
-            self.memory.played.clear()
-            for s in Seat:
-                self.memory.known_voids[s].clear()
-            self.memory.processed_tricks_count = 0
-            self.memory.last_voids_key = None
-            self.memory.last_partner_hand_key = None
+            # the current state instead of trying to subtract. The signal
+            # tally is rebuilt by _update_voids' re-walk (processed count is
+            # reset to 0), so it MUST be cleared here too — otherwise the
+            # surviving tricks' signals are double-counted. Same full reset
+            # as a new round.
+            self._reset_round_memory()
 
         # Track all cards in completed tricks. N is small (max 32 cards), so
         # the O(N) re-walk is fine and keeps this in sync with the transient

{belote_cli-4.9.4 → belote_cli-4.9.6}/src/belote/ansi.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 import os
 import re
+import unicodedata
 from dataclasses import dataclass
 from functools import lru_cache
 
@@ -102,15 +103,52 @@ RESET = "\x1b[0m"
 
 
 @lru_cache(maxsize=4096)
+def char_width(ch: str) -> int:
+    """Terminal display width of a single character, in cells.
+
+    4.9.6: minimal, dependency-free wcwidth using only the stdlib
+    ``unicodedata``. Combining marks and zero-width codepoints occupy 0 cells;
+    East-Asian Wide/Fullwidth glyphs (CJK, many emoji) occupy 2; everything
+    else 1. Not a full Unicode-grapheme/emoji-ZWJ implementation — it is the
+    pragmatic subset the UI needs so ``visible_len`` reports *cells*, not
+    codepoints, and centering/padding/truncation stay aligned.
+    """
+    # C0/C1 controls (other than handled escapes) have no width here.
+    if ch == "\x00":
+        return 0
+    if unicodedata.combining(ch) or unicodedata.category(ch) in ("Mn", "Me", "Cf"):
+        return 0
+    if unicodedata.east_asian_width(ch) in ("W", "F"):
+        return 2
+    return 1
+
+
+@lru_cache(maxsize=2048)
+def _visible_len_ansi(s: str) -> int:
+    return sum(char_width(c) for c in _RESET_RE.sub("", s))
+
+
 def visible_len(s: str) -> int:
-    """Return length of string with ANSI escape codes stripped."""
-    if "\x1b" not in s:
+    """Return the terminal *cell* width of a string, ignoring ANSI escapes.
+
+    4.9.5 (P3): only the regex-stripping path is cached — plain (no-ESC)
+    strings skip the bounded cache so it stays reserved for ANSI strings that
+    benefit from memoising the regex sub (static glyphs, frames).
+
+    4.9.6: width is measured in display cells (see ``char_width``), not
+    codepoints. Pure-ASCII *escape-free* strings — the overwhelmingly common
+    case — take the allocation-free ``len(s)`` fast path since every such char
+    is exactly one cell. Anything with an ESC (note: ESC is itself ASCII, so it
+    must be excluded explicitly) or any non-ASCII char pays for the strip +
+    per-char width sum.
+    """
+    if "\x1b" not in s and s.isascii():
         return len(s)
-    return len(_RESET_RE.sub("", s))
+    return _visible_len_ansi(s)
 
 
 def ansi_center(s: str, width: int) -> str:
-    """Center a string by visible width, padding both sides."""
+    """Center a string by visible cell width, padding both sides."""
     vlen = visible_len(s)
     pad = max(0, width - vlen)
     left = pad // 2
@@ -119,7 +157,7 @@ def ansi_center(s: str, width: int) -> str:
 
 
 def ansi_ljust(s: str, width: int) -> str:
-    """Left-justify a string to `width` visible characters, ANSI-aware.
+    """Left-justify a string to `width` visible cells, ANSI-aware.
     Never use str.ljust() on ANSI strings — it counts escape bytes as chars.
     """
     vlen = visible_len(s)
@@ -127,6 +165,39 @@ def ansi_ljust(s: str, width: int) -> str:
     return s + " " * pad
 
 
+def ansi_truncate(s: str, width: int) -> str:
+    """Truncate `s` to at most `width` visible cells, skipping ANSI escapes.
+
+    Cell-aware: a wide (2-cell) glyph that would straddle the boundary is
+    dropped rather than split. ASCII strings without escapes take a plain slice
+    fast path. Returns the original string untouched when it already fits.
+    """
+    if s.isascii() and "\x1b" not in s:
+        return s if len(s) <= width else s[:width]
+    if visible_len(s) <= width:
+        return s
+    out: list[str] = []
+    used = 0
+    i = 0
+    n = len(s)
+    while i < n:
+        ch = s[i]
+        if ch == "\x1b":
+            # Copy the whole escape sequence verbatim (zero width).
+            m = _RESET_RE.match(s, i)
+            if m:
+                out.append(m.group())
+                i = m.end()
+                continue
+        w = char_width(ch)
+        if used + w > width:
+            break
+        out.append(ch)
+        used += w
+        i += 1
+    return "".join(out)
+
+
 @lru_cache(maxsize=512)
 def _fg_seq(r: int, g: int, b: int) -> str:
     return f"\x1b[38;2;{r};{g};{b}m"

{belote_cli-4.9.4 → belote_cli-4.9.6}/src/belote/belatro/items/partner_jokers/passive.py

@@ -29,7 +29,10 @@ class LaSymbiose(Joker):
     is_partner_joker = True
 
     def on_declaration(self, event: DeclarationScoredEvent, state: dict[str, Any]) -> JokerResult | None:
-        if event.seat == Seat.NORTH:
+        # Gate on points so Le Mime (declarations_zero) — which emits
+        # declarations worth 0 — doesn't grant the multiplier for a
+        # declaration that scored nothing. Mirrors LeMathematicien's guard.
+        if event.seat == Seat.NORTH and event.points > 0:
             return JokerResult(times_mult=1.2)
         return None
 

{belote_cli-4.9.4 → belote_cli-4.9.6}/src/belote/belatro/main.py

@@ -326,6 +326,22 @@ class BelAtroGame:
         for msg in self.unlock_tracker.drain_announcements():
             BelAtroAnnounce.banner(msg, self.reader, hold=1.5)
 
+    def _reconcile_bonus_money(self, bonus_money: int) -> None:
+        """Apply a round's signed joker money to the wallet.
+
+        ``final_state._bonus_money`` accumulates ``JokerResult.add_money`` over
+        the round (positive = credit, negative = debit such as LePreteur's -$5
+        skim). Positive amounts credit; negative amounts route through
+        ``spend_money`` (which no-ops if the wallet can't cover it) so the
+        Economy's non-negative guard on ``add_money`` is respected.
+        """
+        if self.run is None:
+            return
+        if bonus_money > 0:
+            self.run.economy.add_money(bonus_money)
+        elif bonus_money < 0:
+            self.run.economy.spend_money(-bonus_money)
+
     def _run_loop(self) -> None:
         """Main game loop: Blind -> Shop -> Next."""
         if self.run is None:
@@ -617,6 +633,12 @@ class BelAtroGame:
                     color="red",
                     hold=2.5,
                 )
+            else:
+                # The run continues past this chute. Reconcile signed joker
+                # money (e.g. LePreteur's -$5 skim, which was baked into the
+                # round's ×Mult) so the player isn't handed a free multiplier
+                # for the surviving round. spend_money no-ops if broke.
+                self._reconcile_bonus_money(final_state._bonus_money)
             if not lock_trust:
                 trust.blind_failed()
         else:
@@ -624,16 +646,7 @@ class BelAtroGame:
             payout = self.run.economy.process_round_end(total - self.run.target_score)
             if auto_coinche_active:
                 self.run.economy.add_money(payout * 2)  # L'Avocat: triple total payout
-            # JokerResult.add_money is signed: positive = credit, negative = debit.
-            # Pre-4.6.5 this branch was `> 0`, which silently dropped LePreteur's
-            # `-5` cost (and any other negative-add_money joker) while still
-            # applying the multiplier — free ×1.2 Mult on every $50+ round.
-            if final_state._bonus_money > 0:
-                self.run.economy.add_money(final_state._bonus_money)
-            elif final_state._bonus_money < 0:
-                # Route through spend_money so the Economy negative guard fires
-                # if accumulated debit somehow exceeds wallet (caller's bug).
-                self.run.economy.spend_money(-final_state._bonus_money)
+            self._reconcile_bonus_money(final_state._bonus_money)
             if final_state._joker_state.get("puriste_triggered"):
                 extra = max(0, (total - self.run.target_score) // 10)
                 self.run.economy.add_money(extra)  # Le Puriste: double base payout

{belote_cli-4.9.4 → belote_cli-4.9.6}/src/belote/belatro/partner/trust.py

@@ -73,15 +73,19 @@ class TrustTrack:
     def tier(self) -> int:
         """Five-tier bucketing for partner-joker effect scaling.
 
-        0 (degraded, value 0–2) — partner-joker effects halved
-        1 (base, value 3–4)     — baseline
-        2 (boost, value 5–6)    — +25%
-        3 (strong, value 7–8)   — +50%
-        4 (elite, value 9–10)   — +100%
+        Scaling is implemented as N *extra* applications of the joker's
+        JokerResult on top of the baseline one (see
+        ``ScoreAccumulator._fire_jokers``; ``tier_extras = (0, 0, 1, 1, 2)``):
+
+        0 (degraded, value 0–2) — baseline only (no bonus, no penalty)
+        1 (base,     value 3–4) — baseline only
+        2 (boost,    value 5–6) — +1 apply  (≈ ×2 effect)
+        3 (strong,   value 7–8) — +1 apply  (≈ ×2 effect)
+        4 (elite,    value 9–10) — +2 applies (≈ ×3 effect)
 
         Used by partner_jokers/* to scale their JokerResult payloads. The
         legacy `partner_jokers_double` flag (value≥7) still exists for backward
-        compatibility but tier_for is the new path.
+        compatibility but tier is the new path.
         """
         if self.value <= 2:
             return 0