scopone/docs/FINDINGS.md

Findings

Last Updated: 2026-04-09T20:59:51.000Z

Summary

Initializer refresh for SCOPONE-0010. The cache was invalid because docs/FINDINGS.md no longer matched its recorded hash, and the architecture document no longer matched the live source layout after settings, preferences, and benchmark changes. The observations below reflect the current repository state.

Codebase Observations

• Primary gameplay code currently lives in 15 TypeScript source files under src/; the Android wrapper adds 3 Java files.
• The project is structurally split between framework-free gameplay modules in src/game/ and Phaser scene code in src/scenes/.
• src/scenes/GameScene.ts and src/game/ai.ts remain the two largest concentrations of application logic.
• A dedicated audio preference path now exists: src/game/preferences.ts, src/scenes/MenuScene.ts, and src/scenes/SettingsScene.ts.
• main.ts still contains a local SettingsScene placeholder class, while MenuScene.ensureSettingsSceneAvailable() swaps in the concrete imported scene before navigation.
• The AI transport layer is a stable three-file path: ai-worker-protocol.ts, ai-worker-client.ts, and ai.worker.ts.
• The AI exposes three difficulty levels: beginner, advanced, and master.
• advanced and master both use CardTracker to reason about unseen cards without directly reading hidden hands.
• The base master search profile is 4300 ms / 8 samples / depth 5 / batch 2, with tighter endgame branches down to 3200 ms / 4 samples / exact remaining depth / batch 1 when 4 cards remain.
• GameScene consumes AI progress callbacks to update an on-screen think bar while a worker request is running.
• GameScene now enforces AI_MIN_THINK_MS = 1000 and MOVE_OUTCOME_STATUS_MS = 2000 through timer-backed scene logic.
• AIWorkerClient fails over pending work to in-thread chooseMove() if worker creation, posting, or deserialization fails.
• The AI benchmark harness is now in source under src/game/ai-benchmark.ts and src/game/ai-benchmark-fixtures.ts, and package.json exposes it as npm run benchmark:ai-quality.
• The current benchmark contract is iteration 5: 13 fixed fixtures, 6 critical concepts, and 48 self-play matches.
• The Android wrapper targets SDK 36 with minSdkVersion 24 and applies immersive mode from the native activity.
• Audio remains procedural via Web Audio; there is still no dedicated audio asset pipeline in the source tree.
• No ESLint or Prettier configuration is present.
• The only repository-wide verification command supplied is npx tsc --noEmit.

Potential Improvement Areas

• GameScene.ts still centralizes layout, turn flow, HUD updates, effects, audio, status messaging, and AI orchestration in one scene class.
• ai.ts still combines heuristic tiers, inference helpers, determinization, move ordering, and alpha-beta evaluation in one module.
• The current settings flow works, but the dual registration pattern for SettingsScene in main.ts plus dynamic replacement in MenuScene is fragile and worth simplifying later.
• Worker transport is isolated cleanly, but progress rendering and fallback behavior remain coupled to scene-level UI concerns.
• A 3.2 to 4.35 second master search window may still be noticeable on slower mobile devices even with yielding and the minimum-think pacing already in place.
• There is no dedicated automated rules test suite beyond type-checking and the AI benchmark harness.
• Formatting and style are enforced socially rather than by automated linting or formatting tools.

Current Rule / Implementation Notes

Capture behavior in engine.ts

• Direct-match capture has priority over subset-sum capture.
• When multiple direct matches exist, findCaptures() returns one single-card option per matching card.
• Subset-sum captures are considered only when no direct match exists.
• applyMove() defaults to the first legal capture if no explicit capture choice is supplied.
• Scopa is awarded only when a capture clears the table before the final play of the round.

AI implementation snapshot

• beginner uses a simpler heuristic with noise to remain beatable.
• advanced adds race awareness, anti-scopa logic, partner setup, denari pressure, and tracker-based probability estimates.
• master orders legal moves with a quick evaluator, samples hidden hands, and scores them with alpha-beta search under a dynamic deadline.
• Progress is reported through AIDecisionProgress so the scene can keep the think bar responsive.
• CardTracker now exposes same-rank residue summaries through getValueRankResidue() and getValueRankResidueSummary(), and those semantics are the live inference surface for unseen-value reasoning.

Worker execution snapshot

• GameScene creates AIWorkerClient during create() and disposes it on both shutdown and destroy.
• AIWorkerClient serializes CardTracker state through toSnapshot() instead of attempting to transfer the class instance.
• ai.worker.ts rebuilds tracker state with CardTracker.fromSnapshot() before calling chooseMove().
• Progress, result, and serialized error payloads all travel through ai-worker-protocol.ts.
• If worker execution becomes unavailable, pending requests are rerun with the in-thread AI path rather than being dropped.

Scene / UI implementation snapshot

• BootScene loads atlas assets and presents a simple loading bar.
• MenuScene now exposes both difficulty selection and a dedicated entry point into SettingsScene.
• SettingsScene persists music and effects toggles immediately through saveAudioPreferences().
• GameScene reads normalized audio preferences from scene data or persisted storage before match start.
• GameScene tracks played and captured cards in CardTracker as the round evolves.
• The scene owns score HUD rendering, player labels, status text, think-bar rendering, procedural audio, and particle effects.
• Round-end and match-end flows remain managed inside the scene instead of separate overlay components.

Benchmark snapshot

• ai-benchmark.ts now uses a simulated timing source for fixture and self-play evaluation instead of depending only on wall-clock timing.
• The benchmark summary records per-seed aggregates, dual-loss seeds, and a regression watchlist intersection.
• The harness remains source-local under src/, so it is covered by the default npx tsc --noEmit include set.

Research Performed

Web Research: Scopone Scientifico Rules (2026-03-31)

Sources: Wikipedia (Scopa article, Scopone section), Pagat.com (Scopone page by John McLeod)

Core Rules (Scopone Scientifico variant)

• 4 players, 2 fixed teams of 2 (sit opposite): Team A = players 0+2, Team B = players 1+3.
• 40-card Napoletane deck: 4 suits (bastoni, coppe, denara, spade), values 1-10.
• All 40 cards are dealt at the start of the round; the table begins empty.
• Turns advance in the implementation as 0 -> 1 -> 2 -> 3.

Capture Rules

1. If the played card matches one or more table cards by value, a direct match must be taken.
2. If multiple direct matches exist, one matching table card is chosen.
3. If no direct match exists, a subset of table cards may be captured when their values sum to the played value.
4. A direct match has priority over any possible sum capture.
5. Scopa awards a point only when the table is cleared before the final play of the round.

Scoring

Category	Rule
Carte	Majority of captured cards
Denari	Majority of denara suit cards
Settebello	Team that captures the 7 of denara
Primiera	Highest best-of-each-suit prime value
Scope	One point per scopa

Primiera values used in code

Card value	Primiera value
7	21
6	18
1	16
5	15
4	14
3	13
2	12
8, 9, 10	10

SCOPONE-0008: AI progress rendering notes (2026-04-02)

• The current implementation does not use Phaser TimerEvent progress helpers.
• Instead, chooseMove() emits its own normalized progress payload through AIDecisionProgress.
• GameScene.updateThinkBar() renders remaining time from that callback.
• The yielding behavior in the master search path is necessary so the browser can repaint while search batches continue.

SCOPONE-0009: Phaser scene lifecycle notes (2026-04-08)

• Source: Context7 /websites/phaser_io_api-documentation, query Phaser 3.87 Scene lifecycle create restart shutdown destroy event listeners scene restart preserving external state.
• Phaser dispatches shutdown when a scene stops being active but may be re-used later; resource cleanup that should also cover final teardown can additionally listen to destroy.
• The current GameScene pattern of registering one-shot shutdown and destroy handlers is aligned with Phaser guidance for worker disposal and UI cleanup.
• Dealer rotation and next-round state changes can stay inside the existing in-scene orchestration without requiring a different Phaser lifecycle primitive.

SCOPONE-0010: UI, settings, and benchmark refresh notes (2026-04-09)

• src/game/preferences.ts is now the authoritative audio preference seam. It normalizes stored values and shields scenes from malformed storage state.
• src/scenes/MenuScene.ts now reads persisted audio preferences and exposes a dedicated settings entry point instead of keeping audio options implicit.
• src/scenes/SettingsScene.ts exists as a real scene and persists music and effects toggles independently through saveAudioPreferences().
• src/scenes/GameScene.ts already contains the previously planned pacing and status work: AI_MIN_THINK_MS = 1000, MOVE_OUTCOME_STATUS_MS = 2000, timer-backed setStatus(...), and handleSceneShutdown() timer cleanup are all present in source and should be treated as current behavior, not future work.
• src/game/ai-benchmark.ts now enforces an iteration 5 contract with simulated timing, cross-seed aggregation, dual-loss reporting, and a regression watchlist intersection. Older findings that described iteration 4 targets or wall-clock-only timing are stale.
• main.ts still registers a local SettingsScene stub while MenuScene dynamically installs the concrete scene implementation before use. This works today but is an architectural wrinkle worth remembering in later planning.