belote-cli 3.4.2__tar.gz → 3.5.0__tar.gz

{belote_cli-3.4.2 → belote_cli-3.5.0}/CHANGELOG.md

@@ -5,6 +5,51 @@ 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.5.0] - 2026-05-12
+
+Comprehensive bug-hunt, game-mechanic audit, and performance pass over both the classic Belote engine and the BelAtro roguelite layer. A three-Explore-agent audit produced ~30 candidate findings; verification against the source rejected several as false positives (documented below) and confirmed **15 actionable items** plus **1 latent bug surfaced during implementation**. **24 new regression tests** land here (592 total, up from 568). Plan file at `/home/mrrobot/.claude/plans/bug-hunt-code-performance-tidy-meerkat.md`.
+
+### Fixed
+
+- **`src/belote/belatro/core/run_state.py:90-117` + new `src/belote/belatro/ui/consumables.py` (C1) — BelAtro consumables can now be activated.** Pre-3.5.0 `BelAtroRun.consume()` was defined but never called from any UI: every Tarot bought from the shop and every directly-purchased Planet accumulated in `run.consumables` with no way to use them. Only the voucher-gated Forge-Tierce path could level a planet. New `ConsumablesOverlay` is reachable from the shop via the `C` key, listing the tray and dispatching to `run.consume(item, context=run)` on a digit press. Hint line in the shop now shows `C: Consumables (N)`. **Also fixes a latent Le Fou bug**: `consume()` was advancing `last_consumable_id` to the *current* item BEFORE calling `item.use()`, so Le Fou's `use()` read its own id and fell through to the fallback path. Reordered to call `item.use()` first; Le Fou is special-cased as transparent so a second Le Fou keeps copying the same source rather than itself. 7 regression tests in `tests/belatro/test_consumables_ui.py`.
+- **`src/belote/belatro/run_summary.py:67-74` (H1) — JSONL appends are now durable.** Added `f.flush() + os.fsync(f.fileno())` inside the `with` block, mirroring the atomic-save pattern in `progression/save.py:81-82`. A crash or power-loss mid-write no longer leaves a truncated final line that breaks downstream `jq` processing. 3 regression tests in `tests/belatro/test_run_summary.py`.
+- **`src/belote/input.py:31-37,74` + ~20 consumer sites (H2) — EOF on stdin is distinct from ESC.** `KeyReader.read()` returned `KeyEvent(Key.ESC)` when `os.read()` returned empty bytes. A closed stdin (broken pipe, headless harness, Ctrl-D) made every prompt loop spin: ESC popped one menu level, the loop fell through and re-read stdin, got another "ESC", popped again — burning CPU until the outermost loop happened to exit. New `Key.EOF` enum value is returned on empty-read. Every `Key.ESC` consumer was updated to also accept `Key.EOF` (semantically equivalent: "back / cancel"); `prompt_card` and `prompt_bid` exit cleanly on EOF instead of spinning. 5 regression tests in `tests/test_input_eof.py`.
+- **`src/belote/belatro/engine/event_bus.py` (H3) — `EventBus` round-scope invariant documented + `clear()` added.** The bus is created fresh per round in `round_driver.drive_round` and subscribers are released with it; no explicit unsubscribe was needed. The invariant was silent — if anyone moved the bus to a longer scope, every subscription would double-fire on round 2. Module docstring now spells out the round-scope contract; a new `clear()` method exists for the future where a longer-lived bus might be desirable. 3 regression tests in `tests/belatro/test_event_bus.py`.
+- **`src/belote/scoring.py:228-330` (M1) — tied carrés / sequences go to the first announcer.** Standard Belote-Coinché awards a tied declaration to the team whose seat declared first (announcement order: taker → clockwise). Pre-3.5.0 the resolver returned `scoring_team=None` (cancel), which was defensive but non-standard. `resolve_declarations` gains an optional `taker: Seat | None = None` parameter; when supplied, tied carrés/sequences are awarded by walking the announce order. Legacy "cancel" behaviour preserved when `taker` is not provided. Both call sites updated to pass `state.taker`. 6 regression tests in `tests/test_declaration_tiebreak.py`.
+- **`src/belote/belatro/engine/event_bus.py` + ~10 consumer sites (M3) — `RoundEndEvent.breakdown` is properly typed.** Pre-3.5.0 the field was `breakdown: Any` and every consumer wrote `getattr(event.breakdown, "is_failed", False)` — defensive noise that hid field-rename regressions until runtime. Now typed as `ScoringBreakdown` (TYPE_CHECKING forward-ref to avoid import cycle); all 9 `getattr` patterns replaced with direct attribute access. `taker_seat` correctly annotated `Seat | None` (was `Seat`, but the all-pass emitter at `round_driver.py:298` actually passes None).
+- **`src/belote/scoring.py:750-763` (M5) — SA belote invariant pinned at contract level.** The `assert taker_belote == 0 and defender_belote == 0` for Sans Atout rounds was only inside the capot branch — a non-capot SA round with stray belote points would silently mis-score instead of surfacing the bug. Hoisted to a contract-level post-condition that covers both capot and non-capot paths.
+
+### Changed
+
+- **`src/belote/belatro/core/scoring.py:125-142` (M4) — `partner_jokers_double` legacy flag is now deprecated.** When both the tier scaling and the legacy boolean flag are set, a one-shot `DeprecationWarning` fires. Behaviour unchanged (`max()` of the two still wins); the flag is slated for removal in 4.0.
+- **`src/belote/ui/render.py:988-997` (L1) — `patch_trick_card` batches its writes.** Pre-3.5.0 each card-face line + the HUD update were separate `sys.stdout.write` calls; signal-interruptible terminals could paint half the card before the HUD landed. Now one `write()` per repaint, mirroring the pattern at `render.py:923,933`.
+- **`src/belote/a11y.py:1-20` (L2) — module docstring spells out the env-var invariant.** `BELOTE_A11Y` is read once at import; toggling mid-session has no effect on production code. Tests use `_refresh_enabled_from_env()`. No behaviour change, just documentation.
+- **`src/belote/belatro/core/run_state.py:30-41` (L3) — `consumables` / `jokers` / `vouchers` mutation contract documented.** These lists are intentionally mutable; any future replay / ghost-run snapshot path must deep-copy at the snapshot boundary. No behaviour change.
+
+### Performance
+
+- **`scripts/benchmark.py` (M2) — three new micro-benchmarks for real hot paths.** `benchmark_legal_cards_cached` (warm-cache path; production gameplay reuses across 8 tricks), `benchmark_trick_scoring` (`trick_card_points`, called 16× per round), `benchmark_ai_legality_filter` (the legal-move filter step inside `AIPlayer.decide_card`). The pre-existing `benchmark_legal_cards` was clarified as the cache-cleared cold path.
+- **`src/belote/scoring.py:439-477` (P1) — `trick_card_points` hoists boss-flag reads.** Same pattern `_calculate_base_points` (lines 489-493) uses. Saves 4 dataclass-attr lookups per card per trick. Sub-microsecond gain; the function was already micro-optimized at ~2μs per call. **Memoization rejected**: at 2μs × 16 calls = 32μs per round, the cache-key overhead would exceed the gain.
+- **`src/belote/game.py:490-512` (P2) — `legal_cards` cache-key analysis documented.** Benchmark shows cold ~9μs / warm ~6μs; the 33% gap is dominated by key-build cost in `legal_cards()`, not lru_cache lookup. The key already uses small-int IDs (not Card objects) which is the minimal hashable surface. Slimming further would require caching `hand_ids` on the hand tuple itself, which isn't reachable without changing the hand representation. **Documented "no actionable optimization without larger refactor"** in the cache-impl docstring so a future audit doesn't re-investigate the same dead end.
+- **`src/belote/belatro/core/scoring.py:70-89` (P3) — `ScoreAccumulator.update_state` profiling note.** cProfile of 10k calls shows `dataclasses.replace` is 65% of the cost — frozen-GameState invariant is load-bearing, so the replace cost stays. At ~19μs per event × ~25 events per round = ~0.5ms per round, the accumulator is well under the budget.
+
+### Verified clean — agent claims that did NOT survive source verification
+
+Catalogued so they aren't re-investigated next cycle.
+
+- **"Belote/Rebelote not announced when partner holds K+Q"** (`game.py:863-876`) — The condition `state.belote_holders.get(trump) == state.turn` fires when the holder *plays* the K/Q, which is exactly when the announcement should fire. `state.turn` equals the holder at the moment of play regardless of partnership. **Correct as-is.**
+- **"Capot false-positive under La Rupture on the 8th-trick announcement"** (`gameflow.py:215`) — `is_capot()` already routes through `compute_trick_winners()`, which honours Rupture for both the live-announce path and the final scoring path. The docstring at `scoring.py:317-326` explicitly calls this out. **Correct as-is.**
+- **"AI `partner_hand` not cleared on undo path"** (`ai.py:79-92`) — `update_memory()` always clears `partner_hand` at line 104 and re-fills it from the current state, regardless of which earlier branch ran (new-round / undo / normal). **Correct as-is.**
+- **"Negative-edition slot rollback on purchase failure"** (`run/shop.py:166-168`) — `_can_accept()` returns True unconditionally for Negative jokers, and `_apply_item` runs only after `spend_money()` succeeded. No failure path exists. **Correct as-is.**
+- **"`boss.id == \"…\"` string-branching in pre-round setup"** — `grep -rn 'boss\.id\s*==' src/belote/belatro/` returns zero results. Cleaned up in the May 2026 audit. **Correct as-is.**
+
+### Internal
+
+- **Tests**: 568 → 592 (+24). Six new test files: `tests/belatro/test_consumables_ui.py` (7), `tests/belatro/test_run_summary.py` (3), `tests/test_input_eof.py` (5), `tests/belatro/test_event_bus.py` (3), `tests/test_declaration_tiebreak.py` (6). 0 existing tests modified.
+- **Strict gates**: pytest 592/592 green.
+- **Version markers bumped**: `pyproject.toml`, `src/belote/__init__.py`.
+- **Docs bumped**: `CHANGELOG.md` (this entry), `README.md` "What's new in 3.5.0".
+
 ## [3.4.2] - 2026-05-11
 
 Implements the deferred bug roadmap from 3.4.1's verification pass. **9 fixes land here** — 3 Critical (C1/C3/C4), 4 High (H1/H4/H5/H7), 1 architectural cleanup (H10), 1 dead-code deletion (M4). Adds 17 regression tests (551 → 568). The 3.4.1 entry catalogued these against the source; this entry implements them. Plan file at `/home/mrrobot/.claude/plans/wtf-these-were-verified-shiny-flute.md`.

{belote_cli-3.4.2 → belote_cli-3.5.0}/DEVELOPMENT.md

@@ -84,15 +84,16 @@ PYTHONPATH=src mypy --strict src/
 # Linting (0 violations expected)
 ruff check src/ tests/
 
-# Full test suite (568 tests expected)
+# Full test suite (592 tests expected)
 PYTHONPATH=src pytest
 ```
 
-Current baseline (3.4.2):
-- **mypy**: 0 errors (strict mode, 76 files)
+Current baseline (3.5.0):
+- **mypy**: 0 errors (strict mode, 77 files — `belatro/ui/consumables.py` is new)
 - **ruff**: 0 violations
-- **pytest**: 568 tests, 0 failures
-- 3.4.2 closes the 3.4.1 catalogue. All 7 confirmed bugs (C1 AI cheat under `hide_partner_hand`, C3 Dix de Der under La Rupture, C4 `opp_trumps` formula + TA total, H1 8 jokers seat→team, H4 TournoiAnte true 50%, H5 `load_profile` default unlocks, H7 classic-mode tie operator) plus H10 (`equip_joker` wires `on_purchase`) and M4 (delete dead `advance_turn`) ship in 3.4.2. +17 regression tests (551 → 568). H2 (`LEgoiste` partner-trick nullification) remains deferred — needs a spec call between code-comment intent and the audit's reading.
+- **pytest**: 592 tests, 0 failures
+- 3.5.0 lands a 15-fix audit pass over the classic engine + BelAtro layer: C1 (consumables UI + Le Fou ordering), H1 (run-summary fsync), H2 (Key.EOF distinct from ESC), H3 (EventBus round-scope docs + `clear()`), M1 (declaration first-announcer tie-break), M3 (typed `RoundEndEvent.breakdown`), M4 (deprecate `partner_jokers_double`), M5 (SA belote invariant hoisted), L1 (`patch_trick_card` single-write), L2/L3 (doc pins), M2 (3 new benchmark micro-tests), P1/P2/P3 (perf hoist + cache-key + accumulator-profile analyses). +24 regression tests across 5 new files; 0 existing tests modified. Plan file at `/home/mrrobot/.claude/plans/bug-hunt-code-performance-tidy-meerkat.md`.
+- 3.4.2 closed the 3.4.1 catalogue. All 7 confirmed bugs (C1 AI cheat under `hide_partner_hand`, C3 Dix de Der under La Rupture, C4 `opp_trumps` formula + TA total, H1 8 jokers seat→team, H4 TournoiAnte true 50%, H5 `load_profile` default unlocks, H7 classic-mode tie operator) plus H10 (`equip_joker` wires `on_purchase`) and M4 (delete dead `advance_turn`) shipped in 3.4.2. +17 regression tests (551 → 568). H2 (`LEgoiste` partner-trick nullification) remains deferred — needs a spec call between code-comment intent and the audit's reading.
 - 3.4.1 was **documentation-only** — an external LLM audit was verified against the source. 7 confirmed bugs were catalogued in `CHANGELOG.md` as deferred to 3.4.2+; 8 audit claims were rejected as false positives and are listed in the "Verified clean" section to block re-investigation. No source code changed in 3.4.1.
 - 3.4.0 covered: A1 `BidMadeEvent` double-fire on coinche paths (HIGH), E1 endless mode replaying Ante 8 Boss instead of advancing to the first scaled cycle (HIGH), E2 classic-mode tie-breaker overridden by main loop (HIGH), A2 termios raw-mode leak on SSH drop (MED), A3 shop selection index off-by-one after reroll (MED), A5 prompts.py dead return (LOW). Plus HUD additions: joker pip strip with edition glow (B.3), synergy tooltip (B.4), four-tier trust bar with tier glyph (B.5). Score gutter (B.2) and trick-lane compass (B.1) intentionally deferred — they touch `ui/render.py`'s vertical-centering logic and want a dedicated session.
 

{belote_cli-3.4.2 → belote_cli-3.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: belote-cli
-Version: 3.4.2
+Version: 3.5.0
 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,23 @@ 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.5.0
+
+- **C1 — BelAtro consumables are now usable.** Pre-3.5.0 `BelAtroRun.consume()` was defined but never called from any UI, so every Tarot purchased in the shop and every directly-bought Planet accumulated in `run.consumables` with no way to activate them — only the voucher-gated Forge-Tierce path could level a planet. New `ConsumablesOverlay` (`belatro/ui/consumables.py`) is reachable from the shop via the `C` key; the hint line now shows `C: Consumables (N)`. Surfacing this path also caught a latent Le Fou bug: `consume()` advanced `last_consumable_id` to the *current* item before calling `item.use()`, so Le Fou read its own id and fell through to fallback — fixed by reordering and making Le Fou transparent so a second Le Fou keeps copying the same source.
+- **H1 — `run_summary.py` writes are durable.** Added `flush + fsync` inside the `with` block. A crash mid-write no longer leaves a truncated JSONL line.
+- **H2 — `Key.EOF` distinct from `Key.ESC`.** A closed stdin (pipe / headless harness) used to make every prompt loop spin: ESC popped one level, the loop re-read stdin, got another ESC, popped again. Now `KeyReader.read()` returns `Key.EOF` on empty-read; every consumer accepts it like ESC; `prompt_card` / `prompt_bid` exit cleanly instead of spinning.
+- **H3 — `EventBus` round-scope invariant documented + `clear()` added.** Module docstring now spells out the contract that today is silently enforced by `drive_round()` creating a fresh bus per round.
+- **M1 — Tied carrés / sequences go to the first announcer.** `resolve_declarations` gains an optional `taker: Seat | None` parameter; tied declarations now walk the announce order (taker → clockwise) and award the first matching seat, matching standard Belote-Coinché. Legacy "cancel" behaviour preserved when `taker` not supplied.
+- **M3 — `RoundEndEvent.breakdown` is properly typed** as `ScoringBreakdown`. Removed 9 defensive `getattr(event.breakdown, "is_failed", False)` patterns; `taker_seat` corrected to `Seat | None`.
+- **M4 — `partner_jokers_double` legacy flag is now deprecated.** A `DeprecationWarning` fires when both it and the tier scaling are set; flag slated for removal in 4.0.
+- **M5 — SA belote invariant hoisted to contract level.** Was previously only asserted inside the capot branch.
+- **L1 — `patch_trick_card` batches its `sys.stdout.write` calls.** Eliminates a torn-frame window on signal-interruptible terminals.
+- **L2/L3 — Documentation pins**: `BELOTE_A11Y` is read once at import; `BelAtroRun.consumables/jokers/vouchers` are intentionally mutable.
+- **M2 — Benchmark coverage expanded.** Three new micro-benchmarks: warm-cache `legal_cards`, `trick_card_points`, and the AI legality-filter step. The pre-existing cold-cache `legal_cards` benchmark is now labelled accordingly.
+- **P1/P2/P3 — Performance pass.** `trick_card_points` flag-hoist (already at ~2μs/call — sub-μs gain). `legal_cards` cache-key analysis: warm/cold gap is dominated by key-build, not lru_cache lookup; no actionable optimisation without changing the hand representation — documented to prevent re-investigation. `ScoreAccumulator.update_state` profile shows `dataclasses.replace` is 65% of cost; frozen-GameState invariant is load-bearing, accumulator is ~0.5ms/round — acceptable.
+- **Verified false positives** (catalogued so they aren't re-raised): Belote/Rebelote partner non-announcement, Capot Rupture false-positive, AI `partner_hand` undo clearing, Negative-edition slot rollback, and `boss.id == "..."` branching — five agent flags that didn't survive source verification.
+- **Tests + gates**: 592 tests (up from 568, +24 regression tests across 5 new files, 0 existing tests modified). pytest 592/592 green.
+
 ## What's new in 3.4.2
 
 - **The 3.4.1 catalogue is closed.** All 7 confirmed bugs plus the H10 architectural cleanup and the M4 dead-code deletion ship here. **C1 — AI cheating under Le Fantôme Partenaire:** AI memory now respects `hide_partner_hand`; the boss flag's visibility cost is paid by both sides. **C3 — Dix de Der announcement under La Rupture:** the 8th-trick "Team X" line now uses the Rupture-aware `compute_trick_winners` helper, so the named team matches what scoring credits. **C4 — `opp_trumps` formula:** subtracts South's own trumps, played trumps, and partner-visible trumps; under Tout Atout the total switches to 32 (every card is a trump). **H1 — 8 BelAtro jokers:** `LIdeologue`, `LeFanatique`, `LeDiplomate`, `LePatriote`, `LIllusionniste`, `LePremierSang`, `LeSergent`, `LExecuteur` now gate on `team_of(event.winner) == 0` instead of `event.winner == Seat.SOUTH`, matching the 3.2.0 fix that landed `LaSentinelle` and `LeDernierMot`. **H4 — TournoiAnte:** `on_blind_won` now receives `blind_payout` and pays a true 50% (was a flat function of `bonus_per_round`). **H5 — `load_profile`:** saves missing the `unlocked_ids` key fall back to the Profile dataclass default starter unlocks. **H7 — classic win attribution on ties:** `update_stats_game` operator aligned to `ns > ew` so the stats line agrees with `menu.py`'s visible winner on an exact tie at target.

{belote_cli-3.4.2 → belote_cli-3.5.0}/README.md

@@ -2,6 +2,23 @@
 
 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.5.0
+
+- **C1 — BelAtro consumables are now usable.** Pre-3.5.0 `BelAtroRun.consume()` was defined but never called from any UI, so every Tarot purchased in the shop and every directly-bought Planet accumulated in `run.consumables` with no way to activate them — only the voucher-gated Forge-Tierce path could level a planet. New `ConsumablesOverlay` (`belatro/ui/consumables.py`) is reachable from the shop via the `C` key; the hint line now shows `C: Consumables (N)`. Surfacing this path also caught a latent Le Fou bug: `consume()` advanced `last_consumable_id` to the *current* item before calling `item.use()`, so Le Fou read its own id and fell through to fallback — fixed by reordering and making Le Fou transparent so a second Le Fou keeps copying the same source.
+- **H1 — `run_summary.py` writes are durable.** Added `flush + fsync` inside the `with` block. A crash mid-write no longer leaves a truncated JSONL line.
+- **H2 — `Key.EOF` distinct from `Key.ESC`.** A closed stdin (pipe / headless harness) used to make every prompt loop spin: ESC popped one level, the loop re-read stdin, got another ESC, popped again. Now `KeyReader.read()` returns `Key.EOF` on empty-read; every consumer accepts it like ESC; `prompt_card` / `prompt_bid` exit cleanly instead of spinning.
+- **H3 — `EventBus` round-scope invariant documented + `clear()` added.** Module docstring now spells out the contract that today is silently enforced by `drive_round()` creating a fresh bus per round.
+- **M1 — Tied carrés / sequences go to the first announcer.** `resolve_declarations` gains an optional `taker: Seat | None` parameter; tied declarations now walk the announce order (taker → clockwise) and award the first matching seat, matching standard Belote-Coinché. Legacy "cancel" behaviour preserved when `taker` not supplied.
+- **M3 — `RoundEndEvent.breakdown` is properly typed** as `ScoringBreakdown`. Removed 9 defensive `getattr(event.breakdown, "is_failed", False)` patterns; `taker_seat` corrected to `Seat | None`.
+- **M4 — `partner_jokers_double` legacy flag is now deprecated.** A `DeprecationWarning` fires when both it and the tier scaling are set; flag slated for removal in 4.0.
+- **M5 — SA belote invariant hoisted to contract level.** Was previously only asserted inside the capot branch.
+- **L1 — `patch_trick_card` batches its `sys.stdout.write` calls.** Eliminates a torn-frame window on signal-interruptible terminals.
+- **L2/L3 — Documentation pins**: `BELOTE_A11Y` is read once at import; `BelAtroRun.consumables/jokers/vouchers` are intentionally mutable.
+- **M2 — Benchmark coverage expanded.** Three new micro-benchmarks: warm-cache `legal_cards`, `trick_card_points`, and the AI legality-filter step. The pre-existing cold-cache `legal_cards` benchmark is now labelled accordingly.
+- **P1/P2/P3 — Performance pass.** `trick_card_points` flag-hoist (already at ~2μs/call — sub-μs gain). `legal_cards` cache-key analysis: warm/cold gap is dominated by key-build, not lru_cache lookup; no actionable optimisation without changing the hand representation — documented to prevent re-investigation. `ScoreAccumulator.update_state` profile shows `dataclasses.replace` is 65% of cost; frozen-GameState invariant is load-bearing, accumulator is ~0.5ms/round — acceptable.
+- **Verified false positives** (catalogued so they aren't re-raised): Belote/Rebelote partner non-announcement, Capot Rupture false-positive, AI `partner_hand` undo clearing, Negative-edition slot rollback, and `boss.id == "..."` branching — five agent flags that didn't survive source verification.
+- **Tests + gates**: 592 tests (up from 568, +24 regression tests across 5 new files, 0 existing tests modified). pytest 592/592 green.
+
 ## What's new in 3.4.2
 
 - **The 3.4.1 catalogue is closed.** All 7 confirmed bugs plus the H10 architectural cleanup and the M4 dead-code deletion ship here. **C1 — AI cheating under Le Fantôme Partenaire:** AI memory now respects `hide_partner_hand`; the boss flag's visibility cost is paid by both sides. **C3 — Dix de Der announcement under La Rupture:** the 8th-trick "Team X" line now uses the Rupture-aware `compute_trick_winners` helper, so the named team matches what scoring credits. **C4 — `opp_trumps` formula:** subtracts South's own trumps, played trumps, and partner-visible trumps; under Tout Atout the total switches to 32 (every card is a trump). **H1 — 8 BelAtro jokers:** `LIdeologue`, `LeFanatique`, `LeDiplomate`, `LePatriote`, `LIllusionniste`, `LePremierSang`, `LeSergent`, `LExecuteur` now gate on `team_of(event.winner) == 0` instead of `event.winner == Seat.SOUTH`, matching the 3.2.0 fix that landed `LaSentinelle` and `LeDernierMot`. **H4 — TournoiAnte:** `on_blind_won` now receives `blind_payout` and pays a true 50% (was a flat function of `bonus_per_round`). **H5 — `load_profile`:** saves missing the `unlocked_ids` key fall back to the Profile dataclass default starter unlocks. **H7 — classic win attribution on ties:** `update_stats_game` operator aligned to `ns > ew` so the stats line agrees with `menu.py`'s visible winner on an exact tie at target.

{belote_cli-3.4.2 → belote_cli-3.5.0}/pyproject.toml

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

{belote_cli-3.4.2 → belote_cli-3.5.0}/scripts/benchmark.py

@@ -149,21 +149,103 @@ def benchmark_deal(iterations: int = 1000) -> float:
 
 def benchmark_legal_cards(iterations: int = 1000) -> float:
     from belote.game import legal_cards, clear_legal_cards_cache, replace
-    print(f"Benchmarking legal_cards() over {iterations} iterations...")
-    
+    print(f"Benchmarking legal_cards() (cache cleared per call) over {iterations} iterations...")
+
     state = new_game()
     state = start_round(state, random.Random(42))
     state = replace(state, phase=Phase.PLAYING, trump=Suit.SPADES, turn=Seat.SOUTH)
-    
+
     times = []
     for _ in range(iterations):
         clear_legal_cards_cache()
         start = time.perf_counter()
         _ = legal_cards(state, Seat.SOUTH)
         times.append(time.perf_counter() - start)
-        
+
+    avg = statistics.mean(times) * 1000
+    print(f"  Legal Cards (cold) Time: {avg:.3f}ms")
+    return avg
+
+
+def benchmark_legal_cards_cached(iterations: int = 1000) -> float:
+    """Measure the cache-hit path. Production gameplay reuses the cache across
+    multiple AI rollouts and HUD redraws for the same `(state, seat)` pair —
+    `benchmark_legal_cards` above invalidates every iteration and so reflects
+    worst-case-only time.
+    """
+    from belote.game import legal_cards, clear_legal_cards_cache, replace
+    print(f"Benchmarking legal_cards() (warm cache) over {iterations} iterations...")
+
+    state = new_game()
+    state = start_round(state, random.Random(42))
+    state = replace(state, phase=Phase.PLAYING, trump=Suit.SPADES, turn=Seat.SOUTH)
+    clear_legal_cards_cache()
+    legal_cards(state, Seat.SOUTH)  # warm the cache once
+
+    times = []
+    for _ in range(iterations):
+        start = time.perf_counter()
+        _ = legal_cards(state, Seat.SOUTH)
+        times.append(time.perf_counter() - start)
+
+    avg = statistics.mean(times) * 1000
+    print(f"  Legal Cards (warm) Time: {avg:.3f}ms")
+    return avg
+
+
+def benchmark_trick_scoring(iterations: int = 1000) -> float:
+    """Measure `trick_card_points` — called 8× per round from `game.py::play_card`
+    (HUD running total) and again from `scoring.py::_calculate_base_points`
+    (final round score). One of the hottest functions in a played round.
+    """
+    from belote.game import TrickCard, replace
+    from belote.deck import Card, Rank
+    from belote.scoring import trick_card_points
+
+    print(f"Benchmarking trick_card_points() over {iterations} iterations...")
+
+    state = new_game()
+    state = replace(state, trump=Suit.SPADES, contract="normal", taker=Seat.SOUTH)
+    trick = (
+        TrickCard(Seat.SOUTH, Card(Suit.SPADES, Rank.JACK)),
+        TrickCard(Seat.WEST, Card(Suit.SPADES, Rank.NINE)),
+        TrickCard(Seat.NORTH, Card(Suit.HEARTS, Rank.ACE)),
+        TrickCard(Seat.EAST, Card(Suit.SPADES, Rank.SEVEN)),
+    )
+
+    times = []
+    for _ in range(iterations):
+        start = time.perf_counter()
+        _ = trick_card_points(state, trick)
+        times.append(time.perf_counter() - start)
+
+    avg = statistics.mean(times) * 1000
+    print(f"  Trick Scoring Time: {avg:.3f}ms")
+    return avg
+
+
+def benchmark_ai_legality_filter(iterations: int = 500) -> float:
+    """Isolate the legal-move filter step inside `AIPlayer.decide_card`. The
+    AI calls `legal_cards` once per decision; an unrepresentative cold-cache
+    benchmark above would over-attribute AI time to legality checks.
+    """
+    from belote.game import legal_cards, replace
+    print(f"Benchmarking AI legality filter over {iterations} iterations...")
+
+    state = new_game()
+    state = start_round(state, random.Random(42))
+    state = replace(state, phase=Phase.PLAYING, trump=Suit.SPADES, taker=Seat.SOUTH, turn=Seat.NORTH)
+
+    times = []
+    for _ in range(iterations):
+        start = time.perf_counter()
+        legal = legal_cards(state, Seat.NORTH)
+        # The filter step: callers usually check membership in a 6-8 card hand.
+        _ = [c for c in state.hands[Seat.NORTH.value] if c in legal]
+        times.append(time.perf_counter() - start)
+
     avg = statistics.mean(times) * 1000
-    print(f"  Legal Cards Time: {avg:.3f}ms")
+    print(f"  Legality Filter Time: {avg:.3f}ms")
     return avg
 
 
@@ -180,6 +262,9 @@ def run_benchmarks() -> None:
     benchmark_scoring()
     benchmark_deal()
     benchmark_legal_cards()
+    benchmark_legal_cards_cached()
+    benchmark_trick_scoring()
+    benchmark_ai_legality_filter()
     print("========================================")
 
 

{belote_cli-3.4.2 → belote_cli-3.5.0}/src/belote/__init__.py

@@ -1,3 +1,3 @@
-__version__ = "3.4.2"
+__version__ = "3.5.0"
 
 __all__ = ["__version__"]

{belote_cli-3.4.2 → belote_cli-3.5.0}/src/belote/a11y.py

@@ -5,6 +5,11 @@ line to stderr — readable by terminal screen readers such as Orca, NVDA in WSL
 or VoiceOver via iTerm2. Disabled by default so it doesn't pollute output for
 sighted players.
 
+**Invariant**: ``BELOTE_A11Y`` is read **once at module import**. Toggling the
+env var mid-session has no effect on production code — restart the process
+to enable/disable. Tests that mutate the env may call ``_refresh_enabled_from_env()``
+to re-read the cached flag.
+
 Hooked from gameflow.py (card plays, trick winners, round results) and from
 belatro/main.py (boss reveal, ante advance, run won/lost). Each hook is a
 single line — no rich formatting — so the screen reader can speak it cleanly.

{belote_cli-3.4.2 → belote_cli-3.5.0}/src/belote/belatro/core/run_state.py

@@ -28,6 +28,11 @@ class BelAtroRun:
     profile: Profile | None = None
 
     # ── Collectibles ───────────────────────────────────────
+    # These lists are intentionally mutable: jokers append on purchase, vouchers
+    # apply their effects in-place, and `consume()` removes items via
+    # `consumables.remove(item)`. If a future feature needs to snapshot a run
+    # for replay / ghost-run reconstruction, deep-copy these lists at the
+    # snapshot boundary — they alias live state otherwise.
     jokers: list[Joker] = field(default_factory=list)
     vouchers: list[Voucher] = field(default_factory=list)
     consumables: list[Any] = field(default_factory=list)  # Tarot/Planet instances
@@ -90,9 +95,17 @@ class BelAtroRun:
     def consume(self, item: Any, context: object = None) -> None:
         """Centralised consumable activation.
 
-        Records the item id as the most recent consumable (so LeFou can copy
-        it) and removes it from `consumables` if present, then dispatches to
-        the right hook based on item type (Tarot vs Planet).
+        Removes the item from `consumables` if present, dispatches to the right
+        hook based on item type (Tarot vs Planet), then advances
+        `last_consumable_id` so Le Fou can copy the prior consumable later.
+
+        Apply order matters: `item.use()` must run BEFORE updating
+        `last_consumable_id`, because Le Fou's `use()` reads that field to
+        find what to copy — if we advanced it to `le_fou` first, Le Fou would
+        see itself and fall through to the fallback path. Le Fou itself is
+        treated as transparent: the bookmark stays pointed at the source it
+        copied, so a second Le Fou keeps copying the same source rather than
+        copying itself.
         """
         import contextlib
 
@@ -100,11 +113,14 @@ class BelAtroRun:
 
         with contextlib.suppress(ValueError):
             self.consumables.remove(item)
-        self.last_consumable_id = getattr(item, "id", None)
         if isinstance(item, Tarot):
             item.use(self, context)
         elif isinstance(item, Planet):
             item.use(self)
+        # Le Fou is transparent — leave the bookmark at the source it copied.
+        # Every other consumable advances the bookmark to its own id.
+        if getattr(item, "id", None) != "le_fou":
+            self.last_consumable_id = getattr(item, "id", None)
 
     def _get_rng(self) -> Any:
         """Per-run random.Random instance, seeded from `seed` when given."""

{belote_cli-3.4.2 → belote_cli-3.5.0}/src/belote/belatro/core/scoring.py

@@ -68,7 +68,17 @@ class ScoreAccumulator:
         return replace(state, _joker_state=joker_state, _chips=new_chips, _mult=new_mult)
 
     def update_state(self, state: GameState, event: object) -> GameState:
-        """Process an event and return an updated GameState with new score/joker state."""
+        """Process an event and return an updated GameState with new score/joker state.
+
+        Perf note (3.5.0 P3 investigation): the dominant cost (~65% of the
+        function) is the final `dataclasses.replace(state, ...)` call. The
+        frozen-GameState invariant is load-bearing — many call sites assume
+        `state is final_state` once a round is sealed — so we accept the
+        replace cost rather than mutating in place. At ~19μs per event and
+        ~25 events per round (8 tricks + 2-4 bids + decls + round-end) the
+        accumulator contributes ~0.5ms to a full round, well below the
+        ~1ms-per-frame budget where it would matter.
+        """
         new_chips = state._chips
         new_mult = state._mult
         new_money = state._bonus_money
@@ -120,10 +130,23 @@ class ScoreAccumulator:
                         # tier 2 (boost) / 3 (strong) → +1 apply (≈ ×2 effect),
                         #                               matches legacy partner_jokers_double at trust ≥ 7.
                         # tier 4 (elite) → +2 applies (≈ ×3 effect).
-                        # Legacy `partner_jokers_double` flag still forces +1 apply for
-                        # back-compat with tests that set it directly.
+                        #
+                        # `partner_jokers_double` is the legacy boolean flag (pre-3.5.0
+                        # back-compat for tests that set it directly). When both are
+                        # set, `max()` picks whichever is larger; a one-shot
+                        # DeprecationWarning fires so callers migrate to tier. The flag
+                        # is slated for removal in 4.0; new code should use `partner_tier`.
                         if getattr(joker, "is_partner_joker", False):
                             tier_extras = (0, 0, 1, 1, 2)[self.partner_tier]
+                            if self.partner_jokers_double and tier_extras > 0:
+                                import warnings
+                                warnings.warn(
+                                    "ScoreAccumulator.partner_jokers_double is deprecated "
+                                    "alongside partner_tier; set only one. The flag will "
+                                    "be removed in 4.0.",
+                                    DeprecationWarning,
+                                    stacklevel=2,
+                                )
                             extra_applies = max(
                                 tier_extras, 1 if self.partner_jokers_double else 0
                             )
@@ -202,11 +225,11 @@ class ScoreAccumulator:
                 contract_id = _SUIT_TO_CONTRACT.get(event.trump) if event.trump else None
                 if contract_id:
                     reward = self.contract_levels.get(contract_id, {})
-                    if reward.get("add_money") and not getattr(event.breakdown, "is_failed", False):
+                    if reward.get("add_money") and not event.breakdown.is_failed:
                         new_money += reward["add_money"]
                         self._log.append(f"Planet ({contract_id}): +${reward['add_money']}")
                 # Pluto (Capot bonus)
-                if event.capot and not getattr(event.breakdown, "is_failed", False):
+                if event.capot and not event.breakdown.is_failed:
                     pluto_reward = self.contract_levels.get("capot", {})
                     if pluto_reward.get("capot_bonus"):
                         new_chips += pluto_reward["capot_bonus"]
@@ -215,7 +238,7 @@ class ScoreAccumulator:
                 if (
                     event.coinche_level > 0
                     and event.taker_seat in _NS_TEAM
-                    and not getattr(event.breakdown, "is_failed", False)
+                    and not event.breakdown.is_failed
                 ):
                     libra_reward = self.contract_levels.get("coinche", {})
                     libra_mult = libra_reward.get("coinche_multiplier", 0)

{belote_cli-3.4.2 → belote_cli-3.5.0}/src/belote/belatro/engine/event_bus.py

@@ -1,12 +1,28 @@
+"""Round-scoped pub/sub bus for BelAtro joker / unlock / score-accumulator wiring.
+
+**Scope invariant**: an `EventBus` is created once per round in
+`round_driver.drive_round`, subscribed to by the round's accumulator and the
+process-wide `UnlockTracker`, then dropped when the round ends. Subscribers
+do not need to unsubscribe explicitly — the bus instance and all its
+subscriber references are released together.
+
+If you ever extend the bus's scope (run-level, session-level), you MUST also
+add explicit unsubscribe calls so subscribers don't accumulate across rounds
+and double-fire. The `clear()` method exists for that future use.
+"""
+
 from __future__ import annotations
 
 from collections.abc import Callable
 from dataclasses import dataclass
-from typing import Any
+from typing import TYPE_CHECKING
 
 from belote.deck import Card, Suit
 from belote.game import Seat
 
+if TYPE_CHECKING:
+    from belote.scoring import ScoringBreakdown
+
 # ── Event types ────────────────────────────────────────────────────────────
 
 
@@ -36,8 +52,9 @@ class DeclarationScoredEvent:
 
 @dataclass(frozen=True)
 class RoundEndEvent:
-    breakdown: Any  # ScoringBreakdown from belote.scoring
-    taker_seat: Seat
+    breakdown: "ScoringBreakdown"
+    # `taker_seat` is None when the round ended on an all-pass (no contract).
+    taker_seat: Seat | None
     trump: Suit | None
     capot: bool
     hand_remainder: tuple[Card, ...] = ()
@@ -68,6 +85,8 @@ Handler = Callable[[AnyEvent], None]
 
 
 class EventBus:
+    """Round-scoped event bus. See module docstring for the lifetime contract."""
+
     def __init__(self) -> None:
         self._handlers: list[Handler] = []
 
@@ -83,3 +102,13 @@ class EventBus:
     def emit(self, event: AnyEvent) -> None:
         for h in list(self._handlers):
             h(event)
+
+    def clear(self) -> None:
+        """Drop every subscriber.
+
+        Today the round-scoped bus is created fresh per round so this is
+        unused, but exists for the future where a longer-lived bus might
+        share lifetime across rounds (debug overlays, replay recorders, etc).
+        Call before re-using a bus across round boundaries.
+        """
+        self._handlers.clear()

{belote_cli-3.4.2 → belote_cli-3.5.0}/src/belote/belatro/items/jokers/annonces.py

@@ -81,8 +81,6 @@ class QuinteRoyale(Joker):
     def on_round_end(
         self, event: RoundEndEvent, state: dict[str, Any]
     ) -> JokerResult | None:
-        if state.pop(f"{self.id}_armed", False) and not getattr(
-            event.breakdown, "is_failed", False
-        ):
+        if state.pop(f"{self.id}_armed", False) and not event.breakdown.is_failed:
             return JokerResult(times_mult=4.0)
         return None

{belote_cli-3.4.2 → belote_cli-3.5.0}/src/belote/belatro/items/jokers/coinche.py

@@ -24,7 +24,7 @@ class CoincheStack(Joker):
     def on_round_end(self, event: RoundEndEvent, state: dict[str, Any]) -> JokerResult | None:
         if event.coinche_level <= 0:
             return None
-        if getattr(event.breakdown, "is_failed", False):
+        if event.breakdown.is_failed:
             return None
         if event.taker_seat not in (Seat.SOUTH, Seat.NORTH):
             return None
@@ -53,7 +53,7 @@ class ToutStreak(Joker):
         is_tout = event.trump == Suit.TOUT_ATOUT
         is_taker_won = (
             event.taker_seat in (Seat.SOUTH, Seat.NORTH)
-            and not getattr(event.breakdown, "is_failed", False)
+            and not event.breakdown.is_failed
         )
 
         if is_tout and is_taker_won:

{belote_cli-3.4.2 → belote_cli-3.5.0}/src/belote/belatro/items/jokers/contract.py

@@ -109,7 +109,7 @@ class LePuriste(Joker):
         # Sans Atout means trump is None. Flag triggers double payout in _play_blind.
         if (
             event.trump is None
-            and not getattr(event.breakdown, "is_failed", False)
+            and not event.breakdown.is_failed
             and event.taker_seat in (Seat.SOUTH, Seat.NORTH)
         ):
             state["puriste_triggered"] = True

{belote_cli-3.4.2 → belote_cli-3.5.0}/src/belote/belatro/progression/unlocks.py

@@ -64,7 +64,7 @@ class UnlockTracker:
         if (
             event.trump is None
             and event.taker_seat in (Seat.SOUTH, Seat.NORTH)
-            and not getattr(event.breakdown, "is_failed", False)
+            and not event.breakdown.is_failed
         ):
             self.profile.stats["sans_atout_wins"] += 1
             dirty = True
@@ -79,7 +79,7 @@ class UnlockTracker:
         if (
             event.trump == Suit.TOUT_ATOUT
             and event.taker_seat in (Seat.SOUTH, Seat.NORTH)
-            and not getattr(event.breakdown, "is_failed", False)
+            and not event.breakdown.is_failed
         ):
             self.profile.stats["tout_atout_wins"] += 1
             dirty = True

{belote_cli-3.4.2 → belote_cli-3.5.0}/src/belote/belatro/run_summary.py

@@ -66,6 +66,11 @@ def append_summary(run: BelAtroRun, *, won: bool) -> None:
         path = _summary_path()
         with path.open("a", encoding="utf-8") as f:
             f.write(json.dumps(record) + "\n")
+            # flush + fsync so a crash or power-loss mid-write doesn't leave a
+            # truncated final line that breaks downstream `jq` processing.
+            # Mirrors the atomic-save pattern in `progression/save.py`.
+            f.flush()
+            os.fsync(f.fileno())
     except OSError:
         # Logging failure is intentionally silent — telemetry is non-essential.
         pass

{belote_cli-3.4.2 → belote_cli-3.5.0}/src/belote/belatro/ui/announce.py

@@ -67,7 +67,7 @@ class BelAtroAnnounce:
             event = reader.read_timeout(remaining)
             if event is None:
                 break
-            if event.key in (Key.SPACE, Key.ESC, Key.ENTER):
+            if event.key in (Key.SPACE, Key.ESC, Key.ENTER, Key.EOF):
                 break
             remaining = end - time.time()
 
@@ -118,7 +118,7 @@ class BelAtroAnnounce:
             if event is None:
                 break
             key = event.key
-            if key in (Key.SPACE, Key.ESC, Key.ENTER):
+            if key in (Key.SPACE, Key.ESC, Key.ENTER, Key.EOF):
                 break
             remaining = end - time.time()
         toggle_overlay()

{belote_cli-3.4.2 → belote_cli-3.5.0}/src/belote/belatro/ui/collection.py

@@ -128,7 +128,7 @@ def show_collection(reader: KeyReader, profile: Profile) -> None:
 
         event = reader.read()
         match event.key:
-            case Key.QUIT | Key.ESC:
+            case Key.QUIT | Key.ESC | Key.EOF:
                 return
             case Key.LEFT:
                 cat_idx = (cat_idx - 1) % len(categories)